@cratis/scene.engine 4.24.0 → 4.26.0

package/index.ts

@@ -43,4 +43,5 @@ export * from './resolveStrings';
 export * from './navigation';
 export * from './validateNavigationDestinations';
 export * from './editing';
+export * from './sampleData';
 export * from './structure';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cratis/scene.engine",
-    "version": "4.24.0",
+    "version": "4.26.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.24.0"
+        "@cratis/scene.model": "4.26.0"
     },
     "devDependencies": {
-        "@cratis/scene.model": "4.24.0"
+        "@cratis/scene.model": "4.26.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;
+}

package/sampleData/generateSample.ts

@@ -0,0 +1,156 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { SampleFieldKind, SampleShape, SampleShapeField } from '@cratis/scene.model';
+import { inferSampleFieldKind } from './inferSampleFieldKind';
+import { SampleLocale, sampleLocaleFor } from './sampleLocales';
+import { SampleRandom, rowSeed } from './SampleRandom';
+
+/** The seed used when none is given, so previews are stable without any configuration. */
+export const defaultSampleSeed = 1;
+
+/** How many rows are generated when no count is given. */
+export const defaultSampleRowCount = 5;
+
+/** The most rows one call generates. */
+export const maximumSampleRowCount = 1000;
+
+/** Days since 1970-01-01 of 2024-01-01, the anchor generated dates count forward from. */
+const anchorDay = 19723;
+
+/** Generated dates fall within this many days after the anchor. */
+const dateSpanDays = 731;
+
+/**
+ * Generates `rowCount` rows of a shape, deterministically for a seed: the same shape, seed, row count and
+ * locale yield the same rows (byte-identical once serialized) in the C# and TypeScript engines.
+ *
+ * Each row has its own generator (see {@link rowSeed}), so row `i` is the same however many rows are asked
+ * for. Within a row the fields are generated in declaration order. A nullable field first draws whether it is
+ * null (one in five is) and then always draws its value, so the sequence never depends on nullability
+ * outcomes. Values follow the field's kind and locale; enum fields only ever produce one of their values,
+ * dates stay within 2024-2025 and amounts have two decimals.
+ *
+ * @param shape The shape to generate rows for.
+ * @param seed The seed; defaults to {@link defaultSampleSeed}.
+ * @param rowCount The number of rows; defaults to {@link defaultSampleRowCount}, clamped to `[0, 1000]`.
+ * @param locale The BCP 47 locale tag selecting names, cities and formats; unknown tags use the default pool.
+ */
+export function generateSample(shape: SampleShape, seed?: number, rowCount?: number, locale?: string): Record<string, unknown>[] {
+    const count = Math.min(Math.max(Math.trunc(rowCount ?? defaultSampleRowCount), 0), maximumSampleRowCount);
+    const effectiveSeed = (seed ?? defaultSampleSeed) >>> 0;
+    const pool = sampleLocaleFor(locale);
+    const rows: Record<string, unknown>[] = [];
+
+    for (let index = 0; index < count; index++) {
+        const random = new SampleRandom(rowSeed(effectiveSeed, shape.name, index));
+        const row: Record<string, unknown> = {};
+        for (const field of shape.fields) {
+            const isNull = field.nullable === true && random.nextInt(5) === 0;
+            const value = generateValue(field, inferSampleFieldKind(field), random, pool);
+            row[field.name] = isNull ? null : value;
+        }
+        rows.push(row);
+    }
+
+    return rows;
+}
+
+function generateValue(field: SampleShapeField, kind: SampleFieldKind, random: SampleRandom, pool: SampleLocale): unknown {
+    switch (kind) {
+        case SampleFieldKind.Id:
+            return generateId(random);
+        case SampleFieldKind.Name:
+            return `${random.pick(pool.firstNames)} ${random.pick(pool.lastNames)}`;
+        case SampleFieldKind.Company:
+            return random.pick(pool.companies);
+        case SampleFieldKind.Email: {
+            const first = random.pick(pool.firstNames);
+            const last = random.pick(pool.lastNames);
+            return `${slug(first)}.${slug(last)}@${random.pick(pool.domains)}`;
+        }
+        case SampleFieldKind.Phone:
+            return [...pool.phoneTemplate].map(character => (character === '#' ? String(random.nextInt(10)) : character)).join('');
+        case SampleFieldKind.City:
+            return random.pick(pool.cities);
+        case SampleFieldKind.Text: {
+            const words = Array.from({ length: 3 + random.nextInt(4) }, () => random.pick(pool.words));
+            return capitalize(words.join(' '));
+        }
+        case SampleFieldKind.WholeNumber: {
+            const [low, high] = range(field.min, field.max, 0, 1000, Math.trunc);
+            return low + random.nextInt(high - low + 1);
+        }
+        case SampleFieldKind.Amount: {
+            const [low, high] = range(field.min, field.max, 10, 5000, value => Math.floor(value * 100 + 0.5));
+            return (low + random.nextInt(high - low + 1)) / 100;
+        }
+        case SampleFieldKind.Boolean:
+            return random.nextInt(2) === 1;
+        case SampleFieldKind.Date:
+            return formatDay(anchorDay + random.nextInt(dateSpanDays));
+        case SampleFieldKind.DateTime: {
+            const day = anchorDay + random.nextInt(dateSpanDays);
+            const seconds = random.nextInt(86400);
+            return `${formatDay(day)}T${pad(Math.floor(seconds / 3600))}:${pad(Math.floor(seconds / 60) % 60)}:${pad(seconds % 60)}Z`;
+        }
+        case SampleFieldKind.Enum:
+            return field.enumValues !== undefined && field.enumValues !== null && field.enumValues.length > 0 ? random.pick(field.enumValues) : null;
+        default:
+            return null;
+    }
+}
+
+function range(min: number | undefined, max: number | undefined, defaultMin: number, defaultMax: number, convert: (value: number) => number): [number, number] {
+    const low = convert(min ?? defaultMin);
+    const high = convert(max ?? defaultMax);
+    return high < low ? [high, low] : [low, high];
+}
+
+function generateId(random: SampleRandom): string {
+    const a = random.next();
+    const b = ((random.next() & 0xFFFF0FFF) | 0x00004000) >>> 0;
+    const c = ((random.next() & 0x3FFFFFFF) | 0x80000000) >>> 0;
+    const d = random.next();
+    return `${hex(a, 8)}-${hex(b >>> 16, 4)}-${hex(b & 0xFFFF, 4)}-${hex(c >>> 16, 4)}-${hex(c & 0xFFFF, 4)}${hex(d, 8)}`;
+}
+
+const transliterations = new Map<string, string>([['æ', 'ae'], ['ø', 'o'], ['å', 'a'], ['ä', 'a'], ['ö', 'o'], ['ü', 'u'], ['ß', 'ss'], ['é', 'e']]);
+
+function slug(text: string): string {
+    let result = '';
+    for (const character of text.toLowerCase()) {
+        const mapped = transliterations.get(character) ?? character;
+        for (const part of mapped) {
+            if ((part >= 'a' && part <= 'z') || (part >= '0' && part <= '9')) result += part;
+        }
+    }
+    return result;
+}
+
+function capitalize(text: string): string {
+    const first = text.charAt(0);
+    return first >= 'a' && first <= 'z' ? first.toUpperCase() + text.slice(1) : text;
+}
+
+function hex(value: number, digits: number): string {
+    return (value >>> 0).toString(16).padStart(digits, '0');
+}
+
+function pad(value: number): string {
+    return value < 10 ? `0${value}` : String(value);
+}
+
+/** Formats days since 1970-01-01 as `yyyy-MM-dd` (Howard Hinnant's civil-from-days). */
+function formatDay(days: number): string {
+    const shifted = days + 719468;
+    const era = Math.floor(shifted / 146097);
+    const dayOfEra = shifted - era * 146097;
+    const yearOfEra = Math.floor((dayOfEra - Math.floor(dayOfEra / 1460) + Math.floor(dayOfEra / 36524) - Math.floor(dayOfEra / 146096)) / 365);
+    const dayOfYear = dayOfEra - (365 * yearOfEra + Math.floor(yearOfEra / 4) - Math.floor(yearOfEra / 100));
+    const monthPrime = Math.floor((5 * dayOfYear + 2) / 153);
+    const day = dayOfYear - Math.floor((153 * monthPrime + 2) / 5) + 1;
+    const month = monthPrime < 10 ? monthPrime + 3 : monthPrime - 9;
+    const year = yearOfEra + era * 400 + (month <= 2 ? 1 : 0);
+    return `${String(year).padStart(4, '0')}-${pad(month)}-${pad(day)}`;
+}

