@horon-ai/react 0.1.0 → 0.1.2

package/src/{lib → hooks}/use-active-indicator.ts

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

package/src/hooks/use-color-scheme.ts

@@ -0,0 +1,50 @@
+import { useSyncExternalStore } from "react";
+
+/** The two schemes the `.dark` class switch can report. */
+export type ColorScheme = "light" | "dark";
+
+const noop = () => {};
+
+/**
+ * The theme is stored as the `.dark` class on <html> (the site's ThemeToggle
+ * writes it), so that class is the only source — `prefers-color-scheme` is not
+ * consulted.
+ */
+function subscribe(onChange: () => void): () => void {
+  if (typeof document === "undefined" || typeof MutationObserver === "undefined") return noop;
+  const observer = new MutationObserver(onChange);
+  observer.observe(document.documentElement, { attributes: true, attributeFilter: ["class"] });
+  return () => observer.disconnect();
+}
+
+function readIsDark(): boolean {
+  if (typeof document === "undefined") return false;
+  return document.documentElement.classList.contains("dark");
+}
+
+/**
+ * The active color scheme; `light` on the server and before hydration.
+ *
+ * The `.dark` class on <html> is the only source, watched with a `MutationObserver`, so a toggle anywhere on the
+ * page re-renders every caller. `prefers-color-scheme` is deliberately ignored: the theme is an explicit switch,
+ * not an OS follow. A server render reports `light` until the class is read on the client.
+ *
+ * @returns `dark` while the root element carries the `.dark` class, `light` otherwise.
+ *
+ * @example
+ * ```tsx
+ * import { useColorScheme } from "@horon-ai/react";
+ *
+ * function ThemeToggle() {
+ *   const scheme = useColorScheme();
+ *   return (
+ *     <Button variant="ghost" onClick={() => document.documentElement.classList.toggle("dark")}>
+ *       {scheme === "dark" ? "Light" : "Dark"}
+ *     </Button>
+ *   );
+ * }
+ * ```
+ */
+export function useColorScheme(): ColorScheme {
+  return useSyncExternalStore(subscribe, readIsDark, () => false) ? "dark" : "light";
+}

package/src/hooks/use-copy-to-clipboard.ts

@@ -0,0 +1,55 @@
+import { useCallback, useEffect, useState } from "react";
+
+/** What {@link useCopyToClipboard} returns: the transient flag and the write function. */
+export type CopyToClipboard = {
+  /** True from a successful write until `resetMs` has passed; stays false when the write fails. */
+  copied: boolean;
+  /** Writes `text`; a failed write leaves `copied` false instead of throwing. */
+  copy: (text: string) => void;
+};
+
+/**
+ * Clipboard writes with a self-clearing confirmation: `copied` turns true when
+ * the write resolves and back to false after `resetMs`, so a button needs no
+ * timer of its own.
+ *
+ * The write goes through `navigator.clipboard`, so it needs a secure context and a user gesture; where that API
+ * is missing the call is a no-op and `copied` never turns true. The timer is cleared when the component unmounts
+ * or `resetMs` changes.
+ *
+ * @param resetMs - How long `copied` stays true after a successful write, in milliseconds. @default 1500
+ * @returns A {@link CopyToClipboard}: the current `copied` flag and a stable `copy` function.
+ *
+ * @example
+ * ```tsx
+ * import { useCopyToClipboard } from "@horon-ai/react";
+ *
+ * function CopyRow({ value }: { value: string }) {
+ *   const { copied, copy } = useCopyToClipboard();
+ *   return (
+ *     <Button variant="ghost" onClick={() => copy(value)}>
+ *       {copied ? "Copied" : "Copy"}
+ *     </Button>
+ *   );
+ * }
+ * ```
+ */
+export function useCopyToClipboard(resetMs = 1500): CopyToClipboard {
+  const [copied, setCopied] = useState(false);
+
+  useEffect(() => {
+    if (!copied) return undefined;
+    const timer = setTimeout(() => setCopied(false), resetMs);
+    return () => clearTimeout(timer);
+  }, [copied, resetMs]);
+
+  const copy = useCallback((text: string) => {
+    if (typeof navigator === "undefined" || !navigator.clipboard) return;
+    navigator.clipboard.writeText(text).then(
+      () => setCopied(true),
+      () => undefined,
+    );
+  }, []);
+
+  return { copied, copy };
+}

package/src/hooks/use-device.ts

