@textui/widgets 0.1.0

package/src/chart/shared.ts

@@ -0,0 +1,112 @@
+import type { BoxProps, SemanticVariant, StyleColor } from '@textui/core';
+import { defineComponent, h, useTheme } from '@textui/core';
+
+export const TONE: Record<SemanticVariant, StyleColor> = {
+  default: 'text', primary: 'primary', secondary: 'secondary', accent: 'accent',
+  success: 'success', warning: 'warning', danger: 'danger', info: 'info', muted: 'muted',
+};
+
+export interface Series {
+  values: number[];
+  label?: string;
+  tone?: SemanticVariant;
+}
+
+export function bounds(values: number[], min?: number, max?: number): [number, number] {
+  if (values.length === 0) return [min ?? 0, max ?? 1];
+  const lo = min ?? Math.min(...values);
+  const hi = max ?? Math.max(...values);
+  return lo === hi ? [lo, lo + 1] : [lo, hi];
+}
+
+/** Take `width` samples, averaging when there is more data than cells. */
+export function resample(values: number[], width: number): number[] {
+  if (width <= 0) return [];
+  if (values.length === 0) return new Array<number>(width).fill(0);
+  if (values.length === width) return values;
+
+  if (values.length < width) {
+    // Fewer points than cells: stretch across the width. Padding with the
+    // first value would invent a flat stretch of history that never happened,
+    // which on a chart reads as "nothing was going on" rather than "no data".
+    return Array.from({ length: width }, (_, i) => {
+      const position = (i * (values.length - 1)) / (width - 1 || 1);
+      const low = Math.floor(position);
+      const high = Math.min(values.length - 1, low + 1);
+      const t = position - low;
+      return (values[low] as number) * (1 - t) + (values[high] as number) * t;
+    });
+  }
+
+  const out: number[] = [];
+  const bucket = values.length / width;
+  for (let i = 0; i < width; i++) {
+    const start = Math.floor(i * bucket);
+    const end = Math.max(start + 1, Math.floor((i + 1) * bucket));
+    const slice = values.slice(start, end);
+    out.push(slice.reduce((a, b) => a + b, 0) / slice.length);
+  }
+  return out;
+}
+
+export const VerticalBars = defineComponent<{
+  data: { label: string; value: number; tone?: SemanticVariant }[];
+  max: number;
+  height: number;
+  /** Cells across, per bar. One is a hairline; two or three read as bars. */
+  columnWidth?: number;
+}>('VerticalBars', ({ data, max, height, columnWidth = 1, ...rest }) => {
+  const theme = useTheme();
+  const blocks = theme.glyphs.blocks;
+
+  // Each cell holds eight levels, so a column is a run of full blocks plus one
+  // partial - the same trick as the progress bar, turned on its side.
+  const columns = data.map((item) => {
+    const units = Math.round((item.value / max) * height * blocks.length);
+    const full = Math.floor(units / blocks.length);
+    const partialIndex = units % blocks.length;
+    const cells: string[] = [];
+    for (let row = height - 1; row >= 0; row--) {
+      if (row < full) cells.push(blocks[blocks.length - 1] as string);
+      else if (row === full && partialIndex > 0) cells.push(blocks[partialIndex - 1] as string);
+      else cells.push(' ');
+    }
+    return { cells: cells.reverse(), item };
+  });
+
+  return h('box', { direction: 'column', ...rest },
+    ...Array.from({ length: height }, (_, row) =>
+      h('box', { key: row, direction: 'row', gap: 1 },
+        ...columns.map((col, i) =>
+          h('text', {
+            key: i,
+            // The glyph repeated, not a wider glyph: a column is one cell of
+            // vertical resolution and `columnWidth` of horizontal, so widening
+            // it must not change how the value is drawn.
+            content: (col.cells[height - 1 - row] as string).repeat(columnWidth),
+            fg: TONE[col.item.tone ?? 'accent'],
+          })))),
+    h('box', { direction: 'row', gap: 1 },
+      ...data.map((item, i) =>
+        // As much of the label as the bar is wide, padded so the next one
+        // starts over its own bar rather than sliding left under a short name.
+        h('text', {
+          key: i,
+          content: item.label.slice(0, columnWidth).padEnd(columnWidth),
+          fg: 'subtle',
+        }))),
+  );
+});
+
+export interface LineChartProps extends BoxProps {
+  series: Series[];
+  min?: number;
+  max?: number;
+  chartWidth?: number;
+  chartHeight?: number;
+  /** Draw a y-axis with the bounds labelled. */
+  axis?: boolean;
+  /** Fill under the line. */
+  area?: boolean;
+  format?(value: number): string;
+}

