@skdx/react 0.26.0

package/dist/utils/direction.d.ts

@@ -0,0 +1,82 @@
+import * as React from 'react';
+/**
+ * Writing direction resolution, shared by every component whose keyboard
+ * behaviour is horizontal (arrow-key navigation, submenu open/close, slider
+ * stepping, resize handles).
+ *
+ * There is exactly one rule to apply: **under `dir="rtl"`, ArrowLeft and
+ * ArrowRight swap meaning.** Everything else — Home/End, the vertical arrows,
+ * typeahead — is direction-agnostic, so handlers call {@link directionalKey}
+ * once at the top and then keep their existing LTR-authored branches.
+ *
+ * Direction is resolved in this order:
+ *
+ * 1. an explicit `dir` prop on the component, if it accepts one;
+ * 2. the nearest {@link DirectionProvider};
+ * 3. the nearest `[dir]` ancestor **in the DOM** — which is what a plain
+ *    `dir="rtl"` prop on any skdx component produces, since `dir` is a
+ *    global HTML attribute and `Primitive` spreads it onto the element;
+ * 4. `document.dir`.
+ *
+ * Step 3 is why most components need no `dir` prop of their own and no
+ * provider: `<Tabs dir="rtl">` already renders `dir="rtl"` on the tablist,
+ * and the handler reads it back off `event.currentTarget`. The provider
+ * exists for the case that has no element to hang the attribute on — a whole
+ * app rendered RTL without touching every subtree's markup.
+ */
+/** Writing direction of a subtree. */
+export type Direction = 'ltr' | 'rtl';
+/** Props for {@link DirectionProvider}. */
+export interface DirectionProviderProps {
+    /** Writing direction every descendant skdx component should assume. */
+    dir: Direction;
+    children?: React.ReactNode;
+}
+/**
+ * Declares the writing direction for every skdx component beneath it,
+ * without rendering an element of its own. Wrap your app (or an RTL subtree)
+ * in one when the direction is not already expressed as a `dir` attribute in
+ * the DOM.
+ *
+ * @example
+ * ```tsx
+ * <DirectionProvider dir="rtl">
+ *   <App />
+ * </DirectionProvider>
+ * ```
+ */
+export declare function DirectionProvider({ dir, children }: DirectionProviderProps): React.JSX.Element;
+/**
+ * The direction declared by an explicit prop or the nearest
+ * {@link DirectionProvider}, or `undefined` when neither is present — in
+ * which case {@link directionalKey} falls back to the DOM.
+ */
+export declare function useDirection(dirProp?: Direction): Direction | undefined;
+/** @internal Resolves `el`'s direction, with `override` (prop/provider) winning when set. */
+export declare function resolveDirection(el: Element | null | undefined, override?: Direction): Direction;
+/** @internal An edge named logically: `start`/`end` follow the writing direction. */
+export type LogicalSide = 'start' | 'end' | 'top' | 'bottom';
+/** @internal An edge named physically, which is what CSS `left`/`right` and `data-side` mean. */
+export type PhysicalSide = 'left' | 'right' | 'top' | 'bottom';
+/**
+ * Resolves a logical edge to the physical one it lands on: `start`/`end` swap
+ * under RTL, `top`/`bottom` and already-physical `left`/`right` pass through.
+ *
+ * Components keep publishing the *logical* value (Drawer's `data-placement`,
+ * an overlay's `side` prop) and only resolve at the last moment — a component
+ * that stored `left` instead of `start` would break RTL for every consumer
+ * downstream.
+ *
+ * @internal
+ */
+export declare function resolvePhysicalSide(side: LogicalSide | PhysicalSide, direction: Direction): PhysicalSide;
+/**
+ * Translates the key the user physically pressed into the key an
+ * LTR-authored handler should act on: in RTL, ArrowLeft and ArrowRight swap.
+ * Every other key is returned unchanged, so this is safe to apply
+ * unconditionally — including in vertical widgets, where neither key means
+ * anything.
+ *
+ * @internal
+ */
+export declare function directionalKey(key: string, el: Element | null | undefined, override?: Direction): string;

package/dist/utils/direction.js

@@ -0,0 +1 @@
+import*as i from"react";import{jsx as d}from"react/jsx-runtime";var n=i.createContext(void 0);function u({dir:t,children:e}){return d(n.Provider,{value:t,children:e})}function f(t){let e=i.useContext(n);return t??e}function o(t,e){if(e)return e;let r=t?.closest("[dir]")?.getAttribute("dir")?.toLowerCase();return r==="rtl"||r==="ltr"?r:typeof document>"u"?"ltr":(document.dir||document.documentElement?.getAttribute("dir")||"").toLowerCase()==="rtl"?"rtl":"ltr"}function s(t,e){return t==="start"?e==="rtl"?"right":"left":t==="end"?e==="rtl"?"left":"right":t}var c={ArrowLeft:"ArrowRight",ArrowRight:"ArrowLeft"};function a(t,e,r){return o(e,r)==="rtl"?c[t]??t:t}export{u as DirectionProvider,a as directionalKey,o as resolveDirection,s as resolvePhysicalSide,f as useDirection};

