@skdx/react 0.26.0

package/dist/transfer/types.d.ts

@@ -0,0 +1,204 @@
+import type * as React from 'react';
+import type { PrimitivePropsWithRef } from '../utils/primitive.js';
+/**
+ * Which of the two lists a part belongs to. `'source'` is the pool an item
+ * starts in; `'target'` is the result — the array `Transfer`'s `value` holds.
+ *
+ * Named by role rather than by position: under `dir="rtl"` the target list is
+ * on the left, so a `'left'`/`'right'` API would be wrong for half the world.
+ */
+export type TransferSide = 'source' | 'target';
+/**
+ * A move, named by where it lands rather than by which arrow it looks like.
+ * `'toTarget'` adds to the value, `'toSource'` removes from it — true in both
+ * writing directions, which `'right'`/`'left'` would not be.
+ */
+export type TransferDirection = 'toTarget' | 'toSource';
+/** One entry in a {@link Transfer}'s collection. */
+export interface TransferItemData {
+    /** Unique id. This is what appears in `Transfer`'s `value` once the item is on the target side. */
+    value: string;
+    /** Human-readable text, used as the option's content and its typeahead `textValue` when the list renders itself. */
+    label: string;
+    /**
+     * Excludes this item from selection, from keyboard navigation, and from
+     * every move — including "move all".
+     * @default undefined — the item behaves normally.
+     */
+    disabled?: boolean;
+}
+/** @internal Shared state distributed from {@link Transfer} to its parts via context. Not part of the public API. */
+export interface TransferContextValue {
+    /** Stable id prefix the parts derive their wiring ids from. */
+    baseId: string;
+    /** Whether the whole widget is disabled. */
+    disabled: boolean;
+    /** Whether the search plumbing is on; `TransferListSearch` renders nothing while it is off. */
+    searchable: boolean;
+    /** Every item on a side, before the search filter. */
+    sideItems: Record<TransferSide, TransferItemData[]>;
+    /** Every item on a side that survives the current search query — what is actually rendered. */
+    visibleItems: Record<TransferSide, TransferItemData[]>;
+    /** Each side's marked-for-move selection, already pruned of values that side no longer holds. */
+    marked: Record<TransferSide, string[]>;
+    /** Replaces one side's marked selection wholesale. */
+    setMarked: (side: TransferSide, values: string[]) => void;
+    /** Each side's search query. */
+    query: Record<TransferSide, string>;
+    setQuery: (side: TransferSide, query: string) => void;
+    /** The option value holding each list's own tab stop — one roving group per side. */
+    active: Record<TransferSide, string | null>;
+    setActive: (side: TransferSide, value: string | null) => void;
+    /** Range-selection anchor per side: the last option marked *without* Shift. */
+    anchor: React.MutableRefObject<Record<TransferSide, string | null>>;
+    /** Whether a `TransferListHeader` is mounted for a side, which decides `aria-labelledby` vs `aria-label`. */
+    labelled: Record<TransferSide, boolean>;
+    registerHeader: (side: TransferSide, present: boolean) => void;
+    /** Lets the root find a list element again, to place focus after a move. */
+    registerList: (side: TransferSide, node: HTMLDivElement | null) => void;
+    /** Moves `values` (silently dropping any disabled ones), announces the outcome, and re-places focus. */
+    move: (direction: TransferDirection, values: string[]) => void;
+    /** The accessible name each move trigger gives itself — the root's `getMoveLabel`, or the built-in English one. */
+    moveLabel: (count: number, direction: TransferDirection, all: boolean) => string;
+}
+/** What a move just did, handed to {@link TransferProps.getMoveAnnouncement} so it can word the live-region message. */
+export interface TransferMoveDetail {
+    /** How many items actually moved (disabled ones are never counted). */
+    moved: number;
+    /** How many items are left on the side they came from. */
+    remaining: number;
+    /** Which way they went. */
+    direction: TransferDirection;
+    /** The side they left. */
+    from: TransferSide;
+    /** The side they landed on. */
+    to: TransferSide;
+}
+/** Props for the {@link Transfer} root. */
+export interface TransferProps extends Omit<PrimitivePropsWithRef<'div'>, 'onChange' | 'defaultValue'> {
+    /**
+     * The whole collection, both sides at once. Each side is *derived* from this
+     * plus `value`, never stored separately — one array is the source of truth,
+     * so the two lists cannot drift apart.
+     */
+    items: TransferItemData[];
+    /**
+     * The ids currently on the target side, for controlled usage. Pair with
+     * `onValueChange`. Rendering order always follows `items`, not this array,
+     * so a controlled consumer never has to keep two orderings in sync.
+     * @default undefined — uncontrolled, tracks its own membership internally.
+     */
+    value?: string[];
+    /**
+     * The ids initially on the target side, for uncontrolled usage.
+     * @default undefined — every item starts on the source side.
+     */
+    defaultValue?: string[];
+    /**
+     * Fires with the whole new target-side id array whenever a move happens,
+     * controlled or not.
+     * @default undefined — no-op if omitted.
+     */
+    onValueChange?: (value: string[]) => void;
+    /**
+     * Fires alongside `onValueChange` with the items that actually moved and
+     * which way, for side effects that need the moved rows rather than the new
+     * membership — a toast, an undo entry, a server call.
+     * @default undefined — no-op if omitted.
+     */
+    onMove?: (items: TransferItemData[], direction: TransferDirection) => void;
+    /**
+     * Disables both lists and every move trigger at once. Individual items can
+     * still be disabled on their own via `TransferItemData.disabled`.
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Enables per-list filtering. While `false`, `TransferListSearch` renders
+     * nothing and `filter` is never called — so the search box cannot be left
+     * on screen as decoration that does not work.
+     * @default false — both lists show everything on their side.
+     */
+    searchable?: boolean;
+    /**
+     * Decides whether an item survives its list's current query. Only consulted
+     * while `searchable`.
+     * @default undefined — case-insensitive substring match against `item.label`.
+     */
+    filter?: (item: TransferItemData, query: string) => boolean;
+    /**
+     * Words the accessible name of every `TransferMoveTrigger` and
+     * `TransferMoveAllTrigger` under this root. `all` distinguishes the two, and
+     * `count` is how many items pressing it would actually move — zero included,
+     * because the trigger stays focusable with nothing to move and has to say
+     * why.
+     *
+     * The only way to translate those names: they are computed from live counts,
+     * so a static `aria-label` on the trigger cannot express them.
+     * @default undefined — the built-in English wording ("Move 3 items to selected").
+     */
+    getMoveLabel?: (count: number, direction: TransferDirection, all: boolean) => string;
+    /**
+     * Words the polite live-region announcement made after each move. Return
+     * `''` to say nothing at all.
+     * @default undefined — the built-in English wording ("3 items moved to selected. 5 remaining in available.").
+     */
+    getMoveAnnouncement?: (detail: TransferMoveDetail) => string;
+}
+/** @internal Wiring passed from a {@link TransferList} to the {@link TransferItem}s inside it. Not part of the public API. */
+export interface TransferListContextValue {
+    side: TransferSide;
+}
+/** Props for {@link TransferList}, the `role="listbox"` element for one side. */
+export interface TransferListProps extends Omit<PrimitivePropsWithRef<'div'>, 'onChange' | 'defaultValue'> {
+    /** Which of the two sides this list renders the items for. */
+    side: TransferSide;
+    /**
+     * Your own `TransferItem`s, when the default rendering is not enough.
+     * @default undefined — the list renders one `TransferItem` per visible item on its side, using `label` as both content and `textValue`.
+     */
+    children?: React.ReactNode;
+}
+/** Props for {@link TransferListHeader}, the heading naming one list. */
+export interface TransferListHeaderProps extends PrimitivePropsWithRef<'div'> {
+    /** Which side this header names. Must match the `side` of the list it sits beside. */
+    side: TransferSide;
+}
+/** Props for {@link TransferListSearch}, the filter input for one list. */
+export interface TransferListSearchProps extends Omit<PrimitivePropsWithRef<'input'>, 'value' | 'defaultValue' | 'type'> {
+    /** Which of the two sides this input filters the items of. */
+    side: TransferSide;
+}
+/** Props for a single {@link TransferItem} option. */
+export interface TransferItemProps extends PrimitivePropsWithRef<'div'> {
+    /** The id of the `TransferItemData` entry this option renders. */
+    value: string;
+    /**
+     * Excludes this option from marking, navigation, and moves.
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Text typeahead matches this option against, published as `data-text-value`.
+     * @default undefined — falls back to the option's rendered text content, indicator glyph included.
+     */
+    textValue?: string;
+}
+/** Props for {@link TransferControls}, the named group holding the move triggers. */
+export interface TransferControlsProps extends PrimitivePropsWithRef<'div'> {
+}
+/** Props for {@link TransferMoveTrigger}, which moves the marked items one way. */
+export interface TransferMoveTriggerProps extends PrimitivePropsWithRef<'button'> {
+    /** Which way this trigger moves: `'toTarget'` adds to the value, `'toSource'` removes from it. */
+    direction: TransferDirection;
+}
+/** Props for {@link TransferMoveAllTrigger}, which moves every visible item one way. */
+export interface TransferMoveAllTriggerProps extends PrimitivePropsWithRef<'button'> {
+    /** Which way this trigger moves: `'toTarget'` adds to the value, `'toSource'` removes from it. */
+    direction: TransferDirection;
+}
+/** Props for {@link TransferEmpty}, shown while one side has nothing to render. */
+export interface TransferEmptyProps extends PrimitivePropsWithRef<'div'> {
+    /** Which side's emptiness this message covers. */
+    side: TransferSide;
+}

