@jxsuite/studio 0.10.1 → 0.11.0

package/src/settings/{collections-editor.js → content-types-editor.js}

@@ -1,8 +1,8 @@
 /**
- * Collections Editor — visual schema builder for project content collections.
+ * Content Types Editor — visual schema builder for project content types.
  *
- * Renders inside the Settings view "Collections" tab. Two-column layout: left column lists
- * collection names, right column edits the selected collection's schema.
+ * Renders inside the Settings view "Content Types" tab. Two-column layout: left column lists
+ * content type names, right column edits the selected content type's schema.
  */
 
 import { html, render as litRender } from "lit-html";
@@ -13,11 +13,11 @@ import { fieldCardTpl, addFieldFormTpl, schemaForType } from "./schema-field-ui.
 // ─── Module state ─────────────────────────────────────────────────────────────
 
 /** @type {string | null} */
-let selectedCollection = null;
+let selectedContentType = null;
 let showAddField = false;
 let newFieldState = { name: "", type: "string", required: false };
-let showNewCollection = false;
-let newCollectionName = "";
+let showNewContentType = false;
+let newContentTypeName = "";
 
 // ─── Persistence ──────────────────────────────────────────────────────────────
 
@@ -29,17 +29,17 @@ async function saveProjectConfig() {
 
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 
-/** Get the schema object for the selected collection. */
+/** Get the schema object for the selected content type. */
 function getSelectedSchema() {
   const config = projectState?.projectConfig;
-  return config?.collections?.[/** @type {string} */ (selectedCollection)]?.schema;
+  return config?.contentTypes?.[/** @type {string} */ (selectedContentType)]?.schema;
 }
 
 // ─── Handlers ─────────────────────────────────────────────────────────────────
 
 /** @param {() => void} rerender */
-function handleNewCollection(rerender) {
-  const slug = newCollectionName
+function handleNewContentType(rerender) {
+  const slug = newContentTypeName
     .toLowerCase()
     .replace(/\s+/g, "-")
     .replace(/[^a-z0-9-]/g, "");
@@ -47,30 +47,30 @@ function handleNewCollection(rerender) {
 
   const config = projectState?.projectConfig;
   if (!config) return;
-  if (!config.collections) config.collections = {};
-  if (config.collections[slug]) return; // already exists
+  if (!config.contentTypes) config.contentTypes = {};
+  if (config.contentTypes[slug]) return; // already exists
 
-  config.collections[slug] = {
-    source: `./${slug}/**/*.md`,
+  config.contentTypes[slug] = {
+    source: `./content/${slug}/**/*.md`,
     schema: { type: "object", properties: {}, required: [] },
   };
 
-  selectedCollection = slug;
-  showNewCollection = false;
-  newCollectionName = "";
+  selectedContentType = slug;
+  showNewContentType = false;
+  newContentTypeName = "";
   rerender();
 
   // Persist in background
   saveProjectConfig().then(async () => {
     const platform = getPlatform();
-    await platform.writeFile(`${slug}/.gitkeep`, "");
+    await platform.writeFile(`content/${slug}/.gitkeep`, "");
   });
 }
 
 /** @param {() => void} rerender */
 function handleAddField(rerender) {
   const name = newFieldState.name.trim();
-  if (!name || !selectedCollection) return;
+  if (!name || !selectedContentType) return;
 
   const schema = getSelectedSchema();
   if (!schema) return;
@@ -163,6 +163,20 @@ function handleChangeType(fieldName, newType, rerender) {
   saveProjectConfig();
 }
 
+/**
+ * @param {string} fieldName
+ * @param {string} target
+ * @param {() => void} rerender
+ */
+function handleChangeRefTarget(fieldName, target, rerender) {
+  const schema = getSelectedSchema();
+  if (!schema?.properties) return;
+
+  schema.properties[fieldName] = { $ref: `#/contentTypes/${target}` };
+  rerender();
+  saveProjectConfig();
+}
+
 // ─── Nested field handlers ───────────────────────────────────────────────────
 
 /**
@@ -270,13 +284,13 @@ function handleChangeNestedType(parentName, childName, newType, rerender) {
 }
 
 /** @param {() => void} rerender */
-function handleDeleteCollection(rerender) {
-  if (!selectedCollection) return;
+function handleDeleteContentType(rerender) {
+  if (!selectedContentType) return;
   const config = projectState?.projectConfig;
-  if (!config?.collections?.[selectedCollection]) return;
+  if (!config?.contentTypes?.[selectedContentType]) return;
 
-  delete config.collections[selectedCollection];
-  selectedCollection = null;
+  delete config.contentTypes[selectedContentType];
+  selectedContentType = null;
 
   rerender();
   saveProjectConfig();
@@ -285,26 +299,26 @@ function handleDeleteCollection(rerender) {
 // ─── Render ───────────────────────────────────────────────────────────────────
 
 /**
- * Render the collections editor.
+ * Render the content types editor.
  *
  * @param {HTMLElement} container
  */
-export function renderCollectionsEditor(container) {
-  const rerender = () => renderCollectionsEditor(container);
+export function renderContentTypesEditor(container) {
+  const rerender = () => renderContentTypesEditor(container);
   const config = projectState?.projectConfig;
-  const collections = config?.collections || {};
-  const collectionNames = Object.keys(collections);
+  const contentTypes = config?.contentTypes || {};
+  const contentTypeNames = Object.keys(contentTypes);
 
-  // Left column — collection list
+  // Left column — content type list
   const listTpl = html`
     <div class="settings-list-panel">
-      ${collectionNames.map(
+      ${contentTypeNames.map(
         (name) => html`
           <sp-action-button
             size="s"
-            ?selected=${selectedCollection === name}
+            ?selected=${selectedContentType === name}
             @click=${() => {
-              selectedCollection = name;
+              selectedContentType = name;
               showAddField = false;
               rerender();
             }}
@@ -313,25 +327,25 @@ export function renderCollectionsEditor(container) {
           </sp-action-button>
         `,
       )}
-      ${showNewCollection
+      ${showNewContentType
         ? html`
             <div class="settings-inline-form">
               <sp-textfield
                 size="s"
-                placeholder="collection-name"
-                .value=${newCollectionName}
+                placeholder="content-type-name"
+                .value=${newContentTypeName}
                 @input=${(/** @type {any} */ e) => {
-                  newCollectionName = e.target.value;
+                  newContentTypeName = e.target.value;
                 }}
                 @keydown=${(/** @type {any} */ e) => {
-                  if (e.key === "Enter") handleNewCollection(rerender);
+                  if (e.key === "Enter") handleNewContentType(rerender);
                   if (e.key === "Escape") {
-                    showNewCollection = false;
+                    showNewContentType = false;
                     rerender();
                   }
                 }}
               ></sp-textfield>
-              <sp-action-button size="s" @click=${() => handleNewCollection(rerender)}>
+              <sp-action-button size="s" @click=${() => handleNewContentType(rerender)}>
                 Create
               </sp-action-button>
             </div>
@@ -341,11 +355,11 @@ export function renderCollectionsEditor(container) {
               size="s"
               quiet
               @click=${() => {
-                showNewCollection = true;
+                showNewContentType = true;
                 rerender();
               }}
             >
-              <sp-icon-add slot="icon"></sp-icon-add> New Collection
+              <sp-icon-add slot="icon"></sp-icon-add> New Content Type
             </sp-action-button>
           `}
     </div>
@@ -353,10 +367,10 @@ export function renderCollectionsEditor(container) {
 
   // Right column — schema editor
   let editorTpl;
-  if (!selectedCollection || !collections[selectedCollection]) {
-    editorTpl = html`<div class="settings-empty-state">Select or create a collection</div>`;
+  if (!selectedContentType || !contentTypes[selectedContentType]) {
+    editorTpl = html`<div class="settings-empty-state">Select or create a content type</div>`;
   } else {
-    const col = collections[selectedCollection];
+    const col = contentTypes[selectedContentType];
     const schema = col.schema || {};
     const properties = schema.properties || {};
     const required = schema.required || [];
@@ -367,6 +381,7 @@ export function renderCollectionsEditor(container) {
       onToggleRequired: (n) => handleToggleRequired(n, rerender),
       onRename: (oldN, newN) => handleRenameField(oldN, newN, rerender),
       onChangeType: (n, t) => handleChangeType(n, t, rerender),
+      onChangeRefTarget: (n, target) => handleChangeRefTarget(n, target, rerender),
       onAddNestedField: (p, s) => handleAddNestedField(p, s, rerender),
       onDeleteNested: (p, c) => handleDeleteNested(p, c, rerender),
       onToggleNestedRequired: (p, c) => handleToggleNestedRequired(p, c, rerender),
@@ -375,19 +390,25 @@ export function renderCollectionsEditor(container) {
     };
 
     const fieldCards = Object.entries(properties).map(([name, def]) =>
-      fieldCardTpl(name, /** @type {any} */ (def), required.includes(name), handlers),
+      fieldCardTpl(
+        name,
+        /** @type {any} */ (def),
+        required.includes(name),
+        handlers,
+        contentTypeNames,
+      ),
     );
 
     editorTpl = html`
       <div class="settings-editor-panel">
         <div class="settings-editor-header">
-          <h3>${selectedCollection}</h3>
+          <h3>${selectedContentType}</h3>
           <sp-field-label size="s">Source: ${col.source || "—"}</sp-field-label>
           <sp-action-button
             size="xs"
             quiet
-            title="Delete collection"
-            @click=${() => handleDeleteCollection(rerender)}
+            title="Delete content type"
+            @click=${() => handleDeleteContentType(rerender)}
           >
             <sp-icon-delete slot="icon"></sp-icon-delete>
           </sp-action-button>

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

@@ -1,11 +1,21 @@
 /**
- * Schema field UI — shared field-card and add-field-dialog templates for the collections and
+ * Schema field UI — shared field-card and add-field-dialog templates for the content types and
  * definitions editors.
  */
 
 import { html, nothing } from "lit-html";
 
-export const FIELD_TYPES = ["string", "number", "boolean", "array", "object", "date"];
+export const FIELD_TYPES = [
+  "string",
+  "number",
+  "boolean",
+  "array",
+  "object",
+  "date",
+  "image",
+  "gallery",
+  "reference",
+];
 
 /**
  * @typedef {{
@@ -14,6 +24,7 @@ export const FIELD_TYPES = ["string", "number", "boolean", "array", "object", "d
  *   required?: string[];
  *   items?: any;
  *   format?: string;
+ *   $ref?: string;
  * }} SchemaProperty
  */
 
@@ -23,6 +34,7 @@ export const FIELD_TYPES = ["string", "number", "boolean", "array", "object", "d
  *   onToggleRequired: (name: string) => void;
  *   onRename: (oldName: string, newName: string) => void;
  *   onChangeType: (name: string, newType: string) => void;
+ *   onChangeRefTarget?: (name: string, target: string) => void;
  *   onAddNestedField?: (
  *     parentName: string,
  *     state: { name: string; type: string; required: boolean },
@@ -34,6 +46,20 @@ export const FIELD_TYPES = ["string", "number", "boolean", "array", "object", "d
  * }} FieldHandlers
  */
 
+/**
+ * Detect the studio field type from a JSON Schema property definition.
+ *
+ * @param {SchemaProperty} schema
+ * @returns {string}
+ */
+export function detectFieldType(schema) {
+  if (schema.$ref) return "reference";
+  if (schema.format === "image") return "image";
+  if (schema.format === "date") return "date";
+  if (schema.type === "array" && schema.items?.format === "image") return "gallery";
+  return schema.type || "string";
+}
+
 /**
  * Render a single schema field as an inline-editable form row.
  *
@@ -41,13 +67,16 @@ export const FIELD_TYPES = ["string", "number", "boolean", "array", "object", "d
  * @param {SchemaProperty} fieldSchema — JSON Schema property definition
  * @param {boolean} isRequired
  * @param {FieldHandlers} handlers
+ * @param {string[]} [contentTypeNames] - Available content type names for reference target picker
  * @returns {any}
  */
-export function fieldCardTpl(fieldName, fieldSchema, isRequired, handlers) {
-  const type = fieldSchema.format === "date" ? "date" : fieldSchema.type || "string";
+export function fieldCardTpl(fieldName, fieldSchema, isRequired, handlers, contentTypeNames = []) {
+  const type = detectFieldType(fieldSchema);
   const isNested = type === "object";
+  const isRef = type === "reference";
   const nestedProps = fieldSchema.properties || {};
   const nestedRequired = fieldSchema.required || [];
+  const refTarget = fieldSchema.$ref ? fieldSchema.$ref.replace("#/contentTypes/", "") : "";
 
   return html`
     <div class="schema-field-card">
@@ -87,6 +116,23 @@ export function fieldCardTpl(fieldName, fieldSchema, isRequired, handlers) {
           <sp-icon-delete slot="icon"></sp-icon-delete>
         </sp-action-button>
       </div>
+      ${isRef && contentTypeNames.length
+        ? html`
+            <div class="schema-field-ref-target">
+              <sp-picker
+                size="s"
+                label="Target"
+                value=${refTarget}
+                @change=${(/** @type {any} */ e) => {
+                  if (handlers.onChangeRefTarget)
+                    handlers.onChangeRefTarget(fieldName, e.target.value);
+                }}
+              >
+                ${contentTypeNames.map((n) => html`<sp-menu-item value=${n}>${n}</sp-menu-item>`)}
+              </sp-picker>
+            </div>
+          `
+        : nothing}
       ${isNested
         ? html`
             <div class="schema-field-nested">
@@ -119,7 +165,7 @@ export function fieldCardTpl(fieldName, fieldSchema, isRequired, handlers) {
  * @returns {any}
  */
 function nestedFieldCardTpl(parentName, childName, childSchema, isRequired, handlers) {
-  const type = childSchema.format === "date" ? "date" : childSchema.type || "string";
+  const type = detectFieldType(childSchema);
 
   return html`
     <div class="schema-field-card schema-field-card--nested">
@@ -300,6 +346,12 @@ export function schemaForType(type) {
       return { type: "object", properties: {}, required: [] };
     case "date":
       return { type: "string", format: "date" };
+    case "image":
+      return { type: "string", format: "image" };
+    case "gallery":
+      return { type: "array", items: { type: "string", format: "image" } };
+    case "reference":
+      return { $ref: "#/contentTypes/" };
     default:
       return { type: "string" };
   }
@@ -314,6 +366,7 @@ export function schemaForType(type) {
  */
 export function yamlDefault(type, format) {
   if (format === "date") return new Date().toISOString().split("T")[0];
+  if (format === "image") return '""';
   switch (type) {
     case "boolean":
       return "false";

package/src/site-context.js

@@ -109,6 +109,111 @@ export function getEffectiveHead(docHead) {
   return merged;
 }
 
+// ─── Layout resolution ──────────────────────────────────────────────────────
+
+/** @type {Map<string, any>} */
+const layoutCache = new Map();
+
+export function invalidateLayoutCache() {
+  layoutCache.clear();
+}
+
+/**
+ * Determine the effective layout path for a document.
+ *
+ * @param {any} 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) {
+  if (docLayout === false) return null;
+  const defaultLayout = projectState?.projectConfig?.defaults?.layout;
+  return docLayout || defaultLayout || null;
+}
+
+/**
+ * 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
+ */
+export async function resolveLayoutDoc(layoutPath) {
+  const normalized = layoutPath.replace(/^\.\//, "");
+  if (layoutCache.has(normalized)) return structuredClone(layoutCache.get(normalized));
+
+  try {
+    const platform = getPlatform();
+    const content = await platform.readFile(normalized);
+    const doc = JSON.parse(content);
+    layoutCache.set(normalized, doc);
+    return structuredClone(doc);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 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
+ */
+export function distributePageIntoLayout(layoutDoc, pageDoc) {
+  const pageChildren = pageDoc.children ?? [];
+  const children = typeof pageChildren === "string" ? [pageChildren] : pageChildren;
+
+  const named = new Map();
+  const defaults = [];
+
+  for (const child of children) {
+    if (child && typeof child === "object" && child.attributes?.slot) {
+      const slotName = child.attributes.slot;
+      if (!named.has(slotName)) named.set(slotName, []);
+      named.get(slotName).push(child);
+    } else {
+      defaults.push(child);
+    }
+  }
+
+  fillSlots(layoutDoc, named, defaults);
+
+  if (pageDoc.state) layoutDoc.state = { ...layoutDoc.state, ...pageDoc.state };
+  if (pageDoc.$media) layoutDoc.$media = { ...layoutDoc.$media, ...pageDoc.$media };
+  if (pageDoc.style) layoutDoc.style = { ...layoutDoc.style, ...pageDoc.style };
+  if (pageDoc.attributes) layoutDoc.attributes = { ...layoutDoc.attributes, ...pageDoc.attributes };
+
+  return layoutDoc;
+}
+
+function fillSlots(
+  /** @type {any} */ node,
+  /** @type {Map<string, any[]>} */ named,
+  /** @type {any[]} */ defaults,
+) {
+  if (!node || typeof node !== "object") return;
+  if (!Array.isArray(node.children)) return;
+
+  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)));
+        named.delete(slotName);
+      } else if (!slotName && defaults.length > 0) {
+        newChildren.push(...defaults);
+      } else if (child.children) {
+        newChildren.push(...child.children);
+      }
+    } else {
+      fillSlots(child, named, defaults);
+      newChildren.push(child);
+    }
+  }
+  node.children = newChildren;
+}
+
 /**
  * Update the project's project.json with a partial patch and persist to disk.
  *

package/src/state.js

@@ -229,7 +229,7 @@ export function createState(doc) {
       stylebookTab: "elements", // "elements" | "variables"
       stylebookFilter: "", // search filter text
       stylebookCustomizedOnly: false, // show only customized elements
-      settingsTab: "stylebook", // "stylebook" | "definitions" | "collections"
+      settingsTab: "stylebook", // "stylebook" | "definitions" | "contentTypes"
       gitStatus: null, // { branch, ahead, behind, files: [] }
       gitBranches: null, // { current, branches: [] }
       gitCommitMessage: "", // commit message input

package/src/store.js

@@ -164,7 +164,15 @@ export function stripEventHandlers(node) {
       const cases = {};
       for (const [ck, cv] of Object.entries(v)) cases[ck] = stripEventHandlers(cv);
       out.cases = cases;
-    } else if (k === "state" || k === "style" || k === "attributes" || k === "$media") {
+    } else if (k === "state" && typeof v === "object" && v !== null) {
+      /** @type {Record<string, any>} */
+      const state = {};
+      for (const [sk, sv] of Object.entries(v)) {
+        if (sv && typeof sv === "object" && sv.timing === "server") continue;
+        state[sk] = sv;
+      }
+      out.state = state;
+    } else if (k === "style" || k === "attributes" || k === "$media") {
       out[k] = v;
     } else {
       out[k] = v;

package/src/studio.js

@@ -543,13 +543,19 @@ if (_openParam) {
         }
 
         // Read and open the file
-        const fileRelPath = siteCtx.fileRelPath || _openParam;
+        const _fileParam = new URLSearchParams(location.search).get("file");
+        const fileRelPath = _fileParam || siteCtx.fileRelPath || _openParam;
         const content = await platform.readFile(fileRelPath);
         if (content) {
-          const parsed = JSON.parse(content);
-          S = createState(parsed);
+          if (fileRelPath.endsWith(".md")) {
+            await loadMarkdown(content, null);
+            S.documentPath = fileRelPath;
+          } else {
+            const parsed = JSON.parse(content);
+            S = createState(parsed);
+            S.documentPath = fileRelPath;
+          }
           S.dirty = false;
-          S.documentPath = fileRelPath;
           S.ui = { ...S.ui, leftTab: "files" };
           ({ doc, session } = fromFlat(S));
           render();

package/src/ui/spectrum.js

@@ -47,6 +47,7 @@ import { PickerButton } from "@spectrum-web-components/picker-button/src/PickerB
 import { Accordion } from "@spectrum-web-components/accordion/src/Accordion.js";
 import { AccordionItem } from "@spectrum-web-components/accordion/src/AccordionItem.js";
 import { ActionBar } from "@spectrum-web-components/action-bar/src/ActionBar.js";
+import { Toast } from "@spectrum-web-components/toast/src/Toast.js";
 import { Table } from "@spectrum-web-components/table/src/Table.js";
 import { TableHead } from "@spectrum-web-components/table/src/TableHead.js";
 import { TableHeadCell } from "@spectrum-web-components/table/src/TableHeadCell.js";
@@ -180,6 +181,7 @@ const components = [
   ["sp-accordion", Accordion],
   ["sp-accordion-item", AccordionItem],
   ["sp-action-bar", ActionBar],
+  ["sp-toast", Toast],
   ["sp-table", Table],
   ["sp-table-head", TableHead],
   ["sp-table-head-cell", TableHeadCell],

package/src/utils/studio-utils.js

@@ -123,17 +123,17 @@ export function inferInputType(entry) {
 }
 
 /**
- * Match a document path to a content collection and return its schema. Uses simple directory-prefix
- * + extension matching against the collection's `source` glob.
+ * Match a document path to a content type and return its schema. Uses simple directory-prefix +
+ * extension matching against the content type's `source` glob.
  *
  * @param {string | null} documentPath — project-relative path (e.g. "blog/hello.md")
  * @param {any} projectConfig — parsed project.json
  * @returns {{ name: string; schema: any } | null}
  */
-export function findCollectionSchema(documentPath, projectConfig) {
-  if (!documentPath || !projectConfig?.collections) return null;
+export function findContentTypeSchema(documentPath, projectConfig) {
+  if (!documentPath || !projectConfig?.contentTypes) return null;
   for (const [name, def] of Object.entries(
-    /** @type {Record<string, any>} */ (projectConfig.collections),
+    /** @type {Record<string, any>} */ (projectConfig.contentTypes),
   )) {
     if (!def.source || !def.schema) continue;
     const src = def.source.replace(/^\.\//, "");

package/src/view.js

@@ -61,6 +61,9 @@ export const view = {
   showAddBreakpointForm: false,
   addBreakpointPreview: "",
 
+  // Layout selection (when user clicks a layout element)
+  layoutSelection: null,
+
   // Autosave
   autosaveTimer: null,
 };