@cratis/scene.engine 4.25.0 → 4.27.0

package/navigation/navigationEdits.ts

@@ -0,0 +1,176 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ApplicationLogo, NavigationModel, NavigationRegion, NavigationRegionKind, NavigationRegionMode, NavItem } from '@cratis/scene.model';
+import { NavigationEdit } from './NavigationEdit';
+import { NavigationEditKind } from './NavigationEditKind';
+import { NavigationEditOutcome } from './NavigationEditOutcome';
+import { NavigationEditPlan } from './NavigationEditPlan';
+import { applicationItems, collectItemIds, findModuleNavigation, findNavigationRegion, modeOfModuleRegion } from './navigationRegions';
+
+const noMode = 'The application is the base of the navigation and has no region mode.';
+const logoLevel = 'The logo is defined at the application level only.';
+const flatTopbar = 'A topbar is flat; only a sidebar item has sub-items.';
+
+/**
+ * Plans a change of a module region's mode. Switching to `inherit` clears the module's items (NAV3); switching from
+ * `inherit` to `override` with `copy` first copies the application's items so the module starts from them (NAV5).
+ * @param navigation The navigation as it is.
+ * @param module The module whose region changes; the application has no mode and is refused.
+ * @param region The region.
+ * @param mode The mode to switch to.
+ * @param options `copy` copies the application items when switching from inherit to override.
+ */
+export function switchRegionMode(
+    navigation: NavigationModel,
+    module: string | undefined,
+    region: NavigationRegionKind,
+    mode: NavigationRegionMode,
+    options: { copy?: boolean } = {},
+): NavigationEditPlan {
+    if (module === undefined) return { edits: [], rejected: noMode };
+
+    const current = modeOfModuleRegion(navigation, module, region);
+    if (current === mode) return { edits: [] };
+
+    const setMode: NavigationEdit = { kind: NavigationEditKind.SetRegionMode, module, region, mode };
+    if (mode === NavigationRegionMode.Inherit) {
+        return { edits: [{ kind: NavigationEditKind.SetRegionItems, module, region, items: [] }, setMode] };
+    }
+
+    if (mode === NavigationRegionMode.Override && current === NavigationRegionMode.Inherit && options.copy === true) {
+        return { edits: [{ kind: NavigationEditKind.SetRegionItems, module, region, items: structuredClone(applicationItems(navigation.application, region)) }, setMode] };
+    }
+
+    return { edits: [setMode] };
+}
+
+/**
+ * Plans adding an item to a region, after the ones already there. Adding to an inheriting module region first
+ * switches it to `extend` (NAV6), so the application's items stay and the new item follows them.
+ * @param navigation The navigation as it is.
+ * @param module The module that gets the item; undefined for the application.
+ * @param region The region.
+ * @param item The item to add.
+ * @param parent The id of the item it becomes a sub-item of; sidebar only.
+ */
+export function addNavItem(
+    navigation: NavigationModel,
+    module: string | undefined,
+    region: NavigationRegionKind,
+    item: NavItem,
+    parent?: string,
+): NavigationEditPlan {
+    if (parent !== undefined && region !== NavigationRegionKind.Sidebar) return { edits: [], rejected: flatTopbar };
+
+    const own = ownItems(navigation, module, region);
+    const ids = collectItemIds(own, region);
+    if (ids.includes(item.id)) return { edits: [], rejected: `Navigation item id '${item.id}' is already used in this region.` };
+    if (parent !== undefined && !ids.includes(parent)) return { edits: [], rejected: `There is no item '${parent}' to add a sub-item to.` };
+
+    const add: NavigationEdit = { kind: NavigationEditKind.AddItem, module, region, item: structuredClone(item) };
+    if (parent !== undefined) add.parent = parent;
+    if (module !== undefined && modeOfModuleRegion(navigation, module, region) === NavigationRegionMode.Inherit) {
+        return { edits: [{ kind: NavigationEditKind.SetRegionMode, module, region, mode: NavigationRegionMode.Extend }, add] };
+    }
+
+    return { edits: [add] };
+}
+
+/**
+ * Plans setting the logo. The logo is defined at the application level only, so a module is refused.
+ * @param navigation The navigation as it is.
+ * @param module The module asking; only undefined (the application) is allowed.
+ * @param logo The logo.
+ */
+export function setApplicationLogo(navigation: NavigationModel, module: string | undefined, logo: ApplicationLogo): NavigationEditPlan {
+    void navigation;
+    return module === undefined ? { edits: [{ kind: NavigationEditKind.SetLogo, logo: { ...logo } }] } : { edits: [], rejected: logoLevel };
+}
+
+/**
+ * Applies navigation edits to a copy of the model. Either every edit applies, or none does.
+ * @param navigation The navigation as it is; never changed.
+ * @param edits The edits, in order.
+ */
+export function applyNavigationEdits(navigation: NavigationModel, edits: NavigationEdit[]): NavigationEditOutcome {
+    const model = structuredClone(navigation);
+    for (const edit of edits) {
+        const rejected = apply(model, edit);
+        if (rejected !== undefined) return { applied: false, model: navigation, rejected };
+    }
+
+    return { applied: true, model };
+}
+
+function ownItems(navigation: NavigationModel, module: string | undefined, region: NavigationRegionKind): NavItem[] {
+    return module === undefined
+        ? applicationItems(navigation.application, region)
+        : findNavigationRegion(findModuleNavigation(navigation, module)?.regions, region)?.items ?? [];
+}
+
+function regionOf(model: NavigationModel, module: string | undefined, region: NavigationRegionKind): NavigationRegion {
+    let regions: NavigationRegion[];
+    if (module === undefined) {
+        regions = model.application.regions;
+    } else {
+        let block = findModuleNavigation(model, module);
+        if (!block) {
+            block = { module, regions: [] };
+            model.modules.push(block);
+        }
+
+        regions = block.regions;
+    }
+
+    let found = findNavigationRegion(regions, region);
+    if (!found) {
+        found = { region, items: [] };
+        regions.push(found);
+    }
+
+    return found;
+}
+
+function apply(model: NavigationModel, edit: NavigationEdit): string | undefined {
+    switch (edit.kind) {
+        case NavigationEditKind.SetRegionMode:
+            if (edit.module === undefined) return noMode;
+            regionOf(model, edit.module, edit.region!).mode = edit.mode;
+            return undefined;
+        case NavigationEditKind.SetRegionItems:
+            regionOf(model, edit.module, edit.region!).items = structuredClone(edit.items ?? []);
+            return undefined;
+        case NavigationEditKind.AddItem: {
+            const target = regionOf(model, edit.module, edit.region!);
+            const item = structuredClone(edit.item!);
+            if (collectItemIds(target.items, target.region).includes(item.id)) return `Navigation item id '${item.id}' is already used in this region.`;
+            if (edit.parent === undefined) {
+                target.items.push(item);
+                return undefined;
+            }
+
+            if (target.region !== NavigationRegionKind.Sidebar) return flatTopbar;
+            const owner = findItem(target.items, edit.parent);
+            if (!owner) return `There is no item '${edit.parent}' to add a sub-item to.`;
+            (owner.children ??= []).push(item);
+            return undefined;
+        }
+        case NavigationEditKind.SetLogo:
+            if (edit.module !== undefined) return logoLevel;
+            model.application.logo = { ...edit.logo! };
+            return undefined;
+        default:
+            return `'${String((edit as NavigationEdit).kind)}' is not a navigation edit.`;
+    }
+}
+
+function findItem(items: NavItem[], id: string): NavItem | undefined {
+    for (const item of items) {
+        if (item.id === id) return item;
+        const nested = findItem(item.children ?? [], id);
+        if (nested) return nested;
+    }
+
+    return undefined;
+}

