@skdx/react 0.27.0 → 0.29.0

package/dist/autocomplete/types.d.ts

@@ -1,178 +1,259 @@
 import type * as React from 'react';
+import type { FormValidityHandle } from '../utils/formControl.js';
+import type { PassThroughProps } from '../utils/passThrough.js';
 import type { PopperContentProps } from '../utils/popper.js';
 import type { PortalProps } from '../utils/portal.js';
 import type { PrimitivePropsWithRef } from '../utils/primitive.js';
 import type { FocusOutsideEvent, InteractOutsideEvent } from '../utils/useDismiss.js';
 import type { OptionEntry } from '../utils/useOptionCollection.js';
+/** One suggestion for the {@link AutocompleteProps.options} recipe prop — a flat entry rendered as an `AutocompleteItem`. */
+export interface AutocompleteOption {
+    /** Value committed to the field when this suggestion is chosen. */
+    value: string;
+    /**
+     * Text matched by `filter` and written to the Input on selection.
+     * @default undefined — falls back to `value`.
+     */
+    label?: string | undefined;
+    /**
+     * Excludes this suggestion from selection and pointer highlight.
+     * @default false
+     */
+    disabled?: boolean | undefined;
+}
+/** A labeled group of {@link AutocompleteOption}s for {@link AutocompleteProps.options} — grouping is data, never a wrapper component. */
+export interface AutocompleteOptionGroup {
+    /** Heading rendered as an `AutocompleteGroupLabel` above this group's suggestions. */
+    label: string;
+    /** The suggestions belonging to this group. */
+    options: AutocompleteOption[];
+}
+/** One entry of {@link AutocompleteProps.options}: a flat suggestion, or a labeled group of them. */
+export type AutocompleteOptionOrGroup = AutocompleteOption | AutocompleteOptionGroup;
+/**
+ * Filters and ranks Items against the draft text: `'manual'` filters nothing,
+ * a predicate filters, and a number ranks (0 excludes, positive keeps and
+ * orders by score descending).
+ */
+export type AutocompleteFilter = 'manual' | ((itemText: string, inputValue: string) => boolean | number);
+/** What drove an {@link Autocomplete} value change. */
+export type AutocompleteValueChangeReason = 'keyboard' | 'pointer' | 'programmatic';
 /**
- * Decides which `AutocompleteItem`s survive the current draft text.
- * `undefined` filters nothing — the consumer renders only the suggestions that
- * match, which is what an async or server-side search needs.
+ * The payload `onValueChange` receives; `created` is `true` when the commit
+ * was the draft text itself rather than an existing suggestion.
  */
-export type AutocompleteFilter = (itemText: string, inputValue: string) => boolean;
-/** @internal Shared state distributed from {@link Autocomplete} to its parts via context. Not part of the public API. */
+export interface AutocompleteValueChangeDetail {
+    /** The new committed value. */
+    value: string;
+    /** Previous value, or `null` when there was none. */
+    previousValue: string | null;
+    /** What drove the change. */
+    reason: AutocompleteValueChangeReason;
+    /** True when the commit was the draft text rather than a suggestion. */
+    created: boolean;
+}
+/** @internal Shared state distributed from {@link Autocomplete} to its parts via context. */
 export interface AutocompleteContextValue {
     inputRef: React.RefObject<HTMLInputElement | null>;
-    /** The optional `AutocompleteTrigger`, if one is mounted. Part of the layer for dismissal purposes: it toggles on *click*, so a pointer-down on it must not be reported as an outside interaction and close the popup the click is about to reopen. */
+    /** Excluded from outside-interaction detection so its click can't close the popup it just opened. */
     triggerRef: React.RefObject<HTMLButtonElement | null>;
     contentRef: React.RefObject<HTMLDivElement | null>;
     /** Id of `AutocompleteList`, referenced by the input's `aria-controls`. */
     listId: string;
-    /** The committed value — the answer the form takes, which need not be one of the suggestions. */
+    /** The committed value, which need not match any suggestion. */
     value: string;
     /** Whether an option value is the committed one, for `aria-selected`. */
     isSelected: (value: string) => boolean;
-    /** The draft text currently in the input. */
     inputValue: string;
     onInputValueChange: (value: string) => void;
     open: boolean;
     onOpenChange: (open: boolean) => void;
     activeId: string | null;
+    /** CSS `order` for score-ranked Items when `filter` ranks; null leaves order untouched. */
+    itemOrder: ReadonlyMap<string, number> | null;
     setActiveId: (id: string | null) => void;
-    moveActive: (direction: 1 | -1) => void;
+    moveActive: (direction: 1 | -1) => string | null;
+    /** Moves the highlight to the first/last Item, only while open (Home/End). */
+    moveActiveToEdge: (edge: 'first' | 'last') => string | null;
     openWithHighlight: (edge: 'first' | 'last') => void;
     itemCount: number;
     registerItem: (id: string, entry: OptionEntry) => void;
     unregisterItem: (id: string) => void;
     getItem: (id: string) => OptionEntry | undefined;
-    /** Whether an item with this text survives the current `filter` and draft text. */
+    /** Whether an item's text survives the current `filter` and draft text. */
     matchesFilter: (itemText: string) => boolean;
-    /** Commits a suggestion: writes its text into the input, its value into `value`, and closes. */
-    commitItem: (value: string, text: string) => void;
-    /** Commits the raw draft text as the value (Tab, blur) — or restores the last committed text when `allowCustomValue` is off. */
-    commitInputValue: () => void;
-    /** Closes and puts the last committed text back in the input (Escape). */
+    /** Commits a suggestion — writes its text and value, closes, and tags the change with `reason`. */
+    commitItem: (value: string, text: string, reason: AutocompleteValueChangeReason) => void;
+    /** Commits the raw draft (Tab, blur) or restores the last committed text when `allowCustomValue` is off. */
+    commitInputValue: (reason: AutocompleteValueChangeReason) => void;
+    /** Closes and restores the last committed text (Escape). */
     revert: () => void;
+    /** Empties draft, value, and the remembered committed text so blur can't restore what was cleared. */
+    clear: () => void;
     allowCustomValue: boolean;
     openOnFocus: boolean;
     disabled: boolean;
     readOnly: boolean;
     invalid: boolean;
+    /** Whether suggestions are in flight, exposed as `aria-busy`/`data-loading`, suppressing count announcement. */
+    loading: boolean;
+    /** Form field name, stamped on the real `<input>` the Input part renders. */
+    name: string | undefined;
+    /** Id of the `<form>` the field submits into, stamped on the real `<input>` the Input part renders. */
+    form: string | undefined;
 }