package/dist/tree/Tree.cjs

@@ -0,0 +1 @@
+"use strict";var Ue=Object.create;var q=Object.defineProperty;var Ye=Object.getOwnPropertyDescriptor;var $e=Object.getOwnPropertyNames;var Je=Object.getPrototypeOf,Qe=Object.prototype.hasOwnProperty;var We=(t,o)=>{for(var c in o)q(t,c,{get:o[c],enumerable:!0})},Te=(t,o,c,s)=>{if(o&&typeof o=="object"||typeof o=="function")for(let i of $e(o))!Qe.call(t,i)&&i!==c&&q(t,i,{get:()=>o[i],enumerable:!(s=Ye(o,i))||s.enumerable});return t};var _=(t,o,c)=>(c=t!=null?Ue(Je(t)):{},Te(o||!t||!t.__esModule?q(c,"default",{value:t,enumerable:!0}):c,t)),Xe=t=>Te(q({},"__esModule",{value:!0}),t);var nt={};We(nt,{Tree:()=>be,TreeAmbientContext:()=>v,TreeGroup:()=>L,TreeItem:()=>ce,TreeItemIndicator:()=>de,TreeProvider:()=>Pe,defaultGetLoadedLabel:()=>Ee,useTreeContext:()=>N});module.exports=Xe(nt);var a=_(require("react"),1),ye=require("../utils/createContext.cjs"),B=require("../utils/direction.cjs"),Ce=require("../utils/liveAnnouncer.cjs"),Re=require("../utils/part.cjs"),A=require("../utils/primitive.cjs"),ne=require("../utils/useControllableState.cjs"),U=require("../utils/useRovingFocus.cjs"),Y=require("../utils/useTypeahead.cjs"),se=require("react/jsx-runtime"),oe='[role="treeitem"]:not([data-disabled])',ke='[role="treeitem"]';function Ee(t){return`${t} loaded`}var[Pe,N]=(0,ye.createSafeContext)("Tree"),v=a.createContext({depth:1,parentId:null});function P(t){return Array.from(t.querySelectorAll(oe))}function C(t){return t.getAttribute("data-skdx-tree-node-id")??""}function Ze(t){let o=t.getAttribute("data-text-value");if(o!==null)return o;let c="";for(let s of t.childNodes){let i=s.nodeType===1?s:null;i&&(i.getAttribute("role")==="group"||i.getAttribute("aria-hidden")==="true")||(c+=s.textContent??"")}return c}function je(t){let o=new Map;for(let s of t.querySelectorAll(ke)){let i=C(s);if(!i)continue;let d=s.getAttribute("data-skdx-tree-parent-id")??"",m=o.get(d);m?m.push(i):o.set(d,[i])}let c=new Map;for(let s of o.values())s.forEach((i,d)=>{c.set(i,{posinset:d+1,setsize:s.length})});return c}function et(t,o){if(t.size!==o.size)return!1;for(let[c,s]of t){let i=o.get(c);if(!i||i.posinset!==s.posinset||i.setsize!==s.setsize)return!1}return!0}function xe(t,o,c){let s=P(t),i=s.indexOf(o);if(i===-1)return;let d=s[i+c];return d?.focus(),d}var be=a.forwardRef(({selectionMode:t="single",expandedIds:o,defaultExpandedIds:c=[],onExpandedIdsChange:s,selectedIds:i,defaultSelectedIds:d=[],onSelectedIdsChange:m,selectionPropagation:T="none",loadChildren:g,getLoadedLabel:b=Ee,...x},R)=>{let h=a.useRef(null),D=(0,B.useDirection)(),[I,p]=a.useState(null),[K,k]=a.useState(()=>new Set),Q=a.useRef(new Set),[le,ue]=a.useState(()=>new Map),G=T==="descendants",[fe=[],O]=(0,ne.useControllableState)({prop:o,defaultProp:c,onChange:s}),[me=[],S]=(0,ne.useControllableState)({prop:i,defaultProp:d,onChange:m}),Ke=a.useMemo(()=>new Set(fe),[fe]),z=a.useMemo(()=>new Set(me),[me]),Ge=a.useCallback((e,r)=>{ue(n=>n.get(e)===r?n:new Map(n).set(e,r))},[]),Oe=a.useCallback(e=>{ue(r=>{if(!r.has(e))return r;let n=new Map(r);return n.delete(e),n})},[]),W=a.useMemo(()=>{let e=new Map;for(let[r,n]of le){if(n===null)continue;let l=e.get(n);l?l.push(r):e.set(n,[r])}return e},[le]),F=a.useCallback(e=>{let r=[],n=[...W.get(e)??[]];for(;n.length>0;){let l=n.pop();r.push(l),n.push(...W.get(l)??[])}return r},[W]),X=a.useCallback(e=>{if(!G)return!1;let r=F(e);if(r.length===0)return z.has(e);let n=r.filter(l=>z.has(l)).length;return n===0?!1:n===r.length?!0:"mixed"},[G,F,z]),V=a.useCallback(e=>{if(!g||Q.current.has(e))return;Q.current.add(e),k(n=>new Set(n).add(e));let r=()=>k(n=>{let l=new Set(n);return l.delete(e),l});Promise.resolve(g(e)).then(()=>{r(),(0,Ce.announce)(b(e))},()=>{Q.current.delete(e),r()})},[g,b]),Z=a.useCallback((e,r)=>{O((n=[])=>r?[...n,e]:n.filter(l=>l!==e)),r&&V(e)},[O,V]),ze=a.useCallback(e=>{if(e.length!==0){O((r=[])=>[...new Set([...r,...e])]);for(let r of e)V(r)}},[O,V]),j=a.useCallback(e=>{if(t!=="none"){if(t==="multiple"&&G){let r=X(e)!==!0,n=[e,...F(e)];S((l=[])=>{let E=new Set(l);for(let M of n)r?E.add(M):E.delete(M);return[...E]});return}S((r=[])=>t==="single"?[e]:r.includes(e)?r.filter(n=>n!==e):[...r,e])}},[t,G,X,F,S]),pe=a.useCallback(e=>{t==="multiple"&&S((r=[])=>[...new Set([...r,...e])])},[t,S]);(0,U.useRovingTabStop)(h,oe,"data-skdx-tree-node-id",I,p);let[ge,Fe]=a.useState(()=>new Map);a.useLayoutEffect(()=>{let e=h.current;if(!e)return;let r=je(e);Fe(n=>et(n,r)?n:r)});let Ve=a.useCallback(e=>ge.get(e),[ge]),qe=(0,U.useRovingFocus)({orientation:"vertical",loop:!1,itemSelector:oe,typeahead:!1}),_e=(0,Y.useTypeahead)(a.useCallback(()=>h.current?P(h.current).map(Ze):[],[])),Be=e=>{let r=e.currentTarget,n=e.target;if(!n.matches('[role="treeitem"]'))return;let l=C(n),E=n.getAttribute("aria-expanded"),M=E!==null,he=E==="true",ee=n.getAttribute("data-skdx-tree-parent-id")||"",te=t==="multiple",w=(0,B.directionalKey)(e.key,e.currentTarget,D);if(te&&e.shiftKey&&(w==="ArrowDown"||w==="ArrowUp")){e.preventDefault();let u=xe(r,n,w==="ArrowDown"?1:-1);u&&j(C(u));return}if(te&&e.shiftKey&&(e.key==="Home"||e.key==="End")){e.preventDefault();let u=P(r),y=u.indexOf(n),re=e.key==="Home"?0:u.length-1;pe(u.slice(Math.min(y,re),Math.max(y,re)+1).map(C)),u[re]?.focus();return}if(te&&(e.ctrlKey||e.metaKey)&&e.key.toLowerCase()==="a"){e.preventDefault(),pe(P(r).map(C));return}if(w==="ArrowRight")e.preventDefault(),M&&!he?Z(l,!0):xe(r,n,1);else if(w==="ArrowLeft")e.preventDefault(),M&&he?Z(l,!1):ee&&P(r).find(y=>C(y)===ee)?.focus();else if(e.key==="Enter"||e.key===" ")e.preventDefault(),j(l);else if(e.key==="*")e.preventDefault(),ze(Array.from(r.querySelectorAll(ke)).filter(u=>(u.getAttribute("data-skdx-tree-parent-id")||"")===ee&&u.getAttribute("aria-expanded")==="false").map(C));else if((0,Y.isTypeaheadKey)(e)){let u=P(r),y=_e(e.key,u.indexOf(n));if(y===-1)return;e.preventDefault(),u[y].focus()}};return(0,se.jsx)(Pe,{selectionMode:t,selectionPropagation:T,expandedIds:Ke,selectedIds:z,loadingIds:K,activeNodeId:I,setActiveNodeId:p,onExpandedChange:Z,onSelectedChange:j,checkedState:X,positionOf:Ve,registerNode:Ge,unregisterNode:Oe,children:(0,se.jsx)(A.Primitive.div,{role:"tree","aria-multiselectable":t==="multiple"?!0:void 0,...x,...(0,Re.skdxPart)("tree","root",x.className),ref:e=>{h.current=e,typeof R=="function"?R(e):R&&(R.current=e)},onKeyDown:(0,A.composeEventHandlers)(x.onKeyDown,(0,A.composeEventHandlers)(Be,qe))})})});be.displayName="Tree";var f=_(require("react"),1),Ae=require("../utils/createContext.cjs"),Ne=require("../utils/part.cjs"),H=require("../utils/primitive.cjs"),ve=require("../utils/useRovingFocus.cjs");var Ie=_(require("react"),1),Se=require("../utils/part.cjs"),Me=require("../utils/primitive.cjs");var ie=require("react/jsx-runtime"),L=Ie.forwardRef(({forceMount:t,children:o,...c},s)=>{let i=$("TreeGroup");return t||i.expanded?(0,ie.jsx)(v.Provider,{value:{depth:i.depth+1,parentId:i.nodeId},children:(0,ie.jsx)(Me.Primitive.div,{role:"group",...c,...(0,Se.skdxPart)("tree","group",c.className),ref:s,children:o})}):null});L.displayName="TreeGroup";var ae=require("react/jsx-runtime"),[tt,$]=(0,Ae.createSafeContext)("TreeItem");function we(t){return t.target.closest('[role="treeitem"]')!==t.currentTarget}function rt(t){return f.Children.toArray(t).some(o=>f.isValidElement(o)&&o.type===L)}var ce=f.forwardRef(({nodeId:t,disabled:o=!1,children:c,...s},i)=>{let d=N("TreeItem"),m=f.useContext(v),T=rt(c),g=d.expandedIds.has(t),b=d.selectedIds.has(t),x=d.loadingIds.has(t),R=(0,ve.rovingTabIndex)(d.activeNodeId!==null,d.activeNodeId===t,o),{registerNode:h,unregisterNode:D}=d,I=m.parentId;f.useEffect(()=>(h(t,I),()=>D(t)),[t,I,h,D]);let p=d.selectionPropagation==="descendants"?d.checkedState(t):void 0,K=d.positionOf(t);return(0,ae.jsx)(tt,{nodeId:t,depth:m.depth,expanded:g,selected:b,disabled:o,hasChildren:T,loading:x,children:(0,ae.jsx)(H.Primitive.div,{role:"treeitem","aria-level":m.depth,"aria-posinset":K?.posinset,"aria-setsize":K?.setsize,"aria-selected":d.selectionMode==="none"?void 0:b,"aria-expanded":T?g:void 0,"aria-checked":p===void 0?void 0:p==="mixed"?"mixed":p,"aria-busy":x||void 0,"aria-disabled":o||void 0,"data-state":T?g?"expanded":"collapsed":void 0,"data-checked":p===void 0?void 0:p==="mixed"?"indeterminate":p?"checked":"unchecked","data-loading":x?"":void 0,"data-disabled":o?"":void 0,"data-skdx-tree-node-id":t,"data-skdx-tree-parent-id":m.parentId??void 0,tabIndex:R,...s,...(0,Ne.skdxPart)("tree","item",s.className),ref:i,onClick:(0,H.composeEventHandlers)(s.onClick,k=>{o||we(k)||(d.onSelectedChange(t),T&&d.onExpandedChange(t,!g))}),onFocus:(0,H.composeEventHandlers)(s.onFocus,k=>{!o&&!we(k)&&d.setActiveNodeId(t)}),children:c})})});ce.displayName="TreeItem";var Le=_(require("react"),1),He=require("../utils/part.cjs"),J=require("../utils/primitive.cjs");var De=require("react/jsx-runtime"),de=Le.forwardRef((t,o)=>{let c=N("TreeItemIndicator"),s=$("TreeItemIndicator");return(0,De.jsx)(J.Primitive.span,{"aria-hidden":"true","data-state":s.hasChildren?s.expanded?"expanded":"collapsed":void 0,...t,...(0,He.skdxPart)("tree","item-indicator",t.className),ref:o,onClick:(0,J.composeEventHandlers)(t.onClick,i=>{i.stopPropagation(),s.hasChildren&&c.onExpandedChange(s.nodeId,!s.expanded)})})});de.displayName="TreeItemIndicator";0&&(module.exports={Tree,TreeAmbientContext,TreeGroup,TreeItem,TreeItemIndicator,TreeProvider,defaultGetLoadedLabel,useTreeContext});

