@skdx/react 0.26.0

package/dist/listbox/ListboxItemIndicator.d.ts

@@ -0,0 +1,21 @@
+import * as React from 'react';
+import type { ListboxItemIndicatorProps } from './types.js';
+/**
+ * Marker shown inside a {@link ListboxItem} while that option is selected
+ * (typically a checkmark). Renders an `aria-hidden` `<span>` — the option's
+ * `aria-selected` already carries the state, so announcing the glyph too would
+ * say it twice; renders nothing while its option isn't selected unless
+ * `forceMount` is set.
+ *
+ * Give the option a `textValue` whenever you render an indicator: typeahead
+ * otherwise matches against the option's whole text content, glyph included.
+ *
+ * @example
+ * ```tsx
+ * <ListboxItem value="react" textValue="React">
+ *   <ListboxItemIndicator>✓</ListboxItemIndicator>
+ *   React
+ * </ListboxItem>
+ * ```
+ */
+export declare const ListboxItemIndicator: React.ForwardRefExoticComponent<Omit<ListboxItemIndicatorProps, "ref"> & React.RefAttributes<HTMLSpanElement>>;

package/dist/listbox/ListboxLabel.d.cts

@@ -0,0 +1,19 @@
+import * as React from 'react';
+import type { ListboxLabelProps } from './types.cjs';
+/**
+ * The heading naming a {@link ListboxGroup}. Renders a plain `<div>` carrying
+ * the id its group points `aria-labelledby` at, so the group is named without
+ * the label itself becoming an option.
+ *
+ * Must be rendered inside a `ListboxGroup` — a label with no group to name has
+ * nothing to attach to.
+ *
+ * @example
+ * ```tsx
+ * <ListboxGroup>
+ *   <ListboxLabel>Frameworks</ListboxLabel>
+ *   <ListboxItem value="react">React</ListboxItem>
+ * </ListboxGroup>
+ * ```
+ */
+export declare const ListboxLabel: React.ForwardRefExoticComponent<Omit<ListboxLabelProps, "ref"> & React.RefAttributes<HTMLDivElement>>;

package/dist/listbox/ListboxLabel.d.ts

@@ -0,0 +1,19 @@
+import * as React from 'react';
+import type { ListboxLabelProps } from './types.js';
+/**
+ * The heading naming a {@link ListboxGroup}. Renders a plain `<div>` carrying
+ * the id its group points `aria-labelledby` at, so the group is named without
+ * the label itself becoming an option.
+ *
+ * Must be rendered inside a `ListboxGroup` — a label with no group to name has
+ * nothing to attach to.
+ *
+ * @example
+ * ```tsx
+ * <ListboxGroup>
+ *   <ListboxLabel>Frameworks</ListboxLabel>
+ *   <ListboxItem value="react">React</ListboxItem>
+ * </ListboxGroup>
+ * ```
+ */
+export declare const ListboxLabel: React.ForwardRefExoticComponent<Omit<ListboxLabelProps, "ref"> & React.RefAttributes<HTMLDivElement>>;

package/dist/listbox/index.d.cts

@@ -0,0 +1,6 @@
+export * from './Listbox.cjs';
+export { ListboxItem } from './ListboxItem.cjs';
+export { ListboxItemIndicator } from './ListboxItemIndicator.cjs';
+export { ListboxGroup } from './ListboxGroup.cjs';
+export { ListboxLabel } from './ListboxLabel.cjs';
+export type { ListboxProps, ListboxItemProps, ListboxItemIndicatorProps, ListboxGroupProps, ListboxLabelProps, } from './types.cjs';

package/dist/listbox/index.d.ts

@@ -0,0 +1,6 @@
+export * from './Listbox.js';
+export { ListboxItem } from './ListboxItem.js';
+export { ListboxItemIndicator } from './ListboxItemIndicator.js';
+export { ListboxGroup } from './ListboxGroup.js';
+export { ListboxLabel } from './ListboxLabel.js';
+export type { ListboxProps, ListboxItemProps, ListboxItemIndicatorProps, ListboxGroupProps, ListboxLabelProps, } from './types.js';