package/src/chart/sparkline.ts

@@ -0,0 +1,46 @@
+import type { BoxProps, SemanticVariant } from '@textui/core';
+import { defineComponent, h, useTheme } from '@textui/core';
+import { TONE, bounds, resample } from './shared.js';
+
+export interface SparklineProps extends BoxProps {
+  values: number[];
+  min?: number;
+  max?: number;
+  tone?: SemanticVariant;
+  /** Cells wide. Values are sampled to fit. */
+  chartWidth?: number;
+  /** Print the latest value after the line. */
+  showValue?: boolean;
+  format?(value: number): string;
+}
+
+/** One row of block glyphs: eight levels per cell. */
+export const Sparkline = defineComponent<SparklineProps>('Sparkline', (props) => {
+  const theme = useTheme();
+  const {
+    values, min, max, tone = 'accent', chartWidth,
+    showValue = false, format, ...rest
+  } = props;
+
+  const blocks = theme.glyphs.blocks;
+  const width = chartWidth ?? values.length;
+  const sampled = resample(values, width);
+  const [lo, hi] = bounds(sampled, min, max);
+
+  const line = sampled
+    .map((v) => {
+      const ratio = (v - lo) / (hi - lo);
+      const index = Math.max(0, Math.min(blocks.length - 1, Math.round(ratio * (blocks.length - 1))));
+      return blocks[index] as string;
+    })
+    .join('');
+
+  const latest = values[values.length - 1];
+
+  return h('box', { direction: 'row', gap: 1, ...rest },
+    h('text', { content: line, fg: TONE[tone] }),
+    showValue && latest !== undefined
+      ? h('text', { content: format ? format(latest) : String(latest), fg: 'muted' })
+      : null,
+  );
+});

package/src/control/button.ts

