@textui/widgets 0.1.0

package/src/overlay/index.ts

@@ -0,0 +1,232 @@
+import type {
+  ComponentDefinition,
+  Disposable,
+  LayerEntry,
+  LayerPosition,
+  SemanticVariant,
+  TextUIApp,
+} from '@textui/core';
+import { CommandPalette } from './command-palette.js';
+import { Dialog } from './dialog.js';
+import { LayerScope } from './layer-scope.js';
+import { PathPicker } from './path-picker.js';
+import { PromptDialog } from './prompt-dialog.js';
+import type { ToastHostProps } from './toast-host.js';
+import { ToastHost } from './toast-host.js';
+import { Toast } from './toast.js';
+import { Tooltip } from './tooltip.js';
+
+/**
+ * Overlays.
+ *
+ * Every one of these is a layer entry, not a component that draws itself over
+ * its neighbours - so focus trapping, dismissal and paint order are decided
+ * once by the layer manager rather than five times, slightly differently.
+ */
+export * from './command-palette.js';
+export * from './dialog.js';
+export * from './layer-scope.js';
+export * from './path-picker.js';
+export * from './prompt-dialog.js';
+export * from './toast.js';
+export * from './toast-host.js';
+export * from './tooltip.js';
+
+export interface ConfirmOptions {
+  title?: string;
+  message: string;
+  confirmLabel?: string;
+  cancelLabel?: string;
+  tone?: SemanticVariant;
+}
+
+/**
+ * The composition rule the brief asks for: a dialog can be assembled by hand
+ * out of public components, and the common case gets a one-liner that returns
+ * a promise. Both go through the same layer manager.
+ */
+export function confirm(
+  layers: { open(entry: LayerEntry): { dispose(): void } },
+  options: ConfirmOptions,
+): Promise<boolean> {
+  return new Promise((resolve) => {
+    const id = `confirm:${options.message}`;
+    let settled = false;
+
+    const finish = (value: boolean): void => {
+      if (settled) return;
+      settled = true;
+      handle.dispose();
+      resolve(value);
+    };
+
+    const handle = layers.open({
+      id,
+      layer: 'modal',
+      scrim: true,
+      trapFocus: true,
+      dismissOnEscape: true,
+      onClose: () => finish(false),
+      node: {
+        component: 'Dialog',
+        title: options.title ?? 'Confirm',
+        width: 50,
+        children: { component: 'text', content: options.message, wrap: 'word' },
+        actions: [
+          {
+            id: 'confirm',
+            label: options.confirmLabel ?? 'Confirm',
+            tone: options.tone ?? 'primary',
+            onPress: () => finish(true),
+          },
+          {
+            id: 'cancel',
+            label: options.cancelLabel ?? 'Cancel',
+            onPress: () => finish(false),
+          },
+        ],
+      },
+    });
+  });
+}
+
+export interface PromptOptions {
+  title?: string;
+  message?: string;
+  placeholder?: string;
+  initialValue?: string;
+  mask?: string;
+}
+
+export function prompt(
+  layers: { open(entry: LayerEntry): { dispose(): void } },
+  options: PromptOptions,
+): Promise<string | null> {
+  return new Promise((resolve) => {
+    let settled = false;
+    const finish = (value: string | null): void => {
+      if (settled) return;
+      settled = true;
+      handle.dispose();
+      resolve(value);
+    };
+
+    const handle = layers.open({
+      id: `prompt:${options.title ?? options.message ?? 'input'}`,
+      layer: 'modal',
+      scrim: true,
+      trapFocus: true,
+      dismissOnEscape: true,
+      onClose: () => finish(null),
+      node: {
+        component: 'PromptDialog',
+        title: options.title ?? 'Input',
+        message: options.message,
+        placeholder: options.placeholder,
+        initialValue: options.initialValue,
+        mask: options.mask,
+        onSubmit: { handler: (value: string) => finish(value) },
+        onCancel: { handler: () => finish(null) },
+      },
+    });
+  });
+}
+
+/**
+ * Picking a path by looking at it.
+ *
+ * The third question, beside `confirm` and `prompt`, and it exists because the
+ * other two cannot ask it. A path typed blind into a text field is the worst
+ * way to give one: you have to already know the answer, which is the opposite
+ * of what picking is for.
+ *
+ * It reads the **resource registry**, never the filesystem. `search` made that
+ * choice already and it is why search works on whatever is mounted; a picker
+ * that reached for `node:fs` would work on `file:` and nothing else, and the
+ * first thing anyone wants to pick off a remote is a file.
+ */
+export interface PickOptions {
+  /** Where to start looking. A directory URI. */
+  start: string;
+  /** What counts as an answer. Directories are walked through either way. */
+  wants?: 'file' | 'directory';
+  title?: string;
+  placeholder?: string;
+  visibleRows?: number;
+  width?: number;
+}
+
+export function pick(app: TextUIApp, options: PickOptions): Promise<string | null> {
+  return new Promise((resolve) => {
+    let settled = false;
+    const finish = (value: string | null): void => {
+      if (settled) return;
+      settled = true;
+      handle.dispose();
+      resolve(value);
+    };
+
+    const handle = app.layers.open({
+      id: `pick:${options.start}`,
+      layer: 'modal',
+      scrim: true,
+      trapFocus: true,
+      dismissOnEscape: true,
+      onClose: () => finish(null),
+      node: {
+        component: 'PathPicker',
+        start: options.start,
+        wants: options.wants ?? 'file',
+        title: options.title,
+        placeholder: options.placeholder,
+        visibleRows: options.visibleRows,
+        width: options.width,
+        onPick: { handler: (uri: string) => finish(uri) },
+        onCancel: { handler: () => finish(null) },
+      },
+    });
+  });
+}
+
+export interface NotifyOptions {
+  message: string;
+  tone?: SemanticVariant;
+  title?: string;
+  icon?: string;
+  /** Milliseconds on screen. 0 keeps it until it is closed. */
+  timeoutMs?: number;
+  /** Reuse an id to replace a standing toast rather than stack another. */
+  id?: string;
+}
+
+let notifyCounter = 0;
+
+export function notify(app: TextUIApp, options: NotifyOptions): Disposable {
+  const { message, tone = 'info', title, icon, timeoutMs = 2500, id } = options;
+  return app.layers.open({
+    id: id ?? `toast-${++notifyCounter}`,
+    layer: 'notification',
+    timeoutMs: timeoutMs > 0 ? timeoutMs : undefined,
+    node: { component: 'Toast', message, tone, title, icon },
+  });
+}
+
+export function toastPosition(anchor: ToastHostProps['anchor']): LayerPosition {
+  switch (anchor) {
+    case 'top': return { kind: 'screen', rect: { y: 1 } };
+    case 'top-right': return { kind: 'screen', rect: { y: 1 } };
+    case 'bottom': return { kind: 'screen', rect: { y: 0 } };
+    default: return { kind: 'screen', rect: {} };
+  }
+}
+
+export const OVERLAY_COMPONENTS: ComponentDefinition[] = [
+  { component: 'Dialog', category: 'overlay', renderer: { kind: 'function', render: Dialog }, role: 'dialog', description: 'Modal box with actions; traps focus and restores it.' },
+  { component: 'PromptDialog', category: 'overlay', renderer: { kind: 'function', render: PromptDialog }, role: 'dialog', description: 'One-field dialog behind the `prompt` helper.' },
+  { component: 'PathPicker', category: 'overlay', renderer: { kind: 'function', render: PathPicker }, role: 'dialog', description: 'Walk the resource tree and pick a file or a folder.' },
+  { component: 'Tooltip', category: 'overlay', renderer: { kind: 'function', render: Tooltip }, role: 'tooltip', description: 'Small anchored hint.' },
+  { component: 'Toast', category: 'overlay', renderer: { kind: 'function', render: Toast }, role: 'status', description: 'Transient notification.' },
+  { component: 'ToastHost', category: 'overlay', renderer: { kind: 'function', render: ToastHost }, description: 'Where toasts stack.' },
+  { component: 'LayerScope', category: 'overlay', renderer: { kind: 'function', render: LayerScope }, description: 'The focus scope a layer lives in; makes `trapFocus` real.' },
+  { component: 'CommandPalette', category: 'overlay', renderer: { kind: 'function', render: CommandPalette }, role: 'dialog', description: 'Fuzzy search over the command registry.' },
+];

