@textui/widgets 0.1.0

package/src/display/index.ts

@@ -0,0 +1,55 @@
+import type { ComponentDefinition } from '@textui/core';
+import { Alert } from './alert.js';
+import { Badge } from './badge.js';
+import { Card } from './card.js';
+import { EmptyState } from './empty-state.js';
+import { ErrorState } from './error-state.js';
+import { Heading } from './heading.js';
+import { KeyValue } from './key-value.js';
+import { Label } from './label.js';
+import { Marquee } from './marquee.js';
+import { Progress } from './progress.js';
+import { Skeleton } from './skeleton.js';
+import { Spinner } from './spinner.js';
+import { StatusDot } from './status-dot.js';
+import { Timeline } from './timeline.js';
+
+/**
+ * Display components.
+ *
+ * The rule that shapes all of them: **meaning never depends on colour alone.**
+ * A degraded service is a different glyph as well as a different colour,
+ * because a 16-colour ssh session, a colourblind reader and a piped log all
+ * lose the colour and keep the glyph.
+ */
+export * from './alert.js';
+export * from './badge.js';
+export * from './card.js';
+export * from './empty-state.js';
+export * from './error-state.js';
+export * from './heading.js';
+export * from './key-value.js';
+export * from './label.js';
+export * from './marquee.js';
+export * from './progress.js';
+export * from './skeleton.js';
+export * from './spinner.js';
+export * from './status-dot.js';
+export * from './timeline.js';
+
+export const DISPLAY_COMPONENTS: ComponentDefinition[] = [
+  { component: 'Heading', category: 'display', renderer: { kind: 'function', render: Heading }, role: 'heading', description: 'Section heading, three levels.' },
+  { component: 'Label', category: 'display', renderer: { kind: 'function', render: Label }, role: 'label', description: 'Secondary text with a semantic tone.' },
+  { component: 'Badge', category: 'display', renderer: { kind: 'function', render: Badge }, variants: ['solid', 'outline', 'ghost'], description: 'Small status marker; carries a glyph as well as a colour.' },
+  { component: 'StatusDot', category: 'display', renderer: { kind: 'function', render: StatusDot }, role: 'status', description: 'The shared status vocabulary: up, degraded, down.' },
+  { component: 'Alert', category: 'feedback', renderer: { kind: 'function', render: Alert }, role: 'alert', description: 'A message with an icon and a tone.' },
+  { component: 'Card', category: 'display', renderer: { kind: 'function', render: Card }, description: 'Bordered block with a title.' },
+  { component: 'KeyValue', category: 'data', renderer: { kind: 'function', render: KeyValue }, description: 'Aligned label/value pairs.' },
+  { component: 'Progress', category: 'feedback', renderer: { kind: 'function', render: Progress }, role: 'progressbar', description: 'Determinate or indeterminate bar, sub-cell resolution.' },
+  { component: 'Spinner', category: 'feedback', renderer: { kind: 'function', render: Spinner }, role: 'status', description: 'Animated activity indicator.' },
+  { component: 'Marquee', category: 'display', renderer: { kind: 'function', render: Marquee }, role: 'marquee', description: 'Text too long for its box, read by sliding it while it has the cursor.' },
+  { component: 'Skeleton', category: 'feedback', renderer: { kind: 'function', render: Skeleton }, description: 'Loading placeholder.' },
+  { component: 'EmptyState', category: 'feedback', renderer: { kind: 'function', render: EmptyState }, description: 'Nothing here, and what to do about it.' },
+  { component: 'ErrorState', category: 'feedback', renderer: { kind: 'function', render: ErrorState }, role: 'alert', description: 'A failure, with its message.' },
+  { component: 'Timeline', category: 'data', renderer: { kind: 'function', render: Timeline }, description: 'Ordered events down a rail.' },
+];

package/src/display/key-value.ts