@@ -0,0 +1,184 @@
+import type {
+  BorderStyle,
+  BoxProps,
+  SemanticVariant,
+  StyleColor,
+  SurfaceVariant,
+} from '@textui/core';
+import { defineComponent, h, useFocus, useInput, useTheme } from '@textui/core';
+import { ON_TONE, TONE } from '../tone.js';
+
+/** A border that takes up space without drawing anything. */
+const BLANK_BORDER = {
+  topLeft: ' ', top: ' ', topRight: ' ', right: ' ',
+  bottomRight: ' ', bottom: ' ', bottomLeft: ' ', left: ' ',
+  cross: ' ', teeTop: ' ', teeBottom: ' ', teeLeft: ' ', teeRight: ' ',
+};
+
+export interface ButtonProps extends BoxProps {
+  label: string;
+  tone?: SemanticVariant;
+  variant?: SurfaceVariant;
+  icon?: string;
+  /** Shortcut hint rendered after the label. */
+  hint?: string;
+  onPress?(): void;
+  autoFocus?: boolean;
+  /**
+   * How much of the screen the button takes, and how heavy its edge is.
+   *
+   * `md` is a button: three rows, the theme's edge. `sm` is one row with no
+   * edge at all, for a toolbar or a row of buttons that must not out-weigh
+   * the fields beside them. `lg` is three rows with a heavy one.
+   *
+   * It matters most when filled. A solid `md` draws its edge in half-blocks,
+   * so it stands the same height as the outline button next to it without
+   * reading as a heavier object; `lg` fills the edge cells too and becomes
+   * the whole rectangle, which is what solid used to do at every size - and
+   * why one row of buttons looked bigger than the row above it.
+   */
+  size?: 'sm' | 'md' | 'lg';
+}
+
+export const Button = defineComponent<ButtonProps>('Button', (props) => {
+  const theme = useTheme();
+  const {
+    label, tone = 'default', variant = 'outline', icon, hint,
+    onPress, disabled, autoFocus, size = 'md', ...rest
+  } = props;
+
+  const focus = useFocus({ disabled, autoFocus });
+  useInput(
+    (event) => {
+      if (disabled) return false;
+      if (event.name === 'enter' || event.name === 'space') {
+        onPress?.();
+        return true;
+      }
+      return false;
+    },
+    { focusId: focus.id },
+  );
+
+  // Selection inverts.
+  //
+  // At rest a button is a line and a label in its tone; selected, the tone
+  // becomes the background and the label flips to the colour written for it.
+  // Recolouring only the border was too quiet to find - and next to a filled
+  // button it read backwards, because the filled one looked like the selected
+  // one however hard the border tried.
+  const filled = (focus.focused || props.selected === true) && !disabled;
+  const resolvedTone = filled && tone === 'default' ? 'primary' : tone;
+
+  const color = disabled ? 'disabled' : TONE[resolvedTone];
+  const onColor = disabled ? 'text' : ON_TONE[resolvedTone];
+
+  // `sm` has no ring, so nothing here reserves one.
+  const ringed = size !== 'sm' && theme.border !== 'none';
+
+  // A solid button reserves the same ring an outline one draws, filled with
+  // its own background rather than left out. Without it the two are one row
+  // and three rows tall, and a dialog's OK sits a line above its Cancel.
+  const solidBorder = {
+    style: theme.border,
+    color: focus.focused ? ('focus' as StyleColor) : undefined,
+    ...(focus.focused ? {} : { chars: BLANK_BORDER }),
+  };
+
+  // The tone fills the inside of the frame, not the frame itself. A cell
+  // carries one background, so a background on the button's own box lands on
+  // the border glyphs too - rounded corners included - and the button reads as
+  // a coloured block rather than a filled button. Hanging the fill on an inner
+  // box leaves the ring on whatever is behind it. The wrapper is there whether
+  // or not the button is filled, so focusing one does not reshape its tree.
+  //
+  // A solid button is inset too at `md`, which is the whole of the size fix:
+  // hanging the fill on an inner box leaves the ring to be drawn in
+  // half-blocks rather than filled through, so it weighs what the outline
+  // button beside it weighs. `lg` keeps the fill on the outer box - the ring
+  // cells take the tone as well and the button becomes a solid rectangle.
+  const inset = variant === 'ghost' || variant === 'link'
+    ? false
+    : variant !== 'solid' || (ringed && size === 'md');
+
+  // Filled, the frame becomes the fill's own edge.
+  //
+  // A cell holds one background, so filling the box the ordinary way colours
+  // its border glyphs too and the button reads as a block; filling only the
+  // inside leaves the border cell on the backdrop, and a gap runs between the
+  // frame and the fill. `half` is drawn from block elements whose coloured
+  // half faces inward, so the ring meets the inside with nothing between. It
+  // measures the same as the line border it replaces - one cell a side - so
+  // focus changes how a button looks without changing its size.
+  //
+  // A theme that asked for no border, or for ascii, is left alone: both are
+  // deliberate looks, and `half` degrades to ascii anyway on a terminal that
+  // cannot draw block elements.
+  const filledBorder: BorderStyle =
+    theme.border === 'none' || theme.border === 'ascii' ? theme.border : 'half';
+
+  // The edge, by size. `lg` asks for the heaviest line the theme can draw and
+  // falls back to the theme's own where there is none to ask for.
+  const edge: BorderStyle = size === 'lg' && theme.border !== 'ascii' ? 'bold' : theme.border;
+
+  const style =
+    variant === 'solid'
+      ? size === 'sm' || !ringed
+        // One row, filled. No ring to reserve and nothing to align to.
+        ? { bg: color, fg: onColor }
+        : size === 'lg'
+          // The fill runs under the ring, so the whole rectangle is the button.
+          ? { bg: color, fg: onColor, border: solidBorder }
+          // The ring is drawn from block elements whose coloured half faces
+          // inward: it meets the fill with no gap and stands half as heavy.
+          : { border: { style: filledBorder, color }, fg: color }
+      : variant === 'ghost' || variant === 'link'
+        ? (filled ? { bg: color, fg: onColor } : { fg: color })
+        : size === 'sm' || !ringed
+          ? (filled ? { bg: color, fg: onColor } : { fg: color })
+          : { border: { style: filled ? filledBorder : edge, color }, fg: color };
+
+  const padding = variant === 'ghost' || variant === 'link' ? 0 : ([0, 1] as [number, number]);
+
+  const content = [
+    icon ? h('text', { content: icon }) : null,
+    h('text', { content: label }),
+    // On a filled button the hint has to sit on the tone too; `muted` against
+    // a solid colour is the one combination that is never readable.
+    hint ? h('text', { content: hint, fg: filled ? onColor : 'muted', dim: !filled }) : null,
+  ];
+
+  return h('box', {
+    id: focus.id,
+    role: 'button',
+    label,
+    direction: 'row',
+    // The inner box owns the run of the label - gap, padding and centring -
+    // whenever there is one, so the two paths measure the same.
+    gap: inset ? 0 : 1,
+    // Centred, so a button stretched by the row it sits in keeps its label on
+    // the same line as its neighbours' labels.
+    align: 'center',
+    padding: inset ? 0 : padding,
+    bold: inset ? undefined : focus.focused,
+    underline: focus.focused && (variant === 'ghost' || variant === 'link'),
+    onClick: () => { if (!disabled) onPress?.(); },
+    ...style,
+    ...rest,
+  },
+    inset
+      ? h('box', {
+          // Grow, so the fill reaches the frame on a button the row stretched.
+          flex: 1,
+          direction: 'row',
+          gap: 1,
+          align: 'center',
+          padding,
+          bold: focus.focused,
+          // A solid button is filled whether or not it has focus - that is
+          // what solid means. An outline one fills only when it takes focus.
+          ...(variant === 'solid' || filled ? { bg: color, fg: onColor } : {}),
+        }, ...content)
+      : content,
+  );
+});

