@jxsuite/studio 0.19.0 → 0.20.0

package/src/panels/head-panel.js

@@ -27,6 +27,15 @@ import { isGoogleFontEntry, isGoogleFontPreconnect } from "../utils/google-fonts
  * }} MetaField
  */
 
+/**
+ * @typedef {{
+ *   type?: string;
+ *   enum?: string[];
+ *   format?: string;
+ *   properties?: Record<string, unknown>;
+ * }} FmSchemaEntry
+ */
+
 /** @type {MetaField[]} */
 const PAGE_FIELDS = [
   { label: "Description", attr: "name", key: "description" },
@@ -44,48 +53,53 @@ const OG_FIELDS = [
 /** Set of `name`/`property` values managed by the structured forms. */
 const MANAGED_META_KEYS = new Set([...PAGE_FIELDS, ...OG_FIELDS].map((f) => f.key));
 
+/** Frontmatter keys managed by the PAGE dedicated controls (others live inside $head). */
+const RESERVED_FM_KEYS = new Set(["title"]);
+
 // ─── Helpers ─────────────────────────────────────────────────────────────
 
 /**
  * Find a `$head` meta entry by attribute match.
  *
- * @param {any[]} head
+ * @param {JxHeadEntry[]} head
  * @param {"name" | "property"} attr
  * @param {string} key
- * @returns {any | undefined}
+ * @returns {JxHeadEntry | undefined}
  */
 function findMetaEntry(head, attr, key) {
   if (!head) return undefined;
   return head.find(
-    (/** @type {any} */ e) => e?.tagName === "meta" && e?.attributes?.[attr] === key,
+    (/** @type {JxHeadEntry} */ e) => e?.tagName === "meta" && e?.attributes?.[attr] === key,
   );
 }
 
 /**
  * Find a `$head` link entry by `rel` attribute.
  *
- * @param {any[]} head
+ * @param {JxHeadEntry[]} head
  * @param {string} rel
- * @returns {any | undefined}
+ * @returns {JxHeadEntry | undefined}
  */
 function findLinkEntry(head, rel) {
   if (!head) return undefined;
-  return head.find((/** @type {any} */ e) => e?.tagName === "link" && e?.attributes?.rel === rel);
+  return head.find(
+    (/** @type {JxHeadEntry} */ e) => e?.tagName === "link" && e?.attributes?.rel === rel,
+  );
 }
 
 /**
  * Check if a `$head` entry is managed by the structured forms.
  *
- * @param {any} entry
+ * @param {JxHeadEntry} entry
  * @returns {boolean}
  */
 function isManagedEntry(entry) {
   if (!entry?.tagName) return false;
   // Managed meta tags
   if (entry.tagName === "meta") {
-    const name = entry?.attributes?.name;
-    const prop = entry?.attributes?.property;
-    return (name && MANAGED_META_KEYS.has(name)) || (prop && MANAGED_META_KEYS.has(prop));
+    const name = String(entry?.attributes?.name ?? "");
+    const prop = String(entry?.attributes?.property ?? "");
+    return !!(name && MANAGED_META_KEYS.has(name)) || !!(prop && MANAGED_META_KEYS.has(prop));
   }
   // Managed link: favicon
   if (entry.tagName === "link" && entry?.attributes?.rel === "icon") return true;
@@ -95,7 +109,7 @@ function isManagedEntry(entry) {
 /**
  * Upsert or remove a meta entry in `doc.$head`.
  *
- * @param {any} doc
+ * @param {JxMutableNode} doc
  * @param {"name" | "property"} attr
  * @param {string} key
  * @param {string} content
@@ -103,7 +117,7 @@ function isManagedEntry(entry) {
 function upsertMeta(doc, attr, key, content) {
   if (!doc.$head) doc.$head = [];
   const idx = doc.$head.findIndex(
-    (/** @type {any} */ e) => e?.tagName === "meta" && e?.attributes?.[attr] === key,
+    (/** @type {JxHeadEntry} */ e) => e?.tagName === "meta" && e?.attributes?.[attr] === key,
   );
   if (content) {
     const entry = { tagName: "meta", attributes: { [attr]: key, content } };
@@ -120,14 +134,14 @@ function upsertMeta(doc, attr, key, content) {
 /**
  * Upsert or remove a link entry in `doc.$head`.
  *
- * @param {any} doc
+ * @param {JxMutableNode} doc
  * @param {string} rel
  * @param {string} href
  */
 function upsertLink(doc, rel, href) {
   if (!doc.$head) doc.$head = [];
   const idx = doc.$head.findIndex(
-    (/** @type {any} */ e) => e?.tagName === "link" && e?.attributes?.rel === rel,
+    (/** @type {JxHeadEntry} */ e) => e?.tagName === "link" && e?.attributes?.rel === rel,
   );
   if (href) {
     const entry = { tagName: "link", attributes: { rel, href } };
@@ -144,29 +158,29 @@ function upsertLink(doc, rel, href) {
 /**
  * Get a display label for an arbitrary $head entry.
  *
- * @param {any} entry
+ * @param {JxHeadEntry} entry
  * @returns {string}
  */
 function entryLabel(entry) {
   if (!entry?.tagName) return "unknown";
   const a = entry.attributes ?? {};
-  if (a.name) return `<meta name="${a.name}">`;
-  if (a.property) return `<meta property="${a.property}">`;
-  if (a.rel && a.href) return `<link rel="${a.rel}">`;
-  if (a.src) return `<script src="${a.src}">`;
-  if (a.charset) return `<meta charset="${a.charset}">`;
+  if (a.name) return `<meta name="${String(a.name)}">`;
+  if (a.property) return `<meta property="${String(a.property)}">`;
+  if (a.rel && a.href) return `<link rel="${String(a.rel)}">`;
+  if (a.src) return `<script src="${String(a.src)}">`;
+  if (a.charset) return `<meta charset="${String(a.charset)}">`;
   return `<${entry.tagName}>`;
 }
 
 /**
  * Get a display value for an arbitrary $head entry.
  *
- * @param {any} entry
+ * @param {JxHeadEntry} entry
  * @returns {string}
  */
 function entryValue(entry) {
   const a = entry?.attributes ?? {};
-  return a.content ?? a.href ?? a.src ?? entry?.textContent ?? "";
+  return String(a.content ?? a.href ?? a.src ?? entry?.textContent ?? "");
 }
 
 // ─── Field renderers ─────────────────────────────────────────────────────
@@ -175,13 +189,13 @@ function entryValue(entry) {
  * Render a meta field row using renderFieldRow.
  *
  * @param {MetaField} field
- * @param {any[]} head
- * @param {(fn: (doc: any) => void) => void} applyMutation
- * @returns {any}
+ * @param {JxHeadEntry[]} head
+ * @param {(fn: (doc: JxMutableNode) => void) => void} applyMutation
+ * @returns {import("lit-html").TemplateResult}
  */
 function renderMetaFieldRow(field, head, applyMutation) {
   const entry = findMetaEntry(head, field.attr, field.key);
-  const val = entry?.attributes?.content ?? "";
+  const val = String(entry?.attributes?.content ?? "");
 
   if (field.media) {
     return renderFieldRow({
@@ -189,9 +203,11 @@ function renderMetaFieldRow(field, head, applyMutation) {
       label: field.label,
       hasValue: !!val,
       onClear: () =>
-        applyMutation((/** @type {any} */ d) => upsertMeta(d, field.attr, field.key, "")),
-      widget: renderMediaPicker(field.key, val, (/** @type {any} */ v) => {
-        applyMutation((/** @type {any} */ d) => upsertMeta(d, field.attr, field.key, v || ""));
+        applyMutation((/** @type {JxMutableNode} */ d) => upsertMeta(d, field.attr, field.key, "")),
+      widget: renderMediaPicker(field.key, val, (/** @type {string} */ v) => {
+        applyMutation((/** @type {JxMutableNode} */ d) =>
+          upsertMeta(d, field.attr, field.key, v || ""),
+        );
       }),
     });
   }
@@ -203,9 +219,11 @@ function renderMetaFieldRow(field, head, applyMutation) {
           multiline
           .value=${live(val)}
           placeholder="${field.label}…"
-          @input=${debouncedStyleCommit(`head:${field.key}`, 400, (/** @type {any} */ e) => {
-            const content = e.target.value?.trim() ?? "";
-            applyMutation((/** @type {any} */ d) => upsertMeta(d, field.attr, field.key, content));
+          @input=${debouncedStyleCommit(`head:${field.key}`, 400, (/** @type {Event} */ e) => {
+            const content = /** @type {HTMLInputElement} */ (e.target).value?.trim() ?? "";
+            applyMutation((/** @type {JxMutableNode} */ d) =>
+              upsertMeta(d, field.attr, field.key, content),
+            );
           })}
         ></sp-textfield>
       `
@@ -216,9 +234,11 @@ function renderMetaFieldRow(field, head, applyMutation) {
           placeholder=${field.key === "viewport"
             ? "width=device-width, initial-scale=1"
             : `${field.label}…`}
-          @input=${debouncedStyleCommit(`head:${field.key}`, 400, (/** @type {any} */ e) => {
-            const content = e.target.value?.trim() ?? "";
-            applyMutation((/** @type {any} */ d) => upsertMeta(d, field.attr, field.key, content));
+          @input=${debouncedStyleCommit(`head:${field.key}`, 400, (/** @type {Event} */ e) => {
+            const content = /** @type {HTMLInputElement} */ (e.target).value?.trim() ?? "";
+            applyMutation((/** @type {JxMutableNode} */ d) =>
+              upsertMeta(d, field.attr, field.key, content),
+            );
           })}
         ></sp-textfield>
       `;
@@ -228,7 +248,7 @@ function renderMetaFieldRow(field, head, applyMutation) {
     label: field.label,
     hasValue: !!val,
     onClear: () =>
-      applyMutation((/** @type {any} */ d) => upsertMeta(d, field.attr, field.key, "")),
+      applyMutation((/** @type {JxMutableNode} */ d) => upsertMeta(d, field.attr, field.key, "")),
     widget,
   });
 }
@@ -237,11 +257,11 @@ function renderMetaFieldRow(field, head, applyMutation) {
 
 /**
  * @param {{
- *   document: any;
- *   applyMutation: (fn: (doc: any) => void) => void;
+ *   document: JxMutableNode;
+ *   applyMutation: (fn: (doc: JxMutableNode) => void) => void;
  *   renderLeftPanel: () => void;
  * }} ctx
- * @returns {any}
+ * @returns {import("lit-html").TemplateResult}
  */
 export function renderHeadTemplate({ document: doc, applyMutation, renderLeftPanel }) {
   const head = doc.$head ?? [];
@@ -249,11 +269,11 @@ export function renderHeadTemplate({ document: doc, applyMutation, renderLeftPan
 
   // Icon (favicon) link
   const iconEntry = findLinkEntry(head, "icon");
-  const iconHref = iconEntry?.attributes?.href ?? "";
+  const iconHref = String(iconEntry?.attributes?.href ?? "");
 
   // Custom entries not managed by structured forms, fonts, or preconnects
   const customEntries = head.filter(
-    (/** @type {any} */ e) =>
+    (/** @type {JxHeadEntry} */ e) =>
       !isManagedEntry(e) && !isGoogleFontEntry(e) && !isGoogleFontPreconnect(e),
   );
 
@@ -277,7 +297,7 @@ export function renderHeadTemplate({ document: doc, applyMutation, renderLeftPan
             label: "Title",
             hasValue: !!title,
             onClear: () =>
-              applyMutation((/** @type {any} */ d) => {
+              applyMutation((/** @type {JxMutableNode} */ d) => {
                 delete d.title;
               }),
             widget: html`
@@ -285,9 +305,9 @@ export function renderHeadTemplate({ document: doc, applyMutation, renderLeftPan
                 size="s"
                 .value=${live(title)}
                 placeholder="Page title…"
-                @input=${debouncedStyleCommit("head:title", 400, (/** @type {any} */ e) => {
-                  const val = e.target.value?.trim() ?? "";
-                  applyMutation((/** @type {any} */ d) => {
+                @input=${debouncedStyleCommit("head:title", 400, (/** @type {Event} */ e) => {
+                  const val = /** @type {HTMLInputElement} */ (e.target).value?.trim() ?? "";
+                  applyMutation((/** @type {JxMutableNode} */ d) => {
                     if (val) d.title = val;
                     else delete d.title;
                   });
@@ -300,9 +320,10 @@ export function renderHeadTemplate({ document: doc, applyMutation, renderLeftPan
             prop: "icon",
             label: "Icon",
             hasValue: !!iconHref,
-            onClear: () => applyMutation((/** @type {any} */ d) => upsertLink(d, "icon", "")),
-            widget: renderMediaPicker("icon", iconHref, (/** @type {any} */ v) => {
-              applyMutation((/** @type {any} */ d) => upsertLink(d, "icon", v || ""));
+            onClear: () =>
+              applyMutation((/** @type {JxMutableNode} */ d) => upsertLink(d, "icon", "")),
+            widget: renderMediaPicker("icon", iconHref, (/** @type {string} */ v) => {
+              applyMutation((/** @type {JxMutableNode} */ d) => upsertLink(d, "icon", v || ""));
             }),
           })}
         </div>
@@ -327,7 +348,7 @@ export function renderHeadTemplate({ document: doc, applyMutation, renderLeftPan
         ${customEntries.length > 0
           ? html`
               <div class="imports-list">
-                ${customEntries.map((/** @type {any} */ entry) => {
+                ${customEntries.map((/** @type {JxHeadEntry} */ entry) => {
                   const label = entryLabel(entry);
                   const value = entryValue(entry);
                   return html`
@@ -339,7 +360,7 @@ export function renderHeadTemplate({ document: doc, applyMutation, renderLeftPan
                         size="xs"
                         title="Remove"
                         @click=${() => {
-                          applyMutation((/** @type {any} */ d) => {
+                          applyMutation((/** @type {JxMutableNode} */ d) => {
                             if (!d.$head) return;
                             const idx = d.$head.indexOf(entry);
                             if (idx >= 0) d.$head.splice(idx, 1);
@@ -373,19 +394,25 @@ export function renderHeadTemplate({ document: doc, applyMutation, renderLeftPan
             quiet
             size="xs"
             title="Add tag"
-            @click=${(/** @type {any} */ e) => {
-              const form = e.target.closest(".head-add-form");
-              const tagPicker = form?.querySelector(".head-add-tag");
-              const attrField = form?.querySelector(".head-add-attr");
-              const valField = form?.querySelector(".head-add-val");
+            @click=${(/** @type {Event} */ e) => {
+              const form = /** @type {HTMLElement} */ (e.target).closest(".head-add-form");
+              const tagPicker = /** @type {HTMLInputElement | null} */ (
+                form?.querySelector(".head-add-tag")
+              );
+              const attrField = /** @type {HTMLInputElement | null} */ (
+                form?.querySelector(".head-add-attr")
+              );
+              const valField = /** @type {HTMLInputElement | null} */ (
+                form?.querySelector(".head-add-val")
+              );
               const tagName = tagPicker?.value || "meta";
               const attrKey = attrField?.value?.trim();
               const attrVal = valField?.value?.trim();
               if (!attrKey || !attrVal) return;
-              attrField.value = "";
-              valField.value = "";
+              if (attrField) attrField.value = "";
+              if (valField) valField.value = "";
 
-              /** @type {Record<string, any>} */
+              /** @type {JxHeadEntry} */
               const entry = { tagName, attributes: {} };
               if (tagName === "meta") {
                 entry.attributes = { name: attrKey, content: attrVal };
@@ -395,7 +422,7 @@ export function renderHeadTemplate({ document: doc, applyMutation, renderLeftPan
                 entry.attributes = { [attrKey]: attrVal };
               }
 
-              applyMutation((/** @type {any} */ d) => {
+              applyMutation((/** @type {JxMutableNode} */ d) => {
                 if (!d.$head) d.$head = [];
                 d.$head.push(entry);
               });
@@ -421,29 +448,30 @@ function renderFrontmatterSection() {
   const schemaProps = col?.schema?.properties;
   const requiredFields = new Set(col?.schema?.required || []);
 
-  /** @type {{ field: string; entry: any; value: any }[]} */
+  /** @type {{ field: string; entry: FmSchemaEntry; value: JsonValue }[]} */
   const fields = [];
   if (schemaProps) {
     for (const [field, fieldSchema] of Object.entries(
-      /** @type {Record<string, any>} */ (schemaProps),
+      /** @type {Record<string, FmSchemaEntry>} */ (schemaProps),
     )) {
-      fields.push({ field, entry: fieldSchema, value: fm[field] });
+      if (RESERVED_FM_KEYS.has(field)) continue;
+      fields.push({ field, entry: fieldSchema, value: /** @type {JsonValue} */ (fm[field]) });
     }
     for (const [field, value] of Object.entries(fm)) {
-      if (schemaProps[field] || field.startsWith("$")) continue;
+      if (schemaProps[field] || field.startsWith("$") || RESERVED_FM_KEYS.has(field)) continue;
       fields.push({
         field,
         entry: { type: typeof value === "boolean" ? "boolean" : "string" },
-        value,
+        value: /** @type {JsonValue} */ (value),
       });
     }
   } else {
     for (const [field, value] of Object.entries(fm)) {
-      if (field.startsWith("$")) continue;
+      if (field.startsWith("$") || RESERVED_FM_KEYS.has(field)) continue;
       fields.push({
         field,
         entry: { type: typeof value === "boolean" ? "boolean" : "string" },
-        value,
+        value: /** @type {JsonValue} */ (value),
       });
     }
   }
@@ -466,8 +494,8 @@ function renderFrontmatterSection() {
 
 function renderFmField(
   /** @type {string} */ field,
-  /** @type {any} */ entry,
-  /** @type {any} */ value,
+  /** @type {FmSchemaEntry} */ entry,
+  /** @type {JsonValue} */ value,
   /** @type {Set<string>} */ requiredFields,
 ) {
   const isRequired = requiredFields.has(field);
@@ -487,9 +515,13 @@ function renderFmField(
         <sp-checkbox
           size="s"
           .checked=${live(!!value)}
-          @change=${(/** @type {any} */ e) =>
+          @change=${(/** @type {Event} */ e) =>
             transactDoc(activeTab.value, (t) =>
-              mutateUpdateFrontmatter(t, field, e.target.checked || undefined),
+              mutateUpdateFrontmatter(
+                t,
+                field,
+                /** @type {HTMLInputElement} */ (e.target).checked || undefined,
+              ),
             )}
         ></sp-checkbox>
       `,
@@ -508,9 +540,9 @@ function renderFmField(
           size="s"
           placeholder="comma, separated"
           .value=${live(display)}
-          @input=${debouncedStyleCommit(`fm:${field}`, 400, (/** @type {any} */ e) => {
-            const arr = e.target.value
-              ? e.target.value
+          @input=${debouncedStyleCommit(`fm:${field}`, 400, (/** @type {Event} */ e) => {
+            const arr = /** @type {HTMLInputElement} */ (e.target).value
+              ? /** @type {HTMLInputElement} */ (e.target).value
                   .split(",")
                   .map((/** @type {string} */ s) => s.trim())
                   .filter(Boolean)
@@ -532,9 +564,13 @@ function renderFmField(
         <sp-picker
           size="s"
           .value=${live(value || "")}
-          @change=${(/** @type {any} */ e) =>
+          @change=${(/** @type {Event} */ e) =>
             transactDoc(activeTab.value, (t) =>
-              mutateUpdateFrontmatter(t, field, e.target.value || undefined),
+              mutateUpdateFrontmatter(
+                t,
+                field,
+                /** @type {HTMLInputElement} */ (e.target).value || undefined,
+              ),
             )}
         >
           ${entry.enum.map(
@@ -551,7 +587,7 @@ function renderFmField(
       label: displayLabel,
       hasValue: hasVal,
       onClear,
-      widget: renderMediaPicker(field, value, (v) =>
+      widget: renderMediaPicker(field, /** @type {string} */ (value), (/** @type {string} */ v) =>
         transactDoc(activeTab.value, (t) => mutateUpdateFrontmatter(t, field, v || undefined)),
       ),
     });
@@ -568,10 +604,10 @@ function renderFmField(
           size="s"
           hide-stepper
           .value=${live(value !== undefined ? Number(value) : undefined)}
-          @change=${debouncedStyleCommit(`fm:${field}`, 400, (/** @type {any} */ e) => {
-            const v = e.target.value;
+          @change=${debouncedStyleCommit(`fm:${field}`, 400, (/** @type {Event} */ e) => {
+            const v = /** @type {HTMLInputElement} */ (e.target).value;
             transactDoc(activeTab.value, (t) =>
-              mutateUpdateFrontmatter(t, field, isNaN(v) ? undefined : Number(v)),
+              mutateUpdateFrontmatter(t, field, isNaN(Number(v)) ? undefined : Number(v)),
             );
           })}
         ></sp-number-field>
@@ -589,9 +625,13 @@ function renderFmField(
         size="s"
         placeholder=${entry.format === "date" ? "YYYY-MM-DD" : ""}
         .value=${live(value || "")}
-        @input=${debouncedStyleCommit(`fm:${field}`, 400, (/** @type {any} */ e) => {
+        @input=${debouncedStyleCommit(`fm:${field}`, 400, (/** @type {Event} */ e) => {
           transactDoc(activeTab.value, (t) =>
-            mutateUpdateFrontmatter(t, field, e.target.value || undefined),
+            mutateUpdateFrontmatter(
+              t,
+              field,
+              /** @type {HTMLInputElement} */ (e.target).value || undefined,
+            ),
           );
         })}
       ></sp-textfield>