package/dist/tree/Tree.d.cts

@@ -0,0 +1,54 @@
+import * as React from 'react';
+import type { TreeContextValue, TreeProps } from './types.cjs';
+/** Default `getLoadedLabel`: `"src loaded"`. */
+export declare function defaultGetLoadedLabel(nodeId: string): string;
+export declare const TreeProvider: {
+    (props: TreeContextValue & {
+        children: React.ReactNode;
+    }): React.JSX.Element;
+    displayName: string;
+}, useTreeContext: (consumerName: string) => TreeContextValue;
+/** Ambient depth/parent-id passed down to the next level of TreeItems; overridden by each TreeGroup. */
+export declare const TreeAmbientContext: React.Context<{
+    depth: number;
+    parentId: string | null;
+}>;
+/**
+ * Root of a tree view following the WAI-ARIA `treeview` pattern: renders a
+ * `<div role="tree">` with `aria-multiselectable` when `selectionMode` is
+ * `"multiple"`. Owns expanded/selected/active-node state and hands it down
+ * to `TreeItem` / `TreeGroup` / `TreeItemIndicator` via context.
+ *
+ * A single tab stop uses roving tabindex over the currently *visible* items
+ * only — collapsed subtrees aren't rendered, so they're naturally excluded.
+ * Arrow Up/Down/Home/End move focus; Arrow Right expands a collapsed node
+ * (or moves to its first child if already expanded); Arrow Left collapses an
+ * expanded node (or moves focus to its parent); Enter/Space select the
+ * focused node; printable characters run typeahead over the visible nodes'
+ * labels; `*` expands every collapsed sibling of the focused node. Under
+ * `selectionMode="multiple"`, Shift+Arrow Up/Down moves focus and toggles the
+ * node it lands on, Shift+Home/End selects through to the first/last node,
+ * Ctrl+A selects every visible node, and Ctrl+Arrow Up/Down moves focus
+ * without touching the selection.
+ *
+ * Expansion and selection each work controlled (`expandedIds`/`selectedIds`
+ * + their `onChange`) or uncontrolled (`defaultExpandedIds`/`defaultSelectedIds`).
+ *
+ * `loadChildren` lazily populates a branch the first time it expands, marking
+ * the node `aria-busy` meanwhile and announcing when its children arrive.
+ * `selectionPropagation="descendants"` turns it into a tri-state checkbox tree.
+ *
+ * @example
+ * ```tsx
+ * <Tree defaultExpandedIds={['src']}>
+ *   <TreeItem nodeId="src">
+ *     <TreeItemIndicator>▸</TreeItemIndicator>
+ *     src
+ *     <TreeGroup>
+ *       <TreeItem nodeId="src/index.ts">index.ts</TreeItem>
+ *     </TreeGroup>
+ *   </TreeItem>
+ * </Tree>
+ * ```
+ */
+export declare const Tree: React.ForwardRefExoticComponent<Omit<TreeProps, "ref"> & React.RefAttributes<HTMLDivElement>>;