package/src/control/checkbox.ts

@@ -0,0 +1,48 @@
+import type { BoxProps } from '@textui/core';
+import { defineComponent, h, useFocus, useInput, useTheme } from '@textui/core';
+
+export interface CheckboxProps extends BoxProps {
+  label?: string;
+  checked?: boolean;
+  /** Neither checked nor unchecked - a parent of mixed children. */
+  indeterminate?: boolean;
+  onChange?(checked: boolean): void;
+}
+
+export const Checkbox = defineComponent<CheckboxProps>('Checkbox', (props) => {
+  const theme = useTheme();
+  const { label, checked = false, indeterminate, onChange, disabled, ...rest } = props;
+  const focus = useFocus({ disabled });
+
+  useInput(
+    (event) => {
+      if (disabled) return false;
+      if (event.name === 'space' || event.name === 'enter') {
+        onChange?.(!checked);
+        return true;
+      }
+      return false;
+    },
+    { focusId: focus.id },
+  );
+
+  const glyph = indeterminate
+    ? theme.glyphs.checkboxMixed
+    : checked ? theme.glyphs.checkboxOn : theme.glyphs.checkboxOff;
+
+  return h('box', {
+    id: focus.id,
+    role: 'checkbox',
+    label,
+    selected: checked,
+    direction: 'row',
+    gap: 1,
+    fg: disabled ? 'disabled' : focus.focused ? 'accent' : undefined,
+    bold: focus.focused,
+    onClick: () => { if (!disabled) onChange?.(!checked); },
+    ...rest,
+  },
+    h('text', { content: glyph }),
+    label ? h('text', { content: label }) : null,
+  );
+});

package/src/control/index.ts

@@ -0,0 +1,40 @@
+import type { ComponentDefinition } from '@textui/core';
+import { Button } from './button.js';
+import { Checkbox } from './checkbox.js';
+import { RadioGroup } from './radio-group.js';
+import { SearchBox } from './search-box.js';
+import { Select } from './select.js';
+import { Slider } from './slider.js';
+import { Switch } from './switch.js';
+import { TextArea } from './text-area.js';
+import { TextInput } from './text-input.js';
+
+/**
+ * Controls.
+ *
+ * Every control here is focusable, keyboard-first and states its own focus
+ * ring, because a terminal has no hover to fall back on: if the focused
+ * control is not obvious without moving a mouse, the interface is unusable.
+ */
+export * from './button.js';
+export * from './checkbox.js';
+export * from './radio-group.js';
+export * from './search-box.js';
+export * from './select.js';
+export * from './slider.js';
+export * from './switch.js';
+export * from './text-area.js';
+export * from './text-input.js';
+export type { TextInputProps } from './shared.js';
+
+export const CONTROL_COMPONENTS: ComponentDefinition[] = [
+  { component: 'Button', category: 'control', renderer: { kind: 'function', render: Button }, role: 'button', variants: ['solid', 'outline', 'ghost', 'link'], description: 'Focusable action.' },
+  { component: 'Checkbox', category: 'control', renderer: { kind: 'function', render: Checkbox }, role: 'checkbox', description: 'On, off, or mixed.' },
+  { component: 'Switch', category: 'control', renderer: { kind: 'function', render: Switch }, role: 'switch', description: 'Two-state toggle with words, not only colour.' },
+  { component: 'RadioGroup', category: 'control', renderer: { kind: 'function', render: RadioGroup }, role: 'radio', description: 'One of several.' },
+  { component: 'Slider', category: 'control', renderer: { kind: 'function', render: Slider }, role: 'slider', description: 'A value along a track.' },
+  { component: 'TextArea', category: 'control', renderer: { kind: 'function', render: TextArea }, role: 'textbox', description: 'A field that is a paragraph: grows, scrolls, and gives back the keys it does not want.' },
+  { component: 'TextInput', category: 'control', renderer: { kind: 'function', render: TextInput }, role: 'textbox', description: 'Single-line text with a real caret.' },
+  { component: 'Select', category: 'control', renderer: { kind: 'function', render: Select }, role: 'combobox', description: 'Pick from a list, collapsed or open.' },
+  { component: 'SearchBox', category: 'control', renderer: { kind: 'function', render: SearchBox }, role: 'searchbox', description: 'A text field that looks like search.' },
+];