package/navigation/navigationRegions.ts

@@ -0,0 +1,39 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ApplicationNavigation, ModuleNavigation, NavigationModel, NavigationRegion, NavigationRegionKind, NavigationRegionMode, NavItem } from '@cratis/scene.model';
+
+/** The regions in the order every result lists them. */
+export const navigationRegionOrder: NavigationRegionKind[] = [NavigationRegionKind.Topbar, NavigationRegionKind.Sidebar];
+
+/** The slot an item renders into when it names none: the primary outlet. */
+export const primarySlot = 'content';
+
+/**
+ * Finds the items a level defines for a region.
+ * @param regions The regions of the application or of a module.
+ * @param region The region to look for.
+ */
+export function findNavigationRegion(regions: NavigationRegion[] | undefined, region: NavigationRegionKind): NavigationRegion | undefined {
+    return regions?.find(candidate => candidate.region === region);
+}
+
+/** Finds what a module declares; undefined when it declares nothing. */
+export function findModuleNavigation(navigation: NavigationModel, module: string): ModuleNavigation | undefined {
+    return navigation.modules.find(candidate => candidate.module === module);
+}
+
+/** The mode of a module's region: `inherit` when the module does not declare the region or its mode. */
+export function modeOfModuleRegion(navigation: NavigationModel, module: string, region: NavigationRegionKind): NavigationRegionMode {
+    return findNavigationRegion(findModuleNavigation(navigation, module)?.regions, region)?.mode ?? NavigationRegionMode.Inherit;
+}
+
+/** The application-level items of a region. */
+export function applicationItems(application: ApplicationNavigation, region: NavigationRegionKind): NavItem[] {
+    return findNavigationRegion(application.regions, region)?.items ?? [];
+}
+
+/** Every id in a list of items, depth first. Sub-items count only in the sidebar. */
+export function collectItemIds(items: NavItem[], region: NavigationRegionKind): string[] {
+    return items.flatMap(item => [item.id, ...(region === NavigationRegionKind.Sidebar ? collectItemIds(item.children ?? [], region) : [])]);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cratis/scene.engine",
-    "version": "4.25.0",
+    "version": "4.27.0",
     "description": "The Scene runtime: walks a Scene element tree and drives whichever renderer is plugged in. Does not know React, or any other rendering platform, exists.",
     "keywords": [
         "cratis",
@@ -48,9 +48,9 @@
         "up": "yarn g:up"
     },
     "dependencies": {
-        "@cratis/scene.model": "4.25.0"
+        "@cratis/scene.model": "4.27.0"
     },
     "devDependencies": {
-        "@cratis/scene.model": "4.25.0"
+        "@cratis/scene.model": "4.27.0"
     }
 }