@@ -0,0 +1,69 @@
+import { useMediaQuery } from "./use-media-query";
+
+/** The three layout classes: `mobile` under 768px, `tablet` for a coarse pointer above that, `desktop` otherwise. */
+export type DeviceType = "mobile" | "tablet" | "desktop";
+
+/** The primary input behind the pointer: `touch` for a coarse pointer, `pointer` for a fine one. */
+export type DeviceInput = "touch" | "pointer";
+
+/** What the layout and the key hints need: the device class, the input behind it and whether a key chip can be reached. */
+export type Device = {
+  /** `mobile` below 768px, `tablet` for a coarse pointer above that, `desktop` otherwise. */
+  type: DeviceType;
+  /** `touch` when the pointer is coarse, `pointer` when it is fine. */
+  input: DeviceInput;
+  /** True only for a hovering fine pointer, the input that can actually reach a key chip. */
+  keyboardHints: boolean;
+};
+
+const MOBILE_QUERY = "(max-width: 767px)";
+const COARSE_QUERY = "(pointer: coarse)";
+const HINTS_QUERY = "(hover: hover) and (pointer: fine)";
+
+/**
+ * `useSyncExternalStore` compares snapshots by reference, so each result is
+ * built once and handed out again.
+ */
+const devices = new Map<string, Device>();
+
+function deviceSnapshot(type: DeviceType, input: DeviceInput, keyboardHints: boolean): Device {
+  const key = `${type}:${input}:${keyboardHints}`;
+  const cached = devices.get(key);
+  if (cached) return cached;
+  const next = { type, input, keyboardHints };
+  devices.set(key, next);
+  return next;
+}
+
+/**
+ * The device class and its primary input, as the layout and key hints need them.
+ *
+ * The three queries go through {@link useMediaQuery}, so nothing is read during a server render or the first
+ * hydration pass: that pass reports `desktop` / `pointer` with `keyboardHints` on, the value the query hooks
+ * were given as their server fallback. The returned object is shared, so a re-render with the same device
+ * hands back the same reference.
+ *
+ * @returns The current `Device`: `type`, `input` and `keyboardHints`.
+ *
+ * @example
+ * ```tsx
+ * import { useDevice } from "@horon-ai/react";
+ *
+ * function ComposeFooter() {
+ *   const { type, keyboardHints } = useDevice();
+ *   return (
+ *     <footer className="flex items-center gap-2">
+ *       <span className="text-caption">{type}</span>
+ *       {keyboardHints && <Kbd keys="Mod+Enter" />}
+ *     </footer>
+ *   );
+ * }
+ * ```
+ */
+export function useDevice(): Device {
+  const mobile = useMediaQuery(MOBILE_QUERY);
+  const coarse = useMediaQuery(COARSE_QUERY);
+  const keyboardHints = useMediaQuery(HINTS_QUERY, true);
+  const type: DeviceType = mobile ? "mobile" : coarse ? "tablet" : "desktop";
+  return deviceSnapshot(type, coarse ? "touch" : "pointer", keyboardHints);
+}

package/src/hooks/use-hotkey.ts

@@ -0,0 +1,56 @@
+import { useEffect, useRef } from "react";
+
+import { matchesShortcut } from "../lib/platform";
+import { usePlatform } from "./use-platform";
+
+/** Options of {@link useHotkey}: the only switch is whether the listener is attached. */
+export type HotkeyOptions = {
+  /** When false the listener is detached and the hotkey does nothing (default true). */
+  enabled?: boolean;
+};
+
+/**
+ * Runs `handler` on a `document` keydown that matches `keys`, such as `Mod+K`,
+ * and prevents the browser default. Text inputs keep their focus, so a palette
+ * shortcut still fires mid-typing; the check follows the OS modifier key.
+ *
+ * The listener is attached in an effect, so a server render binds nothing. The handler is held in a ref, so a
+ * caller can pass an inline arrow without re-binding on every render; only `keys`, `enabled` and the OS
+ * re-subscribe. `Mod` follows {@link usePlatform}: ⌘ on macOS and iOS, Ctrl on Windows, Linux and Android,
+ * and either one while the OS is still unknown.
+ *
+ * @param keys - Shortcut string such as `Mod+K`, `Mod+Shift+Enter` or `Escape`, in the same syntax `Kbd` draws.
+ * @param handler - Called with the matching keydown event after `preventDefault()`.
+ * @param options - {@link HotkeyOptions}; `enabled` defaults to `true`.
+ * @returns Nothing; the listener is cleaned up when the component unmounts or `keys`/`enabled` change.
+ *
+ * @example
+ * ```tsx
+ * import { useHotkey } from "@horon-ai/react";
+ *
+ * function PaletteShortcut({ open }: { open: () => void }) {
+ *   useHotkey("Mod+K", open);
+ *   return <Kbd keys="Mod+K" />;
+ * }
+ * ```
+ */
+export function useHotkey(keys: string, handler: (event: KeyboardEvent) => void, options: HotkeyOptions = {}) {
+  const { enabled = true } = options;
+  const platform = usePlatform();
+  const handlerRef = useRef(handler);
+
+  useEffect(() => {
+    handlerRef.current = handler;
+  });
+
+  useEffect(() => {
+    if (!enabled) return undefined;
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (!matchesShortcut(event, keys, platform.os)) return;
+      event.preventDefault();
+      handlerRef.current(event);
+    };
+    document.addEventListener("keydown", onKeyDown);
+    return () => document.removeEventListener("keydown", onKeyDown);
+  }, [keys, enabled, platform.os]);
+}

