@skdx/react 0.26.0 → 0.28.0

package/dist/autocomplete/types.d.ts

@@ -1,178 +1,254 @@
 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;
+    /**
+     * Excludes this suggestion from selection and pointer highlight.
+     * @default false
+     */
+    disabled?: boolean;
+}
+/** 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;
     /**
-     * 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;
     /**
-     * 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;
     /**
-     * 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;
     /**
-     * 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;
     /**
-     * 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;
     /**
-     * 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;
     /**
-     * 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;
     /**
-     * Initial open state, for uncontrolled usage.
+     * Initial open state; popup waits for keystroke or trigger if false.
      * @default false
      */
     defaultOpen?: boolean;
     /**
-     * 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;
     /**
-     * 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;
     /**
-     * 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;
     /**
-     * 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;
     /**
-     * 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.
+     * Keeps the first suggestion highlighted as the filtered list changes while open, so Enter always has a target.
+     * @default false
+     */
+    autoHighlight?: boolean;
+    /**
+     * Wraps arrow navigation around list ends; set `false` to clamp. Home/End always jump to an end regardless.
+     * @default true
+     */
+    loop?: boolean;
+    /**
+     * 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;
     /**
-     * Blocks all interaction: the input is natively `disabled`, so it is not
-     * focusable and the popup can never open.
+     * Blocks all interaction; the input is natively disabled and the popup can't open.
      * @default false
      */
     disabled?: boolean;
     /**
-     * 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.
+     * Shows the committed text but blocks changes, while remaining focusable, unlike `disabled`.
      * @default false
      */
     readOnly?: boolean;
     /**
-     * Marks the field as invalid, exposed as `aria-invalid`/`data-invalid` on
-     * `AutocompleteInput`.
+     * Marks the field as invalid, exposed as `aria-invalid`/`data-invalid` on the Input.
      * @default false
      */
     invalid?: boolean;
     /**
-     * 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.
+     * Marks suggestions as in flight; suppresses the suggestion-count announcement that would race an in-progress fetch.
+     * @default false
+     */
+    loading?: boolean;
+    /**
+     * 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;
+    /**
+     * Id of the `<form>` the field submits into; requires `name` to have any effect.
+     * @default undefined — associates with the nearest ancestor `<form>`.
+     */
+    form?: string;
+    /**
+     * 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;
+    /**
+     * 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[];
+    /**
+     * 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;
+    /**
+     * Placeholder for the derived Input; only read while `options` derives the anatomy.
+     * @default undefined
+     */
+    placeholder?: string;
+    /**
+     * 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;
 }
 /** 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'> {
@@ -191,12 +267,9 @@ export interface AutocompletePortalProps extends PortalProps {
     forceMount?: boolean;
 }
 /**
- * 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 {
     /**
@@ -205,22 +278,22 @@ export interface AutocompleteContentProps extends PopperContentProps {
      */
     forceMount?: boolean;
     /**
-     * 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;
     /**
-     * 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;
     /**
-     * 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;
     /**
-     * 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;
@@ -238,9 +311,7 @@ export interface AutocompleteItemProps extends PrimitivePropsWithRef<'div'> {
      */
     disabled?: boolean;
     /**
-     * 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;
@@ -248,3 +319,17 @@ export interface AutocompleteItemProps extends PrimitivePropsWithRef<'div'> {
 /** 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 @@
-"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 strict";var _=Object.create;var g=Object.defineProperty;var $=Object.getOwnPropertyDescriptor;var B=Object.getOwnPropertyNames;var q=Object.getPrototypeOf,G=Object.prototype.hasOwnProperty;var J=(t,a)=>{for(var e in a)g(t,e,{get:a[e],enumerable:!0})},x=(t,a,e,r)=>{if(a&&typeof a=="object"||typeof a=="function")for(let o of B(a))!G.call(t,o)&&o!==e&&g(t,o,{get:()=>a[o],enumerable:!(r=$(a,o))||r.enumerable});return t};var k=(t,a,e)=>(e=t!=null?_(q(t)):{},x(a||!t||!t.__esModule?g(e,"default",{value:t,enumerable:!0}):e,t)),K=t=>x(g({},"__esModule",{value:!0}),t);var Q={};J(Q,{Avatar:()=>I,AvatarFallback:()=>p,AvatarImage:()=>A,AvatarProvider:()=>D,useAvatarContext:()=>c});module.exports=K(Q);var b=k(require("react"),1),E=require("../utils/createContext.cjs"),H=require("../utils/part.cjs"),M=require("../utils/primitive.cjs");var d=k(require("react"),1),L=require("../utils/part.cjs"),P=require("../utils/primitive.cjs");var R=require("react/jsx-runtime"),p=d.forwardRef(({delayMs:t,...a},e)=>{let r=c("AvatarFallback"),[o,u]=d.useState(t===void 0);return d.useEffect(()=>{if(t===void 0)return;let i=window.setTimeout(()=>u(!0),t);return()=>window.clearTimeout(i)},[t]),o&&r.imageLoadingStatus!=="loaded"?(0,R.jsx)(P.Primitive.span,{...a,...(0,L.skdxPart)("avatar","fallback",a.className),ref:e}):null});p.displayName="AvatarFallback";var v=k(require("react"),1),S=require("../utils/part.cjs"),C=require("../utils/primitive.cjs"),F=require("../utils/useCallbackRef.cjs");var N=require("react/jsx-runtime"),A=v.forwardRef(({onLoadingStatusChange:t=()=>{},src:a,srcSet:e,sizes:r,alt:o,children:u,...i},y)=>{let s=c("AvatarImage"),m=(0,F.useCallbackRef)(n=>{t(n),s.onImageLoadingStatusChange(n)});return v.useLayoutEffect(()=>{if(!a){m("error");return}let n=!0,f=new window.Image,w=V=>()=>{n&&m(V)};return m("loading"),f.onload=w("loaded"),f.onerror=w("error"),e&&(f.srcset=e),r&&(f.sizes=r),f.src=a,()=>{n=!1}},[a,e,r,m]),s.imageLoadingStatus==="loaded"?(0,N.jsx)(C.Primitive.img,{src:a,srcSet:e,sizes:r,alt:s.decorative?"":o??s.label??"",...i,...(0,S.skdxPart)("avatar","image",i.className),ref:y}):null});A.displayName="AvatarImage";var l=require("react/jsx-runtime");function O(t){let a=t.trim().split(/\s+/).filter(Boolean);return a.length===0?"":a.length===1?a[0].slice(0,2):`${a[0][0]}${a[a.length-1][0]}`}function T({src:t,name:a,fallbackDelayMs:e}){return(0,l.jsxs)(l.Fragment,{children:[t?(0,l.jsx)(A,{src:t}):null,(0,l.jsx)(p,{delayMs:e,children:a?O(a):null})]})}var h=require("react/jsx-runtime"),[D,c]=(0,E.createSafeContext)("Avatar"),I=b.forwardRef(({label:t,decorative:a=!1,src:e,name:r,fallbackDelayMs:o,children:u,...i},y)=>{let[s,m]=b.useState("idle"),n=t??r;return(0,h.jsx)(D,{imageLoadingStatus:s,onImageLoadingStatusChange:m,label:n,decorative:a,children:(0,h.jsx)(M.Primitive.span,{"data-load-status":s,role:n?"img":void 0,"aria-label":n,"aria-hidden":a?!0:void 0,...i,...(0,H.skdxPart)("avatar","root",i.className),ref:y,children:u??(0,h.jsx)(T,{src:e,name:r,fallbackDelayMs:o})})})});I.displayName="Avatar";0&&(module.exports={Avatar,AvatarFallback,AvatarImage,AvatarProvider,useAvatarContext});

package/dist/avatar/Avatar.d.cts

@@ -7,15 +7,14 @@ export declare const AvatarProvider: {
     displayName: string;
 }, 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>
  * ```

package/dist/avatar/Avatar.d.ts

@@ -7,15 +7,14 @@ export declare const AvatarProvider: {
     displayName: string;
 }, 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>
  * ```

package/dist/avatar/Avatar.js

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

package/dist/avatar/AvatarAnatomy.d.cts

@@ -0,0 +1,11 @@
+/**
+ * The anatomy an {@link Avatar} draws when given no children: an Image when
+ * `src` is given, and a Fallback showing `name`'s initials.
+ *
+ * @internal
+ */
+export declare function AvatarAnatomy({ src, name, fallbackDelayMs, }: {
+    src?: string;
+    name?: string;
+    fallbackDelayMs?: number;
+}): import("react").JSX.Element;

