@dashforge/tw 1.0.0 → 1.1.0

package/dist/src/components/Alert/Alert.d.ts

@@ -0,0 +1,65 @@
+import type { AlertProps, AlertTitleProps } from './alert.types.js';
+/**
+ * `<AlertTitle>` — optional title block, rendered as the first child
+ * of `<Alert>`. Pattern mirrors MUI exactly (sub-component, not a
+ * prop), so the JSX shape ports 1:1 from `@mui/material`.
+ *
+ * @example
+ * <Alert severity="warning">
+ *   <AlertTitle>Subscription expires soon</AlertTitle>
+ *   Renew before 2026-06-20 to keep access.
+ * </Alert>
+ */
+export declare function AlertTitle({ children, className }: AlertTitleProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * `<Alert>` — inline persistent status surface.
+ *
+ * **API**: full MUI Alert parity (`severity`, `variant`, `icon`,
+ * `onClose`, `action`, `role`, `<AlertTitle>` sub-component). One
+ * deliberate divergence: `severity="danger"` instead of MUI's
+ * `severity="error"` — aligned to the `danger.*` token palette.
+ *
+ * **Bridge integration** (Dashforge extras):
+ *   - `visibleWhen` — engine-reactive predicate (re-evaluated on
+ *     every engine state change when mounted inside a `<DashForm>`)
+ *   - `access` — RBAC gating via `@dashforge/rbac`
+ *
+ * **Token-driven**: every color class flows from `dashforgePreset()`
+ * via CSS variables. No hardcoded hex, no `dark:` variants. The
+ * 3×4 color matrix lives in `_shared/severity/severityVariants.ts`
+ * and is shared with the refactored `<Snackbar>` (and future Banner).
+ *
+ * **A11y**: `role="alert"` for assertive severities (warning, danger)
+ * and `role="status"` for polite ones (info, success). Override via
+ * the `role` prop. The icon is `aria-hidden` — the message text is
+ * the semantic carrier.
+ *
+ * @example
+ * // Default — soft tinted surface, default icon
+ * <Alert severity="info">New feature: export to CSV is now in beta.</Alert>
+ *
+ * // With title (sub-component) + close button
+ * <Alert severity="warning" onClose={dismiss}>
+ *   <AlertTitle>Subscription expires soon</AlertTitle>
+ *   Your Pro plan ends in 3 days.
+ * </Alert>
+ *
+ * // Custom icon
+ * import { Bell } from 'lucide-react';
+ * <Alert severity="info" icon={<Bell size={20} />}>3 new notifications</Alert>
+ *
+ * // No icon — colored surface alone carries the severity
+ * <Alert severity="success" icon={false}>Saved 2 minutes ago.</Alert>
+ *
+ * // Custom action — CTA replaces the auto-close button
+ * <Alert severity="warning" action={<button onClick={renew}>Renew</button>}>
+ *   Trial expires in 3 days.
+ * </Alert>
+ *
+ * // Filled variant — for high-priority callouts
+ * <Alert severity="danger" variant="filled">
+ *   Couldn't save — 3 fields below contain validation errors.
+ * </Alert>
+ */
+export declare function Alert({ severity, variant, children, icon: iconProp, onClose, closeText, action, role: roleProp, visibleWhen, access, sx, className, slotProps, }: AlertProps): import("react/jsx-runtime").JSX.Element | null;
+//# sourceMappingURL=Alert.d.ts.map

package/dist/src/components/Alert/Alert.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Alert.d.ts","sourceRoot":"","sources":["../../../../src/components/Alert/Alert.tsx"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAEpE;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,EAAE,QAAQ,EAAE,SAAS,EAAE,EAAE,eAAe,2CAOlE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,wBAAgB,KAAK,CAAC,EACpB,QAAQ,EACR,OAAoB,EACpB,QAAQ,EACR,IAAI,EAAE,QAAQ,EACd,OAAO,EACP,SAAmB,EACnB,MAAM,EACN,IAAI,EAAE,QAAQ,EACd,WAAW,EACX,MAAM,EACN,EAAE,EACF,SAAS,EACT,SAAS,GACV,EAAE,UAAU,kDAyFZ"}

package/dist/src/components/Alert/alert.types.d.ts

