@jxsuite/studio 6.1.1 → 8.0.0

package/src/editor/convert-to-component.ts

@@ -12,14 +12,18 @@
  * was fixed.
  *
  * What is left is the flow, which is all this module ever owned that mattered: what the default
- * name is, what makes a name usable, whether the document actually took the reference, and what is
- * written to disk once it has.
+ * name is, whether the document actually took the reference, and what is written to disk once it
+ * has. What makes a name usable is no longer this module's: it is HTML's valid custom element name,
+ * stated once in `create/element-name.ts` and asked by Add new's Component kind too, which runs
+ * {@link convertSelectionToComponent} for **Start from: Current selection** (`specs/studio.md`
+ * §9.1.1).
  *
  * @docs studio/design/components
  */
-import { displayTagName } from "@jxsuite/schema/guards";
+import { displayTagName, isNonNullObject } from "@jxsuite/schema/guards";
 import { errorMessage } from "@jxsuite/schema/parse";
-import { childIndex, getNodeAtPath, parentElementPath } from "../store";
+import { getNodeAtPath } from "@jxsuite/schema/doc-ops";
+import { childIndex, parentElementPath } from "../store";
 import { primarySelection } from "../tabs/selection";
 import { activeTab } from "../workspace/workspace";
 import { transact } from "../tabs/transact";
@@ -30,33 +34,62 @@ import { serializeJson } from "@jxsuite/schema/json-layout";
 import { notify } from "../services/notify";
 import { showPromptDialog } from "../ui/layers";
 import { validateComponentSlots } from "../services/cem-export";
+import { customElementNameProblem, deriveTagName } from "../create/element-name";
 
-import type { JxMutableNode } from "@jxsuite/schema/types";
+import type { JxMutableNode, JxPath } from "@jxsuite/schema/types";
 
