@jxsuite/studio 6.1.1 → 8.0.0

package/src/create/element-name.ts

@@ -0,0 +1,121 @@
+/**
+ * What makes a component's tag name usable, decided once.
+ *
+ * Two rules used to answer this and they disagreed: Convert to Component accepted
+ * `/^[a-z][a-z0-9]*(-[a-z0-9]+)+$/`, which refused `x-card.v2` and `my_el-x`, and the Library's
+ * component seed accepted `/^[a-z][\d.a-z]*-[\d.a-z-]*$/`, which allowed a trailing hyphen the
+ * first refused. Neither was the rule the browser applies, which is the only one that matters: a
+ * definition whose tag `customElements.define` rejects is a component nothing can register. So this
+ * module states HTML's own production — the [valid custom element
+ * name](https://html.spec.whatwg.org/multipage/custom-elements.html#valid-custom-element-name) —
+ * and every creation flow asks it: Add new (`create/add-new.ts`) and Convert to Component
+ * (`editor/convert-to-component.ts`).
+ *
+ * The DERIVER is the other half. A name the reader typed as a title ("Pricing table") becomes a tag
+ * (`pricing-table`), and a name with no hyphen gains a `site-` prefix rather than being refused,
+ * because "Hero" is a perfectly good thing to call a component and a refusal there teaches nothing
+ * but the syntax of a rule the app can satisfy itself (`specs/studio.md` §9.1.1).
+ *
+ * DOM-free, so the command records and the pure derivation can import it in a bare Bun process.
+ *
+ * @docs studio/design/components
+ */
+
+import { slugify } from "../files/new-file-name";
+
+/** The prefix a hyphenless slug gains, so the derived tag is a valid custom element name. */
+export const TAG_PREFIX = "site-";
+
+/**
+ * Names HTML reserves: they match the production but are SVG and MathML elements that predate it,
+ * so `customElements.define` refuses each one.
+ */
+export const RESERVED_ELEMENT_NAMES: ReadonlySet<string> = new Set([
+  "annotation-xml",
+  "color-profile",
+  "font-face",
+  "font-face-format",
+  "font-face-name",
+  "font-face-src",
+  "font-face-uri",
+  "missing-glyph",
+]);
+
+/**
+ * HTML's `PCENChar`: the characters a potential custom element name may hold after its first
+ * letter. ASCII upper case is deliberately absent, which is why a tag name is lower case.
+ */
+const PCEN_RANGES: readonly (readonly [number, number])[] = [
+  [0xb7, 0xb7],
+  [0xc0, 0xd6],
+  [0xd8, 0xf6],
+  [0xf8, 0x3_7d],
+  [0x3_7f, 0x1f_ff],
+  [0x20_0c, 0x20_0d],
+  [0x20_3f, 0x20_40],
+  [0x20_70, 0x21_8f],
+  [0x2c_00, 0x2f_ef],
+  [0x30_01, 0xd7_ff],
+  [0xf9_00, 0xfd_cf],
+  [0xfd_f0, 0xff_fd],
+  [0x1_00_00, 0xe_ff_ff],
+];
+
+/** A code point as a `u`-flag regular expression escape, so no invisible character is in source. */
+function escapeCodePoint(cp: number): string {
+  return `${String.fromCodePoint(92)}u{${cp.toString(16)}}`;
+}
+
+/** The whole class body: ASCII first, then each range by its escaped ends. */
+const PCEN_CHAR = [
+  String.raw`\-.0-9_a-z`,
+  ...PCEN_RANGES.map(([from, to]) => `${escapeCodePoint(from)}-${escapeCodePoint(to)}`),
+].join("");
+
+/** One character that may appear after the first letter. */
+const ONE_PCEN_CHAR = new RegExp(`^[${PCEN_CHAR}]$`, "u");
+
+/**
+ * The sentence a tag name earns, or `""` when it is valid.
+ *
+ * Each sentence names the one thing to change, in the order a reader fixes them: say something,
+ * start with a letter, lose the character the browser refuses, add the hyphen, avoid a reserved
+ * name.
+ */
+export function customElementNameProblem(name: string): string {
+  if (name === "") {
+    return "Enter a tag name.";
+  }
+  if (!/^[a-z]/.test(name)) {
+    return "A tag name starts with a lower-case letter.";
+  }
+  for (const char of name.slice(1)) {
+    if (!ONE_PCEN_CHAR.test(char)) {
+      return /[A-Z]/.test(char)
+        ? "A tag name is lower case."
+        : `“${char}” cannot appear in a tag name.`;
+    }
+  }
+  if (!name.includes("-")) {
+    return "A tag name needs a hyphen, such as my-card.";
+  }
+  if (RESERVED_ELEMENT_NAMES.has(name)) {
+    return `<${name}> is reserved by HTML.`;
+  }
+  return "";
+}
+
+/**
+ * The tag a display name derives to: slugified, its hyphens tidied, and prefixed with
+ * {@link TAG_PREFIX} when it would otherwise have no hyphen or would start with a digit.
+ *
+ * `"Pricing table"` → `pricing-table`, `"Hero"` → `site-hero`, `"2 columns"` → `site-2-columns`,
+ * and a name with nothing usable in it → `""`, which {@link customElementNameProblem} refuses.
+ */
+export function deriveTagName(input: string): string {
+  const slug = slugify(input).replaceAll(/-+/g, "-").replaceAll(/^-|-$/g, "");
+  if (slug === "") {
+    return "";
+  }
+  return /^[a-z]/.test(slug) && slug.includes("-") ? slug : `${TAG_PREFIX}${slug}`;
+}