package/src/overlay/layer-scope.ts

@@ -0,0 +1,26 @@
+import type { ComponentNode, RenderOutput } from '@textui/core';
+import { defineComponent, useFocusScope } from '@textui/core';
+
+/**
+ * The focus scope a layer lives in.
+ *
+ * `trapFocus` on a layer used to be a flag nothing read: `Dialog` and
+ * `CommandPalette` trapped because they each called `useFocusScope`
+ * themselves, and any layer built out of plain nodes - a menu dropdown, say -
+ * silently did not. Tab then walked straight out of the open thing and into
+ * whatever was behind it, and the next key went with it.
+ *
+ * Wrapping every layer in this makes the flag mean what it says, once, for all
+ * of them. It renders its child rather than a box of its own, so a layer's
+ * measurements are unchanged by being scoped.
+ */
+export interface LayerScopeProps {
+  scopeId: string;
+  trap?: boolean;
+  children?: ComponentNode | ComponentNode[];
+}
+
+export const LayerScope = defineComponent<LayerScopeProps>('LayerScope', (props) => {
+  useFocusScope({ id: `layer:${props.scopeId}`, trap: props.trap === true, restore: true });
+  return (props.children ?? null) as RenderOutput;
+});

package/src/overlay/path-picker.ts

@@ -0,0 +1,215 @@
+import type { BoxProps } from '@textui/core';
+import {
+  defineComponent,
+  h,
+  nameOf,
+  useEffect,
+  useInput,
+  useRuntime,
+  useState,
+  useTheme,
+} from '@textui/core';
+import { TextInput } from '../control/index.js';
+import type { MenuItem } from '../navigation/index.js';
+import { Menu } from '../navigation/index.js';
+import { hint } from './shared.js';
+
+export interface PathPickerProps extends BoxProps {
+  start: string;
+  wants?: 'file' | 'directory';
+  title?: string;
+  placeholder?: string;
+  visibleRows?: number;
+  onPick?(uri: string): void;
+  onCancel?(): void;
+}
+
+/** The parent of a directory URI, or null at the top of its scheme. */
+export function parentOf(uri: string): string | null {
+  const at = uri.lastIndexOf('/');
+  if (at < 0) return null;
+  const head = uri.slice(0, at);
+  // `scheme://` is a root, not a parent: trimming again would produce
+  // `scheme:/` and then `scheme:`, which are two URIs nothing can list.
+  if (head.endsWith('/') || head.endsWith(':')) return null;
+  return head;
+}
+
+export const PathPicker = defineComponent<PathPickerProps>('PathPicker', (props) => {
+  const {
+    start, wants = 'file', title, placeholder, visibleRows = 10,
+    width = 60, onPick, onCancel, ...rest
+  } = props;
+  const theme = useTheme();
+  const runtime = useRuntime();
+  const app = runtime.app();
+
+  const [at, setAt] = useState(start);
+  const [query, setQuery] = useState('');
+  const [highlight, setHighlight] = useState(0);
+  const [entries, setEntries] = useState<{ uri: string; name: string; directory: boolean }[]>([]);
+  /*
+   * An empty folder and a folder still being read are different answers.
+   *
+   * "Nothing here" under a list that has not arrived is a lie the reader acts
+   * on - they press escape and go somewhere else. So the list says which.
+   */
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    let live = true;
+    setLoading(true);
+    void (async () => {
+      const found = await app?.resources.list(at).catch(() => []) ?? [];
+      if (!live) return;
+      setEntries(found.map((r) => ({
+        uri: r.uri,
+        name: r.metadata.name || nameOf(r.uri),
+        directory: r.capabilities.includes('list'),
+      })));
+      setLoading(false);
+    })();
+    return () => { live = false; };
+  }, [at]);
+
+  const parent = parentOf(at);
+  const q = query.trim().toLowerCase();
+  const shown = entries
+    // A folder cannot be *chosen* when a file is wanted, but it still has to
+    // be walked through - so both kinds are listed either way, and only what
+    // enter does about them differs.
+    .filter((e) => q === '' || e.name.toLowerCase().includes(q))
+    // Folders first, then by name: a list sorted only by name buries the way
+    // onward among the things at the end of the journey.
+    .sort((a, b) => (a.directory === b.directory
+      ? a.name.localeCompare(b.name)
+      : (a.directory ? -1 : 1)));
+
+  const rows: MenuItem[] = [
+    // Picking the folder you are standing in needs a row, because there is no
+    // child to press enter on and a hidden chord for it is a chord nobody
+    // finds. It is first, since it is the answer most often wanted.
+    ...(wants === 'directory'
+      ? [{ id: '.', label: 'Use this folder', icon: theme.glyphs.check }]
+      : []),
+    ...(parent !== null ? [{ id: '..', label: '..', icon: theme.glyphs.chevronUp }] : []),
+    ...shown.map((e) => ({
+      id: e.uri,
+      label: e.name,
+      icon: e.directory ? theme.glyphs.chevronRight : ' ',
+      ...(e.directory ? {} : { description: '' }),
+    })),
+  ];
+
+  const index = Math.max(0, Math.min(highlight, rows.length - 1));
+
+  const up = (): void => {
+    if (parent === null) return;
+    setAt(parent);
+    setQuery('');
+    setHighlight(0);
+  };
+
+  const choose = (id?: string): void => {
+    const chosen = id ?? rows[index]?.id;
+    if (chosen === undefined) return;
+    if (chosen === '.') { onPick?.(at); return; }
+    if (chosen === '..') { up(); return; }
+    const entry = entries.find((e) => e.uri === chosen);
+    if (!entry) return;
+    // A directory is a place to go when a file is wanted, and both a place to
+    // go and an answer when one is not - which is why enter descends and the
+    // row above is what picks.
+    if (entry.directory) { setAt(entry.uri); setQuery(''); setHighlight(0); return; }
+    if (wants === 'file') onPick?.(entry.uri);
+  };
+
+  useInput((event) => {
+    const wrap = (n: number): number => (rows.length === 0
+      ? 0
+      : ((n % rows.length) + rows.length) % rows.length);
+    if (event.name === 'up') { setHighlight(wrap(index - 1)); return true; }
+    if (event.name === 'down') { setHighlight(wrap(index + 1)); return true; }
+    // Only when a caller gave one. `pick` mounts this on a dismissible layer
+    // and the layer closes itself on escape, so taking the key unconditionally
+    // would swallow escape for a caller that mounted the picker plainly and
+    // wired nothing to it.
+    if (event.name === 'escape' && onCancel) { onCancel(); return true; }
+    return false;
+  }, { global: true });
+
+
+  const move = `${theme.glyphs.arrowUp}${theme.glyphs.arrowDown} move`;
+
+  return h('box', {
+    role: 'dialog',
+    label: title ?? 'Choose',
+    border: theme.border,
+    bg: 'overlay',
+    width,
+    direction: 'column',
+    ...(theme.border === 'none' ? { padding: { left: 1, right: 1 } } : {}),
+    title: ` ${title ?? (wants === 'directory' ? 'choose a folder' : 'choose a file')} `,
+    ...rest,
+  },
+    // Where you are. A column of bare names with no header is a list you can
+    // get lost in - and the tail is the part that changes, so it is the part
+    // kept when the path is too long for the dialog.
+    h('text', { content: at, fg: 'muted', truncate: 'start' }),
+    h(TextInput, {
+      value: query,
+      onChange: (next: string) => { setQuery(next); setHighlight(0); },
+      onSubmit: () => choose(),
+      /*
+       * Leftwards is upwards, the way it is in every tree.
+       *
+       * Through `onEdge` rather than a key handler beside the others: the
+       * field has the keyboard, and it answers `left` itself until the caret
+       * runs out of text. A global handler for it never fires - the field
+       * reports the edge instead, which is the hook that exists for exactly
+       * this. It also means a typed filter keeps its own arrows, which is
+       * what you want while editing one.
+       */
+      onEdge: (edge: 'start' | 'end') => { if (edge === 'start') up(); },
+      placeholder: placeholder ?? `Filter${theme.glyphs.ellipsis}`,
+      search: true,
+      autoFocus: true,
+      border: 'none',
+    }),
+    h('box', { height: 1, fill: theme.borderChars().top, fg: 'borderSubtle' }),
+    h(Menu, {
+      items: rows,
+      visibleRows,
+      interactive: false,
+      activeId: rows[index]?.id,
+      onSelect: (id: string) => { choose(id); },
+    }),
+    /*
+     * An empty folder and a folder still being read are different answers.
+     *
+     * "Nothing here" under a list that has not arrived is a lie the reader
+     * acts on - they press escape and go somewhere else. It is a line of its
+     * own rather than the menu's empty state because the menu is never empty:
+     * `..` and "Use this folder" are rows, and neither is a child.
+     */
+    shown.length === 0
+      ? h('text', {
+          content: loading
+            ? `Reading${theme.glyphs.ellipsis}`
+            : (q === '' ? 'Nothing here.' : 'Nothing matches.'),
+          fg: 'muted',
+        })
+      : null,
+    h('box', { height: 1, fill: theme.borderChars().top, fg: 'borderSubtle' }),
+    h('text', {
+      content: hint(theme, [
+        move,
+        wants === 'directory' ? 'enter open' : 'enter choose',
+        `${theme.glyphs.chevronLeft} up`,
+        'esc cancel',
+      ]),
+      fg: 'subtle',
+      truncate: 'end',
+    }),
+  );
+});

