@quario/editor 0.1.0

package/lib/rail.js

@@ -0,0 +1,506 @@
+/**
+ * The right rail's three sections — Properties, Groups, Problems — as Lit
+ * templates over the document model. Two flat groups per node, Content and
+ * Style, no progressive disclosure: at most six own keys plus nine style
+ * names is not a surface that earns one. Only literal-or-expression fields
+ * get the fx toggle; a group's `by` and an image's `source` are bare text
+ * fields, because there is no literal form of them to offer.
+ *
+ * Commits are the element's: every control reports through `act.edit`, which
+ * is three verbs. `touch` moves the working document without taking a history
+ * entry, so the preview and the problem list answer to the keystroke.
+ * `settle` is a typed control's own gesture ending — blurred, Entered, or a
+ * picker released — which is what the `touch`es before it were building
+ * toward. `write` is a discrete gesture in one act: a checkbox, an alignment
+ * button, an fx toggle. The distinction between the last two is the whole
+ * reason this module has three verbs rather than two: an fx toggle carries
+ * the same `key` as the field beside it, so routing by key alone would let it
+ * swallow the typing it interrupted instead of letting that land first.
+ */
+import { html, nothing } from "lit";
+import { fieldKind, nodeKindAt, resolve } from "./document.js";
+
+/**
+ * The rail's whole seam to the element: how a control says what it did.
+ *
+ * @typedef {{
+ *   touch: (key: string, value: any) => void,
+ *   settle: (key: string, value: any) => void,
+ *   write: (key: string, value: any) => void,
+ * }} Edit
+ */
+
+/** The closed style vocabulary an item offers, in one fixed panel order. */
+let STYLES = [
+  "family",
+  "size",
+  "bold",
+  "italic",
+  "underline",
+  "strikethrough",
+  "color",
+  "background",
+  "align",
+];
+// The vocabulary that differs from the full set: an image has two style
+// declarations, and a group or the table itself has none.
+/** @type {Record<string, string[]>} */
+let STYLE_VOCABULARY = { image: ["align", "background"], group: [], table: [] };
+
+let FAMILIES = ["", "sans", "serif", "mono"];
+let ALIGNS = ["left", "center", "right"];
+let FLAGS = new Set(["bold", "italic", "underline", "strikethrough"]);
+
+/** @type {(value: any) => boolean} */
+let isExpr = (value) => typeof value === "string" && value.startsWith("=");
+
+/** What a plain text field writes: the string, as typed. */
+/** @type {(value: string) => any} */
+let asIs = (value) => value;
+
+/** Which of a node's keys a problem belongs to: "" for the node itself,
+ * `style.color` for one inside it, null for a problem elsewhere. */
+/** @type {(at: string, path: string) => string | null} */
+let subKey = (at, path) => {
+  if (at === path) return "";
+  return at.startsWith(path + ".") ? at.slice(path.length + 1) : null;
+};
+
+/**
+ * The problems that sit at or under one node, mapped to the sub-key they
+ * belong to, with the exact character span when the diagnostic carries one.
+ *
+ * @type {(problems: readonly any[], path: string) => Map<string, any>}
+ */
+let inlineProblems = (problems, path) => {
+  let out = new Map();
+  for (let problem of problems) {
+    let key = subKey(problem.path, path);
+    if (key !== null && !out.has(key)) out.set(key, problem);
+  }
+  return out;
+};
+
+/** Whether a diagnostic carries offsets at all. */
+/** @type {(d: any) => boolean} */
+let hasSpan = (d) => !!d && d.start != null && d.end != null;
+
+/** Whether those offsets land inside the source the panel is showing. */
+/** @type {(problem: any) => boolean} */
+let spanned = (problem) =>
+  hasSpan(problem.diagnostic) &&
+  problem.source != null &&
+  problem.diagnostic.end <= problem.source.length;
+
+/** The message without its located prefix: the field it sits under already
+ * names the node, so repeating the path there is noise. Built from the
+ * problem's own `path` and `source` — the engine kept both as data precisely
+ * so no consumer has to parse a wording format back apart. */
+/** @type {(problem: any) => string} */
+let trimmed = ({ path, source, message }) => {
+  let prefix = (source === undefined ? path : path + " [" + source + "]") + ": ";
+  return message.startsWith(prefix) ? message.slice(prefix.length) : message;
+};
+
+/** The message with its located span underlined, when the engine knows it. */
+/** @type {(problem: any) => unknown} */
+let said = (problem) => {
+  if (!spanned(problem)) return html`<p class="qe-inline-error">${problem.message}</p>`;
+  let { diagnostic: d, source: src } = problem;
+  let end = Math.max(d.end, d.start + 1);
+  return html`<p class="qe-inline-error">
+    ${trimmed(problem)}<br />
+    <code>${src.slice(0, d.start)}<u>${src.slice(d.start, end)}</u>${src.slice(end)}</code>
+  </p>`;
+};
+
+/** @type {(faults: Map<string, any>, key: string) => unknown} */
+let fault = (faults, key) => {
+  let problem = faults.get(key);
+  return problem ? said(problem) : nothing;
+};
+
+/** A literal-or-expression style flag (`bold`, `italic`, ...) edits as a
+ * checkbox; everything else is a text field. */
+/** @type {(kind: string, key: string) => boolean} */
+let asFlag = (kind, key) => kind === "dual" && FLAGS.has(key.replace(/^style\./, ""));
+
+// The closed sets a literal field offers, so an author picks rather than
+// spells. `visible`'s literal form is a boolean — SCHEMA.md makes any other
+// literal a definition error — which is why it is a checkbox until the fx
+// toggle turns it into an expression.
+/** @type {Record<string, string[]>} */
+let CHOICES = { fit: ["natural", "width"], break: ["page"], reset: ["page"] };
+/** The literal fields whose value is a number, never the string typed. */
+let COUNTED = new Set(["width", "take", "columns"]);
+
+/** A value already written as an expression edits as its source, whatever
+ * control its literal form would have had. */
+/** @type {(kind: string, key: string, ctx: any) => unknown} */
+let literalOrFlag = (kind, key, ctx) => {
+  if (key === "visible") return visibleControl(ctx);
+  return asFlag(kind, key) ? flagControl(ctx) : textControl(ctx);
+};
+
+/** @type {(ctx: any) => unknown} */
+let readonlyControl = ({ value }) => html`<input type="text" .value=${value ?? ""} disabled />`;
+
+// Four kinds decide every control (quario-yre.7): literal-only, always a
+// template, always an expression, and literal-or-expression. Only the fourth
+// can already hold an expression, and then it edits as its source.
+/** @type {Record<string, (key: string, value: any, ctx: any) => unknown>} */
+let CONTROLS = {
+  readonly: (_key, _value, ctx) => readonlyControl(ctx),
+  literal: (key, _value, ctx) => literalControl(key, ctx),
+  template: (_key, _value, ctx) => textControl(ctx),
+  expression: (_key, _value, ctx) => textControl(ctx),
+  dual: (key, value, ctx) => (isExpr(value) ? textControl(ctx) : literalOrFlag("dual", key, ctx)),
+};
+
+/** @type {(kind: string, key: string, value: any, ctx: any) => unknown} */
+let fieldControl = (kind, key, value, ctx) => CONTROLS[kind](key, value, ctx);
+
+/** The two handlers a typed control needs: `input` moves the working
+ * document, `change` ends the gesture. `read` is what the schema wants out of
+ * the DOM's string. */
+/** @type {(edit: Edit, key: string, read: (value: string) => any) => { live: any, commit: any }} */
+let handlers = (edit, key, read) => ({
+  live: (/** @type {any} */ event) => edit.touch(key, read(event.target.value)),
+  commit: (/** @type {any} */ event) => edit.settle(key, read(event.target.value)),
+});
+
+/** A count writes a number: `width: "30"` is a definition error, and the
+ * author never sees the difference between the two on screen. */
+/** @type {(value: string) => any} */
+let asCount = (value) => (value === "" ? "" : Number(value));
+
+/** A number field's intermediate states — a lone `-`, a half-typed `1e` —
+ * reach the DOM as an empty value. Live-writing that would clear the key, and
+ * the re-render would then erase what was typed, so a count moves the working
+ * document only once it is one. Clearing the field still commits on blur. */
+/** @type {(edit: Edit, key: string) => any} */
+let liveCount = (edit, key) => (/** @type {any} */ event) => {
+  if (event.target.value === "") return;
+  edit.touch(key, Number(event.target.value));
+};
+
+/** The counted control both `width`-style literals and `style.size` use: the
+ * ordinary pair read as a count, with only the live half replaced. */
+/** @type {(ctx: any, least: unknown) => unknown} */
+let countedControl = ({ edit, key, value }, least) => html`<input
+  type="number"
+  min=${least ?? nothing}
+  .value=${value ?? ""}
+  @input=${liveCount(edit, key)}
+  @change=${handlers(edit, key, asCount).commit}
+/>`;
+
+/** @type {(key: string, ctx: any) => unknown} */
+let literalControl = (key, ctx) => {
+  if (COUNTED.has(key)) return countedControl(ctx, undefined);
+  return CHOICES[key] ? choiceControl(CHOICES[key], ctx) : textControl(ctx);
+};
+
+/**
+ * One field. `kind` narrows the control; `dual` fields carry the fx toggle
+ * that swaps the control for its expression source.
+ */
+/** @type {(label: string, key: string, value: any, kind: string, faults: Map<string, any>, edit: Edit) => unknown} */
+let field = (label, key, value, kind, faults, edit) => {
+  let ctx = { key, value, edit, ...handlers(edit, key, asIs) };
+  let control = fieldControl(kind, key, value, ctx);
+  return html`<label class="qe-field">
+    <span>${label}</span>
+    <span class="qe-row">${control}${kind === "dual" ? fxButton(key, value, edit) : nothing}</span>
+    ${fault(faults, key)}
+  </label>`;
+};
+
+// The fx toggle: only a literal-or-expression field has a literal form to
+// swap back to, which is why a group's `by` and an image's `source` never
+// carry one.
+/** @type {(key: string, value: any, edit: Edit) => unknown} */
+let fxButton = (key, value, edit) => html`<button
+  class="qe-button"
+  title="Switch between a value and an expression"
+  aria-pressed=${isExpr(value) ? "true" : "false"}
+  @click=${() => edit.write(key, isExpr(value) ? "" : "=")}
+>
+  fx
+</button>`;
+
+/** @type {(ctx: any) => unknown} */
+let flagControl = ({ value, key, edit }) => html`<input
+  type="checkbox"
+  .checked=${!!value}
+  @change=${(/** @type {any} */ event) => edit.write(key, event.target.checked ? true : "")}
+/>`;
+
+// `visible` is the mirror image of a style flag: an absent key means visible,
+// so the box is checked by default and unchecking it writes the literal
+// `false` the schema wants — clearing the key instead would make the item
+// visible again, which is the one control that could turn it back on.
+/** @type {(ctx: any) => unknown} */
+let visibleControl = ({ value, key, edit }) => html`<input
+  type="checkbox"
+  .checked=${value !== false}
+  @change=${(/** @type {any} */ event) => edit.write(key, event.target.checked ? "" : false)}
+/>`;
+
+/** @type {(ctx: any) => unknown} */
+let textControl = ({ value, live, commit }) =>
+  html`<input type="text" .value=${value ?? ""} @input=${live} @change=${commit} />`;
+
+/** One of a closed set, plus the empty choice that clears the key. */
+/** @type {(options: string[], ctx: any) => unknown} */
+let choiceControl = (options, { value, commit }) => html`<select @change=${commit}>
+  ${["", ...options].map(
+    (option) =>
+      html`<option value=${option} ?selected=${(value ?? "") === option}>
+        ${option || "(none)"}
+      </option>`,
+  )}
+</select>`;
+
+/** @type {(ctx: any) => unknown} */
+let colorControl = ({ value, key, edit, live, commit }) => html`<span class="qe-row">
+  <input
+    type="color"
+    .value=${typeof value === "string" && value.startsWith("#") ? value : "#000000"}
+    @input=${live}
+    @change=${commit}
+  />
+  <button class="qe-button" title="Clear" @click=${() => edit.write(key, "")}>×</button>
+</span>`;
+
+// Real controls, one per style name — a colour picker, a bold toggle,
+// alignment buttons — so nothing is a value the author has to remember.
+// Anything unlisted falls back to a plain text field.
+/** @type {Record<string, (ctx: any) => unknown>} */
+let STYLE_CONTROLS = {
+  family: ({ value, commit }) => html`<select @change=${commit}>
+    ${FAMILIES.map(
+      (option) =>
+        html`<option value=${option} ?selected=${(value ?? "") === option}>
+          ${option || "(default)"}
+        </option>`,
+    )}
+  </select>`,
+  align: ({ value, key, edit }) => html`<span class="qe-row" role="group" aria-label="align">
+    ${ALIGNS.map(
+      (option) => html`<button
+        class="qe-button"
+        aria-pressed=${value === option ? "true" : "false"}
+        @click=${() => edit.write(key, value === option ? "" : option)}
+      >
+        ${option}
+      </button>`,
+    )}
+  </span>`,
+  size: (ctx) => countedControl(ctx, "1"),
+  color: colorControl,
+  background: colorControl,
+};
+
+/** @type {(ctx: any) => unknown} */
+let styleControl = (ctx) => {
+  if (FLAGS.has(ctx.name)) return flagControl(ctx);
+  return (STYLE_CONTROLS[ctx.name] ?? textControl)(ctx);
+};
+
+/** @type {(name: string, node: any, faults: Map<string, any>, edit: Edit) => unknown} */
+let styleField = (name, node, faults, edit) => {
+  let value = node?.style?.[name];
+  let key = "style." + name;
+  // An expression-valued style edits as its source, through the same field a
+  // `visible` expression gets.
+  if (isExpr(value)) return field(name, key, value, "dual", faults, edit);
+  let ctx = { name, key, value, edit, ...handlers(edit, key, asIs) };
+  return html`<label class="qe-field">
+    <span>${name}</span>
+    <span class="qe-row">${styleControl(ctx)}${fxButton(key, value, edit)}</span>
+    ${fault(faults, key)}
+  </label>`;
+};
+
+/** Content fields per node kind — each an entry of [label, key, kind]. */
+let CONTENT = /** @type {Record<string, [string, string][]>} */ ({
+  text: [
+    ["value", "value"],
+    ["visible", "visible"],
+  ],
+  image: [
+    ["source", "source"],
+    ["alt", "alt"],
+    ["fit", "fit"],
+    ["visible", "visible"],
+  ],
+  column: [
+    ["header", "header"],
+    ["value", "value"],
+    ["visible", "visible"],
+    ["width", "width"],
+  ],
+  total: [
+    ["value", "value"],
+    ["visible", "visible"],
+  ],
+  group: [
+    ["name", "name"],
+    ["by", "by"],
+    ["break", "break"],
+    ["reset", "reset"],
+    ["take", "take"],
+    ["columns", "columns"],
+  ],
+  table: [],
+});
+
+/** Every rail section is a titled block; the title is the only chrome. */
+/** @type {(title: string, body: unknown) => unknown} */
+let section = (title, body) => html`<div class="qe-section">
+  <h3>${title}</h3>
+  ${body}
+</div>`;
+
+/** A column's shorthand string header edits as its own template; the widened
+ * object form edits through `.value`. Widening is the element's write path. */
+/** @type {(header: any) => any} */
+let headerText = (header) => (typeof header === "string" ? header : header?.value);
+
+/** @type {(node: any, key: string) => any} */
+let readKey = (node, key) => (key === "header" ? headerText(node?.header) : node?.[key]);
+
+/** The style vocabulary a node kind actually has: an image shows its two
+ * declarations rather than nine controls with seven disabled. */
+/** @type {(kind: string) => string[]} */
+let stylesFor = (kind) => STYLE_VOCABULARY[kind] ?? STYLES;
+
+/** @type {(kind: string, node: any, faults: Map<string, any>, edit: Edit) => unknown} */
+let styleFields = (kind, node, faults, edit) => {
+  let names = stylesFor(kind);
+  if (!names.length) return nothing;
+  return html`<h3>Style</h3>
+    ${names.map((name) => styleField(name, node, faults, edit))}`;
+};
+
+/** The table verbs, on the table and on any column of it. */
+/** @type {(kind: string, act: any) => unknown} */
+let columnVerbs = (kind, act) => {
+  if (kind !== "column" && kind !== "table") return nothing;
+  return html`<div class="qe-row">
+    <button class="qe-button" @click=${act.insertColumn}>Add column</button>
+    ${
+      kind === "column"
+        ? html`<button class="qe-button" @click=${act.duplicateColumn}>Duplicate</button>
+          <button class="qe-button" @click=${act.removeColumn}>Remove</button>`
+        : nothing
+    }
+  </div>`;
+};
+
+/**
+ * The Properties section for the selected node, or its empty prompting form.
+ *
+ * @param {any} schema
+ * @param {string | null} selected
+ * @param {readonly any[]} problems
+ * @param {{ edit: Edit,
+ *   insertColumn: () => void, removeColumn: () => void, duplicateColumn: () => void }} act
+ */
+export let propertiesSection = (schema, selected, problems, act) => {
+  let kind = selected && nodeKindAt(schema, selected);
+  if (!selected || !kind)
+    return section("Properties", html`<p>Select something in the preview.</p>`);
+  let node = resolve(schema, selected);
+  let faults = inlineProblems(problems, selected);
+  return section(
+    "Properties",
+    html`<p><code class="qe-crumb">${selected}</code></p>
+      ${columnVerbs(kind, act)}
+      ${CONTENT[kind].map(([label, key]) =>
+        field(label, key, readKey(node, key), fieldKind(key), faults, act.edit),
+      )}
+      ${styleFields(kind, node, faults, act.edit)}`,
+  );
+};
+
+/** One toolbar button in a group's row. */
+/** @type {(title: string, glyph: string, click: () => void, opts?: any) => unknown} */
+let rowButton = (title, glyph, click, opts = {}) => html`<button
+  class="qe-button"
+  title=${title}
+  ?disabled=${!!opts.disabled}
+  aria-pressed=${opts.pressed ?? nothing}
+  @click=${click}
+>
+  ${glyph}
+</button>`;
+
+/** @type {Record<string, string>} */
+let GLYPH = { header: "H", footer: "F" };
+
+/** A group's header or footer band: one verb that adds it, one that removes
+ * it whole. There is no such thing as a hidden band, so the editor presents
+ * none — an off-then-on toggle would discard the band's contents. */
+/** @type {(group: any, i: number, which: "header" | "footer", act: any) => unknown} */
+let bandButton = (group, i, which, act) => {
+  let band = group?.[which];
+  let title = (band ? "Remove the " : "Add a ") + which + " band";
+  let pressed = band ? "true" : "false";
+  return rowButton(title, GLYPH[which], () => act.band(i, which, band == null), { pressed });
+};
+
+/** @type {(group: any, i: number, count: number, act: any) => unknown} */
+let groupRow = (group, i, count, act) => html`<div class="qe-group-row">
+  <button class="qe-button qe-name" @click=${() => act.select("groups[" + i + "]")}>
+    ${group?.name}
+  </button>
+  ${rowButton("Move up", "↑", () => act.move(i, i - 1), { disabled: i === 0 })}
+  ${rowButton("Move down", "↓", () => act.move(i, i + 2), { disabled: i === count - 1 })}
+  ${bandButton(group, i, "header", act)} ${bandButton(group, i, "footer", act)}
+  ${rowButton("Remove the group, keeping its items", "⇱", () => act.remove(i, "splice"))}
+  ${rowButton("Remove the group and its bands", "×", () => act.remove(i, "discard"))}
+</div>`;
+
+/**
+ * The Groups section: the docked list no single part of the page shows. A
+ * group spans its whole instance, so its controls cannot sit on any one part
+ * of the page — this is their one home.
+ *
+ * @param {any} schema
+ * @param {{ select: (path: string) => void, move: (at: number, to: number) => void,
+ *   remove: (at: number, mode: "discard" | "splice") => void,
+ *   band: (at: number, which: "header" | "footer", add: boolean) => void }} act
+ */
+export let groupsSection = (schema, act) => {
+  let groups = Array.isArray(schema?.groups) ? schema.groups : [];
+  return section(
+    "Groups",
+    html`${groups.length ? nothing : html`<p>No groups.</p>`}
+      ${groups.map((/** @type {any} */ group, /** @type {number} */ i) =>
+        groupRow(group, i, groups.length, act),
+      )}`,
+  );
+};
+
+/**
+ * The Problems section: every problem in the document; clicking one selects
+ * the node it belongs to.
+ *
+ * @param {readonly any[]} problems
+ * @param {{ select: (path: string) => void }} act
+ */
+export let problemsSection = (problems, act) =>
+  section(
+    "Problems",
+    html`${problems.length ? nothing : html`<p>None.</p>`}
+      ${problems.map(
+        (/** @type {any} */ problem) => html`<button
+          class="qe-problem"
+          @click=${() => act.select(problem.path)}
+        >
+          ${problem.message}
+        </button>`,
+      )}`,
+  );

package/lib/register.d.ts

@@ -0,0 +1,9 @@
+import { QuarioEditor } from "./index.js";
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "quario-editor": QuarioEditor;
+  }
+}
+
+export {};

package/lib/register.js

@@ -0,0 +1,10 @@
+/**
+ * The one-line define, as its own entry so the main module stays
+ * side-effect-free: importing `@quario/editor` gives you the class and
+ * defines nothing, importing `@quario/editor/register` gives the tag to
+ * hosts that want the platform default. A host that wants its own tag calls
+ * `customElements.define` itself (docs/adr/0005-the-surfaces-are-custom-elements.md).
+ */
+import { QuarioEditor, TAG } from "./index.js";
+
+customElements.define(TAG, QuarioEditor);