@kud/ink-ui 0.7.0 → 0.9.0

package/README.md

@@ -13,11 +13,18 @@
 
 ## Features
 
-- **Ten ready-made components** — Banner, Header, Badge, Spinner, Table, Tabs, FooterHints, LoadingScreen, KeyValue, and SelectableRow, pre-styled and ready to drop in
+- **25 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`, `Switch`, `Toggle`, `SelectableRow`
+  - **Status & feedback** — `Spinner`, `ProgressBar`, `StatusMessage`, `Alert`, `Badge`, `Toast`
+  - **Layout & chrome** — `Banner`, `Header`, `FooterHints`, `KeyValue`, `LoadingScreen`, `ScrollView`
+- **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** — a shared colour palette (`colors`) and spacing scale (`spacing`) to keep every screen consistent
 - **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 ≥ 4` and `react ≥ 18`; `ink-spinner` is the sole production dependency
+- **Peer-dependency light** — only requires `ink ≥ 7` and `react ≥ 19`
 
 ## Install
 
@@ -50,6 +57,33 @@ const App = () => (
 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 "@kud/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>
+  </>
+)
+```
+
 All components accept only the props they need — no theme provider or context required. Design tokens are plain objects:
 
 ```ts

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import React from 'react';
+import React, { ReactNode } from 'react';
 
 type BannerProps = {
     title: string;
@@ -54,6 +54,38 @@ type LoadingScreenProps = {
 };
 declare const LoadingScreen: ({ label }: LoadingScreenProps) => React.JSX.Element;
 
+type ScreenProps = {
+    children: ReactNode;
+    /**
+     * Enter the terminal's alternate buffer so the app owns the whole screen and
+     * the previous scrollback is restored on exit. Defaults to true. Set false to
+     * render full-height inline instead.
+     */
+    altScreen?: boolean;
+};
+declare const Screen: ({ children, altScreen }: ScreenProps) => React.JSX.Element;
+
+type PanelProps = {
+    /** Optional title shown in the panel's header row. */
+    title?: string;
+    /** Accent colour for the border + title when focused. Defaults to the info token. */
+    color?: string;
+    /** When true the border brightens to `color` and the title gains a ● marker. */
+    focused?: boolean;
+    width?: number;
+    height?: number;
+    flexGrow?: number;
+    children: ReactNode;
+};
+declare const Panel: ({ title, color, focused, width, height, flexGrow, children, }: PanelProps) => React.JSX.Element;
+
+type ColumnsProps = {
+    /** Horizontal gap between columns (character cells). Defaults to 1. */
+    gap?: number;
+    children: ReactNode;
+};
+declare const Columns: ({ gap, children }: ColumnsProps) => React.JSX.Element;
+
 type SelectableRowProps = {
     active?: boolean;
     marker?: string;
@@ -160,8 +192,9 @@ type ScrollViewProps = {
     lines: StyledLine[];
     showIndicator?: boolean;
     initialStart?: number;
+    isActive?: boolean;
 };
-declare const ScrollView: ({ lines, showIndicator, initialStart, }: ScrollViewProps) => React.JSX.Element;
+declare const ScrollView: ({ lines, showIndicator, initialStart, isActive, }: ScrollViewProps) => React.JSX.Element;
 
 type TabItem<T extends string = string> = {
     value: T;
@@ -247,4 +280,4 @@ declare const spacing: {
 };
 type Spacing = (typeof spacing)[keyof typeof spacing];
 
-export { Alert, Badge, type BadgeVariant, Banner, type Color, type Column, ConfirmInput, EmailInput, FooterHints, Header, type Hint, type IconMode, KeyValue, LoadingScreen, MultiSelect, type NotifyOptions, OrderedList, 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, UnorderedList, colors, getIconMode, notify, setIconMode, 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, Screen, 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, UnorderedList, colors, getIconMode, notify, setIconMode, spacing };

package/dist/index.js

@@ -1,6 +1,6 @@
-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 React9, { createContext, useContext, useState, useEffect, useRef, useLayoutEffect } from 'react';
 import cliSpinners from 'cli-spinners';
 import { glyphs } from '@kud/glyphs';
 import { spawn } from 'child_process';
@@ -73,6 +73,55 @@ var KeyValue = ({ label, value, labelWidth = 12 }) => /* @__PURE__ */ jsxs(Box,
   isTextValue(value) ? /* @__PURE__ */ jsx(Text, { children: value }) : value
 ] });
 var LoadingScreen = ({ label }) => /* @__PURE__ */ jsx(Box, { padding: 1, children: /* @__PURE__ */ jsx(Spinner, { label }) });
+var ENTER_ALT = "\x1B[?1049h";
+var LEAVE_ALT = "\x1B[?1049l";
+var Screen = ({ children, altScreen = true }) => {
+  const { stdout } = useStdout();
+  const [size, setSize] = useState({
+    columns: stdout.columns || 80,
+    rows: stdout.rows || 24
+  });
+  useEffect(() => {
+    const restore = () => {
+      if (altScreen) stdout.write(LEAVE_ALT);
+    };
+    if (altScreen) stdout.write(ENTER_ALT);
+    const onResize = () => setSize({ columns: stdout.columns || 80, rows: stdout.rows || 24 });
+    stdout.on("resize", onResize);
+    process.on("exit", restore);
+    return () => {
+      stdout.off("resize", onResize);
+      process.off("exit", restore);
+      restore();
+    };
+  }, [stdout, altScreen]);
+  return /* @__PURE__ */ jsx(Box, { width: size.columns, height: size.rows, flexDirection: "column", children });
+};
+var Panel = ({
+  title,
+  color = colors.info,
+  focused = false,
+  width,
+  height,
+  flexGrow,
+  children
+}) => /* @__PURE__ */ jsxs(
+  Box,
+  {
+    flexDirection: "column",
+    width,
+    height,
+    flexGrow,
+    borderStyle: "round",
+    borderColor: focused ? color : colors.muted,
+    overflow: "hidden",
+    children: [
+      title && /* @__PURE__ */ jsx(Text, { color: focused ? color : colors.muted, bold: true, children: focused ? `${title} \u25CF` : title }),
+      children
+    ]
+  }
+);
+var Columns = ({ gap = 1, children }) => /* @__PURE__ */ jsx(Box, { flexDirection: "row", gap, flexGrow: 1, children });
 var isTextValue2 = (value) => typeof value === "string" || typeof value === "number";
 var SelectableRow = ({
   active = false,
@@ -115,7 +164,10 @@ var Select = ({
   return /* @__PURE__ */ jsxs(Box, { flexDirection: "column", children: [
     visible.map((option, i) => {
       const active = start + i === cursor;
-      return /* @__PURE__ */ jsx(SelectableRow, { active, children: /* @__PURE__ */ jsx(Text, { bold: active, color: active ? colors.accent : void 0, children: option.label }) }, option.value);
+      return /* @__PURE__ */ jsxs(SelectableRow, { active, children: [
+        /* @__PURE__ */ jsx(Text, { bold: active, color: active ? colors.info : void 0, children: option.label }),
+        active ? /* @__PURE__ */ jsx(Text, { color: colors.success, children: " \u2713" }) : null
+      ] }, option.value);
     }),
     options.length > count && /* @__PURE__ */ jsx(Text, { dimColor: true, children: `  \u2026 ${options.length} total` })
   ] });
@@ -159,8 +211,8 @@ var MultiSelect = ({
       const active = start + i === cursor;
       const on = selected.has(option.value);
       return /* @__PURE__ */ jsxs(SelectableRow, { active, children: [
-        /* @__PURE__ */ jsx(Text, { color: on ? colors.success : void 0, children: on ? "\u25C9" : "\u25CB" }),
-        /* @__PURE__ */ jsx(Text, { bold: active, color: active ? colors.accent : void 0, children: " " + option.label })
+        /* @__PURE__ */ jsx(Text, { bold: active, color: active ? colors.info : void 0, children: option.label }),
+        on ? /* @__PURE__ */ jsx(Text, { color: colors.success, children: " \u2713" }) : null
       ] }, option.value);
     }),
     options.length > count && /* @__PURE__ */ jsx(Text, { dimColor: true, children: `  \u2026 ${options.length} total` })
@@ -420,10 +472,10 @@ var OrderedListItem = ({ children, _index = 1 }) => /* @__PURE__ */ jsxs(Box, {
 ] });
 var OrderedListRoot = ({ children }) => {
   let n = 0;
-  const numbered = React8.Children.map(children, (child) => {
-    if (React8.isValidElement(child) && child.type === OrderedListItem) {
+  const numbered = React9.Children.map(children, (child) => {
+    if (React9.isValidElement(child) && child.type === OrderedListItem) {
       n += 1;
-      return React8.cloneElement(child, {
+      return React9.cloneElement(child, {
         _index: n
       });
     }
@@ -437,7 +489,8 @@ var OrderedList = Object.assign(OrderedListRoot, {
 var ScrollView = ({
   lines,
   showIndicator = true,
-  initialStart = 0
+  initialStart = 0,
+  isActive = true
 }) => {
   const ref = useRef(null);
   const [height, setHeight] = useState(1);
@@ -450,16 +503,19 @@ var ScrollView = ({
   });
   const maxStart = Math.max(0, lines.length - height);
   const clamped = Math.min(start, maxStart);
-  useInput((input, key) => {
-    if (key.downArrow || input === "j")
-      setStart((s) => Math.min(maxStart, s + 1));
-    if (key.upArrow || input === "k") setStart((s) => Math.max(0, s - 1));
-    if (input === " " || key.pageDown || input === "f")
-      setStart((s) => Math.min(maxStart, s + height));
-    if (key.pageUp || input === "b") setStart((s) => Math.max(0, s - height));
-    if (input === "g") setStart(0);
-    if (input === "G") setStart(maxStart);
-  });
+  useInput(
+    (input, key) => {
+      if (key.downArrow || input === "j")
+        setStart((s) => Math.min(maxStart, s + 1));
+      if (key.upArrow || input === "k") setStart((s) => Math.max(0, s - 1));
+      if (input === " " || key.pageDown || input === "f")
+        setStart((s) => Math.min(maxStart, s + height));
+      if (key.pageUp || input === "b") setStart((s) => Math.max(0, s - height));
+      if (input === "g") setStart(0);
+      if (input === "G") setStart(maxStart);
+    },
+    { isActive }
+  );
   const visible = lines.slice(clamped, clamped + height);
   const hasMore = lines.length > height;
   const atEnd = clamped >= maxStart;
@@ -660,4 +716,4 @@ var notify = (message, options = {}) => {
   child.unref();
 };
 
-export { Alert, Badge, Banner, ConfirmInput, EmailInput, FooterHints, Header, KeyValue, LoadingScreen, MultiSelect, OrderedList, PasswordInput, ProgressBar, ScrollView, Select, SelectableRow, Spinner, StatusMessage, Switch, Table, Tabs, TextInput, Toast, Toggle, UnorderedList, colors, getIconMode, notify, setIconMode, spacing };
+export { Alert, Badge, Banner, Columns, ConfirmInput, EmailInput, FooterHints, Header, KeyValue, LoadingScreen, MultiSelect, OrderedList, Panel, PasswordInput, ProgressBar, Screen, ScrollView, Select, SelectableRow, Spinner, StatusMessage, Switch, Table, Tabs, TextInput, Toast, Toggle, UnorderedList, colors, getIconMode, notify, setIconMode, spacing };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kud/ink-ui",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "React component library for Ink CLIs",
   "type": "module",
   "main": "dist/index.js",
@@ -20,6 +20,7 @@
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",
+    "demo": "tsx src/demo/index.tsx",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest"
@@ -41,6 +42,7 @@
     "react": "19.2.7",
     "react-devtools-core": "7.0.1",
     "tsup": "8.5.1",
+    "tsx": "4.23.1",
     "typescript": "5.9.3",
     "vitest": "4.1.10"
   },