@garage49/garage49-tui-ink 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 garage49
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,98 @@
-# Temporary Holding Version
+# @garage49/garage49-tui-ink
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The garage49 TUI design system for Node.js: OpenCode's look and feel as [Ink](https://github.com/vadimdemedes/ink) components, with an application shell that gives every app the same navigation, focus, mouse, overlays and status bars.
+
+## Install
+
+```bash
+pnpm add @garage49/garage49-tui-ink ink react   # or npm install
+```
+
+Requires Node.js 20 or later, Ink 8 and React 19.
+
+## Use
+
+```tsx
+import {useState} from 'react';
+import {App, Content, Main, Nav, Sidebar, Table, run, useFocused, useStatus} from '@garage49/garage49-tui-ink';
+
+const views = [{id: 'work', label: 'Work'}, {id: 'settings', label: 'Settings'}];
+const pages = [{id: 'projects', label: 'Projects', section: 'Browse'}, {id: 'log', label: 'Activity', section: 'Browse'}];
+
+function ProjectsPage() {
+  const focused = useFocused();
+  const {report} = useStatus();
+  const [selected, setSelected] = useState('garage49-tui');
+  return (
+    <Table
+      columns={[{id: 'name', title: 'Name', width: 24, cell: (p: {name: string}) => p.name}]}
+      rows={[{name: 'garage49-tui'}, {name: 'skills'}]}
+      rowId={p => p.name}
+      selectedId={selected}
+      focused={focused}
+      onSelect={p => setSelected(p.name)}
+      onClick={p => report(`open: ${p.name}`)}
+    />
+  );
+}
+
+function MyApp() {
+  const [view, setView] = useState('work');
+  const [page, setPage] = useState('projects');
+  return (
+    <App context="myapp">
+      <Nav brand="myapp" items={views} activeId={view} onChange={item => setView(item.id)} right="v1.0.0" />
+      <Content>
+        {view === 'work' && <Sidebar items={pages} selectedId={page} onSelect={item => setPage(item.id)} />}
+        <Main title="Projects"><ProjectsPage /></Main>
+      </Content>
+    </App>
+  );
+}
+
+run(<MyApp />);
+```
+
+## Rules of use
+
+Read these before writing app code.
+
+1. **The root renders `App` and nothing else.** `useOverlay`, `useStatus`, `useTyping` and `useFocused` are contexts that `App` provides, so they work only in App's children. Put the app body, the pages and every hook call in child components.
+2. **Running inside an existing event loop.** `run()` calls Ink's `render` and returns its `Instance`; it does not block. Keep servers and timers on the same Node event loop and call `instance.unmount()` (or `exit` from `useApp`) to leave.
+3. **Pushing a background task's state into the UI.** Hold the task's state in React state (or an external store read with `useSyncExternalStore`) in a component under `App`, and update it from the task's callbacks; never render from the task.
+4. **Page letter keys yield while a field is editing.** A page that binds letters (`j k e d s …`) must pass `isActive: focused && !typing` (read it with `useTypingState()` from the shell) or those keys also type into the editing field. App's own `q ? t m` already yield.
+5. **Editor round trips.** Use Ink's `useApp().suspendTerminal()` (Ink 8) around the external program; the shell does not wrap it yet.
+
+`run` mounts the app on the alternate screen with the theme that fits the terminal (OpenCode's truecolor theme, or the system theme without truecolor) and restores the terminal on exit. `App` provides focus cycling (tab, enter/esc), the mouse, the overlay slot, the command palette (ctrl+p), help (?), the quit confirmation (q), theme (t) and mouse (m) toggles, the status line and the key hint bar.
+
+## Build
+
+```bash
+npm run build
+```
+
+Emits `dist/` with JavaScript and type declarations.
+
+## Test
+
+Unit tests:
+
+```bash
+npm test
+```
+
+Complexity check (ESLint: cyclomatic complexity 10, 50 lines per function, 5 parameters):
+
+```bash
+npm run complexity
+```
+
+`npm run check` runs the type check, the complexity check and the tests.
+
+## Run
+
+The gallery in `samples/node` of the repository shows every component:
+
+```bash
+pnpm gallery
+```

package/dist/components/Button.d.ts

@@ -0,0 +1,8 @@
+type Props = {
+    label: string;
+    selected?: boolean;
+    onPress?: () => void;
+};
+/** A clickable label on a raised surface; the selected button is filled with the accent color. */
+export declare function Button({ label, selected, onPress }: Props): import("react").JSX.Element;
+export {};

package/dist/components/Button.js

@@ -0,0 +1,13 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+import { useRef } from 'react';
+import { useMouseTarget } from '../input/Mouse.js';
+import { useTheme } from '../theme/ThemeContext.js';
+/** A clickable label on a raised surface; the selected button is filled with the accent color. */
+export function Button({ label, selected = false, onPress }) {
+    const theme = useTheme();
+    const box = useRef(null);
+    useMouseTarget(box, { onPress: event => { if (event.button === 'left')
+            onPress?.(); } });
+    return (_jsx(Box, { ref: box, backgroundColor: selected ? theme.tokens.selectionBackground : theme.tokens.surfaceRaised, paddingX: 2, marginLeft: 2, children: _jsx(Text, { bold: selected, color: selected ? theme.tokens.selectionText : theme.tokens.text, children: label }) }));
+}

package/dist/components/Checkbox.d.ts

@@ -0,0 +1,10 @@
+type Props = {
+    label: string;
+    checked: boolean;
+    onChange?: (checked: boolean) => void;
+    focused?: boolean;
+    onFocus?: () => void;
+};
+/** A check box on the screen background: ☑ in the success color when checked, ☐ muted otherwise. Space or click toggles. */
+export declare function Checkbox({ label, checked, onChange, focused, onFocus }: Props): import("react").JSX.Element;
+export {};

package/dist/components/Checkbox.js

@@ -0,0 +1,18 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+import { useRef } from 'react';
+import { useKeys } from '../input/Keys.js';
+import { useMouseTarget } from '../input/Mouse.js';
+import { Glyphs } from '../theme/Glyphs.js';
+import { useTheme } from '../theme/ThemeContext.js';
+import { FieldBar } from './FieldBar.js';
+import { useSurface } from './FocusRegion.js';
+/** A check box on the screen background: ☑ in the success color when checked, ☐ muted otherwise. Space or click toggles. */
+export function Checkbox({ label, checked, onChange, focused = false, onFocus }) {
+    const theme = useTheme();
+    const surface = useSurface();
+    const box = useRef(null);
+    useMouseTarget(box, { onPress: () => { onFocus?.(); onChange?.(!checked); } });
+    useKeys([{ keys: ['space', 'enter'], run: () => onChange?.(!checked) }], { isActive: focused });
+    return (_jsxs(Box, { ref: box, flexDirection: "row", height: 1, children: [_jsx(FieldBar, { focused: focused, surface: surface }), _jsx(Text, { children: " " }), _jsxs(Text, { bold: true, color: checked ? theme.tokens.success : theme.tokens.textMuted, children: [checked ? Glyphs.checked : Glyphs.unchecked, " "] }), _jsx(Text, { color: focused ? theme.tokens.text : theme.tokens.textMuted, children: label })] }));
+}

package/dist/components/Chip.d.ts

@@ -0,0 +1,14 @@
+export type ChipTone = 'default' | 'accent' | 'success' | 'warning' | 'error';
+type Props = {
+    label: string;
+    /** Colors the label; the pill stays on the raised surface so tone reads as a state, not a cursor. */
+    tone?: ChipTone;
+    /** The cursor is on this chip: filled with the accent color. */
+    selected?: boolean;
+    /** Shows a × and calls onRemove when it is clicked. */
+    onRemove?: () => void;
+    onPress?: () => void;
+};
+/** A small pill on the raised surface: a tag, a filter, a status. Click selects; × removes. */
+export declare function Chip({ label, tone, selected, onRemove, onPress }: Props): import("react").JSX.Element;
+export {};

package/dist/components/Chip.js

@@ -0,0 +1,25 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+import { useRef } from 'react';
+import { useMouseTarget } from '../input/Mouse.js';
+import { useTheme } from '../theme/ThemeContext.js';
+/** A small pill on the raised surface: a tag, a filter, a status. Click selects; × removes. */
+export function Chip({ label, tone = 'default', selected = false, onRemove, onPress }) {
+    const theme = useTheme();
+    const box = useRef(null);
+    const tones = {
+        default: theme.tokens.text,
+        accent: theme.tokens.accent,
+        success: theme.tokens.success,
+        warning: theme.tokens.warning,
+        error: theme.tokens.error,
+    };
+    useMouseTarget(box, {
+        onPress: event => {
+            if (onRemove && event.localX >= [...label].length + 2)
+                return onRemove();
+            onPress?.();
+        },
+    });
+    return (_jsxs(Box, { ref: box, paddingX: 1, marginRight: 1, backgroundColor: selected ? theme.tokens.selectionBackground : theme.tokens.surfaceRaised, children: [_jsx(Text, { bold: selected, color: selected ? theme.tokens.selectionText : tones[tone], children: label }), onRemove && _jsx(Text, { color: selected ? theme.tokens.selectionText : theme.tokens.textMuted, children: " \u00D7" })] }));
+}

package/dist/components/ConfirmDialog.d.ts

@@ -0,0 +1,13 @@
+type Props = {
+    title: string;
+    message: string;
+    confirmLabel?: string;
+    cancelLabel?: string;
+    /** Marks the confirming action as destructive: the dialog title turns to the error color. */
+    danger?: boolean;
+    onConfirm: () => void;
+    onCancel: () => void;
+};
+/** A yes/no dialog: message, then two buttons; the chosen button is filled with the accent color. */
+export declare function ConfirmDialog({ title, message, confirmLabel, cancelLabel, danger, onConfirm, onCancel }: Props): import("react").JSX.Element;
+export {};

package/dist/components/ConfirmDialog.js

@@ -0,0 +1,18 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box } from 'ink';
+import { useState } from 'react';
+import { useKeys } from '../input/Keys.js';
+import { Button } from './Button.js';
+import { Label } from './Label.js';
+import { Overlay } from './Overlay.js';
+/** A yes/no dialog: message, then two buttons; the chosen button is filled with the accent color. */
+export function ConfirmDialog({ title, message, confirmLabel = 'OK', cancelLabel = 'Cancel', danger = false, onConfirm, onCancel }) {
+    const [confirmSelected, setConfirmSelected] = useState(false);
+    useKeys([
+        { keys: ['esc', 'n'], run: onCancel },
+        { keys: ['y'], run: onConfirm },
+        { keys: ['left', 'right', 'tab'], run: () => setConfirmSelected(!confirmSelected) },
+        { keys: ['enter'], run: () => (confirmSelected ? onConfirm() : onCancel()) },
+    ]);
+    return (_jsxs(Overlay, { title: title, width: 50, variant: danger ? 'error' : 'default', children: [_jsx(Box, { children: _jsx(Label, { children: message }) }), _jsx(Box, { height: 1 }), _jsxs(Box, { flexDirection: "row", justifyContent: "flex-end", children: [_jsx(Button, { label: cancelLabel, selected: !confirmSelected, onPress: onCancel }), _jsx(Button, { label: confirmLabel, selected: confirmSelected, onPress: onConfirm })] })] }));
+}