@@ -0,0 +1,130 @@
+import type { ComponentPropsWithoutRef, ReactNode } from 'react';
+import type { ClassValue } from 'tailwind-variants';
+import type { Engine } from '@dashforge/ui-core';
+import type { AccessRequirement } from '@dashforge/rbac';
+import type { Severity, SeverityVariant } from '../_shared/severity/severity.types.js';
+/**
+ * Per-slot override props for `<Alert>`. Mirrors the standard
+ * `slotProps` contract used across `@dashforge/tw` components.
+ */
+export interface AlertSlotProps {
+    root?: ComponentPropsWithoutRef<'div'>;
+    icon?: ComponentPropsWithoutRef<'span'>;
+    content?: ComponentPropsWithoutRef<'div'>;
+    action?: ComponentPropsWithoutRef<'div'>;
+    closeButton?: ComponentPropsWithoutRef<'button'>;
+}
+/**
+ * Props for the `<Alert>` component.
+ *
+ * Mirrors the MUI Alert API surface 1:1 (drop-in muscle memory) with
+ * a single deliberate divergence: `severity` uses `'danger'` instead of
+ * MUI's `'error'` for alignment with the `danger.*` token palette in
+ * `@dashforge/tw-tokens`.
+ *
+ * In addition to the MUI surface, Dashforge adds:
+ *   - `visibleWhen` — engine-reactive visibility predicate (same
+ *     contract as `<TextField>` / `<Checkbox>` / etc.)
+ *   - `access` — RBAC integration via `@dashforge/rbac`
+ *
+ * @see https://mui.com/material-ui/api/alert/
+ */
+export interface AlertProps {
+    /**
+     * Visual severity. Drives the color treatment and the default ARIA
+     * role (`alert` for warning / danger, `status` for info / success).
+     *
+     * Note: this is `danger`, not MUI's `error`. The runtime behaviour
+     * is identical; the naming follows the Dashforge token palette.
+     */
+    severity: Severity;
+    /**
+     * Variant of the severity surface. Mirrors MUI's three-way axis.
+     *
+     * - `'standard'` (default) — tinted soft surface, severity-toned
+     *   text. The "all-purpose" reading.
+     * - `'filled'` — solid colored surface, light text. High visual
+     *   weight, for blocking / critical messages.
+     * - `'outlined'` — transparent surface, severity border + text.
+     *   Minimal weight, for dense layouts.
+     *
+     * @default 'standard'
+     */
+    variant?: SeverityVariant;
+    /** Body content of the alert. */
+    children?: ReactNode;
+    /**
+     * Icon control with full MUI parity.
+     *
+     * - omitted / `undefined` → default per-severity icon (lib's inline
+     *   stroke SVG)
+     * - `ReactNode` → consumer-provided custom icon (Lucide, Phosphor,
+     *   Tabler, custom SVG — bring your own iconography)
+     * - `false` → no icon rendered (the colored surface carries the
+     *   severity signal; use when icons compete with the layout)
+     */
+    icon?: ReactNode | false;
+    /**
+     * When defined, the alert renders a trailing close button that
+     * fires this callback on click. Ignored if `action` is provided
+     * (`action` slot wins, matching MUI behaviour).
+     */
+    onClose?: () => void;
+    /**
+     * `aria-label` for the close button.
+     * @default 'Close'
+     */
+    closeText?: string;
+    /**
+     * Custom trailing slot — CTA buttons, links, inline forms. When
+     * provided, replaces the auto-rendered close button. The consumer
+     * is responsible for wiring any close behaviour into the custom
+     * action node.
+     */
+    action?: ReactNode;
+    /**
+     * Override the auto-derived ARIA role. Defaults to `'alert'` for
+     * `severity={'warning' | 'danger'}` (assertive announcement) and
+     * `'status'` for `severity={'info' | 'success'}` (polite).
+     */
+    role?: 'alert' | 'status';
+    /**
+     * Reactive visibility predicate. Re-evaluated on every engine state
+     * change when the alert is mounted inside a `<DashForm>`; outside a
+     * form, evaluated as a plain predicate (the consumer captures any
+     * external state in the closure).
+     *
+     * When the predicate returns `false`, the component renders `null`
+     * — same contract as form fields.
+     */
+    visibleWhen?: (engine: Engine) => boolean;
+    /**
+     * RBAC requirement. When the current subject does not satisfy the
+     * requirement, the alert is hidden (or disabled / read-only,
+     * per `onUnauthorized`).
+     */
+    access?: AccessRequirement;
+    /** Root-element class shortcut (string or `clsx`-compatible value). */
+    sx?: ClassValue;
+    /** Standard React `className` — appended to the root via `cn()`. */
+    className?: string;
+    /** Per-slot overrides — typed handles for the inner elements. */
+    slotProps?: AlertSlotProps;
+}
+/**
+ * Props for the `<AlertTitle>` sub-component.
+ *
+ * AlertTitle is a separate exported component, not a prop on Alert —
+ * follows MUI's pattern. Pass it as the first child of `<Alert>`:
+ *
+ * @example
+ * <Alert severity="warning">
+ *   <AlertTitle>Subscription expires soon</AlertTitle>
+ *   Your Pro plan ends on 2026-06-20.
+ * </Alert>
+ */
+export interface AlertTitleProps {
+    children: ReactNode;
+    className?: string;
+}
+//# sourceMappingURL=alert.types.d.ts.map