package/dist/utils/formControl.cjs

@@ -0,0 +1 @@
+"use strict";var u=Object.create;var i=Object.defineProperty;var s=Object.getOwnPropertyDescriptor;var f=Object.getOwnPropertyNames;var m=Object.getPrototypeOf,R=Object.prototype.hasOwnProperty;var y=(e,t)=>{for(var r in t)i(e,r,{get:t[r],enumerable:!0})},o=(e,t,r,n)=>{if(t&&typeof t=="object"||typeof t=="function")for(let a of f(t))!R.call(e,a)&&a!==r&&i(e,a,{get:()=>t[a],enumerable:!(n=s(t,a))||n.enumerable});return e};var V=(e,t,r)=>(r=e!=null?u(m(e)):{},o(t||!e||!e.__esModule?i(r,"default",{value:e,enumerable:!0}):r,e)),p=e=>o(i({},"__esModule",{value:!0}),e);var v={};y(v,{formValidityHandle:()=>d,useFormReset:()=>b,useFormValidityHandle:()=>H});module.exports=p(v);var l=V(require("react"),1),c=require("./useCallbackRef.cjs");function d(e){return{checkValidity:()=>e.current?.checkValidity()??!0,reportValidity:()=>e.current?.reportValidity()??!0}}function H(e,t,r){l.useImperativeHandle(e,()=>{let n=d(r);return t.current?Object.assign(t.current,n):n})}function b(e,t){let r=(0,c.useCallbackRef)(t);l.useEffect(()=>{let n=e.current?.closest("form");if(n)return n.addEventListener("reset",r),()=>n.removeEventListener("reset",r)},[e,r])}0&&(module.exports={formValidityHandle,useFormReset,useFormValidityHandle});

package/dist/utils/formControl.d.cts

@@ -0,0 +1,66 @@
+import * as React from 'react';
+/**
+ * The two constraint-validation methods every form-associated component
+ * publishes — the same pair `<skdx-*>` gets from the `FormAssociated` mixin
+ * (`packages/web-components/src/internal/form-associated.ts`), and the same
+ * pair a native `HTMLInputElement` has.
+ *
+ * On a root that renders a DOM element these are hung on that element, so
+ * `ref.current` stays the node consumers already focus and measure. On a root
+ * that renders no DOM of its own (`Select`, `Combobox`, `DatePicker`) the ref
+ * *is* this object and nothing else.
+ */
+export interface FormValidityHandle {
+    /** Returns whether the current value satisfies its constraints, firing `invalid` if not. */
+    checkValidity(): boolean;
+    /** Like {@link checkValidity}, but also shows the browser's validation message. */
+    reportValidity(): boolean;
+}
+/**
+ * Builds {@link FormValidityHandle} on top of whichever native control
+ * actually carries the submitted value — the wrapped `<input>` for a
+ * TextField, the visually-hidden one a composite renders for its selection.
+ *
+ * Both methods answer `true` when that control is absent, which is what a
+ * control without a `name` is: it submits nothing, so there is nothing for it
+ * to be invalid about. This mirrors the `?? true` fallbacks in the Web
+ * Components mixin, where `ElementInternals` may not implement constraint
+ * validation at all.
+ */
+export declare function formValidityHandle(control: React.RefObject<FormValidityHandle | null>): FormValidityHandle;
+/**
+ * Publishes {@link FormValidityHandle} on the forwarded ref of a root that
+ * *does* render an element: the two methods are assigned onto the node rather
+ * than replacing it, so every existing use of the ref (`focus()`,
+ * `getBoundingClientRect()`, `contains()`) keeps working — this is additive,
+ * not a swap.
+ *
+ * Attach `nodeRef` to the root element yourself; the forwarded ref must not
+ * also be attached, since this hook owns it.
+ *
+ * @example
+ * ```tsx
+ * const rootRef = React.useRef<HTMLDivElement>(null);
+ * const inputRef = React.useRef<HTMLInputElement>(null);
+ * useFormValidityHandle(forwardedRef, rootRef, inputRef);
+ * return <Primitive.div {...props} ref={rootRef} />;
+ * ```
+ */
+export declare function useFormValidityHandle<T extends HTMLElement>(forwardedRef: React.ForwardedRef<T>, nodeRef: React.RefObject<T | null>, control: React.RefObject<FormValidityHandle | null>): void;
+/**
+ * Restores a control's declared default when the owning `<form>` is reset —
+ * the React counterpart of `formResetCallback()` on `<skdx-*>`.
+ *
+ * `element` is any node the control always renders (its root, its input, its
+ * trigger); the form is found from it with `closest('form')`, so a control
+ * outside a form simply never subscribes. Resolved once, on mount — moving a
+ * mounted control into a different `<form>` does not re-associate it, the same
+ * way a native input's `form` is fixed at parse time.
+ *
+ * Unlike the Web Components mixin, which writes the property back silently,
+ * `onReset` here has to go through the component's normal setter and fire its
+ * change callback: a *controlled* React control's value belongs to the parent,
+ * and one that reset itself without telling the parent would be overwritten on
+ * the very next render.
+ */
+export declare function useFormReset(element: React.RefObject<HTMLElement | null>, onReset: () => void): void;

