@skdx/react 0.26.0 → 0.28.0

package/dist/transfer/types.d.ts

@@ -1,19 +1,13 @@
 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.
- */
+/** `'source'` is the pool, `'target'` is the array `Transfer`'s `value` holds; named by role, not position. */
 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.
- */
+/** Named by where items land: `'toTarget'` adds to value, `'toSource'` removes. */
 export type TransferDirection = 'toTarget' | 'toSource';
+/** How the built-in matcher compares queries against item labels. */
+export type TransferFilterMatchMode = 'startsWith' | 'contains' | 'endsWith';
+/** Where items land on target side: `'items'` keeps collection order; `'append'` / `'prepend'` follow moves. */
+export type TransferTargetOrder = 'items' | 'append' | 'prepend';
 /** 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. */
@@ -21,129 +15,195 @@ export interface TransferItemData {
     /** 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.
+     * Excludes item from selection, navigation, and moves.
+     * @default undefined — 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. */
+    /** Whether search is active; `TransferListSearch` renders nothing when off. */
     searchable: boolean;
-    /** Every item on a side, before the search filter. */
+    /** All items on each side before search filtering. */
     sideItems: Record<TransferSide, TransferItemData[]>;
-    /** Every item on a side that survives the current search query — what is actually rendered. */
+    /** Items on each side that survive the current search query. */
     visibleItems: Record<TransferSide, TransferItemData[]>;
-    /** Each side's marked-for-move selection, already pruned of values that side no longer holds. */
+    /** Each side's marked-for-move selection, pruned to values still present. */
     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. */
+    /** The roving-focus option id for each list. */
     active: Record<TransferSide, string | null>;
     setActive: (side: TransferSide, value: string | null) => void;
-    /** Range-selection anchor per side: the last option marked *without* Shift. */
+    /** Range-selection anchor per side (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`. */
+    /** Whether `TransferListHeader` is mounted (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. */
+    /** Flag to suppress `focusin` being mistaken for external Tab after programmatic focus. */
+    suppressFocusIn: React.MutableRefObject<boolean>;
+    /** Moves values, announces outcome, and re-places focus; silently drops disabled items. */
     move: (direction: TransferDirection, values: string[]) => void;
-    /** The accessible name each move trigger gives itself — the root's `getMoveLabel`, or the built-in English one. */
+    /** Accessible name for move triggers (from `getMoveLabel` or built-in English). */
     moveLabel: (count: number, direction: TransferDirection, all: boolean) => string;
+    emitListScroll: (side: TransferSide, list: HTMLElement) => void;
 }
-/** What a move just did, handed to {@link TransferProps.getMoveAnnouncement} so it can word the live-region message. */
+/** Move outcome, handed to {@link TransferProps.getMoveAnnouncement} for wording. */
 export interface TransferMoveDetail {
-    /** How many items actually moved (disabled ones are never counted). */
+    /** How many items moved (disabled items never counted). */
     moved: number;
-    /** How many items are left on the side they came from. */
+    /** Items left on the origin side. */
     remaining: number;
-    /** Which way they went. */
     direction: TransferDirection;
-    /** The side they left. */
     from: TransferSide;
-    /** The side they landed on. */
     to: TransferSide;
 }
+/** Search results, handed to {@link TransferProps.getSearchResultsAnnouncement}. */
+export interface TransferSearchResultsDetail {
+    /** Items on this side that match the query. */
+    shown: number;
+    /** Total items on this side before filtering. */
+    total: number;
+    side: TransferSide;
+    /** The settled query (empty if user cleared the box). */
+    query: string;
+}
+/** List scroll geometry, carried by {@link TransferProps.onListScroll}. */
+export interface TransferListScrollDetail {
+    side: TransferSide;
+    scrollTop: number;
+    scrollHeight: number;
+    clientHeight: number;
+}
+/** Reason {@link TransferEmpty} is showing, handed to a function child. */
+export interface TransferEmptyContext {
+    /** `'empty'` when side holds nothing; `'no-results'` when filtered to nothing. */
+    reason: 'empty' | 'no-results';
+    /** The active search query (empty string if reason is `'empty'`). */
+    query: string;
+}
 /** 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.
+     * Manually-composed parts; omitted, derives headed searchable lists from `titles` and `renderItem`.
+     * @default undefined — derives anatomy.
      */
+    children?: React.ReactNode;
+    /** Entire collection; both sides are derived from this plus `value`. */
     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.
