@vjdesigns/vjdesigns-ui 0.0.0-stage → 2.0.0

package/dist/components/data-display/Timeline/Timeline.d.ts

@@ -0,0 +1,92 @@
+import { ComponentPropsWithRef, ReactNode } from 'react';
+import { Orientation, Size, Tone } from '../../../types/common';
+/**
+ * Where item content sits relative to the line.
+ * - `start`: content after the line (right of it in left-to-right text; below it when horizontal).
+ * - `end`: content before the line (left of it; above it when horizontal).
+ * - `alternate`: zig-zags between both sides. Vertical timelines collapse to
+ *   `start` when the timeline is narrower than 40rem (container query).
+ */
+export type TimelineAlign = "start" | "alternate" | "end";
+/** Connector line style. Per-item status can still override a segment (upcoming segments are always dashed). */
+export type TimelineVariant = "solid" | "dashed";
+/** Progress status of an item. Changes the marker shape and the connector segment after it. */
+export type TimelineStatus = "complete" | "current" | "upcoming" | "error";
+/** Screen-reader text announced before each item's content, per status. */
+export type TimelineStatusLabels = Partial<Record<TimelineStatus, string>>;
+/** Default screen-reader text for each status. */
+export declare const defaultTimelineStatusLabels: Record<TimelineStatus, string>;
+export interface TimelineOwnProps {
+    /** Direction of the line. Use `horizontal` for short milestone tracks; it scrolls sideways (and becomes keyboard scrollable) when it overflows. @default "vertical" */
+    orientation?: Orientation;
+    /** Which side of the line the content sits on. @default "start" */
+    align?: TimelineAlign;
+    /** Marker size, spacing, and type size. @default "md" */
+    size?: Size;
+    /** Connector line style. @default "solid" */
+    variant?: TimelineVariant;
+    /** Overrides the screen-reader text for statuses ("Completed", "Current step", "Upcoming", "Error"). */
+    statusLabels?: TimelineStatusLabels;
+    /**
+     * Accessible name for the horizontal scroll region, used only when a
+     * horizontal timeline overflows and becomes focusable. Falls back to
+     * `aria-label`, then "Timeline".
+     */
+    scrollLabel?: string;
+    /** `Timeline.Item` elements. */
+    children?: ReactNode;
+}
+export type TimelineProps = TimelineOwnProps & Omit<ComponentPropsWithRef<"ol">, keyof TimelineOwnProps>;
+declare function TimelineRoot({ orientation, align, size, variant, statusLabels, scrollLabel, className, children, ref, ...rest }: TimelineProps): import("react").JSX.Element;
+export interface TimelineItemOwnProps {
+    /** Item heading, in bold display type. */
+    title?: ReactNode;
+    /** Supporting text under the title. */
+    description?: ReactNode;
+    /** When it happened, e.g. "Oct 12" or "2h ago". Rendered in a `<time>` element when `dateTime` is set. */
+    time?: ReactNode;
+    /** Machine-readable date for `time` (e.g. `"2026-10-12"` or `"2026-10-12T19:30"`). */
+    dateTime?: string;
+    /** Extra muted detail next to the time (e.g. a location or author). */
+    meta?: ReactNode;
+    /**
+     * Icon shown in a tone-tinted circle instead of the dot. Decorative: the
+     * title must carry the meaning. Overrides the status marker shape (the
+     * status is still announced), so prefer it for items without a status.
+     */
+    icon?: ReactNode;
+    /**
+     * Fully custom marker, such as an `Avatar` (pass `decorative` when the
+     * name is visible in the content). Overrides `icon` and the status shape.
+     */
+    marker?: ReactNode;
+    /** Color of the marker and the connector segment after it. @default "danger" when `status="error"`, otherwise "primary" */
+    tone?: Tone;
+    /**
+     * Progress status. `complete` shows a filled check, `current` a pulsing
+     * ring (and sets `aria-current="step"`), `upcoming` a hollow circle, and
+     * `error` a filled cross. Each is also announced as hidden text.
+     */
+    status?: TimelineStatus;
+    /** Overrides the screen-reader status text for this item. */
+    statusLabel?: string;
+    /** Render the content inside a rounded outline card (for activity feeds). @default false */
+    card?: boolean;
+    /** Extra content below the description (links, badges, a stat line). */
+    children?: ReactNode;
+}
+export type TimelineItemProps = TimelineItemOwnProps & Omit<ComponentPropsWithRef<"li">, keyof TimelineItemOwnProps>;
+declare function TimelineItem({ title, description, time, dateTime, meta, icon, marker, tone, status, statusLabel, card, className, children, ...rest }: TimelineItemProps): import("react").JSX.Element;
+type TimelineComponent = typeof TimelineRoot & {
+    /** One event or step on the timeline. */
+    Item: typeof TimelineItem;
+};
+/**
+ * A vertical or horizontal sequence of events or steps, rendered as an
+ * ordered list. Items show a marker on a connector line plus a title,
+ * time, meta, and description. Use `status` for progress tracking
+ * (complete, current, upcoming, error): each status has its own marker
+ * shape and hidden status text, so it never relies on color alone.
+ */
+export declare const Timeline: TimelineComponent;
+export { TimelineItem };