package/dist/utils/formControl.d.ts

@@ -0,0 +1,66 @@
+import * as React from 'react';
+/**
+ * The two constraint-validation methods every form-associated component
+ * publishes — the same pair `<skdx-*>` gets from the `FormAssociated` mixin
+ * (`packages/web-components/src/internal/form-associated.ts`), and the same
+ * pair a native `HTMLInputElement` has.
+ *
+ * On a root that renders a DOM element these are hung on that element, so
+ * `ref.current` stays the node consumers already focus and measure. On a root
+ * that renders no DOM of its own (`Select`, `Combobox`, `DatePicker`) the ref
+ * *is* this object and nothing else.
+ */
+export interface FormValidityHandle {
+    /** Returns whether the current value satisfies its constraints, firing `invalid` if not. */
+    checkValidity(): boolean;
+    /** Like {@link checkValidity}, but also shows the browser's validation message. */
+    reportValidity(): boolean;
+}
+/**
+ * Builds {@link FormValidityHandle} on top of whichever native control
+ * actually carries the submitted value — the wrapped `<input>` for a
+ * TextField, the visually-hidden one a composite renders for its selection.
+ *
+ * Both methods answer `true` when that control is absent, which is what a
+ * control without a `name` is: it submits nothing, so there is nothing for it
+ * to be invalid about. This mirrors the `?? true` fallbacks in the Web
+ * Components mixin, where `ElementInternals` may not implement constraint
+ * validation at all.
+ */
+export declare function formValidityHandle(control: React.RefObject<FormValidityHandle | null>): FormValidityHandle;
+/**
+ * Publishes {@link FormValidityHandle} on the forwarded ref of a root that
+ * *does* render an element: the two methods are assigned onto the node rather
+ * than replacing it, so every existing use of the ref (`focus()`,
+ * `getBoundingClientRect()`, `contains()`) keeps working — this is additive,
+ * not a swap.
+ *
+ * Attach `nodeRef` to the root element yourself; the forwarded ref must not
+ * also be attached, since this hook owns it.
+ *
+ * @example
+ * ```tsx
+ * const rootRef = React.useRef<HTMLDivElement>(null);
+ * const inputRef = React.useRef<HTMLInputElement>(null);
+ * useFormValidityHandle(forwardedRef, rootRef, inputRef);
+ * return <Primitive.div {...props} ref={rootRef} />;
+ * ```
+ */
+export declare function useFormValidityHandle<T extends HTMLElement>(forwardedRef: React.ForwardedRef<T>, nodeRef: React.RefObject<T | null>, control: React.RefObject<FormValidityHandle | null>): void;
+/**
+ * Restores a control's declared default when the owning `<form>` is reset —
+ * the React counterpart of `formResetCallback()` on `<skdx-*>`.
+ *
+ * `element` is any node the control always renders (its root, its input, its
+ * trigger); the form is found from it with `closest('form')`, so a control
+ * outside a form simply never subscribes. Resolved once, on mount — moving a
+ * mounted control into a different `<form>` does not re-associate it, the same
+ * way a native input's `form` is fixed at parse time.
+ *
+ * Unlike the Web Components mixin, which writes the property back silently,
+ * `onReset` here has to go through the component's normal setter and fire its
+ * change callback: a *controlled* React control's value belongs to the parent,
+ * and one that reset itself without telling the parent would be overwritten on
+ * the very next render.
+ */
+export declare function useFormReset(element: React.RefObject<HTMLElement | null>, onReset: () => void): void;

package/dist/utils/formControl.js

@@ -0,0 +1 @@
+import*as a from"react";import{useCallbackRef as i}from"./useCallbackRef.js";function l(e){return{checkValidity:()=>e.current?.checkValidity()??!0,reportValidity:()=>e.current?.reportValidity()??!0}}function c(e,n,r){a.useImperativeHandle(e,()=>{let t=l(r);return n.current?Object.assign(n.current,t):t})}function d(e,n){let r=i(n);a.useEffect(()=>{let t=e.current?.closest("form");if(t)return t.addEventListener("reset",r),()=>t.removeEventListener("reset",r)},[e,r])}export{l as formValidityHandle,d as useFormReset,c as useFormValidityHandle};

package/dist/utils/hiddenInput.cjs

