@jarenjs/play 0.34.0

package/src/index.js

@@ -0,0 +1,157 @@
+//@ts-check
+/**
+ * @file `@jarenjs/play` — a JSON-engine playground. Pick an engine, feed
+ * it a source input and one or more datasets, and watch it run — a way to
+ * understand an engine standalone before composing it in the studio.
+ *
+ * The model (PLAY-FORMAT.md): each engine is a DESCRIPTOR — the panes it
+ * consumes (`sourcePanes` = the input; `dataPanes` = the JSON it runs
+ * against, possibly none) plus a pure `run`. Each EXAMPLE presets those
+ * source panes plus a LIST of datasets: 0 = the engine takes no data
+ * (markdown/mermaid), 1 = one dataset, N = a dataset switcher (the same
+ * source over several shapes). The engine registry and the example library
+ * fill in over the next orders; this is the headless core the component
+ * renders.
+ */
+
+import { ENGINE_LIST } from './engines.js';
+import { EXAMPLE_LIST } from './examples.js';
+
+/**
+ * @typedef {Object} EnginePane
+ * @property {string} key - the pane's id (e.g. 'selector', 'data')
+ * @property {string} label
+ * @property {'code' | 'text'} [control]
+ */
+
+/**
+ * @typedef {Object} OptionPane
+ * A live select above the editors — a mode an engine runs in (JOSL vs TOML,
+ * CSV strict vs repair). Its value lives in the host's `config` slice.
+ * @property {string} key
+ * @property {string} label
+ * @property {Array<{ value: string, label: string }>} choices
+ * @property {string} default - the value used until the user picks another
+ */
+
+/**
+ * @typedef {Object} Panel
+ * A single result SCREEN. Every ok run yields at least one; a multi-screen
+ * engine (CSV: a summary note, the parsed table, the CSV round-trip) yields
+ * several, which the component shows behind a tab strip.
+ * @property {string} id - unique within the result (the tab key)
+ * @property {string} [label] - the tab label (defaults to `id`)
+ * @property {'code' | 'view' | 'table' | 'note' | 'cards'} kind
+ * @property {'simple' | 'deep'} [depth] - `deep` panels are the engine's rich
+ *   explainers, hidden until the student drills in via the depth toggle;
+ *   defaults to `simple` (the calm default view)
+ * @property {string} [text] - `code` / `note`: the text body
+ * @property {any} [vnode] - `view`: a host-rendered vnode, spliced verbatim
+ * @property {string[]} [columns] - `table`: the header labels
+ * @property {Array<Array<any>>} [rows] - `table`: cells, row-major
+ * @property {'ok' | 'warn' | 'info'} [tone] - `note`: the callout tone
+ * @property {Array<{ title: string, value: string, note?: string }>} [items]
+ *   `cards`: a row of stat cards (matches, compile/run timings, …)
+ */
+
+/**
+ * @typedef {Object} PlayResult
+ * @property {boolean} ok
+ * @property {{ compileMs: number, runMs: number } | null} timing
+ * @property {{ message: string, code?: string, path?: string } | null} error
+ * @property {Panel[]} panels - the result screens (`[]` on error); a single
+ *   `code` panel for most engines, several for the richer ones
+ */
+
+/**
+ * @typedef {Object} EngineDescriptor
+ * @property {string} id
+ * @property {string} label
+ * @property {string} [lead] - one line describing the engine
+ * @property {EnginePane[]} sourcePanes - the engine INPUT pane(s)
+ * @property {EnginePane[]} dataPanes - the JSON it runs against (may be [])
+ * @property {OptionPane[]} [optionPanes] - live mode selects (may be absent)
+ * @property {(source: Record<string, string>, data: Record<string, string>, options?: RunOptions) => PlayResult} run
+ */
+
+/**
+ * @typedef {Object} RunOptions
+ * @property {any} [operators] - a host operator registry ({ toOptions() }) for query/jslt/jtlt
+ * @property {Record<string, string>} [config] - the current option-pane values
+ * @property {Record<string, (source: string, config?: any) => any>} [renderers]
+ *   host-injected vnode renderers keyed by engine id — the visual engines
+ *   (markdown/mermaid/charts) delegate their rendering here (the hybrid seam),
+ *   so the package owns the descriptors + examples but stays dependency-light.
+ *   A renderer receives the source text plus its second argument — the
+ *   option-pane config for the visual engines, the PARSED data document for
+ *   `mdx` — and returns the preview vnode, or `{ vnode, deep }` where `deep`
+ *   is extra `Panel`s (AST, canonical round-trip) the host derives — shown
+ *   only behind the depth toggle
+ * @property {(schemaText: string, data: any, locale: string) => { schemaError: string|null, draft: string, compileMs: number|null, validateMs: number|null, valid: boolean|null, errors: any[] }} [validate]
+ *   host-injected JSON Schema validator (the same seam) — the `validate`
+ *   engine delegates here so @jarenjs/validate + the locale packs stay in the host
+ */
+
+/**
+ * @typedef {Object} PlayExample
+ * @property {string} id
+ * @property {string} label
+ * @property {string} engine - an engine id
+ * @property {Record<string, string>} source - presets the source pane(s)
+ * @property {Array<{ label: string, data: Record<string, string> }>} datasets
+ *   the JSON to run against — `[]` for a source-only engine (josl/csv/md),
+ *   one for a single run, several for a switcher
+ * @property {Record<string, string>} [config] - presets option-pane values
+ */
+
+/** The registered engines, by id. */
+export const ENGINES = Object.freeze(/** @type {Record<string, EngineDescriptor>} */ (
+  Object.fromEntries(ENGINE_LIST.map((e) => [e.id, e]))));
+
+/** The ids of the registered engines, in registration order. */
+export function engineIds() {
+  return ENGINE_LIST.map((e) => e.id);
+}
+
+/** The curated example library (the canonical home for the suite's engine
+ * examples). */
+export const EXAMPLES = Object.freeze(/** @type {PlayExample[]} */ (EXAMPLE_LIST));
+
+/**
+ * Fill an engine's option-pane defaults so its runner always sees a
+ * complete `config` (the host `config` slice may hold only user overrides).
+ * @param {EngineDescriptor} engine
+ * @param {{ operators?: any, config?: Record<string, string> }} options
+ */
+function withConfig(engine, options) {
+  const panes = engine.optionPanes ?? [];
+  if (panes.length === 0) return options;
+  const given = options.config ?? {};
+  /** @type {Record<string, string>} */
+  const config = {};
+  for (const p of panes) config[p.key] = given[p.key] ?? p.default;
+  return { ...options, config };
+}
+
+/**
+ * Run one engine over a source + data. An unknown engine (or a throwing
+ * runner) yields an error Result — this never throws.
+ * @param {string} engineId
+ * @param {Record<string, string>} source
+ * @param {Record<string, string>} data
+ * @param {RunOptions} [options] - operators (query/jslt), the option-pane
+ *   config, and host renderers (markdown/mermaid/charts)
+ * @returns {PlayResult}
+ */
+export function runExample(engineId, source, data, options = {}) {
+  const engine = ENGINES[engineId];
+  if (engine === undefined) {
+    return { ok: false, timing: null, error: { message: `unknown engine: ${engineId}` }, panels: [] };
+  }
+  try {
+    return engine.run(source ?? {}, data ?? {}, withConfig(engine, options));
+  }
+  catch (err) {
+    return { ok: false, timing: null, error: { message: String(/** @type {any} */ (err)?.message ?? err) }, panels: [] };
+  }
+}

