@skdx/react 0.26.0 → 0.28.0

package/dist/multi-select/types.d.ts

@@ -1,17 +1,56 @@
 import type * as React from 'react';
 import type { TagGroupProps } from '../tag-group/types.js';
 import type { TagProps } from '../tag/types.js';
+import type { FormValidityHandle } from '../utils/formControl.js';
+import type { PassThroughProps } from '../utils/passThrough.js';
 import type { PopperContentProps } from '../utils/popper.js';
 import type { PortalProps } from '../utils/portal.js';
 import type { PrimitivePropsWithRef } from '../utils/primitive.js';
 import type { FocusOutsideEvent, InteractOutsideEvent } from '../utils/useDismiss.js';
 import type { OptionEntry } from '../utils/useOptionCollection.js';
+/** One option for the {@link MultiSelectProps.options} recipe prop — a flat entry rendered as a `MultiSelectItem`/`MultiSelectTag`. */
+export interface MultiSelectOption {
+    /** Value added to (or removed from) the selection when this option is chosen. */
+    value: string;
+    /**
+     * Text shown by the tag and matched by `filter`.
+     * @default undefined — falls back to `value`.
+     */
+    label?: string;
+    /**
+     * Excludes this option from selection and pointer highlight.
+     * @default false
+     */
+    disabled?: boolean;
+}
+/** A labeled group of {@link MultiSelectOption}s for {@link MultiSelectProps.options} — grouping is data, never a wrapper component. */
+export interface MultiSelectOptionGroup {
+    /** Heading rendered as a `MultiSelectGroupLabel` above this group's options. */
+    label: string;
+    /** The options belonging to this group. */
+    options: MultiSelectOption[];
+}
+/** One entry of {@link MultiSelectProps.options}: a flat option, or a labeled group of them. */
+export type MultiSelectOptionOrGroup = MultiSelectOption | MultiSelectOptionGroup;
 /**
- * Decides which `MultiSelectItem`s survive the current draft text.
- * `undefined` filters nothing — the consumer renders only the options that
- * match, which is what an async or server-side search needs.
+ * Filter predicate; returns boolean or score for ranking (0 excludes, positive keeps).
  */
