alchemy 2.0.0-beta.76 → 2.0.0-beta.77

package/src/Cli/components/ui/Layout.tsx

@@ -0,0 +1,252 @@
+/** @jsxImportSource react */
+import { Box as SigilBox, type DOMElement } from "@alchemy.run/sigil";
+import {
+  forwardRef,
+  type ComponentProps,
+  type ForwardRefExoticComponent,
+  type PropsWithoutRef,
+  type ReactNode,
+  type RefAttributes,
+} from "react";
+import { theme } from "../../../Util/Theme.ts";
+import { useCliEnvironment, useGlyphs } from "./Environment.tsx";
+import { Text } from "./Typography.tsx";
+
+// Windowed list that clips to the rows its container leaves over; it draws no
+// colors of its own, so it needs no theme-aware wrapper.
+export { VirtualList } from "@alchemy.run/sigil";
+
+export type BoxProps = ComponentProps<typeof SigilBox>;
+
+/** Theme-aware Sigil container used by CliKit layouts. */
+export const Box: ForwardRefExoticComponent<
+  PropsWithoutRef<BoxProps> & RefAttributes<DOMElement>
+> = forwardRef<DOMElement, BoxProps>(function Box(props, ref) {
+  const { colors } = useCliEnvironment();
+  const {
+    borderColor: _borderColor,
+    borderTopColor: _borderTopColor,
+    borderBottomColor: _borderBottomColor,
+    borderLeftColor: _borderLeftColor,
+    borderRightColor: _borderRightColor,
+    borderBackgroundColor: _borderBackgroundColor,
+    borderTopBackgroundColor: _borderTopBackgroundColor,
+    borderBottomBackgroundColor: _borderBottomBackgroundColor,
+    borderLeftBackgroundColor: _borderLeftBackgroundColor,
+    borderRightBackgroundColor: _borderRightBackgroundColor,
+    backgroundColor: _backgroundColor,
+    borderDimColor: _borderDimColor,
+    borderTopDimColor: _borderTopDimColor,
+    borderBottomDimColor: _borderBottomDimColor,
+    borderLeftDimColor: _borderLeftDimColor,
+    borderRightDimColor: _borderRightDimColor,
+    ...colorless
+  } = props;
+  return <SigilBox {...(colors ? props : colorless)} ref={ref} />;
+});
+
+export interface StackProps extends Omit<BoxProps, "flexDirection"> {
+  readonly gap?: number;
+}
+
+/** Vertical layout primitive. */
+export function Stack({ children, gap = 0, ...props }: StackProps) {
+  return (
+    <Box flexDirection="column" gap={gap} {...props}>
+      {children}
+    </Box>
+  );
+}
+
+export interface RowProps extends Omit<
+  BoxProps,
+  "flexDirection" | "alignItems" | "justifyContent"
+> {
+  readonly gap?: number;
+  readonly align?: "flex-start" | "center" | "flex-end";
+  readonly justify?:
+    | "flex-start"
+    | "center"
+    | "flex-end"
+    | "space-between"
+    | "space-around";
+}
+
+/** Horizontal layout primitive. */
+export function Row({
+  children,
+  gap = 1,
+  align = "flex-start",
+  justify = "flex-start",
+  ...props
+}: RowProps) {
+  return (
+    <Box
+      flexDirection="row"
+      gap={gap}
+      alignItems={align}
+      justifyContent={justify}
+      {...props}
+    >
+      {children}
+    </Box>
+  );
+}
+
+type HeadingProps = {
+  readonly children?: ReactNode;
+  /** Set false to drop the section glyph prefix (e.g. help-screen headings). */
+  readonly glyph?: boolean;
+};
+
+export function Heading({ children, glyph = true }: HeadingProps) {
+  const glyphs = useGlyphs();
+  return (
+    <Box>
+      <Text bold color={theme.color.brand}>
+        {glyph ? `${glyphs.section} ` : null}
+        {children}
+      </Text>
+    </Box>
+  );
+}
+
+type SectionHeadingProps = {
+  readonly children?: ReactNode;
+  readonly annotation?: ReactNode;
+};
+
+export function SectionHeading({ children, annotation }: SectionHeadingProps) {
+  return (
+    <Text>
+      <Text bold color={theme.color.brand}>
+        {children}
+      </Text>
+      {annotation === undefined ? null : (
+        <Text tone="muted"> · {annotation}</Text>
+      )}
+    </Text>
+  );
+}
+
+type GutterProps = {
+  readonly depth?: number;
+  readonly children?: ReactNode;
+};
+
+export function Gutter({ depth = 1, children }: GutterProps) {
+  return (
+    <Box paddingLeft={Math.max(0, depth) * theme.space.indent}>
+      <Box flexDirection="column" flexGrow={1}>
+        {children}
+      </Box>
+    </Box>
+  );
+}
+
+/**
+ * The centering clamp shared by every windowed list: a window of `count` rows
+ * over `length` items keeping `cursor` as close to the middle as the list
+ * bounds allow.
+ */
+export const listWindow = (
+  length: number,
+  cursor: number,
+  count: number,
+): { readonly start: number; readonly end: number } => {
+  const start = Math.max(
+    0,
+    Math.min(cursor - Math.floor(count / 2), length - count),
+  );
+  return { start, end: Math.min(length, start + count) };
+};
+
+/**
+ * Horizontal window over variable-width items (tab chips): expands around
+ * `active` — alternating right/left so the selection stays roughly centered —
+ * until `available` columns are exhausted. Returns `[start, end)` like
+ * {@link listWindow}; `active` is always inside the window.
+ */
+export const tabsWindow = (
+  widths: ReadonlyArray<number>,
+  active: number,
+  available: number,
+  gap = 1,
+): { readonly start: number; readonly end: number } => {
+  if (widths.length === 0) return { start: 0, end: 0 };
+  const cursor = Math.max(0, Math.min(active, widths.length - 1));
+  let start = cursor;
+  let end = cursor + 1;
+  let used = widths[cursor]!;
+  let takeRight = true;
+  while (true) {
+    const canRight =
+      end < widths.length && used + gap + widths[end]! <= available;
+    const canLeft = start > 0 && used + gap + widths[start - 1]! <= available;
+    if (!canRight && !canLeft) break;
+    if ((takeRight && canRight) || !canLeft) {
+      used += gap + widths[end]!;
+      end++;
+    } else {
+      start--;
+      used += gap + widths[start]!;
+    }
+    takeRight = !takeRight;
+  }
+  return { start, end };
+};
+
+/**
+ * Window for prompt lists that render "↑ N more"/"↓ N more" indicator rows:
+ * reserves two of `visibleCount`'s rows for the indicators when overflowing so
+ * the widget stays within the requested height.
+ */
+export const overflowListWindow = (
+  length: number,
+  cursor: number,
+  visibleCount: number,
+): { readonly start: number; readonly end: number } =>
+  listWindow(
+    length,
+    cursor,
+    Math.max(1, length > visibleCount ? visibleCount - 2 : visibleCount),
+  );
+
+/** Windowed list keeping `cursor` centered; each item renders as a block. */
+type ViewportProps<Item> = {
+  readonly items: ReadonlyArray<Item>;
+  readonly cursor?: number;
+  readonly height: number;
+  readonly renderItem: (item: Item, index: number) => ReactNode;
+  readonly getKey: (item: Item, index: number) => string;
+  readonly empty?: ReactNode;
+};
+
+export function Viewport<Item>({
+  items,
+  cursor = 0,
+  height,
+  renderItem,
+  getKey,
+  empty,
+}: ViewportProps<Item>) {
+  if (items.length === 0) return <>{empty}</>;
+  const selected = Math.max(0, Math.min(cursor, items.length - 1));
+  const { start, end } = listWindow(
+    items.length,
+    selected,
+    Math.max(1, height),
+  );
+  return (
+    <Stack>
+      {items.slice(start, end).map((item, offset) => {
+        const index = start + offset;
+        return (
+          <Box key={getKey(item, index)} flexDirection="column">
+            {renderItem(item, index)}
+          </Box>
+        );
+      })}
+    </Stack>
+  );
+}

