@valyrianjs/terminal 0.2.1 → 0.2.2

package/examples/docs/module-forms.tsx

@@ -0,0 +1,218 @@
+import { FormStore } from "valyrian.js/forms";
+import { Input, Pane, Screen, Text, mountTerminal } from "@valyrianjs/terminal";
+import type { TerminalMountOptions, TerminalSession } from "@valyrianjs/terminal";
+
+interface ModuleDemo {
+  session: TerminalSession;
+  dispatchKey(key: string): string;
+  output(): string;
+  ansiOutput(): string;
+  isRunning(): boolean;
+  destroy(): void;
+}
+
+type ProfileForm = { name: string; email: string };
+
+interface SavedProfile {
+  name: string;
+  email: string;
+}
+
+interface FormDemoState {
+  form: FormStore<ProfileForm>;
+  valid: boolean;
+  savedProfile: SavedProfile | null;
+  submitMessage: string;
+  resetMessage: string;
+  running: boolean;
+}
+
+const PANEL_STYLE = { color: "#f8fafc", background: "#111827", padding: { left: 1, right: 1 } };
+const FIELD_STYLE = { color: "#ffffff", background: "#0f3b3e", padding: { left: 1, right: 1 } };
+const ERROR_STYLE = { color: "#fecaca" };
+const FOOTER_STYLE = { color: "#dbeafe", background: "#1e293b" };
+
+function shouldRunSnapshot() {
+  return process.argv.includes("--snapshot") || process.env.VALYRIAN_TERMINAL_EXAMPLE_SNAPSHOT === "1" || !process.stdin.isTTY;
+}
+
+function createProfileForm(onSaved: (profile: SavedProfile) => void) {
+  return new FormStore<ProfileForm>({
+    state: { name: "", email: "" },
+    schema: {
+      type: "object",
+      properties: {
+        name: { type: "string", minLength: 1 },
+        email: { type: "string", format: "email" }
+      },
+      required: ["name", "email"]
+    },
+    clean: {
+      name: (value) => String(value).trim(),
+      email: (value) => String(value).trim().toLowerCase()
+    },
+    onSubmit(values) {
+      onSaved({ name: values.name, email: values.email });
+    }
+  });
+}
+
+function fieldError(form: FormStore<ProfileForm>, field: keyof ProfileForm) {
+  return String(form.validationErrors[field] || "not checked");
+}
+
+function savedSummary(profile: SavedProfile | null) {
+  return profile ? `${profile.name} / ${profile.email}` : "none";
+}
+
+export function App({ state, onSubmit }: { state: FormDemoState; onSubmit: () => void }) {
+  return (
+    <Screen title="Profile Editor">
+      <Text style={{ color: "#ffffff", background: "#020617" }}>Profile Editor</Text>
+      <Pane style={FIELD_STYLE}>
+        <Text>Name</Text>
+        <Input
+          id="profile-name"
+          value={state.form.state.name}
+          placeholder="Full name"
+          onchange={(event) => {
+            state.form.setField("name", event.value);
+            state.valid = false;
+          }}
+          onsubmit={onSubmit}
+        />
+        <Text>{`Name: ${state.form.state.name || "blank"}`}</Text>
+        <Text style={ERROR_STYLE}>{`Name error: ${fieldError(state.form, "name")}`}</Text>
+        <Text>Email</Text>
+        <Input
+          id="profile-email"
+          value={state.form.state.email}
+          placeholder="name@example.com"
+          onchange={(event) => {
+            state.form.setField("email", event.value);
+            state.valid = false;
+          }}
+          onsubmit={onSubmit}
+        />
+        <Text>{`Email: ${state.form.state.email || "blank"}`}</Text>
+        <Text style={ERROR_STYLE}>{`Email error: ${fieldError(state.form, "email")}`}</Text>
+      </Pane>
+      <Pane style={PANEL_STYLE}>
+        <Text>{`Form valid: ${state.valid}`}</Text>
+        <Text>{`Submit: ${state.submitMessage}`}</Text>
+        <Text>{`Reset: ${state.resetMessage}`}</Text>
+        <Text>{`Saved profile: ${savedSummary(state.savedProfile)}`}</Text>
+      </Pane>
+      <Text style={FOOTER_STYLE}>Type profile fields | Tab: next field | Shift+Tab: previous field | Enter: save profile | R: reset form | Ctrl+C: quit</Text>
+    </Screen>
+  );
+}
+
+export function createModuleFormsDemo(options: TerminalMountOptions = {}): ModuleDemo {
+  const state: FormDemoState = {
+    form: null as unknown as FormStore<ProfileForm>,
+    valid: false,
+    savedProfile: null,
+    submitMessage: "not submitted",
+    resetMessage: "not reset",
+    running: true
+  };
+  state.form = createProfileForm((profile) => {
+    state.savedProfile = profile;
+    state.submitMessage = `saved ${profile.name} <${profile.email}>`;
+  });
+  let session: TerminalSession;
+
+  function resetForm() {
+    state.form.reset();
+    state.valid = false;
+    state.savedProfile = null;
+    state.submitMessage = "not submitted";
+    state.resetMessage = "form reset";
+  }
+
+  function submitForm() {
+    state.valid = state.form.validate();
+    if (!state.valid) {
+      state.submitMessage = "blocked by validation";
+      session.update();
+      return;
+    }
+
+    void state.form.submit().then((ok) => {
+      state.valid = ok;
+      if (!ok) state.submitMessage = "blocked by validation";
+      session.update();
+    });
+  }
+
+  function quit() {
+    state.running = false;
+    session.destroy();
+  }
+
+  session = mountTerminal(<App state={state} onSubmit={submitForm} />, {
+    ...options,
+    cols: options.cols ?? 92,
+    rows: options.rows ?? 20,
+    keymap: {
+      ...options.keymap,
+      bindings: [
+        ...(options.keymap?.bindings || []),
+        { key: "R", command: { id: "forms.reset" }, scope: "global" },
+        { key: "CTRL_C", command: { id: "quit" }, scope: "global" }
+      ],
+      onCommand(command, context) {
+        if (command.id === "forms.reset") {
+          resetForm();
+          return true;
+        }
+        if (command.id === "quit") {
+          quit();
+          return true;
+        }
+        return options.keymap?.onCommand?.(command, context);
+      }
+    }
+  });
+
+  session.focus("profile-name");
+
+  return {
+    session,
+    dispatchKey(key: string) {
+      return session.dispatchKey(key);
+    },
+    output() {
+      return session.output();
+    },
+    ansiOutput() {
+      return session.ansiOutput();
+    },
+    isRunning() {
+      return state.running;
+    },
+    destroy() {
+      state.running = false;
+      session.destroy();
+    }
+  };
+}
+
+if (import.meta.main) {
+  if (shouldRunSnapshot()) {
+    const demo = createModuleFormsDemo({ runtime: "headless", cols: 92, rows: 20 });
+    demo.dispatchKey("ENTER");
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    for (const key of "AdaLovelace") demo.dispatchKey(key);
+    demo.dispatchKey("TAB");
+    for (const key of "ada@example.com") demo.dispatchKey(key);
+    demo.dispatchKey("ENTER");
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    process.stdout.write(demo.output());
+    process.stdout.write("\n");
+    demo.destroy();
+  } else {
+    createModuleFormsDemo();
+  }
+}