package/dist/components/data-display/Timeline/Timeline.mjs

@@ -0,0 +1,140 @@
+import { en as e } from "../../../i18n/en.mjs";
+import { useMessages as t } from "../../utilities/LocaleProvider/LocaleProvider.mjs";
+import { assignRef as n } from "../../../utils/refs.mjs";
+import { cx as r } from "../../../utils/cx.mjs";
+import { VisuallyHidden as i } from "../../utilities/VisuallyHidden/VisuallyHidden.mjs";
+import { CheckIcon as a, CloseIcon as o } from "../../primitives/Icon/icons.mjs";
+import { Card as s } from "../Card/Card.mjs";
+import c from "./Timeline.module.css.mjs";
+import { createContext as l, useCallback as u, useContext as d, useLayoutEffect as f, useRef as p, useState as m } from "react";
+import { jsx as h, jsxs as g } from "react/jsx-runtime";
+//#region src/components/data-display/Timeline/Timeline.tsx
+var _ = e.timeline.status, v = {
+	sm: c.sm,
+	md: c.md,
+	lg: c.lg
+}, y = {
+	vertical: c.vertical,
+	horizontal: c.horizontal
+}, b = {
+	start: c.alignStart,
+	alternate: c.alignAlternate,
+	end: c.alignEnd
+}, x = {
+	solid: c.solid,
+	dashed: c.dashed
+}, S = {
+	neutral: c.neutral,
+	primary: c.primary,
+	accent: c.accent,
+	success: c.success,
+	warning: c.warning,
+	danger: c.danger,
+	info: c.info
+}, C = {
+	complete: c.statusComplete,
+	current: c.statusCurrent,
+	upcoming: c.statusUpcoming,
+	error: c.statusError
+}, w = l({ statusLabels: _ });
+function T({ orientation: e = "vertical", align: i = "start", size: a = "md", variant: o = "solid", statusLabels: s, scrollLabel: l, className: d, children: g, ref: _, ...S }) {
+	let C = t(), T = e === "horizontal", E = p(null), D = p(null), [O, k] = m(!1), A = u((e) => {
+		D.current = e, n(_, e);
+	}, [_]);
+	f(() => {
+		if (!T) return;
+		let e = E.current, t = D.current;
+		if (!e || !t) return;
+		let n = () => k(e.scrollWidth > e.clientWidth);
+		if (n(), typeof ResizeObserver > "u") return;
+		let r = new ResizeObserver(n);
+		return r.observe(e), r.observe(t), () => r.disconnect();
+	}, [T]);
+	let j = { statusLabels: {
+		...C.timeline.status,
+		...s
+	} }, M = /* @__PURE__ */ h("ol", {
+		role: "list",
+		...S,
+		ref: A,
+		className: r(c.root, y[e], b[i], v[a], x[o], d),
+		children: g
+	});
+	return /* @__PURE__ */ h(w.Provider, {
+		value: j,
+		children: T ? /* @__PURE__ */ h("div", {
+			ref: E,
+			className: c.scroller,
+			role: O ? "region" : void 0,
+			"aria-label": O ? l ?? S["aria-label"] ?? C.timeline.region : void 0,
+			tabIndex: O ? 0 : void 0,
+			children: M
+		}) : M
+	});
+}
+function E({ title: e, description: t, time: n, dateTime: l, meta: u, icon: f, marker: p, tone: m, status: _, statusLabel: v, card: y = !1, className: b, children: x, ...T }) {
+	let { statusLabels: E } = d(w), D = m ?? (_ === "error" ? "danger" : "primary"), O = _ ? v ?? E[_] : void 0, k = p == null ? f == null ? _ ? "status" : "dot" : "icon" : "custom", A = null;
+	k === "custom" ? A = p : k === "icon" ? A = f : _ === "complete" ? A = /* @__PURE__ */ h(a, { strokeWidth: 3 }) : _ === "error" && (A = /* @__PURE__ */ h(o, { strokeWidth: 3 }));
+	let j = n != null || u != null, M = /* @__PURE__ */ g("div", {
+		className: c.body,
+		children: [
+			O && /* @__PURE__ */ h(i, { children: `${O}: ` }),
+			e != null && /* @__PURE__ */ h("div", {
+				className: c.title,
+				children: e
+			}),
+			j && /* @__PURE__ */ g("div", {
+				className: c.meta,
+				children: [
+					n != null && (l ? /* @__PURE__ */ h("time", {
+						className: c.time,
+						dateTime: l,
+						children: n
+					}) : /* @__PURE__ */ h("span", {
+						className: c.time,
+						children: n
+					})),
+					n != null && u != null && /* @__PURE__ */ h("span", {
+						className: c.separator,
+						"aria-hidden": "true"
+					}),
+					u != null && /* @__PURE__ */ h("span", { children: u })
+				]
+			}),
+			t != null && /* @__PURE__ */ h("div", {
+				className: c.description,
+				children: t
+			}),
+			x != null && /* @__PURE__ */ h("div", {
+				className: c.extra,
+				children: x
+			})
+		]
+	});
+	return /* @__PURE__ */ g("li", {
+		"aria-current": _ === "current" ? "step" : void 0,
+		...T,
+		className: r(c.item, S[D], _ && C[_], b),
+		"data-status": _,
+		children: [/* @__PURE__ */ g("div", {
+			className: c.rail,
+			"aria-hidden": "true",
+			children: [/* @__PURE__ */ h("span", {
+				className: r(c.marker, k === "dot" && c.markerDot, k === "icon" && c.markerIcon, k === "status" && c.markerStatus, k === "custom" && c.markerCustom),
+				children: A
+			}), /* @__PURE__ */ h("span", { className: c.connector })]
+		}), /* @__PURE__ */ h("div", {
+			className: r(c.content, y && c.contentCard),
+			children: y ? /* @__PURE__ */ h(s, {
+				as: "div",
+				variant: "outline",
+				padding: "sm",
+				radius: "lg",
+				children: M
+			}) : M
+		})]
+	});
+}
+var D = Object.assign(T, { Item: E });
+//#endregion
+export { D as Timeline, E as TimelineItem, _ as defaultTimelineStatusLabels };

