@skdx/react 0.27.0 → 0.29.0

package/dist/tree/Tree.js

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

package/dist/tree/TreeAnatomy.d.cts

@@ -0,0 +1,4 @@
+import type * as React from 'react';
+import type { TreeNode } from './types.cjs';
+/** @internal The `collection` data path: builds the same `TreeItem`/`TreeGroup` structure a consumer writes by hand. */
+export declare function TreeAnatomy(nodes: readonly TreeNode[], renderLabel: ((node: TreeNode) => React.ReactNode) | undefined): React.ReactNode;

package/dist/tree/TreeAnatomy.d.ts

@@ -0,0 +1,4 @@
+import type * as React from 'react';
+import type { TreeNode } from './types.js';
+/** @internal The `collection` data path: builds the same `TreeItem`/`TreeGroup` structure a consumer writes by hand. */
+export declare function TreeAnatomy(nodes: readonly TreeNode[], renderLabel: ((node: TreeNode) => React.ReactNode) | undefined): React.ReactNode;

package/dist/tree/TreeGroup.d.cts

@@ -1,10 +1,7 @@
 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.
+ * Collapsible `<div role="group">` container for child `TreeItem`s, unmounted while the parent is collapsed unless `forceMount`.
  *
  * @example
  * ```tsx
@@ -16,4 +13,7 @@ import type { TreeGroupProps } from './types.cjs';
  * </TreeItem>
  * ```
  */
-export declare const TreeGroup: React.ForwardRefExoticComponent<Omit<TreeGroupProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+export declare const TreeGroup: {
+    ({ forceMount, children, ref: forwardedRef, ...props }: TreeGroupProps): React.ReactNode;
+    displayName: string;
+};

package/dist/tree/TreeGroup.d.ts

@@ -1,10 +1,7 @@
 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.
+ * Collapsible `<div role="group">` container for child `TreeItem`s, unmounted while the parent is collapsed unless `forceMount`.
  *
  * @example
  * ```tsx
@@ -16,4 +13,7 @@ import type { TreeGroupProps } from './types.js';
  * </TreeItem>
  * ```
  */
-export declare const TreeGroup: React.ForwardRefExoticComponent<Omit<TreeGroupProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+export declare const TreeGroup: {
+    ({ forceMount, children, ref: forwardedRef, ...props }: TreeGroupProps): React.ReactNode;
+    displayName: string;
+};

package/dist/tree/TreeItem.d.cts

@@ -1,26 +1,12 @@
 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;
+export declare const TreeItemProvider: React.FC<TreeItemContextValue & {
+    children: React.ReactNode;
+}>, useTreeItemContext: (consumerName: string) => TreeItemContextValue;
+/** @internal Maps hasChildren/expanded to the `data-state` string shared by `TreeItem` and `TreeItemIndicator`. */
+export declare function expandStateAttr(hasChildren: boolean, expanded: boolean): 'expanded' | 'collapsed' | undefined;
 /**
- * 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.
+ * Single tree node (`role="treeitem"`), publishing `aria-level`/`aria-posinset`/`aria-setsize`, `aria-selected`/`aria-checked`, and the CSS custom property `--skdx-tree-node-depth`.
  *
  * @example
  * ```tsx
@@ -33,4 +19,7 @@ export declare const TreeItemProvider: {
  * </TreeItem>
  * ```
  */
-export declare const TreeItem: React.ForwardRefExoticComponent<Omit<TreeItemProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+export declare const TreeItem: {
+    ({ nodeId, disabled, hasChildren: hasChildrenProp, textValue, children, ref: forwardedRef, ...props }: TreeItemProps): React.ReactNode;
+    displayName: string;
+};

package/dist/tree/TreeItem.d.ts

@@ -1,26 +1,12 @@
 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;
+export declare const TreeItemProvider: React.FC<TreeItemContextValue & {
+    children: React.ReactNode;
+}>, useTreeItemContext: (consumerName: string) => TreeItemContextValue;
+/** @internal Maps hasChildren/expanded to the `data-state` string shared by `TreeItem` and `TreeItemIndicator`. */
+export declare function expandStateAttr(hasChildren: boolean, expanded: boolean): 'expanded' | 'collapsed' | undefined;
 /**
- * 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.
+ * Single tree node (`role="treeitem"`), publishing `aria-level`/`aria-posinset`/`aria-setsize`, `aria-selected`/`aria-checked`, and the CSS custom property `--skdx-tree-node-depth`.
  *
  * @example
  * ```tsx
@@ -33,4 +19,7 @@ export declare const TreeItemProvider: {
  * </TreeItem>
  * ```
  */