package/sampleData/SampleDataPackSource.ts

@@ -0,0 +1,13 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { SampleDataPack, ScenePackage } from '@cratis/scene.model';
+
+/**
+ * A package and the sample-data packs it ships, loaded. A React `ScenePackageBundle` already has the manifest;
+ * hosts add the loaded packs the manifest's `sampleData` references point to.
+ */
+export interface SampleDataPackSource {
+    manifest: ScenePackage;
+    packs?: SampleDataPack[];
+}

package/sampleData/SampleDataResolution.ts

@@ -0,0 +1,93 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { SampleDataPack, SampleShape, UiProfile } from '@cratis/scene.model';
+
+/** Which rung of the resolution order supplied the rows. */
+export type SampleDataResolutionSource =
+    /** A pack explicitly bound to the read model or shape. */
+    | 'binding'
+    /** The application's active pack: the profile's `sampleData.activePack`, or the session override. */
+    | 'activePack'
+    /** The default pack of the blueprint the template came from. */
+    | 'blueprintDefault'
+    /** Generated, typed by field kind. */
+    | 'generated'
+    /** Not resolved, because the host is not in design or preview mode (SD6). */
+    | 'disabled'
+    /** No pack had rows and no shape was given to generate from. */
+    | 'none';
+
+/** What is being asked for: rows for a read model or shape. */
+export interface SampleDataRequest {
+    /** The read model or shape name; defaults to the `shape`'s name when only a shape is given. */
+    target?: string;
+
+    /** The shape of one row; needed for the generated rung to produce anything. */
+    shape?: SampleShape;
+}
+
+/** What the host knows when it asks for sample data. */
+export interface SampleDataContext {
+    /** Every pack available: blueprint packs and the author's own. */
+    packs: SampleDataPack[];
+
+    /**
+     * The application's UI profile, whose `sampleData` is the one place the active pack is chosen (plus the
+     * rare mappings and bindings). Absent, or a profile without `sampleData`, behaves as no active pack, no
+     * mappings and no bindings.
+     */
+    profile?: Pick<UiProfile, 'sampleData'>;
+
+    /**
+     * A session-only override of the profile's active pack, as the preview strip's selector sets it: a pack
+     * id replaces `profile.sampleData.activePack`, the empty string (the generated entry's id) means no
+     * active pack, and `undefined` (absent) leaves the profile's choice. It is never a second source of truth: it is not stored, and bindings and
+     * mappings still come from the profile.
+     */
+    sessionActivePack?: string;
+
+    /** The default pack of the blueprint the template came from. */
+    blueprintDefaultPack?: string;
+
+    /** The locale of generated data when no pack supplies one; defaults to `en-GB`. */
+    locale?: string;
+
+    /** The seed for generated data; defaults to 1 so previews are stable. */
+    seed?: number;
+
+    /** The number of generated rows; defaults to 5. */
+    rowCount?: number;
+
+    /**
+     * Whether the host is design time or preview. Sample data resolves only when this is true; a Stage
+     * production build leaves it false (the default) and gets nothing (SD6).
+     */
+    isDesignOrPreview?: boolean;
+}
+
+/** A problem found while resolving, which never stops the resolution falling through to the next rung. */
+export interface SampleDataDiagnostic {
+    /** `packNotFound` or `shapeNotInPack`. */
+    code: string;
+    message: string;
+}
+
+/** The outcome of {@link resolveSampleData}. */
+export interface SampleDataResolution {
+    /** Which rung supplied the rows. */
+    source: SampleDataResolutionSource;
+
+    /** The identity of the pack that supplied the rows; absent for generated, disabled and none. */
+    pack?: string;
+
+    /** The locale of the data: the pack's, or the one generated data followed. */
+    locale: string;
+
+    /** The shape name the rows belong to. */
+    shape?: string;
+
+    rows: Record<string, unknown>[];
+
+    diagnostics: SampleDataDiagnostic[];
+}

