@skdx/react 0.26.0 → 0.28.0

package/dist/listbox/types.d.cts

@@ -1,4 +1,43 @@
+import type * as React from 'react';
 import type { PrimitivePropsWithRef } from '../utils/primitive.cjs';
+/** One option for the {@link ListboxProps.options} recipe prop — a flat entry rendered as a `ListboxItem`. */
+export interface ListboxOption {
+    /** Unique identifier committed to the listbox's value when this option is chosen. */
+    value: string;
+    /**
+     * Text shown for the option and matched by typeahead.
+     * @default undefined — falls back to `value`.
+     */
+    label?: string;
+    /**
+     * Excludes this option from selection and from keyboard/typeahead navigation.
+     * @default false
+     */
+    disabled?: boolean;
+}
+/** A labeled group of {@link ListboxOption}s for {@link ListboxProps.options} — grouping is data, never a wrapper component. */
+export interface ListboxOptionGroup {
+    /** Heading rendered as a `ListboxLabel` above this group's options. */
+    label: string;
+    /** The options belonging to this group. */
+    options: ListboxOption[];
+}
+/** One entry of {@link ListboxProps.options}: a flat option, or a labeled group of them. */
+export type ListboxOptionOrGroup = ListboxOption | ListboxOptionGroup;
+/**
+ * Event detail on selection change from arrow key, typeahead, click, etc.
+ * `reason` distinguishes the interaction. Includes `previousValue` for controlled components.
+ */
+export interface ListboxValueChangeDetail {
+    /** The whole selection after the change, not the single option that was toggled — see `selectedValue`. */
+    value: string[];
+    /** The selection held before this change, or `null` when there was none. */
+    previousValue: string[] | null;
+    /** What drove the change. */
+    reason: 'keyboard' | 'pointer' | 'programmatic';
+    /** The first selected value, or `null` when nothing is selected. */
+    selectedValue: string | null;
+}
 /** @internal Shared state distributed from {@link Listbox} to its parts via context. Not part of the public API. */
 export interface ListboxContextValue {
     /** Whether more than one option can be selected. */
@@ -7,48 +46,89 @@ export interface ListboxContextValue {
     selectedValues: string[];
     /** Whether one option value is currently selected. */
     isSelected: (value: string) => boolean;
-    /** Commits an option: replaces the selection, or toggles it within it when `multiple`. */
-    selectItem: (value: string) => void;
+    /**
+     * Commits option: replaces selection or toggles in `multiple`.
+     * Records selection anchor for Shift+Space range. `reason` names the interaction.
+     */
+    selectItem: (value: string, reason: ListboxValueChangeDetail['reason']) => void;
     /** Whether the whole list is disabled, which disables every option in it. */
     disabled: boolean;
     /** The option value holding the list's single tab stop. */
     activeValue: string | null;
     setActiveValue: (value: string | null) => void;
+    /** Whether moving the pointer over an option moves roving focus onto it. */
+    focusOnHover: boolean;
 }
 /** Props for the {@link Listbox} root. */
 export interface ListboxProps extends Omit<PrimitivePropsWithRef<'div'>, 'onChange' | 'defaultValue'> {
     /**
-     * Selected option's value, for controlled usage — a `string[]` when
-     * `multiple`, a `string` otherwise. Pair with `onValueChange`.
-     * @default undefined — uncontrolled, tracks its own selected value internally.
+     * Selected value for controlled usage: `string` or `string[]` (lenient in).
+     * Single-select with multiple values throws in dev. Pair with `onValueChange`.
+     * @default undefined — uncontrolled, tracks selected value internally.
      */
     value?: string | string[];
     /**
-     * Initially selected option's value, for uncontrolled usage. Same shape as
-     * `value`: a `string[]` when `multiple`.
+     * Initially selected option's value, for uncontrolled usage — the same bare
+     * `string` or `string[]` shapes `value` accepts, under either cardinality.
      * @default undefined — no option selected until the user picks one.
      */
     defaultValue?: string | string[];
     /**
-     * Fires with the new value whenever the selection changes, controlled or
-     * not — the whole `string[]` when `multiple`, not the toggled option.
+     * Fires on selection change (controlled or uncontrolled) with whole selection,
+     * `selectedValue`, `previousValue`, and `reason`. Unchanged selection emits nothing.
      * @default undefined — no-op if omitted.
      */
-    onValueChange?: (value: string | string[]) => void;
+    onValueChange?: (detail: ListboxValueChangeDetail) => void;
     /**
-     * Allows more than one option to be selected: `value` becomes a `string[]`,
-     * the list gains `aria-multiselectable="true"`, and choosing an option
-     * toggles it instead of replacing the selection.
+     * Allow multiple selection: `value` becomes `string[]`, list gets `aria-multiselectable="true"`,
+     * choosing toggles instead of replacing.
      * @default false
      */
     multiple?: boolean;
     /**
-     * Disables every option in the list at once, exposed as `aria-disabled` and
-     * `data-disabled` on the list and on each option. An individual
-     * `ListboxItem` can still be disabled on its own.
+     * Disables all options: `aria-disabled`/`data-disabled` on list and items.
+     * Individual items can disable themselves too.
      * @default false
      */
     disabled?: boolean;
+    /**
+     * Control+A selects/clears all enabled options (multiple only). Defaults to true
+     * (normative shortcut); off to avoid text-selection conflict or expensive fetches.
+     * Inert in single-select.
+     * @default true
+     */
+    allowSelectAll?: boolean;
+    /**
+     * Layout axis: vertical (ArrowUp/Down) or horizontal (ArrowLeft/Right).
+     * Affects selection-extending keys; position keys (Home/End, Control+A) unaffected.
+     * @default 'vertical'
+     */
+    orientation?: 'horizontal' | 'vertical';
+    /**
+     * Moves roving focus on pointer hover (not selection). Off by default
+     * to avoid stealing focus from page. Never focuses disabled items.
+     * @default false
+     */
+    focusOnHover?: boolean;
+    /**
+     * Prevent deselecting the last item (multiple only). Also refuses Control+A clear.
+     * Doesn't create initial selection; empty list stays empty.
+     * @default false
+     */
+    disallowEmptySelection?: boolean;
+    /**
+     * Auto-render options as ListboxItems. Ignored when children declare their own.
+     * @default undefined — render items yourself via children.
+     */
+    options?: ListboxOptionOrGroup[];
+    /**
+     * Customize derived option rendering. Receives option and selected state.
+     * Only read while deriving anatomy.
+     * @default undefined — renders `option.label ?? option.value`.
+     */
+    renderOption?: (option: ListboxOption, state: {
+        selected: boolean;
+    }) => React.ReactNode;
 }
 /** @internal Shared state distributed from {@link ListboxItem} to its indicator via context. Not part of the public API. */
 export interface ListboxItemContextValue {
@@ -66,13 +146,34 @@ export interface ListboxItemProps extends PrimitivePropsWithRef<'div'> {
      */
     disabled?: boolean;
     /**
-     * Text typeahead matches this option against, published as `data-text-value`.
-     * Needed whenever the option renders more than its label — a
-     * {@link ListboxItemIndicator} glyph, an icon, a secondary line — since the
-     * fallback is the option's whole rendered text content.
-     * @default undefined — falls back to the option's rendered text content.
+     * Text for typeahead matching, published as `data-text-value`.
+     * Needed when option has more than label; fallback is rendered text content.
+     * @default undefined — falls back to rendered text content.
      */
     textValue?: string;
+    /**
+     * This option's 1-based position in the *whole* option set, and the size of
+     * that set, published as `aria-posinset` / `aria-setsize`.
+     *
+     * Only needed when the rendered options are a window onto a longer list —
+     * a virtualized listbox, or one that pages in more rows as the user scrolls.
+     * Without them a screen reader counts the DOM and announces "3 of 20" for
+     * row 4,003 of a million, which is both wrong and unrecoverable. This is the
+     * one piece of virtualized-listbox accessibility that belongs inside a
+     * headless package rather than in the consumer's scroll code: the consumer
+     * owns the windowing, but only the option can carry the attribute.
+     *
+     * Set both or neither — `aria-posinset` without `aria-setsize` says "item 4
+     * of an unknown number", which is worse than the DOM count it replaces.
+     * @default undefined — the option set is exactly what is rendered, and the
+     * browser's own count is correct.
+     */
+    posInSet?: number;
+    /**
+     * Size of the full option set this option belongs to. See {@link ListboxItemProps.posInSet}.
+     * @default undefined — the option set is exactly what is rendered, and the browser's own count is correct.
+     */
+    setSize?: number;
 }
 /** Props for {@link ListboxItemIndicator}, shown inside a {@link ListboxItem} while that option is selected. */
 export interface ListboxItemIndicatorProps extends PrimitivePropsWithRef<'span'> {

package/dist/listbox/types.d.ts

@@ -1,4 +1,43 @@
+import type * as React from 'react';
 import type { PrimitivePropsWithRef } from '../utils/primitive.js';
+/** One option for the {@link ListboxProps.options} recipe prop — a flat entry rendered as a `ListboxItem`. */
+export interface ListboxOption {
+    /** Unique identifier committed to the listbox's value when this option is chosen. */
+    value: string;
+    /**
+     * Text shown for the option and matched by typeahead.
+     * @default undefined — falls back to `value`.
+     */
+    label?: string;
+    /**
+     * Excludes this option from selection and from keyboard/typeahead navigation.
+     * @default false
+     */
+    disabled?: boolean;
+}
+/** A labeled group of {@link ListboxOption}s for {@link ListboxProps.options} — grouping is data, never a wrapper component. */
+export interface ListboxOptionGroup {
+    /** Heading rendered as a `ListboxLabel` above this group's options. */
+    label: string;
+    /** The options belonging to this group. */
+    options: ListboxOption[];
+}
+/** One entry of {@link ListboxProps.options}: a flat option, or a labeled group of them. */
+export type ListboxOptionOrGroup = ListboxOption | ListboxOptionGroup;
+/**
+ * Event detail on selection change from arrow key, typeahead, click, etc.
+ * `reason` distinguishes the interaction. Includes `previousValue` for controlled components.
+ */
+export interface ListboxValueChangeDetail {
+    /** The whole selection after the change, not the single option that was toggled — see `selectedValue`. */
+    value: string[];
+    /** The selection held before this change, or `null` when there was none. */
+    previousValue: string[] | null;
+    /** What drove the change. */
+    reason: 'keyboard' | 'pointer' | 'programmatic';
+    /** The first selected value, or `null` when nothing is selected. */
+    selectedValue: string | null;
+}
 /** @internal Shared state distributed from {@link Listbox} to its parts via context. Not part of the public API. */
 export interface ListboxContextValue {
     /** Whether more than one option can be selected. */
@@ -7,48 +46,89 @@ export interface ListboxContextValue {
     selectedValues: string[];
     /** Whether one option value is currently selected. */
     isSelected: (value: string) => boolean;
-    /** Commits an option: replaces the selection, or toggles it within it when `multiple`. */
-    selectItem: (value: string) => void;
+    /**
+     * Commits option: replaces selection or toggles in `multiple`.
+     * Records selection anchor for Shift+Space range. `reason` names the interaction.
+     */
+    selectItem: (value: string, reason: ListboxValueChangeDetail['reason']) => void;
     /** Whether the whole list is disabled, which disables every option in it. */
     disabled: boolean;
     /** The option value holding the list's single tab stop. */
     activeValue: string | null;
     setActiveValue: (value: string | null) => void;
+    /** Whether moving the pointer over an option moves roving focus onto it. */
+    focusOnHover: boolean;
 }
 /** Props for the {@link Listbox} root. */
 export interface ListboxProps extends Omit<PrimitivePropsWithRef<'div'>, 'onChange' | 'defaultValue'> {
     /**
-     * Selected option's value, for controlled usage — a `string[]` when
-     * `multiple`, a `string` otherwise. Pair with `onValueChange`.
-     * @default undefined — uncontrolled, tracks its own selected value internally.
+     * Selected value for controlled usage: `string` or `string[]` (lenient in).
+     * Single-select with multiple values throws in dev. Pair with `onValueChange`.
+     * @default undefined — uncontrolled, tracks selected value internally.
      */
     value?: string | string[];
     /**
-     * Initially selected option's value, for uncontrolled usage. Same shape as
-     * `value`: a `string[]` when `multiple`.
+     * Initially selected option's value, for uncontrolled usage — the same bare
+     * `string` or `string[]` shapes `value` accepts, under either cardinality.
      * @default undefined — no option selected until the user picks one.
      */
     defaultValue?: string | string[];
     /**
-     * Fires with the new value whenever the selection changes, controlled or
-     * not — the whole `string[]` when `multiple`, not the toggled option.
+     * Fires on selection change (controlled or uncontrolled) with whole selection,
+     * `selectedValue`, `previousValue`, and `reason`. Unchanged selection emits nothing.
      * @default undefined — no-op if omitted.
      */
-    onValueChange?: (value: string | string[]) => void;
+    onValueChange?: (detail: ListboxValueChangeDetail) => void;
     /**
-     * Allows more than one option to be selected: `value` becomes a `string[]`,
-     * the list gains `aria-multiselectable="true"`, and choosing an option
-     * toggles it instead of replacing the selection.
+     * Allow multiple selection: `value` becomes `string[]`, list gets `aria-multiselectable="true"`,
+     * choosing toggles instead of replacing.
      * @default false
      */
     multiple?: boolean;
     /**
-     * Disables every option in the list at once, exposed as `aria-disabled` and
-     * `data-disabled` on the list and on each option. An individual
-     * `ListboxItem` can still be disabled on its own.
+     * Disables all options: `aria-disabled`/`data-disabled` on list and items.
+     * Individual items can disable themselves too.
      * @default false
      */
     disabled?: boolean;
+    /**
+     * Control+A selects/clears all enabled options (multiple only). Defaults to true
+     * (normative shortcut); off to avoid text-selection conflict or expensive fetches.
+     * Inert in single-select.
+     * @default true
+     */
+    allowSelectAll?: boolean;
+    /**
+     * Layout axis: vertical (ArrowUp/Down) or horizontal (ArrowLeft/Right).
+     * Affects selection-extending keys; position keys (Home/End, Control+A) unaffected.
+     * @default 'vertical'
+     */
+    orientation?: 'horizontal' | 'vertical';
+    /**
+     * Moves roving focus on pointer hover (not selection). Off by default
+     * to avoid stealing focus from page. Never focuses disabled items.
+     * @default false
+     */
+    focusOnHover?: boolean;
+    /**
+     * Prevent deselecting the last item (multiple only). Also refuses Control+A clear.
+     * Doesn't create initial selection; empty list stays empty.
+     * @default false
+     */
+    disallowEmptySelection?: boolean;
+    /**
+     * Auto-render options as ListboxItems. Ignored when children declare their own.
+     * @default undefined — render items yourself via children.
+     */
+    options?: ListboxOptionOrGroup[];
+    /**
+     * Customize derived option rendering. Receives option and selected state.
+     * Only read while deriving anatomy.
+     * @default undefined — renders `option.label ?? option.value`.
+     */
+    renderOption?: (option: ListboxOption, state: {
+        selected: boolean;
+    }) => React.ReactNode;
 }
 /** @internal Shared state distributed from {@link ListboxItem} to its indicator via context. Not part of the public API. */
 export interface ListboxItemContextValue {
@@ -66,13 +146,34 @@ export interface ListboxItemProps extends PrimitivePropsWithRef<'div'> {
      */
     disabled?: boolean;
     /**
-     * Text typeahead matches this option against, published as `data-text-value`.
-     * Needed whenever the option renders more than its label — a
-     * {@link ListboxItemIndicator} glyph, an icon, a secondary line — since the
-     * fallback is the option's whole rendered text content.
-     * @default undefined — falls back to the option's rendered text content.
+     * Text for typeahead matching, published as `data-text-value`.
+     * Needed when option has more than label; fallback is rendered text content.
+     * @default undefined — falls back to rendered text content.
      */
     textValue?: string;
+    /**
+     * This option's 1-based position in the *whole* option set, and the size of
+     * that set, published as `aria-posinset` / `aria-setsize`.
+     *
+     * Only needed when the rendered options are a window onto a longer list —
+     * a virtualized listbox, or one that pages in more rows as the user scrolls.
+     * Without them a screen reader counts the DOM and announces "3 of 20" for
+     * row 4,003 of a million, which is both wrong and unrecoverable. This is the
+     * one piece of virtualized-listbox accessibility that belongs inside a
+     * headless package rather than in the consumer's scroll code: the consumer
+     * owns the windowing, but only the option can carry the attribute.
+     *
+     * Set both or neither — `aria-posinset` without `aria-setsize` says "item 4
+     * of an unknown number", which is worse than the DOM count it replaces.
+     * @default undefined — the option set is exactly what is rendered, and the
+     * browser's own count is correct.
+     */
+    posInSet?: number;
+    /**
+     * Size of the full option set this option belongs to. See {@link ListboxItemProps.posInSet}.
+     * @default undefined — the option set is exactly what is rendered, and the browser's own count is correct.
+     */
+    setSize?: number;
 }
 /** Props for {@link ListboxItemIndicator}, shown inside a {@link ListboxItem} while that option is selected. */
 export interface ListboxItemIndicatorProps extends PrimitivePropsWithRef<'span'> {

package/dist/loading-overlay/LoadingOverlay.cjs

@@ -1 +1 @@
-"use strict";var K=Object.create;var m=Object.defineProperty;var Q=Object.getOwnPropertyDescriptor;var U=Object.getOwnPropertyNames;var W=Object.getPrototypeOf,X=Object.prototype.hasOwnProperty;var Y=(e,r)=>{for(var o in r)m(e,o,{get:r[o],enumerable:!0})},b=(e,r,o,a)=>{if(r&&typeof r=="object"||typeof r=="function")for(let i of U(r))!X.call(e,i)&&i!==o&&m(e,i,{get:()=>r[i],enumerable:!(a=Q(r,i))||a.enumerable});return e};var v=(e,r,o)=>(o=e!=null?K(W(e)):{},b(r||!e||!e.__esModule?m(o,"default",{value:e,enumerable:!0}):o,e)),Z=e=>b(m({},"__esModule",{value:!0}),e);var _={};Y(_,{LoadingOverlay:()=>N,LoadingOverlayBackdrop:()=>y,LoadingOverlayContent:()=>g,LoadingOverlayProvider:()=>h,useLoadingOverlayContext:()=>s});module.exports=Z(_);var n=v(require("react"),1),C=require("../utils/createContext.cjs"),R=require("../utils/liveAnnouncer.cjs"),x=require("../utils/part.cjs"),k=require("../utils/primitive.cjs"),B=require("../utils/useBodyScrollLock.cjs"),w=require("../utils/useCallbackRef.cjs"),E=require("../utils/useControllableState.cjs"),l=require("react/jsx-runtime"),[h,s]=(0,C.createSafeContext)("LoadingOverlay"),N=n.forwardRef(({visible:e,defaultVisible:r=!1,onVisibleChange:o,fullScreen:a=!1,loadingLabel:i="Loading",delay:d=0,children:F,...L},G)=>{let[f=!1]=(0,E.useControllableState)({prop:e,defaultProp:r}),[I,u]=n.useState(!1);n.useEffect(()=>{if(!f||d<=0)return;let J=window.setTimeout(()=>u(!0),d);return()=>{window.clearTimeout(J),u(!1)}},[f,d]);let t=f&&(d<=0||I),O=(0,w.useCallbackRef)(o),P=n.useRef(t);return n.useEffect(()=>{P.current!==t&&(P.current=t,O(t))},[t,O]),(0,B.useBodyScrollLock)(t&&a),(0,l.jsxs)(h,{visible:t,fullScreen:a,loadingLabel:i,children:[(0,l.jsx)(k.Primitive.div,{"aria-busy":t||void 0,inert:t,"data-state":t?"visible":"hidden","data-full-screen":a?"":void 0,...L,...(0,x.skdxPart)("loading-overlay","root",L.className),ref:G,children:F}),(0,l.jsx)(R.LiveAnnouncer,{message:t?i:""})]})});N.displayName="LoadingOverlay";var S=v(require("react"),1),T=require("../utils/part.cjs"),D=require("../utils/presence.cjs"),V=require("../utils/primitive.cjs");var c=require("react/jsx-runtime"),y=S.forwardRef((e,r)=>{let{visible:o,fullScreen:a}=s("LoadingOverlayBackdrop");return(0,c.jsx)(D.Presence,{present:o,children:(0,c.jsx)(V.Primitive.div,{"aria-hidden":!0,"data-state":o?"visible":"hidden","data-full-screen":a?"":void 0,...e,...(0,T.skdxPart)("loading-overlay","backdrop",e.className),ref:r})})});y.displayName="LoadingOverlayBackdrop";var H=v(require("react"),1),M=require("../spinner/Spinner.cjs"),q=require("../utils/part.cjs"),A=require("../utils/presence.cjs"),z=require("../utils/primitive.cjs");var p=require("react/jsx-runtime"),g=H.forwardRef(({children:e,...r},o)=>{let{visible:a,fullScreen:i,loadingLabel:d}=s("LoadingOverlayContent");return(0,p.jsx)(A.Presence,{present:a,children:(0,p.jsx)(z.Primitive.div,{"data-state":a?"visible":"hidden","data-full-screen":i?"":void 0,...r,...(0,q.skdxPart)("loading-overlay","content",r.className),ref:o,children:e??(0,p.jsx)(M.Spinner,{label:d})})})});g.displayName="LoadingOverlayContent";0&&(module.exports={LoadingOverlay,LoadingOverlayBackdrop,LoadingOverlayContent,LoadingOverlayProvider,useLoadingOverlayContext});
+"use strict";var U=Object.create;var p=Object.defineProperty;var W=Object.getOwnPropertyDescriptor;var X=Object.getOwnPropertyNames;var Z=Object.getPrototypeOf,$=Object.prototype.hasOwnProperty;var j=(e,r)=>{for(var o in r)p(e,o,{get:r[o],enumerable:!0})},S=(e,r,o,i)=>{if(r&&typeof r=="object"||typeof r=="function")for(let n of X(r))!$.call(e,n)&&n!==o&&p(e,n,{get:()=>r[n],enumerable:!(i=W(r,n))||i.enumerable});return e};var L=(e,r,o)=>(o=e!=null?U(Z(e)):{},S(r||!e||!e.__esModule?p(o,"default",{value:e,enumerable:!0}):o,e)),ee=e=>S(p({},"__esModule",{value:!0}),e);var oe={};j(oe,{LoadingOverlay:()=>C,LoadingOverlayBackdrop:()=>v,LoadingOverlayContent:()=>y,LoadingOverlayProvider:()=>G,LoadingOverlayRoot:()=>P,useLoadingOverlayContext:()=>m});module.exports=ee(oe);var a=L(require("react"),1),q=require("../utils/createContext.cjs"),f=require("../utils/liveAnnouncer.cjs"),R=require("../utils/part.cjs"),Y=require("../utils/primitive.cjs"),_=require("../utils/useBodyScrollLock.cjs"),z=require("../utils/useCallbackRef.cjs"),F=require("../utils/useControllableState.cjs");var w=L(require("react"),1),h=require("../utils/part.cjs"),B=require("../utils/presence.cjs"),N=require("../utils/primitive.cjs");var O=require("react/jsx-runtime"),v=w.forwardRef((e,r)=>{let{visible:o,fullScreen:i}=m("LoadingOverlayBackdrop");return(0,O.jsx)(B.Presence,{present:o,children:(0,O.jsx)(N.Primitive.div,{"aria-hidden":!0,"data-state":o?"visible":"hidden","data-full-screen":i?"":void 0,...e,...(0,h.skdxPart)("loading-overlay","backdrop",e.className),ref:r})})});v.displayName="LoadingOverlayBackdrop";var T=L(require("react"),1),D=require("../spinner/Spinner.cjs"),V=require("../utils/part.cjs"),A=require("../utils/presence.cjs"),H=require("../utils/primitive.cjs");var c=require("react/jsx-runtime"),y=T.forwardRef(({children:e,...r},o)=>{let{visible:i,fullScreen:n,loadingLabel:l}=m("LoadingOverlayContent");return(0,c.jsx)(A.Presence,{present:i,children:(0,c.jsx)(H.Primitive.div,{"data-state":i?"visible":"hidden","data-full-screen":n?"":void 0,...r,...(0,V.skdxPart)("loading-overlay","content",r.className),ref:o,children:e??(0,c.jsx)(D.Spinner,{label:l})})})});y.displayName="LoadingOverlayContent";var s=require("react/jsx-runtime"),M=()=>(0,s.jsxs)(s.Fragment,{children:[(0,s.jsx)(v,{}),(0,s.jsx)(y,{})]});var d=require("react/jsx-runtime"),[G,m]=(0,q.createSafeContext)("LoadingOverlay"),re={display:"contents"},P=a.forwardRef(({visible:e,onVisibleChange:r,fullScreen:o=!1,loadingLabel:i="Loading",loadedLabel:n,delay:l=0,children:I,...x},J)=>{let[u=!1]=(0,F.useControllableState)({prop:e}),[K,b]=a.useState(!1);a.useEffect(()=>{if(!u||l<=0)return;let Q=window.setTimeout(()=>b(!0),l);return()=>{window.clearTimeout(Q),b(!1)}},[u,l]);let t=u&&(l<=0||K),k=(0,z.useCallbackRef)(r),E=a.useRef(t);a.useEffect(()=>{E.current!==t&&(E.current=t,k(t))},[t,k]);let g=a.useRef(!1);return a.useEffect(()=>{if(t){g.current=!0,(0,f.announce)(i);return}g.current&&(g.current=!1,n?(0,f.announce)(n):(0,f.clearAnnouncements)("polite"))},[t,i,n]),(0,_.useBodyScrollLock)(t&&o),(0,d.jsx)(G,{visible:t,fullScreen:o,loadingLabel:i,children:(0,d.jsx)(Y.Primitive.div,{"aria-busy":t||void 0,"data-state":t?"visible":"hidden","data-full-screen":o?"":void 0,...x,...(0,R.skdxPart)("loading-overlay","root",x.className),ref:J,children:(0,d.jsx)("div",{inert:t,style:re,...(0,R.skdxPart)("loading-overlay","covered"),children:I})})})});P.displayName="LoadingOverlayRoot";var C=a.forwardRef(({children:e,...r},o)=>(0,d.jsxs)(P,{...r,ref:o,children:[e,(0,d.jsx)(M,{})]}));C.displayName="LoadingOverlay";0&&(module.exports={LoadingOverlay,LoadingOverlayBackdrop,LoadingOverlayContent,LoadingOverlayProvider,LoadingOverlayRoot,useLoadingOverlayContext});

package/dist/loading-overlay/LoadingOverlay.d.cts

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import type { LoadingOverlayContextValue, LoadingOverlayProps } from './types.cjs';
+import type { LoadingOverlayContextValue, LoadingOverlayProps, LoadingOverlayRootProps } from './types.cjs';
 export declare const LoadingOverlayProvider: {
     (props: LoadingOverlayContextValue & {
         children: React.ReactNode;
@@ -8,20 +8,28 @@ export declare const LoadingOverlayProvider: {
 }, useLoadingOverlayContext: (consumerName: string) => LoadingOverlayContextValue;
 /**
  * Root of a loading overlay: wraps the content being covered, owns the
- * visibility (`visible`/`defaultVisible`/`onVisibleChange`) and hands it to
+ * visibility (`visible`/`onVisibleChange`) and hands it to
  * `LoadingOverlayBackdrop` and `LoadingOverlayContent` via context. Renders a
  * plain `<div>` — give it `position: relative` and the backdrop covers exactly
  * this box; set `fullScreen` and it covers the viewport instead.
  *
- * While visible the root is `aria-busy="true"` and carries the `inert`
- * attribute, so the pointer and the tab sequence both stop at the overlay
- * rather than walking into the controls it is hiding. Deliberately **not** a
- * focus trap: this is not a dialog, there is nothing inside to focus and
- * nothing to dismiss, so trapping would strand the keyboard on a spinner.
- * Because `inert` also takes the subtree out of the accessibility tree, the
- * announcement is made through the process-wide live region (see
- * `LiveAnnouncer`) rather than from the `Spinner` inside — a `role="status"`
- * in an inert subtree announces nothing.
+ * While visible the root is `aria-busy="true"` and the `covered` wrapper it
+ * renders inside itself carries the `inert` attribute, so the pointer and the
+ * tab sequence both stop at the overlay rather than walking into the controls
+ * it is hiding. Deliberately **not** a focus trap: this is not a dialog, there
+ * is nothing inside to focus and nothing to dismiss, so trapping would strand
+ * the keyboard on a spinner.
+ *
+ * The two attributes are on two elements on purpose. `inert` takes its subtree
+ * out of the accessibility tree, so `aria-busy` beside it would be removed too
+ * and the busy state would be published to nobody — the component would be
+ * silent about the one thing it is for. It is the same reasoning that puts the
+ * announcement through the process-wide live region (see `announce`)
+ * rather than in a `Spinner` inside the subtree, where a `role="status"`
+ * announces nothing. `loadedLabel` announces the *end* of the work the same
+ * way, and where it is omitted the overlay still clears its own message on
+ * hide, so the next identical `loadingLabel` is a change the announcer will
+ * publish rather than a duplicate it skips.
  *
  * `delay` exists for the same reason `Tooltip` has one: a request that
  * resolves in 80ms should never paint a spinner. The timer is cancelled when
@@ -30,12 +38,42 @@ export declare const LoadingOverlayProvider: {
  * `data-state` is `"visible"`/`"hidden"` and reflects the *effective*
  * visibility, i.e. after `delay`.
  *
+ * Renders `children` verbatim inside the `covered` wrapper —
+ * {@link LoadingOverlay} (the recipe, below) is this root with the `LoadingOverlayBackdrop`
+ * and `LoadingOverlayContent` derived after them.
+ *
  * @example
  * ```tsx
- * <LoadingOverlay visible={isFetching} delay={150} loadingLabel="Loading invoices">
+ * import { LoadingOverlayBackdrop, LoadingOverlayContent, LoadingOverlayRoot } from '@skdx/react/primitives/loading-overlay';
+ *
+ * <LoadingOverlayRoot visible={isFetching} delay={150} loadingLabel="Loading invoices">
  *   <InvoiceTable />
  *   <LoadingOverlayBackdrop />
- *   <LoadingOverlayContent />
+ *   <LoadingOverlayContent>
+ *     <ProgressBar value={percent} />
+ *   </LoadingOverlayContent>
+ * </LoadingOverlayRoot>
+ * ```
+ */
+export declare const LoadingOverlayRoot: React.ForwardRefExoticComponent<Omit<LoadingOverlayRootProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+/**
+ * A loading overlay over the content it covers.
+ *
+ * Always draws the derived anatomy — the `LoadingOverlayBackdrop` scrim and the `LoadingOverlayContent`
+ * layer with the library's `Spinner`, labelled from `loadingLabel` — after
+ * `children`, which is the content being covered. Never a switch: this
+ * component does not inspect what it was given. Replace the indicator by
+ * composing {@link LoadingOverlayRoot} from
+ * `@skdx/react/primitives/loading-overlay`.
+ *
+ * Everything the root owns still applies: `visible`/`onVisibleChange`, the
+ * `delay` window, `fullScreen` with its body-scroll lock, the `inert` covered
+ * wrapper, and the polite `loadingLabel`/`loadedLabel` announcements.
+ *
+ * @example
+ * ```tsx
+ * <LoadingOverlay visible={isFetching} delay={150} loadingLabel="Loading invoices">
+ *   <InvoiceTable />
  * </LoadingOverlay>
  * ```
  */

package/dist/loading-overlay/LoadingOverlay.d.ts

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import type { LoadingOverlayContextValue, LoadingOverlayProps } from './types.js';
+import type { LoadingOverlayContextValue, LoadingOverlayProps, LoadingOverlayRootProps } from './types.js';
 export declare const LoadingOverlayProvider: {
     (props: LoadingOverlayContextValue & {
         children: React.ReactNode;
@@ -8,20 +8,28 @@ export declare const LoadingOverlayProvider: {
 }, useLoadingOverlayContext: (consumerName: string) => LoadingOverlayContextValue;
 /**
  * Root of a loading overlay: wraps the content being covered, owns the
- * visibility (`visible`/`defaultVisible`/`onVisibleChange`) and hands it to
+ * visibility (`visible`/`onVisibleChange`) and hands it to
  * `LoadingOverlayBackdrop` and `LoadingOverlayContent` via context. Renders a
  * plain `<div>` — give it `position: relative` and the backdrop covers exactly
  * this box; set `fullScreen` and it covers the viewport instead.
  *
- * While visible the root is `aria-busy="true"` and carries the `inert`
- * attribute, so the pointer and the tab sequence both stop at the overlay
- * rather than walking into the controls it is hiding. Deliberately **not** a
- * focus trap: this is not a dialog, there is nothing inside to focus and
- * nothing to dismiss, so trapping would strand the keyboard on a spinner.
- * Because `inert` also takes the subtree out of the accessibility tree, the
- * announcement is made through the process-wide live region (see
- * `LiveAnnouncer`) rather than from the `Spinner` inside — a `role="status"`
- * in an inert subtree announces nothing.
+ * While visible the root is `aria-busy="true"` and the `covered` wrapper it
+ * renders inside itself carries the `inert` attribute, so the pointer and the
+ * tab sequence both stop at the overlay rather than walking into the controls
+ * it is hiding. Deliberately **not** a focus trap: this is not a dialog, there
+ * is nothing inside to focus and nothing to dismiss, so trapping would strand
+ * the keyboard on a spinner.
+ *
+ * The two attributes are on two elements on purpose. `inert` takes its subtree
+ * out of the accessibility tree, so `aria-busy` beside it would be removed too
+ * and the busy state would be published to nobody — the component would be
+ * silent about the one thing it is for. It is the same reasoning that puts the
+ * announcement through the process-wide live region (see `announce`)
+ * rather than in a `Spinner` inside the subtree, where a `role="status"`
+ * announces nothing. `loadedLabel` announces the *end* of the work the same
+ * way, and where it is omitted the overlay still clears its own message on
+ * hide, so the next identical `loadingLabel` is a change the announcer will
+ * publish rather than a duplicate it skips.
  *
  * `delay` exists for the same reason `Tooltip` has one: a request that
  * resolves in 80ms should never paint a spinner. The timer is cancelled when
@@ -30,12 +38,42 @@ export declare const LoadingOverlayProvider: {
  * `data-state` is `"visible"`/`"hidden"` and reflects the *effective*
  * visibility, i.e. after `delay`.
  *
+ * Renders `children` verbatim inside the `covered` wrapper —
+ * {@link LoadingOverlay} (the recipe, below) is this root with the `LoadingOverlayBackdrop`
+ * and `LoadingOverlayContent` derived after them.
+ *
  * @example
  * ```tsx
- * <LoadingOverlay visible={isFetching} delay={150} loadingLabel="Loading invoices">
+ * import { LoadingOverlayBackdrop, LoadingOverlayContent, LoadingOverlayRoot } from '@skdx/react/primitives/loading-overlay';
+ *
+ * <LoadingOverlayRoot visible={isFetching} delay={150} loadingLabel="Loading invoices">
  *   <InvoiceTable />
  *   <LoadingOverlayBackdrop />
- *   <LoadingOverlayContent />
+ *   <LoadingOverlayContent>
+ *     <ProgressBar value={percent} />
+ *   </LoadingOverlayContent>
+ * </LoadingOverlayRoot>
+ * ```
+ */
+export declare const LoadingOverlayRoot: React.ForwardRefExoticComponent<Omit<LoadingOverlayRootProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+/**
+ * A loading overlay over the content it covers.
+ *
+ * Always draws the derived anatomy — the `LoadingOverlayBackdrop` scrim and the `LoadingOverlayContent`
+ * layer with the library's `Spinner`, labelled from `loadingLabel` — after
+ * `children`, which is the content being covered. Never a switch: this
+ * component does not inspect what it was given. Replace the indicator by
+ * composing {@link LoadingOverlayRoot} from
+ * `@skdx/react/primitives/loading-overlay`.
+ *
+ * Everything the root owns still applies: `visible`/`onVisibleChange`, the
+ * `delay` window, `fullScreen` with its body-scroll lock, the `inert` covered
+ * wrapper, and the polite `loadingLabel`/`loadedLabel` announcements.
+ *
+ * @example
+ * ```tsx
+ * <LoadingOverlay visible={isFetching} delay={150} loadingLabel="Loading invoices">
+ *   <InvoiceTable />
  * </LoadingOverlay>
  * ```
  */

package/dist/loading-overlay/LoadingOverlay.js

@@ -1 +1 @@
-import*as r from"react";import{createSafeContext as k}from"../utils/createContext.js";import{LiveAnnouncer as B}from"../utils/liveAnnouncer.js";import{skdxPart as w}from"../utils/part.js";import{Primitive as E}from"../utils/primitive.js";import{useBodyScrollLock as h}from"../utils/useBodyScrollLock.js";import{useCallbackRef as N}from"../utils/useCallbackRef.js";import{useControllableState as S}from"../utils/useControllableState.js";import{jsx as y,jsxs as V}from"react/jsx-runtime";var[T,l]=k("LoadingOverlay"),D=r.forwardRef(({visible:a,defaultVisible:t=!1,onVisibleChange:i,fullScreen:o=!1,loadingLabel:d="Loading",delay:n=0,children:b,...p},C)=>{let[s=!1]=S({prop:a,defaultProp:t}),[R,f]=r.useState(!1);r.useEffect(()=>{if(!s||n<=0)return;let x=window.setTimeout(()=>f(!0),n);return()=>{window.clearTimeout(x),f(!1)}},[s,n]);let e=s&&(n<=0||R),v=N(i),c=r.useRef(e);return r.useEffect(()=>{c.current!==e&&(c.current=e,v(e))},[e,v]),h(e&&o),V(T,{visible:e,fullScreen:o,loadingLabel:d,children:[y(E.div,{"aria-busy":e||void 0,inert:e,"data-state":e?"visible":"hidden","data-full-screen":o?"":void 0,...p,...w("loading-overlay","root",p.className),ref:C,children:b}),y(B,{message:e?d:""})]})});D.displayName="LoadingOverlay";import*as L from"react";import{skdxPart as H}from"../utils/part.js";import{Presence as M}from"../utils/presence.js";import{Primitive as q}from"../utils/primitive.js";import{jsx as g}from"react/jsx-runtime";var u=L.forwardRef((a,t)=>{let{visible:i,fullScreen:o}=l("LoadingOverlayBackdrop");return g(M,{present:i,children:g(q.div,{"aria-hidden":!0,"data-state":i?"visible":"hidden","data-full-screen":o?"":void 0,...a,...H("loading-overlay","backdrop",a.className),ref:t})})});u.displayName="LoadingOverlayBackdrop";import*as O from"react";import{Spinner as A}from"../spinner/Spinner.js";import{skdxPart as z}from"../utils/part.js";import{Presence as F}from"../utils/presence.js";import{Primitive as G}from"../utils/primitive.js";import{jsx as m}from"react/jsx-runtime";var P=O.forwardRef(({children:a,...t},i)=>{let{visible:o,fullScreen:d,loadingLabel:n}=l("LoadingOverlayContent");return m(F,{present:o,children:m(G.div,{"data-state":o?"visible":"hidden","data-full-screen":d?"":void 0,...t,...z("loading-overlay","content",t.className),ref:i,children:a??m(A,{label:n})})})});P.displayName="LoadingOverlayContent";export{D as LoadingOverlay,u as LoadingOverlayBackdrop,P as LoadingOverlayContent,T as LoadingOverlayProvider,l as useLoadingOverlayContext};
+import*as r from"react";import{createSafeContext as z}from"../utils/createContext.js";import{announce as b,clearAnnouncements as F}from"../utils/liveAnnouncer.js";import{skdxPart as k}from"../utils/part.js";import{Primitive as G}from"../utils/primitive.js";import{useBodyScrollLock as I}from"../utils/useBodyScrollLock.js";import{useCallbackRef as J}from"../utils/useCallbackRef.js";import{useControllableState as K}from"../utils/useControllableState.js";import*as R from"react";import{skdxPart as T}from"../utils/part.js";import{Presence as D}from"../utils/presence.js";import{Primitive as V}from"../utils/primitive.js";import{jsx as O}from"react/jsx-runtime";var p=R.forwardRef((t,a)=>{let{visible:o,fullScreen:i}=d("LoadingOverlayBackdrop");return O(D,{present:o,children:O(V.div,{"aria-hidden":!0,"data-state":o?"visible":"hidden","data-full-screen":i?"":void 0,...t,...T("loading-overlay","backdrop",t.className),ref:a})})});p.displayName="LoadingOverlayBackdrop";import*as P from"react";import{Spinner as A}from"../spinner/Spinner.js";import{skdxPart as H}from"../utils/part.js";import{Presence as M}from"../utils/presence.js";import{Primitive as q}from"../utils/primitive.js";import{jsx as v}from"react/jsx-runtime";var c=P.forwardRef(({children:t,...a},o)=>{let{visible:i,fullScreen:s,loadingLabel:n}=d("LoadingOverlayContent");return v(M,{present:i,children:v(q.div,{"data-state":i?"visible":"hidden","data-full-screen":s?"":void 0,...a,...H("loading-overlay","content",a.className),ref:o,children:t??v(A,{label:n})})})});c.displayName="LoadingOverlayContent";import{Fragment as Y,jsx as C,jsxs as _}from"react/jsx-runtime";var x=()=>_(Y,{children:[C(p,{}),C(c,{})]});import{jsx as l,jsxs as W}from"react/jsx-runtime";var[Q,d]=z("LoadingOverlay"),U={display:"contents"},E=r.forwardRef(({visible:t,onVisibleChange:a,fullScreen:o=!1,loadingLabel:i="Loading",loadedLabel:s,delay:n=0,children:w,...y},h)=>{let[m=!1]=K({prop:t}),[B,u]=r.useState(!1);r.useEffect(()=>{if(!m||n<=0)return;let N=window.setTimeout(()=>u(!0),n);return()=>{window.clearTimeout(N),u(!1)}},[m,n]);let e=m&&(n<=0||B),g=J(a),L=r.useRef(e);r.useEffect(()=>{L.current!==e&&(L.current=e,g(e))},[e,g]);let f=r.useRef(!1);return r.useEffect(()=>{if(e){f.current=!0,b(i);return}f.current&&(f.current=!1,s?b(s):F("polite"))},[e,i,s]),I(e&&o),l(Q,{visible:e,fullScreen:o,loadingLabel:i,children:l(G.div,{"aria-busy":e||void 0,"data-state":e?"visible":"hidden","data-full-screen":o?"":void 0,...y,...k("loading-overlay","root",y.className),ref:h,children:l("div",{inert:e,style:U,...k("loading-overlay","covered"),children:w})})})});E.displayName="LoadingOverlayRoot";var S=r.forwardRef(({children:t,...a},o)=>W(E,{...a,ref:o,children:[t,l(x,{})]}));S.displayName="LoadingOverlay";export{S as LoadingOverlay,p as LoadingOverlayBackdrop,c as LoadingOverlayContent,Q as LoadingOverlayProvider,E as LoadingOverlayRoot,d as useLoadingOverlayContext};

package/dist/loading-overlay/LoadingOverlayAnatomy.d.cts

@@ -0,0 +1,7 @@
+/**
+ * The anatomy a {@link LoadingOverlay} draws over the covered content: the
+ * `LoadingOverlayBackdrop` scrim, then the `LoadingOverlayContent` layer with its default `Spinner`.
+ *
+ * @internal
+ */
+export declare const LoadingOverlayAnatomy: () => import("react").JSX.Element;

package/dist/loading-overlay/LoadingOverlayAnatomy.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The anatomy a {@link LoadingOverlay} draws over the covered content: the
+ * `LoadingOverlayBackdrop` scrim, then the `LoadingOverlayContent` layer with its default `Spinner`.
+ *
+ * @internal
+ */
+export declare const LoadingOverlayAnatomy: () => import("react").JSX.Element;