package/dist/components/Dropdown.d.ts

@@ -0,0 +1,13 @@
+import { type ListItem } from './List.js';
+type Props = {
+    items: readonly ListItem[];
+    /** The row the cursor starts on; the first row otherwise. */
+    initialId?: string;
+    onPick: (item: ListItem) => void;
+    onClose: () => void;
+    /** Left/right arrow: move to a neighbouring dropdown (menus). Absent, the arrows do nothing. */
+    onNavigate?: (delta: -1 | 1) => void;
+};
+/** A list popover on a raised surface, under a menu label or a select box. Owns its cursor and keys. */
+export declare function Dropdown({ items, initialId, onPick, onClose, onNavigate }: Props): import("react").JSX.Element;
+export {};

package/dist/components/Dropdown.js

@@ -0,0 +1,25 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Box } from 'ink';
+import { useState } from 'react';
+import { Selection } from './Selection.js';
+import { useKeys } from '../input/Keys.js';
+import { TextWidth } from '../theme/TextWidth.js';
+import { useTheme } from '../theme/ThemeContext.js';
+import { List } from './List.js';
+/** A list popover on a raised surface, under a menu label or a select box. Owns its cursor and keys. */
+export function Dropdown({ items, initialId, onPick, onClose, onNavigate }) {
+    const theme = useTheme();
+    const [cursorId, setCursorId] = useState(initialId);
+    const cursor = Selection.ensure(items, cursorId);
+    useKeys([
+        { keys: ['esc'], run: onClose },
+        { keys: ['left'], run: () => onNavigate?.(-1) },
+        { keys: ['right'], run: () => onNavigate?.(1) },
+        { keys: ['up'], run: () => setCursorId(id => Selection.move(items, Selection.ensure(items, id), -1)) },
+        { keys: ['down'], run: () => setCursorId(id => Selection.move(items, Selection.ensure(items, id), 1)) },
+        { keys: ['enter'], run: () => { const item = items.find(candidate => candidate.id === cursor); if (item)
+                onPick(item); } },
+    ]);
+    const widest = TextWidth.widest(items.map(item => item.label + (item.shortcut ? `  ${item.shortcut}` : '')));
+    return (_jsx(Box, { flexDirection: "column", backgroundColor: theme.tokens.surface, width: widest + 4, children: _jsx(List, { items: items, selectedId: cursor, onClick: onPick }) }));
+}