package/dist/components/data-display/Timeline/Timeline.module.css.cjs.js

@@ -0,0 +1 @@
+var e=`_root_vxox2_35`,t=`_solid_vxox2_101`,n=`_dashed_vxox2_109`,r=`_sm_vxox2_121`,i=`_md_vxox2_145`,a=`_lg_vxox2_169`,o=`_neutral_vxox2_197`,s=`_primary_vxox2_213`,c=`_accent_vxox2_229`,l=`_success_vxox2_245`,u=`_warning_vxox2_261`,d=`_danger_vxox2_277`,f=`_info_vxox2_293`,p=`_statusComplete_vxox2_319`,m=`_statusUpcoming_vxox2_329`,h=`_item_vxox2_353`,g=`_rail_vxox2_365`,_=`_connector_vxox2_377`,v=`_content_vxox2_393`,y=`_body_vxox2_403`,b=`_title_vxox2_411`,x=`_meta_vxox2_431`,S=`_time_vxox2_451`,C=`_separator_vxox2_463`,w=`_description_vxox2_479`,T=`_extra_vxox2_513`,E=`_marker_vxox2_529`,D=`_markerDot_vxox2_567`,O=`_markerIcon_vxox2_587`,k=`_markerStatus_vxox2_605`,A=`_statusError_vxox2_339`,j=`_statusCurrent_vxox2_339`,M=`_markerCustom_vxox2_723`,N=`_vertical_vxox2_749`,P=`_contentCard_vxox2_813`,F=`_alignStart_vxox2_823`,I=`_alignAlternate_vxox2_825`,L=`_alignEnd_vxox2_837`,R=`_scroller_vxox2_899`,z=`_horizontal_vxox2_929`,B={root:e,solid:t,dashed:n,sm:r,md:i,lg:a,neutral:o,primary:s,accent:c,success:l,warning:u,danger:d,info:f,statusComplete:p,statusUpcoming:m,item:h,rail:g,connector:_,content:v,body:y,title:b,meta:x,time:S,separator:C,description:w,extra:T,marker:E,markerDot:D,markerIcon:O,markerStatus:k,statusError:A,statusCurrent:j,"timeline-pulse":`_timeline-pulse_vxox2_1`,markerCustom:M,vertical:N,contentCard:P,alignStart:F,alignAlternate:I,alignEnd:L,scroller:R,horizontal:z};exports.accent=c,exports.alignAlternate=I,exports.alignEnd=L,exports.alignStart=F,exports.body=y,exports.connector=_,exports.content=v,exports.contentCard=P,exports.danger=d,exports.dashed=n,exports.default=B,exports.description=w,exports.extra=T,exports.horizontal=z,exports.info=f,exports.item=h,exports.lg=a,exports.marker=E,exports.markerCustom=M,exports.markerDot=D,exports.markerIcon=O,exports.markerStatus=k,exports.md=i,exports.meta=x,exports.neutral=o,exports.primary=s,exports.rail=g,exports.root=e,exports.scroller=R,exports.separator=C,exports.sm=r,exports.solid=t,exports.statusComplete=p,exports.statusCurrent=j,exports.statusError=A,exports.statusUpcoming=m,exports.success=l,exports.time=S,exports.title=b,exports.vertical=N,exports.warning=u;