package/dist/tree/Tree.d.ts

@@ -0,0 +1,54 @@
+import * as React from 'react';
+import type { TreeContextValue, TreeProps } from './types.js';
+/** Default `getLoadedLabel`: `"src loaded"`. */
+export declare function defaultGetLoadedLabel(nodeId: string): string;
+export declare const TreeProvider: {
+    (props: TreeContextValue & {
+        children: React.ReactNode;
+    }): React.JSX.Element;
+    displayName: string;
+}, useTreeContext: (consumerName: string) => TreeContextValue;
+/** Ambient depth/parent-id passed down to the next level of TreeItems; overridden by each TreeGroup. */
+export declare const TreeAmbientContext: React.Context<{
+    depth: number;
+    parentId: string | null;
+}>;
+/**
+ * Root of a tree view following the WAI-ARIA `treeview` pattern: renders a
+ * `<div role="tree">` with `aria-multiselectable` when `selectionMode` is
+ * `"multiple"`. Owns expanded/selected/active-node state and hands it down
+ * to `TreeItem` / `TreeGroup` / `TreeItemIndicator` via context.
+ *
+ * A single tab stop uses roving tabindex over the currently *visible* items
+ * only — collapsed subtrees aren't rendered, so they're naturally excluded.
+ * Arrow Up/Down/Home/End move focus; Arrow Right expands a collapsed node
+ * (or moves to its first child if already expanded); Arrow Left collapses an
+ * expanded node (or moves focus to its parent); Enter/Space select the
+ * focused node; printable characters run typeahead over the visible nodes'
+ * labels; `*` expands every collapsed sibling of the focused node. Under
+ * `selectionMode="multiple"`, Shift+Arrow Up/Down moves focus and toggles the
+ * node it lands on, Shift+Home/End selects through to the first/last node,
+ * Ctrl+A selects every visible node, and Ctrl+Arrow Up/Down moves focus
+ * without touching the selection.
+ *
+ * Expansion and selection each work controlled (`expandedIds`/`selectedIds`
+ * + their `onChange`) or uncontrolled (`defaultExpandedIds`/`defaultSelectedIds`).
+ *
+ * `loadChildren` lazily populates a branch the first time it expands, marking
+ * the node `aria-busy` meanwhile and announcing when its children arrive.
+ * `selectionPropagation="descendants"` turns it into a tri-state checkbox tree.
+ *
+ * @example
+ * ```tsx
+ * <Tree defaultExpandedIds={['src']}>
+ *   <TreeItem nodeId="src">
+ *     <TreeItemIndicator>▸</TreeItemIndicator>
+ *     src
+ *     <TreeGroup>
+ *       <TreeItem nodeId="src/index.ts">index.ts</TreeItem>
+ *     </TreeGroup>
+ *   </TreeItem>
+ * </Tree>
+ * ```
+ */
+export declare const Tree: React.ForwardRefExoticComponent<Omit<TreeProps, "ref"> & React.RefAttributes<HTMLDivElement>>;

