@horon-ai/react 0.1.1 → 0.1.3

package/src/components/toast.tsx

@@ -5,7 +5,14 @@ import type { ReactNode } from "react";
 import { cn } from "../lib/cn";
 import type { ControlSize } from "../lib/size";
 
+/**
+ * Toast severity, which picks the leading icon and its color: `neutral` (info icon, secondary
+ * text), `success` (check, brand color) or `danger` (warning, danger color). Any other Base UI
+ * toast type falls back to `neutral`.
+ */
 export type ToastTone = "neutral" | "success" | "danger";
+
+/** Toast rungs: `sm` 320px, `md` 360px and `lg` 400px wide cards. */
 export type ToastSize = ControlSize;
 
 const toneIcon: Record<ToastTone, ReactNode> = {
@@ -54,7 +61,14 @@ function isTone(value: string | undefined): value is ToastTone {
   return value === "neutral" || value === "success" || value === "danger";
 }
 
-function ToastList({ size, surface }: { size: ToastSize; surface: "solid" | "glass" }) {
+/** Renders the live toast queue; each toast is a Base UI root positioned by the provider's viewport. */
+// prettier-ignore
+function ToastList({ size, surface }: {
+  /** Card rung applied to every toast in the stack. */
+  size: ToastSize;
+  /** `glass` paints each card on the veil; `solid` gives it a surface fill, a border and the popover shadow. */
+  surface: "solid" | "glass";
+}) {
   const { toasts } = BaseToast.useToastManager();
   return toasts.map((toast) => {
     const tone = isTone(toast.type) ? toast.type : "neutral";
@@ -89,21 +103,51 @@ function ToastList({ size, surface }: { size: ToastSize; surface: "solid" | "gla
   });
 }
 
+/** Props of {@link Toaster}: the app subtree it wraps plus the size and surface every toast shares. */
 export type ToasterProps = {
+  /** The app subtree; toasts portal to the viewport on top of it. */
   children?: ReactNode;
-  /** Toast size: `sm` 320px, `md` 360px (default), `lg` 400px; applies to every toast this provider shows. */
+  /** Toast size: `sm` 320px, `md` 360px (default), `lg` 400px; applies to every toast this provider shows. @default "md" */
   size?: ToastSize;
   /**
    * `solid` (default) is an opaque surface card with a default border; `glass` puts it on the veil (`veil-overlay`).
-   * Applies to every toast this provider shows.
+   * Applies to every toast this provider shows. @default "solid"
    */
   surface?: "solid" | "glass";
+  /** Extra classes on the fixed viewport, which sits 24px from the bottom, right and left edges. */
   className?: string;
 };
 
 /**
  * Figma `Toast` (62:307): a 360px card, solid or the veil. Wrap the app once; call
  * `useToast().add({ title, description, type: "success" })` to show one.
+ *
+ * Toasts portal to a fixed bottom-right viewport that stacks upward; each card rises 16px into
+ * place in 240ms, shrinks from 95% as it fades in, and leaves to the right while its height
+ * collapses. The close button clears it, and the whole height/margin tween runs on
+ * `--toast-height`.
+ *
+ * @example
+ * ```tsx
+ * import { Toaster, useToast } from "@horon-ai/react";
+ *
+ * function App() {
+ *   return (
+ *     <Toaster size="md" surface="solid">
+ *       <SaveButton />
+ *     </Toaster>
+ *   );
+ * }
+ *
+ * function SaveButton() {
+ *   const toast = useToast();
+ *   return (
+ *     <button onClick={() => toast.add({ title: "Saved", description: "All changes stored.", type: "success" })}>
+ *       Save
+ *     </button>
+ *   );
+ * }
+ * ```
  */
 export function Toaster({ children, size = "md", surface = "solid", className }: ToasterProps) {
   return (
@@ -125,4 +169,9 @@ export function Toaster({ children, size = "md", surface = "solid", className }:
   );
 }
 
+/**
+ * The toast manager from the nearest {@link Toaster}: `add({ title, description, type })` shows a
+ * toast and returns its id, `close(id)` dismisses one, and `toasts` is the live list the viewport
+ * renders. Calling it without a provider throws.
+ */
 export const useToast = BaseToast.useToastManager;

package/src/components/tool-call.tsx

@@ -7,10 +7,22 @@ import { cn } from "../lib/cn";
 import { Button } from "./button";
 import { Spinner } from "./spinner";
 
+/**
+ * Any JSON-shaped value: a string, number, boolean, `null`, or an array or object of the same.
+ * `ToolCall` renders `args` and `result` through {@link JsonCode}, so plain objects and arrays are
+ * enough; class instances and functions are not supported.
+ */
 type Json = string | number | boolean | null | Json[] | { [key: string]: Json };
 
 const punctuation = (text: string) => <span className="text-syntax-punctuation">{text}</span>;
 
+/**
+ * Walks a JSON value and returns syntax-highlighted React nodes, nesting one indentation step per level.
+ *
+ * @param value - The JSON value to render.
+ * @param indent - Current nesting depth; 0 for a root value, one extra level per object or array.
+ * @returns A flat list of span nodes for the key, string, number and punctuation syntax colors.
+ */
 function renderJson(value: Json, indent: number): ReactNode[] {
   const pad = "  ".repeat(indent);
   if (value === null || typeof value === "number" || typeof value === "boolean") {
@@ -50,8 +62,20 @@ function renderJson(value: Json, indent: number): ReactNode[] {
   ];
 }
 
-/** JSON in Geist Mono code style with the Figma syntax colors (key, string, number, punctuation). */
-export function JsonCode({ value, className }: { value: Json; className?: string }) {
+/**
+ * JSON in Geist Mono code style with the Figma syntax colors (key, string, number, punctuation).
+ *
+ * Renders a `pre` in the code type token that wraps lines so long values stay inside a narrow card;
+ * it scrolls horizontally only when a single unbreakable token overflows. Used by {@link ToolCall}
+ * for tool arguments and results, and usable on its own.
+ */
+// prettier-ignore
+export function JsonCode({ value, className }: {
+  /** The JSON value to print; see `Json` for the accepted shapes. */
+  value: Json;
+  /** Extra classes for the `pre`, for example a maximum height or `text-code` override. */
+  className?: string;
+}) {
   return (
     <pre
       className={cn("max-w-full overflow-x-auto font-mono text-code whitespace-pre-wrap text-syntax-string", className)}
@@ -61,35 +85,67 @@ export function JsonCode({ value, className }: { value: Json; className?: string
   );
 }
 
+/**
+ * Lifecycle state of a tool call.
+ *
+ * - `running`: a spinner replaces the status icon and the result section shows "Waiting for result…".
+ * - `done`: a live-green check marks the row and the result is printed.
+ * - `failed`: the card border turns danger, an error notice (with an optional Retry button) replaces the result.
+ */
 export type ToolCallStatus = "running" | "done" | "failed";
 
+/**
+ * Props for {@link ToolCall}.
+ */
 export type ToolCallProps = {
+  /** Current lifecycle state; drives the status icon, border and which sections appear. */
   status: ToolCallStatus;
   /** Plain tool name, such as "Web search", with its 16px icon. */
-  tool: { icon: ReactNode; name: ReactNode };
+  tool: {
+    /** A 16px Phosphor icon; it inherits the secondary text color inside the name pill. */
+    icon: ReactNode;
+    /** The visible tool name; truncates when the header runs out of room. */
+    name: ReactNode;
+  };
+  /** One-line description of the call, such as the query that was sent. */
   summary: ReactNode;
+  /** Elapsed time, such as "1.2s"; hidden when omitted. */
   elapsed?: ReactNode;
+  /** Arguments object printed as JSON in an `Arguments` section when defined. */
   args?: Json;
+  /** Result value printed as JSON in a `Result` section while the call is `running` (as a waiting message) or `done`; a `failed` call omits the section in favour of `error`. */
   result?: Json;
+  /** Failure message shown instead of the result section when `status` is `failed`. */
   error?: ReactNode;
+  /** Renders a Retry button on the failure notice; omit it to show the error without a retry. */
   onRetry?: () => void;
   /** The result is cut off; shows a "Show all" link under it. */
   truncated?: boolean;
+  /** Called when the "Show all" link is pressed; only rendered when `truncated` is set and a result exists. */
   onShowAll?: () => void;
+  /** Starts the card expanded; the card manages its own open state afterwards. */
   defaultOpen?: boolean;
+  /** Extra classes for the card root. */
   className?: string;
 };
 
+/**
+ * One labelled block inside the expanded card: an uppercase label row with an optional copy button,
+ * a subtle rounded body, and an optional footer (used for the "Show all" link).
+ */
 function Section({
   label,
   children,
   copyText,
   footer,
 }: {
+  /** Uppercase heading, such as "Arguments"; also names the copy button for screen readers. */
   label: string;
+  /** Body content, normally a {@link JsonCode} block or the waiting message. */
   children: ReactNode;
   /** Plain text of the section body; adds a real copy button when present. */
   copyText?: string;
+  /** Content under the body, such as the truncated "Show all" link. */
   footer?: ReactNode;
 }) {
   const { copied, copy } = useCopyToClipboard(1500);
@@ -118,7 +174,34 @@ function Section({
   );
 }
 
-/** Figma `Tool call` (Tool call card 186:7811): a solid 16px-radius card that expands to arguments and result. */
+/**
+ * Figma `Tool call` (Tool call card 186:7811): a solid 16px-radius card that expands to arguments and result.
+ *
+ * The header trigger is a Base UI collapsible: it shows the tool pill, the summary, a status icon
+ * (spinner, check or warning) and a caret that rotates while open. The expanded body adds the
+ * failure notice with Retry, the JSON `Arguments` section and the `Result` section with copy buttons.
+ * The card is uncontrolled apart from `defaultOpen`; use {@link JsonCode} directly when only the
+ * highlighted JSON is needed.
+ *
+ * @example
+ * ```tsx
+ * import { ToolCall } from "@horon-ai/react";
+ * import { Globe } from "@phosphor-icons/react";
+ *
+ * function Example() {
+ *   return (
+ *     <ToolCall
+ *       status="done"
+ *       tool={{ icon: <Globe />, name: "Web search" }}
+ *       summary="Fetched 8 results for Horon tokens"
+ *       elapsed="1.2s"
+ *       args={{ query: "Horon design tokens" }}
+ *       result={{ results: 8 }}
+ *     />
+ *   );
+ * }
+ * ```
+ */
 export function ToolCall({
   status,
   tool,

package/src/components/tool-calls-header.tsx

@@ -4,21 +4,52 @@ import { Children, type ReactNode } from "react";
 
 import { cn } from "../lib/cn";
 
+/**
+ * Props for {@link ToolCallsHeader}.
+ */
 export type ToolCallsHeaderProps = {
   /** Up to three 14px tool icons, drawn as overlapping 28px chips. */
   icons?: ReactNode;
+  /** Header text; defaults to "Using tools…". @default "Using tools…" */
   title?: ReactNode;
   /** Elapsed time, such as "4.0s". */
   elapsed?: ReactNode;
   /** `ToolCall` cards, stacked 8px apart under the header. */
   children?: ReactNode;
+  /** Starts with the cards shown; the group manages its own open state afterwards. @default true */
   defaultOpen?: boolean;
+  /** Controlled open state; pass `onOpenChange` too when set. */
   open?: boolean;
+  /** Called with the next open state whenever the trigger is pressed. */
   onOpenChange?: (open: boolean) => void;
+  /** Extra classes for the outer card. */
   className?: string;
 };
 
-/** Figma `Tool-calls header` (Agents N11): overlapping tool chips, "Using tools…" and a caret that fold the ToolCall cards below. */
+/**
+ * Figma `Tool-calls header` (Agents N11): overlapping tool chips, "Using tools…" and a caret that fold the ToolCall cards below.
+ *
+ * Only the first three icons are drawn, each as a 28px chip. The trigger is a Base UI collapsible
+ * button that rotates the caret and reveals the children in a `motion-collapse` panel. Pass `open`
+ * and `onOpenChange` to control it, or leave them out and start from `defaultOpen`.
+ *
+ * @example
+ * ```tsx
+ * import { ToolCall, ToolCallsHeader } from "@horon-ai/react";
+ * import { Globe, Terminal } from "@phosphor-icons/react";
+ *
+ * function Example() {
+ *   return (
+ *     <ToolCallsHeader
+ *       icons={[<Globe key="globe" aria-hidden />, <Terminal key="terminal" aria-hidden />]}
+ *       elapsed="4.0s"
+ *     >
+ *       <ToolCall status="done" tool={{ icon: <Globe />, name: "Web search" }} summary="Searched the docs" />
+ *     </ToolCallsHeader>
+ *   );
+ * }
+ * ```
+ */
 export function ToolCallsHeader({
   icons,
   title = "Using tools…",

package/src/components/tool-permissions.tsx

@@ -3,27 +3,54 @@ import { type ComponentProps, type ReactNode, useState } from "react";
 import { cn } from "../lib/cn";
 import { SegmentedControl } from "./segmented-control";
 
+/**
+ * Permission a tool can be given.
+ *
+ * - `allow`: runs without asking.
+ * - `ask`: asks for confirmation before each call; the fallback when a `ToolPermissionItem` has no `defaultValue`.
+ * - `off`: the tool is disabled.
+ */
 export type ToolPermission = "allow" | "ask" | "off";
 
+/**
+ * One tool row in {@link ToolPermissions}.
+ */
 export type ToolPermissionItem = {
+  /** Tool name, shown in mono type; also the key used in `values`. */
   name: string;
+  /** Caption under the name, such as what the tool reads or writes. */
   description?: ReactNode;
   /** Starting choice for the uncontrolled component; defaults to `ask`. */
   defaultValue?: ToolPermission;
 };
 
+/**
+ * Props for {@link ToolPermissions}.
+ */
 export type ToolPermissionsProps = Omit<ComponentProps<"div">, "className" | "title" | "onChange"> & {
+  /** Header title, such as "Tool access". */
   title: ReactNode;
+  /** One row per tool, in display order; the row count also fills the header pill. */
   tools: ToolPermissionItem[];
   /** Controlled choices keyed by tool name. */
   values?: Record<string, ToolPermission>;
+  /** Called with the complete next map whenever one row changes or "Allow all" is pressed. */
   onValuesChange?: (values: Record<string, ToolPermission>) => void;
-  /** Label of the text button that sets every tool to Allow. */
+  /** Label of the text button that sets every tool to Allow. @default "Allow all" */
   allowAllLabel?: ReactNode;
+  /** Extra classes for the card root. */
   className?: string;
 };
 
-const options: { value: ToolPermission; label: string }[] = [
+/**
+ * Segmented control options in display order; each row renders the same Allow / Ask / Off triple.
+ */
+const options: {
+  /** Permission stored for the tool when this segment is picked. */
+  value: ToolPermission;
+  /** Segment label shown to the user. */
+  label: string;
+}[] = [
   { value: "allow", label: "Allow" },
   { value: "ask", label: "Ask" },
   { value: "off", label: "Off" },
@@ -34,6 +61,27 @@ const options: { value: ToolPermission; label: string }[] = [
  * carries the group title, a count pill and an "Allow all" text button; below it one divided row per tool
  * with a mono name, a description and a small solid Allow / Ask / Off segmented control. 16px side padding
  * on every row so the names, the header title and the controls line up.
+ *
+ * The component is uncontrolled by default, seeding each row from `ToolPermissionItem.defaultValue`
+ * (or `ask`). Pass `values` and `onValuesChange` to control every row at once; the controlled map wins
+ * over the internal state, and the internal copy is still updated on each change.
+ *
+ * @example
+ * ```tsx
+ * import { ToolPermissions } from "@horon-ai/react";
+ *
+ * function Example() {
+ *   return (
+ *     <ToolPermissions
+ *       title="Tool access"
+ *       tools={[
+ *         { name: "web_search", description: "Read public pages", defaultValue: "allow" },
+ *         { name: "shell", description: "Run local commands" },
+ *       ]}
+ *     />
+ *   );
+ * }
+ * ```
  */
 export function ToolPermissions({
   title,

package/src/components/tooltip.tsx

@@ -1,15 +1,43 @@
 import { Tooltip as BaseTooltip } from "@base-ui/react/tooltip";
 import type { ReactElement, ReactNode } from "react";
 
+/**
+ * Props for {@link Tooltip}.
+ */
 export type TooltipProps = {
   /** The element that shows the tooltip on hover and focus. */
   children: ReactElement;
+  /** Bubble content; keep it to a short phrase because the bubble caps at 256px. */
   label: ReactNode;
+  /** Preferred side of the trigger; Base UI flips it when there is no room. @default "top" */
   side?: "top" | "bottom" | "left" | "right";
+  /** Hover delay in milliseconds before the bubble opens; Base UI's default when omitted. */
   delay?: number;
 };
 
-/** Figma `Tooltip` (62:282): an ink bubble, 10/6px padding, 8px radius, with a 10x6 arrow. */
+/**
+ * Figma `Tooltip` (62:282): an ink bubble, 10/6px padding, 8px radius, with a 10x6 arrow.
+ *
+ * The trigger is the child element itself (Base UI `render`), so no wrapper node is added. The popup
+ * is portaled to the body at `z-50`, 6px from the trigger with an arrow that follows the chosen side,
+ * and it opens on hover and on keyboard focus.
+ *
+ * @example
+ * ```tsx
+ * import { Tooltip } from "@horon-ai/react";
+ * import { Copy } from "@phosphor-icons/react";
+ *
+ * function Example() {
+ *   return (
+ *     <Tooltip label="Copy link" side="top">
+ *       <button type="button" aria-label="Copy link">
+ *         <Copy />
+ *       </button>
+ *     </Tooltip>
+ *   );
+ * }
+ * ```
+ */
 export function Tooltip({ children, label, side = "top", delay }: TooltipProps) {
   return (
     <BaseTooltip.Root>
@@ -30,4 +58,8 @@ export function Tooltip({ children, label, side = "top", delay }: TooltipProps)
   );
 }
 
+/**
+ * Base UI tooltip provider, re-exported unchanged. Wrap a group of tooltips in it to share hover
+ * timing, so moving between adjacent triggers does not restart each delay.
+ */
 export const TooltipProvider = BaseTooltip.Provider;

package/src/components/top-bar.tsx

@@ -6,21 +6,54 @@ import { Avatar } from "./avatar";
 import { IconButton } from "./icon-button";
 import { LiquidGlass } from "./liquid-glass";
 
+/**
+ * Props for {@link TopBar}.
+ */
 export type TopBarProps = Omit<ComponentProps<"header">, "className" | "title"> & {
+  /** Bar title; truncates to one line and re-runs the fade-in when the text changes. */
   title: ReactNode;
+  /** Second line under the title, muted and truncated. */
   subtitle?: ReactNode;
   /** Shows the live status dot on the avatar. */
   live?: boolean;
+  /** Renders the back IconButton on the left and calls this on press; hidden when omitted. */
   onBack?: () => void;
+  /** Renders the overflow IconButton on the right and calls this on press; hidden when omitted. */
   onMore?: () => void;
+  /** Accessible label of the back button. @default "Back" */
   backLabel?: string;
+  /** Accessible label of the overflow button. @default "More" */
   moreLabel?: string;
-  /** `solid` (default) is an opaque surface bar with a default border; `glass` is the regular glass bar. */
+  /** `solid` (default) is an opaque surface bar with a default border; `glass` is the regular glass bar. @default "solid" */
   surface?: "solid" | "glass";
+  /** Extra classes for the `header` element. */
   className?: string;
 };
 
-/** Paper `Top bar`: back button, bot avatar with a flush live dot, title and subtitle, on solid surface or regular glass. */
+/**
+ * Paper `Top bar`: back button, bot avatar with a flush live dot, title and subtitle, on solid surface or regular glass.
+ *
+ * Renders a rounded `header` with `rounded-full` corners; the glass variant mounts {@link LiquidGlass}
+ * as its first child, so keep the bar inside a positioned parent. Back and overflow buttons only appear
+ * when `onBack` / `onMore` are passed, which keeps the bare title layout for read-only screens.
+ *
+ * @example
+ * ```tsx
+ * import { TopBar } from "@horon-ai/react";
+ *
+ * function Example() {
+ *   return (
+ *     <TopBar
+ *       title="Research bot"
+ *       subtitle="12 tasks today"
+ *       live
+ *       onBack={() => history.back()}
+ *       onMore={() => console.log("more")}
+ *     />
+ *   );
+ * }
+ * ```
+ */
 export function TopBar({
   title,
   subtitle,

package/src/components/usage-meter.tsx

@@ -4,7 +4,11 @@ import type { ReactNode } from "react";
 import { cn } from "../lib/cn";
 import { LiquidGlass } from "./liquid-glass";
 
+/**
+ * Props for {@link UsageMeter}.
+ */
 export type UsageMeterProps = {
+  /** What the meter measures, such as "Tasks used"; sits left of the percentage. */
   label: ReactNode;
   /** 0-100. */
   value: number;
@@ -12,12 +16,34 @@ export type UsageMeterProps = {
   detail?: ReactNode;
   /** Right caption, such as "Resets Nov 1". */
   note?: ReactNode;
-  /** `solid` (default) is an opaque surface card with a default border; `glass` is the thick glass card. */
+  /** `solid` (default) is an opaque surface card with a default border; `glass` is the thick glass card. @default "solid" */
   surface?: "solid" | "glass";
+  /** Extra classes for the meter root. */
   className?: string;
 };
 
-/** Figma `Usage meter` (in Loading 109:733): a card with a 6px sky fill, solid or thick glass. */
+/**
+ * Figma `Usage meter` (in Loading 109:733): a card with a 6px sky fill, solid or thick glass.
+ *
+ * Built on Base UI `Meter`, so the percentage is exposed to assistive technology and the fill
+ * animates its width over 400ms. The fill is the single `sky-500` accent; the card caps at 300px wide.
+ *
+ * @example
+ * ```tsx
+ * import { UsageMeter } from "@horon-ai/react";
+ *
+ * function Example() {
+ *   return (
+ *     <UsageMeter
+ *       label="Tasks"
+ *       value={64}
+ *       detail="6,420 of 10,000 tasks"
+ *       note="Resets Nov 1"
+ *     />
+ *   );
+ * }
+ * ```
+ */
 export function UsageMeter({ label, value, detail, note, surface = "solid", className }: UsageMeterProps) {
   return (
     <Meter.Root

package/src/components/workspace-menu.tsx

@@ -4,8 +4,13 @@ import type { ComponentProps, ReactNode } from "react";
 import { cn } from "../lib/cn";
 import { Menu, MenuContent, MenuItem, MenuLabel, MenuSeparator, MenuTile, MenuTrigger } from "./menu";
 
+/**
+ * One workspace listed in {@link WorkspaceMenu}.
+ */
 export type WorkspaceMenuItem = {
+  /** Stable identifier returned by `onValueChange` and compared with `value`. */
   id: string;
+  /** Workspace name shown in the row. */
   name: string;
   /** Caption under the name, such as "12 members". */
   meta?: ReactNode;
@@ -13,21 +18,61 @@ export type WorkspaceMenuItem = {
   initial?: string;
 };
 
+/**
+ * Props for {@link WorkspaceMenu}.
+ */
 export type WorkspaceMenuProps = {
+  /** Workspaces in menu order; the current one gets a check. */
   workspaces: WorkspaceMenuItem[];
+  /** Id of the current workspace. */
   value: string;
+  /** Called with the picked workspace id; pressing the current one calls it too. */
   onValueChange?: (id: string) => void;
+  /** Called by the "New workspace" row; the row stays visible when omitted. */
   onCreate?: () => void;
+  /** Called by the "Workspace settings" row; the row stays visible when omitted. */
   onSettings?: () => void;
   /** The element that opens the menu, such as the sidebar workspace button. */
   trigger: ComponentProps<typeof MenuTrigger>["render"];
+  /** Content of the trigger when `trigger` renders a plain element rather than taking children. */
   triggerChildren?: ReactNode;
+  /** Extra classes for the trigger element. */
   triggerClassName?: string;
+  /** Menu heading above the workspace rows. @default "Workspaces" */
   label?: ReactNode;
+  /** Extra classes for the menu popup. */
   className?: string;
 };
 
-/** Paper `Workspace menu`: solid 256px menu listing workspaces with a check on the current one. */
+/**
+ * Paper `Workspace menu`: solid 256px menu listing workspaces with a check on the current one.
+ *
+ * Wraps the package {@link Menu} in a solid surface so the popup stays readable over any background.
+ * Each row shows a tile with the workspace initial and fades a check in on the selected id; a separator
+ * then offers "New workspace" and "Workspace settings". The menu is anchored to `trigger` and opens
+ * below it, aligned to the start edge.
+ *
+ * @example
+ * ```tsx
+ * import { WorkspaceMenu } from "@horon-ai/react";
+ * import { useState } from "react";
+ *
+ * function Example() {
+ *   const [current, setCurrent] = useState("acme");
+ *   return (
+ *     <WorkspaceMenu
+ *       workspaces={[
+ *         { id: "acme", name: "Acme" },
+ *         { id: "labs", name: "Labs", meta: "4 members" },
+ *       ]}
+ *       value={current}
+ *       onValueChange={setCurrent}
+ *       trigger={<button type="button">Acme</button>}
+ *     />
+ *   );
+ * }
+ * ```
+ */
 export function WorkspaceMenu({
   workspaces,
   value,

package/src/hooks/use-active-indicator.ts

@@ -1,6 +1,18 @@
 import { type RefObject, useEffect, useLayoutEffect, useState } from "react";
 
-export type IndicatorRect = { left: number; top: number; width: number; height: number };
+/**
+ * Position of the active item inside its track, in CSS px, taken from the item's `offset*` readings.
+ */
+export type IndicatorRect = {
+  /** Left offset measured from the track, as `offsetLeft` reports it. */
+  left: number;
+  /** Top offset measured from the track, as `offsetTop` reports it. */
+  top: number;
+  /** Width of the active item. */
+  width: number;
+  /** Height of the active item. */
+  height: number;
+};
 
 /**
  * Measures the active item inside a positioned track so one indicator can slide
@@ -8,6 +20,37 @@ export type IndicatorRect = { left: number; top: number; width: number; height:
  * or `[aria-current="page"]`); the rect follows attribute changes and resizes.
  * `animate` turns true one frame after the first placement, so the indicator
  * lands in place instead of sliding in from 0,0.
+ *
+ * Measuring happens in a layout effect, so a server render draws no indicator: `rect` starts `null`, and the
+ * first client pass places the item before paint while `animate` stays false.
+ *
+ * @param track - Ref to the positioned track element that holds the items.
+ * @param selector - CSS selector for the active item, queried inside the track; a missing item yields a null rect.
+ * @returns The measured rect (or `null` before the first measurement) and an `animate` flag for the first frame.
+ *
+ * @example
+ * ```tsx
+ * import { useActiveIndicator } from "@horon-ai/react";
+ *
+ * function Tabs({ items, value }: { items: string[]; value: string }) {
+ *   const track = useRef<HTMLDivElement>(null);
+ *   const { rect, animate } = useActiveIndicator(track, '[aria-current="page"]');
+ *   return (
+ *     <div ref={track} className="relative flex gap-1">
+ *       {items.map((item) => (
+ *         <button key={item} aria-current={item === value ? "page" : undefined}>
+ *           {item}
+ *         </button>
+ *       ))}
+ *       <span
+ *         aria-hidden
+ *         className={animate ? "pointer-events-none absolute rounded-full motion-indicator" : "pointer-events-none absolute rounded-full"}
+ *         style={{ ...rect, opacity: rect ? 1 : 0 }}
+ *       />
+ *     </div>
+ *   );
+ * }
+ * ```
  */
 export function useActiveIndicator(track: RefObject<HTMLElement | null>, selector: string) {
   const [rect, setRect] = useState<IndicatorRect | null>(null);