-export declare const TreeItem: React.ForwardRefExoticComponent<Omit<TreeItemProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+export declare const TreeItem: {
+    ({ nodeId, disabled, hasChildren: hasChildrenProp, textValue, children, ref: forwardedRef, ...props }: TreeItemProps): React.ReactNode;
+    displayName: string;
+};

package/dist/tree/TreeItemIndicator.d.cts

@@ -1,11 +1,7 @@
-import * as React from 'react';
+import type * 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.
+ * Expand/collapse affordance within a `TreeItem`, a `<span>` publishing `data-state` that toggles expansion on click.
  *
  * @example
  * ```tsx
@@ -15,4 +11,7 @@ import type { TreeItemIndicatorProps } from './types.cjs';
  * </TreeItem>
  * ```
  */
-export declare const TreeItemIndicator: React.ForwardRefExoticComponent<Omit<TreeItemIndicatorProps, "ref"> & React.RefAttributes<HTMLSpanElement>>;
+export declare const TreeItemIndicator: {
+    ({ ref: forwardedRef, ...props }: TreeItemIndicatorProps): React.ReactNode;
+    displayName: string;
+};

package/dist/tree/TreeItemIndicator.d.ts

@@ -1,11 +1,7 @@
-import * as React from 'react';
+import type * 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.
+ * Expand/collapse affordance within a `TreeItem`, a `<span>` publishing `data-state` that toggles expansion on click.
  *
  * @example
  * ```tsx
@@ -15,4 +11,7 @@ import type { TreeItemIndicatorProps } from './types.js';
  * </TreeItem>
  * ```
  */
-export declare const TreeItemIndicator: React.ForwardRefExoticComponent<Omit<TreeItemIndicatorProps, "ref"> & React.RefAttributes<HTMLSpanElement>>;
+export declare const TreeItemIndicator: {
+    ({ ref: forwardedRef, ...props }: TreeItemIndicatorProps): React.ReactNode;
+    displayName: string;
+};

package/dist/tree/index.d.cts

@@ -1,5 +1,2 @@
-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';
+export { Tree } from './Tree.cjs';
+export type { TreeHandle, TreeNode, TreeProps } from './types.cjs';

package/dist/tree/index.d.ts

@@ -1,5 +1,2 @@
-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';
+export { Tree } from './Tree.js';
+export type { TreeHandle, TreeNode, TreeProps } from './types.js';

package/dist/tree/primitives.d.cts

@@ -0,0 +1,24 @@
+/**
+ * Advanced primitives for `Tree` — the parts the recipe composes. Use
+ * for full manual composition.
+ *
+ * @example
+ * ```tsx
+ * import { Tree, TreeGroup, TreeItem, TreeItemIndicator } from '@skdx/react/primitives/tree';
+ *
+ * <Tree aria-label="Project files">
+ *   <TreeItem nodeId="src">
+ *     <TreeItemIndicator>▸</TreeItemIndicator>
+ *     src
+ *     <TreeGroup>
+ *       <TreeItem nodeId="src/index.ts">index.ts</TreeItem>
+ *     </TreeGroup>
+ *   </TreeItem>
+ * </Tree>
+ * ```
+ */
+export { Tree, defaultGetLoadedLabel } from './Tree.cjs';
+export { TreeItem } from './TreeItem.cjs';
+export { TreeGroup } from './TreeGroup.cjs';
+export { TreeItemIndicator } from './TreeItemIndicator.cjs';
+export type { TreeProps, TreeNode, TreeItemProps, TreeGroupProps, TreeItemIndicatorProps, TreeSelectionPropagation, TreeCheckedState, TreeHandle, TreeElementHandle, } from './types.cjs';

package/dist/tree/primitives.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Advanced primitives for `Tree` — the parts the recipe composes. Use
+ * for full manual composition.
+ *
+ * @example
+ * ```tsx
+ * import { Tree, TreeGroup, TreeItem, TreeItemIndicator } from '@skdx/react/primitives/tree';
+ *
+ * <Tree aria-label="Project files">
+ *   <TreeItem nodeId="src">
+ *     <TreeItemIndicator>▸</TreeItemIndicator>
+ *     src
+ *     <TreeGroup>
+ *       <TreeItem nodeId="src/index.ts">index.ts</TreeItem>
+ *     </TreeGroup>
+ *   </TreeItem>
+ * </Tree>
+ * ```
+ */
+export { Tree, defaultGetLoadedLabel } from './Tree.js';
+export { TreeItem } from './TreeItem.js';
+export { TreeGroup } from './TreeGroup.js';
+export { TreeItemIndicator } from './TreeItemIndicator.js';
+export type { TreeProps, TreeNode, TreeItemProps, TreeGroupProps, TreeItemIndicatorProps, TreeSelectionPropagation, TreeCheckedState, TreeHandle, TreeElementHandle, } from './types.js';