package/dist/tree/Tree.js

@@ -0,0 +1 @@
+import*as s from"react";import{createSafeContext as be}from"../utils/createContext.js";import{directionalKey as Ie,useDirection as Se}from"../utils/direction.js";import{announce as Me}from"../utils/liveAnnouncer.js";import{skdxPart as we}from"../utils/part.js";import{composeEventHandlers as ne,Primitive as Ae}from"../utils/primitive.js";import{useControllableState as oe}from"../utils/useControllableState.js";import{useRovingFocus as Ne,useRovingTabStop as ve}from"../utils/useRovingFocus.js";import{isTypeaheadKey as Le,useTypeahead as He}from"../utils/useTypeahead.js";import{jsx as ie}from"react/jsx-runtime";var Q='[role="treeitem"]:not([data-disabled])',ae='[role="treeitem"]';function De(t){return`${t} loaded`}var[Ke,G]=be("Tree"),O=s.createContext({depth:1,parentId:null});function P(t){return Array.from(t.querySelectorAll(Q))}function C(t){return t.getAttribute("data-skdx-tree-node-id")??""}function Ge(t){let i=t.getAttribute("data-text-value");if(i!==null)return i;let d="";for(let o of t.childNodes){let a=o.nodeType===1?o:null;a&&(a.getAttribute("role")==="group"||a.getAttribute("aria-hidden")==="true")||(d+=o.textContent??"")}return d}function Oe(t){let i=new Map;for(let o of t.querySelectorAll(ae)){let a=C(o);if(!a)continue;let c=o.getAttribute("data-skdx-tree-parent-id")??"",m=i.get(c);m?m.push(a):i.set(c,[a])}let d=new Map;for(let o of i.values())o.forEach((a,c)=>{d.set(a,{posinset:c+1,setsize:o.length})});return d}function ze(t,i){if(t.size!==i.size)return!1;for(let[d,o]of t){let a=i.get(d);if(!a||a.posinset!==o.posinset||a.setsize!==o.setsize)return!1}return!0}function se(t,i,d){let o=P(t),a=o.indexOf(i);if(a===-1)return;let c=o[a+d];return c?.focus(),c}var Fe=s.forwardRef(({selectionMode:t="single",expandedIds:i,defaultExpandedIds:d=[],onExpandedIdsChange:o,selectedIds:a,defaultSelectedIds:c=[],onSelectedIdsChange:m,selectionPropagation:T="none",loadChildren:g,getLoadedLabel:b=De,...x},R)=>{let h=s.useRef(null),A=Se(),[I,p]=s.useState(null),[N,k]=s.useState(()=>new Set),V=s.useRef(new Set),[W,X]=s.useState(()=>new Map),v=T==="descendants",[Z=[],L]=oe({prop:i,defaultProp:d,onChange:o}),[j=[],S]=oe({prop:a,defaultProp:c,onChange:m}),he=s.useMemo(()=>new Set(Z),[Z]),H=s.useMemo(()=>new Set(j),[j]),Te=s.useCallback((e,r)=>{X(n=>n.get(e)===r?n:new Map(n).set(e,r))},[]),xe=s.useCallback(e=>{X(r=>{if(!r.has(e))return r;let n=new Map(r);return n.delete(e),n})},[]),q=s.useMemo(()=>{let e=new Map;for(let[r,n]of W){if(n===null)continue;let l=e.get(n);l?l.push(r):e.set(n,[r])}return e},[W]),D=s.useCallback(e=>{let r=[],n=[...q.get(e)??[]];for(;n.length>0;){let l=n.pop();r.push(l),n.push(...q.get(l)??[])}return r},[q]),_=s.useCallback(e=>{if(!v)return!1;let r=D(e);if(r.length===0)return H.has(e);let n=r.filter(l=>H.has(l)).length;return n===0?!1:n===r.length?!0:"mixed"},[v,D,H]),K=s.useCallback(e=>{if(!g||V.current.has(e))return;V.current.add(e),k(n=>new Set(n).add(e));let r=()=>k(n=>{let l=new Set(n);return l.delete(e),l});Promise.resolve(g(e)).then(()=>{r(),Me(b(e))},()=>{V.current.delete(e),r()})},[g,b]),B=s.useCallback((e,r)=>{L((n=[])=>r?[...n,e]:n.filter(l=>l!==e)),r&&K(e)},[L,K]),ye=s.useCallback(e=>{if(e.length!==0){L((r=[])=>[...new Set([...r,...e])]);for(let r of e)K(r)}},[L,K]),U=s.useCallback(e=>{if(t!=="none"){if(t==="multiple"&&v){let r=_(e)!==!0,n=[e,...D(e)];S((l=[])=>{let E=new Set(l);for(let M of n)r?E.add(M):E.delete(M);return[...E]});return}S((r=[])=>t==="single"?[e]:r.includes(e)?r.filter(n=>n!==e):[...r,e])}},[t,v,_,D,S]),ee=s.useCallback(e=>{t==="multiple"&&S((r=[])=>[...new Set([...r,...e])])},[t,S]);ve(h,Q,"data-skdx-tree-node-id",I,p);let[te,Ce]=s.useState(()=>new Map);s.useLayoutEffect(()=>{let e=h.current;if(!e)return;let r=Oe(e);Ce(n=>ze(n,r)?n:r)});let Re=s.useCallback(e=>te.get(e),[te]),ke=Ne({orientation:"vertical",loop:!1,itemSelector:Q,typeahead:!1}),Ee=He(s.useCallback(()=>h.current?P(h.current).map(Ge):[],[])),Pe=e=>{let r=e.currentTarget,n=e.target;if(!n.matches('[role="treeitem"]'))return;let l=C(n),E=n.getAttribute("aria-expanded"),M=E!==null,re=E==="true",Y=n.getAttribute("data-skdx-tree-parent-id")||"",$=t==="multiple",w=Ie(e.key,e.currentTarget,A);if($&&e.shiftKey&&(w==="ArrowDown"||w==="ArrowUp")){e.preventDefault();let u=se(r,n,w==="ArrowDown"?1:-1);u&&U(C(u));return}if($&&e.shiftKey&&(e.key==="Home"||e.key==="End")){e.preventDefault();let u=P(r),y=u.indexOf(n),J=e.key==="Home"?0:u.length-1;ee(u.slice(Math.min(y,J),Math.max(y,J)+1).map(C)),u[J]?.focus();return}if($&&(e.ctrlKey||e.metaKey)&&e.key.toLowerCase()==="a"){e.preventDefault(),ee(P(r).map(C));return}if(w==="ArrowRight")e.preventDefault(),M&&!re?B(l,!0):se(r,n,1);else if(w==="ArrowLeft")e.preventDefault(),M&&re?B(l,!1):Y&&P(r).find(y=>C(y)===Y)?.focus();else if(e.key==="Enter"||e.key===" ")e.preventDefault(),U(l);else if(e.key==="*")e.preventDefault(),ye(Array.from(r.querySelectorAll(ae)).filter(u=>(u.getAttribute("data-skdx-tree-parent-id")||"")===Y&&u.getAttribute("aria-expanded")==="false").map(C));else if(Le(e)){let u=P(r),y=Ee(e.key,u.indexOf(n));if(y===-1)return;e.preventDefault(),u[y].focus()}};return ie(Ke,{selectionMode:t,selectionPropagation:T,expandedIds:he,selectedIds:H,loadingIds:N,activeNodeId:I,setActiveNodeId:p,onExpandedChange:B,onSelectedChange:U,checkedState:_,positionOf:Re,registerNode:Te,unregisterNode:xe,children:ie(Ae.div,{role:"tree","aria-multiselectable":t==="multiple"?!0:void 0,...x,...we("tree","root",x.className),ref:e=>{h.current=e,typeof R=="function"?R(e):R&&(R.current=e)},onKeyDown:ne(x.onKeyDown,ne(Pe,ke))})})});Fe.displayName="Tree";import*as f from"react";import{createSafeContext as _e}from"../utils/createContext.js";import{skdxPart as Be}from"../utils/part.js";import{composeEventHandlers as le,Primitive as Ue}from"../utils/primitive.js";import{rovingTabIndex as Ye}from"../utils/useRovingFocus.js";import*as de from"react";import{skdxPart as Ve}from"../utils/part.js";import{Primitive as qe}from"../utils/primitive.js";import{jsx as ce}from"react/jsx-runtime";var z=de.forwardRef(({forceMount:t,children:i,...d},o)=>{let a=F("TreeGroup");return t||a.expanded?ce(O.Provider,{value:{depth:a.depth+1,parentId:a.nodeId},children:ce(qe.div,{role:"group",...d,...Ve("tree","group",d.className),ref:o,children:i})}):null});z.displayName="TreeGroup";import{jsx as fe}from"react/jsx-runtime";var[$e,F]=_e("TreeItem");function ue(t){return t.target.closest('[role="treeitem"]')!==t.currentTarget}function Je(t){return f.Children.toArray(t).some(i=>f.isValidElement(i)&&i.type===z)}var me=f.forwardRef(({nodeId:t,disabled:i=!1,children:d,...o},a)=>{let c=G("TreeItem"),m=f.useContext(O),T=Je(d),g=c.expandedIds.has(t),b=c.selectedIds.has(t),x=c.loadingIds.has(t),R=Ye(c.activeNodeId!==null,c.activeNodeId===t,i),{registerNode:h,unregisterNode:A}=c,I=m.parentId;f.useEffect(()=>(h(t,I),()=>A(t)),[t,I,h,A]);let p=c.selectionPropagation==="descendants"?c.checkedState(t):void 0,N=c.positionOf(t);return fe($e,{nodeId:t,depth:m.depth,expanded:g,selected:b,disabled:i,hasChildren:T,loading:x,children:fe(Ue.div,{role:"treeitem","aria-level":m.depth,"aria-posinset":N?.posinset,"aria-setsize":N?.setsize,"aria-selected":c.selectionMode==="none"?void 0:b,"aria-expanded":T?g:void 0,"aria-checked":p===void 0?void 0:p==="mixed"?"mixed":p,"aria-busy":x||void 0,"aria-disabled":i||void 0,"data-state":T?g?"expanded":"collapsed":void 0,"data-checked":p===void 0?void 0:p==="mixed"?"indeterminate":p?"checked":"unchecked","data-loading":x?"":void 0,"data-disabled":i?"":void 0,"data-skdx-tree-node-id":t,"data-skdx-tree-parent-id":m.parentId??void 0,tabIndex:R,...o,...Be("tree","item",o.className),ref:a,onClick:le(o.onClick,k=>{i||ue(k)||(c.onSelectedChange(t),T&&c.onExpandedChange(t,!g))}),onFocus:le(o.onFocus,k=>{!i&&!ue(k)&&c.setActiveNodeId(t)}),children:d})})});me.displayName="TreeItem";import*as pe from"react";import{skdxPart as Qe}from"../utils/part.js";import{composeEventHandlers as We,Primitive as Xe}from"../utils/primitive.js";import{jsx as Ze}from"react/jsx-runtime";var ge=pe.forwardRef((t,i)=>{let d=G("TreeItemIndicator"),o=F("TreeItemIndicator");return Ze(Xe.span,{"aria-hidden":"true","data-state":o.hasChildren?o.expanded?"expanded":"collapsed":void 0,...t,...Qe("tree","item-indicator",t.className),ref:i,onClick:We(t.onClick,a=>{a.stopPropagation(),o.hasChildren&&d.onExpandedChange(o.nodeId,!o.expanded)})})});ge.displayName="TreeItemIndicator";export{Fe as Tree,O as TreeAmbientContext,z as TreeGroup,me as TreeItem,ge as TreeItemIndicator,Ke as TreeProvider,De as defaultGetLoadedLabel,G as useTreeContext};