package/src/hooks/use-media-query.ts

@@ -0,0 +1,43 @@
+import { useCallback, useSyncExternalStore } from "react";
+
+const noop = () => {};
+
+/**
+ * Tracks one `matchMedia` query. The server render and the first client render
+ * use `serverValue`, so static thumbnails and hydration agree before the browser
+ * reports the real state.
+ *
+ * The subscription is rebuilt when `query` changes, and both the server snapshot and the snapshot taken before
+ * `window.matchMedia` exists fall back to `serverValue`. The query string must be a literal the caller keeps
+ * stable across renders, as the cache key is the string itself.
+ *
+ * @param query - A media query such as `(max-width: 767px)` or `(prefers-reduced-motion: reduce)`.
+ * @param serverValue - Result to report while rendering on the server or before `matchMedia` is available. @default false
+ * @returns Whether the query currently matches, or `serverValue` on the server and in the first pass.
+ *
+ * @example
+ * ```tsx
+ * import { useMediaQuery } from "@horon-ai/react";
+ *
+ * function Nav() {
+ *   const compact = useMediaQuery("(max-width: 767px)");
+ *   return compact ? <TabBar items={items} value={tab} onValueChange={setTab} /> : <Sidebar items={items} />;
+ * }
+ * ```
+ */
+export function useMediaQuery(query: string, serverValue = false): boolean {
+  const subscribe = useCallback(
+    (onChange: () => void) => {
+      if (typeof window === "undefined" || typeof window.matchMedia !== "function") return noop;
+      const media = window.matchMedia(query);
+      media.addEventListener("change", onChange);
+      return () => media.removeEventListener("change", onChange);
+    },
+    [query],
+  );
+  const getSnapshot = useCallback(() => {
+    if (typeof window === "undefined" || typeof window.matchMedia !== "function") return serverValue;
+    return window.matchMedia(query).matches;
+  }, [query, serverValue]);
+  return useSyncExternalStore(subscribe, getSnapshot, () => serverValue);
+}

package/src/hooks/use-platform.ts

