@kud/ink-ui 0.14.1 → 0.16.0

package/AGENTS.md

@@ -0,0 +1,116 @@
+# Building a CLI with @kud/ink-ui
+
+Guidance for an AI agent writing a terminal UI against this package. It carries
+the judgement calls the type definitions cannot express — everything else is in
+the types, which are always current.
+
+## Read the types, not a list
+
+**The exhaustive component surface is `dist/index.d.ts`.** Read it before
+reaching for anything. This file deliberately does not list what exists: a
+hand-maintained inventory goes stale, and a stale inventory is worse than none
+because it tells you a component is missing when it is not.
+
+**Before writing any component, check it isn't already here.** Bordered panes,
+scrolling viewports, selectable rows, tables, tab bars, spinners, progress
+bars, key/value pairs, badges and footer key hints are all provided. A
+hand-rolled version of one of these is the single most common mistake in a
+consuming repo.
+
+## The one rule that isn't in the types: who owns the keyboard
+
+Components split into two kinds, and mixing them up is what produces a screen
+that swallows keystrokes or responds twice.
+
+**Uncontrolled — these call Ink's `useInput` themselves.** Mount at most one
+per focus region, and gate the rest with `isDisabled` / `isActive`:
+
+`Select` · `MultiSelect` · `TextInput` · `EmailInput` · `PasswordInput` ·
+`ConfirmInput` · `ScrollView` · `UpdateBanner`
+
+**Presentational — everything else.** They take `active` / `value` / `on` and
+render. They never listen for keys, so they compose freely and you drive them
+from your own state.
+
+**The two hooks supply that state.** `useTabs(items)` and
+`useListCursor(length)` own the keyboard so you don't hand-roll it — and both
+take `{ isActive }` so a screen with several focus regions can gate them.
+`useTabs` wraps by default (a tab bar is a ring); `useListCursor` clamps (a
+list has ends) and takes `{ wrap }` when you genuinely want circular.
+
+**Never write `useInput` to move a cursor or switch a tab.** That is what the
+hooks are for, and hand-rolling it is how arrow/vim keys end up behaving
+differently on every screen.
+
+## Reaching for the right composition
+
+| You need | Compose |
+| --- | --- |
+| A scrolling list of selectable rows | `useListCursor` + `SelectableRow`, one row per item |
+| A long scrollable text/log region | `ScrollView` with `StyledLine[]` — it owns its own scroll keys |
+| A tab bar | `useTabs` + `Tabs` — the hook holds `active`, the component renders it |
+| Tabular data with aligned columns | `Table` with a `Column[]` spec — do not lay out columns by hand |
+| Two or more side-by-side regions | `Columns`, and `Panel` for each region that needs a border |
+| A focusable bordered region | `Panel` with `focused` — the border brightens and the title gains a ● marker |
+| One-off prompt for a value | `TextInput` / `EmailInput` / `PasswordInput` / `ConfirmInput` |
+| Pick one / pick many from a list | `Select` / `MultiSelect` — these own their keyboard, unlike `SelectableRow` |
+| A persistent key-hints footer | `FooterHints` with `Hint` tuples: `[["↑↓", "move"], ["q", "quit"]]` |
+| Label/value detail rows | `KeyValue` with a shared `labelWidth` so values align |
+| Transient feedback | `StatusMessage` (inline) · `Alert` (boxed, with title) · `Toast` (self-dismissing) |
+| App chrome | `Banner` at the top, `Header` per section, `LoadingScreen` while booting |
+
+Composing a domain component on top of these is right and expected — wrapping
+`Table` to render your own row shape is the system working. Reimplementing
+`Table` is not.
+
+## House rules
+
+**Colour comes from tokens, never from a string literal.** Import `colors` and
+use it. There are six tokens and only `accent` is a hex value — the rest are
+named ANSI colours that adapt to the user's terminal theme:
+
+```ts
+import { colors, spacing } from "@kud/ink-ui"
+// colors.accent "#FF8C00" · muted · success · error · warning · info
+// spacing.xs 1 · sm 2 · md 3 · lg 4
+```
+
+A literal like `color="orange"` or `color="#FF8C00"` is wrong even when it
+renders identically — it breaks the moment a token moves.
+
+**State is never signalled by colour alone.** Every status carries a shape, a
+glyph or a weight as well, because a colourblind reader cannot see the hue and
+a piped terminal has no colour at all. `SelectableRow` marks the active row
+with `❯` *and* bold, not just a tint. Hold that line in anything you add.
+
+**Set the icon mode once, before the first render.** `setIconMode("nerd")`
+swaps in Nerd Font glyphs; the default `"text"` is safe everywhere. Components
+read it at render time, so calling it after mounting does nothing.
+
+**There is no theme provider and no context.** Components take only the props
+they need. Do not build a provider to pass tokens around — import them.
+
+**ESM only.** `import`, never `require`. Node ≥ 20, with `ink` ≥ 7 and
+`react` ≥ 19 as peer dependencies the consuming project installs itself.
+
+## Traps
+
+- **A row that overflows its container compresses every flexible child.** If a
+  gutter or marker column must hold its width, wrap it in `<Box flexShrink={0}>`.
+  This only bites on content long enough to overflow, so it survives short test
+  fixtures and breaks in real use.
+- **`Table` needs `maxWidth`** when it sits inside a bordered `Panel`, or the
+  columns size against the terminal rather than the pane.
+- **`Toast` returns `null` once it has expired** — it unmounts itself, so don't
+  rely on it holding layout space.
+- **`useTabs` returns `active` as possibly `undefined`** when the item list is
+  empty. Guard before indexing.
+
+## Working on this repo
+
+If you are editing ink-ui itself rather than building with it: components stay
+presentational unless they are in the uncontrolled list above, every new
+component needs a `.test.tsx` beside it, and the public surface is whatever
+`src/index.ts` exports — a component not exported there does not exist.
+`npm run demo` renders the gallery. Run `npm run typecheck`, `npm test` and
+`npm run build` before committing.