package/dist/tree/types.d.cts

@@ -1,20 +1,20 @@
 import type { PrimitivePropsWithRef } from '../utils/primitive.cjs';
 /** How many nodes a {@link Tree} allows selected at once: one, many, or no selection. */
 export type SelectionMode = 'single' | 'multiple' | 'none';
-/**
- * Whether selecting a node also selects its subtree. `'descendants'` turns the
- * tree into a tri-state checkbox tree: toggling a node applies to every one of
- * its descendants, and a parent reports `aria-checked` of `true`, `false`, or
- * `"mixed"` derived from them.
- */
+/** Whether selecting a node also selects its subtree, turning the tree into a tri-state checkbox tree. */
 export type TreeSelectionPropagation = 'none' | 'descendants';
 /** A node's tri-state checkbox value, as reported on `aria-checked`. */
 export type TreeCheckedState = boolean | 'mixed';
-/**
- * A node's place among its siblings — the ones at its own level under its own
- * parent, not a flat index over the tree — as reported on `aria-posinset`
- * (1-based) and `aria-setsize`.
- */
+/** What a `TreeItem`'s `disabled` takes away: `'all'` makes it inert and unreachable, `'selection'` keeps it reachable but refusing selection. */
+export type TreeDisabledBehavior = 'all' | 'selection';
+/** Payload of {@link TreeProps.onLoadError} — the branch whose `loadChildren` rejected, and why. */
+export interface TreeLoadErrorDetail {
+    /** The node whose `loadChildren` call rejected. */
+    nodeId: string;
+    /** Whatever the rejected promise rejected with. Unknown by construction: `loadChildren` is the consumer's. */
+    error: unknown;
+}
+/** Node's position among siblings (reported as `aria-posinset` / `aria-setsize`, 1-based). */
 export interface TreeNodePosition {
     posinset: number;
     setsize: number;
@@ -29,21 +29,19 @@ export interface TreeContextValue {
     loadingIds: Set<string>;
     activeNodeId: string | null;
     setActiveNodeId: (nodeId: string) => void;
+    disabledBehavior: TreeDisabledBehavior;
+    /** Whether branch clicks toggle expansion and selection. */
+    expandOnClick: boolean;
     onExpandedChange: (nodeId: string, expanded: boolean) => void;
+    /** Toggles selection or checked state (depending on checked axis). */
     onSelectedChange: (nodeId: string) => void;
-    /**
-     * Tri-state value for a node: derived from its registered descendants when it
-     * has any, otherwise its own membership in `selectedIds`. Always `false` for
-     * every node unless `selectionPropagation` is `'descendants'`.
-     */
+    /** Fires root's `onActivate` (Enter and click, not Space). */
+    onActivate: (nodeId: string) => void;
+    /** Node's checked value (from `checkedIds` or `selectedIds`; tri-state with propagation). */
     checkedState: (nodeId: string) => TreeCheckedState;
-    /**
-     * A node's `aria-posinset`/`aria-setsize`, measured off the rendered DOM in
-     * document order. `undefined` until the first measurement lands (one commit
-     * after mount) or for a node that isn't rendered.
-     */
+    /** Node's `aria-posinset` / `aria-setsize` (measured from DOM; undefined until first measurement). */
     positionOf: (nodeId: string) => TreeNodePosition | undefined;
-    /** Called by each `TreeItem` on mount so the root can walk the node hierarchy without touching the DOM. */
+    /** Called by each `TreeItem` on mount (lets root walk hierarchy without touching DOM). */
     registerNode: (nodeId: string, parentId: string | null) => void;
     unregisterNode: (nodeId: string) => void;
 }
@@ -58,95 +56,168 @@ export interface TreeItemContextValue {
     /** Whether this node's `loadChildren` call is still pending. */
     loading: boolean;
 }
-/** Props for the {@link Tree} root. */
-export interface TreeProps extends Omit<PrimitivePropsWithRef<'div'>, 'defaultValue'> {
+/** Collection node; `nodeId` must be unique and keys all state. */
+export interface TreeNode {
+    /** Node identity in `expandedIds`, `selectedIds`, `checkedIds`, active node and `loadChildren`. */
+    nodeId: string;
+    /**
+     * Text rendered as node content (falls back to `nodeId`).
+     * @default undefined
+     */
+    label?: string | undefined;
+    /**
+     * Excludes node from selection and activation (like `TreeItem`'s `disabled`).
+     * @default false
+     */
+    disabled?: boolean | undefined;
+    /**
+     * Declares node as branch with unloaded children (reports `aria-expanded="false"`).
+     * @default undefined — inferred from `children`.
+     */
+    hasChildren?: boolean | undefined;
+    /**
+     * Text typeahead matches against (falls back to rendered text).
+     * @default undefined
+     */
+    textValue?: string | undefined;
+    /**
+     * Child nodes (rendered in collapsible `TreeGroup`).
+     * @default undefined — leaf.
+     */
+    children?: TreeNode[] | undefined;
+}
+export interface TreeProps extends Omit<PrimitivePropsWithRef<'div'>, 'defaultValue' | 'ref'> {
+    /**
+     * Hierarchical data the tree renders from (becomes source of truth; `children` ignored).
+     * @default undefined — renders `children`.
+     */
+    collection?: readonly TreeNode[] | undefined;
     /**
-     * `"single"`, `"multiple"`, or `"none"` (not selectable, just expand/collapse).
+     * Renders collection node content (ignored without `collection`).
+     * @default undefined — renders `label ?? nodeId`.
+     */
+    renderLabel?: ((node: TreeNode) => React.ReactNode) | undefined;
+    /**
+     * Selection mode (`'single'`, `'multiple'`, or `'none'` for expand/collapse only).
      * @default 'single'
      */
-    selectionMode?: SelectionMode;
+    selectionMode?: SelectionMode | undefined;
     /**
-     * Expanded node ids, for controlled usage. Pair with `onExpandedIdsChange`.
-     * @default undefined — uncontrolled, tracks its own expanded set internally.
+     * Expanded ids for controlled usage; pair with `onExpandedIdsChange`.
+     * @default undefined — uncontrolled.
      */
-    expandedIds?: string[];
+    expandedIds?: string[] | undefined;
     /**
-     * Initially expanded node ids, for uncontrolled usage.
+     * Initial expanded ids for uncontrolled usage.
      * @default []
      */
-    defaultExpandedIds?: string[];
+    defaultExpandedIds?: string[] | undefined;
     /**
-     * Fires with the new set of expanded ids whenever a node is expanded or collapsed, controlled or not.
-     * @default undefined — no-op if omitted.
+     * Fires with new expanded ids on expand/collapse.
+     * @default undefined — no-op.
      */
-    onExpandedIdsChange?: (ids: string[]) => void;
+    onExpandedIdsChange?: ((ids: string[]) => void) | undefined;
     /**
-     * Selected node ids, for controlled usage. Pair with `onSelectedIdsChange`.
-     * @default undefined — uncontrolled, tracks its own selected set internally.
+     * Selected ids for controlled usage; pair with `onSelectedIdsChange`.
+     * @default undefined — uncontrolled.
      */
-    selectedIds?: string[];
+    selectedIds?: string[] | undefined;
     /**
-     * Initially selected node ids, for uncontrolled usage.
+     * Initial selected ids for uncontrolled usage.
      * @default []
      */
-    defaultSelectedIds?: string[];
+    defaultSelectedIds?: string[] | undefined;
+    /**
+     * Fires with new selected ids on selection change.
+     * @default undefined — no-op.
+     */
+    onSelectedIdsChange?: ((ids: string[]) => void) | undefined;
+    /**
+     * Checked ids for controlled usage (second axis from `selectedIds`); pair with `onCheckedIdsChange`.
+     * @default undefined — uncontrolled; `aria-checked` derives from `selectedIds`.
+     */
+    checkedIds?: string[] | undefined;
     /**
-     * Fires with the new set of selected ids whenever selection changes, controlled or not.
-     * @default undefined — no-op if omitted.
+     * Initial checked ids for uncontrolled usage (gives tree own checked axis).
+     * @default undefined — no checked axis.
      */
-    onSelectedIdsChange?: (ids: string[]) => void;
+    defaultCheckedIds?: string[] | undefined;
     /**
-     * Turns the tree into a tri-state checkbox tree: toggling a node selects or
-     * deselects its whole subtree, and each node reports `aria-checked` of
-     * `true`/`false`/`"mixed"` derived from its descendants. Only meaningful with
-     * `selectionMode="multiple"`; ignored otherwise.
-     *
-     * Propagation reaches *rendered* descendants only — a collapsed `TreeGroup`
-     * is unmounted, so its nodes are not registered and cannot be toggled.
+     * Fires with new checked ids on check/uncheck.
+     * @default undefined — no-op.
+     */
+    onCheckedIdsChange?: ((ids: string[]) => void) | undefined;
+    /**
+     * Tri-state checkbox tree with selection propagation (toggle node selects/deselects subtree).
      * @default 'none'
      */
-    selectionPropagation?: TreeSelectionPropagation;
+    selectionPropagation?: TreeSelectionPropagation | undefined;
     /**
-     * Loads a node's children the first time it is expanded. Return a promise to
-     * mark the node busy (`aria-busy="true"` plus `data-loading`) until it
-     * settles; when it resolves, `getLoadedLabel` is announced through the shared
-     * live region. A rejected promise clears the busy state, announces nothing,
-     * and leaves the node eligible to retry on the next expand.
-     *
-     * The node still needs a `TreeGroup` child to be expandable at all — render
-     * an empty one and fill it in when the promise resolves.
-     * @default undefined — children are always rendered eagerly.
+     * Loads node's children on first expansion (marks node busy until settled).
+     * @default undefined — children eager.
      */
-    loadChildren?: (nodeId: string) => void | Promise<void>;
+    loadChildren?: ((nodeId: string) => void | Promise<void>) | undefined;
     /**
-     * Formats the message announced when a lazily-loaded node's children arrive —
-     * newly rendered children are otherwise silent. Return an empty string to
-     * announce nothing. Close over your own data if you want a count in it.
-     * @default defaultGetLoadedLabel — e.g. `"src loaded"`
+     * Formats announcement when lazily-loaded children arrive.
+     * @default defaultGetLoadedLabel — e.g. `"src loaded"`.
      */
-    getLoadedLabel?: (nodeId: string) => string;
+    getLoadedLabel?: ((nodeId: string) => string) | undefined;
+    /**
+     * Fires when `loadChildren` rejects (swallowed silently if not fired).
+     * @default undefined — no-op.
+     */
+    onLoadError?: ((detail: TreeLoadErrorDetail) => void) | undefined;
+    /**
+     * Fires on Enter or click (not Space).
+     * @default undefined — no-op.
+     */
+    onActivate?: ((nodeId: string) => void) | undefined;
+    /**
+     * What node's `disabled` takes away (see {@link TreeDisabledBehavior}}).
+     * @default 'all'
+     */
+    disabledBehavior?: TreeDisabledBehavior | undefined;
+    /**
+     * Whether branch clicks toggle expansion and selection.
+     * @default true
+     */
+    expandOnClick?: boolean | undefined;
 }
+/** Imperative Tree contract (assigned on root `<div>`). */
+export interface TreeHandle {
+    /** Clears load marker (or node + subtree with `nodeId`) for refetch on next expansion. */
+    invalidate(nodeId?: string): void;
+}
+/** {@link Tree}}'s forwarded ref (root `<div>` plus `invalidate()`). */
+export type TreeElementHandle = HTMLDivElement & TreeHandle;
 /** Props for a single {@link TreeItem} node. */
 export interface TreeItemProps extends PrimitivePropsWithRef<'div'> {
     /** Unique identifier tracked in the tree's expanded/selected/active state. */
     nodeId: string;
     /**
-     * Excludes this node (and its subtree's roving-focus/typeahead reach) from
-     * selection and keyboard activation.
+     * Excludes node from selection and activation (not inherited by descendants).
      * @default false
      */
-    disabled?: boolean;
+    disabled?: boolean | undefined;
+    /**
+     * Typeahead text (published as `data-text-value`; falls back to rendered text).
+     * @default undefined
+     */
+    textValue?: string | undefined;
+    /**
+     * Declares node as branch, overriding `TreeGroup` scan (true makes it expandable before group mounts).
+     * @default undefined — inferred from `TreeGroup`.
+     */
+    hasChildren?: boolean | undefined;
 }
-/** Props for {@link TreeGroup}, the collapsible container of a `TreeItem`'s children. */
+/** Props for {@link TreeGroup}}, collapsible container of `TreeItem`'s children. */
 export interface TreeGroupProps extends PrimitivePropsWithRef<'div'> {
     /**
-     * Keep this group mounted even while its parent `TreeItem` is collapsed,
-     * instead of unmounting it. Useful for animation libraries that need the
-     * outgoing content present in the DOM during an exit transition.
+     * Keep group mounted while parent `TreeItem` collapsed.
      * @default false
      */
-    forceMount?: boolean;
+    forceMount?: boolean | undefined;
 }
-/** Props for {@link TreeItemIndicator}, the expand/collapse affordance (e.g. a chevron) within a `TreeItem`. */
+/** Props for {@link TreeItemIndicator}}, the expand/collapse affordance. */
 export interface TreeItemIndicatorProps extends PrimitivePropsWithRef<'span'> {
 }