package/dist/avatar/AvatarAnatomy.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The anatomy an {@link Avatar} draws when given no children: an Image when
+ * `src` is given, and a Fallback showing `name`'s initials.
+ *
+ * @internal
+ */
+export declare function AvatarAnatomy({ src, name, fallbackDelayMs, }: {
+    src?: string;
+    name?: string;
+    fallbackDelayMs?: number;
+}): import("react").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

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

package/dist/avatar/AvatarImage.d.cts

@@ -6,10 +6,15 @@ 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>
  * ```

package/dist/avatar/AvatarImage.d.ts

@@ -6,10 +6,15 @@ import type { AvatarImageProps } from './types.js';
  * 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>
  * ```

package/dist/avatar/index.d.cts

@@ -1,4 +1,2 @@
-export * from './Avatar.cjs';
-export { AvatarImage } from './AvatarImage.cjs';
-export { AvatarFallback } from './AvatarFallback.cjs';
-export type { AvatarProps, AvatarImageProps, AvatarFallbackProps } from './types.cjs';
+export { Avatar } from './Avatar.cjs';
+export type { AvatarProps } from './types.cjs';

package/dist/avatar/index.d.ts

@@ -1,4 +1,2 @@
-export * from './Avatar.js';
-export { AvatarImage } from './AvatarImage.js';
-export { AvatarFallback } from './AvatarFallback.js';
-export type { AvatarProps, AvatarImageProps, AvatarFallbackProps } from './types.js';
+export { Avatar } from './Avatar.js';
+export type { AvatarProps } from './types.js';

