@horon-ai/react 0.1.1 → 0.1.3

package/src/components/horon-icon.tsx

@@ -81,12 +81,33 @@ import {
 } from "@phosphor-icons/react";
 import type { ComponentProps } from "react";
 
-export type HoronIconProps = Omit<ComponentProps<"svg">, "children"> & { size?: number | string };
+/** Props for the Horon mark: any svg attribute plus a size like a Phosphor icon. */
+export type HoronIconProps = Omit<ComponentProps<"svg">, "children"> & {
+  /** Width and height together: a px number or a CSS length. @default "1em" */
+  size?: number | string;
+};
 
 /**
  * Figma `icon/horon` (256:9116): the line falcon eye that stands in for Horon in
  * navigation. Phosphor has no equivalent, so the path is copied from the Tab bar
  * (63:441) export. It takes `currentColor` and sizes like a Phosphor icon.
+ *
+ * The svg is `aria-hidden` by default and its 22-unit viewBox scales with `size`, so it drops into any place
+ * a Phosphor glyph fits. The default `1em` makes it follow the font size, which is what a row of mixed icons
+ * needs.
+ *
+ * @example
+ * ```tsx
+ * import { HoronIcon } from "@horon-ai/react";
+ *
+ * function BrandMark() {
+ *   return (
+ *     <span className="flex size-10 items-center justify-center rounded-full bg-bg-subtle text-text-primary">
+ *       <HoronIcon size={22} />
+ *     </span>
+ *   );
+ * }
+ * ```
  */
 export function HoronIcon({ size = "1em", ...props }: HoronIconProps) {
   return (
@@ -100,6 +121,9 @@ export function HoronIcon({ size = "1em", ...props }: HoronIconProps) {
  * Paper's icon contract: every icon is a component named `icon/<name>`. `iconNames` is that list in
  * Paper order. Paper draws three sizes (16 in small controls and captions, 20 in buttons and rows,
  * 24 in bars and empty states); 12, 14, 18 and 22 elsewhere in the code stay as they are.
+ *
+ * The tuple is the single source of the registry: `HoronIconName` derives from it and `phosphorGlyphs`
+ * must map every entry except `horon`, so a name added here fails to type-check until it has a glyph.
  */
 export const iconNames = [
   "plus",
@@ -183,6 +207,7 @@ export const iconNames = [
   "plus-circle",
 ] as const;
 
+/** Every registered icon name: a literal union derived from `iconNames`. */
 export type HoronIconName = (typeof iconNames)[number];
 
 const phosphorGlyphs: Record<Exclude<HoronIconName, "horon">, Icon> = {
@@ -266,13 +291,35 @@ const phosphorGlyphs: Record<Exclude<HoronIconName, "horon">, Icon> = {
   "plus-circle": PlusCircle,
 };
 
+/** Props for `HoronGlyph`: the registry name plus the same svg attributes a Phosphor icon takes. */
 export type HoronGlyphProps = Omit<ComponentProps<"svg">, "children" | "ref"> & {
+  /** Which registered glyph to draw; `horon` resolves to the Horon mark instead of a Phosphor icon. */
   name: HoronIconName;
-  /** Paper sizes are 16, 20 and 24. */
+  /** Paper sizes are 16, 20 and 24. @default 20 */
   size?: number | string;
 };
 
-/** Figma `icon/<name>`: resolves a registry name to its glyph. Takes `currentColor`, so the parent's text color drives it. */
+/**
+ * Figma `icon/<name>`: resolves a registry name to its glyph. Takes `currentColor`, so the parent's text color drives it.
+ *
+ * The runtime lookup behind an icon name stored as data (a tool's icon, a settings row): `horon` returns
+ * `HoronIcon`, everything else the matching Phosphor component. Like Phosphor, the svg is `aria-hidden`;
+ * put the meaning on the surrounding button or label. Outside data-driven cases, prefer importing the
+ * Phosphor icon directly so the bundler can tree-shake it.
+ *
+ * @example
+ * ```tsx
+ * import { HoronGlyph, type HoronIconName } from "@horon-ai/react";
+ *
+ * function ToolIcon({ icon }: { icon: HoronIconName }) {
+ *   return (
+ *     <span className="text-text-secondary">
+ *       <HoronGlyph name={icon} size={20} />
+ *     </span>
+ *   );
+ * }
+ * ```
+ */
 export function HoronGlyph({ name, size = 20, ...props }: HoronGlyphProps) {
   if (name === "horon") return <HoronIcon size={size} {...props} />;
   const Glyph = phosphorGlyphs[name];

package/src/components/horon-wordmark.tsx

@@ -1,6 +1,14 @@
 import type { ComponentProps } from "react";
 
-export type HoronWordmarkProps = Omit<ComponentProps<"svg">, "children"> & { title?: string };
+/** Props of {@link HoronWordmark}: any svg attribute plus the accessible name. */
+export type HoronWordmarkProps = Omit<ComponentProps<"svg">, "children"> & {
+  /**
+   * Accessible name of the wordmark. It becomes the `aria-label` on the `role="img"` svg, so screen readers
+   * announce it as one image rather than six paths.
+   * @default "Horon"
+   */
+  title?: string;
+};
 
 const PATHS = [
   "M0.0230414 11.2212H1.91244L1.92626 8.60366L1.93548 5.99076H8.47923L8.48845 8.60366L8.50228 11.2212H10.3917L10.4193 8.06449C10.447 5.32717 10.5207 2.68663 10.6267 0.585252L10.6543 0H8.47923V4.2857H1.93548V0H0L0.0230414 11.2212Z",
@@ -14,6 +22,23 @@ const PATHS = [
 /**
  * The UI-size Horon wordmark from the Figma Sidebar (88:808): a 48.7 x 11.5
  * vector in `currentColor`. Scale it with `height`; the width follows.
+ *
+ * Six filled paths trace the letter outlines as one drawing, painted in the current text color, so color it
+ * with the surrounding `text-*` class rather than a `fill` prop. The paths carry no individual names; only
+ * `title` gives the svg its accessible name.
+ *
+ * @example
+ * ```tsx
+ * import { HoronWordmark } from "@horon-ai/react";
+ *
+ * function SidebarBrand() {
+ *   return (
+ *     <div className="flex items-center gap-2 text-text-primary">
+ *       <HoronWordmark height={12} />
+ *     </div>
+ *   );
+ * }
+ * ```
  */
 export function HoronWordmark({ title = "Horon", height = 11.5, ...props }: HoronWordmarkProps) {
   return (

package/src/components/icon-button.tsx

@@ -5,15 +5,31 @@ import { cn } from "../lib/cn";
 import type { ControlSize } from "../lib/size";
 import { LiquidGlass } from "./liquid-glass";
 
+/**
+ * Fill and text colour of an icon button:
+ *
+ * - `primary`: solid brand fill with the inverse icon, for the one main action in a cluster.
+ * - `ghost` (default): no fill until hover, primary icon; the common toolbar and row action.
+ * - `glass`: the clear glass disc with a `LiquidGlass` layer, for floating chrome over imagery.
+ * - `solid`: bordered raised surface, for a button that sits on the page background.
+ * - `quiet`: no fill and no liquid layer, secondary icon that turns primary on hover; for dark shells
+ *   and title bars where a glass disc would read as a grey bubble.
+ */
 export type IconButtonVariant = "primary" | "ghost" | "glass" | "solid" | "quiet";
+/** Square footprint: `sm` 32px, `md` 40px, `lg` 48px. */
 export type IconButtonSize = ControlSize;
 
+/** Props of {@link IconButton}: the treatment, the footprint and the glyph. */
 export type IconButtonProps = Omit<ComponentProps<typeof BaseButton>, "className" | "children"> & {
+  /** Treatment, from the list on `IconButtonVariant`. @default "ghost" */
   variant?: IconButtonVariant;
+  /** Square footprint: `sm` 32px, `md` 40px, `lg` 48px, with the icon at 16/20/24px. @default "md" */
   size?: IconButtonSize;
+  /** The glyph. It is wrapped in a positioning span; size it through the button rather than by hand. */
   icon: ReactNode;
   /** Accessible name; the button has no visible text. */
   label: string;
+  /** Extra classes for the button. */
   className?: string;
 };
 
@@ -37,7 +53,28 @@ const variantClass: Record<IconButtonVariant, string> = {
     "text-text-secondary hover:not-data-disabled:bg-overlay-ink-6 hover:not-data-disabled:text-text-primary active:not-data-disabled:bg-overlay-ink-10",
 };
 
-/** Figma `Icon button` (57:167): Primary, Ghost, Glass and Solid in three sizes, plus a fill-free `quiet` variant. */
+/**
+ * Figma `Icon button` (57:167): Primary, Ghost, Glass and Solid in three sizes, plus a fill-free `quiet` variant.
+ *
+ * A round, icon-only Base UI button. `label` becomes `aria-label`, since nothing is visible; the visible
+ * disc is 32/40/48px while an invisible pseudo-element keeps a 44px touch target around it. It renders
+ * `LiquidGlass` inside the `glass` variant only, and disabled state is 40% opacity with `cursor-not-allowed`.
+ *
+ * @example
+ * ```tsx
+ * import { Gear, Plus } from "@phosphor-icons/react";
+ * import { IconButton } from "@horon-ai/react";
+ *
+ * function Actions() {
+ *   return (
+ *     <div className="flex items-center gap-1">
+ *       <IconButton icon={<Plus />} label="New agent" variant="primary" />
+ *       <IconButton icon={<Gear />} label="Settings" />
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
 export function IconButton({ variant = "ghost", size = "md", icon, label, className, ...props }: IconButtonProps) {
   return (
     <BaseButton

package/src/components/input-group.tsx

@@ -5,8 +5,10 @@ import { cn } from "../lib/cn";
 import type { ControlSize } from "../lib/size";
 import { fieldBoxClass, fieldTextClass, type InputSurface } from "./input";
 
+/** Height rung of the group and its segments: `sm` 32px, `md` 40px, `lg` 48px. */
 export type InputGroupSize = ControlSize;
 
+/** Props of {@link InputGroup}: the input's own props plus the segments around it. */
 export type InputGroupProps = Omit<ComponentProps<typeof BaseInput>, "className" | "prefix" | "size"> & {
   /**
    * Segment before the input: `<Select variant="segment" />` or `<Combobox variant="segment" />`
@@ -15,19 +17,35 @@ export type InputGroupProps = Omit<ComponentProps<typeof BaseInput>, "className"
   prefix?: ReactNode;
   /** Segment after the input, such as a currency select. */
   suffix?: ReactNode;
+  /** Height and text rung: 32/40/48px, matching a standalone `Input`. @default "md" */
   size?: InputGroupSize;
+  /** Paints the danger border on the whole group and marks the input `aria-invalid`. */
   invalid?: boolean;
-  /** Solid (default) or glass, as on `Input`. */
+  /** Solid (default) or glass, as on `Input`. @default "solid" */
   surface?: InputSurface;
+  /** Extra classes for the box that wraps the segments and the input. */
   className?: string;
 };
 
-type InputGroupContextValue = { size: InputGroupSize; disabled: boolean; surface: InputSurface };
+/** What a segment reads from the group it sits in. */
+type InputGroupContextValue = {
+  /** Height rung the group was given. */
+  size: InputGroupSize;
+  /** Whether the group is disabled, so segments can dim and drop their own interactivity. */
+  disabled: boolean;
+  /** Surface the group uses, so a segment and the box stay the same material. */
+  surface: InputSurface;
+};
 
 /** Lets a segment (select, combobox or fixed text) take the group's size, disabled state and surface. */
 const InputGroupContext = createContext<InputGroupContextValue | null>(null);
 
-/** The group a segment sits in, or null outside an `InputGroup`. */
+/**
+ * The group a segment sits in, or null outside an `InputGroup`. `Select` and `Combobox` call it in their
+ * `segment` variant to pick the right height, padding and disabled look without a prop of their own.
+ *
+ * @returns The `{ size, disabled, surface }` of the enclosing group, or `null` when there is none.
+ */
 export function useInputGroup() {
   return useContext(InputGroupContext);
 }
@@ -55,7 +73,30 @@ export const inputGroupSegmentClass: Record<InputGroupSize, string> = {
 const divider =
   "relative h-full w-px shrink-0 bg-border-default group-data-invalid:bg-border-danger group-data-disabled:bg-border-default/60";
 
-/** Figma `Input group` (60:429): a glass or solid field split into a select segment and an input segment, in three sizes. */
+/**
+ * Figma `Input group` (60:429): a glass or solid field split into a select segment and an input segment, in three sizes.
+ *
+ * One box drawn from `fieldBoxClass` holds the optional `prefix`, the input and the optional `suffix`, with a
+ * 1px hairline between them; the hairlines turn danger-red with `invalid` and dim with the group's `disabled`.
+ * The group renders its own Base UI input, so pass `placeholder`/`value`/`onChange` as props rather than
+ * children. Size, disabled state and surface go to the segments through `InputGroupContext`, which is why a
+ * `Select` or `Combobox` with `variant="segment"` matches without extra props.
+ *
+ * @example
+ * ```tsx
+ * import { InputGroup, InputGroupSegment } from "@horon-ai/react";
+ *
+ * function Website() {
+ *   return (
+ *     <InputGroup
+ *       prefix={<InputGroupSegment>https://</InputGroupSegment>}
+ *       placeholder="horon.ai"
+ *       size="md"
+ *     />
+ *   );
+ * }
+ * ```
+ */
 export function InputGroup({
   prefix,
   suffix,
@@ -99,8 +140,18 @@ export function InputGroup({
   );
 }
 
-/** A fixed-text segment, such as a unit or a `https://` prefix. Takes the group's size. */
-export function InputGroupSegment({ className, children }: { className?: string; children: ReactNode }) {
+/**
+ * Part of {@link InputGroup}. A fixed-text segment, such as a unit or a `https://` prefix. Takes the group's
+ * size (falling back to `md` outside a group), sits on the 4% ink tint, and dims its text when the group is
+ * disabled.
+ */
+// prettier-ignore
+export function InputGroupSegment({ className, children }: {
+  /** Extra classes for the segment. */
+  className?: string;
+  /** Segment content: short text, or text plus an icon sized by the segment's rung. */
+  children: ReactNode;
+}) {
   const group = useInputGroup();
   return (
     <div

package/src/components/input.tsx

@@ -4,17 +4,29 @@ import type { ComponentProps, ReactNode } from "react";
 import { cn } from "../lib/cn";
 import type { ControlSize } from "../lib/size";
 
+/** Height rung shared with every sized control: `sm` 32px, `md` 40px, `lg` 48px. */
 export type InputSize = ControlSize;
+
+/**
+ * Where the input sits:
+ *
+ * - `glass`: on imagery or a glass panel; uses the veil field (`.veil-field`) with no liquid layer inside.
+ * - `solid`: on a raised surface (`bg-bg-surface`), the default.
+ * - `solid-on-page`: directly on the page background (`bg-bg-default`), so the box reads against it.
+ */
 export type InputSurface = "glass" | "solid" | "solid-on-page";
 
+/** Props of {@link Input}: the native input attributes plus the box's size, surface and decorations. */
 export type InputProps = Omit<ComponentProps<typeof BaseInput>, "className" | "size"> & {
+  /** Height and text rung: 32/40/48px with `body-sm/md/lg` text. @default "md" */
   size?: InputSize;
-  /** `glass` over imagery and glass panels, `solid` on raised surfaces, `solid-on-page` directly on the page background. */
+  /** `glass` over imagery and glass panels, `solid` on raised surfaces, `solid-on-page` directly on the page background. @default "solid" */
   surface?: InputSurface;
   /** Leading icon, 16px (sm, md) or 20px (lg), in the secondary text color. */
   icon?: ReactNode;
   /** Shows the error border. Inside a `Field`, an invalid field does the same. */
   invalid?: boolean;
+  /** Extra classes for the box that wraps the input. */
   className?: string;
   /** Classes for the native `<input>`. */
   inputClassName?: string;
@@ -34,19 +46,53 @@ export const fieldTextClass: Record<ControlSize, string> = {
   lg: "text-body-lg",
 };
 
+/**
+ * The class set a field-shaped control composes: the box (border, radius, focus ring), the surface fill and
+ * the inner text/input. Shared by `Input` and `InputGroup` so every field-style control stays one material.
+ */
 export const fieldBoxClass = {
   /** The box is the focus target's container, so the ring is drawn on `:focus-within`, not on the inner input. */
   base: "motion-colors relative flex min-w-0 max-w-full items-center overflow-clip rounded-md border focus-within:outline-2 focus-within:outline-offset-2 focus-within:outline-text-brand",
   /** The veil field (globals.css `.veil-field`): no liquid layers, so hosts render no `LiquidGlass`. */
   glass: "veil-field has-[[data-disabled]]:opacity-60 has-[:disabled]:opacity-60",
+  /** Raised surface fill with a default border; disabled or invalid states repaint both fill and border. */
   solid:
     "border-border-default bg-bg-surface has-[[data-disabled]]:border-border-default has-[:disabled]:border-border-default has-[[data-disabled]]:bg-bg-subtle has-[:disabled]:bg-bg-subtle has-[[data-invalid]]:border-border-danger data-invalid:border-border-danger",
+  /** The solid fill on the page background instead of a raised surface; the same disabled and invalid states. */
   "solid-on-page":
     "border-border-default bg-bg-default has-[[data-disabled]]:border-border-default has-[:disabled]:border-border-default has-[[data-disabled]]:bg-bg-subtle has-[:disabled]:bg-bg-subtle has-[[data-invalid]]:border-border-danger data-invalid:border-border-danger",
+  /** The inner control: transparent, fills the remaining width, primary text, placeholder and disabled colours. */
   text: "min-w-0 flex-1 bg-transparent text-text-primary outline-none placeholder:text-text-placeholder disabled:cursor-not-allowed disabled:text-text-disabled",
 } as const;
 
-/** Figma `Input` (58:126): SM, MD and LG, on Glass or Solid surface. */
+/**
+ * Figma `Input` (58:126): SM, MD and LG, on Glass or Solid surface.
+ *
+ * A bordered box around Base UI's input: render the box, then the optional leading icon, then the native
+ * `<input>`, which takes the remaining width. Focus is drawn on the box (`:focus-within`), so the ring never
+ * detaches from the field. `invalid` marks both the box (`data-invalid`) and the input (`aria-invalid`); a
+ * `Field` that reports invalid does the same through Base UI. Every other prop (`value`, `onChange`,
+ * `placeholder`, `disabled`, `type`, …) goes to the native input, while `className`/`inputClassName` split
+ * between the box and the input itself.
+ *
+ * @example
+ * ```tsx
+ * import { MagnifyingGlass } from "@phosphor-icons/react";
+ * import { Input } from "@horon-ai/react";
+ *
+ * function Search() {
+ *   return (
+ *     <Input
+ *       type="search"
+ *       size="md"
+ *       icon={<MagnifyingGlass />}
+ *       placeholder="Search agents"
+ *       aria-label="Search agents"
+ *     />
+ *   );
+ * }
+ * ```
+ */
 export function Input({
   size = "md",
   surface = "solid",

package/src/components/integration-row.tsx

@@ -4,21 +4,36 @@ import type { ReactNode } from "react";
 import { cn } from "../lib/cn";
 import { LiquidGlass } from "./liquid-glass";
 
+/**
+ * Connection state of an integration:
+ *
+ * - `connected`: sky tile, a live-dot "Connected" pill and no button.
+ * - `reconnect`: dark-sky tile, a red outline on the row, danger text in `detail` and a danger action button.
+ * - `not-connected`: subtle tile, secondary text and the primary "Connect" button.
+ */
 export type IntegrationStatus = "connected" | "reconnect" | "not-connected";
 
+/** Props of {@link IntegrationRow}: the service, its connection state and the one action. */
 export type IntegrationRowProps = {
   /** 20px icon shown in inverse on the 40px tile. */
   icon: ReactNode;
+  /** Service name on the first line, truncated with an ellipsis. */
   name: ReactNode;
   /** Account and scopes, or the reason a reconnect is needed. */
   detail?: ReactNode;
+  /** Drives the tile fill, the pill or button on the right and the row's danger border. */
   status: IntegrationStatus;
+  /** Called when the button is pressed; connected rows have no button, so it never fires then. */
   onAction?: () => void;
+  /** Pill text for `connected`. @default "Connected" */
   connectedLabel?: string;
+  /** Button text for `reconnect`. @default "Reconnect" */
   reconnectLabel?: string;
+  /** Button text for `not-connected`. @default "Connect" */
   connectLabel?: string;
-  /** `solid` (default) is an opaque surface card with a default border; `glass` is the thick glass row. */
+  /** `solid` (default) is an opaque surface card with a default border; `glass` is the thick glass row. @default "solid" */
   surface?: "solid" | "glass";
+  /** Extra classes for the row. */
   className?: string;
 };
 
@@ -28,7 +43,33 @@ const tileClass: Record<IntegrationStatus, string> = {
   "not-connected": "bg-bg-subtle text-text-secondary",
 };
 
-/** Figma `Integration row` (Integrations 110:883): 40px tile, status pill on the right, solid or thick glass. */
+/**
+ * Figma `Integration row` (Integrations 110:883): 40px tile, status pill on the right, solid or thick glass.
+ *
+ * A one-line service row: 40px rounded tile with the icon, a name and an optional detail line that share a
+ * `basis-40` column so the row wraps on narrow widths, and one action slot on the right. The pill and the
+ * button are both mounted and swapped with `motion-swap`; the inactive one is `aria-hidden` and untabbable,
+ * so the row never exposes a dead control. `glass` adds a `LiquidGlass` layer and moves the reconnect outline
+ * to the glass edge.
+ *
+ * @example
+ * ```tsx
+ * import { SlackLogo } from "@phosphor-icons/react";
+ * import { IntegrationRow } from "@horon-ai/react";
+ *
+ * function Slack() {
+ *   return (
+ *     <IntegrationRow
+ *       icon={<SlackLogo />}
+ *       name="Slack"
+ *       detail="horon.slack.com · 4 scopes"
+ *       status="reconnect"
+ *       onAction={() => reconnect("slack")}
+ *     />
+ *   );
+ * }
+ * ```
+ */
 export function IntegrationRow({
   icon,
   name,

package/src/components/kbd.tsx

@@ -5,13 +5,16 @@ import { cn } from "../lib/cn";
 import { formatShortcut } from "../lib/platform";
 import type { ControlSize } from "../lib/size";
 
+/** Height rung of the chip, shared with the other sized controls: `sm`, `md`, `lg`. */
 export type KbdSize = ControlSize;
 
+/** Props of {@link Kbd}: the native `kbd` attributes plus the chip size. */
 export type KbdProps = Omit<ComponentProps<"kbd">, "className"> & {
-  /** Chip size: `sm` tighter caption, `md` the Command palette chip (default), `lg` label-sm with more padding. */
+  /** Chip size: `sm` tighter caption, `md` the Command palette chip (default), `lg` label-sm with more padding. @default "md" */
   size?: KbdSize;
   /** Shortcut such as `Mod+Enter`, drawn with the OS's key labels (`⌘↵` / `Ctrl+Enter`) instead of children. */
   keys?: string;
+  /** Extra classes for the `kbd` element. */
   className?: string;
 };
 
@@ -22,7 +25,30 @@ const sizeClass: Record<KbdSize, string> = {
   lg: "h-6 gap-1 px-2 text-label-sm [&_svg]:size-3.5",
 };
 
-/** Figma `Kbd` (Command palette 110:676): a 6% ink chip with caption text. */
+/**
+ * Figma `Kbd` (Command palette 110:676): a 6% ink chip with caption text.
+ *
+ * A `<kbd>` for a keyboard shortcut: inline-flex, `rounded-xs`, secondary text, centred on a trimmed
+ * line box so the glyph sits optically centred in the chip. Pass `keys` as a `+`-joined shortcut such as
+ * `Mod+Enter` and the chip draws the OS's labels — `⌘↵` on macOS and iOS, `Ctrl+Enter` on Windows, Linux
+ * and Android, and the Mac symbols whenever the OS is still unknown (server render, first hydration pass).
+ * Without `keys` it renders `children`, so several chips can be composed by hand
+ * (`<Kbd>⌘</Kbd><Kbd>K</Kbd>`). Sizes are 16/20/24px tall, and any icon inside is resized with the chip
+ * (`2.5`/`3`/`3.5`), so pass a bare Phosphor icon or glyph.
+ *
+ * @example
+ * ```tsx
+ * import { Kbd } from "@horon-ai/react";
+ *
+ * function Hint() {
+ *   return (
+ *     <span className="flex items-center gap-1 text-caption">
+ *       Search <Kbd keys="Mod+K" />
+ *     </span>
+ *   );
+ * }
+ * ```
+ */
 export function Kbd({ size = "md", keys, className, children, ...props }: KbdProps) {
   const { os } = usePlatform();
   return (

package/src/components/knowledge-base-panel.tsx

@@ -5,32 +5,51 @@ import { cn } from "../lib/cn";
 import { PanelPillTabs } from "./bot-instructions-panel";
 import { Spinner } from "./spinner";
 
+/** One pill tab of {@link KnowledgeBasePanel}, such as "All" or "Documents". */
 export type KnowledgeBaseTab = {
+  /** Stable identifier; it is the tab's value and React key. */
   id: string;
+  /** Tab text. */
   label: ReactNode;
+  /** Optional count drawn in caption colour right of the label. */
   count?: number;
 };
 
+/** Props for {@link KnowledgeBasePanel}: header, tabs, indexing state and the dropzone handler. */
 export type KnowledgeBasePanelProps = Omit<ComponentProps<"section">, "className" | "title" | "onChange"> & {
+  /** Panel heading, rendered as the `h3`. */
   title: ReactNode;
   /** The 12/18 line under the title: sources, chunks, bots. */
   meta?: ReactNode;
+  /** Pills of the tab tray, in display order. */
   tabs: KnowledgeBaseTab[];
+  /** Controlled selected tab id. Leave unset to let the component hold the selection itself. */
   value?: string;
+  /** Initial selected tab when uncontrolled. Falls back to the first tab. */
   defaultValue?: string;
+  /** Fires with the new tab id when a pill is clicked. */
   onValueChange?: (id: string) => void;
-  /** Shows the spinner and "N indexing" at the right of the tabs when above zero. */
+  /** Shows the spinner and "N indexing" at the right of the tabs when above zero.
+   * @default 0 */
   indexing?: number;
+  /** Fires when the round settings button is clicked; the button always renders. */
   onSettings?: () => void;
+  /** Fires when "Add source" is clicked; the button always renders. */
   onAddSource?: () => void;
   /** Called with the files dropped on the dropzone or picked with Browse. Omit to hide the dropzone. */
   onFiles?: (files: File[]) => void;
+  /** Headline inside the dropzone.
+   * @default "Drop files here, or browse" */
   dropTitle?: ReactNode;
+  /** Supporting line under the dropzone headline.
+   * @default "PDF, DOCX, Markdown or TXT · Notion, Google Drive and websites from Add source" */
   dropHint?: ReactNode;
-  /** Pipeline column labels shown above the list; hidden on narrow widths. */
+  /** Pipeline column labels shown above the list; hidden on narrow widths.
+   * @default ["Parse", "Chunk", "Embed", "Index"] */
   stages?: string[];
   /** The list rows, usually `SourceRow variant="list"`. */
   children?: ReactNode;
+  /** Extra classes on the panel `section`, merged after the built-in ones. */
   className?: string;
 };
 
@@ -40,6 +59,25 @@ const defaultStages = ["Parse", "Chunk", "Embed", "Index"];
  * Paper `Knowledge base` (XVM-1): a 24px-radius surface panel with a header, a pill tab tray, a table head, a
  * flat divided source list and a dashed dropzone. The selected tab pill travels in 280ms, the dropzone border and
  * fill change in 150ms while a file is over it, and indexing progress fills are animated by the rows.
+ *
+ * The dropzone is a `<label>` wrapping a visually hidden multi-file input, so
+ * clicking it opens the file picker as well as accepting a drag; the input is
+ * cleared after each pick so the same file can be chosen twice. Passing `onFiles`
+ * is what makes the dropzone appear.
+ *
+ * @example
+ * ```tsx
+ * <KnowledgeBasePanel
+ *   title="Knowledge base"
+ *   meta="3 sources · 128 chunks"
+ *   tabs={[{ id: "all", label: "All", count: 3 }]}
+ *   indexing={2}
+ *   onAddSource={openSourcePicker}
+ *   onFiles={upload}
+ * >
+ *   <SourceRow variant="list" status="ready" icon={<FileText />} name="README.md" detail="24 chunks" />
+ * </KnowledgeBasePanel>
+ * ```
  */
 export function KnowledgeBasePanel({
   title,

package/src/components/liquid-glass.tsx

@@ -18,6 +18,22 @@
  *
  * Without backdrop-filter support, or with reduced transparency requested, the
  * fill turns to `glass-fill-frost` and the rim stays (see `globals.css`).
+ *
+ * It takes no props and renders a single `aria-hidden` span; every visual
+ * decision comes from the host's class list, so the same element serves buttons,
+ * headers, cards and sheets.
+ *
+ * @example
+ * ```tsx
+ * function GlassCard() {
+ *   return (
+ *     <div className="relative isolate overflow-clip rounded-xl bg-glass-regular p-4">
+ *       <LiquidGlass />
+ *       <span className="relative">Floating chrome over the backdrop</span>
+ *     </div>
+ *   );
+ * }
+ * ```
  */
 export function LiquidGlass() {
   return <span aria-hidden className="liquid-layers" />;