@nibapp/ui 0.0.0-stage → 0.1.0

package/dist/lib/use-delayed-loading.js

@@ -0,0 +1,31 @@
+"use client";
+import { DURATIONS } from "../_bundled/tokens/index.js";
+import { useEffect, useRef, useState } from "react";
+/**
+ * Turns a raw `loading` flag into a flicker-free one: fast operations never flash a loader, and a
+ * loader that does appear stays long enough to read as intentional (Vercel's 150–300 / 300–500 ms rule).
+ */
+export function useDelayedLoading(loading, { delay = DURATIONS.loaderDelay, minVisible = DURATIONS.loaderMin } = {}) {
+    const [visible, setVisible] = useState(false);
+    const shownAt = useRef(null);
+    useEffect(() => {
+        if (loading) {
+            if (visible)
+                return undefined;
+            const id = setTimeout(() => {
+                shownAt.current = Date.now();
+                setVisible(true);
+            }, delay);
+            return () => clearTimeout(id);
+        }
+        if (!visible)
+            return undefined;
+        const elapsed = Date.now() - (shownAt.current ?? 0);
+        const id = setTimeout(() => {
+            shownAt.current = null;
+            setVisible(false);
+        }, Math.max(0, minVisible - elapsed));
+        return () => clearTimeout(id);
+    }, [loading, visible, delay, minVisible]);
+    return visible;
+}

package/dist/lib/use-file-picker.d.ts

@@ -0,0 +1,26 @@
+import { type ReactElement } from "react";
+declare module "react" {
+    interface InputHTMLAttributes<T> {
+        /** The folder picker every browser engine has, missing from React's types. */
+        webkitdirectory?: string;
+    }
+}
+export interface FilePickerOptions {
+    /** File types the picker offers (`"image/png,image/jpeg"`); every type when absent. */
+    readonly accept?: string | undefined;
+    /**
+     * What the person picks: one file (the default), several, or a folder — every file under it, each
+     * with its `webkitRelativePath`.
+     */
+    readonly select?: "one" | "many" | "folder" | undefined;
+}
+/**
+ * The system's file picker on demand: render `input` once anywhere in the component and call `pick()`
+ * from a button or menu item (the press is the activation a browser asks for). `pick()` resolves with
+ * what the person picked, or with no files when they cancel. The input is cleared after each pick, so
+ * picking the same file or folder again is a new pick.
+ */
+export declare function useFilePicker({ accept, select }?: FilePickerOptions): {
+    readonly pick: () => Promise<readonly File[]>;
+    readonly input: ReactElement;
+};

package/dist/lib/use-file-picker.js

@@ -0,0 +1,43 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useRef } from "react";
+/** The input's answer to one pick: the files, or none when the person cancels. */
+function answerOf(element, signal) {
+    return new Promise((resolve) => {
+        signal.addEventListener("abort", () => resolve([]), { once: true });
+        // On the element itself, so the answer arrives even when the component is gone by then.
+        element.addEventListener("change", () => {
+            const files = [...(element.files ?? [])];
+            element.value = "";
+            resolve(files);
+        }, { signal });
+        element.addEventListener("cancel", () => resolve([]), { signal });
+    });
+}
+/**
+ * The system's file picker on demand: render `input` once anywhere in the component and call `pick()`
+ * from a button or menu item (the press is the activation a browser asks for). `pick()` resolves with
+ * what the person picked, or with no files when they cancel. The input is cleared after each pick, so
+ * picking the same file or folder again is a new pick.
+ */
+export function useFilePicker({ accept, select = "one" } = {}) {
+    const ref = useRef(null);
+    const waiting = useRef(null);
+    const input = (_jsx("input", { ref: ref, type: "file", hidden: true, accept: accept, multiple: select !== "one", ...(select === "folder" ? { webkitdirectory: "" } : {}) }));
+    const pick = async () => {
+        const element = ref.current;
+        if (element === null)
+            return [];
+        // A pick still waiting (an engine that never says `cancel`) ends as a cancel, so each answer goes
+        // to the latest pick alone.
+        waiting.current?.abort();
+        const controller = new AbortController();
+        waiting.current = controller;
+        const answer = answerOf(element, controller.signal);
+        element.click();
+        const files = await answer;
+        controller.abort();
+        return files;
+    };
+    return { pick, input };
+}