package/sampleData/SampleRandom.ts

@@ -0,0 +1,85 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * The pseudo-random generator behind generated sample data. The C# engine implements the identical
+ * algorithm, and both are asserted against golden rows in `sample-data-resolution-fixtures.json`.
+ *
+ * Algorithm (all arithmetic on unsigned 32-bit integers, wrapping):
+ *
+ * - `hash32(x)`: `x = (x ^ (x >>> 16)) * 0x85EBCA6B; x = (x ^ (x >>> 13)) * 0xC2B2AE35; return x ^ (x >>> 16)`.
+ * - `splitmix32(state)`: `state += 0x9E3779B9`, then `hash32(state)`.
+ * - `fnv1a32(text)`: FNV-1a over the UTF-8 bytes of the text (offset basis `0x811C9DC5`, prime `0x01000193`).
+ * - The generator is xoshiro128** seeded with four consecutive `splitmix32` outputs of the seed.
+ * - `nextInt(bound)` is `next() % bound`.
+ * - Row `i` of a shape named `S` generated with seed `n` uses its own generator seeded with
+ *   `hash32((n ^ fnv1a32(S)) + (i + 1) * 0x9E3779B9)`, so a row never depends on how many rows are asked for.
+ */
+export function hash32(value: number): number {
+    let x = value >>> 0;
+    x = Math.imul(x ^ (x >>> 16), 0x85EBCA6B) >>> 0;
+    x = Math.imul(x ^ (x >>> 13), 0xC2B2AE35) >>> 0;
+    return (x ^ (x >>> 16)) >>> 0;
+}
+
+/** FNV-1a (32-bit) over the UTF-8 bytes of a string. */
+export function fnv1a32(text: string): number {
+    let hash = 0x811C9DC5;
+    for (const byte of new TextEncoder().encode(text)) {
+        hash = Math.imul(hash ^ byte, 0x01000193) >>> 0;
+    }
+    return hash;
+}
+
+/** The seed of the generator for one row of one shape. */
+export function rowSeed(seed: number, shapeName: string, rowIndex: number): number {
+    return hash32((((seed ^ fnv1a32(shapeName)) >>> 0) + Math.imul(rowIndex + 1, 0x9E3779B9)) >>> 0);
+}
+
+/** xoshiro128** with splitmix32 seeding. */
+export class SampleRandom {
+    private s0: number;
+    private s1: number;
+    private s2: number;
+    private s3: number;
+
+    constructor(seed: number) {
+        let state = seed >>> 0;
+        const step = () => {
+            state = (state + 0x9E3779B9) >>> 0;
+            return hash32(state);
+        };
+        this.s0 = step();
+        this.s1 = step();
+        this.s2 = step();
+        this.s3 = step();
+        if ((this.s0 | this.s1 | this.s2 | this.s3) === 0) this.s0 = 1;
+    }
+
+    /** The next unsigned 32-bit value. */
+    next(): number {
+        const result = Math.imul(rotateLeft(Math.imul(this.s1, 5) >>> 0, 7), 9) >>> 0;
+        const t = (this.s1 << 9) >>> 0;
+        this.s2 = (this.s2 ^ this.s0) >>> 0;
+        this.s3 = (this.s3 ^ this.s1) >>> 0;
+        this.s1 = (this.s1 ^ this.s2) >>> 0;
+        this.s0 = (this.s0 ^ this.s3) >>> 0;
+        this.s2 = (this.s2 ^ t) >>> 0;
+        this.s3 = rotateLeft(this.s3, 11);
+        return result;
+    }
+
+    /** A value in `[0, bound)`; zero when the bound is zero. */
+    nextInt(bound: number): number {
+        return bound <= 0 ? 0 : this.next() % bound;
+    }
+
+    /** One element of a non-empty list. */
+    pick<T>(items: readonly T[]): T {
+        return items[this.nextInt(items.length)];
+    }
+}
+
+function rotateLeft(value: number, bits: number): number {
+    return ((value << bits) | (value >>> (32 - bits))) >>> 0;
+}

