@mokly/mokly 0.8.0

package/dist/browser/component_controls.js

@@ -0,0 +1,424 @@
+// src/components/data.ts
+var DataBudget = class {
+  constructor(depthLimit = 64) {
+    this.depthLimit = depthLimit;
+  }
+  depthLimit;
+  nodes = 0;
+  visit(depth, at) {
+    if (depth > this.depthLimit || ++this.nodes > 1e4)
+      invalidData(at, "validation limit exceeded");
+  }
+};
+var ComponentValidationError = class extends Error {
+  constructor(path, detail) {
+    super(`[mokly/components] ${path}: ${detail}`);
+    this.path = path;
+    this.detail = detail;
+    this.name = "ComponentValidationError";
+  }
+  path;
+  detail;
+};
+function invalidData(at, message) {
+  throw new ComponentValidationError(at, message);
+}
+function record(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function plainKeys(value, at) {
+  if (!record(value) || Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null)
+    invalidData(at, "expected a plain object");
+  const keys = [];
+  for (const key2 of Reflect.ownKeys(value)) {
+    if (typeof key2 !== "string") invalidData(at, "symbol keys are unsupported");
+    if (["__proto__", "constructor", "prototype"].includes(key2))
+      invalidData(`${at}.${key2}`, "reserved property name");
+    const descriptor = Object.getOwnPropertyDescriptor(value, key2);
+    if (!descriptor.enumerable || !("value" in descriptor))
+      invalidData(
+        `${at}.${key2}`,
+        "only enumerable data properties are supported"
+      );
+    keys.push(key2);
+  }
+  return keys.sort();
+}
+function denseArray(value, at) {
+  if (!Array.isArray(value)) invalidData(at, "expected an array");
+  if (Reflect.ownKeys(value).length !== value.length + 1)
+    invalidData(at, "expected a dense array without extra properties");
+  for (let i = 0; i < value.length; i++) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, String(i));
+    if (!descriptor || !descriptor.enumerable || !("value" in descriptor))
+      invalidData(`${at}[${i}]`, "expected an array data element");
+  }
+}
+function assertPlainData(value, at = "$", allowUndefined = false, depthLimit = 64) {
+  const budget = new DataBudget(depthLimit);
+  const ancestors = /* @__PURE__ */ new Set();
+  function visit(item, location, depth, optional) {
+    budget.visit(depth, location);
+    if (item === void 0 && optional) return;
+    if (item === null || typeof item === "string" || typeof item === "boolean")
+      return;
+    if (typeof item === "number" && Number.isFinite(item)) return;
+    if (typeof item !== "object" || item === null)
+      invalidData(location, "unsupported data value");
+    if (ancestors.has(item))
+      invalidData(location, "cyclic data is unsupported");
+    ancestors.add(item);
+    if (Array.isArray(item)) {
+      denseArray(item, location);
+      item.forEach(
+        (child, i) => visit(child, `${location}[${i}]`, depth + 1, false)
+      );
+    } else {
+      for (const key2 of plainKeys(item, location))
+        visit(
+          item[key2],
+          `${location}.${key2}`,
+          depth + 1,
+          allowUndefined
+        );
+    }
+    ancestors.delete(item);
+  }
+  visit(value, at, 0, false);
+}
+
+// src/components/codec.ts
+function encodeProps(props) {
+  assertPlainData(props);
+  return Object.fromEntries(
+    Object.keys(props).sort().map((key2) => [key2, encodeValue(props[key2])])
+  );
+}
+function encodeValue(value) {
+  if (value === null) return ["null"];
+  if (typeof value === "number")
+    return ["number", Object.is(value, -0) ? "-0" : String(value)];
+  if (typeof value === "string") return ["string", value];
+  if (typeof value === "boolean") return ["boolean", value];
+  if (Array.isArray(value)) return ["array", value.map(encodeValue)];
+  const object = value;
+  return [
+    "object",
+    Object.keys(object).sort().map((key2) => [key2, encodeValue(object[key2])])
+  ];
+}
+function decodeProps(value) {
+  const budget = new DataBudget();
+  budget.visit(0, "$props");
+  return Object.fromEntries(
+    plainKeys(value, "$props").map((key2) => [
+      key2,
+      decode(
+        value[key2],
+        `$props.${key2}`,
+        budget,
+        1
+      )
+    ])
+  );
+}
+function decode(value, at, budget, depth) {
+  budget.visit(depth, at);
+  denseArray(value, at);
+  const [kind, payload] = value;
+  if (kind === "null" && value.length === 1) return null;
+  if (value.length !== 2) invalidData(at, "invalid wire tuple length");
+  if (kind === "string" && typeof payload === "string") return payload;
+  if (kind === "boolean" && typeof payload === "boolean") return payload;
+  if (kind === "number" && typeof payload === "string") {
+    const number = Number(payload);
+    if (Number.isFinite(number) && (Object.is(number, -0) ? "-0" : String(number)) === payload)
+      return number;
+    invalidData(at, "noncanonical number");
+  }
+  if (kind === "array") {
+    denseArray(payload, at);
+    return payload.map(
+      (item, i) => decode(item, `${at}[${i}]`, budget, depth + 1)
+    );
+  }
+  if (kind === "object") {
+    denseArray(payload, at);
+    const object = {};
+    let previous;
+    for (const pair of payload) {
+      denseArray(pair, at);
+      if (pair.length !== 2 || typeof pair[0] !== "string")
+        invalidData(at, "invalid object entry");
+      const key2 = pair[0];
+      if (previous !== void 0 && previous >= key2)
+        invalidData(at, "object keys must be unique and sorted");
+      plainKeys({ [key2]: null }, at);
+      object[key2] = decode(pair[1], `${at}.${key2}`, budget, depth + 1);
+      previous = key2;
+    }
+    return object;
+  }
+  return invalidData(at, "unknown or malformed wire value");
+}
+
+// src/client/component_controls.ts
+import { currentColorScheme, setColorScheme } from "./browse_state.js";
+import { controlFields } from "./control_fields.js";
+import {
+  requestComponentPreview,
+  componentPreviewExpired
+} from "./control_transport.js";
+import { controlSurface, controlsUnavailable } from "./control_surface.js";
+import { renderProps } from "./inspector_panels.js";
+import { applyVariant } from "./workspace_variants.js";
+var ComponentControls = class {
+  constructor(root, data, signal, changed) {
+    this.root = root;
+    this.data = data;
+    this.changed = changed;
+    this.ui = controlSurface(
+      root.ownerDocument,
+      () => {
+        this.reset();
+        this.buildFields();
+        this.changed();
+      },
+      () => this.edit(true)
+    );
+    signal.addEventListener(
+      "abort",
+      () => {
+        this.disposed = true;
+        this.cancel();
+      },
+      { once: true }
+    );
+    for (const frame of root.querySelectorAll(
+      "iframe[data-workspace-frame]"
+    ))
+      frame.addEventListener(
+        "load",
+        () => void this.verifyLoaded(frame, signal),
+        { signal }
+      );
+  }
+  root;
+  data;
+  changed;
+  ui;
+  fields;
+  variant;
+  contexts = [];
+  contextKey = "";
+  comparing = false;
+  edits = {};
+  previews = /* @__PURE__ */ new Map();
+  timer;
+  request;
+  sequence = 0;
+  disposed = false;
+  dirty = false;
+  pageId = crypto.randomUUID().replaceAll("-", "");
+  sync(variant, contexts, comparing) {
+    const changedVariant = this.variant?.value.id !== variant?.value.id;
+    this.variant = variant;
+    this.contexts = contexts;
+    const contextKey = contexts.map(key).join("|");
+    const changedContext = this.contextKey !== contextKey;
+    this.contextKey = contextKey;
+    if (changedVariant || comparing && !this.comparing) {
+      this.reset();
+      this.buildFields();
+    }
+    this.comparing = comparing;
+    const disabled = this.unavailable();
+    this.fields?.disable(Boolean(disabled));
+    if (disabled) {
+      this.ui.status.textContent = disabled;
+      this.ui.resetButton.disabled = true;
+    } else this.ui.resetButton.disabled = !this.dirty;
+    if (changedContext && !changedVariant && !disabled) {
+      this.cancel();
+      const edits = this.fields?.read() ?? this.edits;
+      if (Object.keys(edits).length) void this.render(edits);
+      else this.ui.status.textContent = "Saved props";
+    }
+  }
+  mount(panel) {
+    if (this.ui.panel.parentElement !== panel)
+      panel.replaceChildren(this.ui.panel);
+  }
+  views(saved) {
+    return saved.map((view) => {
+      const preview = this.previews.get(key(view));
+      return preview ? {
+        ...view,
+        path: decodeURIComponent(preview.previewUrl),
+        usage: preview.view
+      } : view;
+    });
+  }
+  props() {
+    const context = this.contexts[0];
+    return (context ? this.previews.get(key(context))?.props : void 0) ?? this.variant?.value.props;
+  }
+  unavailable() {
+    return controlsUnavailable(this.data, this.variant, this.comparing);
+  }
+  buildFields() {
+    if (this.data.entry.kind !== "component" || !this.variant) {
+      this.ui.form.replaceChildren();
+      return;
+    }
+    this.fields = controlFields(
+      this.root.ownerDocument,
+      this.data.entry,
+      this.variant.value,
+      (immediate) => this.edit(immediate)
+    );
+    this.ui.form.replaceChildren(this.fields.root);
+    this.details(this.variant.value.props);
+  }
+  details(props) {
+    const component = this.data.entry;
+    if (component.kind !== "component") return;
+    const other = Object.fromEntries(
+      Object.entries(decodeProps(props)).filter(
+        ([name]) => !Object.hasOwn(component.controls, name)
+      )
+    );
+    renderProps(this.ui.propsPanel, this.data, {
+      props: encodeProps(other),
+      slots: this.variant?.value.suppliedSlots ?? []
+    });
+    if (!Object.keys(other).length && !this.variant?.value.suppliedSlots.length)
+      this.ui.propsPanel.replaceChildren();
+  }
+  edit(immediate) {
+    if (this.unavailable()) return;
+    this.cancel();
+    this.ui.error.hidden = true;
+    this.ui.retry.hidden = true;
+    const overrides = this.fields?.read();
+    this.dirty = true;
+    this.ui.resetButton.disabled = false;
+    if (!overrides) {
+      this.ui.status.textContent = "Check the highlighted values. The preview shows the last valid props.";
+      return;
+    }
+    this.ui.error.hidden = true;
+    this.ui.retry.hidden = true;
+    const submit = () => {
+      if (!Object.keys(overrides).length) {
+        this.reset();
+        this.changed();
+      } else void this.render(overrides);
+    };
+    if (immediate) submit();
+    else this.timer = setTimeout(submit, 150);
+  }
+  async render(overrides) {
+    const capability = this.data.renderCapability;
+    const variant = this.variant;
+    if (!capability || !variant || this.unavailable()) return;
+    this.cancel();
+    const sequence = this.sequence;
+    const controller = new AbortController();
+    this.request = controller;
+    this.ui.status.textContent = "Updating preview\u2026";
+    this.ui.error.hidden = true;
+    this.ui.retry.hidden = true;
+    const previews = /* @__PURE__ */ new Map();
+    try {
+      for (const view of this.contexts)
+        previews.set(
+          key(view),
+          await requestComponentPreview(
+            {
+              componentId: this.data.entry.id,
+              variantId: variant.value.id,
+              viewport: view.viewport,
+              colorScheme: view.colorScheme,
+              generation: capability.generation,
+              pageId: this.pageId,
+              overrides
+            },
+            capability,
+            view,
+            controller.signal
+          )
+        );
+      if (controller.signal.aborted || sequence !== this.sequence || this.disposed)
+        return;
+      for (const [context, preview] of previews)
+        this.previews.set(context, preview);
+      this.edits = overrides;
+      for (const result of previews.values()) {
+        const frame = this.root.querySelector(
+          `iframe[data-workspace-frame="${result.view.viewport}"]`
+        );
+        if (frame)
+          frame.setAttribute(
+            `data-fragment-${result.view.colorScheme}`,
+            result.previewUrl
+          );
+      }
+      setColorScheme(
+        this.root.ownerDocument,
+        currentColorScheme(this.root.ownerDocument)
+      );
+      this.ui.status.textContent = "Edited props";
+      this.ui.resetButton.disabled = false;
+      const props = this.props();
+      if (props) this.details(props);
+      this.changed();
+    } catch (error) {
+      if (controller.signal.aborted || sequence !== this.sequence || this.disposed)
+        return;
+      this.ui.status.textContent = "The preview shows the last valid props.";
+      this.ui.error.textContent = error instanceof Error ? error.message : "The preview could not be updated. Try again.";
+      this.ui.error.hidden = false;
+      this.ui.retry.hidden = false;
+    }
+  }
+  cancel() {
+    this.sequence++;
+    clearTimeout(this.timer);
+    this.request?.abort();
+    this.request = void 0;
+  }
+  async verifyLoaded(frame, signal) {
+    const sequence = this.sequence;
+    try {
+      const expired = await componentPreviewExpired(
+        frame,
+        this.previews.values(),
+        signal
+      );
+      if (this.disposed || sequence !== this.sequence || !expired) return;
+      this.ui.status.textContent = "The temporary preview expired.";
+      this.ui.error.textContent = "Render it again to continue with these props.";
+      this.ui.error.hidden = false;
+      this.ui.retry.hidden = false;
+    } catch {
+    }
+  }
+  reset() {
+    this.cancel();
+    this.dirty = false;
+    this.edits = {};
+    this.previews.clear();
+    this.ui.error.hidden = true;
+    this.ui.retry.hidden = true;
+    this.ui.status.textContent = "Saved props";
+    this.ui.resetButton.disabled = true;
+    if (this.variant) applyVariant(this.root, this.data, this.variant);
+  }
+};
+function key(view) {
+  return `${view.viewport}/${view.colorScheme}`;
+}
+export {
+  ComponentControls
+};

