@horon-ai/react 0.1.0 → 0.1.2

package/src/components/research-run-panel.tsx

@@ -5,42 +5,112 @@ import { cn } from "../lib/cn";
 import { ChatBubble } from "./chat-bubble";
 import { Spinner } from "./spinner";
 
+/**
+ * One query row in the list under the status line.
+ */
 export type ResearchQuery = {
+  /** Stable key for the row. */
   id: string;
-  /** `searching` shows a spinner and the muted text; `done` a check. */
+  /**
+   * `searching` shows a spinner and the muted text; `done` a check. Anything else (omitted, and
+   * any other value) renders as `done`.
+   * @default "done"
+   */
   state?: "done" | "searching";
+  /** The query text, truncated with an ellipsis when the row runs out of width. */
   text: ReactNode;
   /** Result count shown at the end of the row, such as "8 results". */
   results?: ReactNode;
 };
 
+/**
+ * Props for {@link ResearchRunPanel}. Extra `section` props (`id`, `data-*`, handlers) land on the
+ * outer panel element.
+ */
 export type ResearchRunPanelProps = Omit<ComponentProps<"section">, "title"> & {
+  /**
+   * Header title next to the magnifying glass.
+   * @default "Research"
+   */
   title?: ReactNode;
+  /**
+   * Text of the header button that starts a new run.
+   * @default "New research"
+   */
   newLabel?: ReactNode;
+  /** Fires when the header button is clicked; the button is still rendered without it. */
   onNewResearch?: () => void;
   /** The question bubble, right-aligned. */
   question: ReactNode;
-  /** Shows the spinner, status line and caret while the run works. */
+  /**
+   * Shows the spinner, status line and caret while the run works; when false the status block
+   * collapses and the submit button becomes a send arrow.
+   * @default true
+   */
   running?: boolean;
+  /**
+   * Label in front of the caret in the status line.
+   * @default "Researching"
+   */
   statusLabel?: ReactNode;
+  /** First meta value after the status label, such as "12s"; joins `read`/`total` with a middot. */
   elapsed?: ReactNode;
+  /** Pages read so far; with `total` it renders "N of M read" and drives the sources pill label. */
   read?: number;
+  /** Pages in the run; must be set together with `read` for the count to appear. */
   total?: number;
+  /** Queries resolved so far, drawn under a 1.5px rail with a 30ms stagger per row. */
   queries?: ResearchQuery[];
   /** Initials for the stacked source avatars under the queries. */
   sources?: string[];
+  /** Fires from the round button while `running`, which then shows a stop glyph instead of an arrow. */
   onStop?: () => void;
   /** Makes the sources pill actionable; without it the pill is a plain label. */
   onOpenSources?: () => void;
   /** Makes the running status line expandable; without it the row carries no caret. */
   onToggleStatus?: () => void;
+  /**
+   * Placeholder and accessible name of the follow-up input.
+   * @default "Ask a follow-up"
+   */
   followUpPlaceholder?: string;
+  /** Fires with the raw input value on submit; the field is cleared afterwards. */
   onFollowUp?: (value: string) => void;
 };
 
 const stagger = (index: number) => ({ "--i": index, animationDelay: `calc(var(--i) * 30ms)` }) as CSSProperties;
 