package/dist/components/Editing.d.ts

@@ -0,0 +1,11 @@
+import type { DOMElement } from 'ink';
+import { type RefObject } from 'react';
+/**
+ * Whether a text field is editing: it is the page's current field (`focused`) and no click has landed
+ * outside it since. A click outside ends editing (cursor and bar gone, keys back to the app); a click on
+ * the field (`resume`) or the field becoming current again starts it anew.
+ */
+export declare function useEditing(box: RefObject<DOMElement | null>, focused: boolean): {
+    editing: boolean;
+    resume: () => void;
+};

package/dist/components/Editing.js

@@ -0,0 +1,16 @@
+import { useEffect, useState } from 'react';
+import { useMouseOutside } from '../input/Mouse.js';
+/**
+ * Whether a text field is editing: it is the page's current field (`focused`) and no click has landed
+ * outside it since. A click outside ends editing (cursor and bar gone, keys back to the app); a click on
+ * the field (`resume`) or the field becoming current again starts it anew.
+ */
+export function useEditing(box, focused) {
+    const [blurred, setBlurred] = useState(false);
+    useEffect(() => setBlurred(false), [focused]); // becoming (or ceasing to be) the current field starts afresh
+    useMouseOutside(box, () => {
+        if (focused)
+            setBlurred(true);
+    });
+    return { editing: focused && !blurred, resume: () => setBlurred(false) };
+}