@@ -0,0 +1 @@
+"use strict";var u=Object.create;var o=Object.defineProperty;var I=Object.getOwnPropertyDescriptor;var H=Object.getOwnPropertyNames;var c=Object.getPrototypeOf,f=Object.prototype.hasOwnProperty;var l=(t,n)=>{for(var e in n)o(t,e,{get:n[e],enumerable:!0})},p=(t,n,e,d)=>{if(n&&typeof n=="object"||typeof n=="function")for(let i of H(n))!f.call(t,i)&&i!==e&&o(t,i,{get:()=>n[i],enumerable:!(d=I(n,i))||d.enumerable});return t};var h=(t,n,e)=>(e=t!=null?u(c(t)):{},p(n||!t||!t.__esModule?o(e,"default",{value:t,enumerable:!0}):e,t)),m=t=>p(o({},"__esModule",{value:!0}),t);var R={};l(R,{HiddenInput:()=>r});module.exports=m(R);var a=h(require("react"),1),s=require("react/jsx-runtime");function y(){}var r=a.forwardRef((t,n)=>(0,s.jsx)("input",{"aria-hidden":!0,tabIndex:-1,onChange:y,...t,ref:n,style:{position:"absolute",pointerEvents:"none",opacity:0,margin:0,width:1,height:1,...t.style}}));r.displayName="HiddenInput";0&&(module.exports={HiddenInput});

package/dist/utils/hiddenInput.d.cts

@@ -0,0 +1,18 @@
+import * as React from 'react';
+interface HiddenInputProps extends React.InputHTMLAttributes<HTMLInputElement> {
+}
+/**
+ * Visually hidden native input rendered by form controls (Checkbox, Switch,
+ * RadioGroup, Slider, FileUpload) so they participate in native form
+ * submission. Ref-forwarded so FileUpload can `.click()` it programmatically.
+ *
+ * Deliberately *not* `readOnly`: a readonly input is barred from constraint
+ * validation, so `required` would never report `valueMissing` — which is the
+ * one thing this input exists to carry into the form. The no-op `onChange` is
+ * what `readOnly` was really buying (silencing React's
+ * controlled-value-without-handler warning); the control is 1×1px,
+ * `pointer-events: none` and out of the tab order, so there is no user path to
+ * edit it anyway.
+ */
+export declare const HiddenInput: React.ForwardRefExoticComponent<HiddenInputProps & React.RefAttributes<HTMLInputElement>>;
+export {};

package/dist/utils/hiddenInput.d.ts

@@ -0,0 +1,18 @@
+import * as React from 'react';
+interface HiddenInputProps extends React.InputHTMLAttributes<HTMLInputElement> {
+}
+/**
+ * Visually hidden native input rendered by form controls (Checkbox, Switch,
+ * RadioGroup, Slider, FileUpload) so they participate in native form
+ * submission. Ref-forwarded so FileUpload can `.click()` it programmatically.
+ *
+ * Deliberately *not* `readOnly`: a readonly input is barred from constraint
+ * validation, so `required` would never report `valueMissing` — which is the
+ * one thing this input exists to carry into the form. The no-op `onChange` is
+ * what `readOnly` was really buying (silencing React's
+ * controlled-value-without-handler warning); the control is 1×1px,
+ * `pointer-events: none` and out of the tab order, so there is no user path to
+ * edit it anyway.
+ */
+export declare const HiddenInput: React.ForwardRefExoticComponent<HiddenInputProps & React.RefAttributes<HTMLInputElement>>;
+export {};

package/dist/utils/hiddenInput.js

@@ -0,0 +1 @@
+import*as n from"react";import{jsx as d}from"react/jsx-runtime";function i(){}var o=n.forwardRef((t,e)=>d("input",{"aria-hidden":!0,tabIndex:-1,onChange:i,...t,ref:e,style:{position:"absolute",pointerEvents:"none",opacity:0,margin:0,width:1,height:1,...t.style}}));o.displayName="HiddenInput";export{o as HiddenInput};

package/dist/utils/liveAnnouncer.cjs

@@ -0,0 +1 @@
+"use strict";var m=Object.create;var c=Object.defineProperty;var v=Object.getOwnPropertyDescriptor;var x=Object.getOwnPropertyNames;var L=Object.getPrototypeOf,g=Object.prototype.hasOwnProperty;var E=(e,n)=>{for(var t in n)c(e,t,{get:n[t],enumerable:!0})},s=(e,n,t,o)=>{if(n&&typeof n=="object"||typeof n=="function")for(let i of x(n))!g.call(e,i)&&i!==t&&c(e,i,{get:()=>n[i],enumerable:!(o=v(n,i))||o.enumerable});return e};var P=(e,n,t)=>(t=e!=null?m(L(e)):{},s(n||!e||!e.__esModule?c(t,"default",{value:e,enumerable:!0}):t,e)),T=e=>s(c({},"__esModule",{value:!0}),e);var N={};E(N,{ANNOUNCE_DEBOUNCE_MS:()=>d,LiveAnnouncer:()=>f,announce:()=>u,clearAnnouncements:()=>A,useLiveAnnouncer:()=>C});module.exports=T(N);var l=P(require("react"),1),d=150,y="position:absolute;border:0;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0, 0, 0, 0);white-space:nowrap;word-wrap:normal;",S=["polite","assertive"],r=new Map;function p(e){return document.querySelector(`[data-skdx-live-announcer="${e}"]`)}function a(e){let n=p(e);if(n)return n;let t=document.createElement("div");return t.setAttribute("aria-live",e),t.setAttribute("aria-atomic","true"),t.setAttribute("data-skdx-live-announcer",e),t.style.cssText=y,document.body.appendChild(t),t}function u(e,n="polite"){if(typeof document>"u")return;let t=e.trim();t&&(a(n),clearTimeout(r.get(n)),r.set(n,setTimeout(()=>{r.delete(n);let o=a(n);o.textContent!==t&&(o.textContent=t)},d)))}function A(e){for(let n of S){if(e!==void 0&&n!==e)continue;clearTimeout(r.get(n)),r.delete(n);let t=p(n);t&&(t.textContent="")}}var w={announce:u,clear:A};function C(){return w}function f({message:e,politeness:n="polite"}){return l.useEffect(()=>{u(e,n)},[e,n]),null}f.displayName="LiveAnnouncer";0&&(module.exports={ANNOUNCE_DEBOUNCE_MS,LiveAnnouncer,announce,clearAnnouncements,useLiveAnnouncer});

