{"_id":"@benpley/wappler-avatar-badge","_rev":"2-e4eaa4a5496956e2f60e2e80c6ce654a","name":"@benpley/wappler-avatar-badge","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"@benpley/wappler-avatar-badge","version":"1.0.0","keywords":["wappler-extension","appconnect","wappler","avatar","badge","profile","user","web-components","bootstrap5"],"author":{"name":"Ben Pleysier"},"license":"MIT","_id":"@benpley/wappler-avatar-badge@1.0.0","maintainers":[{"name":"benpley","email":"ben@pleysier.com.au"}],"dist":{"shasum":"f1eb440818eecfc31652d16421d53603ba741df9","tarball":"https://registry.npmjs.org/@benpley/wappler-avatar-badge/-/wappler-avatar-badge-1.0.0.tgz","fileCount":5,"integrity":"sha512-6qJcyG8MFbnf9ngX0A+hMsjifuYgwqIntw1Sb8BPfMWyTVj/knNFu/J3E/WH6bhs6AKdokFI9itowQucg53hxg==","signatures":[{"sig":"MEUCIQCIjxH4KqrYBU/7MpZ6p0wcmico7ZmHHQmmzhPLOo2sNgIgHmUEu3+CQlNbk60XYWtHJvJor8Tbk4BmP70s1w3xBOU=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":55494},"engines":{"node":">=12.0.0"},"_npmUser":{"name":"benpley","email":"ben@pleysier.com.au"},"_npmVersion":"11.12.1","description":"Professional Avatar Badge and Avatar Group Web Components for Wappler - Display user profiles with images, initials, status indicators, count badges, and grouping","directories":{},"_nodeVersion":"22.19.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/wappler-avatar-badge_1.0.0_1777268757751_0.07042115508203972","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@benpley/wappler-avatar-badge","version":"1.0.1","description":"Professional Avatar Badge and Avatar Group Web Components for Wappler with improved App Connect dynamic attribute inspector support - Display user profiles with images, initials, status indicators, count badges, and grouping","author":{"name":"Ben Pleysier"},"license":"MIT","main":"includes/avatar-badge.js","homepage":"https://www.npmjs.com/package/@benpley/wappler-avatar-badge","keywords":["wappler-extension","appconnect","wappler","avatar","badge","profile","user","web-components","bootstrap5"],"engines":{"node":">=12.0.0"},"scripts":{"pack:dry-run":"npm pack --dry-run","publish:npm":"npm publish --access public"},"publishConfig":{"access":"public"},"_id":"@benpley/wappler-avatar-badge@1.0.1","_nodeVersion":"22.19.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-eIvwT7R+vsLa2l/VoQFwsmywXvh532TcUxc4mcT7GOqneaTmmxqdZ/Pj77YfLDD1Vn8o7tYHVPWNTCqV2y52Ig==","shasum":"02c62082f9bf1bad6c8b1875c5eb8317f4d53b9a","tarball":"https://registry.npmjs.org/@benpley/wappler-avatar-badge/-/wappler-avatar-badge-1.0.1.tgz","fileCount":5,"unpackedSize":57124,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCkv3kP+3mq4oIdQg/d9dK6XdCWXGP2a4OBV6RVCnhFuQIhAIAQizR9viSpCjyxU9fiQe0Td8dXQlkbD3DwHvjXRnXC"}]},"_npmUser":{"name":"benpley","email":"ben@pleysier.com.au"},"directories":{},"maintainers":[{"name":"benpley","email":"ben@pleysier.com.au"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/wappler-avatar-badge_1.0.1_1778126384679_0.8078404775864845"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-27T05:45:57.628Z","modified":"2026-05-07T03:59:44.939Z","1.0.0":"2026-04-27T05:45:57.897Z","1.0.1":"2026-05-07T03:59:44.827Z"},"author":{"name":"Ben Pleysier"},"license":"MIT","keywords":["wappler-extension","appconnect","wappler","avatar","badge","profile","user","web-components","bootstrap5"],"description":"Professional Avatar Badge and Avatar Group Web Components for Wappler with improved App Connect dynamic attribute inspector support - Display user profiles with images, initials, status indicators, count badges, and grouping","maintainers":[{"name":"benpley","email":"ben@pleysier.com.au"}],"readme":"# Avatar Badge for Wappler\n\nProfessional Avatar Badge and Avatar Group Web Components for Wappler with comprehensive features for displaying user profiles, status indicators, count badges, and avatar grouping.\n\n## Version 1.0.1\n\nThis release improves the Wappler App Connect inspector integration. Dynamic attributes now use Wappler's standard fieldset/group-enabler pattern, so the checkbox beside each dynamic property can enable or remove the generated `dmx-bind:` attribute correctly.\n\n## Features\n\n### Avatar Badge (`<avatar-badge>`)\n- **Image Support**: Display user images with fallback to initials or icons\n- **Flexible Fallbacks**: Automatic initials generation, custom initials, icon support, or custom HTML content\n- **Status Indicators**: Show online/offline/away/busy status with customizable positions\n- **Count Badges**: Display notification counts with configurable maximum and overflow indicator\n- **Auto-Color**: Automatic color assignment based on user name/initials for consistent avatars\n- **Responsive Sizing**: Predefined size tokens (xs, sm, md, lg, xl, xxl) or custom pixel sizes\n- **Multiple Shapes**: Circle, rounded square, or square variants\n- **Bootstrap Integration**: Works seamlessly with Bootstrap 5 color utilities\n- **Image Loading**: Lazy loading support with fetchpriority control\n- **Accessible**: Proper ARIA labels and semantic HTML\n- **Clickable**: Optional link wrapper with target and rel support\n\n### Avatar Group (`<avatar-group>`)\n- **Stack Avatars**: Display multiple avatars in an overlapping stack\n- **Overflow Display**: Automatically show \"+N\" indicator for additional avatars beyond max count\n- **Configurable Spacing**: Control the overlap amount\n- **Size Propagation**: Automatically apply group size to child avatars\n\n## Installation\n\nInstall this extension directly from within Wappler using the **Project Options > Extensions** panel:\n\n1. Open your project in Wappler.\n2. Go to **Project Options** (the gear icon in the top toolbar).\n3. Select the **Extensions** tab.\n4. In the search box, type `avatar-badge` or `@benpley/wappler-avatar-badge`.\n5. Locate **Avatar Badge for Wappler** in the results and click **Add**.\n6. Wappler will install the extension and automatically copy the required CSS and JavaScript files to your project.\n\n> **Note:** The extension requires Wappler and is installed per-project. Make sure your project is open before installing.\n\n## Basic Usage\n\n### Simple Avatar with Image\n\n```html\n<avatar-badge \n    src=\"/images/user.jpg\" \n    name=\"John Smith\"\n    size=\"md\">\n</avatar-badge>\n```\n\n### Avatar with Initials Fallback\n\n```html\n<avatar-badge \n    name=\"Sarah Johnson\"\n    size=\"lg\"\n    auto-color>\n</avatar-badge>\n```\n\n### Avatar with Status Indicator\n\n```html\n<avatar-badge \n    src=\"/images/user.jpg\"\n    name=\"Michael Brown\"\n    status=\"online\"\n    status-position=\"bottom-end\">\n</avatar-badge>\n```\n\n### Avatar with Count Badge\n\n```html\n<avatar-badge \n    src=\"/images/user.jpg\"\n    name=\"Emily Davis\"\n    count=\"5\"\n    count-max=\"9\"\n    count-position=\"top-end\">\n</avatar-badge>\n```\n\n### Avatar with Icon Fallback\n\n```html\n<avatar-badge \n    icon=\"fas fa-user\"\n    name=\"Guest User\"\n    bg=\"secondary\"\n    text=\"white\">\n</avatar-badge>\n```\n\n### Clickable Avatar\n\n```html\n<avatar-badge \n    src=\"/images/user.jpg\"\n    name=\"John Smith\"\n    href=\"/profile/123\"\n    size=\"lg\">\n</avatar-badge>\n```\n\n### Avatar Group\n\n```html\n<avatar-group max=\"4\" size=\"md\" spacing=\"-12px\">\n    <avatar-badge src=\"/images/user1.jpg\" name=\"John Smith\"></avatar-badge>\n    <avatar-badge src=\"/images/user2.jpg\" name=\"Sarah Johnson\"></avatar-badge>\n    <avatar-badge src=\"/images/user3.jpg\" name=\"Michael Brown\"></avatar-badge>\n    <avatar-badge src=\"/images/user4.jpg\" name=\"Emily Davis\"></avatar-badge>\n    <avatar-badge src=\"/images/user5.jpg\" name=\"David Wilson\"></avatar-badge>\n    <avatar-badge src=\"/images/user6.jpg\" name=\"Lisa Anderson\"></avatar-badge>\n</avatar-group>\n```\n\n## Avatar Badge Attributes\n\n### Core Attributes\n\n| Attribute | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `id` | text | - | Unique identifier for the avatar |\n| `name` | text | - | User's full name (used for initials and ARIA labels) |\n| `src` | text | - | URL of the avatar image |\n| `size` | text | `md` | Size token: `xs`, `sm`, `md`, `lg`, `xl`, `xxl` |\n\n### Fallback Options\n\n| Attribute | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `initials` | text | - | Custom initials (overrides auto-generated from name) |\n| `icon` | text | - | Icon class (e.g., `fas fa-user`) to show instead of initials |\n\n### Appearance\n\n| Attribute | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `shape` | text | `circle` | Shape: `circle`, `rounded`, or `square` |\n| `variant` | text | - | Bootstrap variant: `primary`, `secondary`, etc. |\n| `bg` | text | `primary` | Background color (Bootstrap color class) |\n| `text` | text | `white` | Text color (Bootstrap color class) |\n| `auto-color` | boolean | `false` | Automatically assign colors based on name |\n| `border` | text | - | Border color (enable border by adding attribute) |\n| `border-width` | number | `2` | Border width in pixels (1-5) |\n\n### Status Indicator\n\n| Attribute | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `status` | text | - | Status: `online`, `offline`, `away`, `busy` or custom color |\n| `status-position` | text | `bottom-end` | Position: `bottom-end`, `bottom-start`, `top-end`, `top-start` |\n\n### Count Badge\n\n| Attribute | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `count` | number | - | Number to display in badge |\n| `count-max` | number | - | Maximum count before showing \"N+\" |\n| `count-bg` | text | `danger` | Badge background color |\n| `count-text` | text | `white` | Badge text color |\n| `count-position` | text | `top-end` | Badge position |\n\n### Image Loading\n\n| Attribute | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `loading` | text | `lazy` | Image loading: `lazy`, `eager` |\n| `fetchpriority` | text | - | Fetch priority: `high`, `low`, `auto` |\n\n### Link Wrapper\n\n| Attribute | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `href` | text | - | URL to link to |\n| `target` | text | - | Link target (e.g., `_blank`) |\n| `rel` | text | - | Link relationship |\n\n## Avatar Group Attributes\n\n| Attribute | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `max` | number | - | Maximum avatars to show before overflow indicator |\n| `size` | text | `md` | Size token applied to all child avatars: `xs`, `sm`, `md`, `lg`, `xl`, `xxl` |\n| `spacing` | text | `-8px` | Overlap spacing (negative for overlap) |\n\n## Size Tokens\n\nPredefined size tokens for consistent sizing:\n\n- `xs` = 24px\n- `sm` = 32px\n- `md` = 40px (default)\n- `lg` = 56px\n- `xl` = 80px\n- `xxl` = 112px\n\n## Color Auto-Assignment\n\nWhen `auto-color` attribute is present and no explicit `bg` or `variant` is set, the component automatically assigns a consistent color from a Bootstrap-friendly palette based on the user's name or initials. This ensures the same user always gets the same color.\n\n## App Connect Integration\n\nThe component is fully integrated with Wappler's App Connect framework:\n\n### Dynamic Attribute Support in Wappler\n\nThe extension exposes common avatar attributes in Wappler's **Dynamic Attributes** panel using Wappler's standard removable checkbox pattern. This allows dynamic bindings to be enabled, edited, or removed cleanly from the inspector.\n\nSupported dynamic attributes:\n\n- `dmx-bind:src`\n- `dmx-bind:name`\n- `dmx-bind:status`\n- `dmx-bind:count`\n- `dmx-bind:href`\n\nIn Wappler, select an `<avatar-badge>` element, expand **Dynamic Attributes**, enable the property checkbox, and choose the App Connect expression for the value. Disabling the checkbox removes the corresponding `dmx-bind:` attribute from the markup.\n\nThe attribute will now use `dmx-bind:` in the generated markup and react to data changes automatically.\n\n**Static (fixed value):**\n```html\n<avatar-badge\n    src=\"/images/john.jpg\"\n    name=\"John Smith\"\n    status=\"online\"\n    size=\"md\">\n</avatar-badge>\n```\n\n**Dynamic (bound to App Connect data):**\n```html\n<!-- After toggling each field to Dynamic Attribute in Wappler -->\n<avatar-badge\n    dmx-bind:src=\"user.avatar_url\"\n    dmx-bind:name=\"user.full_name\"\n    dmx-bind:status=\"user.online_status\"\n    size=\"md\">\n</avatar-badge>\n```\n\n> **Note:** Static attributes (like `size`, `auto-color`, `rounded`) that only ever use preset tokens do not need to be toggled — set them directly as plain attributes.\n\n**Dynamic in a repeater:**\n```html\n<div dmx-repeat:user=\"users_list.data\">\n    <avatar-badge\n        dmx-bind:src=\"avatar_url\"\n        dmx-bind:name=\"full_name\"\n        dmx-bind:status=\"online_status\"\n        size=\"sm\"\n        auto-color>\n    </avatar-badge>\n</div>\n```\n\n### Dynamic Bindings\n\n```html\n<avatar-badge \n    dmx-bind:src=\"user.avatar\"\n    dmx-bind:name=\"user.fullname\"\n    dmx-bind:status=\"user.online_status\"\n    dmx-bind:count=\"user.unread_messages\">\n</avatar-badge>\n```\n\n### In Repeaters\n\n```html\n<div dmx-repeat:users=\"users_list.data\">\n    <avatar-badge \n        dmx-bind:src=\"avatar_url\"\n        dmx-bind:name=\"full_name\"\n        dmx-bind:href=\"'/profile/' + id\"\n        auto-color>\n    </avatar-badge>\n</div>\n```\n\n### With Conditions\n\n```html\n<avatar-badge \n    src=\"/images/user.jpg\"\n    name=\"John Smith\"\n    dmx-bind:status=\"is_online ? 'online' : 'offline'\"\n    dmx-bind:count=\"unread_count\">\n</avatar-badge>\n```\n\n## Accessibility\n\nThe component follows accessibility best practices:\n\n- Proper ARIA labels for images and fallbacks\n- Status indicators include ARIA labels\n- Count badges include notification count in ARIA\n- Decorative images (without name) are marked with empty alt and aria-hidden\n- Semantic HTML structure\n\n## Browser Support\n\nWorks in all modern browsers that support:\n- Custom Elements (Web Components)\n- ES6+ JavaScript features\n\n## Customization\n\n### Custom Colors\n\nOverride Bootstrap color variables or add custom CSS classes:\n\n```html\n<avatar-badge \n    name=\"Custom User\"\n    bg=\"custom-purple\"\n    text=\"white\">\n</avatar-badge>\n```\n\n```css\n.bg-custom-purple {\n    background-color: #9b59b6 !important;\n}\n```\n\n### Custom Styles\n\nThe component uses scoped CSS classes that can be targeted:\n\n```css\navatar-badge .ab-wrap {\n    /* Custom wrapper styles */\n}\n\navatar-badge .ab-img {\n    /* Custom image styles */\n}\n\navatar-badge .ab-fallback {\n    /* Custom fallback container styles */\n}\n```\n\n## Performance\n\n- **Lazy Loading**: Images are lazy-loaded by default\n- **Efficient Rendering**: Microtask-based batched rendering\n- **Memory Management**: Proper cleanup on disconnect\n- **Minimal DOM**: Efficient DOM structure\n- **CSS Variables**: Hardware-accelerated CSS custom properties\n\n## License\n\nMIT License - see LICENSE.md for details\n\n## Author\n\nBen Pleysier\n\n## Support\n\nFor issues, questions, or contributions:\n- Wappler Community Forum: https://community.wappler.io\n\n## Changelog\n\n### 1.0.1 (2026-05-07)\n- Fixed Wappler Dynamic Attributes inspector behavior for custom App Connect attributes\n- Reworked dynamic binding rules to use Wappler's fieldset/group-enabler pattern\n- Added removable checkbox support for `src`, `name`, `status`, `count`, and `href` dynamic bindings\n- Normalized `components.hjson` string values with quoted strings for reliable Wappler rule parsing\n- Improved README documentation for Dynamic Attributes usage\n\n### 1.0.0 (2026-04-27)\n- Initial release\n- Avatar Badge component with full feature set\n- Avatar Group component for stacked avatars\n- Bootstrap 5 integration\n- App Connect integration\n- Complete accessibility support\n","readmeFilename":"README.md","homepage":"https://www.npmjs.com/package/@benpley/wappler-avatar-badge"}