@horon-ai/react 0.1.1 → 0.1.3

package/src/components/settings-list.tsx

@@ -4,14 +4,44 @@ import { cn } from "../lib/cn";
 import { LiquidGlass } from "./liquid-glass";
 import { Switch, type SwitchProps } from "./switch";
 
-type WithClass<T> = Omit<T, "className"> & { className?: string };
+/** A component's own prop set with `className` replaced by a plain optional string, so names never collide with the DOM attribute. */
+type WithClass<T> = Omit<T, "className"> & {
+  /** Classes merged onto the rendered element. */
+  className?: string;
+};
 
+/**
+ * Props for {@link SettingsList}. Other `div` props (`id`, `data-*`, handlers) land on the card.
+ */
 export type SettingsListProps = WithClass<ComponentProps<"div">> & {
-  /** `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";
 };
 
-/** Paper `Settings list` (1VD8-0): a 16px-radius card of divided rows, 20px inline padding, solid or thick glass. */
+/**
+ * Paper `Settings list` (1VD8-0): a 16px-radius card of divided rows, 20px inline padding, solid or thick glass.
+ *
+ * Put only `SettingsRow` children inside: each row draws its own bottom divider, and the card clips
+ * the corners, so grouping rows here is enough to get the divided list. Glass keeps the rows above
+ * the liquid layer.
+ *
+ * @example
+ * ```tsx
+ * import { SettingsList, SettingsRow, SettingsSwitch } from "@horon-ai/react";
+ *
+ * function Example() {
+ *   return (
+ *     <SettingsList>
+ *       <SettingsRow title="Sync on Wi-Fi" description="Only use Wi-Fi for uploads" control={<SettingsSwitch defaultChecked />} />
+ *       <SettingsRow title="Version" control={<span>2.4.1</span>} />
+ *     </SettingsList>
+ *   );
+ * }
+ * ```
+ */
 export function SettingsList({ surface = "solid", className, children, ...props }: SettingsListProps) {
   return (
     <div
@@ -28,17 +58,27 @@ export function SettingsList({ surface = "solid", className, children, ...props
   );
 }
 
+/**
+ * Props for {@link SettingsRow}. Extra `div` props (`id`, `data-*`, handlers) land on the row.
+ */
 export type SettingsRowProps = Omit<ComponentProps<"div">, "className" | "title"> & {
+  /** Primary line of the row. */
   title: ReactNode;
+  /** Secondary line under the title, in secondary text. */
   description?: ReactNode;
   /** Leading slot before the title, usually a `SettingsRowIcon`; the row tightens to 12px gap and 13px block padding. */
   leading?: ReactNode;
   /** Trailing control slot: a `Switch`, a `SettingsKeys` pair, a button. */
   control?: ReactNode;
+  /** Classes merged onto the row. */
   className?: string;
 };
 
-/** One row: title and subtitle on the left, control on the right, 1px divider except on the last row. */
+/**
+ * One row: title and subtitle on the left, control on the right, 1px divider except on the last row.
+ *
+ * Part of {@link SettingsList}.
+ */
 export function SettingsRow({ title, description, leading, control, className, ...props }: SettingsRowProps) {
   return (
     <div
@@ -59,7 +99,12 @@ export function SettingsRow({ title, description, leading, control, className, .
   );
 }
 
-/** Paper settings row icon tile: 32px, 9px radius, subtle fill, 16px glyph centered. */
+/**
+ * Paper settings row icon tile: 32px, 9px radius, subtle fill, 16px glyph centered. Decorative,
+ * so it is hidden from assistive technology; the row title carries the meaning.
+ *
+ * Part of {@link SettingsList}.
+ */
 export function SettingsRowIcon({ className, ...props }: WithClass<ComponentProps<"span">>) {
   return (
     <span
@@ -73,12 +118,21 @@ export function SettingsRowIcon({ className, ...props }: WithClass<ComponentProp
   );
 }
 
-/** A `Switch` pre-wired for a row's control slot (md, 44x26). */
+/**
+ * A `Switch` pre-wired for a row's control slot (md, 44x26).
+ *
+ * Part of {@link SettingsList}.
+ */
 export function SettingsSwitch(props: SwitchProps) {
   return <Switch size="md" {...props} />;
 }
 
-/** One keycap: 26px high, 6px radius, subtle fill with a 1px hairline (replaces `Kbd` in settings rows). */
+/**
+ * One keycap: 26px high, 6px radius, subtle fill with a 1px hairline (replaces `Kbd` in settings rows).
+ * It renders a `<kbd>`, so screen readers announce it as keyboard input rather than body text.
+ *
+ * Part of {@link SettingsList}.
+ */
 export function SettingsKey({ className, children, ...props }: WithClass<ComponentProps<"kbd">>) {
   return (
     <kbd
@@ -93,7 +147,11 @@ export function SettingsKey({ className, children, ...props }: WithClass<Compone
   );
 }
 
-/** A keycap pair or chord, 4px apart. */
+/**
+ * A keycap pair or chord, 4px apart; a plain flex wrapper, so it takes its children as-is.
+ *
+ * Part of {@link SettingsList}.
+ */
 export function SettingsKeys({ className, ...props }: WithClass<ComponentProps<"span">>) {
   return <span className={cn("inline-flex items-center gap-1", className)} {...props} />;
 }

package/src/components/sidebar.tsx

@@ -15,28 +15,57 @@ import {
 import { cn } from "../lib/cn";
 import { LiquidGlass } from "./liquid-glass";
 
-type DivProps = Omit<ComponentProps<"div">, "className"> & { className?: string };
-type ButtonProps = Omit<ComponentProps<"button">, "className"> & { className?: string };
+/** A `div` prop set with an optional `className`, used by the parts that render a plain `div`. */
+type DivProps = Omit<ComponentProps<"div">, "className"> & {
+  /** Classes merged onto the element. */
+  className?: string;
+};
+/** A `button` prop set with an optional `className`, used by the parts that render a `button`. */
+type ButtonProps = Omit<ComponentProps<"button">, "className"> & {
+  /** Classes merged onto the button. */
+  className?: string;
+};
 
+/**
+ * Props for {@link Sidebar}. Other `nav` props (`aria-label`, `id`, handlers) land on the column.
+ */
 export type SidebarProps = Omit<ComponentProps<"nav">, "className"> & {
+  /** Classes merged onto the column. */
   className?: string;
   /**
    * `glass` (default) is the thick-glass column. `photo` is the Paper app sidebar: the Horon photo
    * on #EEF3F8 under a 55% white veil, with the thick glass kept for dark mode. `plain` paints no
    * fill or glass, so the column takes the color of the layout behind it, divided by a 1px border.
+   * @default "glass"
    */
   surface?: "glass" | "photo" | "plain";
   /**
    * Drag the right edge to change the width, from the `md` breakpoint (768px) up.
    * Below `md` the handle is hidden and the sidebar keeps its fixed 280px width.
+   * @default false
    */
   resizable?: boolean;
-  /** Starting width in px when `resizable`. Double-clicking the handle returns to it. */
+  /**
+   * Starting width in px when `resizable`. Double-clicking the handle returns to it.
+   * @default 280
+   */
   defaultWidth?: number;
+  /**
+   * Narrowest width in px the handle can drag to.
+   * @default 240
+   */
   minWidth?: number;
+  /**
+   * Widest width in px the handle can drag to.
+   * @default 400
+   */
   maxWidth?: number;
   /** Called with the clamped width as it changes, during a drag too. */
   onWidthChange?: (width: number) => void;
+  /**
+   * Accessible name of the resize handle.
+   * @default "Resize sidebar"
+   */
   resizeLabel?: string;
 };
 
@@ -49,6 +78,27 @@ function clamp(value: number, min: number, max: number): number {
 /**
  * Figma `Sidebar` (88:848): a 280px thick-glass column with a 1px right border, 16/12/12px padding.
  * With `resizable`, an 8px handle on the right edge drags the width between `minWidth` and `maxWidth`.
+ *
+ * Width is uncontrolled: the column keeps its own state, starts at `defaultWidth` and reports every
+ * clamped change through `onWidthChange`. The handle is keyboard operable (arrow keys step 16px,
+ * Home/End jump to the limits) and sits behind `md`; the column never grows past a narrower parent.
+ *
+ * @example
+ * ```tsx
+ * import { Sidebar, SidebarGroup, SidebarHeader, SidebarItem } from "@horon-ai/react";
+ *
+ * function Example() {
+ *   return (
+ *     <Sidebar resizable onWidthChange={(width) => console.log(width)}>
+ *       <SidebarHeader initial="H" name="Horon" onCollapse={() => {}} />
+ *       <SidebarGroup label="Workspace">
+ *         <SidebarItem current>Home</SidebarItem>
+ *         <SidebarItem count={3}>Inbox</SidebarItem>
+ *       </SidebarGroup>
+ *     </Sidebar>
+ *   );
+ * }
+ * ```
  */
 export function Sidebar({
   className,
@@ -65,7 +115,12 @@ export function Sidebar({
 }: SidebarProps) {
   const [width, setWidth] = useState(() => clamp(defaultWidth, minWidth, maxWidth));
   const [dragging, setDragging] = useState(false);
-  const drag = useRef<{ x: number; width: number } | null>(null);
+  const drag = useRef<{
+    /** Pointer x (px, client coordinate) where the drag started. */
+    x: number;
+    /** Column width (px) at the moment the drag started, so every move applies to a fixed base. */
+    width: number;
+  } | null>(null);
 
   const resize = (next: number) => {
     const clamped = clamp(next, minWidth, maxWidth);
@@ -165,22 +220,46 @@ export function Sidebar({
   );
 }
 
+/**
+ * Props for {@link SidebarHeader}. Renders the workspace switch and an optional collapse button in
+ * one 36px row.
+ */
 export type SidebarHeaderProps = {
   /** Workspace initial shown on the 28px ink tile. */
   initial: ReactNode;
+  /** Workspace name next to the tile; truncated when the column is narrow. */
   name: ReactNode;
   /** Props for the workspace switch button, such as a `MenuTrigger` render target. */
   switchProps?: ButtonProps;
   /** Replaces the default switch, such as a `WorkspaceMenu` whose trigger is a `SidebarWorkspaceSwitch`. */
   switchSlot?: ReactNode;
+  /** Shows the collapse button when set; it receives the click and the caller hides the column. */
   onCollapse?: () => void;
+  /**
+   * Accessible name of the collapse button.
+   * @default "Collapse sidebar"
+   */
   collapseLabel?: string;
+  /** Classes merged onto the header row. */
   className?: string;
 };
 
-export type SidebarWorkspaceSwitchProps = Omit<ButtonProps, "name"> & { initial: ReactNode; name: ReactNode };
+/**
+ * Props for {@link SidebarWorkspaceSwitch}: every button prop except `name`, which is the visible
+ * workspace label instead.
+ */
+export type SidebarWorkspaceSwitchProps = Omit<ButtonProps, "name"> & {
+  /** Workspace initial on the 28px ink tile. */
+  initial: ReactNode;
+  /** Workspace name, truncated in the row. */
+  name: ReactNode;
+};
 
-/** The workspace switch button: 28px ink tile, name and up-down caret. Highlights while its menu is open. */
+/**
+ * The workspace switch button: 28px ink tile, name and up-down caret. Highlights while its menu is open.
+ *
+ * Part of {@link Sidebar}.
+ */
 export function SidebarWorkspaceSwitch({ initial, name, className, ...props }: SidebarWorkspaceSwitchProps) {
   return (
     <button
@@ -201,7 +280,12 @@ export function SidebarWorkspaceSwitch({ initial, name, className, ...props }: S
   );
 }
 
-/** Header: workspace switch (tile, name, up-down caret) and an optional 28px collapse button. 10px gap below. */
+/**
+ * Header: workspace switch (tile, name, up-down caret) and an optional 28px collapse button. 10px gap below.
+ *
+ * Part of {@link Sidebar}. Pass `switchSlot` when the switch must open a menu; otherwise the built-in
+ * `SidebarWorkspaceSwitch` is rendered with `switchProps` spread onto it.
+ */
 export function SidebarHeader({
   initial,
   name,
@@ -228,25 +312,41 @@ export function SidebarHeader({
   );
 }
 
+/**
+ * Props every sidebar row shares, whichever element it renders as.
+ */
 type SidebarItemCommonProps = {
   /** 18px icon, or a `SidebarProjectTile`. */
   icon?: ReactNode;
   /** Count on the right, such as unread items. */
   count?: ReactNode;
-  /** Trailing 7px red dot for attention. */
+  /** Trailing 7px red dot marking the row for attention; the dot itself carries `aria-label="Needs attention"` but no role. */
   attention?: boolean;
+  /** Marks the active row: 6% ink fill and `aria-current="page"`. */
   current?: boolean;
+  /** Classes merged onto the row. */
   className?: string;
 };
 
-/** With `href`, the row is a real link and takes anchor props; without it, a `type="button"` button. */
+/**
+ * With `href`, the row is a real link and takes anchor props; without it, a `type="button"` button.
+ * The `current` flag adds `aria-current="page"` to either.
+ */
 export type SidebarItemProps =
-  | (SidebarItemCommonProps & { href: string } & Omit<ComponentProps<"a">, "className" | "href" | "type">)
-  | (SidebarItemCommonProps & { href?: undefined } & ButtonProps);
+  | (SidebarItemCommonProps & {
+      /** Destination; setting it switches the row to an anchor. */
+      href: string;
+    } & Omit<ComponentProps<"a">, "className" | "href" | "type">)
+  | (SidebarItemCommonProps & {
+      /** Leave it out to render a button instead of a link. */
+      href?: undefined;
+    } & ButtonProps);
 
 /**
  * Figma sidebar `Item`: 32px row, 12px radius, 10px gap; the current item is 6% ink.
  * Pass `href` to render an `<a>` with the same look.
+ *
+ * Part of {@link Sidebar}.
  */
 export function SidebarItem({ icon, count, attention, current, className, children, ...props }: SidebarItemProps) {
   const classes = cn(
@@ -286,11 +386,18 @@ export function SidebarItem({ icon, count, attention, current, className, childr
   );
 }
 
-/** A 22px rounded tile with a 14px inverse icon, for project rows. Set the fill with `className`. */
+/**
+ * A 22px rounded tile with a 14px inverse icon, for project rows. Set the fill with `className`.
+ *
+ * Part of {@link Sidebar}.
+ */
 export function SidebarProjectTile({
   className,
   ...props
-}: Omit<ComponentProps<"span">, "className"> & { className?: string }) {
+}: Omit<ComponentProps<"span">, "className"> & {
+  /** Classes merged onto the tile; the fill color comes from here. */
+  className?: string;
+}) {
   return (
     <span
       className={cn(
@@ -302,14 +409,29 @@ export function SidebarProjectTile({
   );
 }
 
+/**
+ * Props for {@link SidebarGroup}.
+ */
 export type SidebarGroupProps = {
+  /** Group caption; also the collapsible trigger's label. */
   label: ReactNode;
+  /**
+   * Whether the group starts expanded.
+   * @default true
+   */
   defaultOpen?: boolean;
+  /** Rows or projects inside the group. */
   children: ReactNode;
+  /** Classes merged onto the group. */
   className?: string;
 };
 
-/** A collapsible group: 28px label in secondary text with a 14px caret, 14px above. */
+/**
+ * A collapsible group: 28px label in secondary text with a 14px caret, 14px above.
+ *
+ * Part of {@link Sidebar}. The group is uncontrolled after mount; the caret rotates from pointing
+ * right (collapsed) to down (open) and the panel height animates.
+ */
 export function SidebarGroup({ label, defaultOpen = true, children, className }: SidebarGroupProps) {
   return (
     <Collapsible.Root defaultOpen={defaultOpen} className={cn("relative mt-3.5 flex flex-col gap-0.5", className)}>
@@ -340,8 +462,19 @@ function branchesPath(count: number): string {
   return [trunk, ...branches].join("");
 }
 
-/** Figma `Tree`: nested sidebar items with 16px icons, 20px in, joined to the parent by curved connectors. */
-export function SidebarTree({ children, className }: { children: ReactNode; className?: string }) {
+/**
+ * Figma `Tree`: nested sidebar items with 16px icons, 20px in, joined to the parent by curved connectors.
+ *
+ * Part of {@link Sidebar}. The connector is one SVG path computed from the child count, so it
+ * assumes 32px rows with a 2px gap; pass the child rows directly rather than wrapping them.
+ */
+// prettier-ignore
+export function SidebarTree({ children, className }: {
+  /** Child rows; their count and order decide the connector shape. */
+  children: ReactNode;
+  /** Classes merged onto the tree wrapper. */
+  className?: string;
+}) {
   const count = Children.count(children);
   const height = ROW / 2 + (count - 1) * (ROW + GAP) + 0.75;
   return (
@@ -361,18 +494,33 @@ export function SidebarTree({ children, className }: { children: ReactNode; clas
   );
 }
 
-/** Pushes the account card to the bottom. */
+/**
+ * Pushes the account card to the bottom.
+ *
+ * Part of {@link Sidebar}; it grows to fill the remaining column height.
+ */
 export function SidebarSpacer() {
   return <div aria-hidden className="min-h-px flex-1" />;
 }
 
+/**
+ * Props for {@link SidebarAccount}: every button prop plus the identity lines it shows.
+ */
 export type SidebarAccountProps = ButtonProps & {
+  /** Initials on the 36px sky avatar tile. */
   initials: ReactNode;
+  /** Account name. */
   name: ReactNode;
+  /** Email line under the name. */
   email?: ReactNode;
 };
 
-/** Figma sidebar `Account`: a 54px row with a 36px sky avatar tile and an up-down caret. */
+/**
+ * Figma sidebar `Account`: a 54px row with a 36px sky avatar tile and an up-down caret.
+ *
+ * Part of {@link Sidebar}. The row is a button, so pair it with a menu when it should open an
+ * account switcher.
+ */
 export function SidebarAccount({ initials, name, email, className, ...props }: SidebarAccountProps) {
   return (
     <button
@@ -396,13 +544,24 @@ export function SidebarAccount({ initials, name, email, className, ...props }: S
   );
 }
 
+/**
+ * Props for {@link SidebarProject}.
+ */
 export type SidebarProjectProps = {
   /** A `SidebarProjectTile`. */
   icon: ReactNode;
+  /** Project name; truncated in the row. */
   label: ReactNode;
+  /** Marks the active project: 6% ink row and `aria-current="page"`. */
   current?: boolean;
+  /**
+   * Whether the project starts expanded in uncontrolled mode.
+   * @default false
+   */
   defaultOpen?: boolean;
+  /** Expanded state in controlled mode; pass `onOpenChange` with it. */
   open?: boolean;
+  /** Fires with the next expanded state when the row is toggled. */
   onOpenChange?: (open: boolean) => void;
   /**
    * The project's "More" control, such as a `MenuTrigger` whose render target is
@@ -411,6 +570,7 @@ export type SidebarProjectProps = {
   actions?: ReactNode;
   /** Chats and documents in the project, shown in a `SidebarTree` when open. */
   children?: ReactNode;
+  /** Classes merged onto the project block. */
   className?: string;
 };
 
@@ -418,6 +578,10 @@ export type SidebarProjectProps = {
  * Figma sidebar project row (88:848, Menu=Project 314:12407): tile, name and a
  * 14px chevron (down when open). An open project shows the 16px "More" button in
  * place of the chevron, on a 6% ink row; a collapsed project keeps the chevron.
+ *
+ * Part of {@link Sidebar}. The expanded state works uncontrolled (`defaultOpen`) or controlled
+ * (`open` + `onOpenChange`). A project without children renders no panel and no chevron; the
+ * trigger still toggles the open state, and any `actions` stay visible.
  */
 export function SidebarProject({
   icon,
@@ -481,9 +645,23 @@ export function SidebarProject({
   );
 }
 
-export type SidebarProjectMoreProps = ButtonProps & { label?: string };
+/**
+ * Props for {@link SidebarProjectMore}: every button prop plus the accessible label.
+ */
+export type SidebarProjectMoreProps = ButtonProps & {
+  /**
+   * Accessible name of the button.
+   * @default "Project actions"
+   */
+  label?: string;
+};
 
-/** The 16px "More" button of a project row. */
+/**
+ * The 16px "More" button of a project row.
+ *
+ * Part of {@link Sidebar}; its tap target is widened to 44px by a pseudo-element so the small glyph
+ * stays easy to hit.
+ */
 export function SidebarProjectMore({ label = "Project actions", className, ...props }: SidebarProjectMoreProps) {
   return (
     <button
@@ -500,15 +678,24 @@ export function SidebarProjectMore({ label = "Project actions", className, ...pr
   );
 }
 
-export type SidebarAddButtonProps = ButtonProps & { icon?: ReactNode };
+/**
+ * Props for {@link SidebarAddButton}: every button prop plus the trailing icon.
+ */
+export type SidebarAddButtonProps = ButtonProps & {
+  /** Icon after the label; defaults to a 16px plus circle. @default a 16px plus-circle (`PlusCircle`) icon */
+  icon?: ReactNode;
+};
+
+/** Default trailing icon of {@link SidebarAddButton}. */
+const addIcon = <PlusCircle />;
 
 /**
  * Figma `Add project`: a 36px button with a 1px inside dashed border (4/3 dash,
  * 20% ink), label then a 16px plus-circle, 12px above. The border is an SVG rect
  * so the dash matches; its 2px stroke is clipped to the inner 1px.
+ *
+ * Part of {@link Sidebar}.
  */
-const addIcon = <PlusCircle />;
-
 export function SidebarAddButton({ icon = addIcon, className, children, ...props }: SidebarAddButtonProps) {
   return (
     <button
@@ -539,4 +726,8 @@ export function SidebarAddButton({ icon = addIcon, className, children, ...props
   );
 }
 
+/**
+ * A `div` prop set with an optional `className`, exported so callers can type their own sidebar
+ * pieces the same way the internal parts do.
+ */
 export type { DivProps as SidebarDivProps };

package/src/components/skeleton.tsx

@@ -3,13 +3,39 @@ import type { ComponentProps } from "react";
 import { cn } from "../lib/cn";
 import { LiquidGlass } from "./liquid-glass";
 
+/**
+ * Props for {@link Skeleton}. Other `div` props (`style`, `data-*`) land on the placeholder.
+ */
 export type SkeletonProps = Omit<ComponentProps<"div">, "className"> & {
-  /** `block` has the Figma 6px radius, `pill` is fully round (avatars, buttons). */
+  /**
+   * `block` has the Figma 6px radius, `pill` is fully round (avatars, buttons).
+   * @default "block"
+   */
   shape?: "block" | "pill";
+  /** Classes that give the placeholder its size, such as `h-2 w-40`. */
   className?: string;
 };
 
-/** A 7% ink placeholder; size it with classes. */
+/**
+ * A 7% ink placeholder; size it with classes.
+ *
+ * The block is `aria-hidden` and shimmers with a translucent highlight, so it shows layout while
+ * content loads without being read out.
+ *
+ * @example
+ * ```tsx
+ * import { Skeleton } from "@horon-ai/react";
+ *
+ * function Example() {
+ *   return (
+ *     <div className="flex items-center gap-3">
+ *       <Skeleton shape="pill" className="size-9" />
+ *       <Skeleton className="h-3 w-48" />
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
 export function Skeleton({ shape = "block", className, ...props }: SkeletonProps) {
   return (
     <div
@@ -24,14 +50,45 @@ export function Skeleton({ shape = "block", className, ...props }: SkeletonProps
   );
 }
 
+/**
+ * Props for {@link SkeletonCard}.
+ */
 export type SkeletonCardProps = {
+  /**
+   * Placeholder arrangement: `row` an avatar with two lines, `card` a heading, three lines and a
+   * button, `text` three lines only.
+   * @default "row"
+   */
   type?: "row" | "card" | "text";
-  /** `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";
+  /** Classes merged onto the card. */
   className?: string;
 };
 
-/** Figma `Skeleton` (in Loading 109:733): Row, Card and Text placeholders on a solid or thick-glass card. */
+/**
+ * Figma `Skeleton` (in Loading 109:733): Row, Card and Text placeholders on a solid or thick-glass card.
+ *
+ * Use it while a list, a detail card or a paragraph loads. The card announces itself once with
+ * `role="status"` and the label "Loading"; the individual bars stay hidden from assistive tech.
+ *
+ * @example
+ * ```tsx
+ * import { SkeletonCard } from "@horon-ai/react";
+ *
+ * function Example() {
+ *   return (
+ *     <div className="flex flex-col gap-3">
+ *       <SkeletonCard />
+ *       <SkeletonCard type="text" />
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
 export function SkeletonCard({ type = "row", surface = "solid", className }: SkeletonCardProps) {
   return (
     <div

package/src/components/slider.tsx

@@ -3,14 +3,44 @@ import type { ComponentProps } from "react";
 
 import { cn } from "../lib/cn";
 
+/**
+ * Props of {@link Slider}: every Base UI `Slider.Root` prop (`value`, `defaultValue`,
+ * `onValueChange`, `min`, `max`, `step`, `disabled`, `orientation`) plus the two overrides below.
+ */
 export type SliderProps = Omit<ComponentProps<typeof BaseSlider.Root>, "className" | "children"> & {
+  /** Extra classes for the root, which is 220px wide (`w-55`) and caps at its container by default. */
   className?: string;
+  /** Accessible name of the thumb, the only focusable part of the control. */
   "aria-label"?: string;
 };
 
 /**
  * Paper settings slider (Voice / Speed): a 20px control, 6px track at 8% ink with an ink fill,
  * and an 18px white thumb with a 1px hairline and a 0 1 3 12% shadow. Width comes from the caller.
+ *
+ * Wraps Base UI's slider: the whole 20px row is draggable and clickable, the thumb is the
+ * focusable element (focus ring on `text-brand`, it scales up on hover and press), and a
+ * disabled slider dims to 40% with a not-allowed cursor.
+ *
+ * @example
+ * ```tsx
+ * import { useState } from "react";
+ * import { Slider } from "@horon-ai/react";
+ *
+ * function VoiceSpeed() {
+ *   const [speed, setSpeed] = useState(1);
+ *   return (
+ *     <Slider
+ *       aria-label="Voice speed"
+ *       min={0.5}
+ *       max={2}
+ *       step={0.1}
+ *       value={speed}
+ *       onValueChange={(next) => setSpeed(next as number)}
+ *     />
+ *   );
+ * }
+ * ```
  */
 export function Slider({ className, "aria-label": ariaLabel, ...props }: SliderProps) {
   return (