-/** Props for the {@link Autocomplete} root. */
-export interface AutocompleteProps {
+/**
+ * Constraint-validation handle for {@link Autocomplete}'s ref; delegates to
+ * the Input's real `<input>`, or reports valid when none is mounted.
+ */
+export type AutocompleteHandle = FormValidityHandle;
+/**
+ * Props for the {@link Autocomplete} root. Standard attributes land on
+ * the derived Input (`role="combobox"`).
+ */
+export interface AutocompleteProps extends PassThroughProps {
     /**
-     * The `AutocompleteInput`/`AutocompletePortal` parts, rendered as children —
-     * `Autocomplete` itself renders no DOM.
+     * The `AutocompleteInput`/`AutocompletePortal` parts — `Autocomplete` itself renders no DOM.
      * @default undefined — renders nothing without children.
      */
-    children?: React.ReactNode;
+    children?: React.ReactNode | undefined;
     /**
-     * The committed value, for controlled usage. Pair with `onValueChange`. This
-     * is a *separate* state from `inputValue`: the draft text moves on every
-     * keystroke, the value only when something is committed.
+     * The committed value, for controlled usage, distinct from the draft `inputValue`.
      * @default undefined — uncontrolled, tracks its own committed value internally.
      */
-    value?: string;
+    value?: string | undefined;
     /**
-     * Initial committed value, for uncontrolled usage. Also seeds
-     * `defaultInputValue`, so an autocomplete restored from saved state shows
-     * the text it committed rather than an empty field.
+     * Initial committed value; also seeds `defaultInputValue`.
      * @default '' — nothing committed, so blurring an untouched field commits nothing.
      */
-    defaultValue?: string;
+    defaultValue?: string | undefined;
     /**
-     * Fires with the new committed value — on Enter, on a suggestion click, on
-     * Tab, and on blur. Never on a keystroke.
+     * Fires with the new committed value on Enter, a suggestion click, Tab, or blur — never on a keystroke.
      * @default undefined — no-op if omitted.
      */
-    onValueChange?: (value: string) => void;
+    onValueChange?: ((detail: AutocompleteValueChangeDetail) => void) | undefined;
     /**
-     * The draft text in the input, for controlled usage. Pair with
-     * `onInputValueChange` — typically used to drive filtering of the suggestion
-     * list, since filtering is the consumer's job unless `filter` is supplied.
+     * Controlled draft text; with no `filter` set, this prop is the filtering mechanism itself.
      * @default undefined — uncontrolled, tracks its own draft text internally.
      */
-    inputValue?: string;
+    inputValue?: string | undefined;
     /**
-     * Initial draft text, for uncontrolled usage.
+     * Initial draft text, falls back to defaultValue if unset.
      * @default defaultValue — the field opens showing whatever value it starts committed to.
      */
-    defaultInputValue?: string;
+    defaultInputValue?: string | undefined;
     /**
-     * Fires with the new draft text on every keystroke, and whenever a commit or
-     * a revert rewrites the field.
+     * Fires with the new draft text on every keystroke, commit, or revert.
      * @default undefined — no-op if omitted.
      */
-    onInputValueChange?: (inputValue: string) => void;
+    onInputValueChange?: ((inputValue: string) => void) | undefined;
     /**
-     * Whether the suggestion popup is open, for controlled usage. Pair with `onOpenChange`.
+     * Whether the suggestion popup is open, for controlled usage.
      * @default undefined — uncontrolled, tracks its own open state internally.
      */
-    open?: boolean;
+    open?: boolean | undefined;
     /**
-     * Initial open state, for uncontrolled usage.
+     * Initial open state; popup waits for keystroke or trigger if false.
      * @default false
      */
-    defaultOpen?: boolean;
+    defaultOpen?: boolean | undefined;
     /**
-     * Fires with the new open state whenever it changes, controlled or not.
+     * Fires with the new open state whenever it changes.
      * @default undefined — no-op if omitted.
      */
-    onOpenChange?: (open: boolean) => void;
+    onOpenChange?: ((open: boolean) => void) | undefined;
     /**
-     * Fires with the new open state once the change has finished on screen —
-     * after `AutocompleteContent`'s enter or exit animation ends, or as soon as it
-     * has settled when the popup declares no animation. Use it for work that must
-     * not race the transition; use `onOpenChange` for work that must not wait for it.
+     * Fires after the open-state animation completes; use for work that must not race the transition.
      * @default undefined — no-op if omitted.
      */
-    onOpenChangeComplete?: (open: boolean) => void;
+    onOpenChangeComplete?: ((open: boolean) => void) | undefined;
     /**
-     * Lets the committed value be text that is not in the suggestion list — Tab,
-     * Enter with nothing highlighted, and blur all commit the raw draft. This is
-     * the whole point of the family: an autocomplete *suggests*, it does not
-     * constrain. Turn it off and an unmatched draft is discarded on blur and the
-     * last committed text is put back, which makes this a
-     * `Combobox` with extra steps — reach for that instead.
+     * Lets the committed value be text outside the suggestion list; off, an unmatched draft reverts to the last committed text on blur.
      * @default true
      */
-    allowCustomValue?: boolean;
+    allowCustomValue?: boolean | undefined;
     /**
-     * Opens the suggestion popup as soon as the input takes focus, instead of
-     * waiting for the first keystroke. Off by default: an empty field usually
-     * means an unfiltered list, and dropping the entire dataset over the page on
-     * focus is rarely what the user asked for.
+     * Opens the suggestion popup on focus instead of waiting for the first keystroke.
      * @default false
      */
-    openOnFocus?: boolean;
+    openOnFocus?: boolean | undefined;
+    /**
+     * Keeps the first suggestion highlighted as the filtered list changes while open, so Enter always has a target.
+     * @default false
+     */
+    autoHighlight?: boolean | undefined;
+    /**
+     * Wraps arrow navigation around list ends; set `false` to clamp. Home/End always jump to an end regardless.
+     * @default true
+     */
+    loop?: boolean | undefined;
     /**
-     * Predicate deciding which `AutocompleteItem`s survive the current draft
-     * text. Every item is measured (its `textValue`, or its rendered text) and
-     * the rejected ones render nothing at all, so they leave the suggestion
-     * count, the highlight order, and `AutocompleteEmpty` exactly as if the
-     * consumer had removed them.
+     * Filters and ranks Items: `'manual'` filters nothing (default), a predicate filters and ranks by score.
      * @default undefined — nothing is filtered; the consumer renders only the matching items, which is what an async or server-side search needs.
      */
-    filter?: AutocompleteFilter;
+    filter?: AutocompleteFilter | undefined;
+    /**
+     * Blocks all interaction; the input is natively disabled and the popup can't open.
+     * @default false
+     */
+    disabled?: boolean | undefined;
     /**
-     * Blocks all interaction: the input is natively `disabled`, so it is not
-     * focusable and the popup can never open.
+     * Shows the committed text but blocks changes, while remaining focusable, unlike `disabled`.
      * @default false
      */
-    disabled?: boolean;
+    readOnly?: boolean | undefined;
     /**
-     * Shows the committed text but blocks any change to it — the input is
-     * natively `readOnly` and still focusable (unlike `disabled`), and no
-     * keystroke, Tab or blur commits anything.
+     * Marks the field as invalid, exposed as `aria-invalid`/`data-invalid` on the Input.
      * @default false
      */
-    readOnly?: boolean;
+    invalid?: boolean | undefined;
     /**
-     * Marks the field as invalid, exposed as `aria-invalid`/`data-invalid` on
-     * `AutocompleteInput`.
+     * Marks suggestions as in flight; suppresses the suggestion-count announcement that would race an in-progress fetch.
      * @default false
      */
-    invalid?: boolean;
+    loading?: boolean | undefined;
+    /**
+     * Form field name; needed on the root since a shadow-root input can't associate with the ancestor form.
+     * @default undefined — the field submits nothing at all.
+     */
+    name?: string | undefined;
     /**
-     * Formats the message announced (through the shared `LiveAnnouncer`) each
-     * time the number of rendered suggestions changes while the popup is open.
-     * Filtering changes nothing `aria-expanded` or `aria-activedescendant`
-     * reports, so this count is the only signal a screen-reader user gets that
-     * typing narrowed anything. Return an empty string to announce nothing.
+     * Id of the `<form>` the field submits into; requires `name` to have any effect.
+     * @default undefined — associates with the nearest ancestor `<form>`.
+     */
+    form?: string | undefined;
+    /**
+     * Formats the polite announcement when the rendered suggestion count changes while open; return an empty string to announce nothing.
      * @default defaultGetSuggestionCountLabel — e.g. `"3 suggestions available"`
      */
-    getSuggestionCountLabel?: (count: number) => string;
+    getResultCountLabel?: ((count: number) => string) | undefined;
+    /**
+     * Flat or grouped suggestion data; when present, derives the Input, Portal, and List instead of using children.
+     * @default undefined — nothing is derived; compose the parts yourself via `children`.
+     */
+    options?: AutocompleteOptionOrGroup[] | undefined;
+    /**
+     * Customises how a derived suggestion renders; only read while `options` derives the anatomy.
+     * @default undefined — renders `option.label ?? option.value`.
+     */
+    renderOption?: ((option: AutocompleteOption, state: {
+        selected: boolean;
+    }) => React.ReactNode) | undefined;
+    /**
+     * Placeholder for the derived Input; only read while `options` derives the anatomy.
+     * @default undefined
+     */
+    placeholder?: string | undefined;
+    /**
+     * Whether the derived anatomy renders a Clear button that empties the draft text and the committed value.
+     * @default false — no Clear button is derived.
+     */
+    clearable?: boolean | undefined;
+    /**
+     * Accessible name for the derived input and list; only read while `options` derives the anatomy.
+     * @default undefined — falls back to `placeholder`; with neither, no attribute is emitted.
+     */
+    'aria-label'?: string | undefined;
 }
 /** Props for {@link AutocompleteInput}, the free-text field that owns real DOM focus for the whole interaction. */
 export interface AutocompleteInputProps extends Omit<PrimitivePropsWithRef<'input'>, 'value' | 'defaultValue'> {
@@ -188,42 +269,39 @@ export interface AutocompletePortalProps extends PortalProps {
      * present in the DOM during an exit transition.
      * @default false
      */
-    forceMount?: boolean;
+    forceMount?: boolean | undefined;
 }
 /**
- * Props for {@link AutocompleteContent}, the popup shell. Extends
- * {@link PopperContentProps} (`side`, `align`, `sideOffset`, `alignOffset`,
- * `avoidCollisions`, `collisionPadding`) for floating-ui positioning relative
- * to the input — note `AutocompleteContent` defaults `side` to `'bottom'`,
- * `align` to `'start'` and `sideOffset` to `4`, instead of the popper base
- * defaults (`'bottom'` / `'center'` / `0`).
+ * Props for {@link AutocompleteContent}, extending {@link PopperContentProps}
+ * for floating-ui positioning; defaults `side` to `'bottom'`, `align` to
+ * `'start'`, and `sideOffset` to `4`.
  */
 export interface AutocompleteContentProps extends PopperContentProps {
     /**
      * Keep this popup mounted even while closed, instead of unmounting it.
      * @default false
      */
-    forceMount?: boolean;
+    forceMount?: boolean | undefined;
     /**
-     * Fires when Escape is pressed while the popup is open. Call `event.preventDefault()` to stop it from closing — which also leaves the draft text alone, since Escape's default here is "revert to the last committed value and close".
+     * Fires on Escape while open; call `event.preventDefault()` to keep the popup open and the draft text unchanged.
      * @default undefined — no-op if omitted.
      */
-    onEscapeKeyDown?: (event: KeyboardEvent) => void;
+    onEscapeKeyDown?: ((event: KeyboardEvent) => void) | undefined;
     /**
-     * Fires on pointer-down outside the popup and the input. Call `event.preventDefault()` to stop the popup from closing.
+     * Fires on pointer-down outside the popup and the input; call `event.preventDefault()` to keep the popup open.
      * @default undefined — no-op if omitted.
      */
-    onPointerDownOutside?: (event: PointerEvent) => void;
+    onPointerDownOutside?: ((event: PointerEvent) => void) | undefined;
     /**
-     * Fires when focus moves to an element outside the popup and the input. Call `event.preventDefault()` to stop the popup from closing. Receives a cancelable stand-in carrying the original `focusin` as its `detail`, since `focusin` itself cannot be canceled.
+     * Fires when focus leaves the popup and the input, via a cancelable stand-in since native `focusin` cannot itself be canceled.
      * @default undefined — no-op if omitted.
      */
-    onFocusOutside?: (event: FocusOutsideEvent) => void;
+    onFocusOutside?: ((event: FocusOutsideEvent) => void) | undefined;
     /**
-     * Fires for either kind of outside interaction — pointer-down or focus — immediately before the specific handler above and with the same event, so one `event.preventDefault()` here vetoes the dismissal whichever way it was triggered.
+     * Fires before either outside handler above, with the same event, so one `event.preventDefault()` here vetoes dismissal from either trigger.
      * @default undefined — no-op if omitted.
      */
-    onInteractOutside?: (event: InteractOutsideEvent) => void;
+    onInteractOutside?: ((event: InteractOutsideEvent) => void) | undefined;
 }
 /** Props for {@link AutocompleteList}, the `role="listbox"` the suggestions live in. */
 export interface AutocompleteListProps extends PrimitivePropsWithRef<'div'> {
@@ -236,15 +314,27 @@ export interface AutocompleteItemProps extends PrimitivePropsWithRef<'div'> {
      * Excludes this suggestion from selection and pointer highlight.
      * @default false
      */
-    disabled?: boolean;
+    disabled?: boolean | undefined;
     /**
-     * Text the root's `filter` predicate matches against, and the text a
-     * commit writes back into `AutocompleteInput`. Only needed when the item
-     * renders more than its label (an icon, a secondary line).
+     * Text matched by `filter` and written to the Input on commit; needed only when the item renders more than its label.
      * @default undefined — falls back to the item's rendered text content.
      */
-    textValue?: string;
+    textValue?: string | undefined;
 }
 /** Props for {@link AutocompleteEmpty}, shown in place of the suggestion list when no items are rendered. */
 export interface AutocompleteEmptyProps extends PrimitivePropsWithRef<'div'> {
 }
+/** Props for {@link AutocompleteClear}, the optional button that empties the draft text and the committed value. */
+export interface AutocompleteClearProps extends PrimitivePropsWithRef<'button'> {
+}
+/** Props for {@link AutocompleteGroup}, a named section of related suggestions inside `AutocompleteList`. */
+export interface AutocompleteGroupProps extends PrimitivePropsWithRef<'div'> {
+}
+/** Props for {@link AutocompleteGroupLabel}, the heading that names its enclosing `AutocompleteGroup`. */
+export interface AutocompleteGroupLabelProps extends PrimitivePropsWithRef<'div'> {
+}
+/** @internal What an {@link AutocompleteGroup} publishes to the `AutocompleteGroupLabel` inside it. */
+export interface AutocompleteGroupContextValue {
+    /** The id the group points `aria-labelledby` at, which its label claims. */
+    labelId: string;
+}

package/dist/avatar/Avatar.cjs

@@ -1 +1,2 @@
-"use strict";var T=Object.create;var p=Object.defineProperty;var h=Object.getOwnPropertyDescriptor;var H=Object.getOwnPropertyNames;var V=Object.getPrototypeOf,q=Object.prototype.hasOwnProperty;var z=(a,t)=>{for(var e in t)p(a,e,{get:t[e],enumerable:!0})},I=(a,t,e,o)=>{if(t&&typeof t=="object"||typeof t=="function")for(let r of H(t))!q.call(a,r)&&r!==e&&p(a,r,{get:()=>t[r],enumerable:!(o=h(t,r))||o.enumerable});return a};var l=(a,t,e)=>(e=a!=null?T(V(a)):{},I(t||!a||!a.__esModule?p(e,"default",{value:a,enumerable:!0}):e,a)),B=a=>I(p({},"__esModule",{value:!0}),a);var D={};z(D,{Avatar:()=>R,AvatarFallback:()=>v,AvatarImage:()=>u,AvatarProvider:()=>L,useAvatarContext:()=>s});module.exports=B(D);var f=l(require("react"),1),S=require("../utils/createContext.cjs"),P=require("../utils/part.cjs"),x=require("../utils/primitive.cjs"),c=require("react/jsx-runtime"),[L,s]=(0,S.createSafeContext)("Avatar"),R=f.forwardRef((a,t)=>{let[e,o]=f.useState("idle");return(0,c.jsx)(L,{imageLoadingStatus:e,onImageLoadingStatusChange:o,children:(0,c.jsx)(x.Primitive.span,{...a,...(0,P.skdxPart)("avatar","root",a.className),ref:t})})});R.displayName="Avatar";var d=l(require("react"),1),k=require("../utils/part.cjs"),C=require("../utils/primitive.cjs"),w=require("../utils/useCallbackRef.cjs");var b=require("react/jsx-runtime"),u=d.forwardRef(({onLoadingStatusChange:a=()=>{},src:t,...e},o)=>{let r=s("AvatarImage"),n=(0,w.useCallbackRef)(m=>{a(m),r.onImageLoadingStatusChange(m)});return d.useLayoutEffect(()=>{if(!t){n("error");return}let m=!0,g=new window.Image,A=E=>()=>{m&&n(E)};return n("loading"),g.onload=A("loaded"),g.onerror=A("error"),g.src=t,()=>{m=!1}},[t,n]),r.imageLoadingStatus==="loaded"?(0,b.jsx)(C.Primitive.img,{src:t,...e,...(0,k.skdxPart)("avatar","image",e.className),ref:o}):null});u.displayName="AvatarImage";var i=l(require("react"),1),y=require("../utils/part.cjs"),F=require("../utils/primitive.cjs");var N=require("react/jsx-runtime"),v=i.forwardRef(({delayMs:a,...t},e)=>{let o=s("AvatarFallback"),[r,n]=i.useState(a===void 0);return i.useEffect(()=>{if(a===void 0)return;let m=window.setTimeout(()=>n(!0),a);return()=>window.clearTimeout(m)},[a]),r&&o.imageLoadingStatus!=="loaded"?(0,N.jsx)(F.Primitive.span,{...t,...(0,y.skdxPart)("avatar","fallback",t.className),ref:e}):null});v.displayName="AvatarFallback";0&&(module.exports={Avatar,AvatarFallback,AvatarImage,AvatarProvider,useAvatarContext});
+'use client';
+"use strict";var q=Object.create;var p=Object.defineProperty;var G=Object.getOwnPropertyDescriptor;var H=Object.getOwnPropertyNames;var K=Object.getPrototypeOf,M=Object.prototype.hasOwnProperty;var O=(t,a)=>{for(var e in a)p(t,e,{get:a[e],enumerable:!0})},P=(t,a,e,r)=>{if(a&&typeof a=="object"||typeof a=="function")for(let o of H(a))!M.call(t,o)&&o!==e&&p(t,o,{get:()=>a[o],enumerable:!(r=G(a,o))||r.enumerable});return t};var y=(t,a,e)=>(e=t!=null?q(K(t)):{},P(a||!t||!t.__esModule?p(e,"default",{value:t,enumerable:!0}):e,t)),Q=t=>P(p({},"__esModule",{value:!0}),t);var Y={};O(Y,{Avatar:()=>x,AvatarFallback:()=>v,AvatarImage:()=>A,AvatarProvider:()=>B,useAvatarContext:()=>c});module.exports=Q(Y);var E=y(require("react"),1),J=require("../utils/appearance.cjs"),T=require("../utils/createContext.cjs"),V=require("../utils/part.cjs"),X=require("../utils/primitive.cjs");var g=y(require("react"),1),k=require("../utils/part.cjs"),R=require("../utils/primitive.cjs");var S=require("react/jsx-runtime"),v=({delayMs:t,ref:a,...e})=>{let r=c("AvatarFallback"),[o,d]=g.useState(t===void 0);return g.useEffect(()=>{if(t===void 0)return;let f=window.setTimeout(()=>d(!0),t);return()=>window.clearTimeout(f)},[t]),o&&r.imageLoadingStatus!=="loaded"?(0,S.jsx)(R.Primitive.span,{...e,...(0,k.skdxPart)("avatar","fallback",e.className),ref:a}):null};v.displayName="AvatarFallback";var L=y(require("react"),1),C=require("../utils/part.cjs"),w=require("../utils/primitive.cjs"),N=require("../utils/useCallbackRef.cjs");var F=require("react/jsx-runtime"),A=({onLoadingStatusChange:t=()=>{},src:a,srcSet:e,sizes:r,alt:o,asChild:d,children:f,ref:h,...u})=>{let i=c("AvatarImage"),s=(0,N.useCallbackRef)(m=>{i.onImageLoadingStatusChange(m),t(m)});return L.useLayoutEffect(()=>{if(!a&&!e){s("error");return}let m=!0,n=new window.Image,I=U=>()=>{m&&s(U)};return s("loading"),n.onload=I("loaded"),n.onerror=I("error"),e&&(n.srcset=e),r&&(n.sizes=r),a&&(n.src=a),()=>{m=!1}},[a,e,r,s]),i.imageLoadingStatus==="loaded"?(0,F.jsx)(w.Primitive.img,{asChild:d,src:a,srcSet:e,sizes:r,alt:i.decorative?"":o??i.label??"",...u,...(0,C.skdxPart)("avatar","image",u.className),ref:h,children:d?f:null}):null};A.displayName="AvatarImage";var l=require("react/jsx-runtime");function W(t){let a=t.trim().split(/\s+/).filter(Boolean);if(a.length===0)return"";let e=a[0].charAt(0),r=a.length>1?a[a.length-1].charAt(0):"";return(e+r).toUpperCase()}function D({src:t,name:a,fallbackDelayMs:e}){return(0,l.jsxs)(l.Fragment,{children:[t?(0,l.jsx)(A,{src:t}):null,(0,l.jsx)(v,{delayMs:e,children:a?W(a):null})]})}var b=require("react/jsx-runtime"),[B,c]=(0,T.createSafeContext)("Avatar"),x=({label:t,decorative:a=!1,src:e,name:r,fallbackDelayMs:o,children:d,ref:f,shape:h,size:u,...i})=>{let[s,m]=E.useState("idle"),n=t??r;return(0,b.jsx)(B,{imageLoadingStatus:s,onImageLoadingStatusChange:m,label:n,decorative:a,children:(0,b.jsx)(X.Primitive.span,{"data-load-status":s,role:n?"img":void 0,"aria-label":n,"aria-hidden":a?!0:void 0,...i,...(0,J.appearanceAttrs)({shape:h,size:u},i),...(0,V.skdxPart)("avatar","root",i.className),ref:f,children:d??(0,b.jsx)(D,{src:e,name:r,fallbackDelayMs:o})})})};x.displayName="Avatar";0&&(module.exports={Avatar,AvatarFallback,AvatarImage,AvatarProvider,useAvatarContext});

package/dist/avatar/Avatar.d.cts

@@ -1,23 +1,22 @@
 import * as React from 'react';
 import type { AvatarContextValue, AvatarProps } from './types.cjs';
-export declare const AvatarProvider: {
-    (props: AvatarContextValue & {
-        children: React.ReactNode;
-    }): React.JSX.Element;
-    displayName: string;
-}, useAvatarContext: (consumerName: string) => AvatarContextValue;
+export declare const AvatarProvider: React.FC<AvatarContextValue & {
+    children: React.ReactNode;
+}>, useAvatarContext: (consumerName: string) => AvatarContextValue;
 /**
- * Root of an avatar: owns the image's loading status and hands it down to
- * `AvatarImage` / `AvatarFallback` via context, so the fallback can appear
- * while the image loads or fails, and the image can replace it once loaded.
- * Renders a plain `<span>`.
+ * Avatar root, owns image loading status. Publishes `data-load-status` so skins
+ * can render shimmer. With no children, renders derived anatomy from
+ * `src`/`name`/`fallbackDelayMs`; with children, renders them verbatim.
  *
  * @example
  * ```tsx
- * <Avatar>
- *   <AvatarImage src="/user.png" alt="Jane Doe" />
+ * <Avatar label="Jane Doe">
+ *   <AvatarImage src="/user.png" />
  *   <AvatarFallback delayMs={300}>JD</AvatarFallback>
  * </Avatar>
  * ```
  */
-export declare const Avatar: React.ForwardRefExoticComponent<Omit<AvatarProps, "ref"> & React.RefAttributes<HTMLSpanElement>>;
+export declare const Avatar: {
+    ({ label, decorative, src, name, fallbackDelayMs, children, ref: forwardedRef, shape, size, ...props }: AvatarProps): React.ReactNode;
+    displayName: string;
+};

package/dist/avatar/Avatar.d.ts

@@ -1,23 +1,22 @@
 import * as React from 'react';
 import type { AvatarContextValue, AvatarProps } from './types.js';
-export declare const AvatarProvider: {
-    (props: AvatarContextValue & {
-        children: React.ReactNode;
-    }): React.JSX.Element;
-    displayName: string;
-}, useAvatarContext: (consumerName: string) => AvatarContextValue;
+export declare const AvatarProvider: React.FC<AvatarContextValue & {
+    children: React.ReactNode;
+}>, useAvatarContext: (consumerName: string) => AvatarContextValue;
 /**
- * Root of an avatar: owns the image's loading status and hands it down to
- * `AvatarImage` / `AvatarFallback` via context, so the fallback can appear
- * while the image loads or fails, and the image can replace it once loaded.
- * Renders a plain `<span>`.
+ * Avatar root, owns image loading status. Publishes `data-load-status` so skins
+ * can render shimmer. With no children, renders derived anatomy from
+ * `src`/`name`/`fallbackDelayMs`; with children, renders them verbatim.
  *
  * @example
  * ```tsx
- * <Avatar>
- *   <AvatarImage src="/user.png" alt="Jane Doe" />
+ * <Avatar label="Jane Doe">
+ *   <AvatarImage src="/user.png" />
  *   <AvatarFallback delayMs={300}>JD</AvatarFallback>
  * </Avatar>
  * ```
  */
-export declare const Avatar: React.ForwardRefExoticComponent<Omit<AvatarProps, "ref"> & React.RefAttributes<HTMLSpanElement>>;
+export declare const Avatar: {
+    ({ label, decorative, src, name, fallbackDelayMs, children, ref: forwardedRef, shape, size, ...props }: AvatarProps): React.ReactNode;
+    displayName: string;
+};

package/dist/avatar/Avatar.js

@@ -1 +1,2 @@
-import*as s from"react";import{createSafeContext as A}from"../utils/createContext.js";import{skdxPart as I}from"../utils/part.js";import{Primitive as S}from"../utils/primitive.js";import{jsx as l}from"react/jsx-runtime";var[P,p]=A("Avatar"),x=s.forwardRef((a,t)=>{let[r,n]=s.useState("idle");return l(P,{imageLoadingStatus:r,onImageLoadingStatusChange:n,children:l(S.span,{...a,...I("avatar","root",a.className),ref:t})})});x.displayName="Avatar";import*as f from"react";import{skdxPart as L}from"../utils/part.js";import{Primitive as R}from"../utils/primitive.js";import{useCallbackRef as k}from"../utils/useCallbackRef.js";import{jsx as C}from"react/jsx-runtime";var c=f.forwardRef(({onLoadingStatusChange:a=()=>{},src:t,...r},n)=>{let i=p("AvatarImage"),o=k(e=>{a(e),i.onImageLoadingStatusChange(e)});return f.useLayoutEffect(()=>{if(!t){o("error");return}let e=!0,d=new window.Image,g=v=>()=>{e&&o(v)};return o("loading"),d.onload=g("loaded"),d.onerror=g("error"),d.src=t,()=>{e=!1}},[t,o]),i.imageLoadingStatus==="loaded"?C(R.img,{src:t,...r,...L("avatar","image",r.className),ref:n}):null});c.displayName="AvatarImage";import*as m from"react";import{skdxPart as w}from"../utils/part.js";import{Primitive as b}from"../utils/primitive.js";import{jsx as y}from"react/jsx-runtime";var u=m.forwardRef(({delayMs:a,...t},r)=>{let n=p("AvatarFallback"),[i,o]=m.useState(a===void 0);return m.useEffect(()=>{if(a===void 0)return;let e=window.setTimeout(()=>o(!0),a);return()=>window.clearTimeout(e)},[a]),i&&n.imageLoadingStatus!=="loaded"?y(b.span,{...t,...w("avatar","fallback",t.className),ref:r}):null});u.displayName="AvatarFallback";export{x as Avatar,u as AvatarFallback,c as AvatarImage,P as AvatarProvider,p as useAvatarContext};
+'use client';
+import*as I from"react";import{appearanceAttrs as T}from"../utils/appearance.js";import{createSafeContext as V}from"../utils/createContext.js";import{skdxPart as X}from"../utils/part.js";import{Primitive as B}from"../utils/primitive.js";import*as c from"react";import{skdxPart as R}from"../utils/part.js";import{Primitive as S}from"../utils/primitive.js";import{jsx as L}from"react/jsx-runtime";var g=({delayMs:e,ref:a,...t})=>{let r=u("AvatarFallback"),[l,m]=c.useState(e===void 0);return c.useEffect(()=>{if(e===void 0)return;let d=window.setTimeout(()=>m(!0),e);return()=>window.clearTimeout(d)},[e]),l&&r.imageLoadingStatus!=="loaded"?L(S.span,{...t,...R("avatar","fallback",t.className),ref:a}):null};g.displayName="AvatarFallback";import*as h from"react";import{skdxPart as C}from"../utils/part.js";import{Primitive as w}from"../utils/primitive.js";import{useCallbackRef as N}from"../utils/useCallbackRef.js";import{jsx as F}from"react/jsx-runtime";var v=({onLoadingStatusChange:e=()=>{},src:a,srcSet:t,sizes:r,alt:l,asChild:m,children:d,ref:p,...f})=>{let n=u("AvatarImage"),i=N(s=>{n.onImageLoadingStatusChange(s),e(s)});return h.useLayoutEffect(()=>{if(!a&&!t){i("error");return}let s=!0,o=new window.Image,b=k=>()=>{s&&i(k)};return i("loading"),o.onload=b("loaded"),o.onerror=b("error"),t&&(o.srcset=t),r&&(o.sizes=r),a&&(o.src=a),()=>{s=!1}},[a,t,r,i]),n.imageLoadingStatus==="loaded"?F(w.img,{asChild:m,src:a,srcSet:t,sizes:r,alt:n.decorative?"":l??n.label??"",...f,...C("avatar","image",f.className),ref:p,children:m?d:null}):null};v.displayName="AvatarImage";import{Fragment as E,jsx as y,jsxs as J}from"react/jsx-runtime";function D(e){let a=e.trim().split(/\s+/).filter(Boolean);if(a.length===0)return"";let t=a[0].charAt(0),r=a.length>1?a[a.length-1].charAt(0):"";return(t+r).toUpperCase()}function x({src:e,name:a,fallbackDelayMs:t}){return J(E,{children:[e?y(v,{src:e}):null,y(g,{delayMs:t,children:a?D(a):null})]})}import{jsx as A}from"react/jsx-runtime";var[U,u]=V("Avatar"),P=({label:e,decorative:a=!1,src:t,name:r,fallbackDelayMs:l,children:m,ref:d,shape:p,size:f,...n})=>{let[i,s]=I.useState("idle"),o=e??r;return A(U,{imageLoadingStatus:i,onImageLoadingStatusChange:s,label:o,decorative:a,children:A(B.span,{"data-load-status":i,role:o?"img":void 0,"aria-label":o,"aria-hidden":a?!0:void 0,...n,...T({shape:p,size:f},n),...X("avatar","root",n.className),ref:d,children:m??A(x,{src:t,name:r,fallbackDelayMs:l})})})};P.displayName="Avatar";export{P as Avatar,g as AvatarFallback,v as AvatarImage,U as AvatarProvider,u as useAvatarContext};

package/dist/avatar/AvatarAnatomy.d.cts

@@ -0,0 +1,7 @@
+import type { JSX } from 'react';
+/** @internal Derived anatomy: an Image when `src` is given, and a Fallback showing `name`'s initials. */
+export declare function AvatarAnatomy({ src, name, fallbackDelayMs, }: {
+    src?: string | undefined;
+    name?: string | undefined;
+    fallbackDelayMs?: number | undefined;
+}): JSX.Element;

package/dist/avatar/AvatarAnatomy.d.ts

@@ -0,0 +1,7 @@
+import type { JSX } from 'react';
+/** @internal Derived anatomy: an Image when `src` is given, and a Fallback showing `name`'s initials. */
+export declare function AvatarAnatomy({ src, name, fallbackDelayMs, }: {
+    src?: string | undefined;
+    name?: string | undefined;
+    fallbackDelayMs?: number | undefined;
+}): JSX.Element;

package/dist/avatar/AvatarFallback.d.cts

@@ -1,10 +1,8 @@
 import * as React from 'react';
 import type { AvatarFallbackProps } from './types.cjs';
 /**
- * Renders while the sibling `AvatarImage` hasn't finished loading (idle,
- * loading, or errored) — typically initials or a placeholder icon. If
- * `delayMs` is set, rendering is held back for that long to avoid a flash
- * when the image loads quickly. Must be used inside an `Avatar`.
+ * Renders while `AvatarImage` hasn't finished loading (idle, loading, or errored).
+ * `delayMs` prevents flashing on quick loads. Must be inside an `Avatar`.
  *
  * @example
  * ```tsx
@@ -14,4 +12,7 @@ import type { AvatarFallbackProps } from './types.cjs';
  * </Avatar>
  * ```
  */
-export declare const AvatarFallback: React.ForwardRefExoticComponent<Omit<AvatarFallbackProps, "ref"> & React.RefAttributes<HTMLSpanElement>>;
+export declare const AvatarFallback: {
+    ({ delayMs, ref: forwardedRef, ...props }: AvatarFallbackProps): React.ReactNode;
+    displayName: string;
+};

package/dist/avatar/AvatarFallback.d.ts

@@ -1,10 +1,8 @@
 import * as React from 'react';
 import type { AvatarFallbackProps } from './types.js';
 /**
- * Renders while the sibling `AvatarImage` hasn't finished loading (idle,
- * loading, or errored) — typically initials or a placeholder icon. If
- * `delayMs` is set, rendering is held back for that long to avoid a flash
- * when the image loads quickly. Must be used inside an `Avatar`.
+ * Renders while `AvatarImage` hasn't finished loading (idle, loading, or errored).
+ * `delayMs` prevents flashing on quick loads. Must be inside an `Avatar`.
  *
  * @example
  * ```tsx
@@ -14,4 +12,7 @@ import type { AvatarFallbackProps } from './types.js';
  * </Avatar>
  * ```
  */
-export declare const AvatarFallback: React.ForwardRefExoticComponent<Omit<AvatarFallbackProps, "ref"> & React.RefAttributes<HTMLSpanElement>>;
+export declare const AvatarFallback: {
+    ({ delayMs, ref: forwardedRef, ...props }: AvatarFallbackProps): React.ReactNode;
+    displayName: string;
+};

package/dist/avatar/AvatarImage.d.cts

@@ -6,12 +6,20 @@ import type { AvatarImageProps } from './types.cjs';
  * renders nothing while idle, loading, or on error, so a sibling
  * `AvatarFallback` shows through instead. Must be used inside an `Avatar`.
  *
+ * `alt` defaults to the root's `label`, so the avatar announces the same name
+ * loaded as it does while showing its fallback, and is forced to `""` when the
+ * root is `decorative`. It is still worth passing explicitly when the picture
+ * says something the label does not.
+ *
  * @example
  * ```tsx
- * <Avatar>
- *   <AvatarImage src="/user.png" alt="Jane Doe" />
+ * <Avatar label="Jane Doe">
+ *   <AvatarImage src="/user.png" />
  *   <AvatarFallback>JD</AvatarFallback>
  * </Avatar>
  * ```
  */
-export declare const AvatarImage: React.ForwardRefExoticComponent<Omit<AvatarImageProps, "ref"> & React.RefAttributes<HTMLImageElement>>;
+export declare const AvatarImage: {
+    ({ onLoadingStatusChange, src, srcSet, sizes, alt, asChild, children, ref: forwardedRef, ...props }: AvatarImageProps): React.ReactNode;
+    displayName: string;
+};