package/dist/components/data-display/Timeline/Timeline.module.css.mjs

@@ -0,0 +1,46 @@
+//#region src/components/data-display/Timeline/Timeline.module.css
+var e = "_root_vxox2_35", t = "_solid_vxox2_101", n = "_dashed_vxox2_109", r = "_sm_vxox2_121", i = "_md_vxox2_145", a = "_lg_vxox2_169", o = "_neutral_vxox2_197", s = "_primary_vxox2_213", c = "_accent_vxox2_229", l = "_success_vxox2_245", u = "_warning_vxox2_261", d = "_danger_vxox2_277", f = "_info_vxox2_293", p = "_statusComplete_vxox2_319", m = "_statusUpcoming_vxox2_329", h = "_item_vxox2_353", g = "_rail_vxox2_365", _ = "_connector_vxox2_377", v = "_content_vxox2_393", y = "_body_vxox2_403", b = "_title_vxox2_411", x = "_meta_vxox2_431", S = "_time_vxox2_451", C = "_separator_vxox2_463", w = "_description_vxox2_479", T = "_extra_vxox2_513", E = "_marker_vxox2_529", D = "_markerDot_vxox2_567", O = "_markerIcon_vxox2_587", k = "_markerStatus_vxox2_605", A = "_statusError_vxox2_339", j = "_statusCurrent_vxox2_339", M = "_markerCustom_vxox2_723", N = "_vertical_vxox2_749", P = "_contentCard_vxox2_813", F = "_alignStart_vxox2_823", I = "_alignAlternate_vxox2_825", L = "_alignEnd_vxox2_837", R = "_scroller_vxox2_899", z = "_horizontal_vxox2_929", B = {
+	root: e,
+	solid: t,
+	dashed: n,
+	sm: r,
+	md: i,
+	lg: a,
+	neutral: o,
+	primary: s,
+	accent: c,
+	success: l,
+	warning: u,
+	danger: d,
+	info: f,
+	statusComplete: p,
+	statusUpcoming: m,
+	item: h,
+	rail: g,
+	connector: _,
+	content: v,
+	body: y,
+	title: b,
+	meta: x,
+	time: S,
+	separator: C,
+	description: w,
+	extra: T,
+	marker: E,
+	markerDot: D,
+	markerIcon: O,
+	markerStatus: k,
+	statusError: A,
+	statusCurrent: j,
+	"timeline-pulse": "_timeline-pulse_vxox2_1",
+	markerCustom: M,
+	vertical: N,
+	contentCard: P,
+	alignStart: F,
+	alignAlternate: I,
+	alignEnd: L,
+	scroller: R,
+	horizontal: z
+};
+//#endregion
+export { c as accent, I as alignAlternate, L as alignEnd, F as alignStart, y as body, _ as connector, v as content, P as contentCard, d as danger, n as dashed, B as default, w as description, T as extra, z as horizontal, f as info, h as item, a as lg, E as marker, M as markerCustom, D as markerDot, O as markerIcon, k as markerStatus, i as md, x as meta, o as neutral, s as primary, g as rail, e as root, R as scroller, C as separator, r as sm, t as solid, p as statusComplete, j as statusCurrent, A as statusError, m as statusUpcoming, l as success, S as time, b as title, N as vertical, u as warning };

package/dist/components/data-display/Timeline/index.d.ts

@@ -0,0 +1 @@
+export * from './Timeline';

package/dist/components/data-display/TreeView/TreeView.cjs.js