package/dist/utils/liveAnnouncer.d.cts

@@ -0,0 +1,77 @@
+/** Which of the two singleton live regions a message is routed to. */
+export type AnnouncePoliteness = 'polite' | 'assertive';
+/**
+ * How long {@link announce} waits before writing a message, so a burst of
+ * calls (a combobox re-filtering on every keystroke) collapses into the one
+ * announcement the user actually cares about instead of a queue of stale
+ * ones.
+ */
+export declare const ANNOUNCE_DEBOUNCE_MS = 150;
+/**
+ * Announces `message` to screen readers through a process-wide `aria-live`
+ * region, without rendering anything into your own tree — for state changes
+ * that have no visible text of their own (a filtered result count, a
+ * re-sorted column).
+ *
+ * Debounced by {@link ANNOUNCE_DEBOUNCE_MS} and deduplicated: only the last
+ * message in a burst is written, and a message identical to what the region
+ * already holds is skipped (writing the same text back is not a DOM change,
+ * so assistive tech would ignore it anyway). Empty/whitespace messages are
+ * ignored. No-ops during SSR.
+ *
+ * @example
+ * ```ts
+ * announce(`${results.length} results available`);
+ * announce('Upload failed', 'assertive');
+ * ```
+ */
+export declare function announce(message: string, politeness?: AnnouncePoliteness): void;
+/**
+ * Empties the live region(s) and drops any debounced message still waiting to
+ * be written — pass a politeness to clear just one. Mostly useful between
+ * tests, and when navigating away from the thing a pending message describes.
+ */
+export declare function clearAnnouncements(politeness?: AnnouncePoliteness): void;
+/** What {@link useLiveAnnouncer} returns. */
+export interface LiveAnnouncerApi {
+    /** See {@link announce}. */
+    announce: (message: string, politeness?: AnnouncePoliteness) => void;
+    /** See {@link clearAnnouncements}. */
+    clear: (politeness?: AnnouncePoliteness) => void;
+}
+/**
+ * Hook form of {@link announce} — returns a stable `{ announce, clear }` pair,
+ * safe to list in a `useEffect`/`useCallback` dependency array.
+ *
+ * @example
+ * ```tsx
+ * const { announce } = useLiveAnnouncer();
+ * React.useEffect(() => announce(`${count} results available`), [count, announce]);
+ * ```
+ */
+export declare function useLiveAnnouncer(): LiveAnnouncerApi;
+/** Props for {@link LiveAnnouncer}. */
+export interface LiveAnnouncerProps {
+    /** Announced whenever this value changes. An empty string announces nothing. */
+    message: string;
+    /**
+     * Which live region to announce through.
+     * @default 'polite'
+     */
+    politeness?: AnnouncePoliteness;
+}
+/**
+ * Declarative form of {@link announce}: renders nothing, and announces
+ * `message` every time it changes. Use it when the message is already a
+ * render-time value; use {@link useLiveAnnouncer} when it isn't (inside an
+ * event handler).
+ *
+ * @example
+ * ```tsx
+ * <LiveAnnouncer message={`${results.length} results available`} />
+ * ```
+ */
+export declare function LiveAnnouncer({ message, politeness }: LiveAnnouncerProps): null;
+export declare namespace LiveAnnouncer {
+    var displayName: string;
+}

package/dist/utils/liveAnnouncer.d.ts