+     * Target-side ids for controlled usage; pair with `onValueChange`.
+     * @default undefined — uncontrolled.
      */
     value?: string[];
     /**
-     * The ids initially on the target side, for uncontrolled usage.
-     * @default undefined — every item starts on the source side.
+     * Initial target-side ids for uncontrolled usage.
+     * @default undefined — all items start on source.
      */
     defaultValue?: string[];
     /**
-     * Fires with the whole new target-side id array whenever a move happens,
-     * controlled or not.
-     * @default undefined — no-op if omitted.
+     * Fires with new target-side ids whenever items move.
+     * @default undefined — no-op.
      */
     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.
+     * Fires alongside `onValueChange` with moved items and direction.
+     * @default undefined — no-op.
      */
     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`.
+     * Disables both lists and all move triggers; individual items have their own `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.
+     * Form field name; target-side ids submit as separate entries (not joined).
+     * @default undefined — submits nothing.
+     */
+    name?: string;
+    /**
+     * Form id for the submitted entries when Transfer is outside the form.
+     * @default undefined — entries belong to nearest ancestor form.
+     */
+    form?: string;
+    /**
+     * Enables per-list filtering; while false, `TransferListSearch` renders nothing.
+     * @default false
      */
     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`.
+     * Custom filter; returns true if item survives query. Only consulted when `searchable`.
+     * @default undefined — case-insensitive substring match.
      */
     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").
+     * How built-in matcher compares queries to labels; ignored if `filter` is given.
+     * @default 'contains'
+     */
+    filterMatchMode?: TransferFilterMatchMode;
+    /**
+     * Words move-trigger accessible names (count is items to move, including zero).
+     * @default undefined — built-in English.
      */
     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.").
+     * Words the polite live-region announcement after moves (return empty string to silence).
+     * @default undefined — built-in English.
      */
     getMoveAnnouncement?: (detail: TransferMoveDetail) => string;
+    /**
+     * Words the polite live-region announcement when search settles per side (return empty to silence).
+     * @default undefined — built-in English.
+     */
+    getSearchResultsAnnouncement?: (detail: TransferSearchResultsDetail) => string;
+    /**
+     * Where items land on target: `'items'` keeps collection order; `'append'` / `'prepend'` follow moves.
+     * @default 'items'
+     */
+    targetOrder?: TransferTargetOrder;
+    /**
+     * Fires on either list scroll with geometry for infinite-scroll loading.
+     * @default undefined — no-op.
+     */
+    onListScroll?: (detail: TransferListScrollDetail) => void;
+    /**
+     * Heading text for derived `TransferListHeader`s. Ignored when `children` given.
+     * @default { source: 'Available items', target: 'Selected items' }
+     */
+    titles?: TransferTitles;
+    /**
+     * Text for derived `TransferEmpty` states (`{query}` replaced with search text).
+     * @default { empty: 'Nothing here.', noMatch: 'No match for "{query}".' }
+     */
+    emptyText?: TransferEmptyText;
+    /**
+     * Whether derived `TransferControls` include a move-all trigger (off by default due to destructiveness).
+     * @default false
+     */
+    showMoveAll?: boolean;
+    /**
+     * Renders derived `TransferItem` content instead of `label`. Ignored when `children` given.
+     * @default undefined — each item renders its `label`.
+     */
+    renderItem?: (item: TransferItemData) => React.ReactNode;
+}
+/** Text for empty states. See {@link TransferProps.emptyText}. */
+export interface TransferEmptyText {
+    /** Shown when side holds no items. @default 'Nothing here.' */
+    empty?: string;
+    /** Shown when search filters all items (`{query}` replaced). @default 'No match for "{query}".' */
+    noMatch?: string;
+}
+/** List headings for derived anatomy. See {@link TransferProps.titles}. */
+export interface TransferTitles {
+    /** Source (available) list heading. @default 'Available items' */
+    source?: string;
+    /** Target (selected) list heading. @default 'Selected items' */
+    target?: string;
 }
 /** @internal Wiring passed from a {@link TransferList} to the {@link TransferItem}s inside it. Not part of the public API. */
 export interface TransferListContextValue {
@@ -154,8 +214,13 @@ export interface TransferListProps extends Omit<PrimitivePropsWithRef<'div'>, 'o
     /** 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`.
+     * Renders derived `TransferItem` content instead of `label`. Ignored when `children` given.
+     * @default undefined — each item renders its `label`.
+     */
+    renderItem?: (item: TransferItemData) => React.ReactNode;
+    /**
+     * Custom `TransferItem`s to override the default rendering of items.
+     * @default undefined — one `TransferItem` per visible item, using `label` as content.
      */
     children?: React.ReactNode;
 }
@@ -174,31 +239,36 @@ 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.
+     * Excludes 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.
+     * Text typeahead matches against, published as `data-text-value`.
+     * @default undefined — falls back to rendered text content.
      */
     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. */