@@ -0,0 +1,32 @@
+import type { BoxProps, SemanticVariant } from '@textui/core';
+import { defineComponent, h, stringWidth } from '@textui/core';
+import { TONE as TONE_COLOR } from '../tone.js';
+
+export interface KeyValueProps extends BoxProps {
+  items: { label: string; value: string; tone?: SemanticVariant }[];
+  /** Cells reserved for labels. Computed from the longest when unset. */
+  labelWidth?: number;
+  columns?: number;
+}
+
+/** Structured data as aligned label/value pairs. */
+export const KeyValue = defineComponent<KeyValueProps>('KeyValue', (props) => {
+  const { items, labelWidth, columns = 1, ...rest } = props;
+  const width = labelWidth ?? Math.max(0, ...items.map((i) => stringWidth(i.label)));
+
+  const rows: typeof items[] = [];
+  for (let i = 0; i < items.length; i += columns) rows.push(items.slice(i, i + columns));
+
+  return h('box', { direction: 'column', ...rest },
+    ...rows.map((row, i) =>
+      h('box', { key: i, direction: 'row', gap: 2 },
+        ...row.map((item, j) =>
+          h('box', { key: j, direction: 'row', gap: 1, flex: 1 },
+            h('box', { width }, h('text', { content: item.label, fg: 'muted' })),
+            h('text', { content: item.value, fg: item.tone ? TONE_COLOR[item.tone] : undefined, truncate: 'end', flex: 1 }),
+          ),
+        ),
+      ),
+    ),
+  );
+});

package/src/display/label.ts

@@ -0,0 +1,11 @@
+import type { SemanticVariant, TextProps } from '@textui/core';
+import { defineComponent, h } from '@textui/core';
+import { TONE as TONE_COLOR } from '../tone.js';
+
+export interface LabelProps extends TextProps {
+  tone?: SemanticVariant;
+}
+
+export const Label = defineComponent<LabelProps>('Label', ({ tone = 'muted', ...props }) =>
+  h('text', { role: 'label', fg: TONE_COLOR[tone], ...props }),
+);

package/src/display/marquee.ts

@@ -0,0 +1,88 @@
+import type { TextProps } from '@textui/core';
+import {
+  defineComponent,
+  h,
+  stringWidth,
+  useEffect,
+  useMeasure,
+  useRef,
+  useRuntime,
+  useState,
+  useTicker,
+} from '@textui/core';
+
+export interface MarqueeProps extends TextProps {
+  content: string;
+  /**
+   * Slide, or rest.
+   *
+   * Off is the resting state and the common one: a list of twenty rows is
+   * twenty still labels, and the one under the cursor is the one that moves.
+   * It is also what keeps the cost honest - a marquee that is not sliding
+   * holds no ticker at all, so a menu is one animation and not one per row.
+   */
+  active?: boolean;
+  /** Cells a second. */
+  speed?: number;
+  /** How long it waits at each end, in milliseconds. */
+  dwell?: number;
+  fps?: number;
+}
+
+/**
+ * Text too long for its box, read by sliding it.
+ *
+ * The alternative was making something else give up room, and in a list there
+ * is nothing else to take it from: a row is a label and a description and both
+ * of them are the answer to "what is this". Truncating is fine for the rows you
+ * are scanning past and useless for the one you have stopped on - which is
+ * exactly the row a marquee costs anything for.
+ *
+ * Rests at the start, slides to the end, waits, and comes back. Not a loop
+ * that wraps around: text that reappears from the right while its own tail is
+ * still leaving reads as two strings rather than one long one.
+ *
+ * Nothing moves where animation is off - a pipe, a CI log, a reader who asked
+ * for stillness - and there it is an ordinary truncated label.
+ */
+export const Marquee = defineComponent<MarqueeProps>('Marquee', (props) => {
+  const { content, active = false, speed = 8, dwell = 900, fps = 10, ...rest } = props;
+  const runtime = useRuntime();
+  // What the last layout gave this text. Zero on the first pass, which is the
+  // one where nothing is known and the honest answer is the whole string.
+  const width = useMeasure().width;
+  const travel = width > 0 ? Math.max(0, stringWidth(content) - width) : 0;
+  const sliding = active && travel > 0 && !runtime.animation.disabled;
+
+  // The ticker's own frame number, not a count of callbacks. A clock driven
+  // by hand - a test, a static render - advances several frames in one call,
+  // and a counter that adds one per call runs at whatever rate it was driven
+  // at rather than at the rate it asked for.
+  const [frame, setFrame] = useState(0);
+  const seen = useRef(0);
+  const from = useRef(0);
+  useTicker((at) => { seen.current = at; setFrame(at - from.current); }, { fps, enabled: sliding });
+  // Back to the start whenever it stops or the words change, so the row you
+  // leave is the row you saw when you arrived at it.
+  useEffect(() => { from.current = seen.current; setFrame(0); }, [sliding, content]);
+
+  if (!sliding) return h('text', { content, truncate: 'end', ...rest });
+
+  const perCell = Math.max(1, Math.round(fps / speed));
+  const hold = Math.max(1, Math.round((dwell / 1000) * fps));
+  const slide = travel * perCell;
+  const cycle = hold + slide + hold + slide;
+  const at = frame % cycle;
+  const offset = at < hold
+    ? 0
+    : at < hold + slide
+      ? Math.floor((at - hold) / perCell)
+      : at < hold + slide + hold
+        ? travel
+        : travel - Math.floor((at - hold - slide - hold) / perCell);
+
+  // Pinned to what it measured. Without this the sliced string is narrower
+  // than the whole one, the layout hands the box back a different width, and
+  // the next frame measures something new - a row that shivers.
+  return h('text', { content: content.slice(offset, offset + width), width, ...rest });
+});