package/styles/play.css

@@ -0,0 +1,176 @@
+/* @jarenjs/play — the playground stylesheet.
+ *
+ * DESIGN.md-conformant: a rail | editors | stage grid, minmax(0,1fr) tracks
+ * with min-width:0 on every scrollable child, the established 1024
+ * breakpoint and theme tokens. Base controls (.editor, .seg / .seg-btn,
+ * .error-line, .code-block, .muted) are the host's shared styles — the
+ * playground only adds its own .jplay-* rules, no new hue family.
+ */
+
+.jplay {
+  display: grid;
+  --jplay-ratio: 0.5;
+  gap: var(--space-3, 0.75rem);
+  /* rail | editors (ratio-driven) | split | result (1fr absorbs the rest);
+     the play-splitter widget drives --jplay-ratio live during a drag */
+  grid-template-columns: 12rem minmax(0, calc((100% - 12rem) * var(--jplay-ratio))) auto minmax(0, 1fr);
+  grid-template-areas:
+    "bar bar bar bar"
+    "rail editors split stage";
+  grid-template-rows: auto minmax(0, 1fr);
+  min-height: 24rem;
+}
+/* the phone pane switcher exists only below the breakpoint */
+.jplay-mobilebar { display: none; }
+/* ——— the IDE bar (New/Save/Load/Share + the session name) ——— */
+.jplay-bar {
+  grid-area: bar; display: flex; align-items: center; gap: var(--space-2, 0.5rem);
+  flex-wrap: wrap; padding-bottom: var(--space-2, 0.5rem); border-bottom: 1px solid var(--border, #e2e8f0);
+}
+.jplay-title { color: var(--fg, #0f172a); }
+.jplay-name {
+  max-width: 12rem; min-width: 0;
+  border: 1px solid var(--border, #e2e8f0); border-radius: var(--radius-sm, 8px);
+  background: var(--bg, #fff); color: var(--fg, #0f172a);
+  padding: var(--space-1, 0.25rem) var(--space-3, 0.75rem); font: inherit; font-size: 0.85rem;
+}
+.jplay-actions { display: flex; gap: var(--space-1, 0.25rem); flex-wrap: wrap; align-items: center; }
+.jplay-load { max-width: 9rem; }
+.jplay-shared { margin-left: auto; }
+/* ——— the editors|result drag splitter (host = the grab bar) ——— */
+.jplay-split {
+  grid-area: split; cursor: col-resize; width: 10px; align-self: stretch; touch-action: none;
+  display: flex; align-items: center; justify-content: center;
+}
+.jplay-split::before { content: ''; width: 2px; height: 100%; background: var(--border, #e2e8f0); border-radius: 1px; }
+.jplay-split:hover::before, .jplay-split:focus-visible::before { background: var(--accent, #2563eb); }
+.jplay-split:focus-visible { outline: none; }
+.jplay-rail { grid-area: rail; min-width: 0; display: flex; flex-direction: column; overflow-y: auto; }
+.jplay-editors { grid-area: editors; min-width: 0; display: flex; flex-direction: column; gap: var(--space-2, 0.5rem); }
+.jplay-stage { grid-area: stage; min-width: 0; display: flex; flex-direction: column; }
+
+/* ——— the example rail ——— */
+.jplay-group-head {
+  font-size: 0.7rem; text-transform: uppercase; letter-spacing: 0.05em;
+  margin-block: var(--space-2, 0.5rem) 2px;
+}
+.jplay-ex {
+  display: block; width: 100%; text-align: left; border: none; background: transparent;
+  cursor: pointer; padding: 3px var(--space-2, 0.5rem);
+  border-radius: var(--radius-sm, 6px); border-left: 2px solid transparent;
+  color: var(--muted, #64748b); font-size: 0.85rem;
+  overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
+}
+.jplay-ex:hover { color: var(--fg, #0f172a); }
+.jplay-ex.active { color: var(--fg, #0f172a); background: var(--accent-soft, #eff6ff); border-left-color: var(--accent, #2563eb); }
+
+/* ——— the editors ——— */
+.jplay-head { display: flex; align-items: baseline; gap: var(--space-2, 0.5rem); flex-wrap: wrap; }
+.jplay-engine { color: var(--fg, #0f172a); }
+.jplay-lead { font-size: 0.8rem; }
+.jplay-pane { display: flex; flex-direction: column; gap: 2px; min-width: 0; }
+.jplay-pane-label { font-size: 0.7rem; font-family: var(--mono, monospace); }
+.jplay-datasets { align-self: flex-start; }
+/* the validate engine's JSON ↔ form toggle + the generated-form container */
+.jplay-dataview { align-self: flex-start; }
+.jplay-form { min-width: 0; }
+
+/* ——— option selects (josl dialect, csv strict/repair) ——— */
+.jplay-options { display: flex; flex-wrap: wrap; gap: var(--space-2, 0.5rem); }
+.jplay-options:empty { display: none; }
+.jplay-option { display: flex; flex-direction: column; gap: 2px; min-width: 0; }
+.jplay-option select { min-width: 0; max-width: 100%; }
+
+/* ——— the stage ——— */
+.jplay-stage-head { font-family: var(--mono, monospace); font-size: 0.75rem; padding-bottom: var(--space-2, 0.5rem); }
+.jplay-result { flex: 1; min-height: 0; overflow: auto; overscroll-behavior: contain; }
+/* a rendered visual result (markdown HTML, mermaid/charts SVG) */
+.jplay-view { min-width: 0; }
+.jplay-view svg { max-width: 100%; height: auto; }
+.jplay-timing { font-size: 0.75rem; margin: 0 0 var(--space-2, 0.5rem); }
+.jplay-hint { padding: var(--space-3, 0.75rem); }
+
+/* ——— multi-panel results: a tab strip (host .seg/.seg-btn) + panel bodies ——— */
+.jplay-tabs { align-self: flex-start; flex-wrap: wrap; margin-bottom: var(--space-2, 0.5rem); }
+/* a `note` panel — a callout, tone-coloured, repair lines on their own line */
+.jplay-note {
+  margin: 0; padding: var(--space-2, 0.5rem) var(--space-3, 0.75rem);
+  border-left: 3px solid var(--border, #e2e8f0); border-radius: var(--radius-sm, 8px);
+  background: var(--surface, #f8fafc); font-size: 0.85rem; white-space: pre-line;
+}
+.jplay-note.ok { border-left-color: var(--ok, #16a34a); background: var(--ok-soft, #f0fdf4); }
+.jplay-note.warn { border-left-color: var(--warn, #d97706); background: var(--warn-soft, #fffbeb); }
+.jplay-note.info { border-left-color: var(--accent, #2563eb); background: var(--accent-soft, #eff6ff); }
+/* a `table` panel — a scrollable bordered grid with a sticky header */
+.jplay-table-wrap { overflow-x: auto; }
+.jplay-table { border-collapse: collapse; font-size: 0.8rem; font-family: var(--mono, monospace); }
+.jplay-table th, .jplay-table td {
+  border: 1px solid var(--border, #e2e8f0); padding: 2px var(--space-2, 0.5rem);
+  text-align: left; white-space: nowrap;
+}
+.jplay-table th { position: sticky; top: 0; background: var(--surface, #f8fafc); color: var(--fg, #0f172a); }
+
+/* ——— the drill-deeper depth toggle: calm by default, deep on demand ———
+ * Desktop: the simple answer stays visible and the deep panels open BENEATH
+ * it as an additional tab row — the learner sees the answer and the
+ * machinery side by side. Mobile swaps panes instead (see the breakpoint). */
+.jplay-deep { margin-top: var(--space-3, 0.75rem); border-top: 1px dashed var(--border, #e2e8f0); padding-top: var(--space-2, 0.5rem); }
+.jplay-deep-toggle {
+  border: none; background: transparent; cursor: pointer; padding: var(--space-1, 0.25rem) 0;
+  color: var(--accent, #2563eb); font-size: 0.8rem; font-family: var(--mono, monospace);
+}
+.jplay-deep-toggle:hover { text-decoration: underline; }
+.jplay-deep-body { display: flex; flex-direction: column; gap: var(--space-2, 0.5rem); margin-top: var(--space-1, 0.25rem); }
+.jplay-deep-tabs { align-self: flex-start; flex-wrap: wrap; }
+/* the ← back affordance exists for the mobile full-pane swap only */
+.jplay-deep-back { display: none; }
+/* a `cards` panel — a row of stat cards (matches, timings, identity) */
+.jplay-cards { display: flex; flex-wrap: wrap; gap: var(--space-2, 0.5rem); }
+.jplay-card {
+  display: flex; flex-direction: column; gap: 2px; min-width: 7rem;
+  border: 1px solid var(--border, #e2e8f0); border-radius: var(--radius-sm, 6px);
+  padding: var(--space-2, 0.5rem) var(--space-3, 0.75rem); background: var(--surface, #f8fafc);
+}
+.jplay-card-title { font-size: 0.7rem; text-transform: uppercase; letter-spacing: 0.05em; }
+.jplay-card-value { color: var(--fg, #0f172a); font-size: 1.1rem; }
+.jplay-card-note { font-size: 0.7rem; }
+
+@media (max-width: 1024px) {
+  /* ONE pane at a time behind the segmented switcher — a phone screen
+     never stacks rail + editors + result into a tall scroll */
+  .jplay {
+    grid-template-columns: minmax(0, 1fr);
+    grid-template-areas: "bar" "switch" "rail" "editors" "stage";
+    grid-template-rows: auto;
+  }
+  .jplay-mobilebar { display: flex; grid-area: switch; align-self: start; }
+  .jplay-mobilebar .seg-btn { flex: 1; }
+  .jplay[data-pane='examples'] .jplay-editors,
+  .jplay[data-pane='examples'] .jplay-stage,
+  .jplay[data-pane='editor'] .jplay-rail,
+  .jplay[data-pane='editor'] .jplay-stage,
+  .jplay[data-pane='result'] .jplay-rail,
+  .jplay[data-pane='result'] .jplay-editors { display: none; }
+  /* no thin drag handle on touch — the switcher owns the pane choice */
+  .jplay-split { display: none; }
+  /* the keyboard seam: the editor pane reserves the published inset as
+     scroll room, so the caret clears the on-screen keyboard */
+  .jplay-editors { padding-bottom: var(--kb-inset, 0px); }
+  /* touch targets: rows, tabs, segments and bar buttons are finger-sized */
+  .jplay-ex, .jplay .seg-btn, .jplay-bar .btn { min-height: 44px; }
+  .jplay-ex { display: flex; align-items: center; }
+  /* the drill-down is a full-pane SWAP on a phone: there is no room to
+   * stack the machinery under the answer (and never under the keyboard),
+   * so the open deep view replaces the simple result, one deep panel at a
+   * time, with a ← back to the answer */
+  .jplay-result.deep-on .jplay-simple { display: none; }
+  .jplay-result.deep-on .jplay-deep { margin-top: 0; border-top: none; padding-top: 0; }
+  .jplay-result.deep-on .jplay-deep-toggle { display: none; }
+  .jplay-deep-back {
+    display: inline-flex; align-items: center; align-self: flex-start;
+    border: none; background: transparent; cursor: pointer;
+    color: var(--accent, #2563eb); font-size: 0.85rem; padding: 0;
+  }
+  /* touch targets: the deep affordances are finger-sized on a phone */
+  .jplay-deep-toggle, .jplay-deep-back, .jplay-deep-tabs .seg-btn { min-height: 44px; }
+}