package/dist/listbox/types.d.cts

@@ -0,0 +1,96 @@
+import type { PrimitivePropsWithRef } from '../utils/primitive.cjs';
+/** @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. */
+    multiple: boolean;
+    /** Every selected value, normalised to an array whether or not `multiple`. */
+    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;
+    /** 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;
+}
+/** 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.
+     */
+    value?: string | string[];
+    /**
+     * Initially selected option's value, for uncontrolled usage. Same shape as
+     * `value`: a `string[]` when `multiple`.
+     * @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.
+     * @default undefined — no-op if omitted.
+     */
+    onValueChange?: (value: string | string[]) => 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.
+     * @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.
+     * @default false
+     */
+    disabled?: boolean;
+}
+/** @internal Shared state distributed from {@link ListboxItem} to its indicator via context. Not part of the public API. */
+export interface ListboxItemContextValue {
+    value: string;
+    selected: boolean;
+    disabled: boolean;
+}
+/** Props for a single {@link ListboxItem} option. */
+export interface ListboxItemProps extends PrimitivePropsWithRef<'div'> {
+    /** Unique identifier committed to the listbox's value when this option is chosen. */
+    value: string;
+    /**
+     * Excludes this option from selection and from keyboard/typeahead navigation.
+     * @default false
+     */
+    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.
+     */
+    textValue?: string;
+}
+/** Props for {@link ListboxItemIndicator}, shown inside a {@link ListboxItem} while that option is selected. */
+export interface ListboxItemIndicatorProps extends PrimitivePropsWithRef<'span'> {
+    /**
+     * Keep this indicator mounted even while its option isn't selected, instead
+     * of rendering nothing.
+     * @default false
+     */
+    forceMount?: boolean;
+}
+/** Props for {@link ListboxGroup}, a labelled group of related `ListboxItem`s. */
+export interface ListboxGroupProps extends PrimitivePropsWithRef<'div'> {
+}
+/** Props for {@link ListboxLabel}, the heading naming its {@link ListboxGroup}. */
+export interface ListboxLabelProps extends PrimitivePropsWithRef<'div'> {
+}
+/** @internal Wiring passed from a {@link ListboxGroup} to its {@link ListboxLabel}. Not part of the public API. */
+export interface ListboxGroupContextValue {
+    /** The id the group points `aria-labelledby` at, which its Label claims. */
+    labelId: string;
+}

package/dist/listbox/types.d.ts

@@ -0,0 +1,96 @@
+import type { PrimitivePropsWithRef } from '../utils/primitive.js';
+/** @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. */
+    multiple: boolean;
+    /** Every selected value, normalised to an array whether or not `multiple`. */
+    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;
+    /** 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;
+}
+/** 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.
+     */
+    value?: string | string[];
+    /**
+     * Initially selected option's value, for uncontrolled usage. Same shape as
+     * `value`: a `string[]` when `multiple`.
+     * @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.
+     * @default undefined — no-op if omitted.
+     */
+    onValueChange?: (value: string | string[]) => 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.
+     * @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.
+     * @default false
+     */
+    disabled?: boolean;
+}
+/** @internal Shared state distributed from {@link ListboxItem} to its indicator via context. Not part of the public API. */
+export interface ListboxItemContextValue {
+    value: string;
+    selected: boolean;
+    disabled: boolean;
+}
+/** Props for a single {@link ListboxItem} option. */
+export interface ListboxItemProps extends PrimitivePropsWithRef<'div'> {
+    /** Unique identifier committed to the listbox's value when this option is chosen. */
+    value: string;
+    /**
+     * Excludes this option from selection and from keyboard/typeahead navigation.
+     * @default false
+     */
+    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.
+     */
+    textValue?: string;
+}
+/** Props for {@link ListboxItemIndicator}, shown inside a {@link ListboxItem} while that option is selected. */
+export interface ListboxItemIndicatorProps extends PrimitivePropsWithRef<'span'> {
+    /**
+     * Keep this indicator mounted even while its option isn't selected, instead
+     * of rendering nothing.
+     * @default false
+     */
+    forceMount?: boolean;
+}
+/** Props for {@link ListboxGroup}, a labelled group of related `ListboxItem`s. */
+export interface ListboxGroupProps extends PrimitivePropsWithRef<'div'> {
+}
+/** Props for {@link ListboxLabel}, the heading naming its {@link ListboxGroup}. */
+export interface ListboxLabelProps extends PrimitivePropsWithRef<'div'> {
+}
+/** @internal Wiring passed from a {@link ListboxGroup} to its {@link ListboxLabel}. Not part of the public API. */
+export interface ListboxGroupContextValue {
+    /** The id the group points `aria-labelledby` at, which its Label claims. */
+    labelId: string;
+}