-export type MultiSelectFilter = (itemText: string, inputValue: string) => boolean;
+export type MultiSelectFilter = (itemText: string, inputValue: string) => boolean | number;
+/**
+ * Payload for `onValueChange`; includes new selection, reason, and diff details.
+ */
+export interface MultiSelectValueChangeDetail {
+    /** The new selection in selection order. */
+    value: string[];
+    /** Previous selection or null. */
+    previousValue: string[] | null;
+    /** What drove the change. */
+    reason: 'keyboard' | 'pointer' | 'programmatic';
+    /** Newly selected values. */
+    added: string[];
+    /** Deselected values. */
+    removed: string[];
+}
 /** @internal Shared state distributed from {@link MultiSelect} to its parts via context. Not part of the public API. */
 export interface MultiSelectContextValue {
     inputRef: React.RefObject<HTMLInputElement | null>;
@@ -20,169 +59,215 @@ export interface MultiSelectContextValue {
     listId: string;
     /** Every selected value, in selection order — the same array `MultiSelectTagList` renders. */
     value: string[];
-    /** Whether one option value is currently selected. */
     isSelected: (value: string) => boolean;
-    /** Toggles an option within the selection, honouring `max` and `closeOnSelect`. */
-    toggle: (value: string) => void;
-    /** Removes one value from the selection — what a tag's remove button and Backspace both call. */
+    /** Toggles an option, honours max and closeOnSelect. */
+    toggle: (value: string, reason: MultiSelectValueChangeDetail['reason']) => void;
+    /** Selects options between range anchor and highlight. */
+    selectRange: () => void;
+    /** Selects from highlight to list edge. */
+    selectToEdge: (edge: 'first' | 'last') => void;
+    /** Toggles all enabled options. */
+    selectAllOrClear: () => void;
+    /** Whether Control+A selects/clears while open. */
+    allowSelectAll: boolean;
     deselect: (value: string) => void;
-    /** Removes the last selected value; Backspace on an empty input. */
     removeLast: () => void;
-    /** Whether the selection has reached `max`, so unselected options are inert. */
     atMax: boolean;
     inputValue: string;
     onInputValueChange: (value: string) => void;
     open: boolean;
     onOpenChange: (open: boolean) => void;
     activeId: string | null;
+    /** CSS order when filter scores items; null leaves order untouched. */
+    itemOrder: ReadonlyMap<string, number> | null;
     setActiveId: (id: string | null) => void;
-    moveActive: (direction: 1 | -1) => void;
+    moveActive: (direction: 1 | -1) => string | null;
+    moveActiveToEdge: (edge: 'first' | 'last') => string | null;
     openWithHighlight: (edge: 'first' | 'last') => void;
     itemCount: number;
     registerItem: (id: string, entry: OptionEntry) => void;
     unregisterItem: (id: string) => void;
     getItem: (id: string) => OptionEntry | undefined;
-    /** Whether an item with this text survives the current `filter` and draft text. */
+    /** Whether item survives filter and draft text. */
     matchesFilter: (itemText: string) => boolean;
     disabled: boolean;
     readOnly: boolean;
     invalid: boolean;
+    loading: boolean;
+    /** Clears selection and draft text. */
+    clear: () => void;
 }
-/** Props for the {@link MultiSelect} root. */
-export interface MultiSelectProps {
+/**
+ * Forwarded ref carrying constraint-validation methods.
+ */
+export type MultiSelectHandle = FormValidityHandle;
+/**
+ * Props for the MultiSelect root; passes attributes to derived input.
+ */
+export interface MultiSelectProps extends PassThroughProps {
     /**
-     * The `MultiSelectTagList`/`MultiSelectInput`/`MultiSelectContent` parts,
-     * rendered as children — `MultiSelect` itself renders no DOM, so the field
-     * that visually wraps the tags and the input is yours to lay out.
-     * @default undefined — renders nothing without children.
+     * The `MultiSelectTagList`, `MultiSelectInput` and `MultiSelectContent` parts, composed as children.
+     * @default undefined
      */
     children?: React.ReactNode;
     /**
-     * Selected values in selection order, for controlled usage. Pair with `onValueChange`.
-     * @default undefined — uncontrolled, tracks its own selection internally.
+     * Selected values, in selection order; for controlled usage.
+     * @default undefined
      */
     value?: string[];
     /**
-     * Initially selected values, for uncontrolled usage.
-     * @default [] — nothing selected, so no tags are rendered.
+     * Initially selected values for uncontrolled usage.
+     * @default []
      */
     defaultValue?: string[];
     /**
-     * Fires with the whole new selection whenever it changes — not the toggled
-     * value — so the array can be written straight back to state.
-     * @default undefined — no-op if omitted.
+     * Fires on selection changes with new selection, reason, and diff.
+     * @default undefined
      */
-    onValueChange?: (value: string[]) => void;
+    onValueChange?: (detail: MultiSelectValueChangeDetail) => void;
     /**
-     * The draft text in the input, for controlled usage. Pair with
-     * `onInputValueChange` — typically used to filter the option list, since
-     * filtering is the consumer's job unless `filter` is supplied.
-     * @default undefined — uncontrolled, tracks its own draft text internally.
+     * Draft text in input for controlled usage; narrows option list.
+     * @default undefined
      */
     inputValue?: string;
     /**
-     * Initial draft text, for uncontrolled usage.
+     * Initial draft text for uncontrolled usage.
      * @default ''
      */
     defaultInputValue?: string;
     /**
-     * Fires with the new draft text on every keystroke, and with `''` when a
-     * selection clears it.
-     * @default undefined — no-op if omitted.
+     * Fires with new draft text on keystroke.
+     * @default undefined
      */
     onInputValueChange?: (inputValue: string) => void;
     /**
-     * Whether the option popup is open, for controlled usage. Pair with `onOpenChange`.
-     * @default undefined — uncontrolled, tracks its own open state internally.
+     * Whether popup is open for controlled usage.
+     * @default undefined
      */
     open?: boolean;
     /**
-     * Initial open state, for uncontrolled usage.
+     * Initial open state for uncontrolled usage.
      * @default false
      */
     defaultOpen?: boolean;
     /**
-     * Fires with the new open state whenever it changes, controlled or not.
-     * @default undefined — no-op if omitted.
+     * Fires with the new open state whenever it changes.
+     * @default undefined
      */
     onOpenChange?: (open: boolean) => void;
     /**
-     * Fires with the new open state once the change has finished on screen —
-     * after `MultiSelectContent`'s enter or exit animation ends, or as soon as it
-     * has settled when the popup declares no animation. Use it for work that must
-     * not race the transition; use `onOpenChange` for work that must not wait for it.
-     * @default undefined — no-op if omitted.
+     * Fires once the popup animation completes.
+     * @default undefined
      */
     onOpenChangeComplete?: (open: boolean) => void;
     /**
-     * Largest number of values that can be selected. Once reached, unselected
-     * options become `aria-disabled` and stop responding rather than silently
-     * swallowing clicks; already-selected ones stay removable.
-     * @default undefined — no cap.
+     * Largest number of values selectable. Once reached, unselected options go aria-disabled; selected ones stay removable.
+     * @default undefined
      */
     max?: number;
     /**
-     * Close the popup after each selection. Off by default, which is the whole
-     * ergonomic point of a multi-select: picking five things should cost five
-     * clicks, not five clicks and five reopenings.
+     * Close the popup after each selection instead of staying open.
      * @default false
      */
     closeOnSelect?: boolean;
     /**
-     * Predicate deciding which `MultiSelectItem`s survive the current draft
-     * text. Rejected items render nothing at all, so they leave the option
-     * count and the highlight order exactly as if the consumer had removed them.
-     * @default undefined — nothing is filtered; the consumer renders only the matching items.
+     * Predicate deciding which items survive the current draft text. Returns a boolean to filter, or a number to filter and rank (0 excludes, positive keeps).
+     * @default undefined
      */
     filter?: MultiSelectFilter;
     /**
-     * Blocks all interaction: the input is natively `disabled`, tags cannot be
-     * removed, and the popup can never open.
+     * Whether Control+A selects every enabled option while the popup is open.
+     * @default true
+     */
+    allowSelectAll?: boolean;
+    /**
+     * Whether the option list is in flight; suppresses the selection-count announcement until options arrive.
+     * @default false
+     */
+    loading?: boolean;
+    /**
+     * Blocks all interaction: input is disabled, tags cannot be removed, popup never opens.
      * @default false
      */
     disabled?: boolean;
     /**
-     * Shows the selection but blocks any change to it — the input is natively
-     * `readOnly` and still focusable (unlike `disabled`), tags are not
-     * removable, and no option can be toggled.
+     * Shows selection but blocks changes — input stays focusable, tags not removable, no option can toggle.
      * @default false
      */
     readOnly?: boolean;
     /**
-     * Marks the field as invalid, exposed as `aria-invalid`/`data-invalid` on
-     * `MultiSelectInput`.
+     * Marks the field invalid, exposed as aria-invalid on the Input.
      * @default false
      */
     invalid?: boolean;
     /**
-     * Formats the message announced (through the shared `LiveAnnouncer`) after
-     * every selection change. Toggling an option changes `aria-selected` on a
-     * node the user is not focused on, so without this a screen-reader user gets
-     * no confirmation that anything happened. Return an empty string to announce
-     * nothing.
-     * @default defaultGetSelectionLabel — e.g. `"2 selected"`
+     * Form field name. One hidden control per selected value produces repeated name=value entries like a native <select multiple>; draft text never submits.
+     * @default undefined
+     */
+    name?: string;
+    /**
+     * Marks the multi-select required: empty selection reports valueMissing. Meaningful only with name.
+     * @default false
+     */
+    required?: boolean;
+    /**
+     * Id of the <form> the multi-select submits into, so it can live outside its owning form.
+     * @default undefined
+     */
+    form?: string;
+    /**
+     * Formats the message announced after each selection change. Without this, screen-reader users get no confirmation that anything happened. Return empty string to announce nothing. Counts *selected* options, not rendered options.
+     * @default defaultGetSelectionLabel
      */
     getSelectionLabel?: (count: number) => string;
+    /**
+     * Flat or grouped option data to render tag list, input, Clear button, and listbox automatically, instead of hand composing parts. Ignored under full manual composition. Property-only on <skdx-multi-select>: an HTML attribute cannot carry an array of objects.
+     * @default undefined
+     */
+    options?: MultiSelectOptionOrGroup[];
+    /**
+     * Customises how a derived option renders inside its MultiSelectItem. Only read while options is deriving the anatomy.
+     * @default undefined
+     */
+    renderOption?: (option: MultiSelectOption, state: {
+        selected: boolean;
+    }) => React.ReactNode;
+    /**
+     * Customises a selected value's content inside its derived MultiSelectTag. Only read while options is deriving the anatomy.
+     * @default undefined
+     */
+    renderTag?: (option: MultiSelectOption) => React.ReactNode;
+    /**
+     * Placeholder for the derived MultiSelectInput. Only read while options is deriving the anatomy.
+     * @default undefined
+     */
+    placeholder?: string;
+    /**
+     * Whether the derived anatomy renders a Clear button that empties the selection and draft text in one action.
+     * @default false
+     */
+    clearable?: boolean;
+    /**
+     * Accessible name for the derived MultiSelectInput and tag list. Only read while options is deriving the anatomy.
+     * @default undefined
+     */
+    'aria-label'?: string;
 }
-/** Props for {@link MultiSelectInput}, the text field that owns real DOM focus and drives filtering. */
+/** Props for the text field that owns DOM focus and drives filtering. */
 export interface MultiSelectInputProps extends Omit<PrimitivePropsWithRef<'input'>, 'value' | 'defaultValue'> {
 }
-/**
- * Props for {@link MultiSelectTagList} — a `TagGroup`, so `orientation`,
- * `loop` and its element props all apply. `disabled` is taken from the
- * `MultiSelect` root instead.
- */
+/** Props for the TagGroup rendering one tag per selected value, in selection order. */
 export interface MultiSelectTagListProps extends Omit<TagGroupProps, 'disabled'> {
 }
-/** Props for a single {@link MultiSelectTag} — a `Tag` naming one selected value. */
+/** Props for one selected value, showing the option's text or raw value if none declared. */
 export interface MultiSelectTagProps extends Omit<TagProps, 'index' | 'value' | 'onDelete'> {
-    /** The selected value this tag stands for. Its position in the root's `value` decides the tag's place in the roving tab order. */
+    /** The selected value this tag represents. Required: it deselects when remove is clicked. */
     value: string;
 }
-/** Props for {@link MultiSelectTagRemove}, the button removing its parent tag's value from the selection. */
+/** Props for the remove button inside a tag, deselecting that value. */
 export interface MultiSelectTagRemoveProps extends PrimitivePropsWithRef<'button'> {
 }
-/** Props for {@link MultiSelectPortal}, which teleports its content to `document.body` while the popup is open. */
+/** Props for the Portal, which teleports content to `document.body` while the popup is open. */
 export interface MultiSelectPortalProps extends PortalProps {
     /**
      * Render (and mount `MultiSelectContent`) even while closed, instead of unmounting.
@@ -190,12 +275,7 @@ export interface MultiSelectPortalProps extends PortalProps {
      */
     forceMount?: boolean;
 }
-/**
- * Props for {@link MultiSelectContent}, the popup shell. Extends
- * {@link PopperContentProps} for floating-ui positioning relative to the
- * input — note it defaults `side` to `'bottom'`, `align` to `'start'` and
- * `sideOffset` to `4`, instead of the popper base defaults.
- */
+/** Props for the popup shell, positioned against the input via the shared popper layer. */
 export interface MultiSelectContentProps extends PopperContentProps {
     /**
      * Keep this popup mounted even while closed, instead of unmounting it.
@@ -203,43 +283,58 @@ export interface MultiSelectContentProps extends PopperContentProps {
      */
     forceMount?: boolean;
     /**
-     * Fires when Escape is pressed while the popup is open. Call `event.preventDefault()` to stop it from closing.
-     * @default undefined — no-op if omitted.
+     * Fires when Escape is pressed while the popup is open. Call `event.preventDefault()` to prevent closing.
+     * @default undefined
      */
     onEscapeKeyDown?: (event: KeyboardEvent) => void;
     /**
-     * Fires on pointer-down outside the popup and the input. Call `event.preventDefault()` to stop the popup from closing.
-     * @default undefined — no-op if omitted.
+     * Fires on pointer-down outside the popup and the input. Call `event.preventDefault()` to prevent closing.
+     * @default undefined
      */
     onPointerDownOutside?: (event: PointerEvent) => void;
     /**
-     * Fires when focus moves to an element outside the popup and the input. Call `event.preventDefault()` to stop the popup from closing. Receives a cancelable stand-in carrying the original `focusin` as its `detail`, since `focusin` itself cannot be canceled.
-     * @default undefined — no-op if omitted.
+     * Fires when focus moves outside the popup and the input. Call `event.preventDefault()` to prevent closing. Receives a cancelable stand-in carrying the original `focusin` as its `detail`, since `focusin` itself cannot be canceled.
+     * @default undefined
      */
     onFocusOutside?: (event: FocusOutsideEvent) => void;
     /**
-     * Fires for either kind of outside interaction — pointer-down or focus — immediately before the specific handler above and with the same event, so one `event.preventDefault()` here vetoes the dismissal whichever way it was triggered.
-     * @default undefined — no-op if omitted.
+     * Fires for either kind of outside interaction — pointer-down or focus — immediately before the specific handler and with the same event. One `event.preventDefault()` here vetoes the dismissal whichever way it was triggered.
+     * @default undefined
      */
     onInteractOutside?: (event: InteractOutsideEvent) => void;
 }
-/** Props for {@link MultiSelectList}, the multi-selectable `role="listbox"`. */
+/** Props for the role="listbox" with aria-multiselectable, referenced by Input's aria-controls. */
 export interface MultiSelectListProps extends PrimitivePropsWithRef<'div'> {
 }
-/** Props for a single {@link MultiSelectItem} option within `MultiSelectList`. */
+/** Props for one option (role="option") with aria-selected reflecting membership. */
 export interface MultiSelectItemProps extends PrimitivePropsWithRef<'div'> {
-    /** Value added to (or removed from) the root's selection when this option is chosen. */
+    /** Value added to or removed from the root's selection when this option is chosen. */
     value: string;
     /**
-     * Excludes this option from selection and pointer highlight.
+     * Excludes this option from selection and highlight.
      * @default false
      */
     disabled?: boolean;
     /**
-     * Text the root's `filter` predicate matches against, and the text a
-     * `MultiSelectTag` shows when none is given. Only needed when the item
-     * renders more than its label.
-     * @default undefined — falls back to the item's rendered text content.
+     * Text the root's `filter` predicate matches against, and the text a `MultiSelectTag` shows when none is given. Falls back to the item's rendered text content.
+     * @default undefined
      */
     textValue?: string;
 }
+/** Props for the button that empties selection and draft text in one press, returning focus to Input. */
+export interface MultiSelectClearProps extends PrimitivePropsWithRef<'button'> {
+}
+/** @internal Wiring passed from a MultiSelectGroup to its MultiSelectGroupLabel. Not part of the public API. */
+export interface MultiSelectGroupContextValue {
+    /** The id the group points `aria-labelledby` at, which its GroupLabel claims. */
+    labelId: string;
+}
+/** Props for a named section of options (role="group"), pointing aria-labelledby at its GroupLabel. */
+export interface MultiSelectGroupProps extends PrimitivePropsWithRef<'div'> {
+}
+/** Props for the heading naming its Group, carrying the id for the Group's aria-labelledby. */
+export interface MultiSelectGroupLabelProps extends PrimitivePropsWithRef<'div'> {
+}
+/** Props for content shown when List renders no options. */
+export interface MultiSelectEmptyProps extends PrimitivePropsWithRef<'div'> {
+}

package/dist/navigation-menu/NavigationMenu.cjs

@@ -1 +1 @@
-"use strict";var le=Object.create;var R=Object.defineProperty;var ve=Object.getOwnPropertyDescriptor;var fe=Object.getOwnPropertyNames;var de=Object.getPrototypeOf,pe=Object.prototype.hasOwnProperty;var Ne=(t,e)=>{for(var n in e)R(t,n,{get:e[n],enumerable:!0})},S=(t,e,n,o)=>{if(e&&typeof e=="object"||typeof e=="function")for(let i of fe(e))!pe.call(t,i)&&i!==n&&R(t,i,{get:()=>e[i],enumerable:!(o=ve(e,i))||o.enumerable});return t};var f=(t,e,n)=>(n=t!=null?le(de(t)):{},S(e||!t||!t.__esModule?R(n,"default",{value:t,enumerable:!0}):n,t)),Me=t=>S(R({},"__esModule",{value:!0}),t);var we={};Ne(we,{NavigationMenu:()=>A,NavigationMenuContent:()=>b,NavigationMenuIndicator:()=>H,NavigationMenuItem:()=>E,NavigationMenuLink:()=>D,NavigationMenuList:()=>x,NavigationMenuRootProvider:()=>z,NavigationMenuTrigger:()=>k,useNavigationMenuContext:()=>c});module.exports=Me(we);var a=f(require("react"),1),K=require("../utils/createContext.cjs"),O=require("../utils/part.cjs"),V=require("../utils/primitive.cjs"),B=require("../utils/useControllableState.cjs"),I=require("react/jsx-runtime"),Re=150,[z,c]=(0,K.createSafeContext)("NavigationMenu"),A=a.forwardRef(({value:t,defaultValue:e,onValueChange:n,delayDuration:o=200,skipDelayDuration:i=300,...u},l)=>{let r=a.useRef(!0),g=a.useRef(0),s=a.useRef(0),y=a.useRef(0),[ue="",m]=(0,B.useControllableState)({prop:t,defaultProp:e??"",onChange:v=>{window.clearTimeout(y.current),v?r.current=!1:y.current=window.setTimeout(()=>{r.current=!0},i),n?.(v)}});a.useEffect(()=>()=>{window.clearTimeout(g.current),window.clearTimeout(s.current),window.clearTimeout(y.current)},[]);let se=a.useCallback(v=>{window.clearTimeout(s.current),window.clearTimeout(g.current),r.current?g.current=window.setTimeout(()=>m(v),o):m(v)},[m,o]),h=a.useCallback(()=>{window.clearTimeout(g.current),window.clearTimeout(s.current),s.current=window.setTimeout(()=>m(""),Re)},[m]),me=a.useCallback(()=>{window.clearTimeout(s.current)},[]),ce=a.useCallback(v=>{window.clearTimeout(g.current),window.clearTimeout(s.current),m(v)},[m]),ge=a.useCallback(()=>{window.clearTimeout(g.current),window.clearTimeout(s.current),m("")},[m]);return(0,I.jsx)(z,{value:ue,onTriggerEnter:se,onTriggerLeave:h,onContentEnter:me,onContentLeave:h,onItemSelect:ce,onClose:ge,children:(0,I.jsx)(V.Primitive.nav,{"aria-label":u["aria-label"]??"Main",...u,...(0,O.skdxPart)("navigation-menu","root",u.className),ref:l})})});A.displayName="NavigationMenu";var G=f(require("react"),1),_=require("../utils/part.cjs"),C=require("../utils/primitive.cjs"),F=require("../utils/useRovingFocus.cjs"),U=require("react/jsx-runtime"),Ce="[data-skdx-nav-trigger]",x=G.forwardRef(({loop:t=!0,...e},n)=>{let o=(0,F.useRovingFocus)({orientation:"horizontal",loop:t,itemSelector:Ce});return(0,U.jsx)(C.Primitive.ul,{"data-orientation":"horizontal",...e,...(0,_.skdxPart)("navigation-menu","list",e.className),ref:n,onKeyDown:(0,C.composeEventHandlers)(e.onKeyDown,o)})});x.displayName="NavigationMenuList";var M=f(require("react"),1),Y=require("../utils/createContext.cjs"),q=require("../utils/part.cjs"),J=require("../utils/primitive.cjs"),L=require("react/jsx-runtime"),[Pe,P]=(0,Y.createSafeContext)("NavigationMenuItem"),E=M.forwardRef(({value:t,...e},n)=>{let o=M.useId(),i=M.useId();return(0,L.jsx)(Pe,{value:t,triggerId:o,contentId:i,children:(0,L.jsx)(J.Primitive.li,{...e,...(0,q.skdxPart)("navigation-menu","item",e.className),ref:n})})});E.displayName="NavigationMenuItem";var w=f(require("react"),1),Q=require("../utils/part.cjs"),d=require("../utils/primitive.cjs");var W=require("react/jsx-runtime"),k=w.forwardRef((t,e)=>{let n=c("NavigationMenuTrigger"),o=P("NavigationMenuTrigger"),i=n.value===o.value,u=w.useRef(!1),l=()=>{i&&!u.current?n.onClose():n.onItemSelect(o.value)};return(0,W.jsx)(d.Primitive.button,{type:"button",id:o.triggerId,"aria-expanded":i,"aria-controls":o.contentId,"data-skdx-nav-trigger":"","data-state":i?"open":"closed",...t,...(0,Q.skdxPart)("navigation-menu","trigger",t.className),ref:e,onPointerEnter:(0,d.composeEventHandlers)(t.onPointerEnter,r=>{r.pointerType!=="touch"&&(u.current=!0,n.onTriggerEnter(o.value))}),onPointerLeave:(0,d.composeEventHandlers)(t.onPointerLeave,r=>{r.pointerType!=="touch"&&(u.current=!1,n.onTriggerLeave())}),onClick:(0,d.composeEventHandlers)(t.onClick,l),onKeyDown:(0,d.composeEventHandlers)(t.onKeyDown,r=>{r.key==="Escape"?(n.onClose(),r.currentTarget.focus()):[" ","Enter"].includes(r.key)&&(r.preventDefault(),l())})})});k.displayName="NavigationMenuTrigger";var N=f(require("react"),1),X=require("../utils/composeRefs.cjs"),Z=require("../utils/part.cjs"),p=require("../utils/primitive.cjs"),$=require("../utils/useDismiss.cjs");var j=require("react/jsx-runtime"),b=N.forwardRef(({forceMount:t,...e},n)=>{let o=c("NavigationMenuContent"),i=P("NavigationMenuContent"),u=o.value===i.value,l=N.useRef(null),r=(0,X.useComposedRefs)(n,l),g=N.useMemo(()=>({get current(){return typeof document>"u"?null:document.getElementById(i.triggerId)}}),[i.triggerId]);return(0,$.useDismiss)({enabled:u,onPointerDownOutside:o.onClose},[l,g]),t||u?(0,j.jsx)(p.Primitive.div,{role:"region",id:i.contentId,"aria-labelledby":i.triggerId,"data-state":u?"open":"closed",...e,...(0,Z.skdxPart)("navigation-menu","content",e.className),ref:r,onPointerEnter:(0,p.composeEventHandlers)(e.onPointerEnter,o.onContentEnter),onPointerLeave:(0,p.composeEventHandlers)(e.onPointerLeave,o.onContentLeave),onKeyDown:(0,p.composeEventHandlers)(e.onKeyDown,s=>{s.key==="Escape"&&(o.onClose(),document.getElementById(i.triggerId)?.focus())})}):null});b.displayName="NavigationMenuContent";var ee=f(require("react"),1),te=require("../utils/part.cjs"),T=require("../utils/primitive.cjs");var ne=require("react/jsx-runtime"),D=ee.forwardRef(({active:t,...e},n)=>{let o=c("NavigationMenuLink");return(0,ne.jsx)(T.Primitive.a,{"data-skdx-nav-trigger":"","data-active":t?"":void 0,"aria-current":t?"page":void 0,...e,...(0,te.skdxPart)("navigation-menu","link",e.className),ref:n,onClick:(0,T.composeEventHandlers)(e.onClick,o.onClose)})});D.displayName="NavigationMenuLink";var oe=f(require("react"),1),ie=require("../utils/part.cjs"),ae=require("../utils/primitive.cjs");var re=require("react/jsx-runtime"),H=oe.forwardRef(({forceMount:t,...e},n)=>{let i=c("NavigationMenuIndicator").value!=="";return t||i?(0,re.jsx)(ae.Primitive.div,{"data-state":i?"visible":"hidden",...e,...(0,ie.skdxPart)("navigation-menu","indicator",e.className),ref:n}):null});H.displayName="NavigationMenuIndicator";0&&(module.exports={NavigationMenu,NavigationMenuContent,NavigationMenuIndicator,NavigationMenuItem,NavigationMenuLink,NavigationMenuList,NavigationMenuRootProvider,NavigationMenuTrigger,useNavigationMenuContext});
+"use strict";var De=Object.create;var I=Object.defineProperty;var He=Object.getOwnPropertyDescriptor;var Se=Object.getOwnPropertyNames;var Be=Object.getPrototypeOf,ze=Object.prototype.hasOwnProperty;var Ke=(o,e)=>{for(var t in e)I(o,t,{get:e[t],enumerable:!0})},Y=(o,e,t,i)=>{if(e&&typeof e=="object"||typeof e=="function")for(let n of Se(e))!ze.call(o,n)&&n!==t&&I(o,n,{get:()=>e[n],enumerable:!(i=He(e,n))||i.enumerable});return o};var p=(o,e,t)=>(t=o!=null?De(Be(o)):{},Y(e||!o||!o.__esModule?I(t,"default",{value:o,enumerable:!0}):t,o)),Oe=o=>Y(I({},"__esModule",{value:!0}),o);var Fe={};Ke(Fe,{NavigationMenu:()=>F,NavigationMenuContent:()=>k,NavigationMenuIndicator:()=>E,NavigationMenuItem:()=>L,NavigationMenuItemProvider:()=>Z,NavigationMenuLink:()=>x,NavigationMenuList:()=>D,NavigationMenuRootProvider:()=>xe,NavigationMenuTrigger:()=>S,useNavigationMenuContext:()=>c,useNavigationMenuItemContext:()=>y});module.exports=Oe(Fe);var a=p(require("react"),1),Me=require("../utils/composeRefs.cjs"),Re=require("../utils/createContext.cjs"),Ce=require("../utils/part.cjs"),ye=require("../utils/primitive.cjs"),we=require("../utils/useControllableState.cjs");var M=p(require("react"),1),j=require("../utils/composeRefs.cjs"),ee=require("../utils/part.cjs"),w=require("../utils/primitive.cjs"),te=require("../utils/useDismiss.cjs");var C=p(require("react"),1),J=require("../utils/createContext.cjs"),Q=require("../utils/part.cjs"),X=require("../utils/primitive.cjs"),V=require("react/jsx-runtime"),[Z,y]=(0,J.createSafeContext)("NavigationMenuItem"),L=C.forwardRef(({value:o,...e},t)=>{let i=C.useId(),n=C.useId();return(0,V.jsx)(Z,{value:o,triggerId:i,contentId:n,children:(0,V.jsx)(X.Primitive.li,{...e,...(0,Q.skdxPart)("navigation-menu","item",e.className),ref:t})})});L.displayName="NavigationMenuItem";var oe=require("react/jsx-runtime"),k=M.forwardRef(({forceMount:o,...e},t)=>{let i=c("NavigationMenuContent"),n=y("NavigationMenuContent"),r=i.value===n.value,g=M.useRef(null),u=(0,j.useComposedRefs)(t,g),f=M.useMemo(()=>({get current(){return typeof document>"u"?null:document.getElementById(n.triggerId)}}),[n.triggerId]);return(0,te.useDismiss)({enabled:r,onEscapeKeyDown:()=>{i.onClose(),document.getElementById(n.triggerId)?.focus()},onPointerDownOutside:i.onClose,onFocusOutside:i.onClose},[g,f]),o||r?(0,oe.jsx)(w.Primitive.div,{role:"region",id:n.contentId,"aria-labelledby":n.triggerId,"data-state":r?"open":"closed",...e,...(0,ee.skdxPart)("navigation-menu","content",e.className),ref:u,onPointerEnter:(0,w.composeEventHandlers)(e.onPointerEnter,i.onContentEnter),onPointerLeave:(0,w.composeEventHandlers)(e.onPointerLeave,i.onContentLeave)}):null});k.displayName="NavigationMenuContent";var ne=p(require("react"),1),ie=require("../utils/part.cjs"),ae=require("../utils/primitive.cjs");var re=require("react/jsx-runtime"),E=ne.forwardRef(({forceMount:o,...e},t)=>{let n=c("NavigationMenuIndicator").value!==null;return o||n?(0,re.jsx)(ae.Primitive.div,{"data-state":n?"visible":"hidden",...e,...(0,ie.skdxPart)("navigation-menu","indicator",e.className),ref:t}):null});E.displayName="NavigationMenuIndicator";var ue=p(require("react"),1),se=require("../utils/part.cjs"),b=require("../utils/primitive.cjs");var me=require("react/jsx-runtime"),x=ue.forwardRef(({active:o,...e},t)=>{let i=c("NavigationMenuLink");return(0,me.jsx)(b.Primitive.a,{"data-skdx-nav-trigger":"","data-active":o?"":void 0,"aria-current":o?"page":void 0,...e,...(0,se.skdxPart)("navigation-menu","link",e.className),ref:t,onClick:(0,b.composeEventHandlers)(e.onClick,i.onLinkSelect)})});x.displayName="NavigationMenuLink";var ce=p(require("react"),1),le=require("../utils/part.cjs"),h=require("../utils/primitive.cjs"),ge=require("../utils/useRovingFocus.cjs");var fe=require("react/jsx-runtime"),Ae=":scope > li > [data-skdx-nav-trigger]",D=ce.forwardRef(({loop:o=!0,...e},t)=>{let{orientation:i}=c("NavigationMenuList"),n=(0,ge.useRovingFocus)({orientation:i,loop:o,itemSelector:Ae});return(0,fe.jsx)(h.Primitive.ul,{role:"list","data-orientation":i,...e,...(0,le.skdxPart)("navigation-menu","list",e.className),ref:t,onKeyDown:(0,h.composeEventHandlers)(e.onKeyDown,n)})});D.displayName="NavigationMenuList";var H=p(require("react"),1),ve=require("../utils/part.cjs"),d=require("../utils/primitive.cjs"),pe=require("../utils/tabbable.cjs");var de=require("react/jsx-runtime"),S=H.forwardRef((o,e)=>{let t=c("NavigationMenuTrigger"),i=y("NavigationMenuTrigger"),n=t.value===i.value,r=H.useRef(!1),g=()=>{n&&!r.current?t.onClose():t.onItemSelect(i.value)};return(0,de.jsx)(d.Primitive.button,{type:"button",id:i.triggerId,"aria-expanded":n,"aria-controls":i.contentId,"data-skdx-nav-trigger":"","data-state":n?"open":"closed",...o,...(0,ve.skdxPart)("navigation-menu","trigger",o.className),ref:e,onPointerEnter:(0,d.composeEventHandlers)(o.onPointerEnter,u=>{u.pointerType!=="touch"&&(r.current=!0,t.onTriggerEnter(i.value))}),onPointerLeave:(0,d.composeEventHandlers)(o.onPointerLeave,u=>{u.pointerType!=="touch"&&(r.current=!1,t.onTriggerLeave())}),onClick:(0,d.composeEventHandlers)(o.onClick,g),onKeyDown:(0,d.composeEventHandlers)(o.onKeyDown,u=>{if([" ","Enter"].includes(u.key))u.preventDefault(),g();else if(u.key==="ArrowDown"&&n&&t.orientation==="horizontal"){let f=u.currentTarget.ownerDocument.getElementById(i.contentId),R=f&&(0,pe.tabbablesWithin)(f)[0];if(!R)return;u.preventDefault(),u.stopPropagation(),R.focus()}})})});S.displayName="NavigationMenuTrigger";var s=require("react/jsx-runtime"),Ne=({items:o=[],renderItem:e})=>(0,s.jsxs)(s.Fragment,{children:[(0,s.jsx)(D,{children:o.map((t,i)=>{let n=t.value??String(i);return(0,s.jsx)(L,{value:n,children:"items"in t?(0,s.jsxs)(s.Fragment,{children:[(0,s.jsx)(S,{children:t.label}),(0,s.jsx)(k,{children:e?e(t):t.items.map(r=>(0,s.jsx)(x,{href:r.href,active:r.active,children:r.label},r.href))})]}):(0,s.jsx)(x,{href:t.href,active:t.active,children:e?e(t):t.label})},n)})}),(0,s.jsx)(E,{})]});var B=require("react/jsx-runtime"),Ve=150,[xe,c]=(0,Re.createSafeContext)("NavigationMenu"),F=a.forwardRef(({children:o,items:e,renderItem:t,value:i,defaultValue:n,onValueChange:r,delayDuration:g=200,skipDelayDuration:u=300,closeDelayDuration:f=Ve,closeOnSelect:R=!0,orientation:P="horizontal",...G},Pe)=>{let _=a.useRef(null),Te=(0,Me.useComposedRefs)(Pe,_),z=a.useRef(!0),N=a.useRef(0),v=a.useRef(0),K=a.useRef(0),[O=null,l]=(0,we.useControllableState)({prop:i,defaultProp:n,onChange:m=>{window.clearTimeout(K.current),m!==null?z.current=!1:K.current=window.setTimeout(()=>{z.current=!0},u),r?.(m)}});a.useEffect(()=>()=>{window.clearTimeout(N.current),window.clearTimeout(v.current),window.clearTimeout(K.current)},[]);let Ie=a.useCallback(m=>{window.clearTimeout(v.current),window.clearTimeout(N.current),z.current?N.current=window.setTimeout(()=>l(m),g):l(m)},[l,g]),$=a.useCallback(()=>{window.clearTimeout(N.current),window.clearTimeout(v.current),v.current=window.setTimeout(()=>l(null),f)},[l,f]),Le=a.useCallback(()=>{window.clearTimeout(v.current)},[]),ke=a.useCallback(m=>{window.clearTimeout(N.current),window.clearTimeout(v.current),l(m)},[l]),A=a.useCallback(()=>{window.clearTimeout(N.current),window.clearTimeout(v.current),l(null)},[l]),Ee=a.useCallback(()=>{R&&A()},[R,A]);return a.useLayoutEffect(()=>{let m=_.current;if(!m||O===null)return;let q=m.querySelector('[data-skdx-nav-trigger][data-state="open"]');if(!q)return;let U=m.getBoundingClientRect(),T=q.getBoundingClientRect(),W=P==="horizontal",be=W?T.left-U.left:T.top-U.top,he=W?T.width:T.height;m.style.setProperty("--skdx-navigation-menu-indicator-offset",`${be}px`),m.style.setProperty("--skdx-navigation-menu-indicator-size",`${he}px`)},[O,P]),(0,B.jsx)(xe,{value:O,orientation:P,onTriggerEnter:Ie,onTriggerLeave:$,onContentEnter:Le,onContentLeave:$,onItemSelect:ke,onClose:A,onLinkSelect:Ee,children:(0,B.jsx)(ye.Primitive.nav,{"data-orientation":P,...G,...(0,Ce.skdxPart)("navigation-menu","root",G.className),ref:Te,children:o??(0,B.jsx)(Ne,{items:e,renderItem:t})})})});F.displayName="NavigationMenu";0&&(module.exports={NavigationMenu,NavigationMenuContent,NavigationMenuIndicator,NavigationMenuItem,NavigationMenuItemProvider,NavigationMenuLink,NavigationMenuList,NavigationMenuRootProvider,NavigationMenuTrigger,useNavigationMenuContext,useNavigationMenuItemContext});

package/dist/navigation-menu/NavigationMenu.d.cts

@@ -1,5 +1,9 @@
 import * as React from 'react';
 import type { NavigationMenuContextValue, NavigationMenuProps } from './types.cjs';
+/**
+ * `null` = nothing open. `undefined` = uncontrolled. Distinguishes uncontrolled
+ * from controlled empty.
+ */
 export declare const NavigationMenuRootProvider: {
     (props: NavigationMenuContextValue & {
         children: React.ReactNode;
@@ -7,18 +11,22 @@ export declare const NavigationMenuRootProvider: {
     displayName: string;
 }, useNavigationMenuContext: (consumerName: string) => NavigationMenuContextValue;
 /**
- * Root of a hover/click-driven navigation menu: owns which item's content is
- * open and hands hover-intent timers down to `NavigationMenuItem` /
- * `NavigationMenuTrigger` / `NavigationMenuContent` via context. Renders a
- * `<nav>` labelled `"Main"` by default (override via `aria-label`).
- *
- * Opening a trigger is delayed by `delayDuration` on first hover, but once
- * one item is open, moving to a sibling trigger within `skipDelayDuration`
- * of closing switches instantly. Works controlled (`value` +
- * `onValueChange`) or uncontrolled (`defaultValue`).
+ * Hover/click-driven menu: owns open item, hands timers to parts. First hover
+ * delayed by `delayDuration`, sibling switches instant within `skipDelayDuration`.
+ * Controlled or uncontrolled. Derives from `items` or renders `children` verbatim.
  *
  * @example
  * ```tsx
+ * <NavigationMenu
+ *   items={[
+ *     { label: 'Home', href: '/' },
+ *     { label: 'Products', items: [{ label: 'Product A', href: '/products/a' }] },
+ *   ]}
+ * />
+ * ```
+ *
+ * @example Full manual composition — `@skdx/react/primitives/navigation-menu`.
+ * ```tsx
  * <NavigationMenu>
  *   <NavigationMenuList>
  *     <NavigationMenuItem value="products">

package/dist/navigation-menu/NavigationMenu.d.ts

@@ -1,5 +1,9 @@
 import * as React from 'react';
 import type { NavigationMenuContextValue, NavigationMenuProps } from './types.js';
+/**
+ * `null` = nothing open. `undefined` = uncontrolled. Distinguishes uncontrolled
+ * from controlled empty.
+ */
 export declare const NavigationMenuRootProvider: {
     (props: NavigationMenuContextValue & {
         children: React.ReactNode;
@@ -7,18 +11,22 @@ export declare const NavigationMenuRootProvider: {
     displayName: string;
 }, useNavigationMenuContext: (consumerName: string) => NavigationMenuContextValue;
 /**
- * Root of a hover/click-driven navigation menu: owns which item's content is
- * open and hands hover-intent timers down to `NavigationMenuItem` /
- * `NavigationMenuTrigger` / `NavigationMenuContent` via context. Renders a
- * `<nav>` labelled `"Main"` by default (override via `aria-label`).
- *
- * Opening a trigger is delayed by `delayDuration` on first hover, but once
- * one item is open, moving to a sibling trigger within `skipDelayDuration`
- * of closing switches instantly. Works controlled (`value` +
- * `onValueChange`) or uncontrolled (`defaultValue`).
+ * Hover/click-driven menu: owns open item, hands timers to parts. First hover
+ * delayed by `delayDuration`, sibling switches instant within `skipDelayDuration`.
+ * Controlled or uncontrolled. Derives from `items` or renders `children` verbatim.
  *
  * @example
  * ```tsx
+ * <NavigationMenu
+ *   items={[
+ *     { label: 'Home', href: '/' },
+ *     { label: 'Products', items: [{ label: 'Product A', href: '/products/a' }] },
+ *   ]}
+ * />
+ * ```
+ *
+ * @example Full manual composition — `@skdx/react/primitives/navigation-menu`.
+ * ```tsx
  * <NavigationMenu>
  *   <NavigationMenuList>
  *     <NavigationMenuItem value="products">