package/dist/lib/use-hydrated.d.ts

@@ -0,0 +1,6 @@
+/**
+ * False on the server and during hydration, true once the client has taken over. Gate any render
+ * difference that comes from client-only state (e.g. `prefers-reduced-motion`) behind it so the
+ * first client render matches the server HTML.
+ */
+export declare function useHydrated(): boolean;

package/dist/lib/use-hydrated.js

@@ -0,0 +1,11 @@
+"use client";
+import { useSyncExternalStore } from "react";
+const subscribe = () => () => { };
+/**
+ * False on the server and during hydration, true once the client has taken over. Gate any render
+ * difference that comes from client-only state (e.g. `prefers-reduced-motion`) behind it so the
+ * first client render matches the server HTML.
+ */
+export function useHydrated() {
+    return useSyncExternalStore(subscribe, () => true, () => false);
+}

package/dist/lib/use-latest.d.ts

@@ -0,0 +1,12 @@
+import { type RefObject } from "react";
+/**
+ * A ref that holds `value` as of the last commit, for effects, timers and stable callbacks that must
+ * read the newest props without re-running. It's written after commit (a layout effect), never during
+ * render: a render React throws away can't leak into it. Don't read it while rendering.
+ */
+export declare function useLatest<T>(value: T): RefObject<T>;
+/**
+ * A callback with a stable identity that always runs the latest `fn` (for memoized children). Like
+ * `useLatest`, it reads what the last commit saw: call it from events and effects, never while rendering.
+ */
+export declare function useStableCallback<A extends unknown[], R>(fn: (...args: A) => R): (...args: A) => R;

package/dist/lib/use-latest.js

@@ -0,0 +1,22 @@
+"use client";
+import { useCallback, useLayoutEffect, useRef } from "react";
+/**
+ * A ref that holds `value` as of the last commit, for effects, timers and stable callbacks that must
+ * read the newest props without re-running. It's written after commit (a layout effect), never during
+ * render: a render React throws away can't leak into it. Don't read it while rendering.
+ */
+export function useLatest(value) {
+    const ref = useRef(value);
+    useLayoutEffect(() => {
+        ref.current = value;
+    });
+    return ref;
+}
+/**
+ * A callback with a stable identity that always runs the latest `fn` (for memoized children). Like
+ * `useLatest`, it reads what the last commit saw: call it from events and effects, never while rendering.
+ */
+export function useStableCallback(fn) {
+    const latest = useLatest(fn);
+    return useCallback((...args) => latest.current(...args), []);
+}

package/dist/lib/use-resolved-theme.d.ts

@@ -0,0 +1,12 @@
+import { type RefObject } from "react";
+import type { ResolvedTheme } from "./theme.js";
+/**
+ * The theme an element is painted in: its nearest `data-theme` (written on <html> by
+ * <ThemeProvider> and `themeInitScript`, or on any subtree that forces one), without requiring the
+ * provider. For art with a separate file per theme, so only that file loads.
+ *
+ * `undefined` until the element is mounted: the server can't know the theme, and asset URLs from
+ * `new URL(…, import.meta.url)` only resolve in the client bundle. It's set in a layout effect, so
+ * client-rendered art never paints without it.
+ */
+export declare function useResolvedTheme(ref: RefObject<Element | null>): ResolvedTheme | undefined;

package/dist/lib/use-resolved-theme.js

@@ -0,0 +1,25 @@
+"use client";
+import { useLayoutEffect, useState } from "react";
+const SELECTOR = "[data-theme]";
+const resolve = (el) => el?.getAttribute("data-theme") === "dark" ? "dark" : "light";
+/**
+ * The theme an element is painted in: its nearest `data-theme` (written on <html> by
+ * <ThemeProvider> and `themeInitScript`, or on any subtree that forces one), without requiring the
+ * provider. For art with a separate file per theme, so only that file loads.
+ *
+ * `undefined` until the element is mounted: the server can't know the theme, and asset URLs from
+ * `new URL(…, import.meta.url)` only resolve in the client bundle. It's set in a layout effect, so
+ * client-rendered art never paints without it.
+ */
+export function useResolvedTheme(ref) {
+    const [theme, setTheme] = useState();
+    useLayoutEffect(() => {
+        const host = ref.current?.closest(SELECTOR) ?? document.documentElement;
+        const update = () => setTheme(resolve(host));
+        update();
+        const observer = new MutationObserver(update);
+        observer.observe(host, { attributes: true, attributeFilter: ["data-theme"] });
+        return () => observer.disconnect();
+    }, [ref]);
+    return theme;
+}