package/dist/tree/TreeGroup.d.cts

@@ -0,0 +1,19 @@
+import * as React from 'react';
+import type { TreeGroupProps } from './types.cjs';
+/**
+ * Collapsible container for a `TreeItem`'s child `TreeItem`s: renders a
+ * `<div role="group">`, unmounted (unless `forceMount`) while the parent
+ * item is collapsed. Increments depth (`aria-level`) and sets itself as the
+ * parent node for the nested items via context.
+ *
+ * @example
+ * ```tsx
+ * <TreeItem nodeId="src">
+ *   src
+ *   <TreeGroup>
+ *     <TreeItem nodeId="src/index.ts">index.ts</TreeItem>
+ *   </TreeGroup>
+ * </TreeItem>
+ * ```
+ */
+export declare const TreeGroup: React.ForwardRefExoticComponent<Omit<TreeGroupProps, "ref"> & React.RefAttributes<HTMLDivElement>>;

package/dist/tree/TreeGroup.d.ts

@@ -0,0 +1,19 @@
+import * as React from 'react';
+import type { TreeGroupProps } from './types.js';
+/**
+ * Collapsible container for a `TreeItem`'s child `TreeItem`s: renders a
+ * `<div role="group">`, unmounted (unless `forceMount`) while the parent
+ * item is collapsed. Increments depth (`aria-level`) and sets itself as the
+ * parent node for the nested items via context.
+ *
+ * @example
+ * ```tsx
+ * <TreeItem nodeId="src">
+ *   src
+ *   <TreeGroup>
+ *     <TreeItem nodeId="src/index.ts">index.ts</TreeItem>
+ *   </TreeGroup>
+ * </TreeItem>
+ * ```
+ */
+export declare const TreeGroup: React.ForwardRefExoticComponent<Omit<TreeGroupProps, "ref"> & React.RefAttributes<HTMLDivElement>>;

