@quario/editor 0.1.0

package/lib/history.js

@@ -0,0 +1,57 @@
+/**
+ * The undo stack: a capped list of whole-document snapshots, each
+ * `{ schema, selection }`. Snapshots make undo correct by construction — no
+ * op vocabulary, no path transforms, no inverse functions — and a
+ * structuredClone of a few-KB schema is free beside the recompile every edit
+ * already pays (docs/adr/0031-undo-is-a-snapshot-stack.md).
+ *
+ * One entry per commit, and a commit is the end of a gesture. Entry zero is
+ * the seeded document, even when invalid — committed-but-invalid is
+ * legitimate and undoable; only per-character states stay out.
+ */
+
+let CAP = 100;
+
+/** @type {(schema: any, selection: string | null) => { schema: any, selection: string | null }} */
+let entry = (schema, selection) => ({ schema: structuredClone(schema), selection });
+
+/**
+ * @param {any} schema The seed document — history entry zero.
+ * @param {string | null} [selection]
+ */
+export function history(schema, selection = null) {
+  let entries = [entry(schema, selection)];
+  let at = 0;
+  return {
+    /** The current entry's schema — what undo/redo restore into the editor. */
+    get current() {
+      return entries[at];
+    },
+    get canUndo() {
+      return at > 0;
+    },
+    get canRedo() {
+      return at < entries.length - 1;
+    },
+    /** One commit per gesture: truncates redo, caps by dropping oldest. */
+    /** @type {(schema: any, selection: string | null) => void} */
+    commit(schema, selection) {
+      entries.length = at + 1;
+      entries.push(entry(schema, selection));
+      if (entries.length > CAP) entries.shift();
+      at = entries.length - 1;
+    },
+    /** @type {() => { schema: any, selection: string | null } | null} */
+    undo() {
+      if (at === 0) return null;
+      at -= 1;
+      return entries[at];
+    },
+    /** @type {() => { schema: any, selection: string | null } | null} */
+    redo() {
+      if (at === entries.length - 1) return null;
+      at += 1;
+      return entries[at];
+    },
+  };
+}

package/lib/index.d.ts

@@ -0,0 +1,119 @@
+import type { LitElement } from "lit";
+import type { Problem, Quario, ReportSchema, Target } from "quario";
+
+/**
+ * Sheet geometry, in PostScript points — the same vocabulary the viewer's
+ * `page` takes (the pdf target's page sizes), purely visual: sheet width and
+ * padding, so preview and export agree.
+ */
+export interface EditorPage {
+  /** Named size or `[width, height]` in points. Default `'A4'`. */
+  size?: "A4" | "letter" | [number, number];
+  /** Margin on all four sides, in points. Default `54` (0.75 in). */
+  margin?: number;
+}
+
+/** The `change` event's payload: the committed document, with its problems. */
+export interface EditorChangeDetail {
+  /**
+   * The edited document, deep-frozen — the host cannot corrupt the editor's
+   * state by mutating it, and assigning this exact object back to `schema`
+   * is a no-op, so a naive persist-and-restore loop does not wipe the
+   * author's history.
+   */
+  schema: ReportSchema;
+  /**
+   * The structured problem list of that document, from the engine's
+   * `plan()` — empty when it compiles. Save buttons disable on it without
+   * re-running the engine.
+   */
+  problems: readonly Problem[];
+}
+
+/** Which failure an `error` event names. */
+export type EditorErrorKind = "mount-render" | "update-render" | "target";
+
+/** The `error` event's payload. */
+export interface EditorErrorDetail {
+  /** The caught value, exactly as thrown. */
+  error: unknown;
+  kind: EditorErrorKind;
+}
+
+/**
+ * The embeddable banded document designer, `<quario-editor>`. Assign
+ * `schema` (the starter document), `instance` (a quario instance — its
+ * `plan()` is the editor's loop, and the licence rides on it exactly as it
+ * does for the viewer), `target` (the html target, made with
+ * `html({ paths: true })` so rendered output maps back to the schema), and
+ * `data` (the sample the preview renders on); listen for `change` and
+ * `error`. Importing this module defines nothing — import
+ * `@quario/editor/register` for the one-line define, or call
+ * `customElements.define` with a tag of your own.
+ *
+ * The editor is uncontrolled: `schema` seeds it and the editor owns the
+ * document thereafter. Only a **new** `schema` object identity resets the
+ * document, history and selection; assigning back the object the last
+ * `change` delivered is a no-op. A new `instance`, `target`, `functions`,
+ * `data` or `page` recompiles and re-renders while leaving the author's
+ * work — document, history, selection — untouched. `colorScheme` repaints
+ * chrome only; the sheet stays white regardless.
+ *
+ * Host mistakes (a wrong target, a malformed page) throw `TypeError`s naming
+ * the property, delivered through the `error` event and the error panel.
+ * Removal is not destruction: the document and history persist, and
+ * reconnecting re-renders from them.
+ */
+export class QuarioEditor extends LitElement {
+  /** The starter document. A new object identity loads and resets. */
+  schema: ReportSchema | undefined;
+  /** The host's configured quario instance; `plan()` drives the edit loop. */
+  instance: Quario | undefined;
+  /** The html target, from `html({ paths: true })`. Nothing else renders a
+   * fragment the editor can map to the schema. */
+  target: Target<"html", Promise<string>> | undefined;
+  /** Functions callable from the document's expressions. */
+  functions: Record<string, (...args: never[]) => unknown> | undefined;
+  /** The sample data the preview renders on. */
+  data: unknown;
+  /** Sheet geometry — the same values a host passes to `pdf({ page })`. */
+  page: EditorPage | undefined;
+  /** Paints the chrome only. Unset is `"light"`; `"auto"` follows the OS. */
+  colorScheme: "light" | "dark" | "auto" | undefined;
+
+  /**
+   * Settles when the newest render settles: `true` when a fragment reached
+   * the sheet, `false` when it failed or there was nothing to render. Never
+   * rejects.
+   */
+  get renderComplete(): Promise<boolean>;
+
+  addEventListener<K extends keyof QuarioEditorEventMap>(
+    type: K,
+    listener: (this: QuarioEditor, ev: QuarioEditorEventMap[K]) => void,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(
+    type: string,
+    listener: EventListenerOrEventListenerObject,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  removeEventListener<K extends keyof QuarioEditorEventMap>(
+    type: K,
+    listener: (this: QuarioEditor, ev: QuarioEditorEventMap[K]) => void,
+    options?: boolean | EventListenerOptions,
+  ): void;
+  removeEventListener(
+    type: string,
+    listener: EventListenerOrEventListenerObject,
+    options?: boolean | EventListenerOptions,
+  ): void;
+}
+
+export interface QuarioEditorEventMap {
+  change: CustomEvent<EditorChangeDetail>;
+  error: CustomEvent<EditorErrorDetail>;
+}
+
+/** The tag `@quario/editor/register` defines the element under. */
+export const TAG: "quario-editor";