@@ -0,0 +1 @@
+const e=require("../../../hooks/useControllableState.cjs.js"),t=require("../../utilities/LocaleProvider/LocaleProvider.cjs.js"),n=require("../../../utils/cx.cjs.js"),r=require("../../utilities/VisuallyHidden/VisuallyHidden.cjs.js"),i=require("../../feedback/Spinner/Spinner.cjs.js"),a=require("../../primitives/Icon/icons.cjs.js"),o=require("./treeUtils.cjs.js"),s=require("./TreeView.module.css.cjs.js");let c=require("react"),l=require("react/jsx-runtime");var u={sm:s.default.sm,md:s.default.md,lg:s.default.lg},d=[],f=500,p=({items:p,expanded:m,defaultExpanded:h=d,onExpandedChange:g,selectionMode:_=`single`,selected:ee,defaultSelected:v=d,onSelectedChange:te,checkboxes:ne=!1,onAction:re,loadChildren:y,renderLabel:ie,size:ae=`md`,loadingLabel:oe,errorLabel:se,className:ce,ref:b,onKeyDown:le,onFocus:ue,onPointerMove:de,...fe})=>{let pe=t.useMessages(),x=oe??pe.treeView.loading,me=se??pe.treeView.error,he=(0,c.useId)(),S=_===`multiple`,C=S&&ne,[ge,_e]=e.useControllableState({value:m,defaultValue:h,onChange:g}),w=(0,c.useMemo)(()=>new Set(ge),[ge]),[T,E]=e.useControllableState({value:ee,defaultValue:v,onChange:te}),D=(0,c.useMemo)(()=>new Set(T),[T]),[O,ve]=(0,c.useState)(()=>new Map),[ye,k]=(0,c.useState)(()=>new Set),[A,j]=(0,c.useState)(()=>new Set),[be,M]=(0,c.useState)(``),[xe,Se]=(0,c.useState)(null),Ce=(0,c.useCallback)(e=>e.children??O.get(e.id),[O]),N=(0,c.useMemo)(()=>o.buildIndex(p,Ce),[p,Ce]),we=(0,c.useRef)(N);we.current=N;let P=(0,c.useMemo)(()=>o.visibleIds(p,N,w),[p,N,w]),Te=(0,c.useMemo)(()=>new Set(P),[P]),Ee=(0,c.useMemo)(()=>C?o.computeCheckStates(p,N,D):null,[C,p,N,D]),F=xe;for(;F&&!Te.has(F);)F=N.get(F)?.parentId??null;!F&&_!==`none`&&(F=P.find(e=>D.has(e))??null),F||=P[0]??null;let I=(0,c.useRef)(null),De=(0,c.useCallback)(e=>{if(I.current=e,typeof b==`function`)return b(e);b&&(b.current=e)},[b]),L=(0,c.useRef)(new Map),Oe=e=>t=>{let n=L.current;return n.set(e,t),()=>{n.get(e)===t&&n.delete(e)}},R=(0,c.useRef)(null),z=e=>{Se(e);let t=L.current.get(e);t?.isConnected?(t.focus({preventScroll:!0}),t.scrollIntoView?.({block:`nearest`})):R.current=e};(0,c.useLayoutEffect)(()=>{let e=R.current;if(!e)return;let t=L.current.get(e);t?.isConnected&&(R.current=null,t.focus({preventScroll:!0}),t.scrollIntoView?.({block:`nearest`}))});let ke=e=>{let t=document.activeElement;for(let n of w){if(e.has(n))continue;let r=L.current.get(n);r&&t&&r!==t&&r.contains(t)&&z(n)}_e([...e])},B=(e,t)=>{if(w.has(e)===t)return;let n=new Set(w);t?n.add(e):n.delete(e),ke(n)},V=(0,c.useRef)(new Set),H=(0,c.useRef)(!0);(0,c.useEffect)(()=>(H.current=!0,()=>{H.current=!1}),[]);let Ae=(0,c.useRef)(C);Ae.current=C;let je=(0,c.useRef)(D);je.current=D,(0,c.useEffect)(()=>{if(y)for(let e of w){let t=N.get(e);if(!t?.pending||V.current.has(e)||A.has(e))continue;let n=t.node,r=o.nodeText(n,L.current.get(e)?.querySelector(`[data-tree-label]`)?.textContent);V.current.add(e),k(new Set(V.current)),M(r?`${r}: ${x}`:x),Promise.resolve().then(()=>y(n)).then(t=>{if(H.current){if(V.current.delete(e),k(new Set(V.current)),we.current.get(e)?.node!==n){M(``);return}ve(n=>new Map(n).set(e,t)),M(``),Ae.current&&je.current.has(e)&&E(e=>[...new Set([...e,...o.collectIds(t)])])}},()=>{H.current&&(V.current.delete(e),k(new Set(V.current)),j(t=>new Set(t).add(e)),M(``))})}},[w,N,A,y,x,E]),(0,c.useEffect)(()=>{let e=[...O.keys()].filter(e=>!N.has(e));e.length>0&&ve(t=>{let n=new Map(t);return e.forEach(e=>n.delete(e)),n}),[...A].some(e=>!N.has(e))&&j(e=>new Set([...e].filter(e=>N.has(e))))},[N,O,A]),(0,c.useEffect)(()=>{[...A].some(e=>!w.has(e))&&j(e=>new Set([...e].filter(e=>w.has(e))))},[A,w]);let U=(0,c.useRef)(null),W=(0,c.useRef)(null),G=e=>{U.current=e,W.current=null},K=e=>!!N.get(e)?.node.disabled,q=e=>{let t=N.get(e);return!t||t.node.disabled?[]:[e,...(t.children??[]).flatMap(e=>q(e.id))]},Me=e=>!N.get(e)?.children?.length,J=e=>{E([...C?o.normalizeChecked(p,N,e):e])},Ne=(e,t,n)=>{for(let r of t)if(!K(r))for(let t of C?q(r):[r])n?e.add(t):e.delete(t);return e},Pe=(e,t)=>{for(let n of t){if(K(n))continue;let t=N.get(n);(C?t?.isParent&&w.has(n)?[]:q(n):[n]).forEach(t=>e.add(t))}return e},Fe=e=>{if(K(e))return;G(e);let t;t=C?!q(e).filter(Me).every(e=>D.has(e)):!D.has(e),J(Ne(new Set(D),[e],t))},Ie=e=>{K(e)||(G(e),(T.length!==1||T[0]!==e)&&E([e]))},Y=(e,t)=>{let n=P.indexOf(e),r=P.indexOf(t);n===-1&&(n=r),n>r&&([n,r]=[r,n]),W.current??=new Set(D),J(Pe(new Set(W.current),P.slice(n,r+1)))},Le=()=>{let e=C?p.flatMap(e=>q(e.id)):[...N.keys()].filter(e=>!K(e)),t=e.filter(e=>!C||Me(e)).every(e=>D.has(e));J(Ne(new Set(D),C?p.map(e=>e.id):e,!t))},X=(e,t,n)=>{let{node:r}=e;if(!r.disabled){if(S&&t===`pointer`){n&&U.current?Y(U.current,r.id):Fe(r.id);return}_===`single`&&Ie(r.id),re?re(r.id,r):e.isParent&&B(r.id,!w.has(r.id))}},Z=(0,c.useRef)({buffer:``,timer:0});(0,c.useEffect)(()=>()=>window.clearTimeout(Z.current.timer),[]);let Re=e=>{let t=N.get(e);return t?o.nodeText(t.node,L.current.get(e)?.querySelector(`[data-tree-label]`)?.textContent):``},ze=(e,t)=>{let n=Z.current;window.clearTimeout(n.timer),n.buffer+=e.toLowerCase(),n.timer=window.setTimeout(()=>{n.buffer=``},f);let r=n.buffer,i=Array.from(r).every(e=>e===r[0]),a=i?r[0]:r,o=i?t+1:Math.max(t,0),s=[...P.slice(o),...P.slice(0,o)].find(e=>Re(e).toLowerCase().startsWith(a));s&&z(s)},Be=e=>{if(le?.(e),e.defaultPrevented)return;let t=e.target;if(t.getAttribute(`role`)!==`treeitem`)return;let n=t.dataset.treeId,r=n?N.get(n):void 0;if(!n||!r)return;I.current?.removeAttribute(`data-pointer`);let i=P.indexOf(n),a=I.current?getComputedStyle(I.current).direction===`rtl`:!1,o=a?`ArrowLeft`:`ArrowRight`,s=a?`ArrowRight`:`ArrowLeft`,c=r.isParent&&w.has(n),l=e.ctrlKey||e.metaKey;switch(e.key){case`ArrowDown`:case`ArrowUp`:{e.preventDefault();let t=P[i+(e.key===`ArrowDown`?1:-1)];if(!t)return;z(t),S&&e.shiftKey&&(U.current||G(n),Y(U.current??n,t));return}case o:if(e.preventDefault(),!r.isParent)return;c?r.children?.length&&z(r.children[0].id):B(n,!0);return;case s:e.preventDefault(),c?B(n,!1):r.parentId&&z(r.parentId);return;case`Home`:case`End`:{e.preventDefault();let t=e.key===`Home`?P[0]:P[P.length-1];if(!t)return;S&&l&&e.shiftKey&&Y(n,t),z(t);return}case`Enter`:if(e.preventDefault(),e.repeat)return;X(r,`keyboard`,e.shiftKey);return;case` `:if(e.preventDefault(),Z.current.buffer){ze(` `,i);return}if(e.repeat)return;S?e.shiftKey&&U.current?Y(U.current,n):Fe(n):_===`single`&&Ie(n);return;case`*`:{e.preventDefault();let t=r.parentId?N.get(r.parentId)?.children??[]:p,n=new Set(w);for(let e of t)N.get(e.id)?.isParent&&n.add(e.id);n.size!==w.size&&ke(n);return}default:if(S&&l&&!e.altKey&&e.key.toLowerCase()===`a`){e.preventDefault(),Le();return}e.key.length===1&&!l&&!e.altKey&&(e.preventDefault(),ze(e.key,i))}},Q=(0,c.useRef)(null),Ve=e=>{ue?.(e);let t=e.target,n=t.getAttribute(`role`)===`treeitem`?t.dataset.treeId:void 0;n&&(Se(n),Q.current=t)};(0,c.useLayoutEffect)(()=>{let e=Q.current;if(!e||e.isConnected)return;Q.current=null;let t=document.activeElement;(!t||t===document.body)&&F&&z(F)});let He=(0,c.useRef)({x:NaN,y:NaN}),Ue=e=>{if(de?.(e),e.pointerType===`touch`)return;let t=He.current;(t.x!==e.clientX||t.y!==e.clientY)&&(t.x=e.clientX,t.y=e.clientY,e.currentTarget.setAttribute(`data-pointer`,``))},$=e=>{let t=N.get(e.id);if(!t)return null;let{level:r}=t,o=!!e.disabled,c=t.isParent&&w.has(e.id),u=c&&t.pending&&A.has(e.id),d=ye.has(e.id)||c&&t.pending&&!u,f=Ee?.get(e.id)??!1,p=C?f===!0:_!==`none`&&D.has(e.id),m={expanded:c,selected:p,checked:f,disabled:o,level:r,loading:d},h=typeof e.icon==`function`?e.icon(m):e.icon,g=`${he}-label-${t.ordinal}`,ee={"--_level":r},v={"--_level":r+1};return(0,l.jsxs)(`li`,{ref:Oe(e.id),role:`treeitem`,"data-tree-id":e.id,tabIndex:F===e.id?0:-1,"aria-labelledby":g,"aria-level":r,"aria-setsize":t.setsize,"aria-posinset":t.posinset,"aria-expanded":t.isParent?c:void 0,"aria-selected":_!==`none`&&!C?p:void 0,"aria-checked":C?f:void 0,"aria-disabled":o||void 0,className:s.default.item,children:[(0,l.jsxs)(`div`,{className:s.default.row,style:ee,"data-selected":p?``:void 0,"data-disabled":o?``:void 0,onClick:e=>{e.defaultPrevented||X(t,`pointer`,e.shiftKey)},children:[(0,l.jsx)(`span`,{"aria-hidden":`true`,className:s.default.toggle,"data-state":c?`open`:`closed`,onClick:t.isParent?t=>{t.preventDefault(),B(e.id,!c)}:void 0,children:t.isParent&&(0,l.jsx)(a.ChevronRightIcon,{className:s.default.chevron,size:`sm`,strokeWidth:2.5})}),C&&(0,l.jsxs)(`span`,{"aria-hidden":`true`,className:s.default.checkbox,"data-state":f===`mixed`?`mixed`:f?`checked`:`unchecked`,children:[(0,l.jsx)(a.CheckIcon,{className:n.cx(s.default.mark,s.default.check),strokeWidth:3}),(0,l.jsx)(a.MinusIcon,{className:n.cx(s.default.mark,s.default.minus),strokeWidth:3})]}),h&&(0,l.jsx)(`span`,{"aria-hidden":`true`,className:s.default.icon,children:h}),(0,l.jsx)(`span`,{id:g,className:s.default.label,"data-tree-label":``,children:ie?ie(e,m):e.label})]}),c&&(0,l.jsxs)(`ul`,{role:`group`,className:s.default.group,"aria-busy":d||void 0,children:[t.children?.map($),d&&!t.children&&(0,l.jsxs)(`li`,{role:`none`,className:s.default.status,style:v,children:[(0,l.jsx)(i.Spinner,{decorative:!0,size:`sm`,tone:`primary`}),(0,l.jsx)(`span`,{children:x})]}),u&&(0,l.jsxs)(`li`,{role:`none`,className:n.cx(s.default.status,s.default.error),style:v,children:[(0,l.jsx)(a.ErrorIcon,{size:`sm`}),(0,l.jsx)(`span`,{role:`alert`,children:me})]})]})]},e.id)};return(0,l.jsxs)(l.Fragment,{children:[(0,l.jsx)(`ul`,{...fe,ref:De,role:`tree`,"aria-multiselectable":S||void 0,className:n.cx(s.default.root,u[ae],C&&s.default.withCheckboxes,ce),onKeyDown:Be,onFocus:Ve,onPointerMove:Ue,children:p.map($)}),(0,l.jsx)(r.VisuallyHidden,{role:`status`,children:be})]})};exports.TreeView=p;