@@ -0,0 +1,68 @@
+import { useSyncExternalStore } from "react";
+
+import { detectOs, detectRuntime, readNavigator, type Os, type Runtime } from "../lib/platform";
+
+/** Which physical key carries `Mod` on this OS: `meta` is ⌘, `ctrl` is Ctrl. */
+export type ModKey = "meta" | "ctrl";
+
+/** What {@link usePlatform} reports: the OS, the shell the page runs in and the key behind `Mod`. */
+export type Platform = {
+  /** The detected OS, `unknown` on the server and when no hint names one. */
+  os: Os;
+  /** `desktop` inside the Tauri shell or Electron, `web` everywhere else including the server. */
+  runtime: Runtime;
+  /** The physical key behind `Mod` on this OS, ready for a keydown check. */
+  modKey: ModKey;
+};
+
+const noop = () => {};
+
+/** What a server render and the first hydration pass assume. */
+const SERVER_PLATFORM: Platform = { os: "unknown", runtime: "web", modKey: "meta" };
+
+/**
+ * The OS and shell do not change while a tab is open, so the platform is read
+ * once and every later render reuses the same object.
+ */
+let clientPlatform: Platform | null = null;
+
+function readPlatform(): Platform {
+  if (typeof window === "undefined") return SERVER_PLATFORM;
+  if (clientPlatform) return clientPlatform;
+  const os = detectOs(readNavigator());
+  const modKey: ModKey = os === "windows" || os === "linux" || os === "android" ? "ctrl" : "meta";
+  clientPlatform = { os, runtime: detectRuntime(window), modKey };
+  return clientPlatform;
+}
+
+const subscribe = (_onChange: () => void) => noop;
+
+/**
+ * The current OS, browser or desktop shell, and the key that means `Mod`.
+ *
+ * The value is read from `navigator` and `window` and cached for the life of the page: there is no store to
+ * subscribe to, so the hook never re-renders on its own. A server render and the first hydration pass get
+ * `{ os: "unknown", runtime: "web", modKey: "meta" }`, which draws the Mac keys; on the client the first render
+ * already reports the detected platform.
+ *
+ * @returns The current {@link Platform}: `os`, `runtime` and `modKey`.
+ *
+ * @example
+ * ```tsx
+ * import { isModKey, usePlatform } from "@horon-ai/react";
+ *
+ * function Composer({ onStart }: { onStart: () => void }) {
+ *   const { os } = usePlatform();
+ *   return (
+ *     <textarea
+ *       onKeyDown={(event) => {
+ *         if (event.key === "Enter" && isModKey(event, os)) onStart();
+ *       }}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+export function usePlatform(): Platform {
+  return useSyncExternalStore(subscribe, readPlatform, () => SERVER_PLATFORM);
+}

package/src/hooks/use-reduced-motion.ts

@@ -0,0 +1,25 @@
+import { useMediaQuery } from "./use-media-query";
+
+const QUERY = "(prefers-reduced-motion: reduce)";
+
+/**
+ * True while the OS asks for reduced motion; false on the server.
+ *
+ * A thin reading of {@link useMediaQuery} over `(prefers-reduced-motion: reduce)`; the CSS side of the same
+ * preference is handled by the motion utilities in `globals.css`, which collapse their durations.
+ *
+ * @returns Whether the user prefers reduced motion; `false` during a server render and the first pass.
+ *
+ * @example
+ * ```tsx
+ * import { useReducedMotion } from "@horon-ai/react";
+ *
+ * function Stream({ text }: { text: string }) {
+ *   const reducedMotion = useReducedMotion();
+ *   return <StreamingText text={text} smooth={!reducedMotion} />;
+ * }
+ * ```
+ */
+export function useReducedMotion(): boolean {
+  return useMediaQuery(QUERY);
+}

package/src/index.ts

@@ -1,3 +1,34 @@
+/**
+ * Horon Design System for React.
+ *
+ * The package holds the 84 Horon components ported from the Figma `Horon` file. Behaviour and
+ * accessibility come from Base UI (`@base-ui/react`); layout and colour come from Tailwind CSS v4
+ * utilities whose values are the `@horon-ai/tokens` variables, so class names such as `text-label-md`
+ * or `bg-glass-regular` are the design tokens themselves. TypeScript source ships as-is, with no
+ * build output, so the consuming bundler compiles it.
+ *
+ * Import everything from the barrel, or one component from its subpath:
+ *
+ * - `import { Button, Card, Input } from "@horon-ai/react"` re-exports every component and its prop types.
+ * - `import { Button } from "@horon-ai/react/components/button"` resolves to the same source file
+ *   through the `./components/*` export map, which keeps a bundle to the components it uses.
+ * - `import { cn } from "@horon-ai/react"` is the tailwind-merge helper that understands the token
+ *   names, so a caller class overrides a component default.
+ * - `import { mountCursorGhost } ...` / `import "@horon-ai/react/cursor-ghost"` adds the desktop
+ *   cursor trail outside React.
+ * - `import { usePlatform, useDevice, useHotkey } from "@horon-ai/react"` reads the OS, the browser or
+ *   desktop shell and the input device, and binds a `Mod+K`-style shortcut. The hooks are barrel-only,
+ *   with no subpath, and the same `lib/platform` helpers (`formatShortcut`, `matchesShortcut`, `isModKey`)
+ *   are exported so a caller's shortcut draws and matches the keys the components use.
+ *
+ * Import `@horon-ai/react/globals.css` once in the app entry stylesheet: it brings in Tailwind CSS v4,
+ * Pretendard, Geist Mono, the generated token theme and the liquid-glass layer styles. Add an `@source`
+ * line beside it that points at the package `src` folder so Tailwind scans the component sources (see
+ * the README for the exact line). Then set `class="dark"` on an ancestor for the dark palette, and
+ * `data-platform="desktop"` or `data-platform="mobile"` to switch the typography board.
+ *
+ * @packageDocumentation
+ */
 export * from "./components/agent-activity";
 export * from "./components/agent-lane";
 export * from "./components/agent-lanes-timeline";