package/dist/src/components/Alert/alert.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alert.types.d.ts","sourceRoot":"","sources":["../../../../src/components/Alert/alert.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACjE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACzD,OAAO,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,uCAAuC,CAAC;AAEvF;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,EAAE,wBAAwB,CAAC,KAAK,CAAC,CAAC;IACvC,IAAI,CAAC,EAAE,wBAAwB,CAAC,MAAM,CAAC,CAAC;IACxC,OAAO,CAAC,EAAE,wBAAwB,CAAC,KAAK,CAAC,CAAC;IAC1C,MAAM,CAAC,EAAE,wBAAwB,CAAC,KAAK,CAAC,CAAC;IACzC,WAAW,CAAC,EAAE,wBAAwB,CAAC,QAAQ,CAAC,CAAC;CAClD;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,UAAU;IACzB;;;;;;OAMG;IACH,QAAQ,EAAE,QAAQ,CAAC;IAEnB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,EAAE,eAAe,CAAC;IAE1B,iCAAiC;IACjC,QAAQ,CAAC,EAAE,SAAS,CAAC;IAErB;;;;;;;;;OASG;IACH,IAAI,CAAC,EAAE,SAAS,GAAG,KAAK,CAAC;IAEzB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IAErB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,SAAS,CAAC;IAEnB;;;;OAIG;IACH,IAAI,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC;IAE1B;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC;IAE1C;;;;OAIG;IACH,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAE3B,uEAAuE;IACvE,EAAE,CAAC,EAAE,UAAU,CAAC;IAEhB,oEAAoE;IACpE,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,iEAAiE;IACjE,SAAS,CAAC,EAAE,cAAc,CAAC;CAC5B;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,SAAS,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB"}

package/dist/src/components/Alert/alert.variants.d.ts

@@ -0,0 +1,85 @@
+import { type VariantProps } from 'tailwind-variants';
+/**
+ * Tailwind-variants recipe for `<Alert>`.
+ *
+ * Slots:
+ *   - `root`         — outer surface, severity + variant color classes
+ *                      come from `_shared/severity/severityVariants`
+ *                      (NOT baked into this recipe, to keep the matrix
+ *                      shared across Alert / Snackbar / future Banner)
+ *   - `icon`         — leading severity icon container
+ *   - `titleSlot`    — `<AlertTitle>` rendered as the first content row
+ *   - `content`      — body text container
+ *   - `action`       — trailing action / close button container
+ *   - `closeButton`  — built-in close `×` (when `onClose` is defined)
+ *
+ * The severity color classes are merged at render time via `cn()` in
+ * `Alert.tsx` — see the call sites of `getSeverityClasses(variant,
+ * severity)`. This recipe owns layout + spacing + typography only.
+ */
+export declare const alertVariants: import("tailwind-variants").TVReturnType<{
+    /**
+     * Layout density. Defaults to comfortable spacing; `compact`
+     * tightens the vertical padding for inline contexts (form
+     * validation summary at the top of a tight modal, etc.).
+     */
+    density: {
+        comfortable: {
+            root: string;
+        };
+        compact: {
+            root: string;
+        };
+    };
+}, {
+    root: string[];
+    icon: string[];
+    titleSlot: string[];
+    content: string[];
+    action: string[];
+    closeButton: string[];
+}, undefined, {
+    /**
+     * Layout density. Defaults to comfortable spacing; `compact`
+     * tightens the vertical padding for inline contexts (form
+     * validation summary at the top of a tight modal, etc.).
+     */
+    density: {
+        comfortable: {
+            root: string;
+        };
+        compact: {
+            root: string;
+        };
+    };
+}, {
+    root: string[];
+    icon: string[];
+    titleSlot: string[];
+    content: string[];
+    action: string[];
+    closeButton: string[];
+}, import("tailwind-variants").TVReturnType<{
+    /**
+     * Layout density. Defaults to comfortable spacing; `compact`
+     * tightens the vertical padding for inline contexts (form
+     * validation summary at the top of a tight modal, etc.).
+     */
+    density: {
+        comfortable: {
+            root: string;
+        };
+        compact: {
+            root: string;
+        };
+    };
+}, {
+    root: string[];
+    icon: string[];
+    titleSlot: string[];
+    content: string[];
+    action: string[];
+    closeButton: string[];
+}, undefined, unknown, unknown, undefined>>;
+export type AlertVariantProps = VariantProps<typeof alertVariants>;
+//# sourceMappingURL=alert.variants.d.ts.map