package/src/Cli/components/ui/Live.tsx

@@ -0,0 +1,131 @@
+/** @jsxImportSource react */
+import type { ReactNode } from "react";
+import { useSyncExternalStore } from "react";
+import { useGlyphs } from "./Environment.tsx";
+import { SpinnerGlyph } from "./Feedback.tsx";
+import { ProgressBar } from "./ProgressBar.tsx";
+import { Box, Row, Stack } from "./Layout.tsx";
+import { Text } from "./Typography.tsx";
+import { theme } from "../../../Util/Theme.ts";
+
+export interface TaskRowProps {
+  /** Status glyph. Ignored while `spinning`; defaults to the bullet glyph. */
+  readonly icon?: string;
+  /** Color for the glyph (and the spinner while `spinning`). */
+  readonly iconColor?: string;
+  /** Render an animated spinner frame in the glyph slot. */
+  readonly spinning?: boolean;
+  readonly label: ReactNode;
+  /** Muted annotation directly after the label. */
+  readonly detail?: ReactNode;
+  /** Indentation in 2-space units. */
+  readonly depth?: number;
+  /** Extra trailing cells (status labels, chips). */
+  readonly children?: ReactNode;
+}
+
+/**
+ * The one status row shape shared by TaskTree and the plan/apply views:
+ * glyph-or-spinner, bold label, muted detail, then any trailing cells.
+ */
+export function TaskRow({
+  icon,
+  iconColor,
+  spinning = false,
+  label,
+  detail,
+  depth = 0,
+  children,
+}: TaskRowProps) {
+  const glyphs = useGlyphs();
+  return (
+    <Row gap={1} paddingLeft={depth * theme.space.indent}>
+      {spinning ? (
+        <SpinnerGlyph color={iconColor} />
+      ) : (
+        <Text color={iconColor}>{icon ?? glyphs.bullet}</Text>
+      )}
+      <Text bold={depth === 0}>{label}</Text>
+      {detail === undefined ? null : <Text tone="muted">· {detail}</Text>}
+      {children}
+    </Row>
+  );
+}
+
+export interface ProgressGroupRow {
+  readonly id: string;
+  readonly label: ReactNode;
+  readonly completed: number;
+  readonly total: number;
+  readonly failed?: number;
+  readonly detail?: ReactNode;
+}
+
+type ProgressGroupProps = {
+  readonly rows: ReadonlyArray<ProgressGroupRow>;
+  readonly width?: number;
+  /** Fixed label column (truncated) so the count cells align across rows. */
+  readonly labelWidth?: number;
+};
+
+export function ProgressGroup({
+  rows,
+  width = 20,
+  labelWidth,
+}: ProgressGroupProps) {
+  return (
+    <Stack>
+      {rows.map((row) => {
+        const complete = row.total > 0 && row.completed >= row.total;
+        const variant = row.failed ? "error" : complete ? "success" : "info";
+        return (
+          <Row key={row.id}>
+            <ProgressBar
+              value={row.total <= 0 ? 0 : row.completed / row.total}
+              width={width}
+              showPercent={false}
+              variant={variant}
+            />
+            {labelWidth === undefined ? (
+              <Text>{row.label}</Text>
+            ) : (
+              <Box width={labelWidth} flexShrink={0}>
+                <Text wrap="truncate-end">{row.label}</Text>
+              </Box>
+            )}
+            <Text bold tone={variant === "error" ? "danger" : variant}>
+              {row.completed}/{row.total}
+            </Text>
+            {row.failed ? (
+              <Text tone="danger">({row.failed} failed)</Text>
+            ) : null}
+            {row.detail === undefined ? null : (
+              <Text tone="muted">{row.detail}</Text>
+            )}
+          </Row>
+        );
+      })}
+    </Stack>
+  );
+}
+
+export class LiveStore<Value> {
+  private value: Value;
+  private readonly listeners = new Set<() => void>();
+  constructor(initial: Value) {
+    this.value = initial;
+  }
+  readonly subscribe = (listener: () => void) => {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  };
+  readonly snapshot = () => this.value;
+  readonly set = (value: Value) => {
+    this.value = value;
+    for (const listener of this.listeners) listener();
+  };
+  readonly update = (f: (value: Value) => Value) => this.set(f(this.value));
+}
+
+export const useLiveStore = <Value,>(store: LiveStore<Value>): Value =>
+  useSyncExternalStore(store.subscribe, store.snapshot);