package/dist/tree/TreeItem.d.cts

@@ -0,0 +1,36 @@
+import * as React from 'react';
+import type { TreeItemContextValue, TreeItemProps } from './types.cjs';
+export declare const TreeItemProvider: {
+    (props: TreeItemContextValue & {
+        children: React.ReactNode;
+    }): React.JSX.Element;
+    displayName: string;
+}, useTreeItemContext: (consumerName: string) => TreeItemContextValue;
+/**
+ * A single node in the tree: renders a `<div role="treeitem">` with
+ * `aria-level` (its depth), `aria-posinset`/`aria-setsize` (its place among
+ * the siblings at its own level), `aria-selected` (unless `selectionMode` is
+ * `"none"`), `aria-expanded` (only if it has a `TreeGroup` child),
+ * `data-state` of `"expanded"`/`"collapsed"`, and `data-disabled`. Detects
+ * whether it has children by checking for a `TreeGroup` among its
+ * `children`. Clicking it selects the node and, if it has children, toggles
+ * expansion; focusing it makes it the tree's active (tabbable) node.
+ *
+ * While the tree's `loadChildren` is pending for this node it carries
+ * `aria-busy="true"` and `data-loading`. Under
+ * `selectionPropagation="descendants"` it also carries `aria-checked`
+ * (`true`/`false`/`"mixed"`) and `data-checked`
+ * (`checked`/`unchecked`/`indeterminate`) derived from its descendants.
+ *
+ * @example
+ * ```tsx
+ * <TreeItem nodeId="src">
+ *   <TreeItemIndicator>▸</TreeItemIndicator>
+ *   src
+ *   <TreeGroup>
+ *     <TreeItem nodeId="src/index.ts">index.ts</TreeItem>
+ *   </TreeGroup>
+ * </TreeItem>
+ * ```
+ */
+export declare const TreeItem: React.ForwardRefExoticComponent<Omit<TreeItemProps, "ref"> & React.RefAttributes<HTMLDivElement>>;