package/src/editor/canvas-context-menu.ts

@@ -15,7 +15,6 @@ import { dismissContextMenu, showContextMenu } from "./context-menu";
 import { bubbleInlinePath } from "../canvas/canvas-helpers";
 import { activeTab } from "../workspace/workspace";
 import type { CanvasContextMenuHandler } from "../canvas/iframe-host";
-import type { JxPath } from "../state";
 
 /**
  * Build the handler.
@@ -34,7 +33,7 @@ export function makeCanvasContextMenuHandler(): CanvasContextMenuHandler {
       }
       // Lift inline-element paths (a <strong> inside a <p>) to their block parent — right-clicking
       // Formatted text should act on the block, matching the legacy handler.
-      const bubbled = bubbleInlinePath(activeTab.value?.doc.document, path as JxPath);
+      const bubbled = bubbleInlinePath(activeTab.value?.doc.document, path);
       // ShowContextMenu reads only preventDefault/clientX/clientY from the event, so a synthetic
       // MouseEvent carries the converted coords safely.
       const evt = new MouseEvent("contextmenu", { clientX, clientY });

package/src/editor/canvas-slash-bridge.ts

@@ -18,11 +18,8 @@ export const canvasSlashHandler: CanvasSlashHandler = {
      opened. Typing "/" needs none — the author keeps typing into the iframe's contenteditable and
      the engine re-posts `slashShow` with the updated filter. A menu opened BY NAME
      (`insert.openSlashMenu`) has no "/…" run to type into, so without the field the only way past
-     fifteen blocks is scrolling. */
+     fifteen blocks is scrolling. The menu reads `showFilter` for truthiness alone, so `false` and an
+     absent key are one state to it. */
   show: ({ rect, filter, showFilter, onSelect, onDismiss }) =>
-    showSlashMenuAtRect(rect, filter, {
-      onDismiss,
-      onSelect,
-      ...(showFilter === true ? { showFilter: true } : {}),
-    }),
+    showSlashMenuAtRect(rect, filter, { onDismiss, onSelect, showFilter: showFilter === true }),
 };

package/src/editor/content-slice.ts

@@ -14,11 +14,18 @@
  * @docs studio/editing/writing
  */
 
+import { isString } from "@jxsuite/schema/guards";
 import type { JxMutableNode } from "@jxsuite/schema/types";
 
 /** A block's content as a children array — the form both storage shapes normalize to. */
 export type Content = (JxMutableNode | string)[];
 
+/** A block's content in the form it is stored: `children` for markup, folded `textContent` else. */
+export interface StoredContent {
+  children?: Content;
+  textContent?: string;
+}
+
 /**
  * The content of `node` as a children array, whichever way it is stored.
  *
@@ -30,18 +37,16 @@ export function contentOf(node: JxMutableNode | undefined | null): Content {
     return [];
   }
   if (Array.isArray(node.children)) {
-    return node.children as Content;
+    return node.children;
   }
-  return typeof node.textContent === "string" && node.textContent.length > 0
-    ? [node.textContent]
-    : [];
+  return isString(node.textContent) && node.textContent.length > 0 ? [node.textContent] : [];
 }
 
 /** The rendered text length of a content array. */
 export function contentLength(children: Content): number {
   let n = 0;
   for (const child of children) {
-    n += typeof child === "string" ? child.length : contentLength(contentOf(child));
+    n += isString(child) ? child.length : contentLength(contentOf(child));
   }
   return n;
 }