package/dist/loading-overlay/LoadingOverlay.cjs

@@ -0,0 +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});

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

@@ -0,0 +1,42 @@
+import * as React from 'react';
+import type { LoadingOverlayContextValue, LoadingOverlayProps } from './types.cjs';
+export declare const LoadingOverlayProvider: {
+    (props: LoadingOverlayContextValue & {
+        children: React.ReactNode;
+    }): React.JSX.Element;
+    displayName: string;
+}, useLoadingOverlayContext: (consumerName: string) => LoadingOverlayContextValue;
+/**
+ * Root of a loading overlay: wraps the content being covered, owns the
+ * visibility (`visible`/`defaultVisible`/`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.
+ *
+ * `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
+ * `visible` flips back to false before it fires, and on unmount.
+ *
+ * `data-state` is `"visible"`/`"hidden"` and reflects the *effective*
+ * visibility, i.e. after `delay`.
+ *
+ * @example
+ * ```tsx
+ * <LoadingOverlay visible={isFetching} delay={150} loadingLabel="Loading invoices">
+ *   <InvoiceTable />
+ *   <LoadingOverlayBackdrop />
+ *   <LoadingOverlayContent />
+ * </LoadingOverlay>
+ * ```
+ */
+export declare const LoadingOverlay: React.ForwardRefExoticComponent<Omit<LoadingOverlayProps, "ref"> & React.RefAttributes<HTMLDivElement>>;

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

@@ -0,0 +1,42 @@
+import * as React from 'react';
+import type { LoadingOverlayContextValue, LoadingOverlayProps } from './types.js';
+export declare const LoadingOverlayProvider: {
+    (props: LoadingOverlayContextValue & {
+        children: React.ReactNode;
+    }): React.JSX.Element;
+    displayName: string;
+}, useLoadingOverlayContext: (consumerName: string) => LoadingOverlayContextValue;
+/**
+ * Root of a loading overlay: wraps the content being covered, owns the
+ * visibility (`visible`/`defaultVisible`/`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.
+ *
+ * `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
+ * `visible` flips back to false before it fires, and on unmount.
+ *
+ * `data-state` is `"visible"`/`"hidden"` and reflects the *effective*
+ * visibility, i.e. after `delay`.
+ *
+ * @example
+ * ```tsx
+ * <LoadingOverlay visible={isFetching} delay={150} loadingLabel="Loading invoices">
+ *   <InvoiceTable />
+ *   <LoadingOverlayBackdrop />
+ *   <LoadingOverlayContent />
+ * </LoadingOverlay>
+ * ```
+ */
+export declare const LoadingOverlay: React.ForwardRefExoticComponent<Omit<LoadingOverlayProps, "ref"> & React.RefAttributes<HTMLDivElement>>;

package/dist/loading-overlay/LoadingOverlay.js

@@ -0,0 +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};

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