package/sampleData/describeSampleDataCatalog.ts

@@ -0,0 +1,108 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { SampleDataPackReference, ScenePackage } from '@cratis/scene.model';
+import { SampleDataPackSource } from './SampleDataPackSource';
+import { validateSampleDataPackages } from './validateSampleDataPackages';
+
+/** The separator between blueprint and pack in a label (`CRM · Nordic SMB`). */
+export const sampleDataLabelSeparator = ' \u00b7 ';
+
+/** One entry of the sample data selector. */
+export interface SampleDataCatalogEntry {
+    /** The pack identity a selection stores as `activePack`; empty for the generated entry. */
+    id: string;
+
+    /** Whether this is the generated entry, the choice that stores no active pack. */
+    isGenerated: boolean;
+
+    /** The pack's name within its group (`Nordic SMB`). */
+    name: string;
+
+    /** The full label (`CRM · Nordic SMB`, or just the name for generated and own packs). */
+    label: string;
+
+    /** The locale tag, absent for the generated entry. */
+    locale?: string;
+
+    /** Whether it is the active pack (the generated entry is selected when no pack is active). */
+    selected: boolean;
+}
+
+/** A blueprint's packs, one group of the Blueprints submenu. */
+export interface SampleDataCatalogGroup {
+    /** The blueprint's display name (`CRM`). */
+    blueprint: string;
+
+    packs: SampleDataCatalogEntry[];
+}
+
+/** The selector's content: generated, the author's own sets, then blueprint groups. */
+export interface SampleDataCatalog {
+    /** `Generic (typed by field kind)`. */
+    generated: SampleDataCatalogEntry;
+
+    /** The author's own data sets, in the order given. */
+    own: SampleDataCatalogEntry[];
+
+    /** Blueprints that ship at least one pack, in package order; blueprints with none are not listed. */
+    blueprints: SampleDataCatalogGroup[];
+
+    /** Problems found validating what the packages ship. */
+    problems: string[];
+}
+
+/** The name of the generated entry. */
+export const generatedSampleDataName = 'Generic (typed by field kind)';
+
+/**
+ * Describes the sample data selector's content: the generated entry first, then the author's own packs, then
+ * each blueprint's packs grouped by the blueprint's display name (falling back to its package name). A pack
+ * whose title already starts with `<Blueprint> · ` shows the rest as its name, so `CRM · Nordic SMB` under
+ * `CRM` is `Nordic SMB`. Same own-first, then Blueprints menu pattern as the template picker (spec §11).
+ *
+ * @param sources The packages and the packs they ship (only their `sampleData` references are listed).
+ * @param ownPacks The author's own packs (id, title, locale).
+ * @param activePack The selection's active pack id, if any.
+ */
+export function describeSampleDataCatalog(
+    sources: readonly SampleDataPackSource[],
+    ownPacks: readonly Pick<SampleDataPackReference, 'id' | 'title' | 'locale'>[] = [],
+    activePack?: string,
+): SampleDataCatalog {
+    const entry = (id: string, name: string, label: string, locale: string): SampleDataCatalogEntry => ({
+        id, isGenerated: false, name, label, locale, selected: id === activePack,
+    });
+
+    const blueprints: SampleDataCatalogGroup[] = [];
+    for (const source of sources) {
+        const references = source.manifest.sampleData ?? [];
+        if (references.length === 0) continue;
+        const group = groupName(source.manifest);
+        const prefix = `${group}${sampleDataLabelSeparator}`;
+        blueprints.push({
+            blueprint: group,
+            packs: references.map(reference => {
+                const name = reference.title.startsWith(prefix) ? reference.title.slice(prefix.length) : reference.title;
+                return entry(reference.id, name, `${group}${sampleDataLabelSeparator}${name}`, reference.locale);
+            }),
+        });
+    }
+
+    return {
+        generated: {
+            id: '',
+            isGenerated: true,
+            name: generatedSampleDataName,
+            label: generatedSampleDataName,
+            selected: activePack === undefined || activePack === null || activePack === '',
+        },
+        own: ownPacks.map(pack => entry(pack.id, pack.title, pack.title, pack.locale)),
+        blueprints,
+        problems: validateSampleDataPackages(sources),
+    };
+}
+
+function groupName(manifest: ScenePackage): string {
+    return manifest.displayName !== undefined && manifest.displayName.trim() !== '' ? manifest.displayName : manifest.name;
+}

