@jxsuite/studio 6.1.2 → 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/convert-to-component.ts

@@ -12,8 +12,11 @@
  * 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
  */
@@ -31,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);
@@ -107,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
@@ -130,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);
 }
 
 /**
@@ -170,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`
+    : "";
 }
 
 /**
@@ -212,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/file-drop-action.ts

@@ -83,11 +83,19 @@ 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" };
+      return { attributes: { src: asset.ref }, tagName: "img" };
     }
     case "video": {
       return { attributes: { controls: "", src: asset.ref }, tagName: "video" };

package/src/editor/inline-edit-apply.ts

@@ -20,6 +20,7 @@ import {
   transactDoc,
 } from "../tabs/transact";
 import { defaultDef } from "../panels/shared";
+import { componentInstance, mutateImportComponent } from "./insert-component";
 
 import { contentLength, contentOf, spliceAcross, toStored } from "./content-slice";
 import type { JxContentResult, SlashCommand } from "./inline-edit";
@@ -276,6 +277,45 @@ export function applyInlineSplit(
   return newPath;
 }
 
+/**
+ * A slash pick from the Components group (§5.7): the empty block the "/" was typed in is REPLACED
+ * by an instance of the component, and a block with content keeps it and gets the instance after
+ * it. Either way the component is imported, as a drop of the same component would import it. An
+ * instance is a whole element with its own `$props` and slot content, so swapping a tag in place —
+ * what an HTML pick does — would leave a paragraph's leftovers inside a component.
+ */
+function insertComponentBlock(
+  tab: Tab | null,
+  path: JxPath,
+  instance: JxMutableNode,
+  commitData: JxContentResult | undefined,
+): JxPath {
+  const { parentPath, index: idx } = blockSlot(path);
+  const replace = isEmptyContent(commitData);
+  const at = replace ? idx : idx + 1;
+  const newPath = [...parentPath, "children", at];
+  if (!tab) {
+    return newPath;
+  }
+  transactDoc(tab, (t) => {
+    if (replace) {
+      mutateRemoveNode(t, path);
+    } else if (commitData?.children) {
+      mutateUpdateProperty(t, path, "textContent");
+      mutateUpdateProperty(t, path, "children", commitData.children);
+    } else if (commitData?.textContent != null) {
+      mutateUpdateProperty(t, path, "children");
+      mutateUpdateProperty(t, path, "textContent", commitData.textContent);
+    }
+    mutateInsertNode(t, parentPath, at, instance);
+    mutateImportComponent(t, instance.tagName);
+    if (isTabActive(tab)) {
+      t.session.selection = [newPath];
+    }
+  });
+  return newPath;
+}
+
 /**
  * Apply a slash-insert at `path` of `tab`'s document: swap the (empty) node's tag in place, or
  * commit pending content and insert a new element after it. Returns the path to edit next (the
@@ -287,6 +327,10 @@ export function applyInlineInsert(
   cmd: SlashCommand,
   commitData: JxContentResult | undefined,
 ): JxPath {
+  const instance = cmd.component === true ? componentInstance(cmd.tag) : null;
+  if (instance) {
+    return insertComponentBlock(tab, path, instance, commitData);
+  }
   if (isEmptyContent(commitData)) {
     if (!tab) {
       return path;

package/src/editor/inline-edit.ts

@@ -81,6 +81,16 @@ export interface SlashCommand {
   label: string;
   tag: string;
   description: string;
+  /**
+   * The heading the offer is listed under. Absent for the HTML elements, which are the menu's
+   * first, unheaded group; `"Components"` for the project's components (§5.7).
+   */
+  group?: string;
+  /**
+   * Whether `tag` names a project component: the pick inserts `buildComponentInstance` and imports
+   * the component (`editor/insert-component.ts`) rather than an element's default definition.
+   */
+  component?: boolean;
 }
 
 export interface JxContentResult {

package/src/editor/insert-component.ts

@@ -0,0 +1,91 @@
+/**
+ * Inserting a component has one meaning everywhere (`specs/studio.md` §5.7, §9.1.3).
+ *
+ * A component instance is only a usable element in a document that imports it: the canvas drop did
+ * that, and the Insert panel's click, the slash menu and the canvas `+` did not, so a component
+ * clicked in rendered as an element the page could not resolve. This module is the one rule the
+ * four doors share — the instance comes from `buildComponentInstance`, and the import from the one
+ * `$elements` service, `files/elements.ts`'s `enableElement`.
+ *
+ * @docs studio/design/components
+ */
+
+import { isString } from "@jxsuite/schema/guards";
+import { buildComponentInstance, componentRegistry } from "../files/components";
+import { enableElement } from "../files/elements";
+import { mutateUpdateProperty } from "../tabs/transact";
+import type { JxNodeValue } from "../tabs/transact";
+import type { ElementsEntry } from "../files/elements";
+import type { JxMutableNode } from "@jxsuite/schema/types";
+import type { Tab } from "../tabs/tab";
+import type { SlashCommand } from "./inline-edit";
+
+/** The slash menu's group heading for the project's components. */
+export const COMPONENTS_GROUP = "Components";
+
+/**
+ * Import the component a node is an instance of into `tab`'s document, when it is one and is not
+ * imported yet. A node whose tag has no hyphen is an HTML element and is left alone, and a
+ * component the registry cannot name (an npm entry with no package, a local one with no path)
+ * changes nothing, so a document that had no `$elements` is not handed an empty one.
+ *
+ * A computed tag (`{ $expression }`) names no registered component, so it is left alone too.
+ *
+ * This is a MUTATION: call it inside the transaction that inserts the instance, so the instance and
+ * its import are one undo step. As a transaction of its own after the insert, the first ⌘Z took
+ * back only the import and left a document using a component it no longer imported, which saves as
+ * an instance the page cannot resolve.
+ *
+ * @param tab The document the node was inserted into, inside a `transactDoc`.
+ * @param tagName The inserted node's tag.
+ */
+export function mutateImportComponent(tab: Tab, tagName: JxMutableNode["tagName"]): void {
+  const after = elementsImporting(tab, tagName);
+  if (after) {
+    /* Through the recorded mutator, not a bare assignment: a transaction that records ops is
+       undone by replaying their inverses, so an unrecorded write beside the insert would survive
+       the ⌘Z that took the instance back, and never reach a co-editor.
+       SAFETY: `$elements` entries are JSON — module specifiers, `{ $ref }` imports and inline
+       element definitions — which is what a node key holds. */
+    mutateUpdateProperty(tab, [], "$elements", after as JxNodeValue);
+  }
+}
+
+/** The document's `$elements` with the component imported, or null when nothing would change. */
+function elementsImporting(tab: Tab, tagName: JxMutableNode["tagName"]): ElementsEntry[] | null {
+  if (!isString(tagName) || !tagName.includes("-")) {
+    return null;
+  }
+  const comp = componentRegistry.find((entry) => entry.tagName === tagName);
+  if (!comp) {
+    return null;
+  }
+  /* SAFETY: `$elements` holds module specifiers and `{ $ref }` imports; the document type and
+     files/elements.ts spell an inline entry as JxMutableNode and JxElement respectively, two editor
+     views of the same JSON object that enableElement only compares by `$ref`. */
+  const before = (tab.doc.document.$elements ?? []) as ElementsEntry[];
+  const after = enableElement(before, comp, tab.documentPath ?? null);
+  return after.length === before.length ? null : after;
+}
+
+/** A fresh instance of a registered component, or null for a tag the registry does not know. */
+export function componentInstance(tagName: string): JxMutableNode | null {
+  const comp = componentRegistry.find((entry) => entry.tagName === tagName);
+  return comp ? buildComponentInstance(comp) : null;
+}
+
+/**
+ * Every registered component as a slash-menu offer, under the Components heading: the project's
+ * own, described by their definition file, and the ones installed packages provide, described by
+ * their package. A package component needs no prior enabling, because inserting one imports its
+ * package ({@link mutateImportComponent}), exactly as the canvas drop does.
+ */
+export function componentSlashCommands(): SlashCommand[] {
+  return componentRegistry.map((comp) => ({
+    component: true,
+    description: (comp.source === "npm" ? comp.package : comp.path) ?? "",
+    group: COMPONENTS_GROUP,
+    label: `<${comp.tagName}>`,
+    tag: comp.tagName,
+  }));
+}

package/src/editor/insert-zone-action.ts

@@ -7,11 +7,13 @@
  * name via `setInsertZoneClickHandler(runInsertZoneAction)` in studio.ts.
  *
  * The cross-origin insertion "+" (drawn by the host from posted zones) runs the parent-realm
- * slash-menu → mutateInsertNode flow on click. The host captured the zone (parentPath + index); the
- * new node is selected at its inserted path. Salvaged from the orphaned insertion-helper.ts.
+ * slash-menu → mutateInsertNode flow on click. The menu offers the HTML elements and, under a
+ * Components heading, the project's components. The host captured the zone (parentPath + index);
+ * the new node is selected at its inserted path. Salvaged from the orphaned insertion-helper.ts.
  */
 
 import { showSlashMenu } from "./slash-menu";
+import { componentInstance, mutateImportComponent } from "./insert-component";
 import { defaultDef } from "../panels/shared";
 import { mutateInsertNode, transactDoc } from "../tabs/transact";
 import { activeTab } from "../workspace/workspace";
@@ -21,12 +23,19 @@ import type { JxPath } from "../state";
 export function runInsertZoneAction(btn: HTMLElement, zone: InsertZone): void {
   showSlashMenu(btn, "", {
     onSelect: (cmd) => {
-      const def = defaultDef(cmd.tag);
+      /* A pick from the Components group inserts an instance and imports the component, as a drop
+         of the same component does (§5.7); every other pick inserts the element's default. */
+      const instance = cmd.component === true ? componentInstance(cmd.tag) : null;
+      const def = instance ?? defaultDef(cmd.tag);
       const insertPath: JxPath = zone.insertParentPath;
       const idx = zone.index;
       const newPath = [...insertPath, "children", idx];
-      transactDoc(activeTab.value, (t) => {
+      const tab = activeTab.value;
+      transactDoc(tab, (t) => {
         mutateInsertNode(t, insertPath, idx, def);
+        if (instance) {
+          mutateImportComponent(t, instance.tagName);
+        }
         t.session.selection = [newPath];
       });
     },