@@ -82,5 +113,18 @@ export * from "./components/tooltip";
 export * from "./components/top-bar";
 export * from "./components/usage-meter";
 export * from "./components/workspace-menu";
+export * from "./hooks";
 export { cn, type ClassValue } from "./lib/cn";
 export { mountCursorGhost, type CursorGhostOptions } from "./lib/cursor-ghost";
+export {
+  detectOs,
+  detectRuntime,
+  formatShortcut,
+  isModKey,
+  matchesShortcut,
+  type Os,
+  type PlatformInput,
+  type Runtime,
+  type RuntimeWindow,
+  type ShortcutEvent,
+} from "./lib/platform";

package/src/lib/cn.ts

@@ -1,6 +1,10 @@
 import { lightColors, primitives, radius, shadow, textStyles } from "@horon-ai/tokens";
 import { extendTailwindMerge } from "tailwind-merge";
 
+/**
+ * One class-name argument accepted by {@link cn}: a class string, or a falsy value that is skipped.
+ * `false`, `null` and `undefined` are common when a class is applied conditionally.
+ */
 export type ClassValue = string | false | null | undefined;
 
 /**
@@ -19,7 +23,15 @@ const merge = extendTailwindMerge({
   },
 });
 
-/** Joins class names, skipping empty values; later classes win over conflicting earlier ones. */
+/**
+ * Joins class names, skipping empty values; later classes win over conflicting earlier ones.
+ *
+ * Use it in every component so a caller's class overrides the component default instead of
+ * duplicating it; the merge is extended with the Horon token names.
+ *
+ * @param values - Any number of class strings or falsy values, applied left to right.
+ * @returns One space-separated class string with conflicting utilities collapsed.
+ */
 export function cn(...values: ClassValue[]): string {
   return merge(values.filter(Boolean).join(" "));
 }

package/src/lib/cursor-ghost.ts

@@ -12,15 +12,15 @@
  */
 
 export type CursorGhostOptions = {
-  /** Number of arrow copies. */
+  /** Number of arrow copies. @default 5 */
   ghosts?: number;
-  /** Arrow height in CSS px. */
+  /** Arrow height in CSS px. @default 26 */
   size?: number;
-  /** Lerp factor of the first copy toward the pointer, per frame. */
+  /** Lerp factor of the first copy toward the pointer, per frame. @default 0.16 */
   headFollow?: number;
-  /** Blur spread of the last copy in CSS px. */
+  /** Blur spread of the last copy in CSS px. @default 14 */
   smear?: number;
-  /** Arrow fill. Blended with `difference`, so white reads dark on light pages. */
+  /** Arrow fill. Blended with `difference`, so white reads dark on light pages. @default "#FFFFFF" */
   color?: string;
 };
 
@@ -195,6 +195,13 @@ function startEffect({ ghosts, size, headFollow, smear, color }: Required<Cursor
 /**
  * Mounts the Cursor Ghost trail and returns its teardown. The trail appears and
  * disappears on its own as the pointer type or the reduced-motion setting changes.
+ *
+ * Safe to call during server rendering: without a `window`, `document` or `matchMedia`
+ * it returns a no-op teardown. Call it after `<html data-horon-cursor="off">` is set when
+ * you want both the automatic mount suppressed and custom options.
+ *
+ * @param options - Overrides for the trail; omitted keys fall back to the built-in defaults.
+ * @returns A teardown that removes the layer, its listeners and any pending animation frame.
  */
 export function mountCursorGhost(options: CursorGhostOptions = {}): () => void {
   if (typeof window === "undefined" || typeof document === "undefined" || !window.matchMedia) return () => {};
@@ -234,7 +241,10 @@ export function mountCursorGhost(options: CursorGhostOptions = {}): () => void {
 
 function autoMount() {
   if (typeof window === "undefined" || typeof document === "undefined") return;
-  const registry = globalThis as typeof globalThis & { [AUTO_MOUNT_KEY]?: true };
+  const registry = globalThis as typeof globalThis & {
+    /** Set once the automatic mount has run, so a second import does not add another trail. */
+    [AUTO_MOUNT_KEY]?: true;
+  };
   if (registry[AUTO_MOUNT_KEY]) return;
   if (document.documentElement.getAttribute(OPT_OUT_ATTRIBUTE) === "off") return;
   registry[AUTO_MOUNT_KEY] = true;