package/sampleData/index.ts

@@ -0,0 +1,17 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+export * from './SampleRandom';
+export * from './sampleLocales';
+export * from './inferSampleFieldKind';
+export * from './generateSample';
+export * from './SampleDataResolution';
+export * from './findSampleDataSet';
+export * from './resolveSampleData';
+export * from './sampleDataRules';
+export * from './validateSampleDataPack';
+export * from './validateSampleDataSelection';
+export * from './SampleDataPackSource';
+export * from './validateSampleDataPackages';
+export * from './describeSampleDataCatalog';
+export * from './findSampleRowLiterals';

package/sampleData/inferSampleFieldKind.ts

@@ -0,0 +1,64 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { SampleFieldKind, SampleShapeField } from '@cratis/scene.model';
+
+const typeKinds = new Map<string, SampleFieldKind>([
+    ['guid', SampleFieldKind.Id],
+    ['uuid', SampleFieldKind.Id],
+    ['int', SampleFieldKind.WholeNumber],
+    ['int16', SampleFieldKind.WholeNumber],
+    ['int32', SampleFieldKind.WholeNumber],
+    ['int64', SampleFieldKind.WholeNumber],
+    ['short', SampleFieldKind.WholeNumber],
+    ['long', SampleFieldKind.WholeNumber],
+    ['integer', SampleFieldKind.WholeNumber],
+    ['number', SampleFieldKind.WholeNumber],
+    ['decimal', SampleFieldKind.Amount],
+    ['double', SampleFieldKind.Amount],
+    ['float', SampleFieldKind.Amount],
+    ['single', SampleFieldKind.Amount],
+    ['money', SampleFieldKind.Amount],
+    ['currency', SampleFieldKind.Amount],
+    ['bool', SampleFieldKind.Boolean],
+    ['boolean', SampleFieldKind.Boolean],
+    ['date', SampleFieldKind.Date],
+    ['dateonly', SampleFieldKind.Date],
+    ['datetime', SampleFieldKind.DateTime],
+    ['datetimeoffset', SampleFieldKind.DateTime],
+    ['timestamp', SampleFieldKind.DateTime],
+]);
+
+const nameKinds: [string[], SampleFieldKind][] = [
+    [['email'], SampleFieldKind.Email],
+    [['phone', 'mobile'], SampleFieldKind.Phone],
+    [['company', 'organization', 'organisation'], SampleFieldKind.Company],
+    [['city', 'town'], SampleFieldKind.City],
+    [['product', 'item', 'title', 'subject', 'description'], SampleFieldKind.Text],
+    [['name', 'customer', 'assignee', 'owner', 'author', 'contact', 'manager', 'employee'], SampleFieldKind.Name],
+];
+
+/**
+ * The kind of value to generate for a field. An explicit `kind` wins; otherwise a field with `enumValues` is
+ * an enum, a recognised `type` decides, and failing that the field's name does (an `Id` suffix, `email`,
+ * `phone`, `company`, `city`, person-like names), with free text as the fallback. A trailing `?` on the type
+ * is ignored and type names compare case-insensitively.
+ */
+export function inferSampleFieldKind(field: SampleShapeField): SampleFieldKind {
+    if (field.kind !== undefined && field.kind !== null) return field.kind as SampleFieldKind;
+    if (field.enumValues !== undefined && field.enumValues !== null && field.enumValues.length > 0) return SampleFieldKind.Enum;
+
+    let type = (field.type ?? '').trim().toLowerCase();
+    if (type.endsWith('?')) type = type.slice(0, -1);
+    const byType = typeKinds.get(type);
+    if (byType !== undefined) return byType;
+
+    const name = field.name ?? '';
+    const lower = name.toLowerCase();
+    if (lower === 'id' || (name.length > 2 && name.endsWith('Id'))) return SampleFieldKind.Id;
+    for (const [fragments, kind] of nameKinds) {
+        if (fragments.some(fragment => lower.includes(fragment))) return kind;
+    }
+
+    return SampleFieldKind.Text;
+}