@@ -0,0 +1,24 @@
+import * as React from 'react';
+import type { LoadingOverlayBackdropProps } from './types.cjs';
+/**
+ * The scrim that covers the work in progress. Mounts through `Presence`, so a
+ * CSS exit animation on `[data-state='hidden']` plays before it unmounts (and
+ * with no animation declared it unmounts immediately, costing nothing).
+ *
+ * Renders `aria-hidden` — it is pure decoration, the announcement comes from
+ * the root — and carries `data-state="visible" | "hidden"` plus
+ * `data-full-screen` so one rule set can style both the inline
+ * (`position: absolute; inset: 0`) and the full-screen
+ * (`position: fixed; inset: 0`) case.
+ *
+ * Must be used inside a {@link LoadingOverlay}.
+ *
+ * @example
+ * ```tsx
+ * <LoadingOverlay visible={isFetching}>
+ *   <InvoiceTable />
+ *   <LoadingOverlayBackdrop />
+ * </LoadingOverlay>
+ * ```
+ */
+export declare const LoadingOverlayBackdrop: React.ForwardRefExoticComponent<Omit<LoadingOverlayBackdropProps, "ref"> & React.RefAttributes<HTMLDivElement>>;

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

@@ -0,0 +1,24 @@
+import * as React from 'react';
+import type { LoadingOverlayBackdropProps } from './types.js';
+/**
+ * The scrim that covers the work in progress. Mounts through `Presence`, so a
+ * CSS exit animation on `[data-state='hidden']` plays before it unmounts (and
+ * with no animation declared it unmounts immediately, costing nothing).
+ *
+ * Renders `aria-hidden` — it is pure decoration, the announcement comes from
+ * the root — and carries `data-state="visible" | "hidden"` plus
+ * `data-full-screen` so one rule set can style both the inline
+ * (`position: absolute; inset: 0`) and the full-screen
+ * (`position: fixed; inset: 0`) case.
+ *
+ * Must be used inside a {@link LoadingOverlay}.
+ *
+ * @example
+ * ```tsx
+ * <LoadingOverlay visible={isFetching}>
+ *   <InvoiceTable />
+ *   <LoadingOverlayBackdrop />
+ * </LoadingOverlay>
+ * ```
+ */
+export declare const LoadingOverlayBackdrop: React.ForwardRefExoticComponent<Omit<LoadingOverlayBackdropProps, "ref"> & React.RefAttributes<HTMLDivElement>>;

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

@@ -0,0 +1,29 @@
+import * as React from 'react';
+import type { LoadingOverlayContentProps } from './types.cjs';
+/**
+ * The indicator layer sitting on top of the backdrop — a spinner, a message,
+ * a cancel affordance, whatever the overlay needs to say. Mounts through
+ * `Presence` alongside the backdrop and carries the same
+ * `data-state="visible" | "hidden"` and `data-full-screen` hooks.
+ *
+ * With no `children` it falls back to the existing `Spinner` family, labelled
+ * with the root's `loadingLabel` — composing the indicator the library
+ * already ships rather than growing a second one. Pass `children` to replace
+ * it entirely.
+ *
+ * The whole overlay sits inside the root's `inert` subtree, so nothing here
+ * is focusable or announced; the "Loading" announcement is made by the root
+ * through the live region.
+ *
+ * Must be used inside a {@link LoadingOverlay}.
+ *
+ * @example
+ * ```tsx
+ * <LoadingOverlay visible={isFetching} loadingLabel="Loading invoices">
+ *   <InvoiceTable />
+ *   <LoadingOverlayBackdrop />
+ *   <LoadingOverlayContent />
+ * </LoadingOverlay>
+ * ```
+ */
+export declare const LoadingOverlayContent: React.ForwardRefExoticComponent<Omit<LoadingOverlayContentProps, "ref"> & React.RefAttributes<HTMLDivElement>>;

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

@@ -0,0 +1,29 @@
+import * as React from 'react';
+import type { LoadingOverlayContentProps } from './types.js';
+/**
+ * The indicator layer sitting on top of the backdrop — a spinner, a message,
+ * a cancel affordance, whatever the overlay needs to say. Mounts through
+ * `Presence` alongside the backdrop and carries the same
+ * `data-state="visible" | "hidden"` and `data-full-screen` hooks.
+ *
+ * With no `children` it falls back to the existing `Spinner` family, labelled
+ * with the root's `loadingLabel` — composing the indicator the library
+ * already ships rather than growing a second one. Pass `children` to replace
+ * it entirely.
+ *
+ * The whole overlay sits inside the root's `inert` subtree, so nothing here
+ * is focusable or announced; the "Loading" announcement is made by the root
+ * through the live region.
+ *
+ * Must be used inside a {@link LoadingOverlay}.
+ *
+ * @example
+ * ```tsx
+ * <LoadingOverlay visible={isFetching} loadingLabel="Loading invoices">
+ *   <InvoiceTable />
+ *   <LoadingOverlayBackdrop />
+ *   <LoadingOverlayContent />
+ * </LoadingOverlay>
+ * ```
+ */
+export declare const LoadingOverlayContent: React.ForwardRefExoticComponent<Omit<LoadingOverlayContentProps, "ref"> & React.RefAttributes<HTMLDivElement>>;

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

