@eifi1/ui-kit 0.7.0 → 0.8.0

package/dist/components/tooltip.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/components/tooltip.tsx"],"sourcesContent":["import {\n  cloneElement,\n  isValidElement,\n  useId,\n  useLayoutEffect,\n  useRef,\n  useState,\n  type ComponentPropsWithoutRef,\n  type ReactElement,\n  type ReactNode,\n} from \"react\";\nimport { createPortal } from \"react-dom\";\nimport { cn } from \"../lib/cn\";\nimport { useEscapeKey } from \"../hooks/use-dismiss\";\nimport { useAnchoredRect, type AnchorRect } from \"../hooks/use-anchored-rect\";\n\ntype TooltipSide = \"top\" | \"bottom\" | \"left\" | \"right\";\n\n/** The floating bubble itself. Uses the shared surface/border/text tokens so it\n *  reads as part of the app's chrome (like the top bar and cards) rather than the\n *  cold slate pill it used to be.\n *\n *  `w-max` keeps a short label on one line — the old `whitespace-nowrap` did that\n *  too, but it also let a sentence-length label grow without bound, and a bubble\n *  wider than the space beside its trigger gets clipped by whatever overflow\n *  container it sits in. So cap it and let long text wrap instead. The cap tracks\n *  the viewport as well, for narrow screens where 20rem is already most of it.\n *  `side` is a preference rather than an instruction for the PORTALLED variant,\n *  which measures the bubble and turns it round when it would not fit\n *  (Steering Design feedback #126). The CSS-only one never learns its own size,\n *  so there `side` is still the whole of the placement. */\nconst TOOLTIP_SURFACE =\n  \"w-max max-w-[min(20rem,calc(100vw-1rem))] rounded-md border border-[var(--border)] bg-[var(--bg-surface)] px-2 py-1 text-xs font-medium text-[var(--text-primary)] shadow-lg\";\n\nconst sidePositionClass: Record<TooltipSide, string> = {\n  top: \"bottom-full left-1/2 -translate-x-1/2 mb-1\",\n  bottom: \"top-full left-1/2 -translate-x-1/2 mt-1\",\n  left: \"right-full top-1/2 -translate-y-1/2 mr-1\",\n  right: \"left-full top-1/2 -translate-y-1/2 ml-1\",\n};\n\n/**\n * `extends ComponentPropsWithoutRef<\"span\">` because the wrapper this renders IS a span,\n * and a tooltip is the component a caller most often needs to reach past: it sits\n * between the layout and the control, so a `data-tour` anchor, a test id or an\n * `aria-label` aimed at the trigger used to be swallowed by it.\n *\n * ⚠️ On the empty-label branch there is no wrapper at all, and therefore nothing for\n * those attributes to land on — see the note in the body.\n */\nexport interface TooltipProps extends ComponentPropsWithoutRef<\"span\"> {\n  label: ReactNode;\n  side?: TooltipSide;\n  className?: string;\n  portal?: boolean;\n  /** Tag the bubble `data-private`, for a label that repeats the user's own data. */\n  redact?: boolean;\n  children: ReactNode;\n}\n\n/** What each variant below takes: the resolved `side`, and every span attribute the\n *  caller handed {@link Tooltip}, forwarded to that variant's own wrapper. */\ntype TooltipVariantProps = Omit<TooltipProps, \"side\" | \"portal\"> & { side: TooltipSide };\n\n/**\n * Hover/focus label for a control.\n *\n * Two implementations, and the choice matters more than it looks. The default is\n * CSS-only: the bubble is always mounted next to the trigger and fades in on\n * `:hover`, which costs no state and works in a plain render test. The `portal`\n * variant mounts the bubble in `document.body` only while hovered, positioned by\n * measurement.\n *\n * ⚠️ **A bubble that repeats a value has to be redactable.** The consuming app blurs\n * `[data-private]` under a `demo-mode` class on `<html>` — and the portalled bubble is\n * mounted on `document.body`, which is INSIDE that class, so the rule reaches it as\n * long as the bubble is tagged. It is not tagged by default, because most labels are\n * UI strings; pass `redact` on the ones that repeat the user's own data (a truncated\n * payee, an account name, a memo). Getting this wrong is silent: the trigger blurs,\n * the bubble spells the value out on hover.\n *\n * ⚠️ **An empty label renders nothing at all.** `title={payee ?? \"\"}` is an ordinary\n * shape at a call site that reveals truncated text, and the native attribute answers\n * it by showing no tooltip. A component that faithfully rendered an empty bubble\n * would be a worse `title`, so the emptiness check is here rather than at every call\n * site that could forget it.\n *\n * ⚠️ **The bubble describes its trigger, which means cloning it.** `role=\"tooltip\"` is\n * a name for a box, not a relationship — so for as long as nothing referenced the\n * bubble, the label reached the pointer and nobody else. That is worst on the call\n * sites that need it most: the kit's icon-only buttons, where the tooltip IS the\n * label. `aria-describedby` has to sit on the focusable element, which is the\n * caller's child and not this component's wrapper, so the child is CLONED to carry\n * it. A description the caller already set is appended to, never replaced — a field's\n * error text and its hint bubble both describe it. Children that cannot take props (a\n * fragment, a bare string, several elements) are left exactly as they were.\n *\n * ⚠️ **Escape dismisses it (WCAG 1.4.13).** Anything that appears on hover or focus has\n * to be dismissible without moving the pointer, and a bubble is opaque: it lands over\n * the row, field or figure you were reading, and the only way out of it used to be to\n * point somewhere else — which is precisely what you cannot do when what you need to\n * read is underneath it. The listener is the document's rather than the wrapper's\n * because the pointer opens this with the keyboard focus somewhere else entirely, and\n * it is subscribed only while a bubble is actually up: the CSS variant is always\n * mounted, and a table of forty tooltips must not mean forty keydown listeners.\n *\n * ⚠️ **Inside a scroll container, use `portal`.** An always-mounted bubble is\n * absolutely positioned, but an absolutely positioned descendant still counts\n * towards its scroll-container ancestor's scrollable overflow — so an invisible\n * bubble on a control near the right edge makes the container scroll sideways\n * with nothing to reveal. That is what Keksdose feedback dev#488 reported on the\n * admin roster: 66px of horizontal scroll on a table that fit, 44px of it owed to\n * tooltips nobody could see. The portalled bubble is `position: fixed` and absent\n * until hovered, so it adds no width — and, being outside the container, it also\n * cannot be clipped by it.\n */\nexport function Tooltip({\n  label,\n  side = \"top\",\n  className,\n  portal = false,\n  redact = false,\n  children,\n  ...rest\n}: TooltipProps) {\n  // No label, no bubble — and no wrapper either, so a conditional tooltip costs the\n  // layout nothing on the branch where it does not apply. `...rest` goes with the\n  // wrapper on this branch, which is the documented limit of the pass-through: there is\n  // no element left to put an attribute on.\n  if (isEmptyLabel(label)) return <>{children}</>;\n  if (portal) {\n    return (\n      <PortalTooltip\n        label={label}\n        side={side}\n        className={className}\n        redact={redact}\n        {...rest}\n      >\n        {children}\n      </PortalTooltip>\n    );\n  }\n  // Both variants are separate components so that `Tooltip` itself can keep calling NO\n  // hooks: the empty-label branch above returns before either of them, and a hook after\n  // a conditional return is a hooks-order bug rather than a style violation.\n  return (\n    <CssTooltip label={label} side={side} className={className} redact={redact} {...rest}>\n      {children}\n    </CssTooltip>\n  );\n}\n\n/** The always-mounted variant: the bubble sits next to the trigger and CSS fades it in.\n *\n *  It holds the little state it does for the two things CSS cannot express — which\n *  element to point `aria-describedby` at, and Escape — and not for the fade, which is\n *  still `group-hover`/`group-focus-within` and still costs a render nothing. */\nfunction CssTooltip({\n  label,\n  side,\n  className,\n  redact,\n  children,\n  ...rest\n}: TooltipVariantProps) {\n  const id = useId();\n  const [hovered, setHovered] = useState(false);\n  const [focused, setFocused] = useState(false);\n  const [dismissed, setDismissed] = useState(false);\n  useEscapeKey(() => setDismissed(true), (hovered || focused) && !dismissed);\n  return (\n    <span\n      // `...rest` first: the four handlers below are what decides whether a bubble is\n      // up, and a caller passing an `onFocus` of its own must not replace them.\n      {...rest}\n      className={cn(\"relative inline-flex group/tooltip\", className)}\n      // These four track WHETHER A BUBBLE IS UP. They activate nothing — the only thing\n      // here that can be activated is the caller's child, which keeps every handler it\n      // arrived with — so this wrapper needs no role and no key handling of its own.\n      // `jsx-a11y/no-static-element-interactions` warns about it all the same, as it\n      // already does about the portal variant's identical trigger below; both are left\n      // visible rather than silenced, because a rule this package ratchets should be\n      // argued with in the backlog and not in a disable comment.\n      //\n      // Re-armed by the next hover or focus rather than by an effect watching those\n      // flags: coming back to a trigger is a fresh request for its label, and an effect\n      // would also re-show the bubble under a pointer that never left.\n      onMouseEnter={() => {\n        setHovered(true);\n        setDismissed(false);\n      }}\n      onMouseLeave={() => setHovered(false)}\n      onFocus={() => {\n        setFocused(true);\n        setDismissed(false);\n      }}\n      onBlur={() => setFocused(false)}\n    >\n      {describedBy(children, dismissed ? undefined : id)}\n      <span\n        id={id}\n        role=\"tooltip\"\n        // The `hidden` ATTRIBUTE, not an opacity class: dismissing has to take the\n        // bubble out of the accessibility tree as well as off the screen, or a screen\n        // reader still reads out the description of a bubble the user just closed.\n        hidden={dismissed || undefined}\n        data-private={redact ? \"\" : undefined}\n        className={cn(\n          TOOLTIP_SURFACE,\n          \"pointer-events-none absolute z-50 opacity-0 group-hover/tooltip:opacity-100 group-focus-within/tooltip:opacity-100\",\n          sidePositionClass[side],\n        )}\n      >\n        {label}\n      </span>\n    </span>\n  );\n}\n\n/** Hand `children` the bubble's id as an `aria-describedby`, if it is an element that\n *  can hold one. `id` is undefined while there is no bubble to point at — a dangling\n *  reference describes the trigger as nothing at all, which is worse than silence. */\nfunction describedBy(children: ReactNode, id: string | undefined): ReactNode {\n  if (id === undefined || !isValidElement(children)) return children;\n  const child = children as ReactElement<{ \"aria-describedby\"?: string }>;\n  // Fragments, Suspense and friends are symbol-typed and take no DOM props; cloning one\n  // with an aria attribute warns in development and drops it in production.\n  if (typeof child.type === \"symbol\") return children;\n  const own = child.props[\"aria-describedby\"];\n  return cloneElement(child, { \"aria-describedby\": own ? `${own} ${id}` : id });\n}\n\n/** \"Would this bubble be blank.\" Only the values a call site actually produces when\n *  it has nothing to say — `\"\"`, `null`, `undefined`, `false` from a `&&` guard. A\n *  numeric `0` is a real label and stays one. */\nfunction isEmptyLabel(label: ReactNode): boolean {\n  return (\n    label == null ||\n    label === false ||\n    (typeof label === \"string\" && label.trim() === \"\")\n  );\n}\n\nconst TOOLTIP_GAP = 4;\n\n/** How close to the viewport edge a bubble may sit. Not zero: a label flush\n *  against the glass reads as clipped even when every character is on screen. */\nconst TOOLTIP_MARGIN = 4;\n\nconst portalTransformBySide: Record<TooltipSide, string> = {\n  right: \"translate(0, -50%)\",\n  left: \"translate(-100%, -50%)\",\n  top: \"translate(-50%, -100%)\",\n  bottom: \"translate(-50%, 0)\",\n};\n\n/** Anchor point (viewport px) for the tooltip on the given side of `r`. Paired\n *  with {@link portalTransformBySide}, which shifts the box onto that point. */\nfunction tooltipAnchor(\n  r: AnchorRect,\n  side: TooltipSide,\n): { left: number; top: number } {\n  switch (side) {\n    case \"right\":\n      return { left: r.right + TOOLTIP_GAP, top: r.top + r.height / 2 };\n    case \"left\":\n      return { left: r.left - TOOLTIP_GAP, top: r.top + r.height / 2 };\n    case \"top\":\n      return { left: r.left + r.width / 2, top: r.top - TOOLTIP_GAP };\n    case \"bottom\":\n      return { left: r.left + r.width / 2, top: r.bottom + TOOLTIP_GAP };\n  }\n}\n\nexport interface TooltipSize {\n  width: number;\n  height: number;\n}\n\nexport interface TooltipViewport {\n  width: number;\n  height: number;\n}\n\nexport interface TooltipPlacement {\n  left: number;\n  top: number;\n  /** Which side it ended up on, which need not be the one that was asked for. */\n  side: TooltipSide;\n}\n\nconst opposite: Record<TooltipSide, TooltipSide> = {\n  left: \"right\",\n  right: \"left\",\n  top: \"bottom\",\n  bottom: \"top\",\n};\n\n/** Whether the bubble clears the viewport edge on `side` of the trigger. */\nfunction roomOn(\n  r: AnchorRect,\n  side: TooltipSide,\n  size: TooltipSize,\n  viewport: TooltipViewport,\n): boolean {\n  switch (side) {\n    case \"left\":\n      return r.left - TOOLTIP_GAP - size.width >= TOOLTIP_MARGIN;\n    case \"right\":\n      return r.right + TOOLTIP_GAP + size.width <= viewport.width - TOOLTIP_MARGIN;\n    case \"top\":\n      return r.top - TOOLTIP_GAP - size.height >= TOOLTIP_MARGIN;\n    case \"bottom\":\n      return r.bottom + TOOLTIP_GAP + size.height <= viewport.height - TOOLTIP_MARGIN;\n  }\n}\n\nfunction sameRoom(\n  a: { size: TooltipSize; viewport: TooltipViewport },\n  b: { size: TooltipSize; viewport: TooltipViewport },\n): boolean {\n  return (\n    a.size.width === b.size.width &&\n    a.size.height === b.size.height &&\n    a.viewport.width === b.viewport.width &&\n    a.viewport.height === b.viewport.height\n  );\n}\n\nfunction clamp(value: number, low: number, high: number): number {\n  // `high` first, so a bubble taller or wider than the viewport is pinned to the\n  // top-left corner rather than to the bottom-right one — the start of a label\n  // is the half worth keeping.\n  return Math.max(low, Math.min(value, high));\n}\n\n/**\n * Where the bubble actually goes, given how big it turned out to be.\n *\n * Two rules, and they are separate because they fix separate failures.\n *\n * **Turn round when the preferred side has no room.** `side` says which side of\n * the trigger the label reads best on, and on a form near the left edge of the\n * window that side is off the screen — the capped bubble can only wrap, not\n * move, so what the reader gets is a sentence with its first half outside the\n * glass. Flipped only when the *other* side is genuinely better: a trigger in a\n * viewport too narrow for the bubble either way keeps the side it asked for, and\n * the clamp below does what it can.\n *\n * **Then clamp both axes.** The cross axis is the one that needs it — a `top`\n * bubble is centred on the trigger, so a trigger near the left edge pushes half\n * the label off even though the side it is on is right — and clamping the main\n * axis too costs nothing and covers the flip having nowhere to land.\n *\n * Pure, and measured in viewport pixels throughout, so it can be tested without\n * a layout: the caller supplies the trigger's rect, the bubble's own size and\n * the window.\n */\nexport function placeTooltip(\n  r: AnchorRect,\n  side: TooltipSide,\n  size: TooltipSize,\n  viewport: TooltipViewport,\n): TooltipPlacement {\n  const chosen =\n    roomOn(r, side, size, viewport) || !roomOn(r, opposite[side], size, viewport)\n      ? side\n      : opposite[side];\n  const point = tooltipAnchor(r, chosen);\n  const box =\n    chosen === \"left\"\n      ? { left: point.left - size.width, top: point.top - size.height / 2 }\n      : chosen === \"right\"\n        ? { left: point.left, top: point.top - size.height / 2 }\n        : chosen === \"top\"\n          ? { left: point.left - size.width / 2, top: point.top - size.height }\n          : { left: point.left - size.width / 2, top: point.top };\n  return {\n    left: clamp(box.left, TOOLTIP_MARGIN, viewport.width - size.width - TOOLTIP_MARGIN),\n    top: clamp(box.top, TOOLTIP_MARGIN, viewport.height - size.height - TOOLTIP_MARGIN),\n    side: chosen,\n  };\n}\n\nfunction PortalTooltip({\n  label,\n  side,\n  className,\n  redact,\n  children,\n  ...rest\n}: TooltipVariantProps) {\n  const triggerRef = useRef<HTMLSpanElement | null>(null);\n  const bubbleRef = useRef<HTMLSpanElement | null>(null);\n  const [visible, setVisible] = useState(false);\n  const id = useId();\n  // Escape closes it outright, since this variant's bubble only exists while it is\n  // shown. The next mouseenter/focus brings it back, which is the behaviour WCAG\n  // 1.4.13 asks for: dismissible now, still available when you ask again.\n  useEscapeKey(() => setVisible(false), visible);\n  // The measure + scroll/resize-tracking lifecycle is owned by useAnchoredRect;\n  // here we only map the rect to a side-specific anchor point.\n  const rect = useAnchoredRect(triggerRef, visible);\n  // The bubble's own size and the window it has to fit in — neither of which is\n  // knowable in render: the width is whatever the label wrapped to inside the\n  // cap, and reading `window` while rendering is not a pure thing to do. Both\n  // are taken in a LAYOUT effect, so the correction lands before the browser\n  // paints and there is no frame in which the label sits off the screen.\n  const [room, setRoom] = useState<{ size: TooltipSize; viewport: TooltipViewport } | null>(null);\n  useLayoutEffect(() => {\n    const measured = visible ? bubbleRef.current?.getBoundingClientRect() : undefined;\n    // eslint-disable-next-line react-hooks/set-state-in-effect -- a measurement is the one thing a layout effect is for\n    setRoom((previous) => {\n      if (!measured) return null;\n      const next = {\n        size: { width: measured.width, height: measured.height },\n        viewport: { width: window.innerWidth, height: window.innerHeight },\n      };\n      // Only publish what actually CHANGED: every re-measure allocates a fresh\n      // object, and a new object on every scroll event would re-render the\n      // bubble forever.\n      return previous && sameRoom(previous, next) ? previous : next;\n    });\n  }, [visible, rect, label]);\n\n  const point = rect ? tooltipAnchor(rect, side) : null;\n  // Unmeasured on the very first pass, where the anchor point plus the side's\n  // own transform is exactly what this always did. One layout effect later the\n  // size is known and the placement is decided properly.\n  const placed = rect && room ? placeTooltip(rect, side, room.size, room.viewport) : null;\n\n  return (\n    <>\n      <span\n        // As in `CssTooltip`: the caller's attributes first, the four handlers that run\n        // this component after them. The BUBBLE is deliberately not given them — it is\n        // portalled to `<body>`, and an id or a tour anchor duplicated onto a node that\n        // only exists while hovered would match twice or match nothing.\n        {...rest}\n        ref={triggerRef}\n        className={cn(\"relative inline-flex\", className)}\n        onMouseEnter={() => setVisible(true)}\n        onMouseLeave={() => setVisible(false)}\n        onFocus={() => setVisible(true)}\n        onBlur={() => setVisible(false)}\n      >\n        {describedBy(children, visible ? id : undefined)}\n      </span>\n      {visible &&\n        point &&\n        typeof document !== \"undefined\" &&\n        createPortal(\n          <span\n            ref={bubbleRef}\n            id={id}\n            role=\"tooltip\"\n            data-private={redact ? \"\" : undefined}\n            style={\n              placed\n                ? { position: \"fixed\", left: placed.left, top: placed.top }\n                : {\n                    position: \"fixed\",\n                    left: point.left,\n                    top: point.top,\n                    transform: portalTransformBySide[side],\n                  }\n            }\n            className={cn(TOOLTIP_SURFACE, \"pointer-events-none z-50\")}\n          >\n            {label}\n          </span>,\n          document.body,\n        )}\n    </>\n  );\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../src/components/tooltip.tsx"],"sourcesContent":["import {\n  cloneElement,\n  isValidElement,\n  useId,\n  useLayoutEffect,\n  useRef,\n  useState,\n  type ComponentPropsWithoutRef,\n  type ReactElement,\n  type ReactNode,\n} from \"react\";\nimport { createPortal } from \"react-dom\";\nimport { cn } from \"../lib/cn\";\nimport { useEscapeKey } from \"../hooks/use-dismiss\";\nimport { useAnchoredRect, type AnchorRect } from \"../hooks/use-anchored-rect\";\nimport { dirOf, type Direction } from \"../lib/direction\";\n\n/** Where the bubble sits. `start` / `end` follow the reading direction — `end` is the\n *  right in LTR and the left in RTL — and are what a layout that mirrors should ask\n *  for. `left` / `right` stay physical, for a bubble tied to something that does not\n *  mirror (a chart axis, a map). */\nexport type TooltipSide = \"top\" | \"bottom\" | \"left\" | \"right\" | \"start\" | \"end\";\n\n/** The placement the maths works in: a logical side resolved against the trigger. */\ntype PhysicalSide = \"top\" | \"bottom\" | \"left\" | \"right\";\n\nfunction physicalSide(side: TooltipSide, dir: Direction): PhysicalSide {\n  if (side === \"start\") return dir === \"rtl\" ? \"right\" : \"left\";\n  if (side === \"end\") return dir === \"rtl\" ? \"left\" : \"right\";\n  return side;\n}\n\n/** The floating bubble itself. Uses the shared surface/border/text tokens so it\n *  reads as part of the app's chrome (like the top bar and cards) rather than the\n *  cold slate pill it used to be.\n *\n *  `w-max` keeps a short label on one line — the old `whitespace-nowrap` did that\n *  too, but it also let a sentence-length label grow without bound, and a bubble\n *  wider than the space beside its trigger gets clipped by whatever overflow\n *  container it sits in. So cap it and let long text wrap instead. The cap tracks\n *  the viewport as well, for narrow screens where 20rem is already most of it.\n *  `side` is a preference rather than an instruction for the PORTALLED variant,\n *  which measures the bubble and turns it round when it would not fit\n *  (Steering Design feedback #126). The CSS-only one never learns its own size,\n *  so there `side` is still the whole of the placement. */\nconst TOOLTIP_SURFACE =\n  \"w-max max-w-[min(20rem,calc(100vw-1rem))] rounded-md border border-[var(--border)] bg-[var(--bg-surface)] px-2 py-1 text-xs font-medium text-[var(--text-primary)] shadow-lg\";\n\nconst sidePositionClass: Record<TooltipSide, string> = {\n  top: \"bottom-full left-1/2 -translate-x-1/2 mb-1\",\n  bottom: \"top-full left-1/2 -translate-x-1/2 mt-1\",\n  left: \"right-full top-1/2 -translate-y-1/2 mr-1\",\n  right: \"left-full top-1/2 -translate-y-1/2 ml-1\",\n  // Logical insets, so CSS resolves the side from the inherited direction with no\n  // JavaScript: `end-full` pins the bubble's END edge to the trigger's start.\n  start: \"end-full top-1/2 -translate-y-1/2 me-1\",\n  end: \"start-full top-1/2 -translate-y-1/2 ms-1\",\n};\n\n/**\n * `extends ComponentPropsWithoutRef<\"span\">` because the wrapper this renders IS a span,\n * and a tooltip is the component a caller most often needs to reach past: it sits\n * between the layout and the control, so a `data-tour` anchor, a test id or an\n * `aria-label` aimed at the trigger used to be swallowed by it.\n *\n * ⚠️ On the empty-label branch there is no wrapper at all, and therefore nothing for\n * those attributes to land on — see the note in the body.\n */\nexport interface TooltipProps extends ComponentPropsWithoutRef<\"span\"> {\n  label: ReactNode;\n  side?: TooltipSide;\n  className?: string;\n  portal?: boolean;\n  /** Tag the bubble `data-private`, for a label that repeats the user's own data. */\n  redact?: boolean;\n  children: ReactNode;\n}\n\n/** What each variant below takes: the resolved `side`, and every span attribute the\n *  caller handed {@link Tooltip}, forwarded to that variant's own wrapper. */\ntype TooltipVariantProps = Omit<TooltipProps, \"side\" | \"portal\"> & { side: TooltipSide };\n\n/**\n * Hover/focus label for a control.\n *\n * Two implementations, and the choice matters more than it looks. The default is\n * CSS-only: the bubble is always mounted next to the trigger and fades in on\n * `:hover`, which costs no state and works in a plain render test. The `portal`\n * variant mounts the bubble in `document.body` only while hovered, positioned by\n * measurement.\n *\n * ⚠️ **A bubble that repeats a value has to be redactable.** The consuming app blurs\n * `[data-private]` under a `demo-mode` class on `<html>` — and the portalled bubble is\n * mounted on `document.body`, which is INSIDE that class, so the rule reaches it as\n * long as the bubble is tagged. It is not tagged by default, because most labels are\n * UI strings; pass `redact` on the ones that repeat the user's own data (a truncated\n * payee, an account name, a memo). Getting this wrong is silent: the trigger blurs,\n * the bubble spells the value out on hover.\n *\n * ⚠️ **An empty label renders nothing at all.** `title={payee ?? \"\"}` is an ordinary\n * shape at a call site that reveals truncated text, and the native attribute answers\n * it by showing no tooltip. A component that faithfully rendered an empty bubble\n * would be a worse `title`, so the emptiness check is here rather than at every call\n * site that could forget it.\n *\n * ⚠️ **The bubble describes its trigger, which means cloning it.** `role=\"tooltip\"` is\n * a name for a box, not a relationship — so for as long as nothing referenced the\n * bubble, the label reached the pointer and nobody else. That is worst on the call\n * sites that need it most: the kit's icon-only buttons, where the tooltip IS the\n * label. `aria-describedby` has to sit on the focusable element, which is the\n * caller's child and not this component's wrapper, so the child is CLONED to carry\n * it. A description the caller already set is appended to, never replaced — a field's\n * error text and its hint bubble both describe it. Children that cannot take props (a\n * fragment, a bare string, several elements) are left exactly as they were.\n *\n * ⚠️ **Escape dismisses it (WCAG 1.4.13).** Anything that appears on hover or focus has\n * to be dismissible without moving the pointer, and a bubble is opaque: it lands over\n * the row, field or figure you were reading, and the only way out of it used to be to\n * point somewhere else — which is precisely what you cannot do when what you need to\n * read is underneath it. The listener is the document's rather than the wrapper's\n * because the pointer opens this with the keyboard focus somewhere else entirely, and\n * it is subscribed only while a bubble is actually up: the CSS variant is always\n * mounted, and a table of forty tooltips must not mean forty keydown listeners.\n *\n * ⚠️ **Inside a scroll container, use `portal`.** An always-mounted bubble is\n * absolutely positioned, but an absolutely positioned descendant still counts\n * towards its scroll-container ancestor's scrollable overflow — so an invisible\n * bubble on a control near the right edge makes the container scroll sideways\n * with nothing to reveal. That is what Keksdose feedback dev#488 reported on the\n * admin roster: 66px of horizontal scroll on a table that fit, 44px of it owed to\n * tooltips nobody could see. The portalled bubble is `position: fixed` and absent\n * until hovered, so it adds no width — and, being outside the container, it also\n * cannot be clipped by it.\n */\nexport function Tooltip({\n  label,\n  side = \"top\",\n  className,\n  portal = false,\n  redact = false,\n  children,\n  ...rest\n}: TooltipProps) {\n  // No label, no bubble — and no wrapper either, so a conditional tooltip costs the\n  // layout nothing on the branch where it does not apply. `...rest` goes with the\n  // wrapper on this branch, which is the documented limit of the pass-through: there is\n  // no element left to put an attribute on.\n  if (isEmptyLabel(label)) return <>{children}</>;\n  if (portal) {\n    return (\n      <PortalTooltip\n        label={label}\n        side={side}\n        className={className}\n        redact={redact}\n        {...rest}\n      >\n        {children}\n      </PortalTooltip>\n    );\n  }\n  // Both variants are separate components so that `Tooltip` itself can keep calling NO\n  // hooks: the empty-label branch above returns before either of them, and a hook after\n  // a conditional return is a hooks-order bug rather than a style violation.\n  return (\n    <CssTooltip label={label} side={side} className={className} redact={redact} {...rest}>\n      {children}\n    </CssTooltip>\n  );\n}\n\n/** The always-mounted variant: the bubble sits next to the trigger and CSS fades it in.\n *\n *  It holds the little state it does for the two things CSS cannot express — which\n *  element to point `aria-describedby` at, and Escape — and not for the fade, which is\n *  still `group-hover`/`group-focus-within` and still costs a render nothing. */\nfunction CssTooltip({\n  label,\n  side,\n  className,\n  redact,\n  children,\n  ...rest\n}: TooltipVariantProps) {\n  const id = useId();\n  const [hovered, setHovered] = useState(false);\n  const [focused, setFocused] = useState(false);\n  const [dismissed, setDismissed] = useState(false);\n  useEscapeKey(() => setDismissed(true), (hovered || focused) && !dismissed);\n  return (\n    <span\n      // `...rest` first: the four handlers below are what decides whether a bubble is\n      // up, and a caller passing an `onFocus` of its own must not replace them.\n      {...rest}\n      className={cn(\"relative inline-flex group/tooltip\", className)}\n      // These four track WHETHER A BUBBLE IS UP. They activate nothing — the only thing\n      // here that can be activated is the caller's child, which keeps every handler it\n      // arrived with — so this wrapper needs no role and no key handling of its own.\n      // `jsx-a11y/no-static-element-interactions` warns about it all the same, as it\n      // already does about the portal variant's identical trigger below; both are left\n      // visible rather than silenced, because a rule this package ratchets should be\n      // argued with in the backlog and not in a disable comment.\n      //\n      // Re-armed by the next hover or focus rather than by an effect watching those\n      // flags: coming back to a trigger is a fresh request for its label, and an effect\n      // would also re-show the bubble under a pointer that never left.\n      onMouseEnter={() => {\n        setHovered(true);\n        setDismissed(false);\n      }}\n      onMouseLeave={() => setHovered(false)}\n      onFocus={() => {\n        setFocused(true);\n        setDismissed(false);\n      }}\n      onBlur={() => setFocused(false)}\n    >\n      {describedBy(children, dismissed ? undefined : id)}\n      <span\n        id={id}\n        role=\"tooltip\"\n        // The `hidden` ATTRIBUTE, not an opacity class: dismissing has to take the\n        // bubble out of the accessibility tree as well as off the screen, or a screen\n        // reader still reads out the description of a bubble the user just closed.\n        hidden={dismissed || undefined}\n        data-private={redact ? \"\" : undefined}\n        className={cn(\n          TOOLTIP_SURFACE,\n          \"pointer-events-none absolute z-50 opacity-0 group-hover/tooltip:opacity-100 group-focus-within/tooltip:opacity-100\",\n          sidePositionClass[side],\n        )}\n      >\n        {label}\n      </span>\n    </span>\n  );\n}\n\n/** Hand `children` the bubble's id as an `aria-describedby`, if it is an element that\n *  can hold one. `id` is undefined while there is no bubble to point at — a dangling\n *  reference describes the trigger as nothing at all, which is worse than silence. */\nfunction describedBy(children: ReactNode, id: string | undefined): ReactNode {\n  if (id === undefined || !isValidElement(children)) return children;\n  const child = children as ReactElement<{ \"aria-describedby\"?: string }>;\n  // Fragments, Suspense and friends are symbol-typed and take no DOM props; cloning one\n  // with an aria attribute warns in development and drops it in production.\n  if (typeof child.type === \"symbol\") return children;\n  const own = child.props[\"aria-describedby\"];\n  return cloneElement(child, { \"aria-describedby\": own ? `${own} ${id}` : id });\n}\n\n/** \"Would this bubble be blank.\" Only the values a call site actually produces when\n *  it has nothing to say — `\"\"`, `null`, `undefined`, `false` from a `&&` guard. A\n *  numeric `0` is a real label and stays one. */\nfunction isEmptyLabel(label: ReactNode): boolean {\n  return (\n    label == null ||\n    label === false ||\n    (typeof label === \"string\" && label.trim() === \"\")\n  );\n}\n\nconst TOOLTIP_GAP = 4;\n\n/** How close to the viewport edge a bubble may sit. Not zero: a label flush\n *  against the glass reads as clipped even when every character is on screen. */\nconst TOOLTIP_MARGIN = 4;\n\nconst portalTransformBySide: Record<PhysicalSide, string> = {\n  right: \"translate(0, -50%)\",\n  left: \"translate(-100%, -50%)\",\n  top: \"translate(-50%, -100%)\",\n  bottom: \"translate(-50%, 0)\",\n};\n\n/** Anchor point (viewport px) for the tooltip on the given side of `r`. Paired\n *  with {@link portalTransformBySide}, which shifts the box onto that point. */\nfunction tooltipAnchor(\n  r: AnchorRect,\n  side: PhysicalSide,\n): { left: number; top: number } {\n  switch (side) {\n    case \"right\":\n      return { left: r.right + TOOLTIP_GAP, top: r.top + r.height / 2 };\n    case \"left\":\n      return { left: r.left - TOOLTIP_GAP, top: r.top + r.height / 2 };\n    case \"top\":\n      return { left: r.left + r.width / 2, top: r.top - TOOLTIP_GAP };\n    case \"bottom\":\n      return { left: r.left + r.width / 2, top: r.bottom + TOOLTIP_GAP };\n  }\n}\n\nexport interface TooltipSize {\n  width: number;\n  height: number;\n}\n\nexport interface TooltipViewport {\n  width: number;\n  height: number;\n}\n\nexport interface TooltipPlacement {\n  left: number;\n  top: number;\n  /** Which side it ended up on, which need not be the one that was asked for. */\n  side: PhysicalSide;\n}\n\nconst opposite: Record<PhysicalSide, PhysicalSide> = {\n  left: \"right\",\n  right: \"left\",\n  top: \"bottom\",\n  bottom: \"top\",\n};\n\n/** Whether the bubble clears the viewport edge on `side` of the trigger. */\nfunction roomOn(\n  r: AnchorRect,\n  side: PhysicalSide,\n  size: TooltipSize,\n  viewport: TooltipViewport,\n): boolean {\n  switch (side) {\n    case \"left\":\n      return r.left - TOOLTIP_GAP - size.width >= TOOLTIP_MARGIN;\n    case \"right\":\n      return r.right + TOOLTIP_GAP + size.width <= viewport.width - TOOLTIP_MARGIN;\n    case \"top\":\n      return r.top - TOOLTIP_GAP - size.height >= TOOLTIP_MARGIN;\n    case \"bottom\":\n      return r.bottom + TOOLTIP_GAP + size.height <= viewport.height - TOOLTIP_MARGIN;\n  }\n}\n\nfunction sameRoom(\n  a: { size: TooltipSize; viewport: TooltipViewport },\n  b: { size: TooltipSize; viewport: TooltipViewport },\n): boolean {\n  return (\n    a.size.width === b.size.width &&\n    a.size.height === b.size.height &&\n    a.viewport.width === b.viewport.width &&\n    a.viewport.height === b.viewport.height\n  );\n}\n\nfunction clamp(value: number, low: number, high: number): number {\n  // `high` first, so a bubble taller or wider than the viewport is pinned to the\n  // top-left corner rather than to the bottom-right one — the start of a label\n  // is the half worth keeping.\n  return Math.max(low, Math.min(value, high));\n}\n\n/**\n * Where the bubble actually goes, given how big it turned out to be.\n *\n * Two rules, and they are separate because they fix separate failures.\n *\n * **Turn round when the preferred side has no room.** `side` says which side of\n * the trigger the label reads best on, and on a form near the left edge of the\n * window that side is off the screen — the capped bubble can only wrap, not\n * move, so what the reader gets is a sentence with its first half outside the\n * glass. Flipped only when the *other* side is genuinely better: a trigger in a\n * viewport too narrow for the bubble either way keeps the side it asked for, and\n * the clamp below does what it can.\n *\n * **Then clamp both axes.** The cross axis is the one that needs it — a `top`\n * bubble is centred on the trigger, so a trigger near the left edge pushes half\n * the label off even though the side it is on is right — and clamping the main\n * axis too costs nothing and covers the flip having nowhere to land.\n *\n * Pure, and measured in viewport pixels throughout, so it can be tested without\n * a layout: the caller supplies the trigger's rect, the bubble's own size and\n * the window.\n */\nexport function placeTooltip(\n  r: AnchorRect,\n  side: PhysicalSide,\n  size: TooltipSize,\n  viewport: TooltipViewport,\n): TooltipPlacement {\n  const chosen =\n    roomOn(r, side, size, viewport) || !roomOn(r, opposite[side], size, viewport)\n      ? side\n      : opposite[side];\n  const point = tooltipAnchor(r, chosen);\n  const box =\n    chosen === \"left\"\n      ? { left: point.left - size.width, top: point.top - size.height / 2 }\n      : chosen === \"right\"\n        ? { left: point.left, top: point.top - size.height / 2 }\n        : chosen === \"top\"\n          ? { left: point.left - size.width / 2, top: point.top - size.height }\n          : { left: point.left - size.width / 2, top: point.top };\n  return {\n    left: clamp(box.left, TOOLTIP_MARGIN, viewport.width - size.width - TOOLTIP_MARGIN),\n    top: clamp(box.top, TOOLTIP_MARGIN, viewport.height - size.height - TOOLTIP_MARGIN),\n    side: chosen,\n  };\n}\n\nfunction PortalTooltip({\n  label,\n  side,\n  className,\n  redact,\n  children,\n  ...rest\n}: TooltipVariantProps) {\n  const triggerRef = useRef<HTMLSpanElement | null>(null);\n  const bubbleRef = useRef<HTMLSpanElement | null>(null);\n  const [visible, setVisible] = useState(false);\n  // The trigger's reading direction, read when the bubble is asked for (an event, not a\n  // render): it resolves `start` / `end`, and the portalled bubble — which has left the\n  // subtree it would have inherited `dir` from — carries it too.\n  const [dir, setDir] = useState<Direction>(\"ltr\");\n  const show = (el: Element) => {\n    setDir(dirOf(el));\n    setVisible(true);\n  };\n  const id = useId();\n  // Escape closes it outright, since this variant's bubble only exists while it is\n  // shown. The next mouseenter/focus brings it back, which is the behaviour WCAG\n  // 1.4.13 asks for: dismissible now, still available when you ask again.\n  useEscapeKey(() => setVisible(false), visible);\n  // The measure + scroll/resize-tracking lifecycle is owned by useAnchoredRect;\n  // here we only map the rect to a side-specific anchor point.\n  const rect = useAnchoredRect(triggerRef, visible);\n  // The bubble's own size and the window it has to fit in — neither of which is\n  // knowable in render: the width is whatever the label wrapped to inside the\n  // cap, and reading `window` while rendering is not a pure thing to do. Both\n  // are taken in a LAYOUT effect, so the correction lands before the browser\n  // paints and there is no frame in which the label sits off the screen.\n  const [room, setRoom] = useState<{ size: TooltipSize; viewport: TooltipViewport } | null>(null);\n  useLayoutEffect(() => {\n    const measured = visible ? bubbleRef.current?.getBoundingClientRect() : undefined;\n    // eslint-disable-next-line react-hooks/set-state-in-effect -- a measurement is the one thing a layout effect is for\n    setRoom((previous) => {\n      if (!measured) return null;\n      const next = {\n        size: { width: measured.width, height: measured.height },\n        viewport: { width: window.innerWidth, height: window.innerHeight },\n      };\n      // Only publish what actually CHANGED: every re-measure allocates a fresh\n      // object, and a new object on every scroll event would re-render the\n      // bubble forever.\n      return previous && sameRoom(previous, next) ? previous : next;\n    });\n  }, [visible, rect, label]);\n\n  const physical = physicalSide(side, dir);\n  const point = rect ? tooltipAnchor(rect, physical) : null;\n  // Unmeasured on the very first pass, where the anchor point plus the side's\n  // own transform is exactly what this always did. One layout effect later the\n  // size is known and the placement is decided properly.\n  const placed = rect && room ? placeTooltip(rect, physical, room.size, room.viewport) : null;\n\n  return (\n    <>\n      <span\n        // As in `CssTooltip`: the caller's attributes first, the four handlers that run\n        // this component after them. The BUBBLE is deliberately not given them — it is\n        // portalled to `<body>`, and an id or a tour anchor duplicated onto a node that\n        // only exists while hovered would match twice or match nothing.\n        {...rest}\n        ref={triggerRef}\n        className={cn(\"relative inline-flex\", className)}\n        onMouseEnter={(e) => show(e.currentTarget)}\n        onMouseLeave={() => setVisible(false)}\n        onFocus={(e) => show(e.currentTarget)}\n        onBlur={() => setVisible(false)}\n      >\n        {describedBy(children, visible ? id : undefined)}\n      </span>\n      {visible &&\n        point &&\n        typeof document !== \"undefined\" &&\n        createPortal(\n          <span\n            ref={bubbleRef}\n            id={id}\n            role=\"tooltip\"\n            dir={dir}\n            data-private={redact ? \"\" : undefined}\n            style={\n              placed\n                ? { position: \"fixed\", left: placed.left, top: placed.top }\n                : {\n                    position: \"fixed\",\n                    left: point.left,\n                    top: point.top,\n                    transform: portalTransformBySide[physical],\n                  }\n            }\n            className={cn(TOOLTIP_SURFACE, \"pointer-events-none z-50\")}\n          >\n            {label}\n          </span>,\n          document.body,\n        )}\n    </>\n  );\n}\n"],"mappings":"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","names":[]}

