@horon-ai/react 0.1.1 → 0.1.2

package/src/components/flue-background.tsx

@@ -3,44 +3,87 @@ import { type CSSProperties, useEffect, useRef } from "react";
 import { useColorScheme } from "../hooks/use-color-scheme";
 import { cn } from "../lib/cn";
 
+/**
+ * Every knob the fragment shader reads. Each key becomes a uniform named `u` plus the capitalised key
+ * (`speed` → `uSpeed`), and a hex string is uploaded as a `vec3`, so add a field here and a matching
+ * uniform in the shader or it silently does nothing. `cursor` and `maxDpr` are engine keys instead: they
+ * never become uniforms and are skipped when uniforms are bound.
+ */
 export type FlueConfig = {
+  /** Flat ground color, hex. Painted on the wrapper, so it is also the fallback when WebGL2 is unavailable. */
   bgColor: string;
+  /** Faintest ramp stop, a near-ground tint that only the thinnest smoke reaches. */
   colorA: string;
+  /** Second ramp stop: the first visible blue of the plume. */
   colorB: string;
+  /** Third ramp stop: the dense body of the plume. */
   colorC: string;
+  /** Densest ramp stop, also the glow color at high density. */
   colorD: string;
+  /** Zoom of the base noise field; larger values make the smoke finer and busier. */
   scale: number;
+  /** Time multiplier, so the drift speed follows it. Larger values scroll faster. */
   speed: number;
+  /** Vertical advection added to the curl field per second, the internal flow of the plume. */
   flow: number;
+  /** Gain of each fbm octave (0..1); lower values keep the coarse shape dominant. */
   roughness: number;
+  /** Frequency step between fbm octaves; larger values add detail at smaller and smaller scale. */
   lacunarity: number;
+  /** Zoom of the density field: larger values make individual wisps smaller. */
   smokeScale: number;
+  /** Amount of curl-noise displacement; higher values swirl the smoke more. */
   curl: number;
+  /** Zoom of the curl potential field, so the swirls themselves change size. */
   curlScale: number;
+  /** Upward drift of the smoke in uv per second. */
   rise: number;
+  /** Vertical frequency multiplier for the density field; larger values compress the wisps vertically. */
   slender: number;
+  /** Half-width (uv) of the vertical corridor the plume is allowed to fill. */
   width: number;
+  /** How much the corridor widens from the bottom to the top of the frame. */
   spread: number;
+  /** How far the pointer's x pushes the top of the plume sideways. */
   lean: number;
+  /** Overall density multiplier before the threshold. */
   density: number;
+  /** Gain around `midpoint`: higher values give a harder edge between ground and smoke. */
   contrast: number;
+  /** Threshold (0..1) where smoke starts to show; higher values leave more of the ground bare. */
   midpoint: number;
+  /** Strength of the `colorD` bloom on the densest part, added as `pow(f, 4)`. */
   glow: number;
+  /** Smoothstep width, over the density value, at which the ground gives way to the ramp; 0 floors at 0.01. */
   sink: number;
+  /** Film-grain strength; 0 turns grain off. */
   grain: number;
+  /** Grain refresh multiplier (24 steps per second at 1); 0 holds one static grain field. */
   grainAnim: number;
+  /** Triangle-dither amplitude added to every channel to stop gradient banding. */
   dither: number;
+  /** Corner darkening; multiplied by the squared uv distance from the centre. */
   vignette: number;
   /** 1 lets the smoke follow the real pointer; 0 (default) ignores it and a slow virtual pointer sways the smoke. */
   cursor: number;
+  /** Radius (uv) of the pointer trail's gaussian falloff. */
   pointerRadius: number;
+  /** How strongly the pointer's velocity drags the smoke along, through the trail. */
   draft: number;
+  /** How much the pointer trail brightens the density, added as `trail * 0.30 * this`. */
   pointerStrength: number;
+  /** How far the whole field shifts against the pointer, in uv. */
   parallax: number;
+  /** Device-pixel-ratio cap for the canvas; 1 halves the pixel count on a 2x screen and keeps the fill cheap. */
   maxDpr: number;
 };
 