package/dist/components/FieldBar.d.ts

@@ -0,0 +1,12 @@
+import type { RegionSurface } from './FocusRegion.js';
+type Props = {
+    focused: boolean;
+    surface?: RegionSurface; /** Height of the field; the bar covers every row. */
+    rows?: number;
+};
+/**
+ * The first column of a form field: blank normally, a blue ┃ down every row while the field is being edited.
+ * Same rule as FocusRegion, at field scale: the bar is painted over the field's own first column.
+ */
+export declare function FieldBar({ focused, surface, rows }: Props): import("react").JSX.Element;
+export {};

package/dist/components/FieldBar.js

@@ -0,0 +1,11 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+import { useTheme } from '../theme/ThemeContext.js';
+/**
+ * The first column of a form field: blank normally, a blue ┃ down every row while the field is being edited.
+ * Same rule as FocusRegion, at field scale: the bar is painted over the field's own first column.
+ */
+export function FieldBar({ focused, surface = 'surface', rows = 1 }) {
+    const theme = useTheme();
+    return (_jsx(Box, { width: 1, height: rows, backgroundColor: theme.tokens[surface], children: _jsx(Text, { color: theme.tokens.accentSecondary, children: (focused ? '┃\n' : ' \n').repeat(rows).trimEnd() }) }));
+}

