@rigerc/ink-ui 0.0.0-stage → 0.41.1

package/dist/index.d.ts

@@ -0,0 +1,1094 @@
+import * as React from 'react';
+import React__default, { ReactNode } from 'react';
+
+type BannerProps = {
+    title: string;
+    subtitle?: string;
+    icon?: string;
+};
+declare const Banner: ({ title, subtitle, icon }: BannerProps) => React__default.JSX.Element;
+
+type BadgeVariant = "success" | "error" | "warning" | "info";
+type BadgeProps = {
+    children: string;
+    variant?: BadgeVariant;
+};
+declare const Badge: ({ children, variant }: BadgeProps) => React__default.JSX.Element;
+
+type PillVariant = "success" | "error" | "warning" | "info" | "accent" | "muted" | "group";
+type PillTone = "solid" | "soft" | "outline" | "tonal";
+type PillProps = {
+    children: string;
+    variant?: PillVariant;
+    /**
+     * Solid is an EVENT — something happened to the thing (`merged`, `NEW`,
+     * `GONE`). Soft is a CLASSIFICATION — what the thing is (`epic`, `bug`): a
+     * quiet permanent fill from `softColors`, built to sit on every row of a
+     * dark ground without out-shouting the row's news. Outline is the same
+     * classification drawn as a hue-only ring, for a ground where a fill of any
+     * weight is too much. Tonal is CHROME — a count, a slot label — a tint of
+     * the hue over the ground from `tonalColors`, inked in the hue: the
+     * quietest filled form, for what the frame says about itself rather than
+     * row data. The default stays solid so nothing already rendered moves.
+   */
+    tone?: PillTone;
+    /**
+     * Tonal only: the thing you are ON takes the stronger tint from
+     * `tonalStrongColors` and bolds its label. Ignored by every other tone.
+     */
+    strong?: boolean;
+    /**
+     * An explicit fill, for a state the external system INVENTED — GitHub's
+     * merged purple, a CI provider's result colours. The hue is that system's
+     * vocabulary for something that happened, and repainting it as a token would
+     * mislabel the event. Overrides `variant`.
+     *
+     * Never for that system's SKIN. Jira colours its issue types, but an issue
+     * type is a classification, and a classification takes a `variant` chosen by
+     * meaning, not the colour Jira happens to paint it. The test is whether the
+     * hue names a state the reader already knows from the source system, or
+     * merely decorates a category the tokens can already say.
+     */
+    color?: string;
+};
+/**
+ * A rounded label — a category the thing belongs to, or an event that has
+ * just happened to it.
+ *
+ * The law, in one line: the column says where it sits, soft says what it is,
+ * solid says something happened, tonal says where you are. A solid pill is an
+ * event (`merged`, `NEW`, `GONE`) and earns its loud fill by being news; a
+ * soft pill is a classification (`epic`, `bug`, `task`) and takes the quiet
+ * fill from `softColors`, because a type is a fact about the row, not
+ * something that happened to it — it has to be legible on every row without
+ * competing with the one row that has news. Outline is the classification
+ * with no fill at all, for a ground where even a soft block is too much.
+ * Tonal is chrome on the frame — a count, a slot label — the quietest filled
+ * form, with `strong` for the thing you are on. A screen where every pill is
+ * solid has no way to say which pill is the news.
+ *
+ * Reach for it when the word IS the information 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. Solid and soft take
+ * the filled caps, outline the thin ones from the same Powerline Extra block.
+ *
+ * `NO_COLOR` sends solid, soft and tonal to brackets: with the fill stripped,
+ * the caps would be drawing the outline of a pill that is not there. Outline
+ * keeps its caps — they ARE the outline, and there was never a fill for them
+ * to be missing.
+ */
+declare const Pill: ({ children, variant, tone, strong, color, }: PillProps) => React__default.JSX.Element;
+/**
+ * How many columns `<Pill>` occupies for `text` — the label plus its two caps,
+ * whichever tone draws them.
+ *
+ * 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;
+};
+declare const Header: ({ children, subtitle }: HeaderProps) => React__default.JSX.Element;
+
+type SpinnerProps = {
+    label?: string;
+    /** Use ASCII spinner frames on limited terminals. */
+    ascii?: boolean;
+};
+declare const Spinner: ({ label, ascii }: 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, gap, maxWidth, headerColor, }: TableProps<T>) => React__default.JSX.Element;
+
+type Hint = [key: string, label: string];
+type FooterHintsProps = {
+    hints: Hint[];
+    /**
+     * Where this page sits, so the footer can end the same way on every page
+     * of every app: `⌫ back` on a nested page, then `? help`, then `q quit`,
+     * always last. A host passes only its own hints — navigation, actions,
+     * modes — and never these three. Omit it to draw the hints as given.
+     */
+    page?: "root" | "nested";
+    /** Drop `? help` from the tail for an app with no legend. */
+    help?: boolean;
+};
+/** The cells every page ends with, in the order the eye learns once. */
+declare const tailHints: (page: "root" | "nested", help?: boolean) => Hint[];
+declare const FooterHints: ({ hints, page, help }: FooterHintsProps) => React__default.JSX.Element;
+
+/**
+ * The title row's live segment. `news` is something to act on (`● 5 new ·
+ * 38 moved · r apply`) and draws bold in the accent; `busy` is in flight
+ * (`↻ refreshing…`) and draws in the info colour; `quiet` is freshness
+ * (`updated 42m ago`) and draws dim.
+ */
+type PageStatus = {
+    text: string;
+    tone: "news" | "busy" | "quiet";
+};
+type PageProps = {
+    /** The app's name, bold, in the accent. Constant across every page of the app. */
+    title: string;
+    /** One glyph before the name — the app's mark. */
+    icon?: string;
+    /** How many things the page holds; drawn dim as `  127 items  ·  ` with a width-stable count. */
+    count?: number;
+    /** What `count` counts. Defaults to `item`. */
+    noun?: string;
+    /** Whose things these are — `@kud` — drawn plain, never dim: scope is the fact the row exists to state. */
+    user?: string;
+    /** A further scope in the host's words, dim: `work`, or a breadcrumb like `ACME-102 · 3 of 12`. */
+    scope?: string;
+    /** Something worth acting on today — a budget running out — bold in the accent. `critical` turns it red. */
+    alert?: string;
+    critical?: boolean;
+    /** Freshness or news; see `PageStatus`. */
+    status?: PageStatus;
+    /** Free text after the name, dim — for a host with nothing structured to say (`loading…`). */
+    facts?: string;
+    /** The tab strip, only on pages that have one. A detail page passes none and the band is dropped, never left empty. */
+    tabs?: ReactNode;
+    /** Right-aligned, dim, above the hints: `3 of 12`, `↓ 40%`. */
+    counter?: string;
+    /** The host's own hints — navigation, actions, modes. The tail (`⌫ back · ? help · q quit`) is derived from `page`. */
+    hints?: Hint[];
+    /** Root or nested, which decides whether `⌫ back` is drawn. Defaults to root. */
+    page?: "root" | "nested";
+    /** Whether the app has a `?` legend; drops `? help` from the tail when false. */
+    help?: boolean;
+    /**
+     * Whether the frame draws the blank under the title (band two). A body that
+     * draws that band itself — a board whose search box lives there — passes
+     * `false`, or the two blanks together overflow the frame and one is lost.
+     */
+    gap?: boolean;
+    /**
+     * A `FilterBar`, drawn in band two — the blank under the title, which is
+     * where search lives — so every app puts its filter in the same place. It
+     * takes the blank's row rather than adding one, so the body never moves
+     * when a filter opens or closes.
+     */
+    filter?: ReactNode;
+    /**
+     * Size the frame to the terminal, and follow it on resize. Without it the
+     * frame is content-sized: as wide as its container and as tall as its body.
+     * An explicit `width` or `height` still wins over the window on that axis.
+     */
+    fill?: boolean;
+    width?: number;
+    height?: number;
+    children: ReactNode;
+};
+/**
+ * The one frame every screen of an app sits in — list, detail, loading,
+ * error, prompt — so the border and the title row never come and go between
+ * states. Six bands inside a round border: title row, the blank under it,
+ * tabs where the page has them, body, counter, hints. Presentational: it
+ * binds no keys, so a host can take the frame without surrendering its own
+ * keyboard handling. `Panel` stays for inner regions inside `Columns`.
+ *
+ * The title row is the cockpit's, made general: brand · count · user · scope ·
+ * alert · status, then a dotted rule to the edge. The count is padded in
+ * front rather than behind so the header does not shuffle as it changes and
+ * the digits stay against their noun. Only the status segment changes width
+ * from one refresh to the next, and the rule after it absorbs the difference.
+ *
+ * A detail page keeps the app's title row rather than taking the item's key
+ * as its title: the title row is how you know which app you are in and how
+ * stale it is, and neither changes when you open an item. The item's key
+ * belongs in `scope` as a breadcrumb.
+ */
+declare const Page: ({ title, icon, count, noun, user, scope, alert, critical, status, facts, tabs, counter, hints, page, help, gap, filter, fill, width, height, children, }: PageProps) => React__default.JSX.Element;
+/** Lines the frame itself spends around the body: two borders, the title row, the blank under it. */
+declare const PAGE_CHROME = 4;
+
+type KeyValueProps = {
+    label: string;
+    value: React__default.ReactNode;
+    labelWidth?: number;
+};
+declare const KeyValue: ({ label, value, labelWidth }: KeyValueProps) => React__default.JSX.Element;
+
+type LoadingScreenProps = {
+    label: string;
+};
+declare const LoadingScreen: ({ label }: LoadingScreenProps) => React__default.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__default.JSX.Element;
+
+type ColumnsProps = {
+    /** Horizontal gap between columns (character cells). Defaults to 1. */
+    gap?: number;
+    children: ReactNode;
+};
+declare const Columns: ({ gap, children }: ColumnsProps) => React__default.JSX.Element;
+
+type SelectableRowProps = {
+    active?: boolean;
+    marker?: string;
+    children: React__default.ReactNode;
+};
+declare const SelectableRow: ({ active, marker, children, }: SelectableRowProps) => React__default.JSX.Element;
+
+type SelectOption<T extends string = string> = {
+    label: string;
+    value: T;
+};
+type SelectProps<T extends string> = {
+    options: SelectOption<T>[];
+    onChange?: (value: T) => void;
+    onSubmit?: (value: T) => void;
+    defaultValue?: T;
+    isDisabled?: boolean;
+    visibleOptionCount?: number;
+};
+declare const Select: <T extends string>({ options, onChange, onSubmit, defaultValue, isDisabled, visibleOptionCount, }: SelectProps<T>) => React__default.JSX.Element;
+
+type MultiSelectProps<T extends string> = {
+    options: SelectOption<T>[];
+    onChange?: (values: T[]) => void;
+    onSubmit?: (values: T[]) => void;
+    defaultValue?: T[];
+    isDisabled?: boolean;
+    visibleOptionCount?: number;
+};
+declare const MultiSelect: <T extends string>({ options, onChange, onSubmit, defaultValue, isDisabled, visibleOptionCount, }: MultiSelectProps<T>) => React__default.JSX.Element;
+
+type TextInputProps = {
+    placeholder?: string;
+    defaultValue?: string;
+    onChange?: (value: string) => void;
+    onSubmit?: (value: string) => void;
+    /**
+     * Called on `esc`. The value is kept — cancelling blurs the field, it does
+     * not clear it — so the host can drop focus and let its own back key
+     * take over, without a second `useInput` around the box.
+     */
+    onCancel?: () => void;
+    isDisabled?: boolean;
+};
+declare const TextInput: ({ placeholder, defaultValue, onChange, onSubmit, onCancel, isDisabled, }: TextInputProps) => React__default.JSX.Element;
+
+type EmailInputProps = {
+    placeholder?: string;
+    defaultValue?: string;
+    domains?: string[];
+    onChange?: (value: string) => void;
+    onSubmit?: (value: string) => void;
+    isDisabled?: boolean;
+};
+declare const EmailInput: ({ placeholder, defaultValue, domains, onChange, onSubmit, isDisabled, }: EmailInputProps) => React__default.JSX.Element;
+
+type PasswordInputProps = {
+    placeholder?: string;
+    mask?: string;
+    onChange?: (value: string) => void;
+    onSubmit?: (value: string) => void;
+    isDisabled?: boolean;
+};
+declare const PasswordInput: ({ placeholder, mask, onChange, onSubmit, isDisabled, }: PasswordInputProps) => React__default.JSX.Element;
+
+type ConfirmInputProps = {
+    defaultChoice?: "confirm" | "cancel";
+    onConfirm?: () => void;
+    onCancel?: () => void;
+    isDisabled?: boolean;
+};
+declare const ConfirmInput: ({ defaultChoice, onConfirm, onCancel, isDisabled, }: ConfirmInputProps) => React__default.JSX.Element;
+
+type ItemProps$1 = {
+    children: React__default.ReactNode;
+};
+type UnorderedListProps = {
+    children: React__default.ReactNode;
+};
+declare const UnorderedList: (({ children }: UnorderedListProps) => React__default.JSX.Element) & {
+    Item: ({ children }: ItemProps$1) => React__default.JSX.Element;
+};
+
+type ItemProps = {
+    children: React__default.ReactNode;
+    _index?: number;
+};
+type OrderedListProps = {
+    children: React__default.ReactNode;
+};
+declare const OrderedList: (({ children }: OrderedListProps) => React__default.JSX.Element) & {
+    Item: ({ children, _index }: ItemProps) => React__default.JSX.Element;
+};
+
+type Span = {
+    text: string;
+    color?: string;
+    bold?: boolean;
+    dim?: boolean;
+    italic?: boolean;
+};
+type StyledLine = {
+    text: string;
+    color?: string;
+    bold?: boolean;
+    dim?: boolean;
+    spans?: Span[];
+};
+type ScrollViewProps = {
+    lines: StyledLine[];
+    showIndicator?: boolean;
+    initialStart?: number;
+    isActive?: boolean;
+};
+declare const ScrollView: ({ lines, showIndicator, initialStart, isActive, }: ScrollViewProps) => React__default.JSX.Element;
+
+type TabItem<T extends string = string> = {
+    value: T;
+    label: string;
+    /**
+     * A single glyph drawn between the `marker` gutter and the label, one space
+     * before the label — a Nerd Font char, a geometric shape, whatever names the
+     * tab at a glance.
+     *
+     * It is part of the label, not a second gutter: it takes the label's own
+     * style (bold in the accent when active, dim when not) and the active rule
+     * spans icon, space and label together. The marker keeps its own cell and its
+     * own colour, so a pulse appearing beside an icon still moves nothing.
+     * Measured with `string-width` rather than counted, so a wide glyph prices
+     * its own columns.
+     *
+     * It is also what a narrow terminal folds to: when the strip does not fit its
+     * `width`, an inactive tab with an icon drops its label and renders `icon
+     * count`. Omit it and the tab never folds.
+     */
+    icon?: string;
+    /**
+     * How many things the tab holds, drawn as a soft chip beside the label — no
+     * parentheses. `null` means "not known yet" and draws a chip holding `–`,
+     * padded in front to the width of a two-digit count, so the bar does not
+     * shift when the real numbers land. Omit it for a tab with no count. With
+     * `NO_COLOR` the chip falls back to the parenthesised `(–)` form.
+     */
+    count?: number | null;
+    /**
+     * A marker drawn immediately before the label, in its own colour.
+     *
+     * Give every tab one of the SAME WIDTH, or none at all. A marker that appears
+     * on one tab alone pushes every tab after it sideways — which is the whole
+     * reason this is a field rather than something a caller prepends to `label`:
+     * a bar that shifts when news arrives is a bar you have to re-find. A blank of
+     * the right width is how you say "not this one".
+     *
+     * Its own `Text` because the label's colour answers "is this tab active" and a
+     * marker usually answers something else; folded together, the marker would
+     * have to borrow the answer to the wrong question.
+     *
+     * Animating one costs nothing: the cell is already reserved, so a caller
+     * cycling the glyph or the colour per frame moves no layout at all.
+     */
+    marker?: string;
+    markerColor?: string;
+    /**
+     * The true size of what `count` is a window onto, drawn inside the count's
+     * own chip as `count/total` — one chip, never two.
+     *
+     * A field rather than something a caller folds into `label`, for the same
+     * reason `marker` is one — and this one was learned the hard way. A caller
+     * with no channel for "there are more than these" smuggled it into the label
+     * as `Issues +129 (20)`, and `+` is an operator: it tells the reader to add,
+     * with nothing on screen to add it to. The arithmetic even works, which is
+     * what makes it vicious — a reader who obeys gets a real number for a question
+     * nobody asked, with no signal they have misread anything.
+     *
+     * A fraction is part-of-whole, the most over-learned notation there is: page 3
+     * of 12. Nobody computes with a slash. The distinction rides on a glyph rather
+     * than a hue, so it survives dimming, greyscale and colourblindness — and the
+     * magnitude survives with it, which is the half that matters most. `30/37`
+     * and `20/149` say very different things about how far a tab can be trusted,
+     * where a bare truncation flag says only "incomplete".
+     *
+     * With `NO_COLOR` the chip falls back to the parenthesised `(count/total)`
+     * form.
+     *
+     * Omit it when the count IS the whole, so one number keeps meaning "complete"
+     * and two always mean "you are looking at a sample".
+     */
+    total?: number;
+    /**
+     * Optional group name. A divider is drawn between tabs whose group value
+     * changes. Tabs with no group, or the same group as their neighbour, render
+     * without a divider.
+     */
+    group?: string;
+};
+type TabsProps<T extends string> = {
+    active: T;
+    items: TabItem<T>[];
+    /**
+     * The width the strip may spend. Defaults to the terminal's columns; when
+     * that is unknown — piped output, a captured stdout — the strip never folds,
+     * because a fold is a judgement about a visible edge.
+     *
+     * Folding is all-or-nothing and measured, never a breakpoint: when the full
+     * strip (every marker gutter, icon, label, chip, gap and divider) does not
+     * fit, each inactive tab WITH an icon drops its label and renders `icon` plus
+     * its chip. The active tab always keeps its full form, tabs without an icon
+     * never fold, and dividers stay where they were.
+     */
+    width?: number;
+};
+declare const Tabs: <T extends string>({ active, items, width, }: TabsProps<T>) => React__default.JSX.Element;
+
+/** Inspired by the MIT-licensed Stepper in rigerc/nosey. */
+interface StepContext {
+    currentStep: number;
+    totalSteps: number;
+    isFirst: boolean;
+    isLast: boolean;
+    isValidating: boolean;
+    /** Enabled only when the parent opts into the Stepper's Enter shortcut. */
+    keyboardNav: boolean;
+    goNext: () => Promise<void>;
+    goBack: () => Promise<void>;
+    /** Jump without canProceed, but still run onExitStep. */
+    goTo: (index: number) => Promise<void>;
+    cancel: () => void;
+}
+interface StepProps {
+    name: string;
+    canProceed?: boolean | (() => boolean | Promise<boolean>);
+    children: ReactNode | ((context: StepContext) => ReactNode);
+}
+/** Marker component: only the active Step's content is mounted. */
+declare const Step: (_props: StepProps) => null;
+interface StepperProps {
+    /** Step elements or fragments of Steps; key conditional/reorderable Steps. */
+    children: ReactNode;
+    onComplete: () => void;
+    onCancel?: () => void;
+    onStepChange?: (index: number) => void;
+    /** Returning false blocks leaving the current step. */
+    onExitStep?: (index: number) => void | boolean | Promise<void | boolean>;
+    onEnterStep?: (index: number) => void;
+    onError?: (cause: unknown) => void;
+    /** Controlled, zero-based position. */
+    step?: number;
+    initialStep?: number;
+    /**
+     * Listen to Enter to advance. Off by default: Ink broadcasts input to all
+     * active useInput listeners, and nested inputs may already own Enter.
+     * Esc/backspace/q always belong to the host's useAppKeys.
+     */
+    keyboardNav?: boolean;
+    /** Use ASCII symbols in the built-in progress display. */
+    ascii?: boolean;
+    showProgress?: boolean;
+    renderProgress?: (props: StepperProgressProps) => ReactNode;
+}
+interface StepperProgressProps {
+    steps: readonly {
+        id: string;
+        name: string;
+    }[];
+    /** steps.length means all steps have been completed. */
+    currentStep: number;
+    orientation?: "horizontal" | "vertical";
+    /** Use printable ASCII symbols rather than Unicode. */
+    ascii?: boolean;
+}
+declare const StepperProgress: ({ steps, currentStep, orientation, ascii, }: StepperProgressProps) => React__default.JSX.Element;
+declare const useStepper: () => StepContext;
+/** Hints follow the FooterHints visual language; the host still owns Back. */
+declare const StepperNavigation: () => React__default.JSX.Element;
+declare const Stepper: ({ children, onComplete, onCancel, onStepChange, onExitStep, onEnterStep, onError, step, initialStep, keyboardNav, ascii, showProgress, renderProgress, }: StepperProps) => React__default.JSX.Element | null;
+
+type UseTabsOptions<T extends string> = {
+    initial?: T;
+    isActive?: boolean;
+    /**
+     * Whether ←→ move between tabs as well as Tab / Shift+Tab. On by default:
+     * a screen whose ←→ mean something else — a yes/no toggle, a horizontal
+     * scroll — turns them off here rather than fighting the hook for the keys.
+     */
+    arrows?: boolean;
+};
+declare const useTabs: <T extends string>(items: TabItem<T>[], { initial, isActive, arrows }?: UseTabsOptions<T>) => {
+    active: T | undefined;
+    setActive: React.Dispatch<React.SetStateAction<T | undefined>>;
+};
+
+type PaletteItem = {
+    id: string;
+    /** What is matched and, absent `label`, what is drawn. */
+    title: string;
+    /**
+     * What is drawn instead of `title` when a row needs more than one ink — a
+     * ticket key in the accent beside a destination word in `info`. Matching
+     * still reads `title`, so a host that draws rich rows keeps them findable.
+     */
+    label?: ReactNode;
+    /** Rows sharing a group are drawn under one header while the query is empty. */
+    group?: string;
+    /** Dim trailing text: a description, a path, what the row will do. */
+    hint?: string;
+    keywords?: string[];
+    /**
+     * One cell, drawn before the title. Every row in a list carries a marker of
+     * the same width or none — the cell is reserved for all rows the moment one
+     * row has one, so a marker arriving never shifts its neighbours.
+     */
+    marker?: string;
+    markerColor?: string;
+};
+/**
+ * A message with a tone. `muted` (the default) is what the query did not find
+ * or what is not configured; `error` is a failure, drawn in `colors.error`
+ * behind the error glyph so it reads as one without the hue. `onSubmit` makes
+ * Enter act while the message shows — a failure the host can retry — where a
+ * bare message leaves Enter a no-op.
+ */
+type PaletteMessage = {
+    text: string;
+    tone?: "muted" | "error";
+    onSubmit?: () => void;
+};
+type CommandPaletteProps = {
+    /** The rows to draw, in order. The palette never filters them. */
+    items: PaletteItem[];
+    query: string;
+    onQueryChange: (query: string) => void;
+    onSelect: (id: string) => void;
+    /** `esc`. The value is the host's, so nothing here clears it. */
+    onClose?: () => void;
+    /**
+     * One line drawn where the rows would be, when there are none: what
+     * the query did not find, or what is not configured. Enter is a no-op while
+     * it shows, unless the message carries `onSubmit`. Never a row, so the
+     * cursor cannot land on it. A string is a muted message; pass a
+     * `PaletteMessage` for the error tone.
+     */
+    message?: string | PaletteMessage;
+    /**
+     * One muted line drawn where the rows would be while the palette is still
+     * waiting for its first query: `items` is empty and the query is too, e.g.
+     * "type a ticket key". Loses to `message`, and never shows beside rows —
+     * once the host has rows (grouped or flat) they are drawn instead.
+     */
+    emptyHint?: string;
+    placeholder?: string;
+    width?: number;
+    /** Visual lines the row area may spend before it scrolls. */
+    maxRows?: number;
+    hints?: Hint[];
+    isActive?: boolean;
+};
+/**
+ * A launcher: a query line over a list of rows, one cursor, Enter runs the row
+ * under it. Dumb by design — it holds no query state of its own and does no
+ * filtering, so the same component serves a host that narrows a fixed command
+ * tree (hand `fuzzyFilter` to `onQueryChange`) and a host that DERIVES rows from
+ * the query, where `ACC-1234` becomes two verbs. Uncontrolled in the keyboard
+ * sense: the query field owns typing, `↑↓` move the cursor, `⏎` selects, `esc`
+ * calls `onClose`. Mount it as the topmost layer and let the app's `useAppKeys`
+ * stand down while it is up, or `esc` will close it and go back a level too.
+ */
+declare const CommandPalette: ({ items, query, onQueryChange, onSelect, onClose, message, emptyHint, placeholder, width, maxRows, hints, isActive, }: CommandPaletteProps) => React__default.JSX.Element;
+
+/**
+ * The static-list half of a launcher, as a pure function: the items that match
+ * `query`, substring hits first, in the caller's order within each rank. An
+ * empty or whitespace query returns every item unchanged — the palette then
+ * draws them grouped — so a host that only ever has a fixed command tree can
+ * hand this straight to `onQueryChange` and never filter itself.
+ *
+ * Deliberately NOT inside `CommandPalette`: the palette takes whatever rows the
+ * host gives it and knows nothing about where they came from, which is what
+ * lets a host derive rows from the query (a ticket key becomes two verbs) rather
+ * than narrow a preset list. Both shapes share one component; only this helper
+ * is optional.
+ */
+declare const fuzzyFilter: (items: PaletteItem[], query: string) => PaletteItem[];
+
+type UseListCursorOptions = {
+    initial?: number;
+    wrap?: boolean;
+    vimKeys?: boolean;
+    isActive?: boolean;
+};
+declare const useListCursor: (length: number, { initial, wrap, vimKeys, isActive, }?: UseListCursorOptions) => {
+    cursor: number;
+    setCursor: React.Dispatch<React.SetStateAction<number>>;
+    moveCursor: (delta: number) => void;
+};
+
+type UseAppKeysOptions = {
+    /**
+     * The host's peel, called on `esc` and `backspace`: close the topmost layer
+     * it owns — a focused input, an overlay, a detail screen — and return
+     * `true`. Return `false` when there was nothing to pop; `atRoot` then says
+     * what happens. A `void` return counts as handled.
+     */
+    onBack?: () => boolean | void;
+    /** What `q` does. Defaults to Ink's `exit()`, which restores the terminal. */
+    onQuit?: () => void;
+    /** `esc` with nothing left to pop: nothing (the default) or quit. */
+    atRoot?: "ignore" | "quit";
+    /** False while a text field has focus — `q` is a letter there and `backspace` deletes. */
+    isActive?: boolean;
+};
+/**
+ * The three keys that belong to the APP, never to a screen: `q` quits from
+ * anywhere, `esc` and `backspace` go back exactly one level. Mounted once, at
+ * the root — Ink runs every active `useInput` on every key with no order and
+ * no propagation, so "who gets `esc`" is only ever solved by there being one
+ * claimant. Not a back stack: a host's layers are a priority order over its
+ * own booleans, and that order stays in the host as `onBack`.
+ *
+ * `esc` at the root does nothing by default. A key that sometimes quits is a
+ * key you flinch from; quitting has its own key.
+ */
+declare const useAppKeys: ({ onBack, onQuit, atRoot, isActive, }?: UseAppKeysOptions) => void;
+
+type UseFilterModeOptions = {
+    /** False while something above the list owns the keyboard — an overlay, a palette. */
+    isActive?: boolean;
+    /** Called after the term changes, with the new one. Typically `setCursor(0)`. */
+    onChange?: (term: string | null) => void;
+};
+/**
+ * A list filter with two modes, vim's split between inserting and acting.
+ *
+ * TYPING: `/` opens the field and every printable key goes into the term.
+ * `↵` and `esc` both leave typing and KEEP the filter (an empty term leaves
+ * no filter); `ctrl+u` clears the term and stays in the field.
+ * ↑↓ are not taken, so a host's `useListCursor` still walks the matches while
+ * the field is open — pass it `vimKeys: !typing` so `j`/`k` type instead.
+ *
+ * KEPT: the filter stays applied and the letter keys are the host's hotkeys
+ * again. `/` goes back INTO the term rather than starting over — the whole
+ * point of keeping it is being able to refine it. `esc` here is not this
+ * hook's: a kept filter is the bottom layer of the host's peel, so the host's
+ * `onBack` clears it through `clear()`, after every layer pushed above it.
+ * `esc` twice therefore clears a filter from anywhere.
+ *
+ * Owns its own `useInput`, like `useListCursor`. The host stands its other
+ * handlers down while `typing` is true — `useAppKeys({ isActive: !typing })`
+ * and an early return in its hotkey handler — because inside the field `q` is
+ * a letter, and Ink hands every key to every active hook.
+ *
+ * Extracted from gh-cockpit's inbox, where `/` used to clear on the way back
+ * in, so refining a kept query meant typing it again from scratch.
+ */
+declare const useFilterMode: ({ isActive, onChange, }?: UseFilterModeOptions) => {
+    term: string | null;
+    typing: boolean;
+    caret: number;
+    active: boolean;
+    clear: () => void;
+    hints: Hint[];
+};
+
+type FilterBarProps = {
+    /** From `useFilterMode`. `null` draws nothing. */
+    term: string | null;
+    /** From `useFilterMode`. Draws the caret. */
+    typing: boolean;
+    /** From `useFilterMode`. Where the caret sits; defaults to end-of-term. */
+    caret?: number;
+    /** How many rows survive the filter. Omit to draw no count. */
+    matches?: number;
+};
+/**
+ * The line a `useFilterMode` filter draws: `/ term▏   3 matches`. The caret
+ * is there only while typing, which is the one visible difference between a
+ * field that takes your keys and a filter that is merely standing — so it is
+ * the thing that tells you whether `c` is a letter or a command.
+ *
+ * Presentational and keyless. It sits in the `Page`'s `filter` slot, band two,
+ * so every app draws its filter in the same place.
+ */
+declare const FilterBar: ({ term, typing, caret, matches }: FilterBarProps) => React__default.JSX.Element | null;
+
+type SwitchValue = "left" | "right";
+type SwitchProps = {
+    left: string;
+    right: string;
+    value: SwitchValue;
+    color?: string;
+};
+declare const Switch: ({ left, right, value, color, }: SwitchProps) => React__default.JSX.Element;
+
+type ToggleProps = {
+    label: string;
+    on: boolean;
+    color?: string;
+};
+declare const Toggle: ({ label, on, color }: ToggleProps) => React__default.JSX.Element;
+
+type ToggleSwitchProps = {
+    on: boolean;
+    label?: string;
+    onColor?: string;
+    offColor?: string;
+};
+declare const ToggleSwitch: ({ on, label, onColor, offColor, }: ToggleSwitchProps) => React__default.JSX.Element;
+
+type UpdateBannerProps = {
+    name: string;
+    current: string;
+    latest: string;
+    command: string;
+    onConfirm: () => void;
+    onDecline: () => void;
+    focused?: boolean;
+};
+declare const UpdateBanner: ({ name, current, latest, command, onConfirm, onDecline, focused, }: UpdateBannerProps) => React__default.JSX.Element;
+
+type ProgressBarProps = {
+    value: number;
+    width?: number;
+    color?: string;
+    trackColor?: string;
+};
+declare const ProgressBar: ({ value, width, color, trackColor, }: ProgressBarProps) => React__default.JSX.Element;
+
+type SkeletonBarProps = {
+    /** Cells to draw. */
+    width: number;
+    /**
+     * Settle for the plain track bar. Defaults to true; still draws static when
+     * stdout is not a TTY or motion is opted out, whatever is passed.
+     */
+    animate?: boolean;
+    /**
+     * A frame on the shared clock, passed by `SkeletonRows` so every row ticks
+     * together. Omit it and the bar keeps its own clock — that is the standalone
+     * behaviour.
+     */
+    frame?: number;
+    /**
+     * Stagger within a shared clock, in frames. `SkeletonRows` passes each row's
+     * lag; a standalone bar leaves it at 0.
+     */
+    rowOffset?: number;
+};
+/**
+ * A placeholder for text that has not arrived: a run of `█` over the track
+ * ground, swept left to right by a soft highlight band that loops after a
+ * short pause.
+ *
+ * Animated on purpose — amended 2026-10-05. This used to be static, on the
+ * grounds that a shimmer is motion with nothing behind it and the status slot
+ * is where a page says it is busy. In practice a first load with nothing on
+ * screen reads as frozen without motion: the status slot says busy, but there
+ * is no body yet for it to reassure. Still draws the plain static bar when
+ * there is nowhere for motion to show — stdout piped, `NO_MOTION` or
+ * `REDUCE_MOTION` set — or when `animate` is false.
+ */
+declare const SkeletonBar: ({ width, animate, frame, rowOffset, }: SkeletonBarProps) => React__default.JSX.Element;
+type SkeletonRowsProps = {
+    /** How many bars to draw. Blank gap rows are extra. */
+    rows: number;
+    /**
+     * Each bar's length as a fraction (0–1) of the width left after `indent`,
+     * cycled in order: row `i` takes `widths[i % widths.length]`. Deterministic,
+     * so the placeholder does not reshuffle on every render.
+     */
+    widths: number[];
+    /** Insert one blank row after every `gapEvery` bars, never after the last. */
+    gapEvery?: number;
+    /** Leading blank cells before every bar. Defaults to 0. */
+    indent?: number;
+    /**
+     * The width the fractions are taken of. Omit it and the rows measure the
+     * space their container gives them, re-measuring when the terminal resizes.
+     */
+    width?: number;
+    /**
+     * Settle every row for the plain track bar. Passed through to each
+     * `SkeletonBar`; defaults to true.
+     */
+    animate?: boolean;
+};
+/**
+ * The body of a list that has nothing to show yet: `rows` skeleton bars whose
+ * lengths cycle through `widths`, grouped by blank rows when `gapEvery` is set.
+ * Only for the first load, when nothing is known — once real rows exist, keep
+ * them on screen and say busy in `Page`'s status slot instead.
+ *
+ * One clock for the group: a single interval here hands each bar its frame,
+ * staggered by row so the wave travels diagonally down-and-across rather than
+ * marching in lockstep.
+ */
+declare const SkeletonRows: ({ rows, widths, gapEvery, indent, width, animate, }: SkeletonRowsProps) => React__default.JSX.Element;
+
+type StatusVariant = "success" | "error" | "warning" | "info";
+
+type StatusMessageProps = {
+    variant?: StatusVariant;
+    children: React__default.ReactNode;
+};
+declare const StatusMessage: ({ variant, children, }: StatusMessageProps) => React__default.JSX.Element;
+
+type AlertProps = {
+    variant?: StatusVariant;
+    title?: string;
+    children: React__default.ReactNode;
+};
+declare const Alert: ({ variant, title, children }: AlertProps) => React__default.JSX.Element;
+
+type ToastProps = {
+    message: string;
+    variant?: StatusVariant;
+    duration?: number;
+    onDone?: () => void;
+};
+declare const Toast: ({ message, variant, duration, onDone, }: ToastProps) => React__default.JSX.Element | null;
+
+type IconMode = "text" | "nerd";
+declare const setIconMode: (mode: IconMode) => void;
+declare const getIconMode: () => IconMode;
+
+type NotifyOptions = {
+    title?: string;
+    subtitle?: string;
+    sound?: boolean | string;
+};
+declare const notify: (message: string, options?: NotifyOptions) => void;
+
+/**
+ * The raw hexes behind every token, tuned to the dark ground `#1a1b27`.
+ * Dark-only and truecolour assumed; on a 256-colour terminal chalk downsamples
+ * them (`tokens.test.ts` checks the pairs that must stay apart). Hex rather
+ * than ANSI names, because the terminal theme repaints a named colour.
+ */
+declare const palette: {
+    readonly orange: "#FF8C00";
+    readonly amber: "#FFB400";
+    readonly yellow: "#FFCB6B";
+    readonly red: "#FF5364";
+    readonly mint: "#5FD7A7";
+    readonly green: "#4ADE80";
+    readonly coral: "#FF6B6B";
+    readonly blue: "#82AAFF";
+    readonly cyan: "#89DDFF";
+    readonly purple: "#C792EA";
+    readonly ink: "#E4E4EC";
+    readonly grey: "#999999";
+    readonly slate: "#75767E";
+    readonly dusk: "#5C5E73";
+    readonly selection: "#30364A";
+    readonly track: "#2B323D";
+    readonly trackHigh: "#6B7480";
+    readonly ground: "#1A1B27";
+};
+type Palette = (typeof palette)[keyof typeof palette];
+/**
+ * `secondary` is the third neutral: text that is context rather than the
+ * answer — a row's labels beside its title — and must read as its own tier.
+ * Default foreground is the answer, `muted` (measured #75767E) is furniture,
+ * and a middle tier drawn in either of those is not "quiet", it is absent: on
+ * a dark ground `dimColor` inks at L* 50 and the eye files it with the age
+ * column. Hex rather than an ANSI name because the tier only exists as a
+ * measured step — `#999999` is L* 63, 5.9:1 on `#1c1c28` and 13 L* above the
+ * faint, which reads as a decision; `#888888` is 7 L* above it and reads as a
+ * rendering wobble. Tuned to the dark ground every consumer already commits
+ * to; a light-theme terminal would need its own value.
+ *
+ * `track` is the unlit ground of a measured strip: the empty part of a
+ * `ProgressBar`, and the base of a `SkeletonBar` standing in for text that
+ * has not arrived. Furniture, never a state — kept clearly darker than any
+ * fill drawn over it, so the two separate by lightness for every reader.
+ *
+ * `trackHighlight` is the crest of that ground: the lighter step a skeleton's
+ * shimmer band peaks at while it sweeps, with the falloff each side blended
+ * between the two. Still ground, never ink — nothing is ever written in it,
+ * which is why it can sit well above `track` without becoming a state.
+ */
+declare const colors: {
+    readonly accent: "#FF8C00";
+    readonly secondary: "#999999";
+    readonly muted: "#75767E";
+    readonly success: "#5FD7A7";
+    readonly error: "#FF5364";
+    readonly warning: "#FFB400";
+    readonly info: "#89DDFF";
+    readonly group: "#C792EA";
+    readonly track: "#2B323D";
+    readonly trackHighlight: "#6B7480";
+    readonly ticket: "#FFCB6B";
+    readonly pr: "#FF8C00";
+    readonly link: "#82AAFF";
+    readonly added: "#4ADE80";
+    readonly removed: "#FF6B6B";
+    readonly pending: "#75767E";
+    readonly dim: "#5C5E73";
+    readonly selection: "#30364A";
+};
+type Color = (typeof colors)[keyof typeof colors];
+/**
+ * The soft family: a filled block that is quiet enough to live on every row.
+ *
+ * Solid `colors` are events and shout on purpose. A permanent classifier —
+ * an issue type, a category — sits on a dark ground beside the row's real
+ * news, and a saturated fill there out-shouts it. These are the same
+ * semantics, desaturated and darkened so white ink reads on all seven,
+ * measured against `#1e1f26` for a deutan/protan reader. Hex rather than
+ * ANSI names because the point is a fixed, measured contrast, and a named
+ * colour is whatever the theme says it is.
+ *
+ * `group` is the container of the rows beneath it (an epic). It is
+ * deliberately not the accent hue: an accent-filled block on the same row
+ * as an accent-coloured key steals the key's colour.
+ */
+declare const softColors: {
+    readonly accent: "#8f4611";
+    readonly muted: "#474a54";
+    readonly success: "#2e6d4c";
+    readonly error: "#7e2a2c";
+    readonly warning: "#8a6a1e";
+    readonly info: "#3c74a2";
+    readonly group: "#524389";
+};
+type SoftColor = (typeof softColors)[keyof typeof softColors];
+/**
+ * The tonal family: a tint of the hue over the ground, inked in the hue — the
+ * quietest filled form, for chrome on the frame (a count, a slot label)
+ * rather than row data.
+ *
+ * Each fill is a linear blend of the variant's solid hue over `#1A1B27` at a
+ * fixed weight (16% rest, 28% strong), computed once and written in as a
+ * literal — no runtime mixing. The accent and muted pairs are frozen
+ * measurements rather than exact mixes: the focus pill is about 16% orange,
+ * the active tab chip about 28%, and the inactive tab chip a step above the
+ * ground that never dims into it. Measured like `softColors`, for the same
+ * reason: a tint is a fixed contrast, and a named colour is whatever the
+ * theme says it is.
+ *
+ * `tonalStrongColors` is the thing you are ON — the active tab's chip — a
+ * stronger tint of the same hue with the same ink, plus a bold label at the
+ * call site. The keys are the seven `Pill` variant names, written out rather
+ * than imported: tokens never reach back into components.
+ */
+declare const tonalColors: Record<"success" | "error" | "warning" | "info" | "accent" | "muted" | "group", {
+    fill: string;
+    ink: string;
+}>;
+declare const tonalStrongColors: Record<"success" | "error" | "warning" | "info" | "accent" | "muted" | "group", {
+    fill: string;
+    ink: string;
+}>;
+/**
+ * Priority is ordinal, so it steps in lightness, never hue: a red chevron
+ * would claim a failure. The chevron's shape carries the rank.
+ */
+declare const priorityColors: {
+    readonly highest: "#E4E4EC";
+    readonly high: "#E4E4EC";
+    readonly medium: "#999999";
+    readonly low: "#75767E";
+    readonly lowest: "#75767E";
+};
+type PriorityColor = (typeof priorityColors)[keyof typeof priorityColors];
+declare const spacing: {
+    readonly xs: 1;
+    readonly sm: 2;
+    readonly md: 3;
+    readonly lg: 4;
+};
+type Spacing = (typeof spacing)[keyof typeof spacing];
+/**
+ * Semantic terminal glyphs, inspired by the token categories in rigerc/nosey.
+ * The default glyphs match ink-ui's existing StatusMessage and Select
+ * conventions. Shape carries meaning; color only reinforces it.
+ */
+type Symbols = {
+    /** Filled state marker used by switches, toggles and focused panels. */
+    active: string;
+    /** Nested square markers for lists. */
+    nestedBullet: string;
+    nestedBulletEmpty: string;
+    /** Dotted horizontal rule for page headers. */
+    rule: string;
+    /** Terminal input caret. */
+    caret: string;
+    /** Vertical group separator. */
+    verticalLine: string;
+    success: string;
+    error: string;
+    warn: string;
+    info: string;
+    pointer: string;
+    checkboxChecked: string;
+    checkboxUnchecked: string;
+    bullet: string;
+    pending: string;
+    ellipsis: string;
+    line: string;
+    barFull: string;
+    barEmpty: string;
+};
+declare const symbols: Symbols;
+declare const asciiSymbols: Symbols;
+/** Border presets are style names accepted by Ink's Box borderStyle prop. */
+type BorderStyle = "round" | "single" | "bold" | "double" | "classic";
+declare const borders: {
+    readonly base: "round";
+    readonly focus: "bold";
+    readonly ascii: "classic";
+};
+/** Motion and fallback frames are visual tokens, not animation state. */
+declare const motion: {
+    readonly spinner: readonly ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+    readonly asciiSpinner: readonly ["-", "\\", "|", "/"];
+    readonly intervalMs: 80;
+    /** Skeleton shimmer has a faster independent rhythm. */
+    readonly skeletonIntervalMs: 70;
+};
+
+export { Alert, Badge, type BadgeVariant, Banner, type BorderStyle, type Color, type Column, type ColumnAlign, type ColumnOverflow, Columns, CommandPalette, ConfirmInput, EmailInput, FilterBar, FooterHints, Header, type Hint, type IconMode, KeyValue, LoadingScreen, MultiSelect, type NotifyOptions, OrderedList, PAGE_CHROME, Page, type PageStatus, type Palette, type PaletteItem, type PaletteMessage, Panel, PasswordInput, Pill, type PillTone, type PillVariant, type PriorityColor, ProgressBar, ScrollView, Select, type SelectOption, SelectableRow, SkeletonBar, SkeletonRows, type SoftColor, type Spacing, type Span, Spinner, StatusMessage, type StatusVariant, Step, type StepContext, type StepProps, Stepper, StepperNavigation, StepperProgress, type StepperProgressProps, type StepperProps, type StyledLine, Switch, type SwitchValue, type Symbols, type TabItem, Table, Tabs, TextInput, Toast, Toggle, ToggleSwitch, UnorderedList, UpdateBanner, asciiSymbols, borders, colors, fuzzyFilter, getIconMode, motion, notify, palette, pillWidth, priorityColors, setIconMode, softColors, spacing, symbols, tailHints, tonalColors, tonalStrongColors, useAppKeys, useFilterMode, useListCursor, useStepper, useTabs };