package/examples/docs/module-money.tsx

@@ -0,0 +1,175 @@
+import { Money, formatMoney, parseMoneyInput } from "valyrian.js/money";
+import { Pane, Screen, Text, mountTerminal } from "@valyrianjs/terminal";
+import type { TerminalMountOptions, TerminalSession } from "@valyrianjs/terminal";
+
+interface ModuleDemo {
+  session: TerminalSession;
+  dispatchKey(key: string): string;
+  output(): string;
+  ansiOutput(): string;
+  isRunning(): boolean;
+  destroy(): void;
+}
+
+type InvoiceLine = { name: string; unit: Money; quantity: number };
+type InvoiceState = { selected: number; discount: boolean; localeIndex: number; lines: InvoiceLine[] };
+
+const LOCALES = [
+  { label: "US / USD", locale: "en-US", currency: "USD" },
+  { label: "MX / USD", locale: "es-MX", currency: "USD" }
+] as const;
+const INITIAL_LINES: InvoiceLine[] = [
+  { name: "Support seats", unit: parseMoneyInput("49.00", { locale: "en-US" }), quantity: 3 },
+  { name: "Priority add-on", unit: Money.fromDecimal(120), quantity: 1 },
+  { name: "Storage pack", unit: Money.fromCents(2500), quantity: 2 }
+];
+const TAX_RATE = 0.16;
+const DISCOUNT_RATE = 0.1;
+const PANEL_STYLE = { color: "#f8fafc", background: "#111827", padding: { left: 1, right: 1 } };
+const FOOTER_STYLE = { color: "#dbeafe", background: "#1e293b" };
+
+function shouldRunSnapshot() {
+  return process.argv.includes("--snapshot") || process.env.VALYRIAN_TERMINAL_EXAMPLE_SNAPSHOT === "1" || !process.stdin.isTTY;
+}
+
+function cloneLines() {
+  return INITIAL_LINES.map((line) => ({ ...line }));
+}
+
+function moneyView(value: Money, state: InvoiceState) {
+  const locale = LOCALES[state.localeIndex];
+  return formatMoney(value, { currency: locale.currency, locale: locale.locale, digits: 2 });
+}
+
+function invoiceTotals(state: InvoiceState) {
+  const subtotal = state.lines.reduce((total, line) => total.add(line.unit.multiply(line.quantity)), Money.fromCents(0));
+  const discount = state.discount ? subtotal.multiply(DISCOUNT_RATE) : Money.fromCents(0);
+  const taxable = subtotal.subtract(discount);
+  const tax = taxable.multiply(TAX_RATE);
+  const total = taxable.add(tax);
+  return { subtotal, discount, tax, total };
+}
+
+export function App({ state }: { state: InvoiceState }) {
+  const totals = invoiceTotals(state);
+  const locale = LOCALES[state.localeIndex];
+
+  return (
+    <Screen title="Invoice Calculator">
+      <Text style={{ color: "#ffffff", background: "#020617" }}>Invoice Calculator</Text>
+      <Pane style={PANEL_STYLE}>
+        <Text>Invoice Calculator</Text>
+        <Text>{`Locale: ${locale.label}`}</Text>
+        {state.lines.map((line, index) => (
+          <Text>{`${index === state.selected ? ">" : " "} ${line.name} x${line.quantity} — ${moneyView(line.unit.multiply(line.quantity), state)}`}</Text>
+        ))}
+        <Text>{`Subtotal: ${moneyView(totals.subtotal, state)}`}</Text>
+        <Text>{`Discount: ${state.discount ? moneyView(totals.discount, state) : "none"}`}</Text>
+        <Text>{`Tax: ${moneyView(totals.tax, state)}`}</Text>
+        <Text>{`Total: ${moneyView(totals.total, state)}`}</Text>
+      </Pane>
+      <Text style={FOOTER_STYLE}>J/K line   +/- quantity   D discount   L locale   Ctrl+C: quit</Text>
+    </Screen>
+  );
+}
+
+export function createModuleMoneyDemo(options: TerminalMountOptions = {}): ModuleDemo {
+  const state: InvoiceState = { selected: 0, discount: false, localeIndex: 0, lines: cloneLines() };
+  let running = true;
+  let session: TerminalSession;
+
+  function quit() {
+    running = false;
+    session.destroy();
+  }
+
+  function changeQuantity(delta: number) {
+    const line = state.lines[state.selected];
+    line.quantity = Math.max(0, line.quantity + delta);
+  }
+
+  session = mountTerminal(<App state={state} />, {
+    ...options,
+    cols: options.cols ?? 92,
+    rows: options.rows ?? 20,
+    keymap: {
+      ...options.keymap,
+      bindings: [
+        ...(options.keymap?.bindings || []),
+        { key: "j", command: { id: "invoice.next" }, scope: "global" },
+        { key: "J", command: { id: "invoice.next" }, scope: "global" },
+        { key: "k", command: { id: "invoice.previous" }, scope: "global" },
+        { key: "K", command: { id: "invoice.previous" }, scope: "global" },
+        { key: "+", command: { id: "invoice.increase" }, scope: "global" },
+        { key: "-", command: { id: "invoice.decrease" }, scope: "global" },
+        { key: "d", command: { id: "invoice.discount" }, scope: "global" },
+        { key: "D", command: { id: "invoice.discount" }, scope: "global" },
+        { key: "l", command: { id: "invoice.locale" }, scope: "global" },
+        { key: "L", command: { id: "invoice.locale" }, scope: "global" },
+        { key: "CTRL_C", command: { id: "quit" }, scope: "global" }
+      ],
+      onCommand(command, context) {
+        if (command.id === "invoice.next") {
+          state.selected = (state.selected + 1) % state.lines.length;
+          return true;
+        }
+        if (command.id === "invoice.previous") {
+          state.selected = (state.selected - 1 + state.lines.length) % state.lines.length;
+          return true;
+        }
+        if (command.id === "invoice.increase") {
+          changeQuantity(1);
+          return true;
+        }
+        if (command.id === "invoice.decrease") {
+          changeQuantity(-1);
+          return true;
+        }
+        if (command.id === "invoice.discount") {
+          state.discount = !state.discount;
+          return true;
+        }
+        if (command.id === "invoice.locale") {
+          state.localeIndex = (state.localeIndex + 1) % LOCALES.length;
+          return true;
+        }
+        if (command.id === "quit") {
+          quit();
+          return true;
+        }
+        return options.keymap?.onCommand?.(command, context);
+      }
+    }
+  });
+
+  return {
+    session,
+    dispatchKey(key: string) {
+      return session.dispatchKey(key);
+    },
+    output() {
+      return session.output();
+    },
+    ansiOutput() {
+      return session.ansiOutput();
+    },
+    isRunning() {
+      return running;
+    },
+    destroy() {
+      running = false;
+      session.destroy();
+    }
+  };
+}
+
+if (import.meta.main) {
+  if (shouldRunSnapshot()) {
+    const demo = createModuleMoneyDemo({ runtime: "headless", cols: 92, rows: 20 });
+    process.stdout.write(demo.output());
+    process.stdout.write("\n");
+    demo.destroy();
+  } else {
+    createModuleMoneyDemo();
+  }
+}

