@jxsuite/studio 1.0.0 → 1.1.0

package/src/tabs/tab.ts

@@ -4,14 +4,16 @@ import { formatByName, formatForPath } from "../format/format-host";
 import { normalizeArrayChildren } from "../state";
 import type {
   DocumentStackEntry,
+  FormulaEditDef,
   FunctionEditDef,
   GitBranchesResult,
   GitDiffState,
   GitStatusResult,
   InlineEditDef,
+  JsonValue,
 } from "../types";
 import type { JxMutableNode } from "@jxsuite/schema/types";
-import type { JxDocOp } from "./patch-ops";
+import type { JxDocOp, JxFmOp } from "./patch-ops";
 
 export interface TabUi {
   rightTab: string;
@@ -20,12 +22,26 @@ export interface TabUi {
   preview: boolean;
   /** Show elements inherited from the page's layout (pages with an effective layout only). */
   showLayout: boolean;
+  /** Above-canvas frontmatter Properties accordion expanded (content-collection docs, edit mode). */
+  frontmatterOpen: boolean;
   /** Chosen literal values for dynamic route params (e.g. { sku: "mini-trencher" }). */
   previewParams: Record<string, string>;
+  /**
+   * Chosen test values for a component doc's props (state entries), seeded into the canvas render
+   * so a non-instantiated component previews with real data (M6) — the previewParams mirror.
+   */
+  previewProps: Record<string, JsonValue> | null;
   zoom: number;
+  /**
+   * Edit-mode content zoom — browser-page-zoom semantics (content reflows at the zoomed effective
+   * width while the canvas footprint stays fixed), unlike `zoom` which pan/zooms the whole canvas.
+   */
+  editZoom: number;
   activeMedia: string | null;
   activeSelector: string | null;
   editingFunction: FunctionEditDef | null;
+  /** Full-screen formula workspace target ($expression editing); editingFunction wins if both set. */
+  editingFormula: FormulaEditDef | null;
   featureToggles: Record<string, boolean>;
   styleSections: Record<string, boolean>;
   inspectorSections: Record<string, boolean>;
@@ -46,6 +62,18 @@ export interface TabUi {
   pendingInlineEdit: InlineEditDef | null;
 }
 
+/**
+ * A live (iframe-evaluated) expression preview retained per editing target (M6). Stored on
+ * `session.canvas` beside `scope` — plain wire data (path-key → display-string pairs), rebuilt into
+ * an ExpressionPreview by services/live-preview.ts on read.
+ */
+export interface StoredLivePreview {
+  /** Serialized expression + context the values were computed for (staleness check). */
+  key: string;
+  values: [string, string][];
+  error: string | null;
+}
+
 interface HistorySnapshot {
   /** Full document at this state (checkpoint), or null when the ops describe the transition. */
   document: Record<string, unknown> | null;
@@ -57,6 +85,8 @@ interface HistorySnapshot {
   forwardOps?: JxDocOp[] | null;
   /** Replayable ops transforming this state back into the previous one. */
   inverseOps?: JxDocOp[] | null;
+  /** Frontmatter key changes in this transaction (before/after values, replayed both ways). */
+  fmOps?: JxFmOp[] | null;
 }
 
 export interface Tab {
@@ -89,6 +119,9 @@ export interface Tab {
       // The bridge as a `dataScope` message and read by the data-explorer panel. Plain data now —
       // The old live `EffectScope` (with `.stop()`) moved into the iframe realm with buildScope.
       scope: Record<string, unknown> | null;
+      // Latest live (iframe-evaluated) expression previews keyed by editing-target id, stored
+      // Beside `scope` the same way (services/live-preview.ts owns reads/writes).
+      livePreviews: Record<string, StoredLivePreview> | null;
       error: string | null;
       pendingInlineEdit: InlineEditDef | null;
     };
@@ -109,8 +142,11 @@ function createDefaultUi(canvasMode: string, preview = false) {
     activeMedia: null,
     activeSelector: null,
     canvasMode,
+    editZoom: 1,
+    editingFormula: null,
     editingFunction: null,
     featureToggles: {},
+    frontmatterOpen: true,
     gitBranches: null,
     gitCommitMessage: "",
     gitDiffState: null,
@@ -121,6 +157,7 @@ function createDefaultUi(canvasMode: string, preview = false) {
     pendingInlineEdit: null,
     preview,
     previewParams: {},
+    previewProps: null,
     rightTab: "properties",
     settingsTab: "stylebook",
     showLayout: true,
@@ -204,6 +241,7 @@ export function createTab({
     session: reactive({
       canvas: {
         error: null,
+        livePreviews: null,
         pendingInlineEdit: null,
         scope: null,
         status: "idle",

package/src/tabs/transact.ts

@@ -8,16 +8,23 @@ import {
   endRecording,
   getPatchConsumer,
   recordDocOp,
+  recordFmOp,
   recordPatch,
 } from "./patch-ops";
 
-import type { JxDocOp, JxDocOpPair, TransactionRecord } from "./patch-ops";
+import type { JxDocOp, JxDocOpPair, JxFmOp, TransactionRecord } from "./patch-ops";
 
 import type { Tab } from "../tabs/tab";
 import type { JxPath } from "../state";
 
 import type { JsonValue } from "../types";
-import type { JxEventBinding, JxMutableNode, JxStateObject, JxStyle } from "@jxsuite/schema/types";
+import type {
+  JxAttributeValue,
+  JxEventBinding,
+  JxMutableNode,
+  JxStateObject,
+  JxStyle,
+} from "@jxsuite/schema/types";
 import { ensureNestedStyle, getNestedStyle, isEventBinding } from "@jxsuite/schema/guards";
 
 const HISTORY_LIMIT = 100;
@@ -205,10 +212,14 @@ function pushHistoryEntry(
   selectionBefore: JxPath | null,
 ) {
   const truncated = tab.history.snapshots.slice(0, tab.history.index + 1);
-  const useOps = patchHistoryEnabled() && record.invertible && record.docOps.length > 0;
+  const useOps =
+    patchHistoryEnabled() &&
+    record.invertible &&
+    (record.docOps.length > 0 || record.fmOps.length > 0);
   const needCheckpoint = !useOps || truncated.length % CHECKPOINT_INTERVAL === 0;
   truncated.push({
     document: needCheckpoint ? jsonClone(raw) : null,
+    fmOps: useOps && record.fmOps.length > 0 ? record.fmOps : null,
     forwardOps: useOps ? record.docOps.map((p) => p.forward) : null,
     inverseOps: useOps ? record.docOps.map((p) => p.inverse) : null,
     selection: tab.session.selection ? [...tab.session.selection] : null,
@@ -471,14 +482,23 @@ export function undo(tab: Tab) {
   }
   const entry = tab.history.snapshots[tab.history.index]!;
   const inverseOps = patchHistoryEnabled() ? entry.inverseOps : null;
-  if (inverseOps && inverseOps.length > 0) {
+  const fmOps = patchHistoryEnabled() ? entry.fmOps : null;
+  if ((inverseOps && inverseOps.length > 0) || (fmOps && fmOps.length > 0)) {
     // Surgical path: apply inverse ops through the normal transaction pipeline (the canvas
     // Patches in place when it can), in reverse recording order.
     transactDoc(
       tab,
       (t) => {
-        for (let i = inverseOps.length - 1; i >= 0; i--) {
-          applyDocOp(t, toRaw(inverseOps[i]) as JxDocOp);
+        if (inverseOps) {
+          for (let i = inverseOps.length - 1; i >= 0; i--) {
+            applyDocOp(t, toRaw(inverseOps[i]) as JxDocOp);
+          }
+        }
+        if (fmOps) {
+          for (let i = fmOps.length - 1; i >= 0; i--) {
+            const op = toRaw(fmOps[i]) as JxFmOp;
+            applyFmState(t, op.field, op.before);
+          }
         }
       },
       { origin: "history", skipHistory: true },
@@ -505,12 +525,21 @@ export function redo(tab: Tab) {
   }
   const entry = tab.history.snapshots[tab.history.index + 1]!;
   const forwardOps = patchHistoryEnabled() ? entry.forwardOps : null;
-  if (forwardOps && forwardOps.length > 0) {
+  const fmOps = patchHistoryEnabled() ? entry.fmOps : null;
+  if ((forwardOps && forwardOps.length > 0) || (fmOps && fmOps.length > 0)) {
     transactDoc(
       tab,
       (t) => {
-        for (const op of forwardOps) {
-          applyDocOp(t, toRaw(op) as JxDocOp);
+        if (forwardOps) {
+          for (const op of forwardOps) {
+            applyDocOp(t, toRaw(op) as JxDocOp);
+          }
+        }
+        if (fmOps) {
+          for (const op of fmOps) {
+            const raw = toRaw(op) as JxFmOp;
+            applyFmState(t, raw.field, raw.after);
+          }
         }
       },
       { origin: "history", skipHistory: true },
@@ -746,13 +775,13 @@ export function mutateUpdateStyle(tab: Tab, path: JxPath, prop: string, value: s
  * @param {Tab} tab
  * @param {JxPath} path
  * @param {string} attr
- * @param {string | undefined} value
+ * @param {JxAttributeValue | undefined} value — a literal, `$ref` binding, or `${}` template.
  */
 export function mutateUpdateAttribute(
   tab: Tab,
   path: JxPath,
   attr: string,
-  value?: string | undefined,
+  value?: JxAttributeValue | undefined,
 ) {
   const node = getNodeAtPath(tab.doc.document, path);
   const attrsBefore = cloneValue(node.attributes);
@@ -1196,10 +1225,28 @@ export function mutateRenameSwitchCase(tab: Tab, path: JxPath, oldName: string,
  * @param {JsonValue} value
  */
 export function mutateUpdateFrontmatter(tab: Tab, field: string, value?: JsonValue) {
-  if (value === undefined || value === null || value === "") {
+  const fm = tab.doc.content.frontmatter;
+  const before = Object.hasOwn(fm, field) ? cloneValue(fm[field]) : undefined;
+  const deletes = value === undefined || value === null || value === "";
+  if (deletes) {
+    delete fm[field];
+  } else {
+    fm[field] = value;
+  }
+  const after = deletes ? undefined : cloneValue(value);
+  recordFmOp({ after, before, field });
+  tab.doc.dirty = true;
+}
+
+/**
+ * Restore a frontmatter key to a recorded history state: `undefined` means the key was absent.
+ * Unlike `mutateUpdateFrontmatter`, values like `""`/`false`/`null` are written verbatim (source
+ * round-trips can put them there) and no fm op is recorded — history replay must not re-record.
+ */
+function applyFmState(tab: Tab, field: string, value: unknown) {
+  if (value === undefined) {
     delete tab.doc.content.frontmatter[field];
   } else {
     tab.doc.content.frontmatter[field] = value;
   }
-  tab.doc.dirty = true;
 }

package/src/types.ts

@@ -427,6 +427,18 @@ export interface FunctionEditDef {
   parameters?: string[];
 }
 
+/**
+ * Identifies which document position's `$expression` the full-screen formula workspace is editing:
+ * a state entry (`type: "def"` + defName) or an element event binding (`type: "event"` + path +
+ * eventKey). Mirrors FunctionEditDef, the Monaco function editor's target shape.
+ */
+export interface FormulaEditDef {
+  type: "def" | "event";
+  defName?: string;
+  path?: JxPath;
+  eventKey?: string;
+}
+
 export interface GitDiffState {
   filePath: string;
   originalContent: string;

package/src/ui/dynamic-slot.ts

@@ -0,0 +1,272 @@
+/// <reference lib="dom" />
+/**
+ * Dynamic-slot — the shared "make this dynamic" control for any bindable document position.
+ *
+ * Renders the panel-provided static widget plus a label-side mode button that cycles the value up
+ * the Rule of Least Power ladder (spec §2.2): literal → $ref pointer → ${} template → $expression.
+ * Capability-driven: each slot offers only the modes its schema position allows, so panels stay
+ * decoupled from which rungs are blessed where. Each mode's last value is remembered per field for
+ * the session, so cycling back to an earlier mode restores what the user had there.
+ */
+
+import { html, nothing } from "lit-html";
+import { live } from "lit-html/directives/live.js";
+import { isRef, isTemplateString } from "@jxsuite/schema/guards";
+import { cloneValue } from "../tabs/doc-op-apply";
+import { activeTab } from "../workspace/workspace";
+import { renderExpressionEditor } from "./expression-editor";
+
+import type { TemplateResult } from "lit-html";
+import type { EditorPreview } from "./expression-editor";
+import type { JxStateDefinition } from "@jxsuite/schema/types";
+import type { JsonValue } from "../types";
+
+export type SlotMode = "literal" | "ref" | "template" | "expression";
+
+const MODE_LABELS: Record<SlotMode, string> = {
+  expression: "fx",
+  literal: "abc",
+  ref: "$ref",
+  template: "${}",
+};
+
+const MODE_NOUNS: Record<SlotMode, string> = {
+  expression: "expression",
+  literal: "static",
+  ref: "signal binding",
+  template: "template literal",
+};
+
+/*
+ * Session memory of each field's last value per mode, so cycling modes round-trips user input.
+ * Keyed `${tabId}|${fieldKey}|${mode}`; the mode key is derived from the value at stash time, so a
+ * restore always lands a value whose slotMode() matches the target mode. `undefined` is a
+ * legitimate stash (cleared literal), hence Map.has() discrimination on recall.
+ */
+const slotModeMemory = new Map<string, JsonValue | undefined>();
+
+/** Test hook: drop all remembered per-mode field values. */
+export function resetSlotModeMemory(): void {
+  slotModeMemory.clear();
+}
+
+function memoryKey(fieldKey: string, mode: SlotMode): string {
+  return `${activeTab.value?.id ?? "-"}|${fieldKey}|${mode}`;
+}
+
+function hasRefOptions(opts: DynamicSlotOpts): boolean {
+  return opts.stateDefs.length > 0 || Boolean(opts.extraSignals?.length);
+}
+
+export interface SignalOption {
+  value: string;
+  label: string;
+}
+
+export interface DynamicSlotOpts {
+  /** Stable identity for per-mode value memory; must incorporate the node path. */
+  fieldKey: string;
+  /** Current raw document value at this position. */
+  value: unknown;
+  /** Write-through to the document; `undefined` clears the position. */
+  onChange: (v?: JsonValue) => void;
+  /** Panel-provided literal editor for this slot's type. */
+  staticWidget: unknown;
+  /** Modes this schema position allows, in ladder order. "literal" and "ref" are the floor. */
+  caps: SlotMode[];
+  /** State keys offered by the ref picker and expression editor. */
+  stateDefs: string[];
+  /** Full state defs map — lets expression mode resolve named-formula catalog entries. */
+  stateEntries?: Record<string, JxStateDefinition> | null;
+  /** Extra pointer options beyond #/state/* (e.g. $map/item within repeater templates). */
+  extraSignals?: SignalOption[] | null;
+  /** Offer event#/ refs inside expression mode (handler positions only). */
+  allowEventRef?: boolean;
+  /** Live values for expression mode badges (services/preview-eval.ts). */
+  preview?: EditorPreview | null;
+  /** Static value restored when de-escalating to literal mode. */
+  literalDefault?: JsonValue;
+}
+
+/** Detect which rung of the ladder a raw document value occupies. */
+export function slotMode(value: unknown): SlotMode {
+  if (isRef(value)) {
+    return "ref";
+  }
+  if (isTemplateString(value)) {
+    return "template";
+  }
+  if (value && typeof value === "object" && "$expression" in value) {
+    return "expression";
+  }
+  return "literal";
+}
+
+function defaultForSlotMode(mode: SlotMode, opts: DynamicSlotOpts): JsonValue | undefined {
+  switch (mode) {
+    case "ref": {
+      const [first] = opts.stateDefs;
+      return first ? { $ref: `#/state/${first}` } : { $ref: opts.extraSignals?.[0]?.value ?? "" };
+    }
+    case "template": {
+      const [first] = opts.stateDefs;
+      return first ? `\${state.${first}}` : "${}";
+    }
+    case "expression": {
+      return { $expression: { operator: "??", target: null, value: null } };
+    }
+    default: {
+      return opts.literalDefault;
+    }
+  }
+}
+
+function renderRefWidget(refVal: string, opts: DynamicSlotOpts) {
+  return html`
+    <sp-picker
+      size="s"
+      quiet
+      style="flex:1"
+      placeholder="— select signal —"
+      value=${refVal || nothing}
+      @change=${(e: Event) => {
+        const v = (e.target as HTMLInputElement).value;
+        if (v) {
+          opts.onChange({ $ref: v });
+        } else {
+          opts.onChange();
+        }
+      }}
+    >
+      ${opts.stateDefs.map(
+        (name) => html`<sp-menu-item value=${`#/state/${name}`}>${name}</sp-menu-item>`,
+      )}
+      ${opts.extraSignals?.length
+        ? html`
+            <sp-menu-divider></sp-menu-divider>
+            ${opts.extraSignals.map(
+              (sig) => html`<sp-menu-item value=${sig.value}>${sig.label}</sp-menu-item>`,
+            )}
+          `
+        : nothing}
+    </sp-picker>
+  `;
+}
+
+function renderTemplateWidget(value: unknown, opts: DynamicSlotOpts) {
+  return html`
+    <sp-textfield
+      size="s"
+      style="flex:1;font-family:var(--spectrum-code-font-family, monospace)"
+      placeholder="\${state.…}"
+      .value=${live(String(value ?? ""))}
+      @change=${(e: Event) => opts.onChange((e.target as HTMLInputElement).value)}
+    ></sp-textfield>
+  `;
+}
+
+export interface DynamicSlotParts {
+  /** Label-side mode-cycle button. */
+  modeButton: TemplateResult;
+  /** Active-mode widget, sized to fill the row's widget column. */
+  widget: TemplateResult;
+}
+
+/**
+ * The label-side field-mode button. Shows the current mode's glyph — quiet/gray while static and
+ * accent-tinted once the value is dynamic — and each click cycles to the next capped mode, stashing
+ * the outgoing mode's value and restoring the incoming mode's remembered one.
+ */
+function renderModeButton(mode: SlotMode, caps: SlotMode[], opts: DynamicSlotOpts): TemplateResult {
+  const color =
+    mode !== "literal"
+      ? "color:var(--spectrum-accent-content-color-default, #5c9dff)"
+      : "color:var(--spectrum-gray-600, #808080)";
+  // A ref rung with nothing to point at is a dead end — drop it rather than trap the cycle there.
+  const cycle = caps.filter((m) => m !== "ref" || hasRefOptions(opts));
+  if (cycle.length < 2) {
+    const hint = `Field mode: ${MODE_NOUNS[mode]} (no other modes available)`;
+    return html`
+      <sp-action-button
+        size="xs"
+        quiet
+        disabled
+        class="dynamic-slot-mode"
+        style=${color}
+        title=${hint}
+        aria-label=${hint}
+        >${MODE_LABELS[mode]}</sp-action-button
+      >
+    `;
+  }
+  // An uncapped current mode indexes to -1, so its next stop is cycle[0] (literal).
+  const next = cycle[(cycle.indexOf(mode) + 1) % cycle.length]!;
+  const hint = `Field mode: ${MODE_NOUNS[mode]} — click for ${MODE_NOUNS[next]}`;
+  return html`
+    <sp-action-button
+      size="xs"
+      quiet
+      class="dynamic-slot-mode"
+      style=${color}
+      title=${hint}
+      aria-label=${hint}
+      @click=${() => {
+        slotModeMemory.set(
+          memoryKey(opts.fieldKey, mode),
+          cloneValue(opts.value as JsonValue | undefined),
+        );
+        // Leaving ref seeds an empty literal stash with the signal's declared default.
+        // Unbind-restores-default thus survives multi-hop cycles (ref → template → literal).
+        if (mode === "ref" && opts.literalDefault !== undefined) {
+          const litKey = memoryKey(opts.fieldKey, "literal");
+          if (!slotModeMemory.has(litKey)) {
+            slotModeMemory.set(litKey, cloneValue(opts.literalDefault));
+          }
+        }
+        const key = memoryKey(opts.fieldKey, next);
+        opts.onChange(
+          slotModeMemory.has(key)
+            ? cloneValue(slotModeMemory.get(key))
+            : defaultForSlotMode(next, opts),
+        );
+      }}
+      >${MODE_LABELS[mode]}</sp-action-button
+    >
+  `;
+}
+
+/**
+ * Render a bindable slot as two parts the panel places independently: the active mode's widget for
+ * the row's value column, and the mode-cycle button for the label side.
+ */
+export function renderDynamicSlot(opts: DynamicSlotOpts): DynamicSlotParts {
+  const caps: SlotMode[] = opts.caps.length > 0 ? opts.caps : ["literal", "ref"];
+  const mode = slotMode(opts.value);
+
+  const widget =
+    mode === "ref"
+      ? renderRefWidget(isRef(opts.value) ? opts.value.$ref : "", opts)
+      : mode === "template"
+        ? renderTemplateWidget(opts.value, opts)
+        : mode === "expression"
+          ? renderExpressionEditor(
+              (opts.value as { $expression?: unknown }).$expression,
+              (node) => opts.onChange({ $expression: node } as JsonValue),
+              {
+                allowEventRef: opts.allowEventRef ?? false,
+                preview: opts.preview ?? null,
+                stateDefs: opts.stateDefs,
+                stateEntries: opts.stateEntries ?? null,
+              },
+            )
+          : opts.staticWidget;
+
+  return {
+    modeButton: renderModeButton(mode, caps, opts),
+    widget: html`
+      <div class="dynamic-slot" style="display:flex;flex:1;min-width:0">
+        <div style="flex:1;min-width:0">${widget}</div>
+      </div>
+    `,
+  };
+}