-/** The Horon sky palette for Flue. Recolour through these values only, never the shader. */
+/**
+ * The Horon sky palette for Flue. Recolour through these values only, never the shader.
+ *
+ * It is a complete `FlueConfig`, so it doubles as the base every variant tunes on top of, and its
+ * `cursor: 0` / `maxDpr: 1` keep the default cheap: a still-ish plume at 1x pixel density.
+ */
 export const FLUE_SKY: FlueConfig = {
   bgColor: "#eef3f8",
   colorA: "#e3ecf6",
@@ -77,7 +120,12 @@ export const FLUE_SKY: FlueConfig = {
   maxDpr: 1,
 };
 
-/** The night palette for dark mode: near-black ground and blue smoke. Same motion as `FLUE_SKY`. */
+/**
+ * The night palette for dark mode: near-black ground and blue smoke. Same motion as `FLUE_SKY`.
+ *
+ * Only the five colors and `glow` differ; every other number is inherited, so light and dark read as the
+ * same plume in two lights.
+ */
 export const FLUE_NIGHT: FlueConfig = {
   ...FLUE_SKY,
   bgColor: "#050608",
@@ -91,9 +139,18 @@ export const FLUE_NIGHT: FlueConfig = {
 /** Where the smoke is drawn; each place tunes the motion and colour on top of `FLUE_SKY` / `FLUE_NIGHT`. */
 export type FlueVariant = "default" | "sidebar" | "auth";
 
-type FlueTuning = { light: Partial<FlueConfig>; dark: Partial<FlueConfig>; tint: string };
+/** One variant's overrides: values layered over the base palette per scheme, plus the tint laid on top. */
+type FlueTuning = {
+  /** Overrides applied on top of `FLUE_SKY` in light mode. */
+  light: Partial<FlueConfig>;
+  /** Overrides applied on top of `FLUE_NIGHT` in dark mode. */
+  dark: Partial<FlueConfig>;
+  /** Classes for the tint div over the smoke; `""` adds none, and it yields to `tintClassName`. */
+  tint: string;
+};
 
 /**
+ * - `default`: no motion overrides, under a regular glass tint in light mode and none in dark.
  * - `sidebar`: a narrow, tall column under the sidebar's glass. The glass blurs the detail away, so the smoke
  *   is calmer and larger, kept low in the column so the nav labels at the top sit on the quiet part. The canvas
  *   paints above the sidebar's own fill, so in light mode the variant lays the thick glass (80% white) over the
@@ -188,10 +245,13 @@ function activate(gl: WebGL2RenderingContext, program: WebGLProgram): void {
   gl[USE_PROGRAM](program);
 }
 
+/** Props of {@link FlueBackground}: placement, which variant, and per-instance shader overrides. */
 export type FlueBackgroundProps = {
+  /** Extra classes for the wrapper, which is already `absolute inset-0 -z-10 overflow-hidden`. */
   className?: string;
+  /** Inline styles for the wrapper; `backgroundColor` is set from the resolved `bgColor` before these apply. */
   style?: CSSProperties;
-  /** `sidebar` under the sidebar glass, `auth` behind the sign-in screen, `default` otherwise. */
+  /** `sidebar` under the sidebar glass, `auth` behind the sign-in screen, `default` otherwise. @default "default" */
   variant?: FlueVariant;
   /** Overrides on top of the variant's `FLUE_SKY` (light) or `FLUE_NIGHT` (dark) tuning. */
   config?: Partial<FlueConfig>;
@@ -204,6 +264,30 @@ export type FlueBackgroundProps = {
  * It fills its positioned parent behind the content (the parent needs `isolate`) and falls
  * back to the flat `bgColor` when WebGL2 is missing. Reduced motion draws a single still frame.
  * Light mode paints the white-and-sky `FLUE_SKY`; dark mode paints the black-and-blue `FLUE_NIGHT`.
+ *
+ * The wrapper is `absolute inset-0 -z-10`, `pointer-events-none` and `aria-hidden`, with a tint div over the
+ * canvas, so it never intercepts input and the content above it stays readable. Settings resolve as palette +
+ * variant tuning + `config`; the effect is keyed by their JSON, so changing `config` rebuilds the program.
+ * Drawing pauses while the canvas is off-screen (`IntersectionObserver`) or the tab is hidden, and the
+ * device-pixel ratio is capped by `maxDpr`. `cursor: 0` (the default) swaps the real pointer for a slow
+ * virtual one that wanders on two incommensurate sines, so a pointerless panel still breathes; `cursor: 1`
+ * follows the real pointer. A context lost
+ * by a previous run leaves the flat color instead of throwing, and cleanup frees this run's GL objects
+ * without dropping the shared context.
+ *
+ * @example
+ * ```tsx
+ * import { FlueBackground } from "@horon-ai/react";
+ *
+ * function Sidebar() {
+ *   return (
+ *     <div className="relative isolate min-h-96 overflow-hidden rounded-xl bg-bg-default">
+ *       <FlueBackground variant="sidebar" config={{ speed: 0.5 }} />
+ *       <nav className="relative p-6 text-text-primary">Navigation</nav>
+ *     </div>
+ *   );
+ * }
+ * ```
  */
 export function FlueBackground({ className, style, variant = "default", config, tintClassName }: FlueBackgroundProps) {
   const canvasRef = useRef<HTMLCanvasElement>(null);

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,