package/src/overlay/prompt-dialog.ts

@@ -0,0 +1,45 @@
+import type { BoxProps } from '@textui/core';
+import { defineComponent, h, useState } from '@textui/core';
+import { TextInput } from '../control/index.js';
+import { Dialog } from './dialog.js';
+
+export interface PromptDialogProps extends BoxProps {
+  title?: string;
+  message?: string;
+  placeholder?: string;
+  initialValue?: string;
+  mask?: string;
+  onSubmit?(value: string): void;
+  onCancel?(): void;
+}
+
+export const PromptDialog = defineComponent<PromptDialogProps>('PromptDialog', (props) => {
+  const { title, message, placeholder, initialValue = '', mask, onSubmit, onCancel, ...rest } = props;
+  const [value, setValue] = useState(initialValue);
+
+  return h(Dialog, {
+    title,
+    width: 50,
+    onClose: onCancel,
+    actions: [
+      { id: 'ok', label: 'OK', tone: 'primary', onPress: () => onSubmit?.(value) },
+      { id: 'cancel', label: 'Cancel', onPress: onCancel },
+    ],
+    ...rest,
+  },
+    message ? h('text', { content: message, wrap: 'word' }) : null,
+    h(TextInput, {
+      value,
+      onChange: setValue,
+      placeholder,
+      mask,
+      // The message names the field: an unlabelled input is a focus stop
+      // nothing can describe, in the dialog whose whole job is one question.
+      // It is already on screen above, so it is not drawn twice.
+      label: message,
+      hideLabel: true,
+      autoFocus: true,
+      onSubmit: () => onSubmit?.(value),
+    }),
+  );
+});