-const VALID_NAME = /^[a-z][a-z0-9]*(-[a-z0-9]+)+$/;
-
-/** Convert the currently selected element into a reusable component. */
-export async function convertToComponent() {
+/**
+ * The selected element a conversion would lift out, or `null` when there is none to convert.
+ *
+ * The root is not convertible (it is the document, not an element in it), and neither is a
+ * selection the document cannot resolve to a node with a tag. Exported so Add new can say WHY its
+ * Current selection choice is disabled rather than offering a button that does nothing.
+ */
+export function convertibleSelection(): { path: JxPath; node: JxMutableNode } | null {
   const tab = activeTab.value;
   const selected = primarySelection(tab?.session.selection);
   if (!tab || !selected || selected.length < 2) {
-    return;
+    return null;
   }
-
   const node = getNodeAtPath(tab.doc.document, selected);
   if (!node || !node.tagName) {
-    return;
+    return null;
   }
+  return { node, path: selected };
+}
 
-  const defaultName = deriveDefaultName(node);
-  const chosen = await promptComponentName(defaultName);
+/** Convert the currently selected element into a reusable component. */
+export async function convertToComponent() {
+  const subject = convertibleSelection();
+  if (!subject) {
+    return;
+  }
+  const chosen = await promptComponentName(deriveDefaultName(subject.node));
   if (!chosen) {
     return;
   }
   /* The prompt resolves the TRIMMED value; the case fold is this module's, because it is the case
      fold `validateName` already judged the name in. A tag name is lower-case by the same rule that
      made `Hero-Block` default to `hero-block`. */
-  const name = chosen.toLowerCase();
+  await convertSelectionToComponent(chosen.toLowerCase());
+}
+
+/**
+ * Replace the selected element with an instance of a new component named `name`, and write the
+ * component's definition to `components/<name>.json`.
+ *
+ * The caller has validated `name` (`create/element-name.ts`). The reference goes into the document
+ * FIRST, in one transaction, and the file is written only if that transaction landed — see below.
+ *
+ * @returns The component file's path, or `null` when nothing was converted or the write failed.
+ */
+export async function convertSelectionToComponent(name: string): Promise<string | null> {
+  const tab = activeTab.value;
+  const subject = convertibleSelection();
+  if (!tab || !subject) {
+    return null;
+  }
+  const { node, path: selected } = subject;
 
   // Extract component definition
   const componentDef = extractComponentDef(node);
@@ -71,10 +104,16 @@ export async function convertToComponent() {
   const converted = transact(tab, (doc) => {
     // Navigate to parent's children array and replace the node
     const pp = parentElementPath(selectionPath) ?? [];
+    /* SAFETY: an element with a sibling position ends in `"children", <index>`, so this is the
+       numeric child index. A selected repeater template (`…, "map"`) or `$switch` case also passes
+       the two-segment check above; callers do not exclude that case yet, so it reaches here with a
+       string segment exactly as before this cast. */
     const idx = childIndex(selectionPath) as number;
     let parent = doc;
-    // Paths address nodes by construction (same contract as getNodeAtPath).
     for (const seg of pp) {
+      /* SAFETY: `pp` is the parent element's path, and a `JxPath` alternates node keys with
+         `"children"` and an index, so walking it from the root lands on a node (the same contract as
+         getNodeAtPath). */
       parent = parent[seg] as JxMutableNode;
     }
     if (!Array.isArray(parent.children)) {
@@ -87,8 +126,7 @@ export async function convertToComponent() {
       doc.$elements = [];
     }
     const alreadyReferenced = doc.$elements.some(
-      (/** @type {JxMutableNode | string | { $ref: string }} */ el) =>
-        el && typeof el === "object" && "$ref" in el && el.$ref === refPath,
+      (el) => isNonNullObject(el) && "$ref" in el && el.$ref === refPath,
     );
     if (!alreadyReferenced) {
       doc.$elements.push({ $ref: refPath });
@@ -101,7 +139,7 @@ export async function convertToComponent() {
      document the author was told had been changed. The gate raises its own toast saying why the
      edit is paused; the honest thing to add to it is nothing at all. */
   if (!converted) {
-    return;
+    return null;
   }
 
   // Write component file and refresh registry
@@ -124,27 +162,31 @@ export async function convertToComponent() {
         tier: "problem",
       });
     }
+    return componentFile;
   } catch (error) {
     notify.error(`Could not save the <${name}> component.`, {
       detail: errorMessage(error),
       path: componentFile,
       source: "Components",
     });
+    return null;
   }
 }
 
 /**
- * Derive a default tag name from a node.
- *
- * @param {JxMutableNode} node
- * @returns {string}
+ * The default tag name for a node: its `$id` when it has one, else its tag, through the shared
+ * deriver — so `$id: "Hero"` proposes `site-hero` and a `<section>` proposes `site-section`, the
+ * same answer Add new gives a component typed as "Hero".
  */
 function deriveDefaultName(node: JxMutableNode) {
-  if (node.$id && node.$id.includes("-")) {
-    return node.$id.toLowerCase();
+  if (node.$id) {
+    const fromId = deriveTagName(node.$id);
+    if (fromId !== "") {
+      return fromId;
+    }
   }
   const tag = (displayTagName(node.tagName) || "div").toLowerCase();
-  return tag.includes("-") ? tag : `jx-${tag}`;
+  return tag.includes("-") ? tag : deriveTagName(tag);
 }
 
 /**
@@ -164,30 +206,18 @@ function extractComponentDef(node: JxMutableNode) {
 }
 
 /**
- * Validate a component name against naming rules and existing registry.
- *
- * @param {string} val
- * @returns {{ valid: boolean; error: string }}
+ * The refusal a component name earns, or `""`: HTML's valid custom element name, then uniqueness
+ * against the registry.
  */
-function validateName(val: string) {
+function validateName(val: string): string {
   const name = val.trim().toLowerCase();
-  if (!name.includes("-")) {
-    return {
-      error: "Name must contain a hyphen (e.g. my-component)",
-      valid: false,
-    };
-  }
-  if (!VALID_NAME.test(name)) {
-    return {
-      error: "Lowercase letters, digits, and hyphens only",
-      valid: false,
-    };
-  }
-  const exists = componentRegistry.some((c) => c.tagName === name);
-  if (exists) {
-    return { error: `Component <${name}> already exists`, valid: false };
+  const problem = customElementNameProblem(name);
+  if (problem !== "") {
+    return problem;
   }
-  return { error: "", valid: true };
+  return componentRegistry.some((c) => c.tagName === name)
+    ? `Component <${name}> already exists`
+    : "";
 }
 
 /**
@@ -206,7 +236,7 @@ function promptComponentName(defaultName: string): Promise<string | null> {
     confirmLabel: "Convert",
     message: "Enter a hyphenated tag name for the new component.",
     placeholder: "my-component",
-    validate: (value) => validateName(value).error,
+    validate: validateName,
     value: defaultName,
   });
 }

package/src/editor/convert-to-repeater.ts

@@ -12,7 +12,9 @@
  *
  * @docs studio/design/repeaters
  */
-import { childIndex, childList, getNodeAtPath, parentElementPath } from "../store";
+import { getNodeAtPath } from "@jxsuite/schema/doc-ops";
+import { isJsonObject, isPrototypeDef } from "@jxsuite/schema/guards";
+import { childIndex, childList, parentElementPath } from "../store";
 import { primarySelection } from "../tabs/selection";
 import { activeTab } from "../workspace/workspace";
 import { transactDoc } from "../tabs/transact";
@@ -22,15 +24,18 @@ import { fetchPluginSchema } from "../services/code-services";
 import { CREATE_NEW_SOURCE, openConvertRepeaterSurface } from "../surfaces/convert-repeater";
 
 import type { ConvertRepeaterView } from "../surfaces/convert-repeater";
-import type { JxMutableNode } from "@jxsuite/schema/types";
+import type { JxMutableNode, JxRef, JxStateDefinition } from "@jxsuite/schema/types";
 
 /** What a name has to look like to become a state definition. */
 const IDENTIFIER = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/;
 
+/** A document's state definitions, by name. */
+type StateDefs = Readonly<Record<string, JxStateDefinition>>;
+
 interface RepeaterConfig {
-  items: { $ref: string } | unknown[];
-  filter?: { $ref: string };
-  sort?: { $ref: string };
+  items: JxRef;
+  filter?: JxRef;
+  sort?: JxRef;
   newDef?: { name: string };
 }
 
@@ -65,14 +70,18 @@ export async function convertToRepeater() {
     if (!pp) {
       return;
     }
+    /* SAFETY: the command is enabled only when every selected path is spliceable
+       (`structurallyEditable` in commands/defaults.ts), so `path` ends in `"children", <index>`. */
     const idx = childIndex(path) as number;
     const parent = getNodeAtPath(doc, pp);
     if (!parent?.children) {
       return;
     }
-    const element = childList(parent)[idx];
+    /* SAFETY: a selection addresses an element node (the canvas selects elements, and an outline
+       text row is not a selectable item), and this reads the selected slot of its parent. */
+    const element = childList(parent)[idx] as JxMutableNode;
 
-    const repeater: Record<string, unknown> = {
+    const repeater: JxMutableNode = {
       $prototype: "Array",
       items: config.items,
       map: element,
@@ -84,9 +93,11 @@ export async function convertToRepeater() {
       repeater.sort = config.sort;
     }
 
-    // Replace the selected element in place with the array pseudo-element — no wrapper div. The
-    // Repeated items render directly among the original parent's children.
-    (parent.children as (string | JxMutableNode)[])[idx] = repeater as unknown as JxMutableNode;
+    /* Replace the selected element in place with the array pseudo-element — no wrapper div. The
+       repeated items render directly among the original parent's children.
+       SAFETY: a document is normalized to the member form when it loads into a tab
+       (`normalizeArrayChildren`), so a present `children` is an array, never a bare repeater. */
+    (parent.children as (string | JxMutableNode)[])[idx] = repeater;
   });
 }
 
@@ -98,18 +109,19 @@ export async function convertToRepeater() {
  * returns in its schema — so it is asked for once per definition, and only for the ones the first
  * three did not already claim.
  */
-async function arraySourceNames(defs: Record<string, unknown>): Promise<string[]> {
+async function arraySourceNames(defs: StateDefs): Promise<string[]> {
   const named = Object.entries(defs)
-    .filter(([, d]) => {
-      const def = d as Record<string, unknown> | null;
-      return def?.type === "array" || Array.isArray(def?.default) || def?.$prototype === "Array";
-    })
+    .filter(
+      ([, def]) =>
+        isJsonObject(def) &&
+        (def.type === "array" || Array.isArray(def.default) || def.$prototype === "Array"),
+    )
     .map(([name]) => name);
 
   const docPath = activeTab.value?.documentPath;
-  for (const [name, d] of Object.entries(defs)) {
-    const def = d as Record<string, unknown> | null;
-    if (!def?.$prototype || def.$prototype === "Function" || def.$prototype === "Array") {
+  for (const [name, def] of Object.entries(defs)) {
+    // Only a named, non-Function, non-Array prototype can be a plugin whose schema says it returns one.
+    if (!isPrototypeDef(def) || !def.$prototype || def.$prototype === "Array") {
       continue;
     }
     if (named.includes(name)) {
@@ -117,8 +129,8 @@ async function arraySourceNames(defs: Record<string, unknown>): Promise<string[]
     }
     const schema = await fetchPluginSchema(
       {
-        ...(def.$src != null && { $src: def.$src as string }),
-        $prototype: def.$prototype as string,
+        ...(def.$src != null && { $src: def.$src }),
+        $prototype: def.$prototype,
       },
       { ...(docPath != null && { documentPath: docPath }) },
     );
@@ -136,10 +148,10 @@ async function arraySourceNames(defs: Record<string, unknown>): Promise<string[]
  * name keeps the dialog open with the reason under the field — the flow's state machine, which is
  * the half the surface deliberately does not have.
  *
- * @param {Record<string, unknown>} defs
+ * @param {StateDefs} defs
  * @returns {Promise<RepeaterConfig | null>}
  */
-async function promptRepeaterConfig(defs: Record<string, unknown>): Promise<RepeaterConfig | null> {
+async function promptRepeaterConfig(defs: StateDefs): Promise<RepeaterConfig | null> {
   const sources = await arraySourceNames(defs);
   const functions = Object.entries(defs)
     .filter(([, d]) => defCategory(d) === "function")

package/src/editor/editable-tags.ts

@@ -21,11 +21,26 @@
  */
 
 import elementsMeta from "../../data/elements-meta.json";
+import type { InlineAction } from "./inline-edit";
 
-interface ElementDef {
+/** The fields of one `elements-meta.json` `$defs` entry the editor reads. */
+export interface ElementMeta {
+  /** Tags this element accepts as inline children; containers declare `[]`. */
   $inlineChildren?: string[];
+  /** The formatting verbs the block action bar offers, or the tag whose list this one shares. */
+  $inlineActions?: InlineAction[] | string;
+  /** The `$convertGroups` group this element converts within. */
+  $convertTo?: string;
+  /** The groups offered instead of `$convertTo` while the element is empty. */
+  $convertToWhenEmpty?: string[];
 }
 
+/**
+ * The studio's element metadata by tag. The JSON is bundled with the studio, so the compiler checks
+ * every entry against {@link ElementMeta} here, once, instead of each reader asserting it.
+ */
+export const ELEMENT_DEFS: Readonly<Record<string, ElementMeta>> = elementsMeta.$defs;
+
 /**
  * Tags the studio's own metadata says accept inline children.
  *
@@ -36,7 +51,7 @@ interface ElementDef {
 const EXCLUDED = new Set(["pre"]);
 
 export const BUILTIN_EDITABLE_TAGS: ReadonlySet<string> = new Set(
-  Object.entries(elementsMeta.$defs as Record<string, ElementDef>)
+  Object.entries(ELEMENT_DEFS)
     .filter(([tag, def]) => !EXCLUDED.has(tag) && (def.$inlineChildren?.length ?? 0) > 0)
     .map(([tag]) => tag),
 );

package/src/editor/file-drop-action.ts

@@ -22,6 +22,8 @@ import { componentRegistry } from "../files/components";
 import { uploadAssets } from "../files/media-upload";
 import { applyDropInstruction } from "../panels/dnd";
 import { mutateUpdateAttribute, mutateUpdateProp, transactDoc } from "../tabs/transact";
+import { isNumber } from "@jxsuite/schema/guards";
+import type { ComponentEntry } from "../files/components";
 import type { UploadedAsset } from "../files/media-upload";
 import type { DropPreview, FileDropHit } from "../canvas/iframe-protocol";
 import type { JxPath } from "../state";
@@ -30,12 +32,12 @@ import type { JxMutableNode } from "@jxsuite/schema/types";
 import { isMediaFormat } from "../utils/studio-utils";
 
 /** Where an asset's URL goes when it replaces an existing element's picture. */
-const REPLACE_ATTRS: Record<string, "src" | "poster"> = {
-  img: "src",
-  source: "src",
+const REPLACE_ATTRS = new Map<string, "src" | "poster">([
+  ["img", "src"],
+  ["source", "src"],
   // A <video>'s own `src` is the movie; dropping an image on one sets its poster frame instead.
-  video: "poster",
-};
+  ["video", "poster"],
+]);
 
 /** What a drop resolves to once the parent has applied its semantics. */
 export type FileDropTarget =
@@ -43,11 +45,8 @@ export type FileDropTarget =
   | { mode: "replace-prop"; path: JxPath; prop: string }
   | { mode: "insert" };
 
-/** A component prop the registry declares as an image, for {@link resolveFileDropTarget}. */
-interface RegistryEntry {
-  tagName: string;
-  props?: { name: string; format?: unknown; [k: string]: unknown }[];
-}
+/** The part of a registry entry {@link resolveFileDropTarget} reads: its tag and declared props. */
+type RegistryEntry = Pick<ComponentEntry, "tagName" | "props">;
 
 /**
  * Decide whether a drop replaces an existing picture or inserts a new element.
@@ -66,15 +65,15 @@ export function resolveFileDropTarget(
   if (!hit || kind !== "image") {
     return { mode: "insert" };
   }
-  const attr = REPLACE_ATTRS[hit.tagName];
+  const attr = REPLACE_ATTRS.get(hit.tagName);
   if (attr) {
-    return { attr, mode: "replace-attr", path: hit.path as JxPath };
+    return { attr, mode: "replace-attr", path: hit.path };
   }
   if (hit.tagName.includes("-")) {
     const entry = registry.find((c) => c.tagName === hit.tagName);
     const imageProps = (entry?.props ?? []).filter((p) => isMediaFormat(p.format));
     if (imageProps.length === 1) {
-      return { mode: "replace-prop", path: hit.path as JxPath, prop: imageProps[0]!.name };
+      return { mode: "replace-prop", path: hit.path, prop: imageProps[0]!.name };
     }
   }
   return { mode: "insert" };
@@ -84,24 +83,32 @@ export function resolveFileDropTarget(
  * The node an uploaded asset becomes when inserted. Images get a plain `<img>` (the build's
  * optimizer picks it up); playable media gets native controls so it is usable straight away;
  * anything else becomes a download link, which is the only sensible generic rendering.
+ *
+ * **An image arrives with no `alt` at all, never an empty one.** `alt=""` is a claim (the image is
+ * decorative, and a screen reader skips it), and a drop cannot know it: stamping it made every
+ * dropped picture invisible to assistive technology and silenced the accessibility report's
+ * `img-alt-missing`, the one check that would have asked. Leaving it out is what gets the image
+ * flagged, and the drop selects the new element (`applyDropInstruction`), so the Inspector is
+ * already on the field the author has to fill. Neither is the file name a description: `IMG_0412`
+ * read aloud is noise, not an alternative.
  */
 export function elementForAsset(asset: UploadedAsset): JxMutableNode {
   switch (asset.kind) {
     case "image": {
-      return { attributes: { alt: "", src: asset.ref }, tagName: "img" } as JxMutableNode;
+      return { attributes: { src: asset.ref }, tagName: "img" };
     }
     case "video": {
-      return { attributes: { controls: "", src: asset.ref }, tagName: "video" } as JxMutableNode;
+      return { attributes: { controls: "", src: asset.ref }, tagName: "video" };
     }
     case "audio": {
-      return { attributes: { controls: "", src: asset.ref }, tagName: "audio" } as JxMutableNode;
+      return { attributes: { controls: "", src: asset.ref }, tagName: "audio" };
     }
     default: {
       return {
         attributes: { href: asset.ref },
         tagName: "a",
         textContent: asset.name,
-      } as JxMutableNode;
+      };
     }
   }
 }
@@ -114,13 +121,13 @@ export function elementForAsset(asset: UploadedAsset): JxMutableNode {
  * they were dropped. `make-child` appends, which is already ordered.
  */
 export function nthDropPath(preview: DropPreview, n: number): JxPath {
-  const path = [...preview.targetPath];
+  const path: JxPath = [...preview.targetPath];
   const tail = path.at(-1);
-  if (n === 0 || typeof tail !== "number") {
-    return path as JxPath;
+  if (n === 0 || !isNumber(tail)) {
+    return path;
   }
   path[path.length - 1] = tail + n;
-  return path as JxPath;
+  return path;
 }
 
 /**
@@ -160,7 +167,7 @@ export async function applyFileDrop(
     if (preview) {
       applyDropInstruction(tab, { type: preview.instruction }, srcData, nthDropPath(preview, i));
     } else {
-      applyDropInstruction(tab, { type: "make-child" }, srcData, [] as unknown as JxPath);
+      applyDropInstruction(tab, { type: "make-child" }, srcData, []);
     }
   }
 }