@valyrianjs/terminal 0.2.1 → 0.2.3

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();
+  }
+}

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();
+  }
+}