package/dist/components/FocusRegion.d.ts

@@ -0,0 +1,27 @@
+import { type ReactNode } from 'react';
+export type RegionSurface = 'background' | 'panel' | 'surface' | 'heading';
+/** Tells the fields inside which color their container draws, so a bar-only field paints its bar column on it. */
+export declare function SurfaceProvider({ surface, children }: {
+    surface: RegionSurface;
+    children: ReactNode;
+}): import("react").JSX.Element;
+/** The color of the nearest container: a Section's panel, a MasterDetail detail's surface, an Overlay's panel, else the background. */
+export declare function useSurface(): RegionSurface;
+type Props = {
+    focused: boolean;
+    /** Take the remaining width of the parent row. */
+    grow?: boolean;
+    /** What the region draws in its first column; the bar is painted on that color. One value, or one per row (the last repeats). */
+    surface?: RegionSurface | readonly RegionSurface[];
+    /** How many rows the bar covers from the top; the whole region by default. A header marks only its title row. */
+    rows?: number;
+    children: ReactNode;
+};
+/**
+ * A focusable region. When focused, a column of ┃ in accentSecondary (blue) is painted over the
+ * region's first column; otherwise nothing is drawn, so the region looks exactly as it did.
+ * The region must keep its first column free (padding-left 1). Ink does not keep the cell's
+ * background when a character is painted over it, so the bar repaints the region's surface.
+ */
+export declare function FocusRegion({ focused, grow, surface, rows, children }: Props): import("react").JSX.Element;
+export {};

package/dist/components/FocusRegion.js

@@ -0,0 +1,30 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text, useBoxMetrics } from 'ink';
+import { createContext, useContext, useRef } from 'react';
+import { useTheme } from '../theme/ThemeContext.js';
+const SurfaceContext = createContext('background');
+/** Tells the fields inside which color their container draws, so a bar-only field paints its bar column on it. */
+export function SurfaceProvider({ surface, children }) {
+    return _jsx(SurfaceContext.Provider, { value: surface, children: children });
+}
+/** The color of the nearest container: a Section's panel, a MasterDetail detail's surface, an Overlay's panel, else the background. */
+export function useSurface() {
+    return useContext(SurfaceContext);
+}
+/**
+ * A focusable region. When focused, a column of ┃ in accentSecondary (blue) is painted over the
+ * region's first column; otherwise nothing is drawn, so the region looks exactly as it did.
+ * The region must keep its first column free (padding-left 1). Ink does not keep the cell's
+ * background when a character is painted over it, so the bar repaints the region's surface.
+ */
+export function FocusRegion({ focused, grow = false, surface = 'background', rows, children }) {
+    const theme = useTheme();
+    const content = useRef(null);
+    const { height } = useBoxMetrics(content);
+    const barHeight = Math.max(1, Math.min(height, rows ?? height));
+    return (_jsxs(Box, { flexDirection: "row", flexGrow: grow ? 1 : 0, flexShrink: grow ? 1 : 0, children: [_jsx(Box, { ref: content, flexDirection: "column", flexGrow: 1, children: children }), focused && (_jsx(Box, { position: "absolute", top: 0, left: 0, width: 1, height: barHeight, overflow: "hidden", flexDirection: "column", children: Array.from({ length: barHeight }, (_, row) => {
+                    const surfaces = typeof surface === 'string' ? [surface] : surface;
+                    const name = surfaces[Math.min(row, surfaces.length - 1)];
+                    return _jsx(Box, { height: 1, backgroundColor: theme.tokens[name], children: _jsx(Text, { color: theme.tokens.accentSecondary, children: "\u2503" }) }, row);
+                }) }))] }));
+}

package/dist/components/Form.d.ts