package/dist/src/components/Alert/alert.variants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alert.variants.d.ts","sourceRoot":"","sources":["../../../../src/components/Alert/alert.variants.ts"],"names":[],"mappings":"AAAA,OAAO,EAAM,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAE1D;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,aAAa;IAmCtB;;;;OAIG;;;;;;;;;;;;;;;;;IAJH;;;;OAIG;;;;;;;;;;;;;;;;;IAJH;;;;OAIG;;;;;;;;;;;;;;;;2CASL,CAAC;AAEH,MAAM,MAAM,iBAAiB,GAAG,YAAY,CAAC,OAAO,aAAa,CAAC,CAAC"}

package/dist/src/components/Avatar/Avatar.d.ts

@@ -0,0 +1,48 @@
+import type { AvatarGroupProps, AvatarProps } from './avatar.types.js';
+/**
+ * `<Avatar>` — image / initials / icon visual identity.
+ *
+ * Fallback chain (top to bottom — first match wins):
+ *   1. `src` set + image loads OK    → render `<img>`
+ *   2. `src` set + image fails       → render initials from `name`
+ *   3. `src` absent + `name` set     → render initials from `name`
+ *   4. `fallbackIcon` set            → render that ReactNode
+ *   5. Nothing                        → render generic user SVG
+ *
+ * Color resolution (only for fallback content, image surface is
+ * independent):
+ *   - `color="primary"` only           → soft default (bg-100, text-900)
+ *   - `color="primary" tone={500}`     → bg-primary-500 + text-primary-50
+ *   - Outside the palette              → use `sx`
+ *
+ * No `access` / `visibleWhen` — Avatar is display-only by category.
+ * For visibility gating, wrap in `<Box>` (which has both since
+ * Sprint 4.4).
+ */
+export declare const Avatar: import("react").ForwardRefExoticComponent<AvatarProps & import("react").RefAttributes<HTMLSpanElement>>;
+/**
+ * `<AvatarGroup>` — thin horizontal wrapper for overlapping avatars.
+ *
+ * Slices children to `max - 1` visible items and renders a trailing
+ * "+N" overflow indicator with the remaining count (when more than
+ * `max` children are passed).
+ *
+ * Each child Avatar inherits the group's `size` unless it explicitly
+ * overrides. When `withRing` is `true` (default), each visible
+ * Avatar gets a `ring-2 ring-white` halo so overlapping borders
+ * stay visually separated.
+ *
+ * @example
+ * ```tsx
+ * <AvatarGroup max={3}>
+ *   <Avatar name="Maya Rodriguez" color="primary" />
+ *   <Avatar name="John Doe" color="success" />
+ *   <Avatar name="Sara Chen" color="warning" />
+ *   <Avatar name="Lila Park" color="info" />
+ *   <Avatar name="Eve Kim" color="danger" />
+ * </AvatarGroup>
+ * // Renders: MR, JD, SC + a "+2" overflow chip
+ * ```
+ */
+export declare const AvatarGroup: import("react").ForwardRefExoticComponent<AvatarGroupProps & import("react").RefAttributes<HTMLDivElement>>;
+//# sourceMappingURL=Avatar.d.ts.map

package/dist/src/components/Avatar/Avatar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Avatar.d.ts","sourceRoot":"","sources":["../../../../src/components/Avatar/Avatar.tsx"],"names":[],"mappings":"AAcA,OAAO,KAAK,EACV,gBAAgB,EAChB,WAAW,EAGZ,MAAM,mBAAmB,CAAC;AA+D3B;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,MAAM,yGA4FjB,CAAC;AAmBH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,WAAW,6GAgEvB,CAAC"}