-/** Paper `Research run` (Agents N10): a 24px-radius panel with a header, the question, a live status line and the queries read so far. */
+/**
+ * Paper `Research run` (Agents N10): a 24px-radius panel with a header, the question, a live status line and the queries read so far.
+ *
+ * The panel is presentational: it holds no run state of its own. Submitted follow-ups are handed
+ * to `onFollowUp` and the input is cleared, so the caller appends the new question. While
+ * `running` the status line is announced politely and the round button stops the run instead of
+ * submitting.
+ *
+ * @example
+ * ```tsx
+ * import { ResearchRunPanel } from "@horon-ai/react";
+ *
+ * function Example() {
+ *   return (
+ *     <ResearchRunPanel
+ *       question="What changed in the EU AI Act this year?"
+ *       statusLabel="Reading sources"
+ *       read={4}
+ *       total={12}
+ *       queries={[
+ *         { id: "1", text: "EU AI Act amendments", results: "8 results" },
+ *         { id: "2", text: "Enforcement timeline", state: "searching" },
+ *       ]}
+ *       sources={["EU", "CE"]}
+ *       onStop={() => {}}
+ *       onFollowUp={(value) => console.log(value)}
+ *     />
+ *   );
+ * }
+ * ```
+ */
 export function ResearchRunPanel({
   title = "Research",
   newLabel = "New research",

package/src/components/schedule.tsx

@@ -8,23 +8,46 @@ import { cn } from "../lib/cn";
 import type { ControlSize } from "../lib/size";
 import { LiquidGlass } from "./liquid-glass";
 
+/**
+ * Field size of a picker, on the shared control scale: `sm` 32px, `md` 40px, `lg` 48px.
+ */
 export type PickerFieldSize = ControlSize;
 
+/**
+ * Props for {@link PickerField}. The type is closed: it declares no `disabled` or `name` (and no
+ * other Base UI `Select.Root` prop), so TypeScript rejects them before they reach the root; `items`
+ * is the label list the trigger reads.
+ */
 export type PickerFieldProps = {
-  items: { value: string; label: ReactNode }[];
+  /** Choices in the popup; `value` is what `onValueChange` returns, `label` is what the row and trigger show. */
+  items: {
+    /** Value reported when the item is picked. */
+    value: string;
+    /** Text shown on the trigger and in the popup row. */
+    label: ReactNode;
+  }[];
+  /** Selected value in controlled mode. */
   value?: string;
+  /** Starting value in uncontrolled mode. */
   defaultValue?: string;
+  /** Fires with the newly selected value, or `null` when the choice is cleared, after a pick. */
   onValueChange?: (value: string | null) => void;
-  /** Leading 16px icon; the Time field uses a clock. */
+  /** Leading icon, 16px on `sm` and `md` and 20px on `lg`; the Time field uses a clock. */
   icon?: ReactNode;
   /**
    * `solid` (default) is the opaque surface field with a default border, `glass` the veil field,
    * `inset` the 4% ink field inside the schedule card.
+   * @default "solid"
    */
   surface?: "solid" | "glass" | "inset";
-  /** Field size: `sm` 32px, `md` 40px (default), `lg` 48px; scales width, icon and menu rows. */
+  /**
+   * Field size: `sm` 32px, `md` 40px (default), `lg` 48px; scales width, icon and menu rows.
+   * @default "md"
+   */
   size?: PickerFieldSize;
+  /** Accessible name of the trigger when no visible label is associated with it. */
   "aria-label"?: string;
+  /** Classes merged onto the trigger. */
   className?: string;
 };
 
@@ -73,7 +96,34 @@ const itemIndicatorSizeClass: Record<PickerFieldSize, string> = {
   lg: "[&_svg]:size-5",
 };
 
-/** Figma `Time field` (Routine schedule 110:765): a 160px picker on the same 32/40/48px and 14/16/18 text rungs as `Input`. */
+/**
+ * Figma `Time field` (Routine schedule 110:765): a 160px picker on the same 32/40/48px and 14/16/18 text rungs as `Input`.
+ *
+ * The popup is portalled to the body and aligned under the trigger with an 8px offset, so it can
+ * escape a scrolling card; the caret rotates while it is open. The field never grows past its
+ * rung width but shrinks with a narrow parent.
+ *
+ * @example
+ * ```tsx
+ * import { useState } from "react";
+ * import { PickerField } from "@horon-ai/react";
+ *
+ * function Example() {
+ *   const [time, setTime] = useState("09:00");
+ *   return (
+ *     <PickerField
+ *       aria-label="Start time"
+ *       value={time}
+ *       onValueChange={(next) => setTime(next ?? time)}
+ *       items={[
+ *         { value: "09:00", label: "9:00 AM" },
+ *         { value: "10:00", label: "10:00 AM" },
+ *       ]}
+ *     />
+ *   );
+ * }
+ * ```
+ */
 export function PickerField({
   items,
   icon,
@@ -145,17 +195,39 @@ export function PickerField({
   );
 }
 
+/**
+ * Day circle size: `sm` 32px, `md` 36px, `lg` 44px.
+ */
 export type WeekdayPickerSize = ControlSize;
 
+/**
+ * Props for {@link WeekdayPicker}. It is a multiple-selection toggle group, so `value` and
+ * `onValueChange` carry an array of day values.
+ */
 export type WeekdayPickerProps = {
   /** One entry per day, in display order. */
-  days: { value: string; label: string; name: string }[];
+  days: {
+    /** Value that goes into `value` and `onValueChange`. */
+    value: string;
+    /** Short text on the circle, such as "M". */
+    label: string;
+    /** Accessible name of the toggle, such as "Monday". */
+    name: string;
+  }[];
+  /** Selected day values in controlled mode. */
   value?: string[];
+  /** Selected day values at first render in uncontrolled mode. */
   defaultValue?: string[];
+  /** Fires with the complete next selection whenever a day is toggled on or off. */
   onValueChange?: (value: string[]) => void;
-  /** Day circle size: `sm` 32px, `md` 36px (default), `lg` 44px. */
+  /**
+   * Day circle size: `sm` 32px, `md` 36px (default), `lg` 44px.
+   * @default "md"
+   */
   size?: WeekdayPickerSize;
+  /** Accessible name of the group. */
   "aria-label"?: string;
+  /** Classes merged onto the wrapping flex row. */
   className?: string;
 };
 
@@ -172,7 +244,32 @@ const weekdayToggleSizeClass: Record<WeekdayPickerSize, string> = {
   lg: "size-11 text-label-lg",
 };
 
-/** Figma `Weekday picker` (110:765): 36px round toggles, ink when on and 6% ink when off. */
+/**
+ * Figma `Weekday picker` (110:765): 36px round toggles, ink when on and 6% ink when off.
+ *
+ * Toggling one day does not close the group; each press reports the whole next selection. The
+ * group wraps instead of shrinking its circles, so touch targets stay at least 32px. It is
+ * multiple-selection, so several days can be on at once.
+ *
+ * @example
+ * ```tsx
+ * import { WeekdayPicker } from "@horon-ai/react";
+ *
+ * function Example() {
+ *   return (
+ *     <WeekdayPicker
+ *       aria-label="Repeat on"
+ *       defaultValue={["mon", "wed", "fri"]}
+ *       days={[
+ *         { value: "mon", label: "M", name: "Monday" },
+ *         { value: "tue", label: "T", name: "Tuesday" },
+ *         { value: "wed", label: "W", name: "Wednesday" },
+ *       ]}
+ *     />
+ *   );
+ * }
+ * ```
+ */
 export function WeekdayPicker({
   days,
   value,
@@ -210,15 +307,28 @@ export function WeekdayPicker({
   );
 }
 
+/**
+ * Props for {@link ScheduleCard}. The card is a plain section: it lays out what you pass and
+ * draws the frame, header and next-run strip around it.
+ */
 export type ScheduleCardProps = {
+  /** Header title next to the repeat icon. */
   title: ReactNode;
-  /** The "Next run" line at the bottom. */
+  /** The "Next run" line at the bottom; without it the strip is not rendered. */
   nextRun?: ReactNode;
+  /** Body of the card, usually a stack of `ScheduleSection` blocks and pickers. */
   children: ReactNode;
-  /** Card size: `sm` 340px, `md` 380px (default), `lg` 420px; scales padding, gaps and text. */
+  /**
+   * Card size: `sm` 340px, `md` 380px (default), `lg` 420px; scales padding, gaps and text.
+   * @default "md"
+   */
   size?: ControlSize;
-  /** `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;
 };
 
@@ -259,7 +369,37 @@ const nextRunIconSizeClass: Record<ControlSize, string> = {
   lg: "size-5",
 };
 
-/** Figma `Routine schedule card` (110:765): a 380px card, 20px padding, 16px gaps, solid or thick glass. */
+/**
+ * Figma `Routine schedule card` (110:765): a 380px card, 20px padding, 16px gaps, solid or thick glass.
+ *
+ * Compose it from `ScheduleSection` blocks holding `WeekdayPicker`, `PickerField` or `Input`
+ * controls. On a narrow column the card folds to the available width instead of overflowing.
+ *
+ * @example
+ * ```tsx
+ * import { PickerField, ScheduleCard, ScheduleSection, WeekdayPicker } from "@horon-ai/react";
+ *
+ * function Example() {
+ *   return (
+ *     <ScheduleCard title="Morning digest" nextRun="Next run tomorrow at 9:00 AM">
+ *       <ScheduleSection label="Repeat">
+ *         <PickerField
+ *           aria-label="Repeat"
+ *           surface="inset"
+ *           items={[
+ *             { value: "daily", label: "Daily" },
+ *             { value: "weekly", label: "Weekly" },
+ *           ]}
+ *         />
+ *       </ScheduleSection>
+ *       <ScheduleSection label="Days">
+ *         <WeekdayPicker days={[{ value: "mon", label: "M", name: "Monday" }]} />
+ *       </ScheduleSection>
+ *     </ScheduleCard>
+ *   );
+ * }
+ * ```
+ */
 export function ScheduleCard({
   title,
   nextRun,
@@ -298,7 +438,7 @@ export function ScheduleCard({
   );
 }
 
-/** A captioned block inside the schedule card, such as "Repeat" or "Days"; the caption-to-control gap is `Field`'s. */
+/** Vertical gap between a section's caption and its control, per size. */
 const sectionSizeClass: Record<ControlSize, string> = {
   sm: "gap-1",
   md: "gap-2",
@@ -311,6 +451,10 @@ const sectionLabelSizeClass: Record<ControlSize, string> = {
   lg: "text-label-sm",
 };
 
+/**
+ * A captioned block inside the schedule card, such as "Repeat" or "Days". Renders the caption in
+ * secondary text above its children, so a card body becomes a stack of labelled controls.
+ */
 export function ScheduleSection({
   label,
   children,
@@ -318,9 +462,16 @@ export function ScheduleSection({
   size = "md",
   className,
 }: {
+  /** Caption above the control, in secondary text. */
   label: ReactNode;
+  /** The control the caption belongs to. */
   children: ReactNode;
+  /**
+   * Matches the size of the controls inside the section; scales the caption rung and the caption gap.
+   * @default "md"
+   */
   size?: ControlSize;
+  /** Classes merged onto the block. */
   className?: string;
 }) {
   return (

package/src/components/segmented-control.tsx

@@ -4,23 +4,48 @@ import { type ReactNode, useRef } from "react";
 
 import { cn } from "../lib/cn";
 import type { ControlSize } from "../lib/size";
-import { useActiveIndicator } from "../lib/use-active-indicator";
+import { useActiveIndicator } from "../hooks/use-active-indicator";
 import { LiquidGlass } from "./liquid-glass";
 
 /** `tab` keeps Paper's page-tab rung beside the three control sizes. */
 export type SegmentedControlSize = ControlSize | "tab";
+
+/**
+ * Track treatment of a segmented control.
+ *
+ * - `solid` — opaque surface track with a default border and a 10% ink selection.
+ * - `glass` — regular glass; the selection is a thick glass pill over it.
+ * - `inset` — 5% ink track, for use inside a routine card.
+ * - `inset-faint` — 4% ink track, for the header filter row.
+ * - `subtle` — `bg-subtle` page-tab tray whose selection is a plain surface pill.
+ */
 export type SegmentedControlSurface = "solid" | "glass" | "inset" | "inset-faint" | "subtle";
 
+/**
+ * Props for {@link SegmentedControl}. The control is single-choice: only one item value is selected.
+ */
 export type SegmentedControlProps = {
-  items: { value: string; label: ReactNode; disabled?: boolean }[];
+  /** Segments in display order; `value` is what `onValueChange` returns and `disabled` dims one segment. */
+  items: {
+    /** Value reported when this segment is chosen. */
+    value: string;
+    /** Text on the segment. */
+    label: ReactNode;
+    /** Disables only this segment; it cannot be selected or focused. */
+    disabled?: boolean;
+  }[];
+  /** Selected value in controlled mode. */
   value?: string;
+  /** Selected value at first render in uncontrolled mode. */
   defaultValue?: string;
+  /** Fires with the chosen value when the selection changes. */
   onValueChange?: (value: string) => void;
   /**
    * `md`: Segmented control (62:379), 36px track, 30px segments, 16px padding.
    * `sm`: one rung down, a 32px track with 26px segments and 10px padding.
    * `lg`: Segmented filter (88:723), 44px track, 36px segments.
    * `tab`: Paper page tabs (Projects Active/Archived), 4px track padding and gap, 32px segments with 14px padding.
+   * @default "md"
    */
   size?: SegmentedControlSize;
   /**
@@ -28,11 +53,17 @@ export type SegmentedControlProps = {
    * `glass` is regular glass. `inset` is the 5% ink track inside the routine card,
    * `inset-faint` the 4% ink track inside the header filter. `subtle` is the bg-subtle page-tab tray whose
    * selection is a plain white pill.
+   * @default "solid"
    */
   surface?: SegmentedControlSurface;
-  /** Segments share the width equally instead of hugging their labels. */
+  /**
+   * Segments share the width equally instead of hugging their labels.
+   * @default size === "md"
+   */
   fill?: boolean;
+  /** Accessible name of the toggle group. */
   "aria-label"?: string;
+  /** Classes merged onto the track. */
   className?: string;
 };
 
@@ -64,6 +95,30 @@ const surfaceClass: Record<SegmentedControlSurface, string> = {
  * thick fill and a 0 1 3 8% shadow, the iOS tab bar selection; dark mode keeps a
  * 10% fill. On the solid and inset tracks it is 10% ink. The pill is the same on
  * every rung, as in `Tabs`.
+ *
+ * The track scrolls horizontally when the segments do not fit, so a long label set never spills.
+ * Pass `aria-label` because the track has no visible name of its own.
+ *
+ * @example
+ * ```tsx
+ * import { useState } from "react";
+ * import { SegmentedControl } from "@horon-ai/react";
+ *
+ * function Example() {
+ *   const [view, setView] = useState("active");
+ *   return (
+ *     <SegmentedControl
+ *       aria-label="Projects"
+ *       value={view}
+ *       onValueChange={setView}
+ *       items={[
+ *         { value: "active", label: "Active" },
+ *         { value: "archived", label: "Archived" },
+ *       ]}
+ *     />
+ *   );
+ * }
+ * ```
  */
 export function SegmentedControl({
   items,

package/src/components/select.tsx

@@ -7,28 +7,65 @@ import type { ControlSize } from "../lib/size";
 import { fieldBoxClass, fieldSizeClass, fieldTextClass, type InputSurface } from "./input";
 import { inputGroupSegmentClass, useInputGroup } from "./input-group";
 
+/** Field height and text rung of a `field` select: 32/40/48px with 14/16/18px text. */
 export type SelectSize = ControlSize;
+
+/**
+ * One choice in the list.
+ */
 export type SelectItemData = {
+  /** Value reported on selection. */
   value: string;
+  /** Text shown both in the trigger and in the popup row. */
   label: ReactNode;
   /** Shorter text for the trigger once chosen, such as `+82` for "+82 South Korea". */
   selectedLabel?: ReactNode;
+  /** Dims the row and blocks picking it. */
   disabled?: boolean;
 };
 
+/**
+ * Props for {@link Select}. Selection props (`value`, `defaultValue`, `onValueChange`, `name`) pass
+ * through to Base UI's select root.
+ */
 export type SelectProps = Omit<ComponentProps<typeof BaseSelect.Root>, "items" | "children"> & {
+  /** Choices in the popup, in display order. */
   items: SelectItemData[];
+  /**
+   * Text shown in the trigger before a choice is made.
+   * @default "Select"
+   */
   placeholder?: ReactNode;
+  /**
+   * Field height and text rung for `variant="field"`; a `chip` trigger keeps its fixed 32px,
+   * `label-md` size and still uses `size` for its popup rows, and a `segment` takes the enclosing
+   * `InputGroup` size instead.
+   * @default "md"
+   */
   size?: SelectSize;
+  /**
+   * Fill of the field and of its popup; `glass` also switches the popup to the veil. A `chip` uses
+   * it for the popup only, since the chip has its own subtle fill.
+   * @default "solid"
+   */
   surface?: InputSurface;
+  /** Paints the danger border and sets `aria-invalid` on the trigger. */
   invalid?: boolean;
   /**
    * `chip` is the Paper filter chip: a 32px bg-subtle pill, 12px padding, 13/18 medium, sized to its label.
    * `segment` is the tinted prefix or suffix of an `InputGroup`; it takes the group's size and disabled state.
+   * @default "field"
    */
   variant?: "field" | "chip" | "segment";
+  /**
+   * Draws the caret at the right of the trigger; set it to false when the trigger supplies its own
+   * icon.
+   * @default true
+   */
   showIndicator?: boolean;
+  /** Classes merged onto the trigger. */
   className?: string;
+  /** Accessible name of the trigger. */
   "aria-label"?: string;
 };
 
@@ -53,6 +90,29 @@ const triggerFocusClass = "focus-visible:outline-2 focus-visible:outline-offset-
  * text size. The popup is the veil (`veil-overlay`), 20px radius, 40px rows; the chosen row
  * is 6% ink with a check. `variant="chip"` keeps its single 32px chip size;
  * `variant="segment"` follows its `InputGroup`.
+ *
+ * The popup is portalled and positioned under the trigger; rows are highlighted with the keyboard
+ * and marked with a check when chosen. The trigger is a button, not a native `select`, so give it an
+ * `aria-label` or associate a visible label yourself; a wrapping `<label>` does not name it.
+ *
+ * @example
+ * ```tsx
+ * import { Select } from "@horon-ai/react";
+ *
+ * function Example() {
+ *   return (
+ *     <Select
+ *       aria-label="Country"
+ *       defaultValue="kr"
+ *       items={[
+ *         { value: "kr", label: "South Korea", selectedLabel: "+82" },
+ *         { value: "jp", label: "Japan", selectedLabel: "+81" },
+ *         { value: "us", label: "United States", disabled: true },
+ *       ]}
+ *     />
+ *   );
+ * }
+ * ```
  */
 export function Select({
   items,