@@ -0,0 +1,27 @@
+import { type ReactNode } from 'react';
+/** The two columns every field of a Form shares. */
+export type FormLayout = {
+    readonly labelWidth: number;
+    readonly valueWidth: number;
+};
+/** The enclosing Form's columns, if any; fields fall back to their own defaults outside a Form. */
+export declare function useFormLayout(): FormLayout | null;
+/** A field's two widths: its own props win, then the enclosing Form, then the gallery defaults (14 / 24). */
+export declare function useFieldColumns(labelWidth?: number, width?: number): {
+    labelCol: number;
+    valueCol: number;
+};
+type Props = {
+    children: ReactNode; /** The form's width; the value column is what the label column leaves. */
+    width?: number;
+};
+/** The narrowest label column a Form uses, so short labels still line up with the gallery. */
+export declare const MIN_LABEL_WIDTH = 12;
+/**
+ * A group of fields that share one label column and one value column. The label column is as wide
+ * as the longest label plus two cells, rounded up to an even number and at least 12; the value column
+ * is the rest of the width, so every text field, select and text area in the form is exactly as wide
+ * as its neighbours.
+ */
+export declare function Form({ children, width }: Props): import("react").JSX.Element;
+export {};

package/dist/components/Form.js

@@ -0,0 +1,29 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Box } from 'ink';
+import { Children, createContext, isValidElement, useContext } from 'react';
+import { TextWidth } from '../theme/TextWidth.js';
+const FormContext = createContext(null);
+/** The enclosing Form's columns, if any; fields fall back to their own defaults outside a Form. */
+export function useFormLayout() {
+    return useContext(FormContext);
+}
+/** A field's two widths: its own props win, then the enclosing Form, then the gallery defaults (14 / 24). */
+export function useFieldColumns(labelWidth, width) {
+    const form = useContext(FormContext);
+    return { labelCol: labelWidth ?? form?.labelWidth ?? 14, valueCol: width ?? form?.valueWidth ?? 24 };
+}
+/** The narrowest label column a Form uses, so short labels still line up with the gallery. */
+export const MIN_LABEL_WIDTH = 12;
+/**
+ * A group of fields that share one label column and one value column. The label column is as wide
+ * as the longest label plus two cells, rounded up to an even number and at least 12; the value column
+ * is the rest of the width, so every text field, select and text area in the form is exactly as wide
+ * as its neighbours.
+ */
+export function Form({ children, width = 60 }) {
+    const labels = Children.toArray(children).flatMap(child => (isValidElement(child) && typeof child.props.label === 'string' ? [child.props.label] : []));
+    // Indents move in steps of two cells, so the label column is rounded up to an even width.
+    const labelWidth = Math.ceil(Math.max(MIN_LABEL_WIDTH, TextWidth.widest(labels) + 2) / 2) * 2;
+    const valueWidth = Math.max(8, width - labelWidth - 1);
+    return (_jsx(FormContext.Provider, { value: { labelWidth, valueWidth }, children: _jsx(Box, { flexDirection: "column", width: width, flexShrink: 0, children: children }) }));
+}

package/dist/components/HelpOverlay.d.ts

@@ -0,0 +1,11 @@
+export type HelpEntry = {
+    readonly keys: string;
+    readonly action: string;
+};
+type Props = {
+    entries: readonly HelpEntry[];
+    onClose: () => void;
+};
+/** The `?` help overlay: one line per key binding. */
+export declare function HelpOverlay({ entries, onClose }: Props): import("react").JSX.Element;
+export {};

package/dist/components/HelpOverlay.js

@@ -0,0 +1,13 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+import { useKeys } from '../input/Keys.js';
+import { TextWidth } from '../theme/TextWidth.js';
+import { useTheme } from '../theme/ThemeContext.js';
+import { Overlay } from './Overlay.js';
+/** The `?` help overlay: one line per key binding. */
+export function HelpOverlay({ entries, onClose }) {
+    const theme = useTheme();
+    useKeys([{ keys: ['esc', '?', 'q'], run: onClose }]);
+    const keyWidth = TextWidth.widest(entries.map(entry => entry.keys)) + 2;
+    return (_jsx(Overlay, { title: "Help", children: _jsx(Box, { flexDirection: "column", children: entries.map(entry => (_jsxs(Box, { flexDirection: "row", children: [_jsx(Box, { width: keyWidth, flexShrink: 0, children: _jsx(Text, { color: theme.tokens.text, children: entry.keys }) }), _jsx(Text, { color: theme.tokens.textMuted, children: entry.action })] }, entry.keys))) }) }));
+}