package/dist/src/components/Avatar/avatar.types.d.ts

@@ -0,0 +1,162 @@
+import type { ImgHTMLAttributes, ReactNode } from 'react';
+import type { ClassValue } from 'tailwind-variants';
+import type { BoxProps } from '../Box/box.types.js';
+/**
+ * Avatar size scale — maps to spacing tokens via avatar.variants.ts:
+ *   - xs → w-5  / 20px
+ *   - sm → w-7  / 28px
+ *   - md → w-9  / 36px  ← default
+ *   - lg → w-12 / 48px
+ *   - xl → w-16 / 64px
+ */
+export type AvatarSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+/**
+ * Avatar shape — semantic shortcut. Maps internally to a Box-style
+ * `radius` value:
+ *   - circle → 'full'
+ *   - rounded → 'lg'
+ *   - square → 'none'
+ *
+ * When both `shape` and `radius` are set, `radius` wins (explicit
+ * token reference takes precedence over semantic shortcut).
+ */
+export type AvatarShape = 'circle' | 'rounded' | 'square';
+/**
+ * Intent color — drives the fallback bg + text colors when no `src`
+ * is provided (or when the image fails to load). Reuses the 7
+ * Dashforge intent tokens.
+ */
+export type AvatarColor = 'neutral' | 'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info';
+/**
+ * Tone shade for the fallback background — gives type-safe access to
+ * any specific shade within the chosen `color` palette. When omitted,
+ * the default "soft" treatment is applied (bg-{color}-100 +
+ * text-{color}-900). When set, both bg and text are computed:
+ *   - tones 50-400  → bg-{color}-{tone} + text-{color}-900 (dark text)
+ *   - tones 500-900 → bg-{color}-{tone} + text-{color}-50  (light text)
+ *
+ * For colors outside the token palette (custom hex, gradient, image
+ * patterns), use the `sx` escape hatch with arbitrary Tailwind
+ * utilities.
+ */
+export type AvatarTone = 50 | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900;
+/**
+ * Props for `<Avatar>`.
+ *
+ * Fallback resolution chain:
+ *   1. `src` set + image loads OK   → render `<img>`
+ *   2. `src` set + image fails      → render initials from `name`
+ *      (or a generic user icon if `name` is also absent)
+ *   3. `src` absent + `name` set    → render initials from `name`
+ *      (first letter of first two words, uppercased)
+ *   4. Everything absent            → render a generic user icon
+ *
+ * No `access` / `visibleWhen` — Avatar is display-only by category.
+ * For visibility gating, wrap in `<Box>` (which has both props since
+ * Sprint 4.4).
+ */
+export interface AvatarProps {
+    /** Image URL. Falls back to initials/icon on load failure. */
+    src?: string;
+    /**
+     * `alt` text for the image. **Required when `src` is set** (a11y
+     * — screen readers need a name). When `src` is absent, the alt is
+     * implied from `name`.
+     */
+    alt?: string;
+    /** Additional `<img>` HTML attributes (sizes, loading, srcSet, …). */
+    imgProps?: ImgHTMLAttributes<HTMLImageElement>;
+    /**
+     * Person / entity name. Auto-generates initials when `src` is
+     * absent or the image fails to load. Algorithm: take the first
+     * letter of the first two whitespace-separated words, uppercased.
+     * "Maya Rodriguez" → "MR". "Cher" → "C". Empty → generic icon.
+     */
+    name?: string;
+    /**
+     * Shape — semantic shortcut. Override with `radius` for fine
+     * control on the Box token scale.
+     * @default 'circle'
+     */
+    shape?: AvatarShape;
+    /**
+     * Border radius — same enum as `<Box rounded>` (Box token scale).
+     * When set, overrides the `shape` mapping. Useful for matching a
+     * specific Card/Box radius (e.g., `radius='2xl'`).
+     */
+    radius?: BoxProps['rounded'];
+    /** @default 'md' */
+    size?: AvatarSize;
+    /**
+     * Intent color used for the fallback background. Ignored when the
+     * image loads successfully.
+     * @default 'neutral'
+     */
+    color?: AvatarColor;
+    /**
+     * Specific shade within the `color` palette (TS-safe). When set,
+     * overrides the default "soft" treatment. See `AvatarTone` for the
+     * full scale.
+     */
+    tone?: AvatarTone;
+    /** Root-element class shortcut (string or clsx-compatible value). */
+    sx?: ClassValue;
+    /** Standard React className — appended to the root via `cn()`. */
+    className?: string;
+    /**
+     * Optional custom fallback ReactNode — replaces both initials and
+     * the generic icon when the image is absent / fails. Useful for
+     * Avatar-with-emoji or Avatar-with-custom-icon patterns. When
+     * passed, `name` is ignored for initials generation but kept as
+     * `alt` semantic.
+     *
+     * **NB**: this is the ONE exception to the "no fallback prop —
+     * only name" rule from the spec. Kept narrow because emoji /
+     * custom icon avatars are common enough that forcing `sx` for
+     * them would be friction.
+     */
+    fallbackIcon?: ReactNode;
+}
+/**
+ * Props for `<AvatarGroup>` — thin horizontal wrapper.
+ *
+ * Renders the first `max` children visibly (with negative-margin
+ * overlap), then an overflow indicator avatar with the remaining
+ * count. Each child Avatar inherits `size` from the group unless it
+ * overrides explicitly. Optional `ring-2 ring-white` halo on each
+ * child via the group's `withRing` prop (visually separates
+ * overlapping avatars on a busy background).
+ */
+export interface AvatarGroupProps {
+    /** Avatar children. */
+    children: ReactNode;
+    /**
+     * Max number of avatars to render visibly. Excess collapses into
+     * a trailing "+N" overflow indicator.
+     * @default 4
+     */
+    max?: number;
+    /**
+     * Size applied to every child Avatar (unless the child explicitly
+     * overrides). Propagated via React.cloneElement.
+     * @default 'md'
+     */
+    size?: AvatarSize;
+    /**
+     * Negative margin between overlapping avatars. Tighter = more
+     * overlap. Looser = more space.
+     * @default 'sm'
+     */
+    spacing?: 'xs' | 'sm' | 'md';
+    /**
+     * Wrap each child avatar with a `ring-2 ring-white` halo for
+     * separation on busy backgrounds.
+     * @default true
+     */
+    withRing?: boolean;
+    /** Standard className. */
+    className?: string;
+    /** sx escape hatch. */
+    sx?: ClassValue;
+}
+//# sourceMappingURL=avatar.types.d.ts.map

