@jxsuite/studio 0.19.0 → 0.21.0

package/src/settings/schema-field-ui.js

@@ -14,7 +14,7 @@ export const FORMAT_OPTIONS = ["", "image", "date", "color"];
  *   type?: string;
  *   properties?: Record<string, SchemaProperty>;
  *   required?: string[];
- *   items?: any;
+ *   items?: SchemaProperty;
  *   format?: string;
  *   $ref?: string;
  * }} SchemaProperty
@@ -70,7 +70,7 @@ export function detectFieldFormat(schema) {
  * @param {boolean} isRequired
  * @param {FieldHandlers} handlers
  * @param {string[]} [contentTypeNames] - Available content type names for reference target picker
- * @returns {any}
+ * @returns {import("lit-html").TemplateResult}
  */
 export function fieldCardTpl(fieldName, fieldSchema, isRequired, handlers, contentTypeNames = []) {
   const type = detectFieldType(fieldSchema);
@@ -89,16 +89,18 @@ export function fieldCardTpl(fieldName, fieldSchema, isRequired, handlers, conte
           quiet
           value=${fieldName}
           class="schema-field-name-input"
-          @change=${(/** @type {any} */ e) => {
-            const newName = e.target.value.trim();
+          @change=${(/** @type {Event} */ e) => {
+            const target = /** @type {HTMLInputElement} */ (e.target);
+            const newName = target.value.trim();
             if (newName && newName !== fieldName) handlers.onRename(fieldName, newName);
-            else e.target.value = fieldName;
+            else target.value = fieldName;
           }}
-          @keydown=${(/** @type {any} */ e) => {
-            if (e.key === "Enter") e.target.blur();
+          @keydown=${(/** @type {KeyboardEvent} */ e) => {
+            const target = /** @type {HTMLInputElement} */ (e.target);
+            if (e.key === "Enter") target.blur();
             if (e.key === "Escape") {
-              e.target.value = fieldName;
-              e.target.blur();
+              target.value = fieldName;
+              target.blur();
             }
           }}
         ></sp-textfield>
@@ -131,9 +133,12 @@ export function fieldCardTpl(fieldName, fieldSchema, isRequired, handlers, conte
                 size="s"
                 label="Target"
                 value=${refTarget}
-                @change=${(/** @type {any} */ e) => {
+                @change=${(/** @type {Event} */ e) => {
                   if (handlers.onChangeRefTarget)
-                    handlers.onChangeRefTarget(fieldName, e.target.value);
+                    handlers.onChangeRefTarget(
+                      fieldName,
+                      /** @type {HTMLInputElement} */ (e.target).value,
+                    );
                 }}
               >
                 ${contentTypeNames.map((n) => html`<sp-menu-item value=${n}>${n}</sp-menu-item>`)}
@@ -170,7 +175,7 @@ export function fieldCardTpl(fieldName, fieldSchema, isRequired, handlers, conte
  * @param {SchemaProperty} childSchema
  * @param {boolean} isRequired
  * @param {FieldHandlers} handlers
- * @returns {any}
+ * @returns {import("lit-html").TemplateResult}
  */
 function nestedFieldCardTpl(parentName, childName, childSchema, isRequired, handlers) {
   const type = detectFieldType(childSchema);
@@ -184,19 +189,21 @@ function nestedFieldCardTpl(parentName, childName, childSchema, isRequired, hand
           quiet
           value=${childName}
           class="schema-field-name-input"
-          @change=${(/** @type {any} */ e) => {
-            const newName = e.target.value.trim();
+          @change=${(/** @type {Event} */ e) => {
+            const target = /** @type {HTMLInputElement} */ (e.target);
+            const newName = target.value.trim();
             if (newName && newName !== childName && handlers.onRenameNested) {
               handlers.onRenameNested(parentName, childName, newName);
             } else {
-              e.target.value = childName;
+              target.value = childName;
             }
           }}
-          @keydown=${(/** @type {any} */ e) => {
-            if (e.key === "Enter") e.target.blur();
+          @keydown=${(/** @type {KeyboardEvent} */ e) => {
+            const target = /** @type {HTMLInputElement} */ (e.target);
+            if (e.key === "Enter") target.blur();
             if (e.key === "Escape") {
-              e.target.value = childName;
-              e.target.blur();
+              target.value = childName;
+              target.blur();
             }
           }}
         ></sp-textfield>
@@ -240,7 +247,7 @@ function nestedFieldCardTpl(parentName, childName, childSchema, isRequired, hand
  *
  * @param {string} parentName
  * @param {FieldHandlers} handlers
- * @returns {any}
+ * @returns {import("lit-html").TemplateResult}
  */
 function nestedAddFieldTpl(parentName, handlers) {
   return html`
@@ -249,15 +256,18 @@ function nestedAddFieldTpl(parentName, handlers) {
         size="s"
         placeholder="field name"
         class="schema-nested-add-name"
-        @keydown=${(/** @type {any} */ e) => {
+        @keydown=${(/** @type {KeyboardEvent} */ e) => {
           if (e.key === "Enter") {
-            const row = e.target.closest(".schema-nested-add");
-            const name = e.target.value.trim();
-            const typePicker = row?.querySelector("sp-picker");
+            const target = /** @type {HTMLInputElement} */ (e.target);
+            const row = target.closest(".schema-nested-add");
+            const name = target.value.trim();
+            const typePicker = /** @type {HTMLInputElement | null} */ (
+              row?.querySelector("sp-picker")
+            );
             const type = typePicker?.value || "string";
             if (name && handlers.onAddNestedField) {
               handlers.onAddNestedField(parentName, { name, type, required: false });
-              e.target.value = "";
+              target.value = "";
             }
           }
         }}
@@ -267,15 +277,20 @@ function nestedAddFieldTpl(parentName, handlers) {
         size="xs"
         quiet
         title="Add nested field"
-        @click=${(/** @type {any} */ e) => {
-          const row = e.target.closest(".schema-nested-add");
-          const nameInput = /** @type {any} */ (row?.querySelector(".schema-nested-add-name"));
-          const typePicker = /** @type {any} */ (row?.querySelector("sp-picker"));
+        @click=${(/** @type {Event} */ e) => {
+          const target = /** @type {HTMLElement} */ (e.target);
+          const row = target.closest(".schema-nested-add");
+          const nameInput = /** @type {HTMLInputElement | null} */ (
+            row?.querySelector(".schema-nested-add-name")
+          );
+          const typePicker = /** @type {HTMLInputElement | null} */ (
+            row?.querySelector("sp-picker")
+          );
           const name = nameInput?.value?.trim();
           const type = typePicker?.value || "string";
           if (name && handlers.onAddNestedField) {
             handlers.onAddNestedField(parentName, { name, type, required: false });
-            nameInput.value = "";
+            if (nameInput) nameInput.value = "";
           }
         }}
       >
@@ -290,7 +305,7 @@ function nestedAddFieldTpl(parentName, handlers) {
  *
  * @param {string} value
  * @param {(type: string) => void} onChange
- * @returns {any}
+ * @returns {import("lit-html").TemplateResult}
  */
 export function typePickerTpl(value, onChange) {
   return html`
@@ -298,7 +313,8 @@ export function typePickerTpl(value, onChange) {
       size="s"
       label="Type"
       value=${value}
-      @change=${(/** @type {any} */ e) => onChange(e.target.value)}
+      @change=${(/** @type {Event} */ e) =>
+        onChange(/** @type {HTMLInputElement} */ (e.target).value)}
     >
       ${FIELD_TYPES.map((t) => html`<sp-menu-item value=${t}>${t}</sp-menu-item>`)}
     </sp-picker>
@@ -310,7 +326,7 @@ export function typePickerTpl(value, onChange) {
  *
  * @param {string} value
  * @param {(format: string) => void} onChange
- * @returns {any}
+ * @returns {import("lit-html").TemplateResult}
  */
 export function formatPickerTpl(value, onChange) {
   return html`
@@ -318,7 +334,8 @@ export function formatPickerTpl(value, onChange) {
       size="s"
       label="Format"
       value=${value}
-      @change=${(/** @type {any} */ e) => onChange(e.target.value)}
+      @change=${(/** @type {Event} */ e) =>
+        onChange(/** @type {HTMLInputElement} */ (e.target).value)}
     >
       ${FORMAT_OPTIONS.map((f) => html`<sp-menu-item value=${f}>${f || "(none)"}</sp-menu-item>`)}
     </sp-picker>
@@ -330,11 +347,11 @@ export function formatPickerTpl(value, onChange) {
  *
  * @param {{ name: string; type: string; format: string; required: boolean }} state
  * @param {{
- *   onInput: (field: string, value: any) => void;
+ *   onInput: (field: string, value: string | boolean) => void;
  *   onConfirm: () => void;
  *   onCancel: () => void;
  * }} handlers
- * @returns {any}
+ * @returns {import("lit-html").TemplateResult}
  */
 export function addFieldFormTpl(state, handlers) {
   return html`
@@ -343,8 +360,9 @@ export function addFieldFormTpl(state, handlers) {
         size="s"
         placeholder="Field name"
         .value=${state.name}
-        @input=${(/** @type {any} */ e) => handlers.onInput("name", e.target.value)}
-        @keydown=${(/** @type {any} */ e) => {
+        @input=${(/** @type {Event} */ e) =>
+          handlers.onInput("name", /** @type {HTMLInputElement} */ (e.target).value)}
+        @keydown=${(/** @type {KeyboardEvent} */ e) => {
           if (e.key === "Enter") handlers.onConfirm();
           if (e.key === "Escape") handlers.onCancel();
         }}
@@ -356,7 +374,8 @@ export function addFieldFormTpl(state, handlers) {
       <sp-switch
         size="s"
         ?checked=${state.required}
-        @change=${(/** @type {any} */ e) => handlers.onInput("required", e.target.checked)}
+        @change=${(/** @type {Event} */ e) =>
+          handlers.onInput("required", /** @type {HTMLInputElement} */ (e.target).checked)}
       >
         Required
       </sp-switch>

package/src/settings/settings-modal.js

@@ -20,6 +20,9 @@ let _handle = null;
 /** @type {string} */
 let _activeSection = "general";
 
+/** @type {HTMLElement | null} */
+let _contentEl = null;
+
 const sections = [
   { key: "general", label: "General", icon: "sp-icon-properties" },
   { key: "head", label: "Head", icon: "sp-icon-file-single-web-page" },
@@ -38,6 +41,7 @@ export function closeSettingsModal() {
   if (!_handle) return;
   _handle.close();
   _handle = null;
+  _contentEl = null;
 }
 
 function renderModal() {
@@ -77,7 +81,8 @@ function renderModal() {
         <div
           class="settings-modal-content"
           ${ref((el) => {
-            if (el) requestAnimationFrame(() => renderActiveSection());
+            _contentEl = /** @type {HTMLElement | null} */ (el || null);
+            if (_contentEl) requestAnimationFrame(() => renderActiveSection());
           })}
         ></div>
       </div>
@@ -92,25 +97,23 @@ function renderModal() {
 }
 
 function renderActiveSection() {
-  if (!_handle) return;
-  const container = _handle.host.querySelector(".settings-modal-content");
-  if (!container) return;
+  if (!_handle || !_contentEl) return;
 
   switch (_activeSection) {
     case "general":
-      renderGeneralSettings(/** @type {HTMLElement} */ (container));
+      renderGeneralSettings(_contentEl);
       break;
     case "head":
-      renderHeadEditor(/** @type {HTMLElement} */ (container));
+      renderHeadEditor(_contentEl);
       break;
     case "cssVars":
-      renderCssVarsEditor(/** @type {HTMLElement} */ (container));
+      renderCssVarsEditor(_contentEl);
       break;
     case "definitions":
-      renderDefsEditor(/** @type {HTMLElement} */ (container));
+      renderDefsEditor(_contentEl);
       break;
     case "contentTypes":
-      renderContentTypesEditor(/** @type {HTMLElement} */ (container));
+      renderContentTypesEditor(_contentEl);
       break;
   }
 }

package/src/site-context.js

@@ -5,14 +5,15 @@
  * definitions merge on top (file wins on conflict).
  */
 
-import { projectState, setProjectState } from "./store.js";
+import { projectState, setProjectState, requireProjectState } from "./store.js";
 import { getPlatform } from "./platform.js";
 
 /**
  * Merge site $media with document $media. Document keys win on conflict.
  *
- * @param {any} docMedia - The current document's $media (may be undefined)
- * @returns {any}
+ * @param {Record<string, string> | undefined} docMedia - The current document's $media (may be
+ *   undefined)
+ * @returns {Record<string, string>}
  */
 export function getEffectiveMedia(docMedia) {
   const siteMedia = projectState?.projectConfig?.$media;
@@ -25,8 +26,8 @@ export function getEffectiveMedia(docMedia) {
  * Merge site style with document style. Document keys win on conflict. Nested selector objects
  * (e.g. `& li`) are shallow-merged individually.
  *
- * @param {any} docStyle - The current document's style (may be undefined)
- * @returns {any}
+ * @param {JxStyle | undefined} docStyle - The current document's style (may be undefined)
+ * @returns {JxStyle}
  */
 export function getEffectiveStyle(docStyle) {
   const siteStyle = projectState?.projectConfig?.style;
@@ -40,7 +41,7 @@ export function getEffectiveStyle(docStyle) {
       typeof merged[k] === "object" &&
       merged[k] !== null
     ) {
-      merged[k] = { ...merged[k], ...v };
+      merged[k] = { .../** @type {JxStyle} */ (merged[k]), .../** @type {JxStyle} */ (v) };
     } else {
       merged[k] = v;
     }
@@ -51,8 +52,9 @@ export function getEffectiveStyle(docStyle) {
 /**
  * Merge site imports with document imports. Document keys win on conflict.
  *
- * @param {any} docImports - The current document's imports (may be undefined)
- * @returns {any}
+ * @param {Record<string, string> | undefined} docImports - The current document's imports (may be
+ *   undefined)
+ * @returns {Record<string, string>}
  */
 export function getEffectiveImports(docImports) {
   const siteImports = projectState?.projectConfig?.imports;
@@ -64,8 +66,9 @@ export function getEffectiveImports(docImports) {
 /**
  * Merge site $elements with document $elements. Union with dedup by $ref or string value.
  *
- * @param {any[]} [docElements] - The current document's $elements (may be undefined)
- * @returns {any[]}
+ * @param {(JxElement | string)[]} [docElements] - The current document's $elements (may be
+ *   undefined)
+ * @returns {(JxElement | string)[]}
  */
 export function getEffectiveElements(docElements) {
   const siteElements = projectState?.projectConfig?.$elements;
@@ -73,7 +76,7 @@ export function getEffectiveElements(docElements) {
   if (!docElements?.length) return [...siteElements];
   /** @type {Set<string>} */
   const seen = new Set();
-  /** @type {any[]} */
+  /** @type {(JxElement | string)[]} */
   const merged = [];
   for (const entry of [...siteElements, ...docElements]) {
     const key = typeof entry === "string" ? entry : entry?.$ref;
@@ -88,8 +91,8 @@ export function getEffectiveElements(docElements) {
 /**
  * Merge site $head with document $head. Union with dedup by href/src.
  *
- * @param {any[]} [docHead] - The current document's $head (may be undefined)
- * @returns {any[]}
+ * @param {JxHeadEntry[]} [docHead] - The current document's $head (may be undefined)
+ * @returns {JxHeadEntry[]}
  */
 export function getEffectiveHead(docHead) {
   const siteHead = projectState?.projectConfig?.$head;
@@ -97,10 +100,11 @@ export function getEffectiveHead(docHead) {
   if (!docHead?.length) return [...siteHead];
   /** @type {Set<string>} */
   const seen = new Set();
-  /** @type {any[]} */
+  /** @type {JxHeadEntry[]} */
   const merged = [];
   for (const entry of [...siteHead, ...docHead]) {
-    const key = entry?.attributes?.href || entry?.attributes?.src || JSON.stringify(entry);
+    const key =
+      String(entry?.attributes?.href || entry?.attributes?.src || "") || JSON.stringify(entry);
     if (!seen.has(key)) {
       seen.add(key);
       merged.push(entry);
@@ -111,7 +115,7 @@ export function getEffectiveHead(docHead) {
 
 // ─── Layout resolution ──────────────────────────────────────────────────────
 
-/** @type {Map<string, any>} */
+/** @type {Map<string, JxMutableNode>} */
 const layoutCache = new Map();
 
 export function invalidateLayoutCache() {
@@ -121,7 +125,8 @@ export function invalidateLayoutCache() {
 /**
  * Determine the effective layout path for a document.
  *
- * @param {any} docLayout - The document's $layout value (string path, false, or undefined)
+ * @param {string | false | undefined} docLayout - The document's $layout value (string path, false,
+ *   or undefined)
  * @returns {string | null} The layout path, or null if no layout applies
  */
 export function getEffectiveLayoutPath(docLayout) {
@@ -134,11 +139,12 @@ export function getEffectiveLayoutPath(docLayout) {
  * Resolve a layout document by path. Fetches and caches the parsed JSON.
  *
  * @param {string} layoutPath - Relative path to the layout file (e.g., "./layouts/base.json")
- * @returns {Promise<any | null>} The parsed layout document, or null on failure
+ * @returns {Promise<JxMutableNode | null>} The parsed layout document, or null on failure
  */
 export async function resolveLayoutDoc(layoutPath) {
   const normalized = layoutPath.replace(/^\.\//, "");
-  if (layoutCache.has(normalized)) return structuredClone(layoutCache.get(normalized));
+  if (layoutCache.has(normalized))
+    return structuredClone(/** @type {JxMutableNode} */ (layoutCache.get(normalized)));
 
   try {
     const platform = getPlatform();
@@ -155,9 +161,9 @@ export async function resolveLayoutDoc(layoutPath) {
  * Distribute page children into a layout document's <slot> elements. Returns the merged document
  * with page content injected into slots.
  *
- * @param {any} layoutDoc - Deep-cloned layout document
- * @param {any} pageDoc - The page document
- * @returns {any} The merged document
+ * @param {JxMutableNode} layoutDoc - Deep-cloned layout document
+ * @param {JxMutableNode} pageDoc - The page document
+ * @returns {JxMutableNode} The merged document
  */
 export function distributePageIntoLayout(layoutDoc, pageDoc) {
   const pageChildren = pageDoc.children ?? [];
@@ -187,19 +193,20 @@ export function distributePageIntoLayout(layoutDoc, pageDoc) {
 }
 
 function fillSlots(
-  /** @type {any} */ node,
-  /** @type {Map<string, any[]>} */ named,
-  /** @type {any[]} */ defaults,
+  /** @type {JxMutableNode} */ node,
+  /** @type {Map<string, JxMutableNode[]>} */ named,
+  /** @type {(JxMutableNode | string)[]} */ defaults,
 ) {
   if (!node || typeof node !== "object") return;
   if (!Array.isArray(node.children)) return;
 
+  /** @type {(JxMutableNode | string)[]} */
   const newChildren = [];
   for (const child of node.children) {
     if (child && typeof child === "object" && child.tagName === "slot") {
       const slotName = child.attributes?.name;
       if (slotName && named.has(slotName)) {
-        newChildren.push(.../** @type {any[]} */ (named.get(slotName)));
+        newChildren.push(.../** @type {JxMutableNode[]} */ (named.get(slotName)));
         named.delete(slotName);
       } else if (!slotName && defaults.length > 0) {
         newChildren.push(...defaults);
@@ -207,21 +214,24 @@ function fillSlots(
         newChildren.push(...child.children);
       }
     } else {
-      fillSlots(child, named, defaults);
+      if (typeof child !== "string") fillSlots(child, named, defaults);
       newChildren.push(child);
     }
   }
-  node.children = newChildren;
+  node.children = /** @type {JxMutableNode[]} */ (newChildren);
 }
 
 /**
  * Update the project's project.json with a partial patch and persist to disk.
  *
- * @param {Record<string, any>} patch - Fields to merge into the current projectConfig
+ * @param {Partial<ProjectConfig>} patch - Fields to merge into the current projectConfig
  */
 export async function updateSiteConfig(patch) {
   const platform = getPlatform();
-  const config = { ...projectState.projectConfig, ...patch };
+  const config = /** @type {ProjectConfig} */ ({
+    ...requireProjectState().projectConfig,
+    ...patch,
+  });
   await platform.writeFile("project.json", JSON.stringify(config, null, 2));
-  setProjectState({ ...projectState, projectConfig: config });
+  setProjectState({ ...requireProjectState(), projectConfig: config });
 }