package/dist/styles/base.css

@@ -0,0 +1,393 @@
+/* Base layer, variants, keyframes and bespoke utilities for @nibapp/ui. */
+
+/* `dark:` follows the resolved theme attribute set by <ThemeProvider> (or any subtree). */
+@custom-variant dark (&:where([data-theme="dark"], [data-theme="dark"] *));
+
+@theme {
+  /* Room for macOS's traffic lights in an overlay title bar (inset at x 18, 70 px wide): what follows
+     them starts 18 px after, as they start 18 px in (`pl-traffic-lights`). */
+  --spacing-traffic-lights: 88px;
+  --animate-spin: spin 0.9s linear infinite;
+  --animate-shimmer: nib-shimmer 2.2s var(--ease-in-out) infinite;
+  --animate-sheen: nib-sheen 1.8s linear infinite;
+  --animate-pulse-soft: nib-pulse-soft 1.6s var(--ease-in-out) infinite;
+  --animate-caret: nib-caret 1.1s steps(1, end) infinite;
+  /* Server-rendered entrances: CSS, so the content paints with the HTML instead of waiting for
+     hydration to fade it in (a JS-driven `initial={{ opacity: 0 }}` hides it until then). */
+  --animate-rise-in: nib-rise-in var(--duration-spring-smooth) var(--ease-spring-smooth) both;
+
+  @keyframes spin {
+    to {
+      transform: rotate(360deg);
+    }
+  }
+  @keyframes nib-shimmer {
+    from {
+      background-position: 150% 0;
+    }
+    to {
+      background-position: -50% 0;
+    }
+  }
+  @keyframes nib-sheen {
+    from {
+      transform: translateX(-100%);
+    }
+    to {
+      transform: translateX(100%);
+    }
+  }
+  @keyframes nib-pulse-soft {
+    0%,
+    100% {
+      opacity: 1;
+    }
+    50% {
+      opacity: 0.45;
+    }
+  }
+  @keyframes nib-rise-in {
+    from {
+      opacity: 0;
+      translate: 0 8px;
+    }
+  }
+  @keyframes nib-caret {
+    0%,
+    100% {
+      opacity: 1;
+    }
+    50% {
+      opacity: 0;
+    }
+  }
+}
+
+@layer base {
+  html {
+    font-family: var(--font-sans);
+    font-optical-sizing: auto;
+    /* Inter 4: tailed l (cv05), single-storey a (cv11) — softer, friendlier rhythm. */
+    font-feature-settings: "cv05", "cv11", "calt";
+    -webkit-font-smoothing: antialiased;
+    -moz-osx-font-smoothing: grayscale;
+    text-rendering: optimizeLegibility;
+    -webkit-tap-highlight-color: transparent;
+    background-color: var(--bg);
+    color: var(--fg);
+    /* Native checkboxes, radios and ranges are ink like ours; the text caret is a blue micro-moment. */
+    accent-color: var(--primary);
+    caret-color: var(--accent);
+  }
+
+  body {
+    font-size: var(--text-base);
+    line-height: var(--text-base--line-height);
+    letter-spacing: var(--text-base--letter-spacing);
+  }
+
+  ::selection {
+    background-color: var(--selection);
+  }
+
+  :where(code, kbd, samp, pre) {
+    font-family: var(--font-mono);
+    font-feature-settings: normal;
+    font-variant-ligatures: none;
+  }
+
+  /* Code, keys and machine output read left to right in every language, isolated from the text
+     around them, so a right-to-left sentence never reorders their punctuation. A `dir` on the
+     element (`auto` for text a person wrote) still decides. */
+  :where(code, kbd, samp, pre):not([dir]) {
+    direction: ltr;
+    unicode-bidi: isolate;
+  }
+
+  /* A field that takes its direction from what a person types (`dir="auto"`) is left to right
+     while empty; its placeholder is our copy, so it keeps the page's direction until then. */
+  :where(input, textarea)[dir="auto"]:placeholder-shown {
+    direction: inherit;
+  }
+
+  :where(:focus-visible) {
+    outline: 2px solid var(--focus);
+    outline-offset: 2px;
+  }
+
+  /* Calm scrollbars everywhere; ScrollArea renders its own overlay bars. */
+  * {
+    scrollbar-width: thin;
+    scrollbar-color: color-mix(in oklab, var(--gray-12) 18%, transparent) transparent;
+  }
+
+  :where(button, [role="button"]) {
+    cursor: default;
+  }
+
+  [hidden]:where(:not([hidden="until-found"])) {
+    display: none !important;
+  }
+
+  /*
+   * Icons that point along the reading direction mirror in a right-to-left language (`dir` comes
+   * from the language). The mirror applies before a component's own `rotate`, so a mirrored icon that
+   * turns (an open chevron) turns the other way right to left (`rtl:-rotate-90`).
+   */
+  [dir="rtl"]
+  :is(
+    .lucide-chevron-right,
+    .lucide-chevron-left,
+    .lucide-chevrons-right,
+    .lucide-chevrons-left,
+    .lucide-arrow-right,
+    .lucide-arrow-left,
+    .lucide-arrow-up-right,
+    .lucide-arrow-up-left,
+    .lucide-corner-down-right,
+    .lucide-corner-down-left,
+    .lucide-external-link,
+    .lucide-square-arrow-out-up-right,
+    .lucide-log-in,
+    .lucide-log-out,
+    .lucide-panel-left,
+    .lucide-panel-right,
+    .lucide-reply,
+    .lucide-forward,
+    .lucide-undo-2,
+    .lucide-redo-2
+  ) {
+    scale: -1 1;
+  }
+}
+
+/* ------------------------------------------------------------------------------------------ */
+/* Utilities                                                                                  */
+/* ------------------------------------------------------------------------------------------ */
+
+/* Focus ring for components that manage their own focus treatment. */
+@utility ring-focus {
+  outline: 2px solid var(--focus);
+  outline-offset: 2px;
+}
+
+/* Animated light sweep over text — the "working" voice of the thinking indicator. */
+@utility text-shimmer {
+  color: transparent;
+  background-image: linear-gradient(
+    100deg,
+    var(--fg-subtle) 0%,
+    var(--fg-subtle) 35%,
+    var(--fg) 50%,
+    var(--fg-subtle) 65%,
+    var(--fg-subtle) 100%
+  );
+  background-size: 250% 100%;
+  background-clip: text;
+  -webkit-background-clip: text;
+  animation: var(--animate-shimmer);
+
+  @media (prefers-reduced-motion: reduce) {
+    animation: none;
+    color: var(--fg-muted);
+    background: none;
+  }
+}
+
+/* Touch screens: the control's hit area reaches at least 44 × 44 px (WCAG 2.5.5, Apple's HIG) without
+   changing how it looks — an invisible layer centred on it, grown only along the sides shorter than
+   44 px. The control needs `position: relative` and no clipping; its own ::after stays free elsewhere. */
+@utility touch-target {
+  @media (pointer: coarse) {
+    &::after {
+      content: "";
+      position: absolute;
+      inset-block: min(0px, calc((100% - 44px) / 2));
+      inset-inline: min(0px, calc((100% - 44px) / 2));
+    }
+  }
+}
+
+/* Any pointer: a control drawn smaller than 24 × 24 px (a 14 px checkbox) still takes presses across
+   24 × 24 (WCAG 2.5.8), on an invisible ::before layer centred on it. `touch-target` grows it to
+   44 px on touch screens on ::after; the two coexist. The control needs `position: relative`. */
+@utility hit-target {
+  &::before {
+    content: "";
+    position: absolute;
+    inset-block: min(0px, calc((100% - 24px) / 2));
+    inset-inline: min(0px, calc((100% - 24px) / 2));
+  }
+}
+
+/*
+ * The caret where text is arriving (a streamed reply, live dictation): accent ink, 2 px wide, blinking
+ * in steps and still under reduced motion. One mark wherever text streams in; callers add its gap.
+ */
+@utility stream-caret {
+  display: inline-block;
+  height: 1.05em;
+  width: 2px;
+  translate: 0 0.18em;
+  border-radius: calc(infinity * 1px);
+  background-color: var(--color-accent);
+  animation: var(--animate-caret);
+
+  @media (prefers-reduced-motion: reduce) {
+    animation: none;
+  }
+}
+
+/* Raised surface: background + border + layered shadow + top edge highlight. */
+@utility surface-raised {
+  background-color: var(--surface-raised);
+  border: 1px solid var(--border);
+  box-shadow: var(--shadow-lg), var(--shadow-inset-edge);
+}
+
+@utility tabular {
+  font-variant-numeric: tabular-nums;
+}
+
+/*
+ * Something whose moment has passed or is held back (an expired request, an archived session, a
+ * resolved comment, a question waiting its turn, a list while offline): it reads inactive at a glance
+ * and its words still read at 4.5:1. Ink text steps down to fg-muted (the quieter tiers stay as they
+ * are); icons, avatars and status glyphs lose their colour and fade, which decorative imagery may.
+ * Never opacity on text: faded words fall under 4.5:1.
+ */
+@utility inactive {
+  --fg: var(--fg-muted);
+
+  &
+    :where(svg, img, [data-slot="avatar"], [data-slot="crew-avatar"], [data-inactive-media]):not(
+      :where([data-slot="avatar"], [data-slot="crew-avatar"], [data-inactive-media]) *
+    ) {
+    filter: grayscale(1);
+    opacity: 0.55;
+  }
+}
+
+@utility scrollbar-none {
+  scrollbar-width: none;
+  &::-webkit-scrollbar {
+    display: none;
+  }
+}
+
+/*
+ * A scroller whose edges fade only where content goes on past them: the top once it's scrolled, the
+ * bottom while there's more below, neither when it all fits. Scroll-driven (no script); an engine
+ * without scroll timelines keeps a 24 px top fade only. Used by the sidebar and the transcript.
+ */
+@property --scroll-fade-top {
+  syntax: "<length>";
+  inherits: false;
+  initial-value: 0px;
+}
+@property --scroll-fade-bottom {
+  syntax: "<length>";
+  inherits: false;
+  initial-value: 0px;
+}
+@keyframes scroll-fade-top-in {
+  from {
+    --scroll-fade-top: 0px;
+  }
+  to {
+    --scroll-fade-top: 24px;
+  }
+}
+@keyframes scroll-fade-bottom-out {
+  from {
+    --scroll-fade-bottom: 24px;
+  }
+  to {
+    --scroll-fade-bottom: 0px;
+  }
+}
+@utility scroll-fade-y {
+  mask-image: linear-gradient(
+    to bottom,
+    transparent 0,
+    black var(--scroll-fade-top),
+    black calc(100% - var(--scroll-fade-bottom)),
+    transparent 100%
+  );
+  animation:
+    scroll-fade-top-in linear both,
+    scroll-fade-bottom-out linear both;
+  animation-timeline: scroll(self), scroll(self);
+  animation-range:
+    0 24px,
+    calc(100% - 24px) 100%;
+}
+
+/* Base UI popups expose data-starting-style / data-ending-style — one shared enter/exit. Functional
+   UI: a 120 ms fade and scale from the trigger, no blur; exits are quicker still. */
+@utility popup-motion {
+  transform-origin: var(--transform-origin);
+  transition-property: opacity, scale;
+  transition-duration: var(--duration-fast);
+  transition-timing-function: var(--ease-out);
+
+  &[data-starting-style],
+  &[data-ending-style] {
+    opacity: 0;
+    scale: 0.97;
+  }
+  &[data-ending-style] {
+    /* Exits are quicker than entrances and never ease-in (UI shouldn't accelerate away). */
+    transition-duration: var(--duration-instant);
+  }
+  @media (prefers-reduced-motion: reduce) {
+    &[data-starting-style],
+    &[data-ending-style] {
+      scale: 1;
+    }
+  }
+}
+
+/* Controls (buttons, tiles): colour feedback is a quick tween that keeps up with the pointer; only
+   the press scale uses the snappy spring. */
+@utility control-motion {
+  transition-property: background-color, border-color, color, box-shadow, opacity, scale;
+  transition-duration:
+    var(--duration-fast), var(--duration-fast), var(--duration-fast), var(--duration-fast),
+    var(--duration-fast), var(--duration-spring-snappy);
+  transition-timing-function:
+    var(--ease-standard), var(--ease-standard), var(--ease-standard), var(--ease-standard),
+    var(--ease-standard), var(--ease-spring-snappy);
+}
+
+/* Rows and cards that open something answer the press like buttons do: a 1.5 % press on the
+   snappy spring (docs/design/system.md §7). No movement under Reduce Motion. */
+@utility press-motion {
+  transition: scale var(--duration-spring-snappy) var(--ease-spring-snappy);
+  &:active {
+    scale: 0.985;
+  }
+  @media (prefers-reduced-motion: reduce) {
+    &:active {
+      scale: 1;
+    }
+  }
+}
+
+@utility backdrop-motion {
+  transition: opacity var(--duration-moderate) var(--ease-out);
+  &[data-starting-style],
+  &[data-ending-style] {
+    opacity: 0;
+  }
+  /* A closing backdrop is already gone for the person: a click lands on what's under it, as the closing popup lets it. */
+  &[data-ending-style] {
+    pointer-events: none;
+  }
+}
+
+/* Theme swaps flip every surface in one frame instead of cross-fading at different speeds. */
+[data-theme-switching],
+[data-theme-switching] * {
+  transition: none !important;
+}