package/dist/src/components/Avatar/avatar.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"avatar.types.d.ts","sourceRoot":"","sources":["../../../../src/components/Avatar/avatar.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAC1D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAEpD;;;;;;;GAOG;AACH,MAAM,MAAM,UAAU,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAE1D;;;;;;;;;GASG;AACH,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAC;AAE1D;;;;GAIG;AACH,MAAM,MAAM,WAAW,GACnB,SAAS,GACT,SAAS,GACT,WAAW,GACX,SAAS,GACT,SAAS,GACT,QAAQ,GACR,MAAM,CAAC;AAEX;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,UAAU,GAClB,EAAE,GACF,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,CAAC;AAER;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,WAAW;IAE1B,8DAA8D;IAC9D,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;;;OAIG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb,sEAAsE;IACtE,QAAQ,CAAC,EAAE,iBAAiB,CAAC,gBAAgB,CAAC,CAAC;IAG/C;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAGd;;;;OAIG;IACH,KAAK,CAAC,EAAE,WAAW,CAAC;IAEpB;;;;OAIG;IACH,MAAM,CAAC,EAAE,QAAQ,CAAC,SAAS,CAAC,CAAC;IAE7B,oBAAoB;IACpB,IAAI,CAAC,EAAE,UAAU,CAAC;IAElB;;;;OAIG;IACH,KAAK,CAAC,EAAE,WAAW,CAAC;IAEpB;;;;OAIG;IACH,IAAI,CAAC,EAAE,UAAU,CAAC;IAGlB,qEAAqE;IACrE,EAAE,CAAC,EAAE,UAAU,CAAC;IAEhB,kEAAkE;IAClE,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;;;;;;;;;OAWG;IACH,YAAY,CAAC,EAAE,SAAS,CAAC;CAC1B;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,gBAAgB;IAC/B,uBAAuB;IACvB,QAAQ,EAAE,SAAS,CAAC;IAEpB;;;;OAIG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;;;OAIG;IACH,IAAI,CAAC,EAAE,UAAU,CAAC;IAElB;;;;OAIG;IACH,OAAO,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;IAE7B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB,0BAA0B;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,uBAAuB;IACvB,EAAE,CAAC,EAAE,UAAU,CAAC;CACjB"}