@kud/ink-ui 0.15.0 → 0.17.0

package/AGENTS.md

@@ -0,0 +1,117 @@
+# 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, pills 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 |
+| A category label — `epic`, `draft` — that should read as one object | `Pill`, filled and rounded; `Badge` for the bracket form. Never for a reference the reader follows |
+| 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

@@ -15,6 +15,46 @@ type BadgeProps = {
 };
 declare const Badge: ({ children, variant }: BadgeProps) => React__default.JSX.Element;
 
+type PillVariant = "success" | "error" | "warning" | "info" | "accent" | "muted";
+type PillProps = {
+    children: string;
+    variant?: PillVariant;
+};
+/**
+ * A filled, rounded label — a category the thing belongs to, not a status it is
+ * in.
+ *
+ * Reach for it when the word IS the information (`epic`, `draft`, `blocked`) and
+ * you want it to read as one object rather than as more prose. For a reference
+ * the reader is meant to follow — a ticket key, a repo — leave the text dim: a
+ * fill gives a breadcrumb a weight it has not earned, and once everything is a
+ * pill none of them is.
+ *
+ * The WORD carries the meaning and the colour only reinforces it, so a pill
+ * survives being read in monochrome, piped, or by someone who cannot separate
+ * the hues.
+ *
+ * Powerline half-circles, like `ToggleSwitch` and for the same reason: they are
+ * the only way to get a genuinely rounded end out of a terminal cell, and a font
+ * without them renders blanks, which degrades to a square pill rather than
+ * breaking the layout. Not gated on `getIconMode` — that switch chooses between
+ * two glyph SETS, and this is one glyph with a graceful absence.
+ *
+ * `NO_COLOR` is the one case that does fall back to brackets: with the fill
+ * stripped, the caps would be drawing the outline of a pill that is not there.
+ */
+declare const Pill: ({ children, variant }: PillProps) => React__default.JSX.Element;
+/**
+ * How many columns `<Pill>` occupies for `text` — the label plus its two caps.
+ *
+ * Exported because a caller laying out a fixed-width row has to price the pill
+ * BEFORE rendering it, and measuring the rendered output is not available at
+ * that point. A row that budgets for the label alone overflows by exactly two
+ * columns, which in a frame sized to fill the terminal scrolls the whole panel
+ * instead of clipping.
+ */
+declare const pillWidth: (text: string) => number;
+
 type HeaderProps = {
     children: string;
     subtitle?: string;
@@ -321,4 +361,4 @@ declare const spacing: {
 };
 type Spacing = (typeof spacing)[keyof typeof spacing];
 
-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 };
+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, Pill, type PillVariant, 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, pillWidth, setIconMode, spacing, useListCursor, useTabs };

package/dist/index.js

@@ -1,9 +1,9 @@
 import { Box, Text, useStdout, useInput, measureElement } from 'ink';
 import { jsx, jsxs } from 'react/jsx-runtime';
+import { glyphs } from '@kud/glyphs';
 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';
 
 // src/components/Banner.tsx
@@ -39,6 +39,36 @@ var Badge = ({ children, variant = "info" }) => /* @__PURE__ */ jsxs(Text, { col
   children,
   "]"
 ] });
+var FILL = {
+  success: colors.success,
+  error: colors.error,
+  warning: colors.warning,
+  info: colors.info,
+  accent: colors.accent,
+  muted: colors.muted
+};
+var INK = {
+  success: "black",
+  error: "white",
+  warning: "black",
+  info: "black",
+  accent: "black",
+  muted: "white"
+};
+var Pill = ({ children, variant = "muted" }) => {
+  const fill = FILL[variant];
+  if (process.env["NO_COLOR"]) return /* @__PURE__ */ jsxs(Text, { color: fill, children: [
+    "[",
+    children,
+    "]"
+  ] });
+  return /* @__PURE__ */ jsxs(Text, { children: [
+    /* @__PURE__ */ jsx(Text, { color: fill, children: glyphs.plCapLeft }),
+    /* @__PURE__ */ jsx(Text, { backgroundColor: fill, color: INK[variant], children }),
+    /* @__PURE__ */ jsx(Text, { color: fill, children: glyphs.plCapRight })
+  ] });
+};
+var pillWidth = (text) => text.length + 2;
 var Header = ({ children, subtitle }) => /* @__PURE__ */ jsxs(Box, { flexDirection: "column", marginBottom: 1, children: [
   /* @__PURE__ */ jsx(Text, { bold: true, underline: true, children }),
   subtitle && /* @__PURE__ */ jsx(Text, { dimColor: true, children: subtitle })
@@ -893,4 +923,4 @@ var notify = (message, options = {}) => {
   child.unref();
 };
 
-export { Alert, Badge, Banner, Columns, ConfirmInput, EmailInput, FooterHints, Header, KeyValue, LoadingScreen, MultiSelect, OrderedList, Panel, PasswordInput, ProgressBar, ScrollView, Select, SelectableRow, Spinner, StatusMessage, Switch, Table, Tabs, TextInput, Toast, Toggle, ToggleSwitch, UnorderedList, UpdateBanner, colors, getIconMode, notify, setIconMode, spacing, useListCursor, useTabs };
+export { Alert, Badge, Banner, Columns, ConfirmInput, EmailInput, FooterHints, Header, KeyValue, LoadingScreen, MultiSelect, OrderedList, Panel, PasswordInput, Pill, ProgressBar, ScrollView, Select, SelectableRow, Spinner, StatusMessage, Switch, Table, Tabs, TextInput, Toast, Toggle, ToggleSwitch, UnorderedList, UpdateBanner, colors, getIconMode, notify, pillWidth, setIconMode, spacing, useListCursor, useTabs };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kud/ink-ui",
-  "version": "0.15.0",
+  "version": "0.17.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"
   },