package/examples/docs/module-native-store.tsx

@@ -0,0 +1,188 @@
+import { createNativeStore, StorageType } from "valyrian.js/native-store";
+import { Input, Pane, Screen, Text, mountTerminal } from "@valyrianjs/terminal";
+import type { TerminalMountOptions, TerminalSession } from "@valyrianjs/terminal";
+
+interface ModuleDemo {
+  session: TerminalSession;
+  dispatchKey(key: string): string;
+  output(): string;
+  ansiOutput(): string;
+  isRunning(): boolean;
+  destroy(): void;
+}
+
+type NativeStoreDemoOptions = TerminalMountOptions & {
+  storeKey?: string;
+  resetOnStart?: boolean;
+};
+
+interface WorkspaceSettingsState {
+  draftWorkspace: string;
+  restoredWorkspace: string;
+  savedWorkspace: string;
+  status: string;
+}
+
+const DEFAULT_WORKSPACE = "Northwind CLI";
+const DEFAULT_STORE_KEY = "valyrian-terminal-docs.workspace-settings";
+const PANEL_STYLE = { color: "#f8fafc", background: "#111827", padding: { left: 1, right: 1 } };
+const FIELD_STYLE = { color: "#ffffff", background: "#0f3b3e", padding: { left: 1, right: 1 } };
+const FOOTER_STYLE = { color: "#dbeafe", background: "#1e293b" };
+
+function shouldRunSnapshot() {
+  return process.argv.includes("--snapshot") || process.env.VALYRIAN_TERMINAL_EXAMPLE_SNAPSHOT === "1" || !process.stdin.isTTY;
+}
+
+
+function normalizeWorkspace(value: unknown) {
+  const workspace = String(value ?? "").trim();
+  return workspace.length > 0 ? workspace : DEFAULT_WORKSPACE;
+}
+
+export function App({ state, onSave }: { state: WorkspaceSettingsState; onSave: () => void }) {
+  return (
+    <Screen title="Persistent Workspace Settings">
+      <Text style={{ color: "#ffffff", background: "#020617" }}>Persistent Workspace Settings</Text>
+      <Pane style={FIELD_STYLE}>
+        <Text>Workspace name</Text>
+        <Input
+          id="workspace-name"
+          value={state.draftWorkspace}
+          placeholder="Workspace name"
+          onchange={(event) => {
+            state.draftWorkspace = event.value;
+            state.status = "editing workspace setting";
+          }}
+          onsubmit={onSave}
+        />
+        <Text>{`Draft workspace: ${state.draftWorkspace || "blank"}`}</Text>
+      </Pane>
+      <Pane style={PANEL_STYLE}>
+        <Text>{`Restored workspace: ${state.restoredWorkspace}`}</Text>
+        <Text>{`Saved workspace: ${state.savedWorkspace}`}</Text>
+        <Text>{`Settings status: ${state.status}`}</Text>
+        <Text>Local native-store keeps workspace settings outside the renderer.</Text>
+      </Pane>
+      <Text style={FOOTER_STYLE}>Type workspace | Enter: save setting | R: reset setting | Ctrl+C: quit</Text>
+    </Screen>
+  );
+}
+
+export function createModuleNativeStoreDemo(options: NativeStoreDemoOptions = {}): ModuleDemo {
+  const settings = createNativeStore<{ workspace: string }>(options.storeKey ?? DEFAULT_STORE_KEY, {}, StorageType.Session, true);
+  if (options.resetOnStart) {
+    settings.clear();
+  }
+
+  function loadWorkspace() {
+    const restored = normalizeWorkspace(settings.get("workspace"));
+    if (settings.get("workspace") !== restored) settings.set("workspace", restored);
+    return restored;
+  }
+
+  const restoredWorkspace = loadWorkspace();
+  const state: WorkspaceSettingsState = {
+    draftWorkspace: restoredWorkspace,
+    restoredWorkspace,
+    savedWorkspace: restoredWorkspace,
+    status: "loaded saved setting"
+  };
+  let running = true;
+  let session: TerminalSession;
+
+  function saveWorkspace() {
+    const workspace = normalizeWorkspace(state.draftWorkspace);
+    settings.set("workspace", workspace);
+    state.draftWorkspace = workspace;
+    state.savedWorkspace = workspace;
+    state.restoredWorkspace = workspace;
+    state.status = "saved setting";
+  }
+
+  function reloadWorkspace() {
+    settings.load();
+    const workspace = loadWorkspace();
+    state.draftWorkspace = workspace;
+    state.savedWorkspace = workspace;
+    state.restoredWorkspace = workspace;
+    state.status = "loaded saved setting";
+  }
+
+  function resetWorkspace() {
+    settings.clear();
+    settings.set("workspace", DEFAULT_WORKSPACE);
+    state.draftWorkspace = "";
+    state.savedWorkspace = DEFAULT_WORKSPACE;
+    state.restoredWorkspace = DEFAULT_WORKSPACE;
+    state.status = "reset to default";
+  }
+
+  function quit() {
+    running = false;
+    settings.cleanup();
+    session.destroy();
+  }
+
+  session = mountTerminal(<App state={state} onSave={saveWorkspace} />, {
+    ...options,
+    cols: options.cols ?? 92,
+    rows: options.rows ?? 18,
+    keymap: {
+      ...options.keymap,
+      bindings: [
+        ...(options.keymap?.bindings || []),
+        { key: "R", command: { id: "store.reset" }, scope: "global" },
+        { key: "CTRL_C", command: { id: "quit" }, scope: "global" }
+      ],
+      onCommand(command, context) {
+        if (command.id === "store.reset") {
+          resetWorkspace();
+          return true;
+        }
+        if (command.id === "quit") {
+          quit();
+          return true;
+        }
+        return options.keymap?.onCommand?.(command, context);
+      }
+    }
+  });
+
+  session.focus("workspace-name");
+
+  return {
+    session,
+    dispatchKey(key: string) {
+      return session.dispatchKey(key);
+    },
+    output() {
+      return session.output();
+    },
+    ansiOutput() {
+      return session.ansiOutput();
+    },
+    isRunning() {
+      return running;
+    },
+    destroy() {
+      running = false;
+      settings.cleanup();
+      session.destroy();
+    }
+  };
+}
+
+if (import.meta.main) {
+  if (shouldRunSnapshot()) {
+    const demo = createModuleNativeStoreDemo({ runtime: "headless", cols: 92, rows: 18, resetOnStart: true });
+    demo.dispatchKey("R");
+    demo.session.focus("workspace-name");
+    for (const key of "Support CLI") demo.dispatchKey(key);
+    demo.dispatchKey("ENTER");
+    process.stdout.write(demo.output());
+    process.stdout.write("\n");
+    demo.destroy();
+  } else {
+    createModuleNativeStoreDemo();
+  }
+}