@rigerc/ink-ui 0.0.0-stage → 0.41.0

package/README.md

@@ -1,3 +1,171 @@
-# Temporary Holding Version
+<div align="center">
 
-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.
+![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?style=flat-square&logo=typescript&logoColor=white)
+![Node.js](https://img.shields.io/badge/Node.js-339933?style=flat-square&logo=node.js&logoColor=white)
+![npm](https://img.shields.io/npm/v/%40rigerc%2Fink-ui?style=flat-square&color=CB3837)
+![MIT](https://img.shields.io/badge/licence-MIT-22C55E?style=flat-square)
+
+**React component library for Ink CLIs**
+
+<a href="https://github.com/rigerc/ink-ui">Repository</a> · <a href="https://github.com/rigerc/ink-ui/tree/main/docs">Documentation</a>
+
+</div>
+
+## Features
+
+- **28 ready-made components**, pre-styled and ready to drop in:
+  - **Inputs** — `TextInput`, `EmailInput` (domain completion), `PasswordInput` (masked), `ConfirmInput`
+  - **Lists** — `UnorderedList`, `OrderedList` (both nestable), `Table`
+  - **Selection & navigation** — `Select`, `MultiSelect`, `Tabs`, `Stepper`, `Switch`, `Toggle`, `SelectableRow`
+  - **Status & feedback** — `Spinner`, `ProgressBar`, `SkeletonBar`, `SkeletonRows`, `StatusMessage`, `Alert`, `Badge`, `Toast`
+  - **Layout & chrome** — `Banner`, `Header`, `Panel` (bordered pane, optional focus state), `Columns`, `FooterHints`, `KeyValue`, `LoadingScreen`, `ScrollView`
+- **Behaviour hooks** — `useTabs` and `useListCursor` own the keyboard state that every consumer used to hand-roll, so Tab/Shift+Tab and arrow/vim navigation behave the same everywhere
+- **Full [@inkjs/ui](https://github.com/vadimdemedes/ink-ui) parity** — every upstream component has an equivalent, plus a dozen more the design system adds on top
+- **Colourblind-safe by design** — state is signalled by shape, case, and glyph, never colour alone
+- **Design tokens included** — established palettes (`colors`, `softColors`, `tonalColors`), spacing, and reusable semantic symbols, ASCII fallbacks, border presets, and motion tokens
+- **Full TypeScript support** — ships compiled output with `.d.ts` declarations for every component and token type
+- **ESM only, zero config** — no runtime bundling step; just import and render
+- **Peer-dependency light** — only requires `ink ≥ 7` and `react ≥ 19`
+
+## Install
+
+```sh
+npm install @rigerc/ink-ui
+```
+
+Until this fork is published under the `@rigerc` npm scope, you can
+install directly from its GitHub branch:
+
+```sh
+npm install github:rigerc/ink-ui#chore/rebrand-rigerc-scope
+```
+
+Git installs build `dist/` automatically using the package's `prepare` script.
+After publication, use the scoped npm install command above.
+
+
+`ink` and `react` are peer dependencies and must be installed separately:
+
+```sh
+npm install ink react
+```
+
+### Ink compatibility
+
+`@rigerc/ink-ui` supports Ink 7 and Ink 8 on Node.js 22 or later. Ink 8
+requires React 19.3 or later; when installing Ink 8, install a matching
+version of React:
+
+```sh
+npm install ink@^8 react@^19.3.0
+```
+
+The library preserves the same public component API across both Ink majors.
+
+
+### 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/@rigerc/ink-ui/AGENTS.md
+```
+
+## Usage
+
+```tsx
+import React from "react"
+import { render } from "ink"
+import { Banner, Header, Badge, Spinner, colors } from "@rigerc/ink-ui"
+
+const App = () => (
+  <>
+    <Banner title="my-tool" subtitle="v1.0.0" />
+    <Header subtitle="Synchronising files…">Status</Header>
+    <Badge variant="success">done</Badge>
+    <Spinner label="Loading…" />
+  </>
+)
+
+render(<App />)
+```
+
+Inputs report their value through `onChange`/`onSubmit`, and lists nest with a shape-distinct marker per level:
+
+```tsx
+import { Text } from "ink"
+import { EmailInput, PasswordInput, UnorderedList } from "@rigerc/ink-ui"
+
+const SignUp = () => (
+  <>
+    <EmailInput placeholder="you@example.com" onSubmit={setEmail} />
+    <PasswordInput placeholder="Password" onSubmit={setPassword} />
+    <UnorderedList>
+      <UnorderedList.Item>
+        <Text>Choose a plan</Text>
+        <UnorderedList>
+          <UnorderedList.Item>
+            <Text>Free</Text>
+          </UnorderedList.Item>
+          <UnorderedList.Item>
+            <Text>Pro</Text>
+          </UnorderedList.Item>
+        </UnorderedList>
+      </UnorderedList.Item>
+    </UnorderedList>
+  </>
+)
+```
+
+Components stay presentational and controlled — they take `active`/`value` and render. The behaviour hooks supply the keyboard state to drive them, so the two compose without either forcing the other:
+
+```tsx
+import { Tabs, useTabs, useListCursor } from "@rigerc/ink-ui"
+
+const items = [
+  { value: "open", label: "Open", count: 3 },
+  { value: "done", label: "Done" },
+]
+
+const Inbox = ({ rows }) => {
+  const { active } = useTabs(items) // Tab or → forward, Shift+Tab or ← back, wraps
+  const { cursor } = useListCursor(rows.length) // ↑/↓ and k/j, clamps at the ends
+  return <Tabs active={active} items={items} />
+}
+```
+
+Both take `{ isActive }` so a screen with several focus regions can gate them, and `useListCursor` takes `{ wrap }` for genuinely circular lists. `useTabs` wraps by default because a tab bar is a ring; `useListCursor` clamps because a list has ends.
+
+All components accept only the props they need — no theme provider or context required. Design tokens are plain objects:
+
+```ts
+import { colors, spacing } from "@rigerc/ink-ui"
+
+// colors.accent   → "#FF8C00"
+// colors.success  → "#5FD7A7"
+// spacing.md      → 3
+```
+
+## Development
+
+```sh
+git clone https://github.com/rigerc/ink-ui.git
+cd ink-ui
+npm install
+npm run dev
+```
+
+### Interactive gallery
+
+Run `npm run demo` to browse live component previews. Use ↑/↓ or j/k
+to select an entry, Enter to focus an interactive example, and Esc to
+return to the gallery. The **Stepper** preview demonstrates async
+`canProceed` validation, back/cancel, completion, restart, ASCII progress
+and vertical progress (space marks details ready, b goes back, a changes
+glyphs, v changes layout, and r restarts). The **Design tokens** preview
+shows shared colors, Unicode/ASCII symbols, borders, spacing and spinner
+frames; press `a` while focused to switch the glyph set.
+
+`npm run build` compiles TypeScript to `dist/`. `npm run dev` runs the compiler in watch mode.
+
+📚 **Full documentation → [ink-ui/docs](https://github.com/rigerc/ink-ui/tree/main/docs)**