@kubex/zinc 1.1.94 → 1.1.95

package/src/components/page-builder/page-tree.ts

@@ -0,0 +1,329 @@
+import {
+  DEFAULT_WIDTHS,
+  defaultLayout,
+  generateSectionId,
+  isContainer,
+  MAX_COLUMNS,
+  MAX_CONTAINER_LEVELS,
+  MAX_SECTIONS,
+  type PageContainerLayout,
+  type PageSection,
+  type PageSectionType,
+  sanitiseWidths,
+} from './page.types';
+
+/** Clamps a requested column count into the supported range. */
+function columnCount(columns: number): number {
+  return Math.min(Math.max(Math.floor(columns) || 1, 1), MAX_COLUMNS);
+}
+
+/** Drops trailing cells that hold nothing. Interior empties are meaningful and kept. */
+export function trimTrailingEmptyCells(cells: PageSection[][]): PageSection[][] {
+  let end = cells.length;
+  while (end > 0 && cells[end - 1].length === 0) end--;
+  return cells.slice(0, end);
+}
+
+/** Pads to a whole number of rows, always leaving at least one row to drop into. */
+export function padCells(cells: PageSection[][], columns: number): PageSection[][] {
+  const cols = columnCount(columns);
+  const remainder = cells.length % cols;
+  const pad = cells.length === 0 ? cols : remainder === 0 ? 0 : cols - remainder;
+  return [...cells, ...Array.from({length: pad}, () => [] as PageSection[])];
+}
+
+/**
+ * The canonical cell list for a container. A growable container never keeps a
+ * trailing all-empty row (the renderer supplies the `+` row itself, so keeping
+ * one would show two); a fixed container's trailing empty row is its layout and
+ * survives untouched.
+ */
+export function normaliseCells(cells: PageSection[][], columns: number, grow: boolean): PageSection[][] {
+  return padCells(grow ? trimTrailingEmptyCells(cells) : cells, columns);
+}
+
+/**
+ * Re-chunks the same ordered list of stacks into a different column count. Only
+ * trailing empties are dropped, so no section can be lost by a column change.
+ */
+export function recolumnCells(cells: PageSection[][], columns: number): PageSection[][] {
+  return padCells(trimTrailingEmptyCells(cells), columns);
+}
+
+/** Row-major view of the flat cell list, for rendering. */
+export function cellRows(cells: PageSection[][], columns: number): PageSection[][][] {
+  const cols = columnCount(columns);
+  const rows: PageSection[][][] = [];
+  for (let i = 0; i < cells.length; i += cols) rows.push(cells.slice(i, i + cols));
+  return rows;
+}
+
+export function containerWidths(section: PageSection, type?: PageSectionType): number[] {
+  return sanitiseWidths(section.layout?.widths ?? type?.defaultWidths ?? [...DEFAULT_WIDTHS]);
+}
+
+export function containerColumns(section: PageSection, type?: PageSectionType): number {
+  return containerWidths(section, type).length;
+}
+
+export function containerGrow(section: PageSection, type?: PageSectionType): boolean {
+  return section.layout?.grow ?? Boolean(type?.defaultGrow);
+}
+
+/** A container's cells, normalised. Empty for a non-container. */
+export function containerCells(section: PageSection, type?: PageSectionType): PageSection[][] {
+  if (!isContainer(type)) return [];
+  return normaliseCells(section.cells ?? [], containerColumns(section, type), containerGrow(section, type));
+}
+
+/** Depth-first search across top-level sections and every cell stack. */
+export function findSection(sections: PageSection[], id: string | null): PageSection | undefined {
+  if (!id) return undefined;
+  for (const section of sections) {
+    if (section.id === id) return section;
+    for (const cell of section.cells ?? []) {
+      const hit = findSection(cell, id);
+      if (hit) return hit;
+    }
+  }
+  return undefined;
+}
+
+/** New section array with `id` replaced by `patch(section)`, wherever it lives. */
+export function patchSection(
+  sections: PageSection[],
+  id: string,
+  patch: (section: PageSection) => PageSection
+): PageSection[] {
+  return sections.map(section => {
+    if (section.id === id) return patch(section);
+    if (!section.cells) return section;
+    return {...section, cells: section.cells.map(cell => patchSection(cell, id, patch))};
+  });
+}
+
+/** Detaches a section from wherever it lives, returning it and the remaining tree. */
+export function extractSection(
+  sections: PageSection[],
+  id: string
+): [PageSection | undefined, PageSection[]] {
+  let removed: PageSection | undefined;
+  const out: PageSection[] = [];
+  for (const section of sections) {
+    if (section.id === id) {
+      removed = section;
+      continue;
+    }
+    if (section.cells) {
+      const cells = section.cells.map(cell => {
+        const [hit, rest] = extractSection(cell, id);
+        if (hit) removed = hit;
+        return rest;
+      });
+      out.push({...section, cells});
+    } else {
+      out.push(section);
+    }
+  }
+  return [removed, out];
+}
+
+/** Inserts a section into a container's cell at a stack position. */
+export function insertIntoCell(
+  sections: PageSection[],
+  containerId: string,
+  cellIndex: number,
+  insertIndex: number,
+  section: PageSection,
+  columns: number
+): PageSection[] {
+  return patchSection(sections, containerId, container => {
+    const cells = (container.cells ?? []).map(cell => [...cell]);
+    const target = Number.isFinite(cellIndex) ? Math.max(0, Math.floor(cellIndex)) : 0;
+    while (cells.length <= target) cells.push([]);
+    const cell = cells[target];
+    cell.splice(Math.max(0, Math.min(insertIndex, cell.length)), 0, section);
+    return {...container, cells: padCells(cells, columns)};
+  });
+}
+
+/**
+ * Nesting level of the container with this id: 1 at the top level, 2 inside a
+ * cell, 0 when not found. Only containers have cells, so every cell level is a
+ * container level.
+ */
+export function containerDepth(sections: PageSection[], containerId: string, depth = 1): number {
+  for (const section of sections) {
+    if (section.id === containerId) return depth;
+    for (const cell of section.cells ?? []) {
+      const hit = containerDepth(cell, containerId, depth + 1);
+      if (hit) return hit;
+    }
+  }
+  return 0;
+}
+
+/** Deep copy with a fresh id for the section and every descendant. */
+export function cloneWithNewIds(section: PageSection): PageSection {
+  const reid = (s: PageSection): PageSection => ({
+    ...structuredClone(s),
+    id: generateSectionId(),
+    ...(s.cells ? {cells: s.cells.map(cell => cell.map(reid))} : {}),
+  });
+  return reid(section);
+}
+
+/** Resolves a type key to its registered type — the registry's `get`. */
+export type TypeLookup = (type: string) => PageSectionType | undefined;
+
+/**
+ * Height of a container's subtree: 1 for a container with no nested containers,
+ * otherwise 1 + the tallest nested container's height. 0 for a non-container, so
+ * it composes with containerDepth to bound how deep a moved subtree would reach:
+ * dropping a section into a container at depth d puts the section's own deepest
+ * descendant at d + containerHeight(section).
+ */
+export function containerHeight(section: PageSection): number {
+  if (!section.cells) return 0;
+  const nested = section.cells.flat().map(containerHeight);
+  return 1 + Math.max(0, ...nested);
+}
+
+/**
+ * Re-applies each container's own grow/columns normalisation throughout the
+ * tree, so a growable container never carries a trailing all-empty row once
+ * committed — not only when read out via containerCells. A section whose
+ * current type isn't a registered container is left untouched, preserving its
+ * cells verbatim per the unknown-type contract.
+ */
+export function normaliseGrowth(sections: PageSection[], lookup: TypeLookup): PageSection[] {
+  return sections.map(section => {
+    if (!section.cells) return section;
+    const type = lookup(section.type);
+    if (!isContainer(type)) return section;
+    const cells = normaliseCells(section.cells, containerColumns(section, type), containerGrow(section, type))
+      .map(cell => normaliseGrowth(cell, lookup));
+    return {...section, cells};
+  });
+}
+
+/**
+ * Rewrites the pre-cells `children` shape as `cells`. The old grid was always
+ * DEFAULT_WIDTHS wide, and the slot count was the layout, so cells are padded
+ * out to the declared slot count, then rounded up to a whole number of
+ * DEFAULT_WIDTHS-wide rows; never trimmed.
+ */
+export function migrateSection(section: PageSection, type?: PageSectionType): PageSection {
+  if (!section.children) return section;
+  const {children, ...rest} = section;
+  const slots = type?.slots ?? children.length;
+  const cells = Array.from({length: slots}, (_, i) => {
+    const child = children[i];
+    return child && typeof child.type === 'string' ? [child] : [];
+  });
+  return {
+    ...rest,
+    layout: section.layout ?? {widths: [...DEFAULT_WIDTHS], grow: false},
+    cells: padCells(cells, DEFAULT_WIDTHS.length),
+  };
+}
+
+function isSectionLike(value: unknown): value is PageSection {
+  return Boolean(value) && typeof value === 'object' && typeof (value as PageSection).type === 'string';
+}
+
+/**
+ * Normalises externally supplied sections: migrates the old shape, gives every
+ * section a unique id, drops malformed entries, sanitises layouts, caps nesting
+ * and clamps sizes. Pure — warnings are returned for the caller to log.
+ */
+export function normaliseSections(
+  sections: unknown,
+  lookup: TypeLookup
+): {sections: PageSection[]; warnings: string[]} {
+  const warnings: string[] = [];
+  const seen = new Set<string>();
+  // A running admitted-section budget shared across every level, so 500 containers
+  // of 500 cells each can't slip past MAX_SECTIONS by hiding depth in nesting —
+  // only the top-level count was ever bounded before.
+  let remaining = MAX_SECTIONS;
+  let budgetExceeded = false;
+
+  const walk = (raw: PageSection, depth: number): PageSection | undefined => {
+    if (remaining <= 0) {
+      budgetExceeded = true;
+      return undefined;
+    }
+    remaining--;
+    const type = lookup(raw.type);
+    const migrated = migrateSection(raw, type);
+    const id = !migrated.id || seen.has(migrated.id) ? generateSectionId() : migrated.id;
+    seen.add(id);
+
+    const out: PageSection = {
+      id,
+      type: migrated.type,
+      label: migrated.label,
+      data: structuredClone(migrated.data ?? {}),
+    };
+
+    if (!migrated.cells) return out;
+
+    // A container past the cap keeps its identity but not its contents, so a
+    // malformed page loses as little as possible without unbounded recursion.
+    if (depth > MAX_CONTAINER_LEVELS) {
+      warnings.push(`container "${migrated.type}" exceeds ${MAX_CONTAINER_LEVELS} nesting levels; its cells were dropped`);
+      out.layout = sanitiseLayout(migrated.layout, type, warnings);
+      out.cells = [];
+      return out;
+    }
+
+    const layout = sanitiseLayout(migrated.layout, type, warnings);
+    // Slice to a whole number of rows (not MAX_SECTIONS itself) so the padding
+    // below is a no-op and the clamped length never overshoots MAX_SECTIONS.
+    const cols = layout.widths.length;
+    const maxCells = Math.floor(MAX_SECTIONS / cols) * cols;
+    let rawCells = migrated.cells;
+    if (rawCells.length > maxCells) {
+      warnings.push(`container "${migrated.type}" declared ${rawCells.length} cells; keeping the first ${maxCells}`);
+      rawCells = rawCells.slice(0, maxCells);
+    }
+
+    out.layout = layout;
+    out.cells = normaliseCells(
+      rawCells.map(cell => (Array.isArray(cell)
+        ? cell.filter(isSectionLike).map(child => walk(child, depth + 1)).filter(isDefined)
+        : [])),
+      layout.widths.length,
+      layout.grow
+    );
+    return out;
+  };
+
+  const incoming = (Array.isArray(sections) ? sections : []).filter(isSectionLike);
+  const kept = incoming.map(section => walk(section, 1)).filter(isDefined);
+  if (budgetExceeded) {
+    warnings.push(`page tree has more than ${MAX_SECTIONS} sections including nested ones; the rest were dropped`);
+  }
+  return {sections: kept, warnings};
+}
+
+function isDefined<T>(value: T | undefined): value is T {
+  return value !== undefined;
+}
+
+function sanitiseLayout(
+  layout: PageContainerLayout | undefined,
+  type: PageSectionType | undefined,
+  warnings: string[]
+): PageContainerLayout {
+  const seeded = defaultLayout(type);
+  if (!layout) return seeded;
+  const widths = sanitiseWidths(layout.widths);
+  const raw = layout.widths;
+  const unchanged = Array.isArray(raw) && raw.length === widths.length && raw.every((w, i) => w === widths[i]);
+  if (!unchanged) {
+    warnings.push(`container layout had unusable widths; corrected to ${widths.join(' ')}`);
+  }
+  return {widths, grow: Boolean(layout.grow)};
+}