package/src/display/progress.ts

@@ -0,0 +1,92 @@
+import type { BoxProps, SemanticVariant } from '@textui/core';
+import { defineComponent, h, useFrame, useTheme } from '@textui/core';
+import { TONE as TONE_COLOR } from '../tone.js';
+
+export interface ProgressProps extends BoxProps {
+  /** 0..1. Omit for an indeterminate bar. */
+  value?: number;
+  total?: number;
+  label?: string;
+  /** Show the percentage after the bar. */
+  showValue?: boolean;
+  tone?: SemanticVariant;
+  barWidth?: number;
+  /**
+   * A fixed gutter for the label, so a stack of bars starts at one column.
+   *
+   * Labels are their own width otherwise, which is right for one bar and
+   * wrong for three: "download", "index" and "working" each push their track
+   * to a different place and the group reads as three unrelated widgets.
+   * Nothing here can measure its siblings, so whoever stacks them says.
+   */
+  labelWidth?: number;
+  /**
+   * Push the bar away from the label, to the right edge of the row.
+   *
+   * The label's cell stretches, so it stays at the left and
+   * the track ends up hard against the right - which is what makes a column of
+   * these read as a table rather than as a ragged stack.
+   *
+   * Different from `labelWidth`, which pads the *label* to a fixed gutter: use
+   * that when the bars should start at one column, and this when they should
+   * end at one. Needs a row wider than its contents to have any effect, so the
+   * caller has to have given it a width or a `flex`.
+   */
+  spacer?: boolean;
+}
+
+/**
+ * A progress bar with sub-cell resolution: the partial block glyphs give eight
+ * steps per cell, so a 20-cell bar moves smoothly rather than in 5% jumps.
+ */
+export const Progress = defineComponent<ProgressProps>('Progress', (props) => {
+  const theme = useTheme();
+  const {
+    value, total = 1, label, showValue = true, tone = 'primary', barWidth, labelWidth,
+    spacer, ...rest
+  } = props;
+  const frame = useFrame(8);
+
+  const width = barWidth ?? 20;
+  const ratio = value === undefined ? 0 : Math.max(0, Math.min(1, value / total));
+
+  let bar: string;
+  if (value === undefined) {
+    // Indeterminate: a block that travels the track.
+    const pos = frame % Math.max(1, width);
+    bar = Array.from({ length: width }, (_, i) =>
+      Math.abs(i - pos) < 2 ? theme.glyphs.progressFull : theme.glyphs.progressEmpty,
+    ).join('');
+  } else {
+    const exact = ratio * width;
+    const full = Math.floor(exact);
+    const partials = theme.glyphs.progressPartial;
+    const remainder = exact - full;
+    const partialIndex = Math.floor(remainder * partials.length);
+    const partial = full < width && remainder > 0 ? (partials[partialIndex] ?? '') : '';
+    bar =
+      theme.glyphs.progressFull.repeat(full) +
+      partial +
+      theme.glyphs.progressEmpty.repeat(Math.max(0, width - full - (partial ? 1 : 0)));
+  }
+
+  return h('box', { role: 'progressbar', label, direction: 'row', gap: 1, ...rest },
+    label !== undefined
+      ? h('text', {
+          content: label,
+          fg: 'muted',
+          ...(labelWidth === undefined ? {} : { width: labelWidth, truncate: 'end' as const }),
+          // The label's own cell stretches, rather than a `spacer` child going
+          // in beside it. A child would be free but its *gap* would not: with
+          // `gap: 1` on the row, one more child is one more cell, so a row
+          // sized exactly to its contents would truncate the bar to make room
+          // for a space. Stretching what is already there costs nothing.
+          ...(spacer === true ? { flex: 1 } : {}),
+        })
+      : spacer === true ? h('spacer', {}) : null,
+    h('text', { content: bar, fg: TONE_COLOR[tone] }),
+    showValue && value !== undefined
+      ? h('text', { content: `${Math.round(ratio * 100)}%`, fg: 'muted' })
+      : null,
+  );
+});