package/dist/components/tree-view.d.ts

@@ -0,0 +1,129 @@
+import * as react from 'react';
+import { ReactNode, ComponentPropsWithoutRef } from 'react';
+
+/**
+ * A hierarchy you walk with the keyboard: kastlan's chart of accounts (Assets › Current
+ * assets › Bank › 1020 Operating account), and — through {@link TreeRow} alone — the
+ * row labels of its gantt, which indent and fold like a tree but sit beside a timeline
+ * and so cannot be one.
+ *
+ * Both apps had written it as nested `<div>`s with a chevron button per row: every
+ * row a Tab stop (a 300-account chart was 300 presses to get past), no way to say
+ * "level 3 of 5, collapsed" to a screen reader, and no ←/→ at all. This is the WAI-ARIA
+ * tree pattern instead:
+ *
+ *  - `role="tree"` › `treeitem` (with `aria-level`, `aria-expanded` on a parent,
+ *    `aria-selected` when selectable) › `role="group"` for its children — so the
+ *    reader announces the position and the state it needs.
+ *  - ONE Tab stop (roving tabindex). ↑/↓ walk the visible rows, → opens a closed
+ *    parent and then steps into it, ← closes an open one and then steps out to the
+ *    parent, Home/End jump to the ends, `*` opens every sibling, and typing a few
+ *    letters jumps to the next row that starts with them. ←/→ follow the reading
+ *    direction (`horizontalStep`): in an RTL tree the children hang off to the left,
+ *    and ← is what opens them.
+ *  - Enter / Space, or a click, select. The chevron alone toggles on click.
+ *
+ * `expanded` and `selected` each work controlled or uncontrolled.
+ */
+interface TreeNode<T = unknown> {
+    /** Unique across the whole tree — it is what `expanded` and `selected` hold. */
+    id: string;
+    label: ReactNode;
+    /** The text type-ahead matches. Defaults to the row's rendered text. */
+    textValue?: string;
+    /** Before the label: an account-type icon, a colour dot. */
+    icon?: ReactNode;
+    /** After the label, pushed to the end of the row: a balance, a count, an action. */
+    trailing?: ReactNode;
+    children?: readonly TreeNode<T>[];
+    /**
+     * The node has children that are not loaded yet — it gets a chevron, and opening it
+     * calls `loadChildren`. Pass the children in `items` once they arrive.
+     */
+    hasChildren?: boolean;
+    /** Focusable and announced as unavailable (`aria-disabled`), but not selectable. */
+    disabled?: boolean;
+    /** Anything of the host's own, handed back to `renderItem` and `onSelectedChange`. */
+    data?: T;
+}
+/** What {@link TreeViewProps.renderItem} is told about a row. */
+interface TreeItemState {
+    level: number;
+    expanded: boolean;
+    selected: boolean;
+    /** It has children, loaded or not — it shows a chevron. */
+    expandable: boolean;
+    loading: boolean;
+    disabled: boolean;
+}
+interface TreeRowProps extends ComponentPropsWithoutRef<"div"> {
+    /** 1 for a top-level row. Sets the indent and the number of guides. */
+    level: number;
+    /** `true`/`false` for a row that can fold; leave it `undefined` for a leaf, which
+     *  gets a chevron-sized gap instead so labels at one level still line up. */
+    expanded?: boolean;
+    /**
+     * Make the chevron a real button (with `aria-expanded`, named by the label) that
+     * calls this. For a row used ON ITS OWN — kastlan's gantt labels, where each row is
+     * a line of a timeline and not an item of a tree widget. Inside {@link TreeView} it
+     * is omitted: the tree owns the keys, and a button per row would be a Tab stop per
+     * row, which is what the tree exists to remove.
+     */
+    onToggle?: () => void;
+    /** The toggle button's name. By default it is named by the row's label (the state
+     *  is `aria-expanded`'s to say); required when `children` replaces the label. */
+    toggleLabel?: string;
+    label: ReactNode;
+    icon?: ReactNode;
+    trailing?: ReactNode;
+    /** Pixels per level. Default 16. */
+    indent?: number;
+    /** Draw a vertical hairline per ancestor level. Default `true`. */
+    guides?: boolean;
+    selected?: boolean;
+    /** A spinner in place of the chevron, while lazy children load. */
+    loading?: boolean;
+    /** Replace the label + trailing part of the row (the indent and chevron stay). */
+    children?: ReactNode;
+}
+/**
+ * One row: indent, guides, chevron, icon, label, trailing — no tree semantics of its
+ * own. {@link TreeView} is built from it, and a host that needs the look without the
+ * widget (a gantt's label column) uses it directly.
+ *
+ * Laid out with logical properties throughout (`padding-inline-start`,
+ * `inset-inline-start`), so the indent, the guides and the chevron all hang from the
+ * reading start in an RTL layout without a second code path.
+ */
+declare function TreeRow({ level, expanded, onToggle, toggleLabel, label, icon, trailing, indent, guides, selected, loading, children, className, style, ...rest }: TreeRowProps): react.JSX.Element;
+interface TreeViewProps<T = unknown> extends Omit<ComponentPropsWithoutRef<"ul">, "onSelect" | "children" | "defaultValue"> {
+    items: readonly TreeNode<T>[];
+    /** Open nodes, controlled. */
+    expanded?: readonly string[];
+    /** Open nodes on first render, uncontrolled. */
+    defaultExpanded?: readonly string[];
+    onExpandedChange?: (expanded: string[]) => void;
+    /** The selected node's id, controlled; `null` for none. */
+    selected?: string | null;
+    defaultSelected?: string | null;
+    onSelectedChange?: (id: string, node: TreeNode<T>) => void;
+    /** `"none"` makes it a navigation-only tree: no `aria-selected`, Enter toggles. */
+    selectionMode?: "single" | "none";
+    /** The whole row content after the chevron, per node. Wins over `label`/`trailing`. */
+    renderItem?: (node: TreeNode<T>, state: TreeItemState) => ReactNode;
+    /**
+     * Called when a node with `hasChildren` and no `children` is opened. While the
+     * promise is pending the row shows a spinner and is `aria-busy`; put the children
+     * into `items` before it resolves (or after — the row opens either way).
+     */
+    loadChildren?: (node: TreeNode<T>) => Promise<void> | void;
+    /** Pixels per level. Default 16. */
+    indent?: number;
+    /** Vertical hairlines per level. Default `true`. */
+    indentGuides?: boolean;
+    /** Extra classes for each row (the `TreeRow`), e.g. a denser height. */
+    rowClassName?: string;
+}
+declare function TreeView<T = unknown>({ items, expanded: expandedProp, defaultExpanded, onExpandedChange, selected: selectedProp, defaultSelected, onSelectedChange, selectionMode, renderItem, loadChildren, indent, indentGuides, rowClassName, className, onKeyDown, onClick, ...rest }: TreeViewProps<T>): react.JSX.Element;
+
+export { type TreeItemState, type TreeNode, TreeRow, type TreeRowProps, TreeView, type TreeViewProps };