package/README.md

@@ -39,6 +39,14 @@ npm install @kud/ink-ui
 npm install ink react
 ```
 
+### Building with an AI agent
+
+The package ships `AGENTS.md`, a short brief covering the composition rules and house conventions that the type definitions cannot express — which components own the keyboard, what to compose for a given screen, and the traps. Point your agent at it:
+
+```
+node_modules/@kud/ink-ui/AGENTS.md
+```
+
 ## Usage
 
 ```tsx

package/dist/index.d.ts

@@ -26,16 +26,25 @@ type SpinnerProps = {
 };
 declare const Spinner: ({ label }: SpinnerProps) => React__default.JSX.Element;
 
+type ColumnAlign = "left" | "center" | "right";
+type ColumnOverflow = "wrap" | "truncate";
+
 type Column<T extends Record<string, unknown>> = {
     key: keyof T & string;
     header: string;
     width?: number;
+    minWidth?: number;
+    align?: ColumnAlign;
+    overflow?: ColumnOverflow;
 };
 type TableProps<T extends Record<string, unknown>> = {
     data: T[];
     columns: Column<T>[];
+    gap?: number;
+    maxWidth?: number;
+    headerColor?: string;
 };
-declare const Table: <T extends Record<string, unknown>>({ data, columns, }: TableProps<T>) => React__default.JSX.Element;
+declare const Table: <T extends Record<string, unknown>>({ data, columns, gap, maxWidth, headerColor, }: TableProps<T>) => React__default.JSX.Element;
 
 type Hint = [key: string, label: string];
 type FooterHintsProps = {
@@ -312,4 +321,4 @@ declare const spacing: {
 };
 type Spacing = (typeof spacing)[keyof typeof spacing];
 
-export { Alert, Badge, type BadgeVariant, Banner, type Color, type Column, Columns, ConfirmInput, EmailInput, FooterHints, Header, type Hint, type IconMode, KeyValue, LoadingScreen, MultiSelect, type NotifyOptions, OrderedList, Panel, PasswordInput, ProgressBar, ScrollView, Select, type SelectOption, SelectableRow, type Spacing, type Span, Spinner, StatusMessage, type StatusVariant, type StyledLine, Switch, type SwitchValue, type TabItem, Table, Tabs, TextInput, Toast, Toggle, ToggleSwitch, UnorderedList, UpdateBanner, colors, getIconMode, notify, setIconMode, spacing, useListCursor, useTabs };
+export { Alert, Badge, type BadgeVariant, Banner, type Color, type Column, type ColumnAlign, type ColumnOverflow, Columns, ConfirmInput, EmailInput, FooterHints, Header, type Hint, type IconMode, KeyValue, LoadingScreen, MultiSelect, type NotifyOptions, OrderedList, Panel, PasswordInput, ProgressBar, ScrollView, Select, type SelectOption, SelectableRow, type Spacing, type Span, Spinner, StatusMessage, type StatusVariant, type StyledLine, Switch, type SwitchValue, type TabItem, Table, Tabs, TextInput, Toast, Toggle, ToggleSwitch, UnorderedList, UpdateBanner, colors, getIconMode, notify, setIconMode, spacing, useListCursor, useTabs };

package/dist/index.js

@@ -1,7 +1,8 @@
-import { Box, Text, useInput, measureElement } from 'ink';
+import { Box, Text, useStdout, useInput, measureElement } from 'ink';
 import { jsx, jsxs } from 'react/jsx-runtime';
 import React8, { createContext, useContext, useState, useEffect, useRef, useLayoutEffect } from 'react';
 import cliSpinners from 'cli-spinners';
+import stringWidth from 'string-width';
 import { glyphs } from '@kud/glyphs';
 import { spawn } from 'child_process';
 
@@ -56,13 +57,100 @@ var Spinner = ({ label }) => {
     label && /* @__PURE__ */ jsx(Text, { dimColor: true, children: label })
   ] });
 };