package/dist/components/Input.d.ts

@@ -0,0 +1,18 @@
+import { type ReactNode } from 'react';
+type Props = {
+    value: string;
+    onChange?: (value: string) => void;
+    onSubmit?: (value: string) => void;
+    placeholder?: string;
+    focused?: boolean;
+    /** Mouse click inside the field. */
+    onFocus?: () => void;
+    /** Secondary line under the text, e.g. mode and model. */
+    footer?: ReactNode;
+};
+/**
+ * OpenCode's input: a surface behind the text with a half-block bottom edge; while focused a blue ┃
+ * is painted over the surface's first column (the FocusRegion rule at field scale).
+ */
+export declare function Input({ value, onChange, onSubmit, placeholder, focused, onFocus, footer }: Props): import("react").JSX.Element;
+export {};

package/dist/components/Input.js

@@ -0,0 +1,31 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+import { useRef } from 'react';
+import { useKeys } from '../input/Keys.js';
+import { useMouseTarget } from '../input/Mouse.js';
+import { useTyping } from '../shell/Typing.js';
+import { useTheme } from '../theme/ThemeContext.js';
+/**
+ * OpenCode's input: a surface behind the text with a half-block bottom edge; while focused a blue ┃
+ * is painted over the surface's first column (the FocusRegion rule at field scale).
+ */
+export function Input({ value, onChange, onSubmit, placeholder = '', focused = true, onFocus, footer }) {
+    const theme = useTheme();
+    useTyping(focused);
+    const box = useRef(null);
+    useMouseTarget(box, { onPress: () => onFocus?.() });
+    // Keys faster than renders chain on `pending`, not on the value captured at the last render.
+    const pending = useRef(value);
+    pending.current = value;
+    const emit = (next) => {
+        pending.current = next;
+        onChange?.(next);
+    };
+    useKeys([
+        { keys: ['enter'], run: () => onSubmit?.(pending.current) },
+        { keys: ['backspace', 'delete'], run: () => emit(pending.current.slice(0, -1)) },
+    ], { isActive: focused, onText: text => emit(pending.current + text) });
+    const cursor = focused ? '█' : '';
+    const bar = focused ? '┃' : ' ';
+    return (_jsxs(Box, { ref: box, flexDirection: "column", children: [_jsxs(Box, { flexDirection: "row", children: [_jsxs(Box, { flexDirection: "column", flexShrink: 0, width: 1, backgroundColor: theme.tokens.surface, children: [_jsx(Text, { color: theme.tokens.accentSecondary, children: bar }), _jsx(Text, { color: theme.tokens.accentSecondary, children: bar }), _jsx(Text, { color: theme.tokens.accentSecondary, children: bar }), footer && _jsx(Text, { color: theme.tokens.accentSecondary, children: bar })] }), _jsxs(Box, { flexDirection: "column", flexGrow: 1, backgroundColor: theme.tokens.surface, paddingX: 2, children: [_jsx(Text, { children: " " }), _jsxs(Text, { color: value ? theme.tokens.text : theme.tokens.textMuted, wrap: "truncate-end", children: [value || placeholder, cursor] }), _jsx(Text, { children: " " }), footer] })] }), _jsxs(Box, { flexDirection: "row", children: [_jsx(Text, { color: focused ? theme.tokens.accentSecondary : theme.tokens.surface, children: focused ? '╹' : '▀' }), _jsx(Box, { flexGrow: 1, overflow: "hidden", height: 1, children: _jsx(Text, { color: theme.tokens.surface, wrap: "wrap", children: '▀'.repeat(400) }) })] })] }));
+}

package/dist/components/Intro.d.ts