package/sampleData/findSampleDataSet.ts

@@ -0,0 +1,18 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { SampleDataMapping, SampleDataPack, SampleDataSet } from '@cratis/scene.model';
+
+/**
+ * Finds the set of a pack that supplies rows for a read model or shape. An explicit mapping whose read model is
+ * the target wins; otherwise a set whose shape has the target's name (compared exactly, case-sensitively).
+ */
+export function findSampleDataSet(pack: SampleDataPack, target: string, mappings: readonly SampleDataMapping[] = []): SampleDataSet | undefined {
+    for (const mapping of mappings) {
+        if (mapping.readModel !== target) continue;
+        const mapped = (pack.sets ?? []).find(set => set.shape === mapping.shape);
+        if (mapped !== undefined) return mapped;
+    }
+
+    return (pack.sets ?? []).find(set => set.shape === target);
+}

package/sampleData/findSampleRowLiterals.ts

@@ -0,0 +1,86 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ComponentDescriptor } from '@cratis/scene.model';
+
+/**
+ * Finds sample-row literals inside a value: an array holding plain objects of two or more keys, which is what
+ * a hand-written list of demo rows looks like. Returns the path of each, e.g. `rows` or `items[2].children`.
+ * A single-key object is a choice or a token, not a row, and is not reported.
+ *
+ * Spec §11 SD1: components keep declaring shapes only, so a component descriptor's defaults and a template's
+ * properties must not carry row literals; demo rows belong to sample-data packs.
+ *
+ * @param value The value to inspect.
+ * @param path The path prefix of the value, empty for the root.
+ */
+export function findSampleRowLiterals(value: unknown, path = ''): string[] {
+    const found: string[] = [];
+    if (Array.isArray(value)) {
+        if (value.some(isRow)) found.push(path === '' ? '(root)' : path);
+        value.forEach((item, index) => found.push(...findSampleRowLiterals(item, `${path}[${index}]`)));
+    } else if (typeof value === 'object' && value !== null) {
+        for (const [key, child] of Object.entries(value)) {
+            found.push(...findSampleRowLiterals(child, path === '' ? key : `${path}.${key}`));
+        }
+    }
+
+    return found;
+}
+
+/**
+ * Finds the sample-row literals in the defaults of component descriptors, as `<component>: <property path>`
+ * entries (the property path is followed by the location inside the default).
+ *
+ * @param descriptors The descriptors to inspect.
+ */
+export function findDescriptorSampleRowLiterals(descriptors: readonly ComponentDescriptor[]): string[] {
+    const found: string[] = [];
+    for (const descriptor of descriptors) {
+        for (const property of descriptor.properties ?? []) {
+            for (const location of findSampleRowLiterals(property.default)) {
+                const suffix = location === '(root)' ? '' : (location.startsWith('[') ? location : `.${location}`);
+                found.push(`${descriptor.component}: ${property.path}${suffix}`);
+            }
+        }
+    }
+
+    return found;
+}
+
+function isRow(item: unknown): boolean {
+    return typeof item === 'object' && item !== null && !Array.isArray(item) && Object.keys(item).length >= 2;
+}
+
+/** The part of a scene element the scan reads: its properties and the child elements in its slots. */
+interface ScannedElement {
+    componentName?: string;
+    properties?: Record<string, unknown>;
+    slots?: Record<string, ScannedElement[]>;
+}
+
+/**
+ * Finds the sample-row literals in the element properties of a template's content, as
+ * `<componentName>.<property>` entries (with the location inside the value when it is nested). Only property
+ * values are scanned: the element tree itself is made of objects and is not data.
+ *
+ * @param content A template's content, keyed by slot name.
+ */
+export function findTemplateSampleRowLiterals(content: Record<string, ScannedElement[]> | undefined): string[] {
+    const found: string[] = [];
+    const visit = (elements: ScannedElement[] | undefined) => {
+        for (const element of elements ?? []) {
+            for (const [name, value] of Object.entries(element.properties ?? {})) {
+                for (const location of findSampleRowLiterals(value)) {
+                    const suffix = location === '(root)' ? '' : (location.startsWith('[') ? location : `.${location}`);
+                    found.push(`${element.componentName ?? '(unnamed)'}.${name}${suffix}`);
+                }
+            }
+
+            Object.values(element.slots ?? {}).forEach(visit);
+        }
+    };
+
+    Object.values(content ?? {}).forEach(visit);
+    return found;
+}