@@ -0,0 +1,77 @@
+/** Which of the two singleton live regions a message is routed to. */
+export type AnnouncePoliteness = 'polite' | 'assertive';
+/**
+ * How long {@link announce} waits before writing a message, so a burst of
+ * calls (a combobox re-filtering on every keystroke) collapses into the one
+ * announcement the user actually cares about instead of a queue of stale
+ * ones.
+ */
+export declare const ANNOUNCE_DEBOUNCE_MS = 150;
+/**
+ * Announces `message` to screen readers through a process-wide `aria-live`
+ * region, without rendering anything into your own tree — for state changes
+ * that have no visible text of their own (a filtered result count, a
+ * re-sorted column).
+ *
+ * Debounced by {@link ANNOUNCE_DEBOUNCE_MS} and deduplicated: only the last
+ * message in a burst is written, and a message identical to what the region
+ * already holds is skipped (writing the same text back is not a DOM change,
+ * so assistive tech would ignore it anyway). Empty/whitespace messages are
+ * ignored. No-ops during SSR.
+ *
+ * @example
+ * ```ts
+ * announce(`${results.length} results available`);
+ * announce('Upload failed', 'assertive');
+ * ```
+ */
+export declare function announce(message: string, politeness?: AnnouncePoliteness): void;
+/**
+ * Empties the live region(s) and drops any debounced message still waiting to
+ * be written — pass a politeness to clear just one. Mostly useful between
+ * tests, and when navigating away from the thing a pending message describes.
+ */
+export declare function clearAnnouncements(politeness?: AnnouncePoliteness): void;
+/** What {@link useLiveAnnouncer} returns. */
+export interface LiveAnnouncerApi {
+    /** See {@link announce}. */
+    announce: (message: string, politeness?: AnnouncePoliteness) => void;
+    /** See {@link clearAnnouncements}. */
+    clear: (politeness?: AnnouncePoliteness) => void;
+}
+/**
+ * Hook form of {@link announce} — returns a stable `{ announce, clear }` pair,
+ * safe to list in a `useEffect`/`useCallback` dependency array.
+ *
+ * @example
+ * ```tsx
+ * const { announce } = useLiveAnnouncer();
+ * React.useEffect(() => announce(`${count} results available`), [count, announce]);
+ * ```
+ */
+export declare function useLiveAnnouncer(): LiveAnnouncerApi;
+/** Props for {@link LiveAnnouncer}. */
+export interface LiveAnnouncerProps {
+    /** Announced whenever this value changes. An empty string announces nothing. */
+    message: string;
+    /**
+     * Which live region to announce through.
+     * @default 'polite'
+     */
+    politeness?: AnnouncePoliteness;
+}
+/**
+ * Declarative form of {@link announce}: renders nothing, and announces
+ * `message` every time it changes. Use it when the message is already a
+ * render-time value; use {@link useLiveAnnouncer} when it isn't (inside an
+ * event handler).
+ *
+ * @example
+ * ```tsx
+ * <LiveAnnouncer message={`${results.length} results available`} />
+ * ```
+ */
+export declare function LiveAnnouncer({ message, politeness }: LiveAnnouncerProps): null;
+export declare namespace LiveAnnouncer {
+    var displayName: string;
+}

package/dist/utils/liveAnnouncer.js

@@ -0,0 +1 @@
+import*as c from"react";var a=150,l="position:absolute;border:0;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0, 0, 0, 0);white-space:nowrap;word-wrap:normal;",d=["polite","assertive"],o=new Map;function u(n){return document.querySelector(`[data-skdx-live-announcer="${n}"]`)}function r(n){let e=u(n);if(e)return e;let t=document.createElement("div");return t.setAttribute("aria-live",n),t.setAttribute("aria-atomic","true"),t.setAttribute("data-skdx-live-announcer",n),t.style.cssText=l,document.body.appendChild(t),t}function s(n,e="polite"){if(typeof document>"u")return;let t=n.trim();t&&(r(e),clearTimeout(o.get(e)),o.set(e,setTimeout(()=>{o.delete(e);let i=r(e);i.textContent!==t&&(i.textContent=t)},a)))}function p(n){for(let e of d){if(n!==void 0&&e!==n)continue;clearTimeout(o.get(e)),o.delete(e);let t=u(e);t&&(t.textContent="")}}var A={announce:s,clear:p};function m(){return A}function f({message:n,politeness:e="polite"}){return c.useEffect(()=>{s(n,e)},[n,e]),null}f.displayName="LiveAnnouncer";export{a as ANNOUNCE_DEBOUNCE_MS,f as LiveAnnouncer,s as announce,p as clearAnnouncements,m as useLiveAnnouncer};

package/dist/utils/menuSub.cjs