package/src/control/radio-group.ts

@@ -0,0 +1,60 @@
+import type { BoxProps } from '@textui/core';
+import { defineComponent, h, useFocus, useInput, useTheme } from '@textui/core';
+
+export interface RadioOption {
+  value: string;
+  label: string;
+  description?: string;
+  disabled?: boolean;
+}
+
+export interface RadioGroupProps extends BoxProps {
+  options: RadioOption[];
+  value?: string;
+  onChange?(value: string): void;
+  label?: string;
+  /** Lay the options out in a row instead of a column. */
+  inline?: boolean;
+}
+
+export const RadioGroup = defineComponent<RadioGroupProps>('RadioGroup', (props) => {
+  const theme = useTheme();
+  const { options, value, onChange, label, inline, disabled, ...rest } = props;
+  const focus = useFocus({ disabled });
+  const index = Math.max(0, options.findIndex((o) => o.value === value));
+
+  useInput(
+    (event) => {
+      if (disabled) return false;
+      const step = inline
+        ? (event.name === 'right' ? 1 : event.name === 'left' ? -1 : 0)
+        : (event.name === 'down' ? 1 : event.name === 'up' ? -1 : 0);
+      if (step === 0) return false;
+      const next = options[(index + step + options.length) % options.length];
+      if (next && !next.disabled) onChange?.(next.value);
+      return true;
+    },
+    { focusId: focus.id },
+  );
+
+  return h('box', { id: focus.id, role: 'group', label, direction: 'column', gap: 0, ...rest },
+    label ? h('text', { content: label, fg: 'muted' }) : null,
+    h('box', { direction: inline ? 'row' : 'column', gap: inline ? 2 : 0 },
+      ...options.map((option) => {
+        const selected = option.value === value;
+        return h('box', {
+          key: option.value,
+          direction: 'row',
+          gap: 1,
+          fg: option.disabled ? 'disabled' : selected && focus.focused ? 'accent' : undefined,
+          bold: selected && focus.focused,
+          onClick: () => { if (!option.disabled) onChange?.(option.value); },
+        },
+          h('text', { content: selected ? theme.glyphs.radioOn : theme.glyphs.radioOff }),
+          h('text', { content: option.label }),
+          option.description ? h('text', { content: option.description, fg: 'subtle' }) : null,
+        );
+      }),
+    ),
+  );
+});

package/src/control/search-box.ts

@@ -0,0 +1,15 @@
+import { defineComponent, h } from '@textui/core';
+import type { TextInputProps } from './shared.js';
+import { TextInput } from './text-input.js';
+
+export interface SearchBoxProps extends Omit<TextInputProps, 'search'> {
+  /** Result count, shown after the field. */
+  count?: number;
+}
+
+export const SearchBox = defineComponent<SearchBoxProps>('SearchBox', ({ count, ...props }) =>
+  h('box', { direction: 'row', gap: 1 },
+    h(TextInput, { search: true, flex: 1, ...props }),
+    count !== undefined ? h('text', { content: `${count}`, fg: 'muted' }) : null,
+  ),
+);