package/dist/components/tree-view.js

@@ -0,0 +1,376 @@
+"use client";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { useEffect, useId, useMemo, useRef, useState } from "react";
+import { ChevronRight } from "lucide-react";
+import { cn } from "../lib/cn.js";
+import { horizontalStep } from "../lib/direction.js";
+import { Spinner } from "./ui.js";
+const DEFAULT_INDENT = 16;
+const CHEVRON = 16;
+const ROW_PAD = 4;
+function TreeRow({
+  level,
+  expanded,
+  onToggle,
+  toggleLabel,
+  label,
+  icon,
+  trailing,
+  indent = DEFAULT_INDENT,
+  guides = true,
+  selected,
+  loading,
+  children,
+  className,
+  style,
+  ...rest
+}) {
+  const labelId = useId();
+  const depth = Math.max(0, level - 1);
+  const expandable = expanded !== void 0;
+  const chevron = /* @__PURE__ */ jsx(
+    ChevronRight,
+    {
+      "aria-hidden": true,
+      className: cn(
+        "size-4 transition-transform motion-reduce:transition-none rtl:-scale-x-100",
+        expanded && "rotate-90 rtl:-rotate-90"
+      )
+    }
+  );
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      ...rest,
+      "data-tree-row": "",
+      "data-selected": selected || void 0,
+      style: { paddingInlineStart: ROW_PAD + depth * indent, ...style },
+      className: cn(
+        "relative flex min-h-8 items-center gap-1.5 rounded pe-2 text-sm",
+        selected ? "bg-[var(--bg-active)] font-medium text-[var(--text-primary)]" : "text-[var(--text-secondary)]",
+        className
+      ),
+      children: [
+        guides && Array.from({ length: depth }, (_, i) => /* @__PURE__ */ jsx(
+          "span",
+          {
+            "aria-hidden": true,
+            "data-tree-guide": "",
+            className: "pointer-events-none absolute inset-y-0 w-px bg-[var(--border)]",
+            style: { insetInlineStart: ROW_PAD + i * indent + CHEVRON / 2 }
+          },
+          i
+        )),
+        loading ? /* @__PURE__ */ jsx("span", { className: "flex size-4 shrink-0 items-center justify-center", children: /* @__PURE__ */ jsx(Spinner, { label: null, className: "size-3 border" }) }) : expandable && onToggle ? /* @__PURE__ */ jsx(
+          "button",
+          {
+            type: "button",
+            "aria-expanded": expanded,
+            "aria-label": toggleLabel,
+            "aria-labelledby": toggleLabel ? void 0 : labelId,
+            onClick: (e) => {
+              e.stopPropagation();
+              onToggle();
+            },
+            className: "flex size-4 shrink-0 items-center justify-center rounded text-[var(--text-muted)] outline-none hover:text-[var(--text-primary)] focus-visible:ring-2 focus-visible:ring-[var(--brand)]",
+            children: chevron
+          }
+        ) : expandable ? /* @__PURE__ */ jsx("span", { "data-tree-toggle": "", className: "flex size-4 shrink-0 cursor-pointer items-center justify-center text-[var(--text-muted)]", children: chevron }) : /* @__PURE__ */ jsx("span", { "aria-hidden": true, className: "size-4 shrink-0" }),
+        children ?? /* @__PURE__ */ jsxs(Fragment, { children: [
+          icon && /* @__PURE__ */ jsx("span", { className: "flex shrink-0 items-center", children: icon }),
+          /* @__PURE__ */ jsx("span", { id: labelId, "data-tree-label": "", className: "min-w-0 flex-1 truncate", children: label }),
+          trailing !== void 0 && trailing !== null && /* @__PURE__ */ jsx("span", { className: "ms-auto flex shrink-0 items-center gap-1 text-xs tabular-nums text-[var(--text-muted)]", children: trailing })
+        ] })
+      ]
+    }
+  );
+}
+const isExpandable = (n) => Boolean(n.children?.length || n.hasChildren);
+function useControllable(value, initial) {
+  const [own, setOwn] = useState(initial);
+  const controlled = value !== void 0;
+  const set = (next) => {
+    if (!controlled) setOwn(next);
+  };
+  return [controlled ? value : own, set];
+}
+const TYPEAHEAD_MS = 500;
+function TreeView({
+  items,
+  expanded: expandedProp,
+  defaultExpanded,
+  onExpandedChange,
+  selected: selectedProp,
+  defaultSelected,
+  onSelectedChange,
+  selectionMode = "single",
+  renderItem,
+  loadChildren,
+  indent = DEFAULT_INDENT,
+  indentGuides = true,
+  rowClassName,
+  className,
+  onKeyDown,
+  onClick,
+  ...rest
+}) {
+  const [expandedList, setExpandedOwn] = useControllable(
+    expandedProp,
+    defaultExpanded ?? []
+  );
+  const [selected, setSelectedOwn] = useControllable(
+    selectedProp,
+    defaultSelected ?? null
+  );
+  const expandedSet = useMemo(() => new Set(expandedList), [expandedList]);
+  const [loading, setLoading] = useState(() => /* @__PURE__ */ new Set());
+  const [focusedId, setFocusedId] = useState(null);
+  const itemRefs = useRef(/* @__PURE__ */ new Map());
+  const pendingFocus = useRef(null);
+  const typeahead = useRef({ text: "", at: 0 });
+  const baseId = useId();
+  const { byId, visible } = useMemo(() => {
+    const map = /* @__PURE__ */ new Map();
+    const rows = [];
+    const walk = (nodes, level, parentId, shown) => {
+      for (const node of nodes) {
+        const flat = { node, level, parentId };
+        map.set(node.id, flat);
+        if (shown) rows.push(flat);
+        if (node.children) walk(node.children, level + 1, node.id, shown && expandedSet.has(node.id));
+      }
+    };
+    walk(items, 1, null, true);
+    return { byId: map, visible: rows };
+  }, [items, expandedSet]);
+  const visibleIds = useMemo(() => new Set(visible.map((f) => f.node.id)), [visible]);
+  const nearestVisible = (id) => {
+    let cur = id;
+    while (cur && !visibleIds.has(cur)) cur = byId.get(cur)?.parentId ?? null;
+    return cur;
+  };
+  const tabbable = nearestVisible(focusedId) ?? nearestVisible(selected) ?? visible[0]?.node.id ?? null;
+  useEffect(() => {
+    const id = pendingFocus.current;
+    if (!id) return;
+    pendingFocus.current = null;
+    itemRefs.current.get(id)?.focus();
+  });
+  const focusRow = (id) => {
+    setFocusedId(id);
+    pendingFocus.current = id;
+    itemRefs.current.get(id)?.focus();
+  };
+  const setExpanded = (next) => {
+    const list = [...next];
+    setExpandedOwn(list);
+    onExpandedChange?.(list);
+  };
+  const open = (node) => {
+    if (expandedSet.has(node.id) || !isExpandable(node)) return;
+    const next = new Set(expandedSet);
+    next.add(node.id);
+    setExpanded(next);
+    if (loadChildren && node.hasChildren && !node.children?.length) {
+      const pending = loadChildren(node);
+      if (pending && typeof pending.then === "function") {
+        setLoading((s) => new Set(s).add(node.id));
+        const done = () => setLoading((s) => {
+          const n = new Set(s);
+          n.delete(node.id);
+          return n;
+        });
+        pending.then(done, done);
+      }
+    }
+  };
+  const close = (node) => {
+    if (!expandedSet.has(node.id)) return;
+    const next = new Set(expandedSet);
+    next.delete(node.id);
+    setExpanded(next);
+  };
+  const toggle = (node) => expandedSet.has(node.id) ? close(node) : open(node);
+  const select = (node) => {
+    if (node.disabled) return;
+    if (selectionMode === "none") {
+      toggle(node);
+      return;
+    }
+    setSelectedOwn(node.id);
+    onSelectedChange?.(node.id, node);
+  };
+  const idOf = (target) => target?.closest?.('[role="treeitem"]')?.dataset.treeId ?? null;
+  const textOf = (flat) => {
+    if (flat.node.textValue !== void 0) return flat.node.textValue;
+    if (typeof flat.node.label === "string") return flat.node.label;
+    const row = itemRefs.current.get(flat.node.id)?.querySelector("[data-tree-row]");
+    return row?.textContent ?? "";
+  };
+  const findByText = (fromIndex, text) => {
+    const needle = text.toLocaleLowerCase();
+    for (let i = 1; i <= visible.length; i++) {
+      const flat = visible[(fromIndex + i) % visible.length];
+      if (textOf(flat).trim().toLocaleLowerCase().startsWith(needle)) return flat.node.id;
+    }
+    return null;
+  };
+  const handleKeyDown = (e) => {
+    onKeyDown?.(e);
+    if (e.defaultPrevented) return;
+    const id = idOf(e.target);
+    const flat = id ? byId.get(id) : void 0;
+    if (!flat) return;
+    const { node } = flat;
+    const index = visible.findIndex((f) => f.node.id === node.id);
+    const expandedNow = expandedSet.has(node.id);
+    const step = horizontalStep(e.key, e.target);
+    const inRun = Date.now() - typeahead.current.at < TYPEAHEAD_MS && typeahead.current.text !== "";
+    const key = e.key === " " && inRun ? "typeahead" : e.key;
+    let handled = true;
+    if (step === 1) {
+      if (!isExpandable(node)) handled = false;
+      else if (!expandedNow) open(node);
+      else if (node.children?.length) focusRow(node.children[0].id);
+    } else if (step === -1) {
+      if (expandedNow) close(node);
+      else if (flat.parentId) focusRow(flat.parentId);
+      else handled = false;
+    } else {
+      switch (key) {
+        case "ArrowDown":
+          if (index < visible.length - 1) focusRow(visible[index + 1].node.id);
+          break;
+        case "ArrowUp":
+          if (index > 0) focusRow(visible[index - 1].node.id);
+          break;
+        case "Home":
+          if (visible.length) focusRow(visible[0].node.id);
+          break;
+        case "End":
+          if (visible.length) focusRow(visible[visible.length - 1].node.id);
+          break;
+        case "Enter":
+        case " ":
+          select(node);
+          break;
+        case "*": {
+          const siblings = flat.parentId ? byId.get(flat.parentId)?.node.children ?? [] : items;
+          const next = new Set(expandedSet);
+          for (const s of siblings) if (isExpandable(s)) next.add(s.id);
+          setExpanded(next);
+          break;
+        }
+        default: {
+          const printable = e.key.length === 1 && !e.ctrlKey && !e.metaKey && !e.altKey;
+          if (!printable) {
+            handled = false;
+            break;
+          }
+          const now = Date.now();
+          const run = now - typeahead.current.at < TYPEAHEAD_MS ? typeahead.current.text : "";
+          typeahead.current = { text: run + e.key, at: now };
+          const typed = typeahead.current.text;
+          const repeated = typed.length > 1 && [...typed].every((c) => c === typed[0]);
+          const target = repeated ? findByText(index, typed[0]) : typed.length > 1 && textOf(flat).trim().toLocaleLowerCase().startsWith(typed.toLocaleLowerCase()) ? node.id : findByText(index, typed);
+          if (target) focusRow(target);
+        }
+      }
+    }
+    if (handled) {
+      e.preventDefault();
+      e.stopPropagation();
+    }
+  };
+  const handleClick = (e) => {
+    onClick?.(e);
+    const id = idOf(e.target);
+    const flat = id ? byId.get(id) : void 0;
+    if (!flat) return;
+    const control = e.target.closest("button, a[href], input, select, textarea");
+    if (control && itemRefs.current.get(flat.node.id)?.contains(control)) return;
+    setFocusedId(flat.node.id);
+    if (e.target.closest("[data-tree-toggle]")) {
+      toggle(flat.node);
+      return;
+    }
+    select(flat.node);
+  };
+  const renderNodes = (nodes, level, path) => nodes.map((node, i) => {
+    const rowId = `${baseId}-${path}${i}`;
+    const expandable = isExpandable(node);
+    const isOpen = expandable && expandedSet.has(node.id);
+    const isSelected = selectionMode !== "none" && selected === node.id;
+    const isLoading = loading.has(node.id);
+    const state = {
+      level,
+      expanded: isOpen,
+      selected: isSelected,
+      expandable,
+      loading: isLoading,
+      disabled: Boolean(node.disabled)
+    };
+    return /* @__PURE__ */ jsxs(
+      "li",
+      {
+        ref: (el) => {
+          if (el) itemRefs.current.set(node.id, el);
+          else itemRefs.current.delete(node.id);
+        },
+        role: "treeitem",
+        "data-tree-id": node.id,
+        "aria-labelledby": rowId,
+        "aria-level": level,
+        "aria-expanded": expandable ? isOpen : void 0,
+        "aria-selected": selectionMode === "none" ? void 0 : isSelected,
+        "aria-disabled": node.disabled || void 0,
+        "aria-busy": isLoading || void 0,
+        tabIndex: node.id === tabbable ? 0 : -1,
+        onFocus: (e) => {
+          if (e.target === e.currentTarget) setFocusedId(node.id);
+        },
+        className: "outline-none [&:focus-visible>[data-tree-row]]:ring-2 [&:focus-visible>[data-tree-row]]:ring-[var(--brand)]",
+        children: [
+          /* @__PURE__ */ jsx(
+            TreeRow,
+            {
+              id: rowId,
+              level,
+              expanded: expandable ? isOpen : void 0,
+              label: node.label,
+              icon: node.icon,
+              trailing: node.trailing,
+              indent,
+              guides: indentGuides,
+              selected: isSelected,
+              loading: isLoading,
+              className: cn(
+                node.disabled ? "cursor-not-allowed opacity-50" : "cursor-pointer hover:bg-[var(--bg-hover)]",
+                rowClassName
+              ),
+              children: renderItem ? renderItem(node, state) : void 0
+            }
+          ),
+          isOpen && /* @__PURE__ */ jsx("ul", { role: "group", children: node.children?.length ? renderNodes(node.children, level + 1, `${path}${i}-`) : null })
+        ]
+      },
+      node.id
+    );
+  });
+  return /* @__PURE__ */ jsx(
+    "ul",
+    {
+      ...rest,
+      role: "tree",
+      onKeyDown: handleKeyDown,
+      onClick: handleClick,
+      className: cn("flex flex-col text-sm", className),
+      children: renderNodes(items, 1, "")
+    }
+  );
+}
+export {
+  TreeRow,
+  TreeView
+};
+//# sourceMappingURL=tree-view.js.map