package/src/Cli/components/ui/ProgressBar.tsx

@@ -0,0 +1,57 @@
+/** @jsxImportSource react */
+import type { ReactNode } from "react";
+import { statusPaint, type StatusVariant } from "../../../Util/Theme.ts";
+import { useCliEnvironment } from "./Environment.tsx";
+import { Box } from "./Layout.tsx";
+import { Text } from "./Typography.tsx";
+
+export interface ProgressBarProps {
+  /** Completion ratio. Values outside 0..1 are clamped. */
+  readonly value: number;
+  /** Width in terminal cells (default: 24). */
+  readonly width?: number;
+  readonly showPercent?: boolean;
+  readonly label?: ReactNode;
+  readonly detail?: ReactNode;
+  readonly variant?: StatusVariant;
+}
+
+/** Left-to-right progress using half/full Braille cells and an ASCII fallback. */
+export function ProgressBar({
+  value,
+  width = 24,
+  showPercent = true,
+  label,
+  detail,
+  variant = "success",
+}: ProgressBarProps) {
+  const { unicode } = useCliEnvironment();
+  const ratio = Math.max(0, Math.min(1, value));
+  const cells = Math.max(1, Math.floor(width));
+  const steps = Math.floor(cells * ratio * (unicode ? 2 : 1));
+  const filled = unicode ? Math.floor(steps / 2) : steps;
+  const partial = unicode && steps % 2 !== 0 ? "⡇" : "";
+  const remaining = cells - filled - (partial === "" ? 0 : 1);
+  return (
+    <Box
+      gap={1}
+      aria-role="progressbar"
+      aria-label={`${Math.round(ratio * 100)}%`}
+      aria-state={{ busy: ratio < 1 }}
+    >
+      <Text>
+        <Text tone="muted">[</Text>
+        <Text color={statusPaint(variant)}>
+          {(unicode ? "⣿" : "#").repeat(filled)}
+          {partial}
+        </Text>
+        <Text tone="muted">{(unicode ? " " : ".").repeat(remaining)}]</Text>
+      </Text>
+      {showPercent ? (
+        <Text tone="muted">{`${Math.round(ratio * 100)}%`.padStart(4)}</Text>
+      ) : null}
+      {label === undefined ? null : <Text>{label}</Text>}
+      {detail === undefined ? null : <Text tone="muted">{detail}</Text>}
+    </Box>
+  );
+}