@@ -0,0 +1 @@
+"use strict";var I=Object.create;var P=Object.defineProperty;var O=Object.getOwnPropertyDescriptor;var A=Object.getOwnPropertyNames;var K=Object.getPrototypeOf,_=Object.prototype.hasOwnProperty;var F=(e,o)=>{for(var a in o)P(e,a,{get:o[a],enumerable:!0})},T=(e,o,a,t)=>{if(o&&typeof o=="object"||typeof o=="function")for(let i of A(o))!_.call(e,i)&&i!==a&&P(e,i,{get:()=>o[i],enumerable:!(t=O(o,i))||t.enumerable});return e};var q=(e,o,a)=>(a=e!=null?I(K(e)):{},T(o||!e||!e.__esModule?P(a,"default",{value:e,enumerable:!0}):a,e)),B=e=>T(P({},"__esModule",{value:!0}),e);var W={};F(W,{MENU_BRANCH_ATTRIBUTE:()=>x,MenuSub:()=>L,MenuSubContent:()=>k,MenuSubTrigger:()=>D});module.exports=B(W);var r=q(require("react"),1),C=require("./composeRefs.cjs"),S=require("./createContext.cjs"),d=require("./direction.cjs"),M=require("./part.cjs"),R=require("./popper.cjs"),y=require("./portal.cjs"),c=require("./primitive.cjs"),E=require("./useControllableState.cjs"),v=require("./useOpenChangeComplete.cjs"),h=require("./useRovingFocus.cjs"),p=require("react/jsx-runtime"),w='[role^="menuitem"]:not([data-disabled])',x="data-skdx-menu-branch",U=150,[V,N]=(0,S.createSafeContext)("MenuSub");function L({family:e,children:o,open:a,defaultOpen:t=!1,onOpenChange:i,onOpenChangeComplete:s}){let m=r.useRef(null),n=r.useRef(null),u=r.useRef(void 0),[b=!1,l]=(0,E.useControllableState)({prop:a,defaultProp:t,onChange:i});(0,v.useOpenChangeComplete)(b,n,s),r.useEffect(()=>()=>clearTimeout(u.current),[]);let f=r.useCallback(()=>{clearTimeout(u.current),l(!0)},[l]),g=r.useCallback(()=>{clearTimeout(u.current),l(!1)},[l]),H=r.useCallback(()=>{clearTimeout(u.current),u.current=setTimeout(()=>l(!1),U)},[l]);return(0,p.jsx)(R.PopperRoot,{children:(0,p.jsx)(V,{family:e,open:b,openNow:f,closeNow:g,scheduleClose:H,triggerRef:m,contentRef:n,contentId:r.useId(),children:o})})}L.displayName="MenuSub";var D=r.forwardRef(({disabled:e,...o},a)=>{let t=N("MenuSubTrigger"),i=(0,C.useComposedRefs)(a,t.triggerRef),s=(0,d.useDirection)(),m=()=>{t.openNow(),requestAnimationFrame(()=>{let n=t.contentRef.current;(n?.querySelector(w)??n)?.focus()})};return(0,p.jsx)(R.PopperAnchor,{asChild:!0,children:(0,p.jsx)(c.Primitive.div,{role:"menuitem","aria-haspopup":"menu","aria-expanded":t.open,"aria-controls":t.contentId,"data-state":t.open?"open":"closed","data-disabled":e?"":void 0,"aria-disabled":e||void 0,tabIndex:e?void 0:-1,...o,...(0,M.skdxPart)(t.family,"sub-trigger",o.className),ref:i,onClick:(0,c.composeEventHandlers)(o.onClick,()=>{e||m()}),onKeyDown:(0,c.composeEventHandlers)(o.onKeyDown,n=>{if(e)return;let u=(0,d.directionalKey)(n.key,n.currentTarget,s);["ArrowRight","Enter"," "].includes(u)&&(n.preventDefault(),n.stopPropagation(),m())}),onPointerEnter:(0,c.composeEventHandlers)(o.onPointerEnter,n=>{e||(n.currentTarget.focus(),t.openNow())}),onPointerLeave:(0,c.composeEventHandlers)(o.onPointerLeave,()=>{e||t.scheduleClose()})})})});D.displayName="MenuSubTrigger";var k=r.forwardRef(({forceMount:e,loop:o=!0,side:a="end",align:t="start",sideOffset:i=0,...s},m)=>{let n=N("MenuSubContent"),u=(0,C.useComposedRefs)(m,n.contentRef),b=(0,d.useDirection)(),l=(0,h.useRovingFocus)({orientation:"vertical",loop:o,itemSelector:w,typeahead:!0});return e||n.open?(0,p.jsx)(y.Portal,{[x]:"",children:(0,p.jsx)(R.PopperContent,{role:"menu","aria-orientation":"vertical",id:n.contentId,"data-state":n.open?"open":"closed",tabIndex:-1,side:a,align:t,sideOffset:i,...s,...(0,M.skdxPart)(n.family,"sub-content",s.className),ref:u,onKeyDown:(0,c.composeEventHandlers)(s.onKeyDown,f=>{let g=(0,d.directionalKey)(f.key,f.currentTarget,b);g==="ArrowLeft"||g==="Escape"?(f.preventDefault(),n.closeNow(),n.triggerRef.current?.focus()):l(f),f.key!=="Tab"&&f.stopPropagation()}),onPointerEnter:(0,c.composeEventHandlers)(s.onPointerEnter,n.openNow),onPointerLeave:(0,c.composeEventHandlers)(s.onPointerLeave,n.scheduleClose)})}):null});k.displayName="MenuSubContent";0&&(module.exports={MENU_BRANCH_ATTRIBUTE,MenuSub,MenuSubContent,MenuSubTrigger});

package/dist/utils/menuSub.d.cts