+var DEFAULT_MIN_WIDTH = 3;
+var widestLine = (value) => value.split("\n").reduce((widest, line) => Math.max(widest, stringWidth(line)), 0);
+var naturalWidth = (column, cells) => cells.reduce(
+  (widest, cell) => Math.max(widest, widestLine(cell)),
+  widestLine(column.header)
+);
+var floorFor = (column, width) => column.width !== void 0 ? width : Math.min(width, column.minWidth ?? DEFAULT_MIN_WIDTH);
+var widestShrinkable = (widths, floors) => widths.reduce(
+  (best, width, index) => width > floors[index] && (best === -1 || width > widths[best]) ? index : best,
+  -1
+);
+var shrinkToFit = (widths, floors, excess) => {
+  const shrunk = [...widths];
+  let remaining = excess;
+  while (remaining > 0) {
+    const target = widestShrinkable(shrunk, floors);
+    if (target === -1) break;
+    shrunk[target] = shrunk[target] - 1;
+    remaining -= 1;
+  }
+  return shrunk;
+};
+var resolveColumnWidths = ({
+  columns,
+  rows,
+  gap,
+  maxWidth
+}) => {
+  const widths = columns.map(
+    (column, index) => column.width ?? naturalWidth(
+      column,
+      rows.map((row) => row[index] ?? "")
+    )
+  );
+  const gaps = gap * Math.max(columns.length - 1, 0);
+  const excess = widths.reduce((total, width) => total + width, gaps) - maxWidth;
+  return excess > 0 ? shrinkToFit(
+    widths,
+    columns.map((column, index) => floorFor(column, widths[index])),
+    excess
+  ) : widths;
+};
+var FALLBACK_TERMINAL_WIDTH = 80;
+var justification = {
+  left: "flex-start",
+  center: "center",
+  right: "flex-end"
+};
+var cellText = (value) => String(value ?? "");
 var Table = ({
   data,
-  columns
-}) => /* @__PURE__ */ jsxs(Box, { flexDirection: "column", children: [
-  /* @__PURE__ */ jsx(Box, { gap: 2, children: columns.map((col) => /* @__PURE__ */ jsx(Box, { width: col.width, minWidth: col.width, children: /* @__PURE__ */ jsx(Text, { bold: true, color: colors.muted, children: col.header }) }, col.key)) }),
-  data.map((row, i) => /* @__PURE__ */ jsx(Box, { gap: 2, children: columns.map((col) => /* @__PURE__ */ jsx(Box, { width: col.width, minWidth: col.width, children: /* @__PURE__ */ jsx(Text, { wrap: "truncate-end", children: String(row[col.key] ?? "") }) }, col.key)) }, i))
-] });
+  columns,
+  gap = 2,
+  maxWidth,
+  headerColor = colors.muted
+}) => {
+  const { stdout } = useStdout();
+  const rows = data.map(
+    (row) => columns.map((column) => cellText(row[column.key]))
+  );
+  const widths = resolveColumnWidths({
+    columns,
+    rows,
+    gap,
+    maxWidth: maxWidth ?? stdout?.columns ?? FALLBACK_TERMINAL_WIDTH
+  });
+  const cell = (column, index, content) => /* @__PURE__ */ jsx(
+    Box,
+    {
+      width: widths[index],
+      flexShrink: 0,
+      flexGrow: 0,
+      justifyContent: justification[column.align ?? "left"],
+      children: content
+    },
+    column.key
+  );
+  return /* @__PURE__ */ jsxs(Box, { flexDirection: "column", children: [
+    /* @__PURE__ */ jsx(Box, { gap, children: columns.map(
+      (column, index) => cell(
+        column,
+        index,
+        /* @__PURE__ */ jsx(Text, { bold: true, color: headerColor, wrap: "truncate-end", children: column.header })
+      )
+    ) }),
+    rows.map((cells, rowIndex) => /* @__PURE__ */ jsx(Box, { gap, children: columns.map(
+      (column, index) => cell(
+        column,
+        index,
+        /* @__PURE__ */ jsx(Text, { wrap: column.overflow === "wrap" ? "wrap" : "truncate-end", children: cells[index] })
+      )
+    ) }, rowIndex))
+  ] });
+};
 var FooterHints = ({ hints }) => /* @__PURE__ */ jsx(Box, { columnGap: 2, rowGap: 0, flexWrap: "wrap", children: hints.map(([key, label]) => /* @__PURE__ */ jsxs(Box, { children: [
   /* @__PURE__ */ jsx(Text, { color: "white", children: key }),
   /* @__PURE__ */ jsx(Text, { dimColor: true, children: " " + label })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kud/ink-ui",
-  "version": "0.14.1",
+  "version": "0.16.0",
   "description": "React component library for Ink CLIs",
   "type": "module",
   "main": "dist/index.js",
@@ -12,7 +12,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "AGENTS.md"
   ],
   "engines": {
     "node": ">=20"
@@ -22,6 +23,7 @@
     "dev": "tsup --watch",
     "demo": "tsx src/demo/index.tsx",
     "typecheck": "tsc --noEmit",
+    "check:agents": "node scripts/check-agents-md.mjs",
     "test": "vitest run",
     "test:watch": "vitest"
   },
@@ -32,7 +34,8 @@
   "dependencies": {
     "@kud/glyphs": "0.1.1",
     "cli-spinners": "3.4.0",
-    "figures": "6.1.0"
+    "figures": "6.1.0",
+    "string-width": "8.2.2"
   },
   "devDependencies": {
     "@types/node": "22.20.1",