package/dist/components/data-display/TreeView/TreeView.d.ts

@@ -0,0 +1,86 @@
+import { ComponentPropsWithRef, ReactNode } from 'react';
+import { Size } from '../../../types/common';
+import { TreeNode, TreeNodeState } from './treeUtils';
+export type { TreeNode, TreeNodeState } from './treeUtils';
+/**
+ * How nodes can be selected.
+ * - `none`: no selection; nodes are only navigated, expanded, and activated (`onAction`).
+ * - `single`: one selected node (`aria-selected`). Click, Enter, or Space selects.
+ * - `multiple`: any number of selected nodes (`aria-multiselectable`). Click or Space toggles.
+ */
+export type TreeViewSelectionMode = "none" | "single" | "multiple";
+/** A tree needs an accessible name: `aria-label`, `aria-labelledby`, or both. */
+type TreeViewLabelling = {
+    "aria-label": string;
+    "aria-labelledby"?: string;
+} | {
+    "aria-label"?: string;
+    "aria-labelledby": string;
+};
+export interface TreeViewBaseProps extends Omit<ComponentPropsWithRef<"ul">, "children" | "role" | "aria-label" | "aria-labelledby" | "aria-multiselectable" | "defaultValue" | "onSelect"> {
+    /** The nodes to show. Each node has a unique `id`, a `label`, and optional `children`, `icon`, `disabled`, `hasChildren`. */
+    items: TreeNode[];
+    /** Ids of the open parent nodes (controlled). */
+    expanded?: string[];
+    /** Ids of the parent nodes open at first render (uncontrolled). @default [] */
+    defaultExpanded?: string[];
+    /** Called with every open id whenever a node is expanded or collapsed. */
+    onExpandedChange?: (ids: string[]) => void;
+    /** How nodes can be selected. See `TreeViewSelectionMode`. @default "single" */
+    selectionMode?: TreeViewSelectionMode;
+    /** Ids of the selected (or, with `checkboxes`, checked) nodes (controlled). */
+    selected?: string[];
+    /** Ids selected at first render (uncontrolled). @default [] */
+    defaultSelected?: string[];
+    /**
+     * Called with every selected id whenever the selection changes. With
+     * `checkboxes`, fully checked parents are included and partly checked ones
+     * are not.
+     */
+    onSelectedChange?: (ids: string[]) => void;
+    /**
+     * With `selectionMode="multiple"`, shows a checkbox on every node and uses
+     * `aria-checked` instead of `aria-selected`. Checking a parent checks all
+     * its (non-disabled) descendants; a partly checked parent is "mixed".
+     * Ignored in other modes. @default false
+     */
+    checkboxes?: boolean;
+    /**
+     * Called when a node is activated: Enter, or a click in `none` and `single`
+     * modes. Use it to open a file or navigate. Without it, activating a parent
+     * toggles it open. Never called for disabled nodes.
+     */
+    onAction?: (id: string, node: TreeNode) => void;
+    /**
+     * Loads the children of a node marked `hasChildren` the first time it's
+     * expanded. A loading row (with `aria-busy` on the group) shows meanwhile;
+     * a rejection shows an error row (`role="alert"`). Collapse and expand the
+     * node to try again.
+     */
+    loadChildren?: (node: TreeNode) => Promise<TreeNode[]>;
+    /** Custom label content. Receives the node and its state. Keep it non-interactive: the whole row is one control. */
+    renderLabel?: (node: TreeNode, state: TreeNodeState) => ReactNode;
+    /** Row height, text size, and indentation. @default "md" */
+    size?: Size;
+    /** Text of the loading row and its announcement. @default "Loading…" */
+    loadingLabel?: string;
+    /** Text of the error row when `loadChildren` fails. @default "Couldn't load items. Collapse and expand to try again." */
+    errorLabel?: string;
+}
+/** Props for `TreeView`. Requires `aria-label` or `aria-labelledby`. */
+export type TreeViewProps = TreeViewBaseProps & TreeViewLabelling;
+/**
+ * A hierarchical list (WAI-ARIA Tree View pattern) for file explorers,
+ * org charts, and nested categories. Data-driven: pass `items` as a tree of
+ * `TreeNode`s.
+ *
+ * One tab stop (roving tabindex). Arrows move, open, and close; Home and End
+ * jump; typing jumps by name; `*` opens all siblings; Enter activates; Space
+ * selects. Supports single, multiple, and tri-state checkbox selection, and
+ * children loaded on demand.
+ *
+ * ```tsx
+ * <TreeView aria-label="Files" items={files} onAction={(id) => open(id)} />
+ * ```
+ */
+export declare const TreeView: ({ items, expanded: expandedProp, defaultExpanded, onExpandedChange, selectionMode, selected: selectedProp, defaultSelected, onSelectedChange, checkboxes, onAction, loadChildren, renderLabel, size, loadingLabel: loadingLabelProp, errorLabel: errorLabelProp, className, ref, onKeyDown, onFocus, onPointerMove, ...rest }: TreeViewProps) => import("react").JSX.Element;