package/src/components/page-builder/page.types.ts

@@ -8,10 +8,25 @@ export interface PageSection {
   label?: string;
   /** Section content, keyed by field name (the inspector's `name` attributes). */
   data: Record<string, unknown>;
-  /** Slot contents for container sections, sized to the type's `slots`. Empty slots are null. */
+  /** Container instances only: the editor-chosen layout. */
+  layout?: PageContainerLayout;
+  /** Container instances only: one ordered stack per cell, row-major. */
+  cells?: PageSection[][];
+  /**
+   * @deprecated The pre-cells fixed-slot shape. Read on load and migrated to
+   * `cells`; never written back.
+   */
   children?: (PageSection | null)[];
 }
 
+/** A container instance's editor-chosen layout. */
+export interface PageContainerLayout {
+  /** One weight per column; the array length IS the column count. */
+  widths: number[];
+  /** When true the builder offers a trailing empty row instead of a pinned cell count. */
+  grow: boolean;
+}
+
 /** The complete serialisable state of a page. Order = render order. */
 export interface PageState {
   sections: PageSection[];
@@ -38,18 +53,65 @@ export interface PageSectionType {
   configTemplate?: HTMLTemplateElement;
   /** Programmatic inspector body — takes precedence over `configTemplate`. */
   renderConfig?: (section: PageSection, update: (data: Record<string, unknown>) => void) => TemplateResult;
+  /** Marks this type a container: its card renders a grid of cells on the canvas. */
+  container?: boolean;
   /**
-   * Number of child slots this section offers on the canvas (a container tile);
-   * rendered as a 3-column grid. Containers cannot be placed inside other containers.
+   * Column weights a new instance of this container starts with. Stored as parsed, not
+   * guaranteed sanitised — route through `sanitiseWidths`/`defaultLayout` before use.
+   */
+  defaultWidths?: number[];
+  /** Whether a new instance of this container starts growable. */
+  defaultGrow?: boolean;
+  /**
+   * @deprecated Use `container` with `columns`/`widths`. Read as a container of
+   * `DEFAULT_WIDTHS` columns with the cell count pinned to this number.
    */
   slots?: number;
-  /** Section type keys allowed in this container's slots. Omit to allow any non-container type. */
+  /**
+   * Section type keys allowed in this container's cells. On a `container` type,
+   * omitting it allows any type, subject to the nesting cap — that is how nesting
+   * is reachable without enumerating types. The deprecated `slots=` alias keeps the
+   * old rule instead: omitting it there allows any non-container type.
+   */
   accepts?: string[];
 }
 
-/** A container section's slot contents, padded/truncated to the type's slot count. */
-export function sectionChildren(section: PageSection, type: PageSectionType): (PageSection | null)[] {
-  return Array.from({length: type.slots ?? 0}, (_, i) => section.children?.[i] ?? null);
+/** Beyond 6 columns a card is under ~170px on the 1024px canvas — unreadable. */
+export const MAX_COLUMNS = 6;
+/** A single weight beyond 12 makes the other columns unusably thin. */
+export const MAX_WIDTH = 12;
+/** Container nesting levels: a top-level container is 1, one inside a cell is 2. */
+export const MAX_CONTAINER_LEVELS = 2;
+/** Global section budget; also the sanity clamp on an incoming `cells` length. */
+export const MAX_SECTIONS = 500;
+/** What a bare `container` declaration seeds. */
+export const DEFAULT_WIDTHS: readonly number[] = [1, 1, 1];
+
+/** Container-ness is a property of the registered type, never of the instance. */
+export function isContainer(type: PageSectionType | undefined): boolean {
+  return Boolean(type?.container ?? (type?.slots !== undefined && type.slots > 0));
+}
+
+/**
+ * Coerces a weights list into a usable one: each entry a whole number from 1 to
+ * MAX_WIDTH (anything unusable becomes 1), at most MAX_COLUMNS entries, falling
+ * back to DEFAULT_WIDTHS only when nothing usable remains.
+ */
+export function sanitiseWidths(raw: unknown): number[] {
+  const list = Array.isArray(raw) ? raw.slice(0, MAX_COLUMNS) : [];
+  const clean = list.map(entry => {
+    const n = typeof entry === 'number' && Number.isFinite(entry) ? Math.floor(entry) : 1;
+    return Math.min(Math.max(n, 1), MAX_WIDTH);
+  });
+  return clean.length ? clean : [...DEFAULT_WIDTHS];
+}
+
+/** The layout a newly placed instance of a container type starts with. */
+export function defaultLayout(type: PageSectionType | undefined): PageContainerLayout {
+  return {
+    widths: sanitiseWidths(type?.defaultWidths ?? [...DEFAULT_WIDTHS]),
+    grow: Boolean(type?.defaultGrow),
+  };
 }
 
 /** Drag-and-drop MIME carrying a section type id from the palette to the canvas. */
@@ -85,6 +147,12 @@ function optionLabel(type: PageSectionType | undefined, name: string, value: str
  * so a tile reads as its linked item however its other fields were filled in.
  */
 export function sectionSummary(section: PageSection, type?: PageSectionType): string {
+  if (isContainer(type)) {
+    const columns = sanitiseWidths(section.layout?.widths ?? type?.defaultWidths).length;
+    const count = (section.cells ?? []).reduce((n, cell) => n + cell.length, 0);
+    const col = `${columns} column${columns === 1 ? '' : 's'}`;
+    return `${col} · ${count} section${count === 1 ? '' : 's'}`;
+  }
   const strings = Object.entries(section.data)
     .filter((entry): entry is [string, string] => typeof entry[1] === 'string' && entry[1].trim() !== '');
   for (const [name, value] of strings) {