package/dist/browser/component_geometry.js

@@ -0,0 +1,125 @@
+// src/client/component_geometry.ts
+import { componentNodeRects } from "./component_range_nodes.js";
+import { uncoveredBoxes } from "./component_occlusion.js";
+function authenticateRanges(frame, path, usage) {
+  try {
+    const doc = frame.contentDocument;
+    const parent = frame.ownerDocument;
+    const location = doc?.defaultView?.location;
+    if (!doc || !location || doc.defaultView?.frameElement !== frame || frame.sandbox.value !== "allow-same-origin" || location.origin !== parent.defaultView?.location.origin)
+      return;
+    const actual = decodeURIComponent(location.pathname).replace(/\.html$/, "");
+    const expected = path.startsWith("/__mokly/components/renders/") ? path : `/static/${path}`;
+    if (actual !== expected.replace(/\.html$/, "")) return;
+    const walker = doc.createTreeWalker(doc, 128);
+    const stack = [];
+    const ranges = /* @__PURE__ */ new Map();
+    let next = 0;
+    let node;
+    while (node = walker.nextNode()) {
+      const text = node.textContent ?? "";
+      if (!text.startsWith("mokly-component:")) continue;
+      const match = /^mokly-component:(start|end):(r-[0-9]+)$/.exec(text);
+      if (!match) return;
+      const record = usage.ranges.find((item) => item.id === match[2]);
+      if (!record) return;
+      if (match[1] === "start") {
+        if (usage.ranges[next++]?.id !== record.id || record.parentId !== stack.at(-1)?.id)
+          return;
+        stack.push({ id: record.id, node });
+      } else {
+        const start = stack.pop();
+        if (start?.id !== record.id) return;
+        if (record.target.kind !== "instance") continue;
+        const range = doc.createRange();
+        range.setStartAfter(start.node);
+        range.setEndBefore(node);
+        const key = record.target.instanceKey;
+        ranges.set(key, [...ranges.get(key) ?? [], range]);
+      }
+    }
+    if (stack.length || next !== usage.ranges.length) return;
+    return { doc, ranges };
+  } catch {
+    return;
+  }
+}
+function intersect(a, b) {
+  const box = {
+    left: Math.max(a.left, b.left),
+    top: Math.max(a.top, b.top),
+    right: Math.min(a.right, b.right),
+    bottom: Math.min(a.bottom, b.bottom)
+  };
+  return box.right > box.left && box.bottom > box.top ? box : void 0;
+}
+function clipAncestors(box, node, win) {
+  let current = box;
+  for (let parent = node; parent && current; parent = parent.parentElement) {
+    const style = win.getComputedStyle(parent);
+    const bounds = parent.getBoundingClientRect();
+    const clipX = /(hidden|clip|scroll|auto)/.test(style.overflowX);
+    const clipY = /(hidden|clip|scroll|auto)/.test(style.overflowY);
+    if (clipX || clipY)
+      current = intersect(current, {
+        left: clipX ? bounds.left : current.left,
+        right: clipX ? bounds.right : current.right,
+        top: clipY ? bounds.top : current.top,
+        bottom: clipY ? bounds.bottom : current.bottom
+      });
+    if (style.position === "fixed") break;
+  }
+  return current;
+}
+function rangeBounds(frame, authenticated, keys) {
+  const { doc, ranges } = authenticated;
+  const win = doc.defaultView;
+  const result = [];
+  const candidates = [...doc.querySelectorAll("body *")];
+  const rects = /* @__PURE__ */ new WeakMap();
+  for (const [key, values] of ranges) {
+    if (!keys.has(key)) continue;
+    for (const range of values) {
+      for (const { rect, parent } of componentNodeRects(range)) {
+        let box = intersect(rect, {
+          left: 0,
+          top: 0,
+          right: frame.clientWidth,
+          bottom: frame.clientHeight
+        });
+        if (!box) continue;
+        box = clipAncestors(box, parent, win);
+        if (!box) continue;
+        for (const visible of uncoveredBoxes(box, range, candidates, rects))
+          result.push({
+            key,
+            x: visible.left,
+            y: visible.top,
+            width: visible.right - visible.left,
+            height: visible.bottom - visible.top
+          });
+      }
+    }
+  }
+  return result.filter(
+    (box, index) => !result.some(
+      (other, otherIndex) => other.key === box.key && otherIndex !== index && other.x <= box.x && other.y <= box.y && other.x + other.width >= box.x + box.width && other.y + other.height >= box.y + box.height && (other.width > box.width || other.height > box.height || otherIndex < index)
+    )
+  );
+}
+function visibleFrameBox(frame) {
+  const win = frame.ownerDocument.defaultView;
+  const bounds = frame.getBoundingClientRect();
+  const viewport = intersect(bounds, {
+    left: 0,
+    top: 0,
+    right: win.innerWidth,
+    bottom: win.innerHeight
+  });
+  return viewport ? clipAncestors(viewport, frame.parentElement, win) : void 0;
+}
+export {
+  authenticateRanges,
+  rangeBounds,
+  visibleFrameBox
+};