@@ -0,0 +1,4 @@
+export * from './LoadingOverlay.cjs';
+export { LoadingOverlayBackdrop } from './LoadingOverlayBackdrop.cjs';
+export { LoadingOverlayContent } from './LoadingOverlayContent.cjs';
+export type { LoadingOverlayProps, LoadingOverlayBackdropProps, LoadingOverlayContentProps } from './types.cjs';

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

@@ -0,0 +1,4 @@
+export * from './LoadingOverlay.js';
+export { LoadingOverlayBackdrop } from './LoadingOverlayBackdrop.js';
+export { LoadingOverlayContent } from './LoadingOverlayContent.js';
+export type { LoadingOverlayProps, LoadingOverlayBackdropProps, LoadingOverlayContentProps } from './types.js';

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

@@ -0,0 +1,74 @@
+import type { PrimitivePropsWithRef } from '../utils/primitive.cjs';
+/**
+ * @internal Shared state distributed from {@link LoadingOverlay} to
+ * `LoadingOverlayBackdrop` and `LoadingOverlayContent` via context. Not part
+ * of the public API.
+ */
+export interface LoadingOverlayContextValue {
+    /**
+     * The *effective* visibility — `visible` after `delay` has elapsed, not the
+     * raw prop. This is what the parts mount against, so a request that
+     * resolves inside the delay window never renders an overlay at all.
+     */
+    visible: boolean;
+    fullScreen: boolean;
+    loadingLabel: string;
+}
+/** Props for the {@link LoadingOverlay} root. */
+export interface LoadingOverlayProps extends PrimitivePropsWithRef<'div'> {
+    /**
+     * Whether work is in flight, for controlled usage. Pair with `onVisibleChange`.
+     * @default undefined — uncontrolled, tracks its own visibility internally.
+     */
+    visible?: boolean;
+    /**
+     * Initial visibility, for uncontrolled usage, seeding the first render.
+     * @default false — the overlay starts hidden and the wrapped content is interactive.
+     */
+    defaultVisible?: boolean;
+    /**
+     * Fires when the overlay *actually* appears or disappears — i.e. after
+     * `delay` — in both controlled and uncontrolled usage. It reports the
+     * effective transition rather than echoing the prop back, because the
+     * moment a delayed overlay paints is the one thing the caller cannot
+     * derive from the `visible` it passed in. With `delay={0}` the two coincide.
+     * @default undefined — no-op if omitted.
+     */
+    onVisibleChange?: (visible: boolean) => void;
+    /**
+     * Cover the viewport instead of the root's own box. Emits
+     * `data-full-screen` (style it `position: fixed; inset: 0`) and locks body
+     * scroll while visible — an inline overlay never locks the body, because
+     * freezing the whole page for a spinner over one card is a bug, not a
+     * feature.
+     * @default false — the overlay covers only the root element's box.
+     */
+    fullScreen?: boolean;
+    /**
+     * Text announced politely when the overlay becomes visible, and the default
+     * `Spinner` label inside `LoadingOverlayContent`.
+     * @default 'Loading' — announced as "Loading"; name the work ("Loading invoices") when the page has more than one.
+     */
+    loadingLabel?: string;
+    /**
+     * Milliseconds to wait after `visible` turns true before the overlay
+     * actually appears. A response that arrives inside the window never renders
+     * an overlay at all, which is what stops the flash-of-spinner on fast
+     * requests. The pending timer is cancelled if `visible` flips back to false
+     * first, and on unmount.
+     * @default 0 — shows immediately, so nothing is hidden from a slow connection by accident.
+     */
+    delay?: number;
+}
+/**
+ * Props for {@link LoadingOverlayBackdrop} — the scrim layer. No props of its
+ * own; it reads visibility from the root's context.
+ */
+export interface LoadingOverlayBackdropProps extends PrimitivePropsWithRef<'div'> {
+}
+/**
+ * Props for {@link LoadingOverlayContent} — the centred indicator layer. No
+ * props of its own; it reads visibility and the label from the root's context.
+ */
+export interface LoadingOverlayContentProps extends PrimitivePropsWithRef<'div'> {
+}

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