package/src/display/skeleton.ts

@@ -0,0 +1,34 @@
+import type { BoxProps } from '@textui/core';
+import { defineComponent, h } from '@textui/core';
+
+export interface SkeletonProps extends BoxProps {
+  lines?: number;
+  /** Width of each line, in cells or as a fraction of the box. */
+  widths?: number[];
+}
+
+/**
+ * The shape of content that has not arrived.
+ *
+ * Drawn in `borderStrong` rather than `borderSubtle`, and the difference is
+ * whether it is there at all: against the dark theme's canvas, subtle is
+ * 1.24:1 - the glyphs are in the buffer and nobody can see them, which is a
+ * placeholder that fails at the one thing it does. Strong is 2.28:1, still
+ * quiet enough not to read as content.
+ *
+ * `fg` overrides it, because how loud a placeholder should be depends on what
+ * it is standing in for.
+ */
+export const Skeleton = defineComponent<SkeletonProps>('Skeleton', ({ lines = 3, widths, fg, ...rest }) =>
+  h('box', { direction: 'column', gap: 0, ...rest },
+    ...Array.from({ length: lines }, (_, i) =>
+      h('box', {
+        key: i,
+        height: 1,
+        width: widths?.[i] ?? (i === lines - 1 ? '60%' : '100%'),
+        fill: '░',
+        fg: fg ?? 'borderStrong',
+      }),
+    ),
+  ),
+);

package/src/display/spinner.ts

@@ -0,0 +1,20 @@
+import type { BoxProps, SemanticVariant } from '@textui/core';
+import { defineComponent, h, useFrame, useTheme } from '@textui/core';
+import { TONE as TONE_COLOR } from '../tone.js';
+
+export interface SpinnerProps extends BoxProps {
+  label?: string;
+  tone?: SemanticVariant;
+}
+
+export const Spinner = defineComponent<SpinnerProps>('Spinner', ({ label, tone = 'accent', ...rest }) => {
+  const theme = useTheme();
+  const frame = useFrame(10);
+  const frames = theme.glyphs.spinner;
+  const glyph = frames[frame % frames.length] ?? frames[0] ?? '*';
+
+  return h('box', { role: 'status', direction: 'row', gap: 1, ...rest },
+    h('text', { content: glyph, fg: TONE_COLOR[tone] }),
+    label ? h('text', { content: label }) : null,
+  );
+});

package/src/display/status-dot.ts