package/dist/browser/component_highlight.js

@@ -0,0 +1,152 @@
+// src/client/component_highlight.ts
+import { createOverlay } from "./component_overlay.js";
+import {
+  authenticateRanges,
+  rangeBounds,
+  visibleFrameBox
+} from "./component_geometry.js";
+function installComponentHighlight(root, frames, selected, label, select, exit) {
+  const doc = root.ownerDocument;
+  const win = doc.defaultView;
+  const controller = new AbortController();
+  const cleanups = [];
+  let pending = 0;
+  const draws = [];
+  const schedule = () => {
+    if (!pending)
+      pending = win.requestAnimationFrame(() => {
+        pending = 0;
+        for (const draw of draws) draw();
+      });
+  };
+  for (const entry of frames) {
+    const { frame, usage } = entry;
+    const authenticated = authenticateRanges(frame, entry.path, usage);
+    if (!authenticated) continue;
+    const layer = doc.createElement("div");
+    layer.className = "mbk-highlight-layer";
+    layer.dataset["highlightViewport"] = usage.viewport;
+    doc.body.append(layer);
+    cleanups.push(() => layer.remove());
+    const keys = new Set(
+      usage.instances.filter(
+        (instance) => selected ? instance.key === selected : instance.owner.kind === "entry"
+      ).map((instance) => instance.key)
+    );
+    let bounds = [];
+    const draw = () => {
+      const visible = visibleFrameBox(frame);
+      layer.hidden = !visible || frame.getClientRects().length === 0;
+      if (layer.hidden || !visible) return;
+      const rect = frame.getBoundingClientRect();
+      const scaleX = rect.width / frame.offsetWidth;
+      const scaleY = rect.height / frame.offsetHeight;
+      Object.assign(layer.style, {
+        left: `${visible.left}px`,
+        top: `${visible.top}px`,
+        width: `${visible.right - visible.left}px`,
+        height: `${visible.bottom - visible.top}px`,
+        zIndex: frame.closest(".browser-frame.is-expanded") ? "951" : "4"
+      });
+      bounds = rangeBounds(frame, authenticated, keys);
+      const width = visible.right - visible.left;
+      const height = visible.bottom - visible.top;
+      const overlay = createOverlay(doc, width, height);
+      const labels = [];
+      const seen = /* @__PURE__ */ new Set();
+      for (const box of bounds) {
+        const x = rect.left + (box.x + frame.clientLeft) * scaleX - visible.left;
+        const y = rect.top + (box.y + frame.clientTop) * scaleY - visible.top;
+        const w = box.width * scaleX;
+        const h = box.height * scaleY;
+        overlay.cutout(x, y, w, h);
+        if (!seen.has(box.key) && x + w > 0 && y + h > 0 && x < width && y < height) {
+          const button = doc.createElement("button");
+          button.type = "button";
+          button.className = "mbk-highlight-label";
+          button.textContent = label(box.key);
+          button.dataset["instanceKey"] = box.key;
+          button.style.left = `${Math.max(0, Math.min(width - 40, x))}px`;
+          button.style.top = `${Math.max(0, Math.min(height - 22, y - 22))}px`;
+          button.addEventListener(
+            "click",
+            () => select(box.key, usage.viewport)
+          );
+          labels.push(button);
+          seen.add(box.key);
+        }
+      }
+      const focusedKey = layer.contains(doc.activeElement) ? doc.activeElement?.dataset["instanceKey"] : void 0;
+      layer.replaceChildren(overlay.svg, ...labels);
+      if (focusedKey)
+        labels.find((button) => button.dataset["instanceKey"] === focusedKey)?.focus({ preventScroll: true });
+    };
+    draws.push(draw);
+    const activate = (event) => {
+      const match = bounds.find(
+        (box) => event.clientX >= box.x && event.clientX <= box.x + box.width && event.clientY >= box.y && event.clientY <= box.y + box.height
+      );
+      if (!match) return;
+      event.preventDefault();
+      event.stopImmediatePropagation();
+      select(match.key, usage.viewport);
+    };
+    authenticated.doc.addEventListener("click", activate, {
+      capture: true,
+      signal: controller.signal
+    });
+    authenticated.doc.addEventListener("auxclick", activate, {
+      capture: true,
+      signal: controller.signal
+    });
+    authenticated.doc.addEventListener(
+      "keydown",
+      (event) => {
+        if (event.key === "Escape") {
+          event.preventDefault();
+          exit();
+        }
+      },
+      { signal: controller.signal }
+    );
+    authenticated.doc.addEventListener("scroll", schedule, {
+      capture: true,
+      passive: true,
+      signal: controller.signal
+    });
+    authenticated.doc.addEventListener("load", schedule, {
+      capture: true,
+      signal: controller.signal
+    });
+    authenticated.doc.fonts.addEventListener("loadingdone", schedule, {
+      signal: controller.signal
+    });
+    const resize = new ResizeObserver(schedule);
+    resize.observe(frame);
+    if (authenticated.doc.body) resize.observe(authenticated.doc.body);
+    cleanups.push(() => resize.disconnect());
+    const changes = new MutationObserver(schedule);
+    changes.observe(authenticated.doc, {
+      attributes: true,
+      childList: true,
+      characterData: true,
+      subtree: true
+    });
+    cleanups.push(() => changes.disconnect());
+  }
+  doc.addEventListener("scroll", schedule, {
+    capture: true,
+    passive: true,
+    signal: controller.signal
+  });
+  win.addEventListener("resize", schedule, { signal: controller.signal });
+  schedule();
+  return () => {
+    controller.abort();
+    if (pending) win.cancelAnimationFrame(pending);
+    for (const cleanup of cleanups) cleanup();
+  };
+}
+export {
+  installComponentHighlight
+};