package/src/overlay/shared.ts

@@ -0,0 +1,19 @@
+import type { ResolvedTheme } from '@textui/core';
+
+/**
+ * Raise a toast.
+ *
+ * Exists because the alternative - every caller assembling a layer entry - is
+ * how two of them end up with different timeouts and one of them forgets the
+ * `notification` layer and lands under the dialog it is reporting on.
+ */
+/**
+ * The footer of an overlay: what the keys do.
+ *
+ * Joined with the theme's separator rather than a `·` written here, because a
+ * terminal that cannot draw a middle dot draws a `?` instead - and the row it
+ * ruins is the one telling you how to get out.
+ */
+export function hint(theme: ResolvedTheme, parts: string[]): string {
+  return parts.join(` ${theme.glyphs.separator} `);
+}

package/src/overlay/toast-host.ts

@@ -0,0 +1,30 @@
+import type { BoxProps } from '@textui/core';
+import { defineComponent, h, useEffect, useRuntime } from '@textui/core';
+
+export interface ToastHostProps extends BoxProps {
+  /** Where the stack sits. Named `anchor` so it does not shadow `position`. */
+  anchor?: 'top-right' | 'bottom-right' | 'top' | 'bottom';
+}
+
+/** Renders whatever is on the notification layer. */
+export const ToastHost = defineComponent<ToastHostProps>('ToastHost', (props) => {
+  const runtime = useRuntime();
+  const { anchor = 'bottom-right', ...rest } = props;
+  const entries = runtime.layers.entries('notification');
+
+  useEffect(() => {
+    // Re-render when the layer set changes; the manager already asks for a
+    // frame, this only keeps the subscription honest.
+  }, [entries.length]);
+
+  if (entries.length === 0) return null;
+
+  return h('box', {
+    direction: 'column',
+    gap: 1,
+    align: anchor.endsWith('right') ? 'end' : 'stretch',
+    ...rest,
+  },
+    ...entries.map((entry) => h('box', { key: entry.id }, entry.node)),
+  );
+});

