meno-core 1.0.53 → 1.1.0

package/lib/shared/treePathUtils.ts

@@ -2,13 +2,13 @@
  * Tree path utilities for parsing and navigating tree structure paths
  */
 
-import { ComponentNode, PageData, JSONPage } from './types';
+import type { ComponentNode, PageData } from './types';
 import type { PropDefinition } from './types';
 import type { Path } from './pathArrayUtils';
 import { stringToPath } from './pathArrayUtils';
 
 // Type for page data that can have component structure
-type PageDataWithComponent = PageData & {
+type _PageDataWithComponent = PageData & {
   component?: {
     structure?: ComponentNode;
     interface?: Record<string, PropDefinition>;
@@ -28,12 +28,12 @@ export interface NodeLocation {
  */
 export function validateComponentStructure(pageData: PageData | null): boolean {
   if (!pageData) return false;
-  
+
   // Check for page format (has root property)
   if ('root' in pageData && pageData.root) {
     return true;
   }
-  
+
   // Check for component format (has component.structure property)
   if ('component' in pageData && pageData.component) {
     if ('structure' in pageData.component && pageData.component.structure) {
@@ -42,7 +42,7 @@ export function validateComponentStructure(pageData: PageData | null): boolean {
     // Component exists but structure is missing
     return false;
   }
-  
+
   return false;
 }
 
@@ -52,12 +52,12 @@ export function validateComponentStructure(pageData: PageData | null): boolean {
  */
 export function getRootData(pageData: PageData | null): ComponentNode | null {
   if (!pageData) return null;
-  
+
   // Check for page format (has root property)
   if ('root' in pageData && pageData.root) {
     return pageData.root;
   }
-  
+
   // Check for component format (has component.structure property)
   if ('component' in pageData && pageData.component) {
     if ('structure' in pageData.component) {
@@ -70,7 +70,7 @@ export function getRootData(pageData: PageData | null): ComponentNode | null {
       // Component exists but structure field is missing
     }
   }
-  
+
   return null;
 }
 
@@ -79,10 +79,7 @@ export function getRootData(pageData: PageData | null): ComponentNode | null {
  * Handles paths like: root_0, root_0_children_0, root_0_children_0_children_1
  * Also accepts array paths: [0], [0,0], [0,0,1]
  */
-export function getParentAndIndexFromPath(
-  path: Path | string, 
-  pageData: PageData
-): NodeLocation | null {
+export function getParentAndIndexFromPath(path: Path | string, pageData: PageData): NodeLocation | null {
   const rootData = getRootData(pageData);
   if (!rootData) return null;
 
@@ -94,7 +91,7 @@ export function getParentAndIndexFromPath(
     return {
       parent: pageData,
       index: 0,
-      node: rootData
+      node: rootData,
     };
   }
 
@@ -106,26 +103,27 @@ export function getParentAndIndexFromPath(
   // Skip first element (root index 0), navigate through rest
   for (let i = 1; i < pathArray.length; i++) {
     const childIndex = pathArray[i];
+    if (childIndex === undefined) return null;
 
-      if (!current || !('children' in current) || !Array.isArray(current.children)) {
-        return null;
-      }
-      
-      if (isNaN(childIndex) || childIndex < 0 || childIndex >= current.children.length) {
-        return null;
-      }
+    if (!current || !('children' in current) || !Array.isArray(current.children)) {
+      return null;
+    }
+
+    if (Number.isNaN(childIndex) || childIndex < 0 || childIndex >= current.children.length) {
+      return null;
+    }
 
     parent = current;
-      const child = current.children[childIndex];
-      if (typeof child === 'string') {
-        return null;
-      }
-      current = child;
-      lastIndex = childIndex;
+    const child = current.children[childIndex];
+    if (child === undefined || typeof child === 'string') {
+      return null;
+    }
+    current = child;
+    lastIndex = childIndex;
 
-      // If this is the last navigation step, we found our node
+    // If this is the last navigation step, we found our node
     if (i === pathArray.length - 1) {
-        return { parent, index: childIndex, node: current };
+      return { parent, index: childIndex, node: current };
     }
   }
 
@@ -137,11 +135,44 @@ export function getParentAndIndexFromPath(
   return null;
 }
 
+/**
+ * Find the path to a node by reference identity (===) within the page tree.
+ *
+ * Used to recover the correct tree path when a stored selection path has drifted
+ * out of sync with the current pageData (e.g. a play-mode reload re-parsed the
+ * tree) but the selected node object is still present in the tree. Returns a path
+ * in the same `[0, ...childIndices]` form that {@link getParentAndIndexFromPath}
+ * consumes, or null if the node isn't reachable from the root by reference.
+ */
+export function findPathToNodeByReference(pageData: PageData, target: ComponentNode): Path | null {
+  const root = getRootData(pageData);
+  if (!root) return null;
+
+  // DFS from the root (path [0]); the children of a node at `path` are `[...path, i]`.
+  const stack: { node: ComponentNode; path: Path }[] = [{ node: root, path: [0] }];
+  while (stack.length > 0) {
+    const { node, path } = stack.pop()!;
+    if (node === target) return path;
+    const children = 'children' in node ? node.children : undefined;
+    if (Array.isArray(children)) {
+      for (let i = 0; i < children.length; i++) {
+        const child = children[i];
+        if (child && typeof child === 'object') {
+          stack.push({ node: child as ComponentNode, path: [...path, i] });
+        }
+      }
+    }
+  }
+  return null;
+}
+
 /**
  * Extract structure without styles/props for tree comparison
  * This allows tree to only regenerate when structure changes, not styles
  */
-export function extractStructureWithoutStyles(node: ComponentNode | string | null | undefined): ComponentNode | string | null | undefined {
+export function extractStructureWithoutStyles(
+  node: ComponentNode | string | null | undefined,
+): ComponentNode | string | null | undefined {
   if (!node || typeof node === 'string') {
     return node;
   }
@@ -157,13 +188,13 @@ export function extractStructureWithoutStyles(node: ComponentNode | string | nul
   const component = 'component' in node ? (node as any).component : undefined;
   const ifCondition = 'if' in node ? node.if : undefined;
   const children = 'children' in node ? node.children : undefined;
-  
+
   // Recursively process children
   let processedChildren: ComponentNode | (ComponentNode | string)[] | string | undefined;
   if (children) {
     if (Array.isArray(children)) {
       processedChildren = children.map((child: ComponentNode | string) =>
-        typeof child === 'string' ? child : extractStructureWithoutStyles(child) as ComponentNode
+        typeof child === 'string' ? child : (extractStructureWithoutStyles(child) as ComponentNode),
       );
     } else if (typeof children === 'string') {
       processedChildren = children;
@@ -202,7 +233,7 @@ export function calculateInsertionIndex(
     linearIndex?: number;
   },
   parentChildren: Array<ComponentNode | string>,
-  nodeDataMap: Map<string, ComponentNode | string>
+  nodeDataMap: Map<string, ComponentNode | string>,
 ): number {
   if (target.childIndex !== undefined && target.childIndex >= 0) {
     // Most reliable: use childIndex directly
@@ -250,13 +281,13 @@ export function isValidNodeLocation(location: unknown): location is NodeLocation
   if (!location || typeof location !== 'object') {
     return false;
   }
-  
+
   // Use proper type narrowing instead of assertion
   const loc = location as Record<string, unknown>;
   const hasParent = 'parent' in loc && (loc.parent === null || typeof loc.parent === 'object');
   const hasIndex = 'index' in loc && typeof loc.index === 'number' && loc.index >= 0;
   const hasNode = 'node' in loc && (loc.node === null || typeof loc.node === 'object');
-  
+
   return hasParent && hasIndex && hasNode;
 }
 
@@ -267,7 +298,7 @@ export function isValidPath(path: unknown): path is Path {
   if (!Array.isArray(path)) {
     return false;
   }
-  
+
   // Path is an array of numbers
   return path.every((item): item is number => typeof item === 'number' && item >= 0);
 }
@@ -275,28 +306,24 @@ export function isValidPath(path: unknown): path is Path {
 /**
  * Type guard to check if parent is PageData
  */
-export function isPageDataParent(
-  parent: ComponentNode | PageData | null
-): parent is PageData {
+export function isPageDataParent(parent: ComponentNode | PageData | null): parent is PageData {
   if (!parent) return false;
-  
+
   // Check for JSONPage format (has root property)
   if ('root' in parent) return true;
-  
+
   // Check for component format - component must be an object, not a string
   if ('component' in parent) {
     return typeof parent.component === 'object' && parent.component !== null;
   }
-  
+
   return false;
 }
 
 /**
  * Type guard to check if parent is ComponentNode
  */
-export function isComponentNodeParent(
-  parent: ComponentNode | PageData | null
-): parent is ComponentNode {
+export function isComponentNodeParent(parent: ComponentNode | PageData | null): parent is ComponentNode {
   if (!parent) return false;
   // Check for 'type' property (all ComponentNodes have it)
   // Then check for specific node types that can have children:
@@ -306,29 +333,34 @@ export function isComponentNodeParent(
   // - LinkNode: type === 'link'
   // - EmbedNode: type === 'embed'
   // - ListNode: type === 'list' (also handles legacy 'cms-list' for migration)
+  // - CustomNode: type === 'custom' (opaque .astro, accepts slotted children)
+  // - IslandNode: type === 'island' (BYO framework island, accepts slotted children)
   const nodeType = (parent as any).type;
-  return 'type' in parent && (
-    'tag' in parent ||
-    'component' in parent ||
-    nodeType === 'slot' ||
-    nodeType === 'link' ||
-    nodeType === 'embed' ||
-    nodeType === 'cms-list' ||  // Legacy support for migration
-    nodeType === 'list'
+  return (
+    'type' in parent &&
+    ('tag' in parent ||
+      'component' in parent ||
+      nodeType === 'slot' ||
+      nodeType === 'link' ||
+      nodeType === 'embed' ||
+      nodeType === 'custom' ||
+      nodeType === 'island' ||
+      nodeType === 'cms-list' || // Legacy support for migration
+      nodeType === 'list')
   );
 }
 
 /**
  * Get children array from parent (handles both PageData and ComponentNode)
  */
-export function getParentChildren(
-  parent: ComponentNode | PageData | null
-): Array<ComponentNode | string> | null {
+export function getParentChildren(parent: ComponentNode | PageData | null): Array<ComponentNode | string> | null {
   if (!parent) return null;
-  
+
   if (isPageDataParent(parent)) {
     const rootData = getRootData(parent);
-    return rootData && 'children' in rootData ? (rootData.children as Array<ComponentNode | string> | undefined) || null : null;
+    return rootData && 'children' in rootData
+      ? (rootData.children as Array<ComponentNode | string> | undefined) || null
+      : null;
   }
 
   if (isComponentNodeParent(parent)) {
@@ -343,10 +375,10 @@ export function getParentChildren(
  */
 export function setParentChildren(
   parent: ComponentNode | PageData | null,
-  children: Array<ComponentNode | string>
+  children: Array<ComponentNode | string>,
 ): void {
   if (!parent) return;
-  
+
   if (isPageDataParent(parent)) {
     const rootData = getRootData(parent);
     if (rootData && 'children' in rootData) {
@@ -358,4 +390,3 @@ export function setParentChildren(
     }
   }
 }
-

package/lib/shared/types/api.ts

@@ -16,9 +16,10 @@ export interface HMRMessage {
     | 'hmr:libraries-update'
     | 'hmr:cms-update'
     | 'hmr:cms-collections-update'
-    | 'hmr:config-update';
+    | 'hmr:config-update'
+    | 'hmr:stylesheet-update';
   path?: string;
-  collection?: string;  // For CMS updates
+  collection?: string; // For CMS updates
 }
 
 export interface PageListResponse {
@@ -39,12 +40,57 @@ export interface PageCmsConfig {
   id: string;
   /** Display name for the collection */
   name: string;
-  /** Which field to use for URL slug */
-  slugField: string;
-  /** URL pattern, e.g., "/blog/{{slug}}" */
-  urlPattern: string;
+  /** Which field to use for URL slug. Omitted for a data-only collection (no per-item route). */
+  slugField?: string;
+  /** URL pattern, e.g., "/blog/{{slug}}". Omitted for a data-only collection (no per-item route). */
+  urlPattern?: string;
   /** Field definitions */
   fields: Record<string, CMSFieldDefinition>;
+  /** Generate an RSS 2.0 feed at `<route-prefix>/rss.xml` (routed collections only). */
+  rss?: boolean;
+}
+
+/** Field type discovered for one SSR data-source result (drives binding autocomplete). */
+export type DataFieldType = 'string' | 'number' | 'boolean' | 'date' | 'image' | 'object';
+
+/**
+ * A single declarative data source on an SSR page (`meta.source === 'ssr'`). v1 supports a
+ * declarative HTTP `GET` whose response is bound into the page body. The fetch runs per
+ * request via the `loadPageData` runtime helper. Anything beyond "GET → bind fields"
+ * (multi-step fetches, mutations, custom transforms) stays a hand-authored escape-hatch page.
+ */
+export interface PageDataSource {
+  /** Source kind. Only declarative HTTP fetch in v1. */
+  type: 'fetch';
+  /**
+   * Endpoint URL. May interpolate request inputs and env secrets via `{{…}}`
+   * (e.g. `https://api…/repos/{{params.owner}}?q={{query.q}}`,
+   * `headers: { authorization: "Bearer {{env.TOKEN}}" }`). The origin is author-fixed —
+   * only path/query segments interpolate (SSRF guard).
+   */
+  url: string;
+  /** HTTP method. GET only in v1 (no modeled mutations). */
+  method?: 'GET';
+  /** Header map; values may interpolate `{{env.SECRET}}` (resolved server-side, never in markup). */
+  headers?: Record<string, string>;
+  /** Dot-path into the JSON response to the payload (e.g. "data.items"); empty = whole response. */
+  path?: string;
+  /** Shape of ONE result, discovered via /api/remote-sample. Drives binding autocomplete. */
+  fields?: Record<string, DataFieldType>;
+  /** 'object' (bind `{{name.field}}`) or 'list' (drives a list node). Default 'object'. */
+  cardinality?: 'object' | 'list';
+}
+
+/**
+ * SSR page data configuration embedded in page meta (`meta.data`, required when
+ * `meta.source === 'ssr'`). Each source key becomes a binding scope in the page body
+ * (`{{repo.stargazers_count}}`). The `getStaticPaths`-equivalent boilerplate
+ * (`const { … } = await loadPageData(meta.data, Astro)`) is derived by the emitter and
+ * skipped by the parser — `meta.data` is authoritative. See docs/meno-astro-ssr-page-type.md.
+ */
+export interface PageDataConfig {
+  /** Named data sources. The key becomes a binding scope in the body. */
+  sources: Record<string, PageDataSource>;
 }
 
 /**
@@ -73,15 +119,66 @@ export interface PageMetaData {
   ogType?: string;
   /** Translated slugs for each locale, e.g., { "en": "about", "pl": "o-nas" } */
   slugs?: Record<string, string>;
-  /** Data source: 'static' (default) or 'cms' */
-  source?: 'static' | 'cms';
+  /** Data source: 'static' (default), 'cms' (content collection), or 'ssr' (live per-request fetch) */
+  source?: 'static' | 'cms' | 'ssr';
   /** CMS configuration with embedded schema (required when source: 'cms') */
   cms?: PageCmsConfig;
+  /** SSR data-source configuration (required when source: 'ssr') */
+  data?: PageDataConfig;
+  /**
+   * Dynamic-route param names for an SSR page that lives at a `[param]` path
+   * (e.g. `["slug"]` for `src/pages/repo/[slug].astro`). When set on an `source: 'ssr'`
+   * page, the emitter exposes `const params = Astro.params` so the body can bind
+   * `{{params.<name>}}` and data-source URLs can interpolate `{{params.<name>}}`. The route
+   * is served on demand (no getStaticPaths) under `output: 'server'`.
+   */
+  routeParams?: string[];
+  /**
+   * Sample param values used ONLY to preview a dynamic `[param]` route in the editor — the
+   * editor loads e.g. `/repo/astro` instead of the un-matchable `/repo/[slug]`
+   * (`{ slug: "astro" }`). Editor-only hint; ignored at build/runtime.
+   */
+  routePreview?: Record<string, string>;
   /** Draft pages are excluded from static build, sitemap, and robots.txt */
   draft?: boolean;
   /** External libraries for this page (extends or replaces global) */
   libraries?: PageLibrariesConfig;
   /** Custom code injected into head/body for this page */
   customCode?: CustomCodeConfig;
+  /**
+   * Verbatim attributes of the source document's `<html>` element, preserved by the
+   * faithful-mirror importer (e.g. Webflow's `data-wf-page` / `data-wf-site`, which its
+   * client interaction engine reads to arm a page's interactions). BaseLayout spreads them
+   * onto its own `<html>` so a mirrored site boots its runtime exactly as the original —
+   * without them, e.g. a Webflow preloader never animates out. `lang` is excluded (BaseLayout
+   * owns it via locale routing).
+   */
+  htmlAttributes?: Record<string, string>;
+  /** Opt this page into Astro View Transitions (renders `<ClientRouter>` in the head) */
+  viewTransitions?: boolean;
+  /** Discourage search indexing (renders `<meta name="robots" content="noindex">`) */
+  noindex?: boolean;
+  /** Per-page sitemap settings (priority/changefreq/exclude) */
+  sitemap?: SitemapPageConfig;
+  /**
+   * Per-page static/SSR override, emitted as Astro's own top-level
+   * `export const prerender = <value>`. `true` forces this route to be statically
+   * generated, `false` makes it server-rendered on demand (requires SSR `output: 'server'`
+   * + an adapter). Omitted (undefined) → the route inherits the project's `output` default.
+   * CMS template routes always prerender (they depend on `getStaticPaths`), so this override
+   * applies only to regular pages.
+   */
+  prerender?: boolean;
 }
 
+/**
+ * Per-page sitemap settings (surfaced in the page SEO panel).
+ */
+export interface SitemapPageConfig {
+  /** Relative importance, 0.0–1.0 (sitemap `<priority>`). */
+  priority?: number;
+  /** Expected update cadence (sitemap `<changefreq>`). */
+  changefreq?: 'always' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly' | 'never';
+  /** Omit this page (and all locale variants) from the generated sitemap. */
+  exclude?: boolean;
+}

package/lib/shared/types/cms.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it } from 'bun:test';
+import { singularize } from './cms';
+
+describe('singularize', () => {
+  it('applies English plural→singular rules', () => {
+    expect(singularize('posts')).toBe('post');
+    expect(singularize('categories')).toBe('category'); // -ies → -y
+    expect(singularize('boxes')).toBe('box'); // -xes → -x
+    expect(singularize('classes')).toBe('class'); // -ses → -s
+    expect(singularize('people')).toBe('person'); // irregular
+  });
+
+  it('leaves an already-singular name unchanged', () => {
+    expect(singularize('author')).toBe('author');
+    expect(singularize('category')).toBe('category');
+  });
+
+  it('coerces a non-identifier collection name into a valid JS identifier', () => {
+    // The result is emitted as a `.map` loop variable, so it must be a legal identifier —
+    // a hyphenated/spaced/dotted collection name would otherwise emit `.map((case-study) => …)`.
+    expect(singularize('case-study')).toBe('caseStudy');
+    expect(singularize('case-study-category')).toBe('caseStudyCategory');
+    expect(singularize('blog posts')).toBe('blogPost'); // space-separated + pluralized last word
+    expect(singularize('2024-items')).toBe('_2024Item'); // leading digit gets prefixed
+  });
+
+  it('degrades a non-string / empty input to the generic `item` rather than throwing', () => {
+    expect(singularize('')).toBe('item');
+    // @ts-expect-error — defensive guard against undefined (was a hard crash: collection.endsWith)
+    expect(singularize(undefined)).toBe('item');
+    // @ts-expect-error — defensive guard against null
+    expect(singularize(null)).toBe('item');
+  });
+});