@@ -0,0 +1,24 @@
+import type { BoxProps, StyleColor } from '@textui/core';
+import { defineComponent, h, useTheme } from '@textui/core';
+
+export interface StatusDotProps extends BoxProps {
+  status: 'up' | 'down' | 'degraded' | 'unknown' | 'pending';
+  label?: string;
+}
+
+/** The status vocabulary, so "degraded" looks the same everywhere. */
+export const StatusDot = defineComponent<StatusDotProps>('StatusDot', ({ status, label, ...rest }) => {
+  const theme = useTheme();
+  const map = {
+    up: { glyph: theme.glyphs.bulletFilled, fg: 'success' as StyleColor },
+    degraded: { glyph: theme.glyphs.bulletHalf, fg: 'warning' as StyleColor },
+    down: { glyph: theme.glyphs.bulletHollow, fg: 'danger' as StyleColor },
+    pending: { glyph: theme.glyphs.bulletHollow, fg: 'info' as StyleColor },
+    unknown: { glyph: theme.glyphs.separator, fg: 'muted' as StyleColor },
+  }[status];
+
+  return h('box', { role: 'status', label: label ?? status, direction: 'row', gap: 1, ...rest },
+    h('text', { content: map.glyph, fg: map.fg }),
+    label ? h('text', { content: label }) : null,
+  );
+});

package/src/display/timeline.ts

@@ -0,0 +1,47 @@
+import type { BoxProps, SemanticVariant } from '@textui/core';
+import { defineComponent, h, useTheme } from '@textui/core';
+import { TONE as TONE_COLOR } from '../tone.js';
+
+export interface TimelineProps extends BoxProps {
+  items: {
+    time?: string;
+    title: string;
+    description?: string;
+    tone?: SemanticVariant;
+    icon?: string;
+  }[];
+}
+
+export const Timeline = defineComponent<TimelineProps>('Timeline', ({ items, ...rest }) => {
+  const theme = useTheme();
+  return h('box', { direction: 'column', ...rest },
+    ...items.map((item, i) =>
+      h('box', { key: i, direction: 'row', gap: 1 },
+        // The gutter is as tall as the entry beside it, not two rows.
+        //
+        // The connector used to be a single `text`, so an entry whose
+        // description wrapped - or which had a description at all, in a narrow
+        // column - got one cell of line under its bullet and then a gap, and
+        // the thread that makes a timeline a timeline broke at every long
+        // entry. `fill` paints the glyph into every cell it is given and
+        // `flex` gives it whatever the row turned out to be.
+        h('box', { direction: 'column', width: 1, alignSelf: 'stretch' },
+          h('text', { content: item.icon ?? theme.glyphs.bulletFilled, fg: item.tone ? TONE_COLOR[item.tone] : 'accent' }),
+          i < items.length - 1
+            // `minHeight` as well as `flex`: an entry with nothing but a
+            // title is one row tall, so a purely elastic connector would get
+            // no rows at all and two short entries would sit against each
+            // other with no thread between them. One row is the floor, and
+            // what a short entry has always had.
+            ? h('box', { flex: 1, minHeight: 1, fill: theme.borderChars().left, fg: 'borderSubtle' })
+            : null),
+        h('box', { direction: 'column', flex: 1 },
+          h('box', { direction: 'row', gap: 1 },
+            h('text', { content: item.title, bold: true }),
+            item.time ? h('spacer', { flex: 1 }) : null,
+            item.time ? h('text', { content: item.time, fg: 'muted' }) : null),
+          item.description ? h('text', { content: item.description, fg: 'muted', wrap: 'word' }) : null),
+      ),
+    ),
+  );
+});

package/src/find.ts