package/src/overlay/toast.ts

@@ -0,0 +1,35 @@
+import type { BoxProps, SemanticVariant } from '@textui/core';
+import { defineComponent, h, useTheme } from '@textui/core';
+
+export interface ToastProps extends BoxProps {
+  message: string;
+  tone?: SemanticVariant;
+  title?: string;
+  icon?: string;
+}
+
+export const Toast = defineComponent<ToastProps>('Toast', (props) => {
+  const theme = useTheme();
+  const { message, tone = 'info', title, icon, ...rest } = props;
+  const glyph = icon ?? {
+    success: theme.glyphs.check,
+    warning: theme.glyphs.warning,
+    danger: theme.glyphs.cross,
+    info: theme.glyphs.info,
+  }[tone as 'success' | 'warning' | 'danger' | 'info'] ?? theme.glyphs.info;
+
+  return h('box', {
+    role: 'status',
+    border: theme.border,
+    bg: 'overlay',
+    padding: [0, 1],
+    direction: 'row',
+    gap: 1,
+    ...rest,
+  },
+    h('text', { content: glyph, fg: tone }),
+    h('box', { direction: 'column' },
+      title ? h('text', { content: title, bold: true }) : null,
+      h('text', { content: message, wrap: 'word' })),
+  );
+});

package/src/overlay/tooltip.ts

@@ -0,0 +1,17 @@
+import type { BoxProps } from '@textui/core';
+import { defineComponent, h, useTheme } from '@textui/core';
+
+export interface TooltipProps extends BoxProps {
+  text: string;
+}
+
+export const Tooltip = defineComponent<TooltipProps>('Tooltip', ({ text, ...rest }) => {
+  const theme = useTheme();
+  return h('box', {
+    role: 'tooltip',
+    border: theme.border,
+    bg: 'overlay',
+    padding: [0, 1],
+    ...rest,
+  }, h('text', { content: text }));
+});