@bspk/ui 1.3.3 → 1.3.5

package/dist/types/common.d.ts

@@ -5,12 +5,16 @@
  *
  * @bspk/ui/Txt".
  */
-import { JSXElementConstructor, ReactNode, ComponentPropsWithoutRef, AriaRole } from 'react';
+import { JSXElementConstructor, ReactNode, ComponentPropsWithoutRef, AriaRole, ChangeEvent, KeyboardEvent, CSSProperties } from 'react';
 export type AlertVariant = 'error' | 'informational' | 'success' | 'warning';
 /** Sets a ref to the given element. */
 export type SetRef<T> = (instance: T | null) => void;
 export type ElementProps<P extends Record<string, unknown>, E extends JSXElementConstructor<unknown> | keyof JSX.IntrinsicElements, O extends string = ''> = Omit<ComponentPropsWithoutRef<E>, O | keyof P> & P;
 export type ElementConstructorProps<E extends JSXElementConstructor<unknown> | keyof JSX.IntrinsicElements, O extends string = ''> = Omit<ComponentPropsWithoutRef<E>, O>;
+type CSSVariables = `--${string}`;
+export type CSSWithVariables = CSSProperties | (CSSProperties & {
+    [key in CSSVariables]: unknown;
+});
 export type DataProps = Record<`data-${string}`, string>;
 export type ButtonSize = 'large' | 'medium' | 'small' | 'x-small';
 export type CallToActionButton = {
@@ -31,9 +35,9 @@ export type CallToActionButton = {
 };
 export type CommonPropsLibrary = {
     /**
-     * Marks the element as invalid and displays error state theme.
+     * Indicates that the element is in an invalid state and displays the error theme.
      *
-     * If the errorMessage is empty the error state theme will not appear.
+     * If set to true, an accompanying error message should be provided.
      *
      * @default false
      */
@@ -87,13 +91,13 @@ export type CommonPropsLibrary = {
      *
      * @required
      */
-    value?: string;
+    optionValue?: string;
     /**
      * The aria-label for the element.
      *
      * @required
      */
-    'aria-label': string;
+    'aria-label'?: string;
     /**
      * Identifies the parent component. Helps with styling, debugging, and/or testing purposes.
      *
@@ -106,14 +110,29 @@ export type CommonPropsLibrary = {
      * @type string
      */
     role?: AriaRole;
+    /**
+     * Inline styles to apply to the element.
+     *
+     * Allows for CSS variables to be passed in as well.
+     */
+    style?: CSSWithVariables;
 };
 export type CommonProps<K extends keyof CommonPropsLibrary> = Pick<CommonPropsLibrary, K>;
 export type RequiredCommonProps<K extends keyof CommonPropsLibrary> = Required<Pick<CommonPropsLibrary, K>>;
-export type FormFieldControlProps = {
-    /** The id of the control description. */
-    'aria-describedby'?: string;
-    /** The id of the error message */
-    'aria-errormessage'?: string;
+export type FieldControlProps<ValueType = string, ChangeContext = ChangeEvent<HTMLElement> | KeyboardEvent | undefined> = CommonProps<'aria-label' | 'disabled' | 'id' | 'invalid' | 'name' | 'readOnly' | 'required'> & {
+    /**
+     * The value of the field control.
+     *
+     * @required
+     */
+    value: ValueType | undefined;
+    /**
+     * The function to call when the value changes.
+     *
+     * @required
+     */
+    onChange: (next: ValueType | undefined, event?: ChangeContext) => void;
 };
 export type Brand = 'anywhere' | 'better-homes-gardens' | 'cartus' | 'century-21' | 'coldwell-banker' | 'corcoran' | 'denali-boss' | 'era' | 'sothebys';
+export {};
 /** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/dist/types/common.js.map

@@ -1 +1 @@
-{"version":3,"file":"common.js","sourceRoot":"","sources":["../../src/types/common.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;;AA8IH,sDAAsD"}
+{"version":3,"file":"common.js","sourceRoot":"","sources":["../../src/types/common.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;;AA2KH,sDAAsD"}

package/dist/types/meta.d.ts

@@ -44,6 +44,7 @@ export type ComponentMeta = BaseMeta & {
         description?: string;
     };
     phase: ComponentPhase;
+    generated?: boolean;
 };
 export type UtilityMeta = BaseMeta & {
     param?: string;

package/dist/types/meta.js.map

@@ -1 +1 @@
-{"version":3,"file":"meta.js","sourceRoot":"","sources":["../../src/types/meta.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,CAAC,MAAM,qBAAqB,GAAqB;IACnD,SAAS,EAAE,qDAAqD;IAChE,SAAS,EAAE,mDAAmD;IAC9D,KAAK,EAAE,+CAA+C;IACtD,UAAU,EAAE,mCAAmC;IAC/C,QAAQ,EAAE,mBAAmB;CAChC,CAAC;AAEF,MAAM,CAAC,MAAM,gBAAgB,GAOzB;IACA,OAAO,EAAE;QACL,KAAK,EAAE,SAAS;QAChB,EAAE,EAAE,SAAS;QACb,WAAW,EACP,4IAA4I;KACnJ;IACD,GAAG,EAAE;QACD,KAAK,EAAE,aAAa;QACpB,EAAE,EAAE,KAAK;QACT,WAAW,EACP,+JAA+J;KACtK;IACD,QAAQ,EAAE;QACN,KAAK,EAAE,WAAW;QAClB,EAAE,EAAE,UAAU;QACd,WAAW,EACP,+LAA+L;KACtM;IACD,MAAM,EAAE;QACJ,KAAK,EAAE,QAAQ;QACf,EAAE,EAAE,QAAQ;QACZ,WAAW,EACP,sJAAsJ;KAC7J;IACD,OAAO,EAAE;QACL,KAAK,EAAE,SAAS;QAChB,EAAE,EAAE,SAAS;QACb,WAAW,EAAE,mEAAmE;KACnF;CACJ,CAAC;AAkDF,sDAAsD"}
+{"version":3,"file":"meta.js","sourceRoot":"","sources":["../../src/types/meta.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,CAAC,MAAM,qBAAqB,GAAqB;IACnD,SAAS,EAAE,qDAAqD;IAChE,SAAS,EAAE,mDAAmD;IAC9D,KAAK,EAAE,+CAA+C;IACtD,UAAU,EAAE,mCAAmC;IAC/C,QAAQ,EAAE,mBAAmB;CAChC,CAAC;AAEF,MAAM,CAAC,MAAM,gBAAgB,GAOzB;IACA,OAAO,EAAE;QACL,KAAK,EAAE,SAAS;QAChB,EAAE,EAAE,SAAS;QACb,WAAW,EACP,4IAA4I;KACnJ;IACD,GAAG,EAAE;QACD,KAAK,EAAE,aAAa;QACpB,EAAE,EAAE,KAAK;QACT,WAAW,EACP,+JAA+J;KACtK;IACD,QAAQ,EAAE;QACN,KAAK,EAAE,WAAW;QAClB,EAAE,EAAE,UAAU;QACd,WAAW,EACP,+LAA+L;KACtM;IACD,MAAM,EAAE;QACJ,KAAK,EAAE,QAAQ;QACf,EAAE,EAAE,QAAQ;QACZ,WAAW,EACP,sJAAsJ;KAC7J;IACD,OAAO,EAAE;QACL,KAAK,EAAE,SAAS;QAChB,EAAE,EAAE,SAAS;QACb,WAAW,EAAE,mEAAmE;KACnF;CACJ,CAAC;AAmDF,sDAAsD"}

package/dist/utils/demo.d.ts

@@ -99,6 +99,7 @@ export type ComponentExample<Props = Record<string, unknown>, PropName extends k
             CodeExample: CodeExample;
             Syntax: Syntax;
         }) => React.ReactNode;
+        location?: 'afterDemo' | 'beforeDemo';
     }[];
 };
 export type Syntax = (params: {

package/dist/utils/demo.js.map

@@ -1 +1 @@
-{"version":3,"file":"demo.js","sourceRoot":"","sources":["../../src/utils/demo.ts"],"names":[],"mappings":"AAAA,uDAAuD;AAgKvD,MAAM,UAAU,SAAS,CAAC,SAAiB,KAAK;IAC5C,OAAO,GAAG,MAAM,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;AACrE,CAAC"}
+{"version":3,"file":"demo.js","sourceRoot":"","sources":["../../src/utils/demo.ts"],"names":[],"mappings":"AAAA,uDAAuD;AAiKvD,MAAM,UAAU,SAAS,CAAC,SAAiB,KAAK;IAC5C,OAAO,GAAG,MAAM,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;AACrE,CAAC"}

package/meta.ts

@@ -212,6 +212,7 @@ function generateComponentMeta({
         phase: (COMPONENT_PHASE_ORDER.includes(componentDoc.phase as ComponentPhase)
             ? componentDoc.phase
             : 'Backlog') as ComponentPhase,
+        generated: 'generated' in componentDoc,
     } as ComponentMeta;
 }
 
@@ -222,17 +223,17 @@ async function generateUtilityMeta(utilityFile: string): Promise<UtilityMeta | n
 
     const utility = fileName;
 
-    const comment = content.match(/\/\*\*[\s\S]+?\*\//);
+    const comment = content.match(/\/\*\*\s*\n([^*]|(\*(?!\/)))*\*\//g)?.map(jsDocParse);
 
     if (!comment?.[0]) {
         // console.info(`No JSDoc found for hook ${utility} for ${hooksDir}/${utility}.tsx`);
         return null;
     }
 
-    const utilityDoc = jsDocParse(comment[0]);
+    const utilityDoc = comment.find((doc) => doc.example);
 
-    if (!utilityDoc.example) {
-        // console.info(`No example found for hook ${utility} for ${hooksDir}/${utility}.tsx`);
+    if (!utilityDoc?.example) {
+        // console.info(`No example found for hook ${utility} for ${hooksDir}/${utility}.tsx`, comment[0]);
         return null;
     }
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@bspk/ui",
-    "version": "1.3.3",
+    "version": "1.3.5",
     "license": "CC-BY-4.0",
     "type": "module",
     "files": [
@@ -59,8 +59,8 @@
         "./Button/*": "./dist/components/Button/*.js",
         "./ButtonDock": "./dist/components/ButtonDock/index.js",
         "./ButtonDock/*": "./dist/components/ButtonDock/*.js",
-        "./CalendarPicker": "./dist/components/CalendarPicker/index.js",
-        "./CalendarPicker/*": "./dist/components/CalendarPicker/*.js",
+        "./Calendar": "./dist/components/Calendar/index.js",
+        "./Calendar/*": "./dist/components/Calendar/*.js",
         "./Card": "./dist/components/Card/index.js",
         "./Card/*": "./dist/components/Card/*.js",
         "./Carousel": "./dist/components/Carousel/index.js",
@@ -69,24 +69,18 @@
         "./Checkbox/*": "./dist/components/Checkbox/*.js",
         "./CheckboxGroup": "./dist/components/CheckboxGroup/index.js",
         "./CheckboxGroup/*": "./dist/components/CheckboxGroup/*.js",
+        "./CheckboxGroupField": "./dist/components/CheckboxGroupField/index.js",
+        "./CheckboxGroupField/*": "./dist/components/CheckboxGroupField/*.js",
         "./CheckboxOption": "./dist/components/CheckboxOption/index.js",
         "./CheckboxOption/*": "./dist/components/CheckboxOption/*.js",
-        "./ChipAssist": "./dist/components/ChipAssist/index.js",
-        "./ChipAssist/*": "./dist/components/ChipAssist/*.js",
-        "./ChipFilter": "./dist/components/ChipFilter/index.js",
-        "./ChipFilter/*": "./dist/components/ChipFilter/*.js",
+        "./Chip": "./dist/components/Chip/index.js",
+        "./Chip/*": "./dist/components/Chip/*.js",
         "./ChipGroup": "./dist/components/ChipGroup/index.js",
         "./ChipGroup/*": "./dist/components/ChipGroup/*.js",
-        "./ChipInput": "./dist/components/ChipInput/index.js",
-        "./ChipInput/*": "./dist/components/ChipInput/*.js",
-        "./ChipSuggestion": "./dist/components/ChipSuggestion/index.js",
-        "./ChipSuggestion/*": "./dist/components/ChipSuggestion/*.js",
-        "./ChipUtility": "./dist/components/ChipUtility/index.js",
-        "./ChipUtility/*": "./dist/components/ChipUtility/*.js",
-        "./DateField": "./dist/components/DateField/index.js",
-        "./DateField/*": "./dist/components/DateField/*.js",
-        "./DateInput": "./dist/components/DateInput/index.js",
-        "./DateInput/*": "./dist/components/DateInput/*.js",
+        "./DatePicker": "./dist/components/DatePicker/index.js",
+        "./DatePicker/*": "./dist/components/DatePicker/*.js",
+        "./DatePickerField": "./dist/components/DatePickerField/index.js",
+        "./DatePickerField/*": "./dist/components/DatePickerField/*.js",
         "./Dialog": "./dist/components/Dialog/index.js",
         "./Dialog/*": "./dist/components/Dialog/*.js",
         "./Divider": "./dist/components/Divider/index.js",
@@ -99,6 +93,8 @@
         "./ExamplePlaceholder/*": "./dist/components/ExamplePlaceholder/*.js",
         "./Fab": "./dist/components/Fab/index.js",
         "./Fab/*": "./dist/components/Fab/*.js",
+        "./Field": "./dist/components/Field/index.js",
+        "./Field/*": "./dist/components/Field/*.js",
         "./FileUpload": "./dist/components/FileUpload/index.js",
         "./FileUpload/*": "./dist/components/FileUpload/*.js",
         "./FileUploadItem": "./dist/components/FileUploadItem/index.js",
@@ -109,38 +105,38 @@
         "./Img/*": "./dist/components/Img/*.js",
         "./InlineAlert": "./dist/components/InlineAlert/index.js",
         "./InlineAlert/*": "./dist/components/InlineAlert/*.js",
+        "./Input": "./dist/components/Input/index.js",
+        "./Input/*": "./dist/components/Input/*.js",
+        "./InputField": "./dist/components/InputField/index.js",
+        "./InputField/*": "./dist/components/InputField/*.js",
+        "./InputNumber": "./dist/components/InputNumber/index.js",
+        "./InputNumber/*": "./dist/components/InputNumber/*.js",
+        "./InputNumberField": "./dist/components/InputNumberField/index.js",
+        "./InputNumberField/*": "./dist/components/InputNumberField/*.js",
+        "./InputPhone": "./dist/components/InputPhone/index.js",
+        "./InputPhone/*": "./dist/components/InputPhone/*.js",
+        "./InputPhoneField": "./dist/components/InputPhoneField/index.js",
+        "./InputPhoneField/*": "./dist/components/InputPhoneField/*.js",
         "./Layout": "./dist/components/Layout/index.js",
         "./Layout/*": "./dist/components/Layout/*.js",
         "./Link": "./dist/components/Link/index.js",
         "./Link/*": "./dist/components/Link/*.js",
         "./ListItem": "./dist/components/ListItem/index.js",
         "./ListItem/*": "./dist/components/ListItem/*.js",
-        "./ListItemMenu": "./dist/components/ListItemMenu/index.js",
-        "./ListItemMenu/*": "./dist/components/ListItemMenu/*.js",
         "./Menu": "./dist/components/Menu/index.js",
         "./Menu/*": "./dist/components/Menu/*.js",
-        "./MenuButton": "./dist/components/MenuButton/index.js",
-        "./MenuButton/*": "./dist/components/MenuButton/*.js",
         "./Modal": "./dist/components/Modal/index.js",
         "./Modal/*": "./dist/components/Modal/*.js",
-        "./NumberField": "./dist/components/NumberField/index.js",
-        "./NumberField/*": "./dist/components/NumberField/*.js",
-        "./NumberInput": "./dist/components/NumberInput/index.js",
-        "./NumberInput/*": "./dist/components/NumberInput/*.js",
         "./OTPInput": "./dist/components/OTPInput/index.js",
         "./OTPInput/*": "./dist/components/OTPInput/*.js",
         "./PageControl": "./dist/components/PageControl/index.js",
         "./PageControl/*": "./dist/components/PageControl/*.js",
         "./Pagination": "./dist/components/Pagination/index.js",
         "./Pagination/*": "./dist/components/Pagination/*.js",
+        "./Password": "./dist/components/Password/index.js",
+        "./Password/*": "./dist/components/Password/*.js",
         "./PasswordField": "./dist/components/PasswordField/index.js",
         "./PasswordField/*": "./dist/components/PasswordField/*.js",
-        "./PasswordInput": "./dist/components/PasswordInput/index.js",
-        "./PasswordInput/*": "./dist/components/PasswordInput/*.js",
-        "./PhoneNumberField": "./dist/components/PhoneNumberField/index.js",
-        "./PhoneNumberField/*": "./dist/components/PhoneNumberField/*.js",
-        "./PhoneNumberInput": "./dist/components/PhoneNumberInput/index.js",
-        "./PhoneNumberInput/*": "./dist/components/PhoneNumberInput/*.js",
         "./Popover": "./dist/components/Popover/index.js",
         "./Popover/*": "./dist/components/Popover/*.js",
         "./Portal": "./dist/components/Portal/index.js",
@@ -157,6 +153,8 @@
         "./Radio/*": "./dist/components/Radio/*.js",
         "./RadioGroup": "./dist/components/RadioGroup/index.js",
         "./RadioGroup/*": "./dist/components/RadioGroup/*.js",
+        "./RadioGroupField": "./dist/components/RadioGroupField/index.js",
+        "./RadioGroupField/*": "./dist/components/RadioGroupField/*.js",
         "./RadioOption": "./dist/components/RadioOption/index.js",
         "./RadioOption/*": "./dist/components/RadioOption/*.js",
         "./Rating": "./dist/components/Rating/index.js",
@@ -179,8 +177,6 @@
         "./Slider/*": "./dist/components/Slider/*.js",
         "./Snackbar": "./dist/components/Snackbar/index.js",
         "./Snackbar/*": "./dist/components/Snackbar/*.js",
-        "./SnackbarProvider": "./dist/components/SnackbarProvider/index.js",
-        "./SnackbarProvider/*": "./dist/components/SnackbarProvider/*.js",
         "./StylesProviderAnywhere": "./dist/components/StylesProviderAnywhere/index.js",
         "./StylesProviderAnywhere/*": "./dist/components/StylesProviderAnywhere/*.js",
         "./StylesProviderBetterHomesGardens": "./dist/components/StylesProviderBetterHomesGardens/index.js",
@@ -217,12 +213,10 @@
         "./Textarea/*": "./dist/components/Textarea/*.js",
         "./TextareaField": "./dist/components/TextareaField/index.js",
         "./TextareaField/*": "./dist/components/TextareaField/*.js",
-        "./TextField": "./dist/components/TextField/index.js",
-        "./TextField/*": "./dist/components/TextField/*.js",
-        "./TextInput": "./dist/components/TextInput/index.js",
-        "./TextInput/*": "./dist/components/TextInput/*.js",
-        "./TimeInput": "./dist/components/TimeInput/index.js",
-        "./TimeInput/*": "./dist/components/TimeInput/*.js",
+        "./TimePicker": "./dist/components/TimePicker/index.js",
+        "./TimePicker/*": "./dist/components/TimePicker/*.js",
+        "./TimePickerField": "./dist/components/TimePickerField/index.js",
+        "./TimePickerField/*": "./dist/components/TimePickerField/*.js",
         "./ToggleOption": "./dist/components/ToggleOption/index.js",
         "./ToggleOption/*": "./dist/components/ToggleOption/*.js",
         "./Tooltip": "./dist/components/Tooltip/index.js",
@@ -336,6 +330,10 @@
         {
             "title": "Sotheby's",
             "slug": "sothebys"
+        },
+        {
+            "title": "Example",
+            "slug": "example"
         }
     ]
 }

package/src/components/Avatar/Avatar.tsx

@@ -63,7 +63,7 @@ export type AvatarProps = CommonProps<'disabled'> & {
      * When provided the image will be displayed instead of the icon or initials.
      *
      * @example
-     *     /profile.jpg
+     *     /avatar-01.png
      */
     image?: string;
     /**
@@ -92,7 +92,7 @@ export type AvatarProps = CommonProps<'disabled'> & {
  *             <Avatar
  *                 color="blue"
  *                 icon={<SvgPerson />}
- *                 image="/profile.jpg"
+ *                 image="/avatar-01.png"
  *                 initials="AR"
  *                 name="Andre Giant"
  *                 showTooltip
@@ -112,14 +112,14 @@ export function Avatar({
     size = 'small',
     showIcon,
     image,
-    name: ariaLabel,
+    name,
     hideTooltip = false,
     onClick,
     disabled,
     ...props
 }: AvatarProps) {
     const children = useMemo(() => {
-        if (image) return <img alt={ariaLabel} aria-hidden={true} src={image} />;
+        if (image) return <img alt={name} aria-hidden={true} src={image} />;
 
         if (showIcon)
             return (
@@ -130,8 +130,8 @@ export function Avatar({
 
         let initials = initialsProp;
 
-        if (ariaLabel && !initials)
-            initials = ariaLabel
+        if (name && !initials)
+            initials = name
                 .split(' ')
                 .map((word) => word.charAt(0))
                 .slice(0, 2)
@@ -146,7 +146,7 @@ export function Avatar({
             );
 
         return null;
-    }, [ariaLabel, showIcon, image, initialsProp]);
+    }, [name, showIcon, image, initialsProp]);
 
     if (!children) return null;
 
@@ -155,21 +155,20 @@ export function Avatar({
             {...props}
             {...triggerProps}
             aria-disabled={disabled || undefined}
-            aria-label={onClick ? ariaLabel : undefined}
-            aria-labelledby={onClick ? triggerProps['aria-labelledby'] : undefined}
+            aria-label={name}
             aria-roledescription="person"
             data-bspk="avatar"
             data-color={color}
             data-size={size}
             onClickCapture={disabled ? undefined : onClick}
-            role={onClick ? 'button' : ''}
+            role={onClick ? 'button' : 'img'}
             tabIndex={onClick && !disabled ? 0 : undefined}
         >
             {children}
         </div>
     );
 
-    return !hideTooltip ? <Tooltip label={ariaLabel}>{avatar}</Tooltip> : avatar({});
+    return !hideTooltip ? <Tooltip label={name}>{avatar}</Tooltip> : avatar({});
 }
 
 /** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/Avatar/AvatarExample.tsx

@@ -41,7 +41,7 @@ export const presets: Preset<AvatarProps>[] = [
         label: 'With Image',
         propState: {
             name: 'Andre Giant',
-            image: '/profile.jpg',
+            image: '/avatar-01.png',
             showIcon: false,
         },
     },

package/src/components/Avatar/avatar.scss

@@ -1,9 +1,13 @@
 [data-bspk='avatar'] {
+    /*! 
+    --avatar-border: is set via inline style 
+    */
+
     --height: var(--spacing-sizing-10);
     --font: var(--labels-base);
     --svg-size: var(--spacing-sizing-10);
 
-    border: unset;
+    border: var(--avatar-border);
 
     &:not([data-color]) {
         --foreground: var(--foreground-neutral-on-surface);
@@ -128,6 +132,7 @@
 
     &:focus:not(:active) {
         outline: 2px solid var(--stroke-neutral-focus);
+        outline-offset: -2px;
     }
 }
 

package/src/components/AvatarGroup/AvatarGroup.tsx

@@ -1,15 +1,17 @@
 import './avatar-group.scss';
+import { AvatarGroupOverflow } from './Overflow';
 import { Avatar, AvatarProps, SizeVariant } from '-/components/Avatar';
+import { CommonProps } from '-/types/common';
 
 export type AvatarItem = Pick<AvatarProps, 'color' | 'image' | 'initials' | 'name' | 'showIcon'>;
 
-export type AvatarGroupProps = {
+export type AvatarGroupProps = CommonProps<'style'> & {
     /**
      * The avatars to display in the group.
      *
      * @example
      *     [
-     *         { name: 'Fezzik', image: '/profile.jpg' },
+     *         { name: 'Fezzik', image: '/avatar-01.png' },
      *         { name: 'Inigo Montoya', initials: 'IM', color: 'blue' },
      *         { name: 'Miracle Max', initials: 'MM', color: 'green' },
      *         { name: 'Princess Buttercup', showIcon: true },
@@ -24,19 +26,23 @@ export type AvatarGroupProps = {
      *
      * @default small
      */
-    size?: Extract<SizeVariant, 'large' | 'medium' | 'small' | 'x-small'>;
+    size?: SizeVariant;
     /**
-     * The maximum number of avatars to display before showing the overflowCount.
+     * The maximum number of avatars to display before showing the overflow menu.
      *
      * This is used to limit the number of avatars displayed in the group.
      *
      * Recommended to set this to a value between 3 and 5 for optimal display.
+     *
+     * @default 5
+     * @min 1
+     * @max 5
      */
     max?: number;
     /**
      * The variant of the avatar group.
      *
-     * @default spread
+     * @default auto
      */
     variant?: 'spread' | 'stacked';
 };
@@ -47,7 +53,7 @@ export type AvatarGroupProps = {
  * @example
  *     import { AvatarGroup } from '@bspk/ui/AvatarGroup';
  *
- *     export function Example() {
+ *     function Example() {
  *         return (
  *             <AvatarGroup
  *                 items={[
@@ -62,28 +68,18 @@ export type AvatarGroupProps = {
  * @name AvatarGroup
  * @phase UXReview
  */
-export function AvatarGroup({ items, size = 'small', max = 5, variant }: AvatarGroupProps) {
-    if (!Array.isArray(items) || !items?.length) return null;
-
-    const overFlowCount = items.length - max;
-    const small = size === 'x-small' || size === 'small';
+export function AvatarGroup({ items, size = 'small', max: maxProp = 5, variant = 'spread', style }: AvatarGroupProps) {
+    const max = maxProp > items.length ? items.length : maxProp;
+    const overflowItems = items.slice(max);
 
-    return (
-        <div data-bspk="avatar-group" data-max={max} data-size={size} data-variant={variant}>
-            <div data-gap={variant === 'spread' ? (small ? '01' : '02') : undefined} data-wrap>
+    return !Array.isArray(items) || !items?.length ? null : (
+        <div data-bspk="avatar-group" data-max={max} data-size={size} data-variant={variant} style={style}>
+            <div data-wrap>
                 {items.slice(0, max).map((item, index) => (
-                    <Avatar
-                        data-stacked={variant === 'stacked' ? (small ? '01' : '02') : undefined}
-                        key={index}
-                        {...item}
-                        size={size}
-                    />
+                    <Avatar key={index} {...item} onClick={() => {}} size={size} />
                 ))}
-
-                {overFlowCount > 0 && (
-                    <div aria-hidden data-bspk="avatar" data-color="white" data-size={size}>
-                        <span data-overflow-count>+{overFlowCount}</span>
-                    </div>
+                {overflowItems.length > 0 && (
+                    <AvatarGroupOverflow items={overflowItems} overflow={overflowItems.length} size={size} />
                 )}
             </div>
         </div>

package/src/components/AvatarGroup/AvatarGroupExample.tsx

@@ -4,7 +4,6 @@ import { ComponentExample, Preset } from '-/utils/demo';
 
 const BLUE = COLOR_VARIANTS[4];
 const GREEN = COLOR_VARIANTS[5];
-const GREY = COLOR_VARIANTS[0];
 const PURPLE = COLOR_VARIANTS[10];
 
 export const presets: Preset<AvatarGroupProps>[] = [
@@ -12,30 +11,57 @@ export const presets: Preset<AvatarGroupProps>[] = [
         label: 'Stacked',
         propState: {
             items: [
-                { name: 'Fezzik', image: '/profile.jpg' },
+                { name: 'Fezzik', image: '/avatar-01.png' },
                 { name: 'Inigo Montoya', initials: 'IM', color: BLUE },
                 { name: 'Miracle Max', initials: 'MM', showIcon: false, color: GREEN },
                 { name: 'Princess Buttercup', showIcon: true, color: PURPLE },
             ],
             variant: 'stacked' as AvatarGroupProps['variant'],
+            max: 10,
         },
     },
     {
-        label: 'Stacked + Overflow',
+        label: 'Stacked With Overflow',
         propState: {
             items: [
-                { name: 'Fezzik', image: '/profile.jpg' },
-                { name: 'Inigo Montoya', initials: 'IM', color: BLUE },
-                { name: 'Miracle Max', initials: 'MM', showIcon: false, color: GREEN },
-                { name: 'Westley Man In Black', initials: 'WB', color: GREY },
-                { name: 'Princess Buttercup', showIcon: true, color: PURPLE },
+                {
+                    name: 'Alice Johnson',
+                    image: '/avatar-01.png',
+                },
+                {
+                    name: 'Bob Smith',
+                    image: '/avatar-02.png',
+                },
+                {
+                    name: 'Charlie Brown',
+                    image: '/avatar-03.png',
+                },
+                {
+                    name: 'David Wilson',
+                    image: '/avatar-04.png',
+                },
+                {
+                    name: 'Eva Green',
+                    image: '/avatar-05.png',
+                },
+                { name: 'Frank Miller', image: '/avatar-06.png' },
+                { name: 'Grace Lee', image: '/avatar-07.png' },
+                { name: 'Hannah Kim', image: '/avatar-08.png' },
+                { name: 'Ian Clark', image: '/avatar-09.png' },
+                { name: 'Julia Adams', image: '/avatar-10.png' },
+                { name: 'Katherine Johnson', image: '/avatar-11.png' },
             ],
-            max: 3,
             variant: 'stacked' as AvatarGroupProps['variant'],
+            max: 5,
         },
     },
 ];
 
 export const AvatarGroupExample: ComponentExample<AvatarGroupProps> = {
     presets,
+    defaultState: {
+        variant: 'spread',
+    },
+    render: ({ props, Component, preset }) => <Component key={preset?.label} {...props} />,
+    variants: false,
 };