@@ -0,0 +1,138 @@
+import type { BindingPath, ReactiveStore } from '@textui/core';
+import { useStoreValue } from '@textui/core';
+
+/**
+ * Finding things in text.
+ *
+ * The query lives in the store rather than in whatever component is showing
+ * the text, for the usual reason: a search box, a status bar counting matches
+ * and the viewer painting them are three things that have to agree, and the
+ * only way three things agree is by reading one answer.
+ *
+ * The matching itself is here and not in the editor because a viewer wants it
+ * too, and so will a results panel: given a string and a query, which spans
+ * matched. Nothing here knows what a caret is.
+ */
+
+export const FIND_ROOT = '$/ui/find';
+export const FIND_QUERY = `${FIND_ROOT}/query` as BindingPath;
+export const FIND_CASE = `${FIND_ROOT}/matchCase` as BindingPath;
+/** Bumped to ask whoever is showing the text to move to the next match. */
+export const FIND_STEP = `${FIND_ROOT}/step` as BindingPath;
+
+export interface FindQuery {
+  text: string;
+  matchCase?: boolean;
+}
+
+/** Where one match is: the line it is on, and the columns it covers. */
+export interface Match {
+  line: number;
+  start: number;
+  end: number;
+}
+
+/**
+ * Every match in a document, in reading order.
+ *
+ * Overlapping matches are not a thing: a search steps past what it found, so
+ * `aa` in `aaaa` is two matches and not three. That is what every editor does
+ * and what "next" means when you press it twice.
+ */
+export function findMatches(text: string, query: FindQuery): Match[] {
+  const needle = query.matchCase === true ? query.text : query.text.toLowerCase();
+  if (needle === '') return [];
+
+  const out: Match[] = [];
+  const lines = text.split('\n');
+  for (let line = 0; line < lines.length; line++) {
+    const raw = lines[line] as string;
+    const haystack = query.matchCase === true ? raw : raw.toLowerCase();
+    let at = haystack.indexOf(needle);
+    while (at !== -1) {
+      out.push({ line, start: at, end: at + needle.length });
+      at = haystack.indexOf(needle, at + needle.length);
+    }
+  }
+  return out;
+}
+
+/**
+ * The match a caret should go to next, wrapping at the end.
+ *
+ * From *after* the caret, not from the caret: pressing next while sitting on a
+ * match has to move, or "next" is a key that does nothing. Backwards is the
+ * mirror, and both wrap, because a search that stops at the end of the file is
+ * a search you have to restart by hand.
+ */
+export function stepMatch(
+  matches: Match[],
+  from: { line: number; column: number },
+  direction: 1 | -1,
+): number {
+  if (matches.length === 0) return -1;
+
+  if (direction === 1) {
+    const found = matches.findIndex(
+      (m) => m.line > from.line || (m.line === from.line && m.start > from.column),
+    );
+    return found === -1 ? 0 : found;
+  }
+
+  /*
+   * Backwards, from *before* the caret - and the caret is usually sitting at
+   * the end of the match it just stepped to, so "before" has to mean the match
+   * *ends* before it. Comparing starts instead finds the match the caret is
+   * standing in and calls that the previous one, which is a key that does
+   * nothing every other press.
+   */
+  for (let i = matches.length - 1; i >= 0; i--) {
+    const m = matches[i] as Match;
+    if (m.line < from.line || (m.line === from.line && m.end < from.column)) return i;
+  }
+  return matches.length - 1;
+}
+
+/** Which match the caret is sitting inside, or -1. */
+export function matchAt(matches: Match[], at: { line: number; column: number }): number {
+  return matches.findIndex(
+    (m) => m.line === at.line && at.column >= m.start && at.column <= m.end,
+  );
+}
+
+export function readQuery(store: ReactiveStore): FindQuery {
+  return {
+    text: store.get<string>(FIND_QUERY) ?? '',
+    matchCase: store.get<boolean>(FIND_CASE) === true,
+  };
+}
+
+export function setQuery(store: ReactiveStore, text: string): void {
+  store.set(FIND_QUERY, text);
+}
+
+/**
+ * Ask whoever is showing the text to move.
+ *
+ * A counter rather than a command, so the thing that moves is the thing that
+ * knows where the caret is - and so two panels showing the same file each move
+ * their own.
+ */
+export function stepFind(store: ReactiveStore, direction: 1 | -1): void {
+  const at = store.get<{ n: number }>(FIND_STEP);
+  store.set(FIND_STEP, { n: (at?.n ?? 0) + 1, direction });
+}
+
+export interface FindHandle {
+  query: FindQuery;
+  /** Changes when somebody asks for the next match. */
+  step: { n: number; direction: 1 | -1 } | undefined;
+}
+
+/** The current query, and the ask to move, for a component showing text. */
+export function useFind(): FindHandle {
+  const text = useStoreValue<string>(FIND_QUERY, '') ?? '';
+  const matchCase = useStoreValue<boolean>(FIND_CASE, false) === true;
+  const step = useStoreValue<{ n: number; direction: 1 | -1 }>(FIND_STEP);
+  return { query: { text, matchCase }, step };
+}