package/dist/styles/code.css

@@ -0,0 +1,35 @@
+/*
+ * Syntax highlighting for <CodeBlock> (and anything else rendering Shiki tokens from
+ * `src/lib/shiki.ts`).
+ *
+ * Tokens are emitted with `defaultColor: false`, i.e. each span carries both palettes as custom
+ * properties (`--shiki-light`, `--shiki-dark`, `--shiki-light-font-style`, …). `light-dark()` picks
+ * the right one from the element's used `color-scheme`, which `[data-theme]` (ThemeProvider) and
+ * `:root { color-scheme: light dark }` (system) already drive — so nested theme scopes work and a
+ * theme switch never re-tokenizes. kit-light/kit-dark share font styles, so the light variables
+ * are authoritative for italic/bold.
+ */
+
+[data-shiki] span[style*="--shiki-"] {
+  color: light-dark(var(--shiki-light), var(--shiki-dark));
+  font-style: var(--shiki-light-font-style, inherit);
+  font-weight: var(--shiki-light-font-weight, inherit);
+  text-decoration: var(--shiki-light-text-decoration, inherit);
+}
+
+/* Streaming: freshly appended lines fade in instead of popping (opacity only). */
+@keyframes nib-code-line-in {
+  from {
+    opacity: 0;
+  }
+}
+
+[data-shiki][data-streaming] [data-line] {
+  animation: nib-code-line-in var(--duration-base) var(--ease-out) both;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  [data-shiki][data-streaming] [data-line] {
+    animation: none;
+  }
+}

package/dist/styles/fonts.css

@@ -0,0 +1,12 @@
+/*
+ * The kit's typefaces (self-hosted via Fontsource, OFL-licensed):
+ *  - Inter 4 with optical sizing  → UI + prose
+ *  - Geist Mono                   → code, terminals, numerals in data
+ *  - Source Serif 4 (opsz)        → rare editorial moments (greetings, landing headlines)
+ * Import once at the app root: `import "@nibapp/ui/fonts.css"`.
+ */
+@import "@fontsource-variable/inter/opsz.css";
+@import "@fontsource-variable/inter/opsz-italic.css";
+@import "@fontsource-variable/geist-mono/wght.css";
+@import "@fontsource-variable/source-serif-4/opsz.css";
+@import "@fontsource-variable/source-serif-4/opsz-italic.css";

package/dist/styles/index.css

@@ -0,0 +1,13 @@
+/*
+ * @nibapp/ui stylesheet. In an app's global CSS:
+ *
+ *   @import "tailwindcss";
+ *   @import "@nibapp/ui/styles.css";
+ *
+ * The @source below makes Tailwind scan @nibapp/ui's components wherever the package lives.
+ */
+@import "./tokens.gen.css";
+@import "./base.css";
+@import "./code.css";
+
+@source "../";