@@ -60,7 +65,7 @@ export function sliceContent(children: Content, start: number, end: number): Con
     if (pos >= end) {
       break;
     }
-    if (typeof child === "string") {
+    if (isString(child)) {
       const childEnd = pos + child.length;
       if (childEnd > start) {
         const text = child.slice(
@@ -102,7 +107,7 @@ function withContent(node: JxMutableNode, children: Content): JxMutableNode {
   if (children.length === 0) {
     return { ...rest, textContent: "" };
   }
-  if (children.length === 1 && typeof children[0] === "string") {
+  if (children.length === 1 && isString(children[0])) {
     return { ...rest, textContent: children[0] };
   }
   return { ...rest, children };
@@ -115,12 +120,12 @@ function withContent(node: JxMutableNode, children: Content): JxMutableNode {
 export function normalizeContent(children: Content): Content {
   const out: Content = [];
   for (const child of children) {
-    if (typeof child === "string") {
+    if (isString(child)) {
       if (child.length === 0) {
         continue;
       }
       const prev = out.at(-1);
-      if (typeof prev === "string") {
+      if (isString(prev)) {
         out[out.length - 1] = prev + child;
         continue;
       }
@@ -152,15 +157,12 @@ export function spliceAcross(
 }
 
 /** `{ children }` when the content carries markup, else the folded `{ textContent }` form. */
-export function toStored(children: Content): {
-  children?: Content;
-  textContent?: string;
-} {
+export function toStored(children: Content): StoredContent {
   const normalized = normalizeContent(children);
   if (normalized.length === 0) {
     return { textContent: "" };
   }
-  if (normalized.length === 1 && typeof normalized[0] === "string") {
+  if (normalized.length === 1 && isString(normalized[0])) {
     return { textContent: normalized[0] };
   }
   return { children: normalized };

package/src/editor/context-menu.ts

@@ -21,10 +21,11 @@
  * is left here is the projection: the menu itself is the `menu` surface (`surfaces/menu.json`), a
  * `jx-menu` the kit gives its keyboard contract, its popover and its dismissal.
  */
-import { displayTagName } from "@jxsuite/schema/guards";
+import { getNodeAtPath } from "@jxsuite/schema/doc-ops";
+import { displayTagName, isNodeObject, isNonNullObject, isString } from "@jxsuite/schema/guards";
 import { jsonClone } from "../utils/studio-utils";
 import { htmlToJx } from "@jxsuite/markup/html-to-jx";
-import { childIndex, getNodeAtPath, parentElementPath } from "../store";
+import { childIndex, parentElementPath } from "../store";
 import { activeTab, workspace } from "../workspace/workspace";
 import { isSelected, isSpliceablePath, primarySelection } from "../tabs/selection";
 import {
@@ -58,17 +59,15 @@ import type { AnyCommand, CommandRegistry } from "../commands/registry";
 import type { CommandContext } from "../commands/context";
 import type { Placement } from "../commands/levels";
 import type { JxPath } from "../state";
-import type { JxMutableNode, JxStyle } from "@jxsuite/schema/types";
-
-type JxNode = JxMutableNode;
+import type { JxAttributeValue, JxMutableNode, JxStyle } from "@jxsuite/schema/types";
 
 // ─── Clipboard helpers ───────────────────────────────────────────────────────
 
-const JX_MIME = "web application/jx+json";
+export const JX_MIME = "web application/jx+json";
 
-/** @param {JxNode | string} node */
-function nodeToHtml(node: JxNode | string): string {
-  if (typeof node === "string") {
+/** @param {JxMutableNode | string} node */
+function nodeToHtml(node: JxMutableNode | string): string {
+  if (isString(node)) {
     return node;
   }
   /* A chosen tag cannot be serialised to one HTML string, so the copy takes the branch the
@@ -77,9 +76,10 @@ function nodeToHtml(node: JxNode | string): string {
   const tag = displayTagName(node.tagName).split("|")[0] || "div";
   let attrs = "";
   if (node.attributes) {
-    for (const [k, v] of Object.entries(node.attributes)) {
+    // A document's attribute value is read as possibly JSON `null`, which is skipped with the refs.
+    for (const [k, v] of Object.entries<JxAttributeValue | null>(node.attributes)) {
       // Bound ($ref) attribute values have no static HTML representation — skip.
-      if (typeof v === "object") {
+      if (v === null || isNonNullObject(v)) {
         continue;
       }
       attrs += v === "" ? ` ${k}` : ` ${k}="${String(v).replaceAll('"', "&quot;")}"`;
@@ -94,7 +94,7 @@ function nodeToHtml(node: JxNode | string): string {
     }
   }
   let inner = "";
-  if (typeof node.textContent === "string") {
+  if (isString(node.textContent)) {
     inner = node.textContent;
   } else if (Array.isArray(node.children)) {
     inner = node.children.map((c) => nodeToHtml(c)).join("");
@@ -105,9 +105,9 @@ function nodeToHtml(node: JxNode | string): string {
 /**
  * Write a Jx node to the system clipboard with both jx+json and text/html types.
  *
- * @param {object} json
+ * @param {JxMutableNode} json
  */
-async function writeToClipboard(json: Record<string, unknown>) {
+async function writeToClipboard(json: JxMutableNode) {
   workspace.clipboard = json;
   try {
     const jxBlob = new Blob([JSON.stringify(json)], { type: JX_MIME });
@@ -131,7 +131,7 @@ async function writeToClipboard(json: Record<string, unknown>) {
 /**
  * Read from the system clipboard. Returns Jx node(s) or null.
  *
- * @returns {Promise<JxNode[] | null>}
+ * @returns {Promise<JxMutableNode[] | null>}
  */
 async function readFromClipboard() {
   try {
@@ -139,16 +139,18 @@ async function readFromClipboard() {
     for (const item of items) {
       if (item.types.includes(JX_MIME)) {
         const blob = await item.getType(JX_MIME);
-        const json = JSON.parse(await blob.text()) as JxNode;
+        /* SAFETY: `web application/jx+json` is Jx's own clipboard type, and `writeToClipboard` puts a
+           node there serialized with JSON.stringify; malformed text throws into the fallback below. */
+        const json = JSON.parse(await blob.text()) as JxMutableNode;
         return [json];
       }
       if (item.types.includes("text/html")) {
         const blob = await item.getType("text/html");
         const htmlStr = await blob.text();
         const nodes = htmlToJx(htmlStr);
-        const jxNodes = nodes.map((n) =>
-          typeof n === "string" ? { tagName: "p", textContent: n } : n,
-        ) as JxNode[];
+        const jxNodes: JxMutableNode[] = nodes.map((n) =>
+          isString(n) ? { tagName: "p", textContent: n } : n,
+        );
         if (jxNodes.length > 0) {
           return jxNodes;
         }
@@ -158,8 +160,8 @@ async function readFromClipboard() {
         const text = await blob.text();
         // Try parsing as Jx JSON
         try {
-          const parsed = JSON.parse(text) as JxNode;
-          if (parsed && parsed.tagName) {
+          const parsed: unknown = JSON.parse(text);
+          if (isNodeObject(parsed) && parsed.tagName) {
             return [parsed];
           }
         } catch {
@@ -241,7 +243,12 @@ export async function pasteNode() {
   }
 
   if (selected && selected.length >= 2) {
+    // SAFETY: parentElementPath returns a path for any path of two or more segments, checked above.
     const pp = parentElementPath(selected) as JxPath;
+    /* SAFETY: a selection with a sibling position ends in `"children", <index>`, so this is the
+       numeric child index. A selected repeater template (`…, "map"`) or `$switch` case also has two
+       or more segments; callers do not exclude that case yet, so it reaches here with a string
+       segment exactly as before this cast. */
     const idx = childIndex(selected) as number;
     transactDoc(tab, (t) => {
       for (let i = 0; i < nodes.length; i++) {
@@ -408,7 +415,10 @@ export function elementCommands(deps: ElementCommandDeps): AnyCommand[] {
         if (!target || !nodes || nodes.length === 0) {
           return;
         }
+        /* SAFETY: this record runs only when enabled, and `spliceable` admits a target whose path
+           ends in `"children", <index>` — so it has a parent element path. */
         const parent = parentElementPath(target.path) as JxPath;
+        // SAFETY: the same `spliceable` check proved the last segment is a numeric child index.
         const idx = childIndex(target.path) as number;
         transactDoc(activeTab.value, (t) => {
           for (const [offset, node] of nodes.entries()) {
@@ -576,7 +586,10 @@ function insertSiblingParagraph(target: ElementMenuTarget | null, offset: number
   if (!target) {
     return;
   }
+  /* SAFETY: both callers are records enabled only by `spliceable`, which admits a target whose path
+     ends in `"children", <index>` — so it has a parent element path. */
   const parent = parentElementPath(target.path) as JxPath;
+  // SAFETY: the same `spliceable` check proved the last segment is a numeric child index.
   const idx = childIndex(target.path) as number;
   transactDoc(activeTab.value, (t) =>
     mutateInsertNode(t, parent, idx + offset, { children: [], tagName: "p" }),
@@ -681,7 +694,7 @@ function commandTarget(): ElementMenuTarget | null {
   if (!tab || !path) {
     return null;
   }
-  const node = getNodeAtPath(tab.doc.document, path) as JxMutableNode | undefined;
+  const node = getNodeAtPath(tab.doc.document, path);
   return node ? { node, path } : null;
 }
 

package/src/editor/convert-targets.ts

@@ -1,34 +1,33 @@
 import elementsMeta from "../../data/elements-meta.json";
 
-export interface SlashCommand {
-  label: string;
-  tag: string;
-  description: string;
-}
+import { ELEMENT_DEFS } from "./editable-tags";
+import type { SlashCommand } from "./inline-edit";
+
+export type { SlashCommand } from "./inline-edit";
 
-const TAG_LABELS = {
-  article: "Article",
-  aside: "Aside",
-  blockquote: "Blockquote",
-  div: "Div",
-  footer: "Footer",
-  h1: "Heading 1",
-  h2: "Heading 2",
-  h3: "Heading 3",
-  h4: "Heading 4",
-  h5: "Heading 5",
-  h6: "Heading 6",
-  header: "Header",
-  main: "Main",
-  nav: "Nav",
-  ol: "Numbered List",
-  p: "Paragraph",
-  search: "Search",
-  section: "Section",
-  ul: "Bulleted List",
-} as Record<string, string>;
+const TAG_LABELS = new Map<string, string>([
+  ["article", "Article"],
+  ["aside", "Aside"],
+  ["blockquote", "Blockquote"],
+  ["div", "Div"],
+  ["footer", "Footer"],
+  ["h1", "Heading 1"],
+  ["h2", "Heading 2"],
+  ["h3", "Heading 3"],
+  ["h4", "Heading 4"],
+  ["h5", "Heading 5"],
+  ["h6", "Heading 6"],
+  ["header", "Header"],
+  ["main", "Main"],
+  ["nav", "Nav"],
+  ["ol", "Numbered List"],
+  ["p", "Paragraph"],
+  ["search", "Search"],
+  ["section", "Section"],
+  ["ul", "Bulleted List"],
+]);
 
-const groups = (elementsMeta.$convertGroups || {}) as Record<string, string[]>;
+const groups: Readonly<Record<string, string[]>> = elementsMeta.$convertGroups;
 
 /**
  * Get the list of tags the current element can be converted to.
@@ -37,18 +36,14 @@ const groups = (elementsMeta.$convertGroups || {}) as Record<string, string[]>;
  * @param {boolean} isEmpty
  * @returns {SlashCommand[]}
  */
-export function getConvertTargets(currentTag: string, isEmpty: boolean) {
-  const def = (elementsMeta.$defs as Record<string, Record<string, unknown>>)?.[currentTag] as
-    | Record<string, unknown>
-    | undefined;
+export function getConvertTargets(currentTag: string, isEmpty: boolean): SlashCommand[] {
+  const def = ELEMENT_DEFS[currentTag];
   if (!def?.$convertTo) {
     return [];
   }
 
   const groupNames =
-    isEmpty && def.$convertToWhenEmpty
-      ? (def.$convertToWhenEmpty as string[])
-      : [def.$convertTo as string];
+    isEmpty && def.$convertToWhenEmpty ? def.$convertToWhenEmpty : [def.$convertTo];
 
   const tags = new Set<string>();
   for (const name of groupNames) {
@@ -61,7 +56,7 @@ export function getConvertTargets(currentTag: string, isEmpty: boolean) {
 
   return [...tags].map((tag) => ({
     description: "",
-    label: TAG_LABELS[tag] || tag.charAt(0).toUpperCase() + tag.slice(1),
+    label: TAG_LABELS.get(tag) || tag.charAt(0).toUpperCase() + tag.slice(1),
     tag,
   }));
 }