@kud/ink-ui 0.16.0 → 0.18.0

package/AGENTS.md

@@ -13,7 +13,7 @@ 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
+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.
 
@@ -56,6 +56,7 @@ differently on every screen.
 | 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 |
 
@@ -78,6 +79,13 @@ import { colors, spacing } from "@kud/ink-ui"
 A literal like `color="orange"` or `color="#FF8C00"` is wrong even when it
 renders identically — it breaks the moment a token moves.
 
+The one exception is `<Pill color>`, for a surface mirroring an external
+system whose colours ARE its vocabulary — GitHub's merged purple, a CI
+provider's result colours. The test is whether the hue is a **fact about the
+thing being labelled**; a colour picked because it looks right is still a token
+job. The pill inks itself against whatever fill it is given, so a caller reaching
+for this never picks a foreground.
+
 **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

package/dist/index.d.ts

@@ -15,6 +15,56 @@ 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;
+    /**
+     * An explicit fill, for a caller that owns a palette of its own — one
+     * mirroring an external system whose colours ARE the vocabulary (GitHub's
+     * merged purple, a CI provider's result colours). Overrides `variant`.
+     *
+     * Not a way round the token rule. A colour picked because it looks nice is
+     * still wrong here; the test is whether the hue is a fact about the thing
+     * being labelled rather than a preference about the label.
+     */
+    color?: string;
+};
+/**
+ * A filled, rounded label — a category the thing belongs to, or an event that
+ * has just happened to it.
+ *
+ * Reach for it when the word IS the information (`epic`, `draft`, `blocked`,
+ * `NEW`) 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, color }: 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 +371,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,47 @@ 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 inkFor = (fill) => {
+  const hex = /^#([0-9a-f]{6})$/i.exec(fill)?.[1];
+  if (!hex) return "white";
+  const channel = (i) => {
+    const c = parseInt(hex.slice(i, i + 2), 16) / 255;
+    return c <= 0.03928 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
+  };
+  const luminance = 0.2126 * channel(0) + 0.7152 * channel(2) + 0.0722 * channel(4);
+  return (luminance + 0.05) / 0.05 >= 1.05 / (luminance + 0.05) ? "black" : "white";
+};
+var Pill = ({ children, variant = "muted", color }) => {
+  const fill = color ?? FILL[variant];
+  const ink = color ? inkFor(color) : INK[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, 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 +934,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.16.0",
+  "version": "0.18.0",
   "description": "React component library for Ink CLIs",
   "type": "module",
   "main": "dist/index.js",