package/src/Cli/components/ui/Transcript.tsx

@@ -0,0 +1,42 @@
+/** @jsxImportSource react */
+import { useGlyphs } from "./Environment.tsx";
+import { Stack } from "./Layout.tsx";
+import { Text } from "./Typography.tsx";
+
+type AnsweredPromptProps = {
+  readonly message: string;
+  readonly answer: string;
+  readonly below?: boolean;
+};
+
+export function AnsweredPrompt({
+  message,
+  answer,
+  below = false,
+}: AnsweredPromptProps) {
+  const glyphs = useGlyphs();
+  return below ? (
+    <Stack>
+      <Text>
+        <Text tone="success">{glyphs.success}</Text> {message}
+      </Text>
+      <Text tone="muted"> {answer}</Text>
+    </Stack>
+  ) : (
+    <Text>
+      <Text tone="success">{glyphs.success}</Text> {message}{" "}
+      <Text tone="muted">· {answer}</Text>
+    </Text>
+  );
+}
+
+type CancelledPromptProps = { readonly message: string };
+
+export function CancelledPrompt({ message }: CancelledPromptProps) {
+  const glyphs = useGlyphs();
+  return (
+    <Text tone="muted">
+      <Text tone="danger">{glyphs.error}</Text> {message} cancelled
+    </Text>
+  );
+}

package/src/Cli/components/ui/Typography.tsx