package/src/form/danger-zone.ts

@@ -0,0 +1,34 @@
+import type { BoxProps } from '@textui/core';
+import { defineComponent, h, useTheme } from '@textui/core';
+import { Button } from '../control/index.js';
+
+export interface DangerZoneProps extends BoxProps {
+  title?: string;
+  description?: string;
+  actionLabel: string;
+  onAction?(): void;
+  /** Require typing this exact text before the action is enabled. */
+  confirmText?: string;
+}
+
+export const DangerZone = defineComponent<DangerZoneProps>('DangerZone', (props) => {
+  const theme = useTheme();
+  const {
+    title = 'Danger zone', description, actionLabel, onAction, confirmText, ...rest
+  } = props;
+
+  return h('box', {
+    border: { style: theme.border, color: 'danger' },
+    padding: [0, 1],
+    direction: 'column',
+    title: ` ${title} `,
+    ...rest,
+  },
+    description ? h('text', { content: description, fg: 'muted', wrap: 'word' }) : null,
+    confirmText
+      ? h('text', { content: `Type "${confirmText}" to confirm.`, fg: 'subtle' })
+      : null,
+    h('box', { direction: 'row', justify: 'end' },
+      h(Button, { label: actionLabel, tone: 'danger', variant: 'outline', onPress: onAction })),
+  );
+});

package/src/form/field.ts

@@ -0,0 +1,61 @@
+import type { BoxProps } from '@textui/core';
+import { defineComponent, h, useTheme } from '@textui/core';
+import { useFormContext } from './shared.js';
+
+export interface FieldProps extends BoxProps {
+  name: string;
+  label?: string;
+  hint?: string;
+  required?: boolean;
+  /** Cells reserved for the label, so a column of fields lines up. */
+  labelWidth?: number;
+  /** Label above the control rather than beside it. */
+  stacked?: boolean;
+}
+
+/**
+ * A labelled control with its error.
+ *
+ * The error line is always reserved when one could appear, so a form does not
+ * jump a row every time validation fires.
+ */
+export const Field = defineComponent<FieldProps>('Field', (props) => {
+  const theme = useTheme();
+  const form = useFormContext();
+  const { name, label, hint, required, labelWidth, stacked, children, ...rest } = props;
+  const error = form.errorFor(name);
+
+  const labelNode = label
+    ? h('box', { direction: 'row', gap: 0, width: stacked ? undefined : labelWidth },
+        h('text', { content: label, fg: error ? 'danger' : 'muted' }),
+        required ? h('text', { content: '*', fg: 'danger' }) : null)
+    : null;
+
+  return h('box', { direction: 'column', ...rest },
+    // Centred, so the label sits on the control's line of text rather than on
+    // the top edge of its frame.
+    //
+    // A row stretches its children, so a one-row label beside a three-row
+    // bordered input was drawn at the top of three rows - level with the
+    // border, one above the text it names. Borderless controls are one row
+    // and were fine, which is why a form mixing the two had half its labels
+    // aligned and half of them a row high.
+    h('box', {
+      direction: stacked ? 'column' : 'row',
+      gap: stacked ? 0 : 1,
+      ...(stacked ? {} : { align: 'center' as const }),
+    },
+      labelNode,
+      h('box', { flex: 1 }, children)),
+    error
+      ? h('box', { direction: 'row', gap: 1 },
+          stacked ? null : h('box', { width: labelWidth }),
+          h('text', { content: theme.glyphs.warning, fg: 'danger' }),
+          h('text', { content: error, fg: 'danger', wrap: 'word' }))
+      : hint
+        ? h('box', { direction: 'row', gap: 1 },
+            stacked ? null : h('box', { width: labelWidth }),
+            h('text', { content: hint, fg: 'subtle' }))
+        : null,
+  );
+});