@@ -0,0 +1,120 @@
+import * as React from 'react';
+import { type PopperContentProps } from './popper.cjs';
+import { type PrimitivePropsWithRef } from './primitive.cjs';
+/**
+ * Marks a portalled submenu panel as belonging to the menu that opened it.
+ *
+ * A menu passes `[${MENU_BRANCH_ATTRIBUTE}]` to `useDismiss` as its
+ * `insideSelector`, so the panel counts as inside despite no longer being
+ * `contains()`-reachable from the menu's content ref.
+ *
+ * Deliberately valueless rather than keyed to the owning menu's id, which would
+ * mean threading that id through three families for a distinction nothing can
+ * observe: opening a second menu dismisses the first through *its* trigger's
+ * pointer-down, which is outside either way, so two menus are never open with
+ * a submenu between them.
+ */
+export declare const MENU_BRANCH_ATTRIBUTE = "data-skdx-menu-branch";
+/** Props for a menu submenu root ({@link MenuSub}). */
+export interface MenuSubProps {
+    /**
+     * The re-exporting family, e.g. `'context-menu'`, which is what lets the
+     * shared parts name their own classes. Supplied by the family wrapper
+     * (`DropdownMenuSub`, `ContextMenuSub`, `MenubarSub`), never by an
+     * application — each wrapper `Omit`s it from its own props for that reason.
+     *
+     * Written as a description followed by the tag, not as tag text: the docs
+     * manifest takes a member's summary from the text *before* the first block
+     * tag, so `@internal The re-exporting family…` left all three wrappers
+     * reported as having an undescribed prop.
+     *
+     * @internal
+     */
+    family: string;
+    /**
+     * The `SubTrigger` and `SubContent` parts of this submenu.
+     * @default undefined — renders nothing if omitted.
+     */
+    children?: React.ReactNode;
+    /**
+     * Whether the submenu is open, for controlled usage. Pair with `onOpenChange`.
+     * @default undefined — uncontrolled, tracks its own open state internally.
+     */
+    open?: boolean;
+    /**
+     * Whether the submenu is initially open, for uncontrolled usage.
+     * @default false
+     */
+    defaultOpen?: boolean;
+    /**
+     * Fires with the new open state whenever the submenu opens or closes, controlled or not.
+     * @default undefined — no-op if omitted.
+     */
+    onOpenChange?: (open: boolean) => void;
+    /**
+     * Fires with the new open state once the change has finished on screen —
+     * after `SubContent`'s enter or exit animation ends, or as soon as it has
+     * settled when the panel declares no animation. Use it for work that must not race
+     * the transition; use `onOpenChange` for work that must not wait for it.
+     * @default undefined — no-op if omitted.
+     */
+    onOpenChangeComplete?: (open: boolean) => void;
+}
+/** Props for a menu submenu trigger ({@link MenuSubTrigger}). */
+export interface MenuSubTriggerProps extends PrimitivePropsWithRef<'div'> {
+    /**
+     * Excludes the trigger from roving-focus navigation and blocks it from opening the submenu.
+     * @default false
+     */
+    disabled?: boolean;
+}
+/**
+ * Props for a menu submenu panel ({@link MenuSubContent}). Extends the shared
+ * popper positioning props (`side`, `align`, `sideOffset`, `alignOffset`,
+ * `avoidCollisions`, `collisionPadding`).
+ */
+export interface MenuSubContentProps extends PopperContentProps {
+    /**
+     * Keep this panel mounted even while the submenu is closed. Useful for
+     * animation libraries that need the outgoing panel present in the DOM
+     * during an exit transition.
+     * @default false
+     */
+    forceMount?: boolean;
+    /**
+     * Whether Up/Down arrow-key navigation wraps from the last item back to
+     * the first (and vice versa).
+     * @default true
+     */
+    loop?: boolean;
+}
+/**
+ * @internal Root of a nested submenu: owns the submenu's open state and the
+ * hover grace timer, and provides a nested popper anchor context so
+ * `MenuSubContent` positions against `MenuSubTrigger`. Renders no DOM element
+ * itself.
+ */
+export declare function MenuSub({ family, children, open: openProp, defaultOpen, onOpenChange, onOpenChangeComplete, }: MenuSubProps): React.JSX.Element;
+export declare namespace MenuSub {
+    var displayName: string;
+}
+/**
+ * @internal The parent-menu item that opens a submenu: `role="menuitem"` with
+ * `aria-haspopup="menu"`, `aria-expanded`, `aria-controls` and `data-state`.
+ * Doubles as the popper anchor for `MenuSubContent`. Opens on click, Enter,
+ * Space and ArrowRight (moving focus to the submenu's first item), and on
+ * hover (leaving focus where it is). Under `dir="rtl"` the opening key is
+ * ArrowLeft instead.
+ */
+export declare const MenuSubTrigger: React.ForwardRefExoticComponent<Omit<MenuSubTriggerProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+/**
+ * @internal The submenu's floating panel: `role="menu"` with
+ * `aria-orientation="vertical"` and `data-state`, positioned by the shared
+ * popper layer against its `MenuSubTrigger` (`side="end"`, `align="start"` by
+ * default — logical, so it opens to the right under LTR and to the left under
+ * RTL) and exposing the resolved `data-side`/`data-align`. Owns vertical
+ * roving focus and typeahead over its own items; ArrowLeft and Escape close
+ * it and return focus to the trigger, leaving the parent menu open — under
+ * `dir="rtl"` the closing arrow is ArrowRight.
+ */
+export declare const MenuSubContent: React.ForwardRefExoticComponent<Omit<MenuSubContentProps, "ref"> & React.RefAttributes<HTMLDivElement>>;