@@ -0,0 +1,83 @@
+/** @jsxImportSource react */
+import {
+  Hyperlink as SigilHyperlink,
+  Text as SigilText,
+} from "@alchemy.run/sigil";
+import type { ComponentProps } from "react";
+import { theme } from "../../../Util/Theme.ts";
+import { useCliEnvironment } from "./Environment.tsx";
+
+export type TextTone =
+  | "default"
+  | "muted"
+  | "emphasis"
+  | "brand"
+  | "accent"
+  | "info"
+  | "success"
+  | "warning"
+  | "danger";
+
+export interface TextProps extends Omit<
+  ComponentProps<typeof SigilText>,
+  "color"
+> {
+  readonly tone?: TextTone;
+  readonly color?: ComponentProps<typeof SigilText>["color"];
+}
+
+/** CliKit typography primitive. Consumers never import Sigil directly. */
+export function Text({
+  tone = "default",
+  color,
+  backgroundColor,
+  bold,
+  dimColor,
+  italic,
+  underline,
+  strikethrough,
+  inverse,
+  ...props
+}: TextProps) {
+  const { colors } = useCliEnvironment();
+  return (
+    <SigilText
+      {...props}
+      color={
+        colors
+          ? (color ??
+            (tone === "default" || tone === "muted"
+              ? undefined
+              : theme.color[tone]))
+          : undefined
+      }
+      backgroundColor={colors ? backgroundColor : undefined}
+      bold={colors ? bold : undefined}
+      dimColor={colors ? (dimColor ?? tone === "muted") : undefined}
+      italic={colors ? italic : undefined}
+      underline={colors ? underline : undefined}
+      strikethrough={colors ? strikethrough : undefined}
+      inverse={colors ? inverse : undefined}
+    />
+  );
+}
+
+type LinkProps = {
+  readonly href: string;
+  readonly children?: string;
+};
+
+export function Link({ href, children }: LinkProps) {
+  const { colors } = useCliEnvironment();
+  const label = children ?? href;
+  return (
+    <SigilHyperlink
+      url={href}
+      fallback={label !== href}
+      color={colors ? theme.color.info : undefined}
+      underline={colors || undefined}
+    >
+      {label}
+    </SigilHyperlink>
+  );
+}

package/src/Cli/components/ui/index.ts

@@ -0,0 +1,68 @@
+/**
+ * Composable terminal layouts and interaction widgets.
+ *
+ * This is a separate entrypoint from `alchemy/Cli/CliKit` so importing the
+ * injectable service does not eagerly load React, Sigil or Yoga.
+ */
+export {
+  CliEnvironment,
+  useBorderStyle,
+  useCliEnvironment,
+  useGlyphs,
+  useKeyGlyphs,
+} from "./Environment.tsx";
+export {
+  Box,
+  Gutter,
+  Heading,
+  Row,
+  SectionHeading,
+  Stack,
+  Viewport,
+  VirtualList,
+  type BoxProps,
+  type RowProps,
+  type StackProps,
+} from "./Layout.tsx";
+export { Link, Text, type TextProps, type TextTone } from "./Typography.tsx";
+export {
+  Alert,
+  KeyBar,
+  Spinner,
+  SpinnerGlyph,
+  Status,
+  Tabs,
+  Toast,
+  type AlertProps,
+  type StatusProps,
+  type ToastProps,
+} from "./Feedback.tsx";
+export { DescriptionList, type DescriptionItem } from "./Data.tsx";
+export {
+  ChoiceGroup,
+  CycleList,
+  InlineConfirm,
+  Pointer,
+  PromptFrame,
+  TextField,
+  useCycleNavigation,
+  useTerminalInput,
+  useTerminalPaste,
+  useTerminalSize,
+  type CycleListProps,
+  type ChoiceGroupProps,
+  type PromptFrameProps,
+  type TerminalKey,
+  type TextFieldProps,
+} from "./Interactive.tsx";
+export { AnsweredPrompt, CancelledPrompt } from "./Transcript.tsx";
+export {
+  LiveStore,
+  ProgressGroup,
+  TaskRow,
+  useLiveStore,
+  type ProgressGroupRow,
+  type TaskRowProps,
+} from "./Live.tsx";
+
+export { ProgressBar, type ProgressBarProps } from "./ProgressBar.tsx";