@@ -0,0 +1,12 @@
+import type { ReactNode } from 'react';
+type Props = {
+    title: string;
+    children?: ReactNode;
+};
+/**
+ * A page's introduction: a block on the panel surface with no header bar, at the top of the page
+ * before its sections, holding one bright title line and a short muted explanation. It is not a
+ * section (nothing is listed or edited in it), so it has no header bar; at most one per page.
+ */
+export declare function Intro({ title, children }: Props): import("react").JSX.Element;
+export {};

package/dist/components/Intro.js

@@ -0,0 +1,13 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+import { useTheme } from '../theme/ThemeContext.js';
+import { SurfaceProvider } from './FocusRegion.js';
+/**
+ * A page's introduction: a block on the panel surface with no header bar, at the top of the page
+ * before its sections, holding one bright title line and a short muted explanation. It is not a
+ * section (nothing is listed or edited in it), so it has no header bar; at most one per page.
+ */
+export function Intro({ title, children }) {
+    const theme = useTheme();
+    return (_jsxs(Box, { flexDirection: "column", marginBottom: 1, flexShrink: 0, backgroundColor: theme.tokens.panel, paddingX: 2, paddingY: 1, children: [_jsx(Text, { color: theme.tokens.textBright, children: title }), _jsx(SurfaceProvider, { surface: "panel", children: children })] }));
+}

package/dist/components/KeyHintBar.d.ts

@@ -0,0 +1,13 @@
+export type KeyHint = {
+    readonly key: string;
+    readonly label: string; /** What a click on the pair runs; the App's built-in hints have none and are routed by key. */
+    readonly run?: () => void;
+};
+type Props = {
+    hints: readonly KeyHint[];
+    left?: string;
+    onPress?: (hint: KeyHint) => void;
+};
+/** Bottom line: muted context on the left, "key (bright) + label (muted)" pairs on the right. A click on a pair triggers it. */
+export declare function KeyHintBar({ hints, left, onPress }: Props): import("react").JSX.Element;
+export {};

package/dist/components/KeyHintBar.js

@@ -0,0 +1,23 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+import { useRef } from 'react';
+import { useMouseTarget } from '../input/Mouse.js';
+import { TextWidth } from '../theme/TextWidth.js';
+import { useTheme } from '../theme/ThemeContext.js';
+/** Bottom line: muted context on the left, "key (bright) + label (muted)" pairs on the right. A click on a pair triggers it. */
+export function KeyHintBar({ hints, left = '', onPress }) {
+    const theme = useTheme();
+    const pairs = useRef(null);
+    const widths = hints.map(hint => 2 + TextWidth.of(hint.key) + 1 + TextWidth.of(hint.label));
+    useMouseTarget(pairs, {
+        onPress: event => {
+            let x = event.localX;
+            for (const [index, width] of widths.entries()) {
+                if (x < width)
+                    return onPress?.(hints[index]);
+                x -= width;
+            }
+        },
+    });
+    return (_jsxs(Box, { flexDirection: "row", height: 1, flexShrink: 0, width: "100%", children: [_jsx(Box, { flexGrow: 1, flexBasis: 0, overflow: "hidden", children: _jsx(Text, { color: theme.tokens.textMuted, wrap: "truncate-middle", children: left }) }), _jsx(Box, { ref: pairs, flexShrink: 0, flexDirection: "row", children: hints.map(hint => (_jsxs(Box, { marginLeft: 2, children: [_jsxs(Text, { color: theme.tokens.text, children: [hint.key, " "] }), _jsx(Text, { color: theme.tokens.textMuted, children: hint.label })] }, hint.key))) })] }));
+}

package/dist/components/Label.d.ts

@@ -0,0 +1,11 @@
+import { type TextProps } from 'ink';
+import type { ReactNode } from 'react';
+export type LabelVariant = 'default' | 'muted' | 'bright' | 'heading' | 'accent' | 'success' | 'warning' | 'error';
+type Props = {
+    variant?: LabelVariant;
+    children: ReactNode;
+    wrap?: TextProps['wrap'];
+};
+/** Text in one of the theme's semantic roles. Headings are bold. */
+export declare function Label({ variant, children, wrap }: Props): import("react").JSX.Element;
+export {};