package/dist/avatar/primitives.d.cts

@@ -0,0 +1,17 @@
+/**
+ * `Avatar`, `AvatarImage`, and `AvatarFallback` primitives.
+ *
+ * @example
+ * ```tsx
+ * import { Avatar, AvatarFallback, AvatarImage } from '@skdx/react/primitives/avatar';
+ *
+ * <Avatar label="Jane Doe">
+ *   <AvatarImage src="/user.png" />
+ *   <AvatarFallback delayMs={300}>JD</AvatarFallback>
+ * </Avatar>
+ * ```
+ */
+export { Avatar } from './Avatar.cjs';
+export { AvatarImage } from './AvatarImage.cjs';
+export { AvatarFallback } from './AvatarFallback.cjs';
+export type { AvatarProps, AvatarImageProps, AvatarFallbackProps } from './types.cjs';

package/dist/avatar/primitives.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `Avatar`, `AvatarImage`, and `AvatarFallback` primitives.
+ *
+ * @example
+ * ```tsx
+ * import { Avatar, AvatarFallback, AvatarImage } from '@skdx/react/primitives/avatar';
+ *
+ * <Avatar label="Jane Doe">
+ *   <AvatarImage src="/user.png" />
+ *   <AvatarFallback delayMs={300}>JD</AvatarFallback>
+ * </Avatar>
+ * ```
+ */
+export { Avatar } from './Avatar.js';
+export { AvatarImage } from './AvatarImage.js';
+export { AvatarFallback } from './AvatarFallback.js';
+export type { AvatarProps, AvatarImageProps, AvatarFallbackProps } from './types.js';