@@ -0,0 +1,74 @@
+import type { PrimitivePropsWithRef } from '../utils/primitive.js';
+/**
+ * @internal Shared state distributed from {@link LoadingOverlay} to
+ * `LoadingOverlayBackdrop` and `LoadingOverlayContent` via context. Not part
+ * of the public API.
+ */
+export interface LoadingOverlayContextValue {
+    /**
+     * The *effective* visibility — `visible` after `delay` has elapsed, not the
+     * raw prop. This is what the parts mount against, so a request that
+     * resolves inside the delay window never renders an overlay at all.
+     */
+    visible: boolean;
+    fullScreen: boolean;
+    loadingLabel: string;
+}
+/** Props for the {@link LoadingOverlay} root. */
+export interface LoadingOverlayProps extends PrimitivePropsWithRef<'div'> {
+    /**
+     * Whether work is in flight, for controlled usage. Pair with `onVisibleChange`.
+     * @default undefined — uncontrolled, tracks its own visibility internally.
+     */
+    visible?: boolean;
+    /**
+     * Initial visibility, for uncontrolled usage, seeding the first render.
+     * @default false — the overlay starts hidden and the wrapped content is interactive.
+     */
+    defaultVisible?: boolean;
+    /**
+     * Fires when the overlay *actually* appears or disappears — i.e. after
+     * `delay` — in both controlled and uncontrolled usage. It reports the
+     * effective transition rather than echoing the prop back, because the
+     * moment a delayed overlay paints is the one thing the caller cannot
+     * derive from the `visible` it passed in. With `delay={0}` the two coincide.
+     * @default undefined — no-op if omitted.
+     */
+    onVisibleChange?: (visible: boolean) => void;
+    /**
+     * Cover the viewport instead of the root's own box. Emits
+     * `data-full-screen` (style it `position: fixed; inset: 0`) and locks body
+     * scroll while visible — an inline overlay never locks the body, because
+     * freezing the whole page for a spinner over one card is a bug, not a
+     * feature.
+     * @default false — the overlay covers only the root element's box.
+     */
+    fullScreen?: boolean;
+    /**
+     * Text announced politely when the overlay becomes visible, and the default
+     * `Spinner` label inside `LoadingOverlayContent`.
+     * @default 'Loading' — announced as "Loading"; name the work ("Loading invoices") when the page has more than one.
+     */
+    loadingLabel?: string;
+    /**
+     * Milliseconds to wait after `visible` turns true before the overlay
+     * actually appears. A response that arrives inside the window never renders
+     * an overlay at all, which is what stops the flash-of-spinner on fast
+     * requests. The pending timer is cancelled if `visible` flips back to false
+     * first, and on unmount.
+     * @default 0 — shows immediately, so nothing is hidden from a slow connection by accident.
+     */
+    delay?: number;
+}
+/**
+ * Props for {@link LoadingOverlayBackdrop} — the scrim layer. No props of its
+ * own; it reads visibility from the root's context.
+ */
+export interface LoadingOverlayBackdropProps extends PrimitivePropsWithRef<'div'> {
+}
+/**
+ * Props for {@link LoadingOverlayContent} — the centred indicator layer. No
+ * props of its own; it reads visibility and the label from the root's context.
+ */
+export interface LoadingOverlayContentProps extends PrimitivePropsWithRef<'div'> {
+}