package/dist/tree/TreeItem.d.ts

@@ -0,0 +1,36 @@
+import * as React from 'react';
+import type { TreeItemContextValue, TreeItemProps } from './types.js';
+export declare const TreeItemProvider: {
+    (props: TreeItemContextValue & {
+        children: React.ReactNode;
+    }): React.JSX.Element;
+    displayName: string;
+}, useTreeItemContext: (consumerName: string) => TreeItemContextValue;
+/**
+ * A single node in the tree: renders a `<div role="treeitem">` with
+ * `aria-level` (its depth), `aria-posinset`/`aria-setsize` (its place among
+ * the siblings at its own level), `aria-selected` (unless `selectionMode` is
+ * `"none"`), `aria-expanded` (only if it has a `TreeGroup` child),
+ * `data-state` of `"expanded"`/`"collapsed"`, and `data-disabled`. Detects
+ * whether it has children by checking for a `TreeGroup` among its
+ * `children`. Clicking it selects the node and, if it has children, toggles
+ * expansion; focusing it makes it the tree's active (tabbable) node.
+ *
+ * While the tree's `loadChildren` is pending for this node it carries
+ * `aria-busy="true"` and `data-loading`. Under
+ * `selectionPropagation="descendants"` it also carries `aria-checked`
+ * (`true`/`false`/`"mixed"`) and `data-checked`
+ * (`checked`/`unchecked`/`indeterminate`) derived from its descendants.
+ *
+ * @example
+ * ```tsx
+ * <TreeItem nodeId="src">
+ *   <TreeItemIndicator>▸</TreeItemIndicator>
+ *   src
+ *   <TreeGroup>
+ *     <TreeItem nodeId="src/index.ts">index.ts</TreeItem>
+ *   </TreeGroup>
+ * </TreeItem>
+ * ```
+ */
+export declare const TreeItem: React.ForwardRefExoticComponent<Omit<TreeItemProps, "ref"> & React.RefAttributes<HTMLDivElement>>;

package/dist/tree/TreeItemIndicator.d.cts

@@ -0,0 +1,18 @@
+import * as React from 'react';
+import type { TreeItemIndicatorProps } from './types.cjs';
+/**
+ * Expand/collapse affordance (e.g. a chevron) within a `TreeItem`: renders a
+ * `<span aria-hidden="true">` with `data-state` of `"expanded"`/`"collapsed"`
+ * (unset if the item has no children). Clicking it toggles expansion and
+ * stops propagation, so the enclosing `TreeItem`'s own click handler doesn't
+ * double-toggle it.
+ *
+ * @example
+ * ```tsx
+ * <TreeItem nodeId="src">
+ *   <TreeItemIndicator>▸</TreeItemIndicator>
+ *   src
+ * </TreeItem>
+ * ```
+ */
+export declare const TreeItemIndicator: React.ForwardRefExoticComponent<Omit<TreeItemIndicatorProps, "ref"> & React.RefAttributes<HTMLSpanElement>>;

package/dist/tree/TreeItemIndicator.d.ts

@@ -0,0 +1,18 @@
+import * as React from 'react';
+import type { TreeItemIndicatorProps } from './types.js';
+/**
+ * Expand/collapse affordance (e.g. a chevron) within a `TreeItem`: renders a
+ * `<span aria-hidden="true">` with `data-state` of `"expanded"`/`"collapsed"`
+ * (unset if the item has no children). Clicking it toggles expansion and
+ * stops propagation, so the enclosing `TreeItem`'s own click handler doesn't
+ * double-toggle it.
+ *
+ * @example
+ * ```tsx
+ * <TreeItem nodeId="src">
+ *   <TreeItemIndicator>▸</TreeItemIndicator>
+ *   src
+ * </TreeItem>
+ * ```
+ */
+export declare const TreeItemIndicator: React.ForwardRefExoticComponent<Omit<TreeItemIndicatorProps, "ref"> & React.RefAttributes<HTMLSpanElement>>;

package/dist/tree/index.d.cts

@@ -0,0 +1,5 @@
+export * from './Tree.cjs';
+export { TreeItem } from './TreeItem.cjs';
+export { TreeGroup } from './TreeGroup.cjs';
+export { TreeItemIndicator } from './TreeItemIndicator.cjs';
+export type { TreeProps, TreeItemProps, TreeGroupProps, TreeItemIndicatorProps, TreeSelectionPropagation, TreeCheckedState, } from './types.cjs';

package/dist/tree/index.d.ts

@@ -0,0 +1,5 @@
+export * from './Tree.js';
+export { TreeItem } from './TreeItem.js';
+export { TreeGroup } from './TreeGroup.js';
+export { TreeItemIndicator } from './TreeItemIndicator.js';
+export type { TreeProps, TreeItemProps, TreeGroupProps, TreeItemIndicatorProps, TreeSelectionPropagation, TreeCheckedState, } from './types.js';