+/** Props for {@link TransferMoveTrigger}, moves marked items. */
 export interface TransferMoveTriggerProps extends PrimitivePropsWithRef<'button'> {
-    /** Which way this trigger moves: `'toTarget'` adds to the value, `'toSource'` removes from it. */
+    /** Direction: `'toTarget'` adds to value, `'toSource'` removes. */
     direction: TransferDirection;
 }
-/** Props for {@link TransferMoveAllTrigger}, which moves every visible item one way. */
+/** Props for {@link TransferMoveAllTrigger}, moves all visible items. */
 export interface TransferMoveAllTriggerProps extends PrimitivePropsWithRef<'button'> {
-    /** Which way this trigger moves: `'toTarget'` adds to the value, `'toSource'` removes from it. */
+    /** Direction: `'toTarget'` adds to value, `'toSource'` removes. */
     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. */
+/** Props for {@link TransferEmpty}, shown when side has nothing to render. */
+export interface TransferEmptyProps extends Omit<PrimitivePropsWithRef<'div'>, 'children'> {
+    /** Which side ('source' or 'target') this empty state applies to. */
     side: TransferSide;
+    /**
+     * Message; pass function to differentiate empty vs no-results (published as `data-reason` / `data-query`).
+     * @default undefined — renders element only.
+     */
+    children?: React.ReactNode | ((context: TransferEmptyContext) => React.ReactNode);
 }

package/dist/tree/Tree.cjs

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

package/dist/tree/Tree.d.cts

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import type { TreeContextValue, TreeProps } from './types.cjs';
+import type { TreeContextValue, TreeNodePosition, TreeProps } from './types.cjs';
 /** Default `getLoadedLabel`: `"src loaded"`. */
 export declare function defaultGetLoadedLabel(nodeId: string): string;
 export declare const TreeProvider: {
@@ -8,39 +8,64 @@ export declare const TreeProvider: {
     }): 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. */
+/**
+ * Ambient depth/parent-id passed to the next level, plus static sibling set.
+ * Each overridden by TreeGroup.
+ */
 export declare const TreeAmbientContext: React.Context<{
     depth: number;
     parentId: string | null;
+    /** The container's declared child node ids, or `null` when it cannot tell. */
+    siblingIds: readonly string[] | null;
 }>;
+/**
+ * Node ids from JSX children, or `null` if unreliable. Enables `aria-posinset`
+ * in server-rendered HTML (DOM measurement runs in layout effect, not on server).
+ * All-or-nothing: every child must have `nodeId`, or the whole set is refused.
+ */
+export declare function staticSiblingIds(children: React.ReactNode): readonly string[] | null;
+/** One node's place in a statically-declared sibling set, or `undefined` when it is not in one. */
+export declare function staticPosition(siblingIds: readonly string[] | null, nodeId: string): TreeNodePosition | undefined;
 /**
  * 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.
+ * `"multiple"`, and hands state down to `TreeItem`/`TreeGroup`/`TreeItemIndicator`
+ * via context.
+ *
+ * Roving tabindex over the currently *visible* items only. Arrow Up/Down/Home/End
+ * move focus; Arrow Right expands (or moves to the first child); Arrow Left
+ * collapses (or moves to the parent); Enter selects and fires `onActivate`,
+ * Space selects only; printable characters run typeahead; `*` expands the
+ * focused node's collapsed siblings. Under `selectionMode="multiple"`:
+ * Shift+Arrow moves and toggles, Shift+Space selects the contiguous run from
+ * the last selected node, Control+Shift+Home/End selects to an edge, Ctrl+A
+ * toggles all/cleared, Ctrl+Arrow moves focus only.
  *
- * 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 are each controlled or uncontrolled independently.
  *
- * Expansion and selection each work controlled (`expandedIds`/`selectedIds`
- * + their `onChange`) or uncontrolled (`defaultExpandedIds`/`defaultSelectedIds`).
+ * `loadChildren` lazily populates a branch on first expand, marking it
+ * `aria-busy` and announcing on arrival. `selectionPropagation="descendants"`
+ * makes it a tri-state checkbox tree reporting `aria-checked` instead of
+ * `aria-selected`. `checkedIds`/`defaultCheckedIds` give it a checked axis
+ * separate from `selectedIds`, which then becomes row highlight only.
  *
- * `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.
+ * Needs an accessible name (`aria-label`/`aria-labelledby`) — APG requires one
+ * on `role="tree"`, which takes no name from its content or node labels.
  *
  * @example
  * ```tsx
- * <Tree defaultExpandedIds={['src']}>
+ * <Tree
+ *   aria-label="Project files"
+ *   collection={[{ nodeId: 'src', children: [{ nodeId: 'src/index.ts', label: 'index.ts' }] }]}
+ *   defaultExpandedIds={['src']}
+ * />
+ * ```
+ *
+ * @example Full manual composition, for anything `collection` can't express — `@skdx/react/primitives/tree`.
+ * ```tsx
+ * import { Tree, TreeGroup, TreeItem, TreeItemIndicator } from '@skdx/react/primitives/tree';
+ *
+ * <Tree aria-label="Project files" defaultExpandedIds={['src']}>
  *   <TreeItem nodeId="src">
  *     <TreeItemIndicator>▸</TreeItemIndicator>
  *     src

package/dist/tree/Tree.d.ts

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import type { TreeContextValue, TreeProps } from './types.js';
+import type { TreeContextValue, TreeNodePosition, TreeProps } from './types.js';
 /** Default `getLoadedLabel`: `"src loaded"`. */
 export declare function defaultGetLoadedLabel(nodeId: string): string;
 export declare const TreeProvider: {
@@ -8,39 +8,64 @@ export declare const TreeProvider: {
     }): 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. */
+/**
+ * Ambient depth/parent-id passed to the next level, plus static sibling set.
+ * Each overridden by TreeGroup.
+ */
 export declare const TreeAmbientContext: React.Context<{
     depth: number;
     parentId: string | null;
+    /** The container's declared child node ids, or `null` when it cannot tell. */
+    siblingIds: readonly string[] | null;
 }>;
+/**
+ * Node ids from JSX children, or `null` if unreliable. Enables `aria-posinset`
+ * in server-rendered HTML (DOM measurement runs in layout effect, not on server).
+ * All-or-nothing: every child must have `nodeId`, or the whole set is refused.
+ */
+export declare function staticSiblingIds(children: React.ReactNode): readonly string[] | null;
+/** One node's place in a statically-declared sibling set, or `undefined` when it is not in one. */
+export declare function staticPosition(siblingIds: readonly string[] | null, nodeId: string): TreeNodePosition | undefined;
 /**
  * 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.
+ * `"multiple"`, and hands state down to `TreeItem`/`TreeGroup`/`TreeItemIndicator`
+ * via context.
+ *
+ * Roving tabindex over the currently *visible* items only. Arrow Up/Down/Home/End
+ * move focus; Arrow Right expands (or moves to the first child); Arrow Left
+ * collapses (or moves to the parent); Enter selects and fires `onActivate`,
+ * Space selects only; printable characters run typeahead; `*` expands the
+ * focused node's collapsed siblings. Under `selectionMode="multiple"`:
+ * Shift+Arrow moves and toggles, Shift+Space selects the contiguous run from
+ * the last selected node, Control+Shift+Home/End selects to an edge, Ctrl+A
+ * toggles all/cleared, Ctrl+Arrow moves focus only.
  *
- * 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 are each controlled or uncontrolled independently.
  *
- * Expansion and selection each work controlled (`expandedIds`/`selectedIds`
- * + their `onChange`) or uncontrolled (`defaultExpandedIds`/`defaultSelectedIds`).
+ * `loadChildren` lazily populates a branch on first expand, marking it
+ * `aria-busy` and announcing on arrival. `selectionPropagation="descendants"`
+ * makes it a tri-state checkbox tree reporting `aria-checked` instead of
+ * `aria-selected`. `checkedIds`/`defaultCheckedIds` give it a checked axis
+ * separate from `selectedIds`, which then becomes row highlight only.
  *
- * `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.
+ * Needs an accessible name (`aria-label`/`aria-labelledby`) — APG requires one
+ * on `role="tree"`, which takes no name from its content or node labels.
  *
  * @example
  * ```tsx
- * <Tree defaultExpandedIds={['src']}>
+ * <Tree
+ *   aria-label="Project files"
+ *   collection={[{ nodeId: 'src', children: [{ nodeId: 'src/index.ts', label: 'index.ts' }] }]}
+ *   defaultExpandedIds={['src']}
+ * />
+ * ```
+ *
+ * @example Full manual composition, for anything `collection` can't express — `@skdx/react/primitives/tree`.
+ * ```tsx
+ * import { Tree, TreeGroup, TreeItem, TreeItemIndicator } from '@skdx/react/primitives/tree';
+ *
+ * <Tree aria-label="Project files" defaultExpandedIds={['src']}>
  *   <TreeItem nodeId="src">
  *     <TreeItemIndicator>▸</TreeItemIndicator>
  *     src