@valyrianjs/terminal 0.2.1 → 0.2.2

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

@@ -0,0 +1,181 @@
+import { FluxStore } from "valyrian.js/flux-store";
+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 JobStatus = "queued" | "running" | "done" | "blocked";
+type Job = { name: string; status: JobStatus };
+type QueueState = { selected: number; jobs: Job[] };
+
+type QueueGetters = { doneCount: number; activeJob: string };
+type QueueStore = FluxStore & { state: QueueState; getters: QueueGetters };
+
+const INITIAL_JOBS: Job[] = [
+  { name: "Sync warehouse feed", status: "queued" },
+  { name: "Package release", status: "queued" },
+  { name: "Review failed payouts", status: "blocked" }
+];
+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 createQueueStore(): QueueStore {
+  return new FluxStore({
+    state: { selected: 0, jobs: INITIAL_JOBS.map((job) => ({ ...job })) },
+    mutations: {
+      SELECT_NEXT(state) {
+        const queueState = state as QueueState;
+        queueState.selected = (queueState.selected + 1) % queueState.jobs.length;
+      },
+      SELECT_PREVIOUS(state) {
+        const queueState = state as QueueState;
+        queueState.selected = (queueState.selected - 1 + queueState.jobs.length) % queueState.jobs.length;
+      },
+      SET_STATUS(state, status: JobStatus) {
+        const queueState = state as QueueState;
+        queueState.jobs = queueState.jobs.map((job, index) => (index === queueState.selected ? { ...job, status } : job));
+      },
+      RESET(state) {
+        const queueState = state as QueueState;
+        queueState.selected = 0;
+        queueState.jobs = INITIAL_JOBS.map((job) => ({ ...job }));
+      }
+    },
+    getters: {
+      doneCount(state) {
+        const queueState = state as QueueState;
+        return queueState.jobs.filter((job) => job.status === "done").length;
+      },
+      activeJob(state) {
+        const queueState = state as QueueState;
+        return queueState.jobs[queueState.selected].name;
+      }
+    }
+  }) as QueueStore;
+}
+
+export function App({ store }: { store: QueueStore }) {
+  return (
+    <Screen title="Operations Queue Manager">
+      <Text style={{ color: "#ffffff", background: "#020617" }}>Operations Queue Manager</Text>
+      <Pane style={PANEL_STYLE}>
+        <Text>Queue Manager</Text>
+        {store.state.jobs.map((job, index) => (
+          <Text>{`${index === store.state.selected ? ">" : " "} ${job.name} — ${job.status}`}</Text>
+        ))}
+        <Text>{`Selected: ${store.getters.activeJob}`}</Text>
+        <Text>{`Done jobs: ${store.getters.doneCount}`}</Text>
+      </Pane>
+      <Text style={FOOTER_STYLE}>J/K select   S start   D mark done   B block   R reset   Ctrl+C: quit</Text>
+    </Screen>
+  );
+}
+
+export function createModuleFluxStoreDemo(options: TerminalMountOptions = {}): ModuleDemo {
+  const store = createQueueStore();
+  let running = true;
+  let session: TerminalSession;
+
+  function quit() {
+    running = false;
+    session.destroy();
+  }
+
+  session = mountTerminal(<App store={store} />, {
+    ...options,
+    cols: options.cols ?? 92,
+    rows: options.rows ?? 18,
+    keymap: {
+      ...options.keymap,
+      bindings: [
+        ...(options.keymap?.bindings || []),
+        { key: "j", command: { id: "queue.next" }, scope: "global" },
+        { key: "J", command: { id: "queue.next" }, scope: "global" },
+        { key: "k", command: { id: "queue.previous" }, scope: "global" },
+        { key: "K", command: { id: "queue.previous" }, scope: "global" },
+        { key: "s", command: { id: "queue.start" }, scope: "global" },
+        { key: "S", command: { id: "queue.start" }, scope: "global" },
+        { key: "d", command: { id: "queue.done" }, scope: "global" },
+        { key: "D", command: { id: "queue.done" }, scope: "global" },
+        { key: "b", command: { id: "queue.block" }, scope: "global" },
+        { key: "B", command: { id: "queue.block" }, scope: "global" },
+        { key: "r", command: { id: "queue.reset" }, scope: "global" },
+        { key: "R", command: { id: "queue.reset" }, scope: "global" },
+        { key: "CTRL_C", command: { id: "quit" }, scope: "global" }
+      ],
+      onCommand(command, context) {
+        if (command.id === "queue.next") {
+          store.commit("SELECT_NEXT");
+          return true;
+        }
+        if (command.id === "queue.previous") {
+          store.commit("SELECT_PREVIOUS");
+          return true;
+        }
+        if (command.id === "queue.start") {
+          store.commit("SET_STATUS", "running");
+          return true;
+        }
+        if (command.id === "queue.done") {
+          store.commit("SET_STATUS", "done");
+          return true;
+        }
+        if (command.id === "queue.block") {
+          store.commit("SET_STATUS", "blocked");
+          return true;
+        }
+        if (command.id === "queue.reset") {
+          store.commit("RESET");
+          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 = createModuleFluxStoreDemo({ runtime: "headless", cols: 92, rows: 18 });
+    process.stdout.write(demo.output());
+    process.stdout.write("\n");
+    demo.destroy();
+  } else {
+    createModuleFluxStoreDemo();
+  }
+}

package/examples/docs/module-form-workflow.tsx

@@ -0,0 +1,339 @@
+import { FormStore } from "valyrian.js/forms";
+import { Money, formatMoney, parseMoneyInput } from "valyrian.js/money";
+import { createNativeStore, StorageType } from "valyrian.js/native-store";
+import { setLang, setLog, setStoreStrategy, setTranslations, t } from "valyrian.js/translate";
+import { get, set } from "valyrian.js/utils";
+import { Input, Pane, Screen, Split, Text, mountTerminal } from "@valyrianjs/terminal";
+import type { TerminalMountOptions, TerminalSession } from "@valyrianjs/terminal";
+
+type Language = "en" | "es";
+
+type BillingForm = {
+  name: string;
+  seats: number;
+  budgetCents: number;
+};
+
+interface SavedBilling {
+  name: string;
+  seats: number;
+  budgetCents: number;
+  workspace: string;
+}
+
+interface FormWorkflowState {
+  language: Language;
+  savedWorkspace: string;
+  savedBilling: SavedBilling | null;
+  saveMessage: string;
+  resetMessage: string;
+  running: boolean;
+}
+
+interface ModuleFormWorkflowDemo {
+  session: TerminalSession;
+  dispatchKey(key: string): string;
+  output(): string;
+  ansiOutput(): string;
+  isRunning(): boolean;
+  destroy(): void;
+}
+
+type FormWorkflowOptions = TerminalMountOptions & {
+  storeKey?: string;
+};
+
+const DEFAULT_STORE_KEY = "valyrian-terminal-docs.billing-settings-wizard";
+const DEFAULT_WORKSPACE = "Northwind CLI";
+
+const SHELL_STYLE = { color: "#f8fafc", background: "#111827", padding: { left: 1, right: 1 } };
+const FORM_STYLE = { color: "#ffffff", background: "#0f3b3e", padding: { left: 1, right: 1 } };
+const SUMMARY_STYLE = { color: "#ffffff", background: "#3b1f4f", padding: { left: 1, right: 1 } };
+const FOOTER_STYLE = { color: "#e5e7eb", background: "#1f2937" };
+const MUTED_STYLE = { color: "#cbd5e1" };
+const ERROR_STYLE = { color: "#fecaca" };
+
+function shouldRunSnapshot() {
+  return process.argv.includes("--snapshot") || process.env.VALYRIAN_TERMINAL_EXAMPLE_SNAPSHOT === "1" || !process.stdin.isTTY;
+}
+
+
+function configureTranslations() {
+  setLog(false);
+  let storedLanguage = "en";
+  setStoreStrategy({
+    get: () => storedLanguage,
+    set: (language) => {
+      storedLanguage = language;
+    }
+  });
+  setTranslations(
+    {
+      heading: "Billing/Settings Wizard",
+      language: "Language: English",
+      workspace: "Workspace",
+      customer: "Customer",
+      seats: "Seats",
+      budget: "Budget"
+    },
+    {
+      es: {
+        heading: "Asistente de cobro/configuración",
+        language: "Idioma: español",
+        workspace: "Espacio",
+        customer: "Cliente",
+        seats: "Asientos",
+        budget: "Presupuesto"
+      }
+    }
+  );
+}
+
+function parseSeats(value: unknown) {
+  const seats = Number(String(value).trim());
+  return Number.isFinite(seats) ? seats : 0;
+}
+
+function parseBudgetCents(value: unknown) {
+  try {
+    return parseMoneyInput(String(value), { decimalPlaces: 2 }).toCents();
+  } catch {
+    return -1;
+  }
+}
+
+function createBillingForm(onSaved: (billing: SavedBilling) => void) {
+  return new FormStore<BillingForm>({
+    state: { name: "Ada", seats: 12, budgetCents: 129950 },
+    schema: {
+      type: "object",
+      properties: {
+        name: { type: "string", minLength: 1 },
+        seats: { type: "number", minimum: 1 },
+        budgetCents: { type: "number", minimum: 100 }
+      },
+      required: ["name", "seats", "budgetCents"]
+    },
+    clean: {
+      name: (value) => String(value).trim(),
+      seats: parseSeats,
+      budgetCents: parseBudgetCents
+    },
+    format: {
+      seats: (value) => String(value),
+      budgetCents: (value) => (Number(value) / 100).toFixed(2)
+    },
+    onSubmit(values) {
+      onSaved({
+        name: values.name,
+        seats: values.seats,
+        budgetCents: values.budgetCents,
+        workspace: DEFAULT_WORKSPACE
+      });
+    }
+  });
+}
+
+function formatBudget(cents: number, language: Language) {
+  const money = Money.fromCents(Number.isFinite(cents) ? cents : 0);
+  return formatMoney(money, { currency: "USD", locale: language === "es" ? "es-MX" : "en-US" });
+}
+
+function fieldError(form: FormStore<BillingForm>, field: keyof BillingForm) {
+  return String(form.validationErrors[field] || "not checked");
+}
+
+function savedSummary(saved: SavedBilling | null, language: Language) {
+  if (!saved) return "none";
+  return `${saved.name} / ${saved.seats} seats / ${formatBudget(saved.budgetCents, language)}`;
+}
+
+export function App({ form, state, onSubmit }: { form: FormStore<BillingForm>; state: FormWorkflowState; onSubmit: () => void }) {
+  setLang(state.language);
+  const data = { billing: { name: form.state.name, seats: form.state.seats } };
+  set(data, "billing.workspace", DEFAULT_WORKSPACE);
+  set(data, "billing.total", formatBudget(form.state.budgetCents, state.language));
+  const workspace = String(get(data, "billing.workspace", DEFAULT_WORKSPACE));
+  const displayBudget = String(get(data, "billing.total", formatBudget(0, state.language)));
+
+  return (
+    <Screen title="Billing/Settings Wizard">
+      <Text style={{ color: "#ffffff", background: "#020617" }}>Valyrian.js modules in terminal apps: form workflow</Text>
+      <Split direction="row" gap={1} sizes={["1fr", "1fr"]}>
+        <Pane style={FORM_STYLE}>
+          <Text>{t("heading")}</Text>
+          <Text>{t("language")}</Text>
+          <Text>{`${t("workspace")}: ${workspace}`}</Text>
+          <Text>{t("customer")}</Text>
+          <Input id="billing-name" value={String(form.state.name)} placeholder="Customer name" onchange={(event) => form.setField("name", event.value)} onsubmit={onSubmit} />
+          <Text>{`Name: ${form.state.name || "missing"}`}</Text>
+          <Text style={ERROR_STYLE}>{`Name error: ${fieldError(form, "name")}`}</Text>
+          <Text>{t("seats")}</Text>
+          <Input id="billing-seats" value={String(form.formatValue("seats", form.state.seats))} placeholder="Seat count" onchange={(event) => form.setField("seats", event.value)} onsubmit={onSubmit} />
+          <Text>{`Seats: ${form.state.seats}`}</Text>
+          <Text style={ERROR_STYLE}>{`Seats error: ${fieldError(form, "seats")}`}</Text>
+          <Text>{t("budget")}</Text>
+          <Input id="billing-budget" value={String(form.formatValue("budgetCents", form.state.budgetCents))} placeholder="Monthly budget" onchange={(event) => form.setField("budgetCents", event.value)} onsubmit={onSubmit} />
+          <Text>{`Budget: ${displayBudget}`}</Text>
+          <Text style={ERROR_STYLE}>{`Budget error: ${fieldError(form, "budgetCents")}`}</Text>
+        </Pane>
+        <Pane style={SUMMARY_STYLE}>
+          <Text>Cleaned billing summary</Text>
+          <Text>{`Workspace: ${workspace}`}</Text>
+          <Text>{`Saved workspace: ${state.savedWorkspace || "none"}`}</Text>
+          <Text>{`Saved billing: ${savedSummary(state.savedBilling, state.language)}`}</Text>
+          <Text>{`Form dirty: ${form.isDirty}`}</Text>
+          <Text>{`Form success: ${form.success}`}</Text>
+          <Text>{`Save: ${state.saveMessage}`}</Text>
+          <Text>{`Reset: ${state.resetMessage}`}</Text>
+          <Text style={MUTED_STYLE}>Forms clean input, native-store persists workspace, translate changes labels, money formats totals, and utils shape summary data.</Text>
+        </Pane>
+      </Split>
+      <Pane style={SHELL_STYLE}>
+        <Text>N: fill name   Tab: next field   Shift+Tab: previous field   L: language   S/Enter: save   R: reset form   X: clear saved   Ctrl+C: quit</Text>
+        <Text style={FOOTER_STYLE}>See the Valyrian.js documentation for forms, native-store, translate, money, and utils.</Text>
+      </Pane>
+    </Screen>
+  );
+}
+
+export function createModuleFormWorkflowDemo(options: FormWorkflowOptions = {}): ModuleFormWorkflowDemo {
+  configureTranslations();
+  const settings = createNativeStore<{ workspace: string }>(options.storeKey ?? DEFAULT_STORE_KEY, {}, StorageType.Session, true);
+  const state: FormWorkflowState = {
+    language: "en",
+    savedWorkspace: String(settings.get("workspace") || ""),
+    savedBilling: null,
+    saveMessage: "not saved",
+    resetMessage: "not reset",
+    running: true
+  };
+  const form = createBillingForm((billing) => {
+    state.savedBilling = billing;
+    state.savedWorkspace = billing.workspace;
+    settings.set("workspace", billing.workspace);
+    state.saveMessage = `saved ${billing.name} for ${billing.seats} seats`;
+  });
+  let session: TerminalSession;
+
+  function quit() {
+    state.running = false;
+    settings.cleanup();
+    session.destroy();
+  }
+
+  function resetForm() {
+    form.reset();
+    state.savedBilling = null;
+    state.savedWorkspace = "";
+    state.saveMessage = "not saved";
+    state.resetMessage = "form reset";
+    settings.clear();
+    session.update();
+  }
+
+  async function submitForm() {
+    const ok = await form.submit();
+    if (!ok) {
+      state.saveMessage = "blocked by validation";
+    }
+    session.update();
+  }
+
+  session = mountTerminal(<App form={form} state={state} onSubmit={submitForm} />, {
+    ...options,
+    cols: options.cols ?? 100,
+    rows: options.rows ?? 24,
+    keymap: {
+      ...options.keymap,
+      bindings: [
+        ...(options.keymap?.bindings || []),
+        { key: "n", command: { id: "form.name" }, scope: "global" },
+        { key: "N", command: { id: "form.name" }, scope: "global" },
+        { key: "l", command: { id: "form.language" }, scope: "global" },
+        { key: "L", command: { id: "form.language" }, scope: "global" },
+        { key: "s", command: { id: "form.save" }, scope: "global" },
+        { key: "S", command: { id: "form.save" }, scope: "global" },
+        { key: "r", command: { id: "form.reset" }, scope: "global" },
+        { key: "R", command: { id: "form.reset" }, scope: "global" },
+        { key: "x", command: { id: "form.clear" }, scope: "global" },
+        { key: "X", command: { id: "form.clear" }, scope: "global" },
+        { key: "CTRL_C", command: { id: "quit" }, scope: "global" }
+      ],
+      onCommand(command, context) {
+        if (command.id === "form.name") {
+          form.setField("name", "Ada Lovelace");
+          session.update();
+          return true;
+        }
+        if (command.id === "form.language") {
+          state.language = state.language === "en" ? "es" : "en";
+          setLang(state.language);
+          session.update();
+          return true;
+        }
+        if (command.id === "form.save") {
+          void submitForm();
+          return true;
+        }
+        if (command.id === "form.reset") {
+          resetForm();
+          return true;
+        }
+        if (command.id === "form.clear") {
+          state.savedWorkspace = "";
+          state.savedBilling = null;
+          state.saveMessage = "not saved";
+          settings.clear();
+          session.update();
+          return true;
+        }
+        if (command.id === "quit") {
+          quit();
+          return true;
+        }
+        return options.keymap?.onCommand?.(command, context);
+      }
+    }
+  });
+
+  session.focus("billing-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;
+      settings.cleanup();
+      session.destroy();
+    }
+  };
+}
+
+if (import.meta.main) {
+  if (shouldRunSnapshot()) {
+    const demo = createModuleFormWorkflowDemo({ runtime: "headless", cols: 100, rows: 24 });
+    demo.dispatchKey("S");
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    demo.dispatchKey("N");
+    demo.dispatchKey("L");
+    demo.dispatchKey("S");
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    process.stdout.write(demo.output());
+    process.stdout.write("\n");
+    demo.destroy();
+  } else {
+    createModuleFormWorkflowDemo();
+  }
+}