@keemakr/ui-sdk 1.5.0 → 1.6.0-dev-20261026112734

package/dist/published/v1.4.0/dataset-view.js

@@ -0,0 +1,702 @@
+// FROZEN COPY of the published @keemakr/ui-sdk@1.4.0 src/dataset-view.ts (git tag @keemakr/ui-sdk@1.4.0).
+// Core checks the tree it sends an older app against the schema that app really parses with.
+// Do not edit: tests/sdk/ui-published-parsers.test.ts pins the bytes below this header.
+/**
+ * The `dataset` node, and how a dataset becomes blocks.
+ *
+ * A screen places one of its module's datasets with a single node:
+ *
+ *   { type: 'dataset', dataset: 'leads', layout: 'table' }
+ *
+ * Core expands the node before any renderer sees it: it queries the dataset
+ * with the viewer's grant and replaces the node with blocks every app already
+ * draws. So a new layout never needs a new client. The layouts:
+ *
+ * - `table`: a table with sort and filter headers and a pager.
+ * - `board`: cards in columns, grouped by a stage or a status.
+ * - `list`: a table with filter chips over its stage or status. Pressing a
+ *   row opens it as a record beside the list, in the screen's right rail.
+ * - `record`: one row, named by a screen param, as a page: its title, its
+ *   status, and its other fields as facts. This file is the pure
+ * half of that: the node's schema, how a screen's params become a query, and
+ * how one page of rows becomes blocks. It runs on the server and in tests.
+ *
+ * Interaction is navigation. A sort header, a filter menu and the pager each
+ * navigate back to the same screen with params (`sort`, `direction`, a field
+ * name, the page param), and the next expansion reads them. One interactive
+ * dataset node per screen: two would share those param names.
+ */
+import { z } from 'zod';
+import { DATASET_LIMITS, } from './dataset.js';
+const slug = z
+    .string()
+    .regex(/^[a-z][a-z0-9_-]*$/, 'lowercase slug (a-z, 0-9, -, _)')
+    .max(64);
+const fieldName = z
+    .string()
+    .max(64)
+    .regex(/^[a-z][a-z0-9_]*$/, 'must be lowercase snake_case, starting with a letter');
+export const DATASET_LAYOUTS = ['table', 'board', 'list', 'record', 'chart'];
+/** Deepest page a table reaches. Paging walks cursors from page 1. */
+export const DATASET_MAX_PAGE = 20;
+export const datasetNodeSchema = z.object({
+    type: z.literal('dataset'),
+    /** A dataset this module declares in ui/datasets/. */
+    dataset: slug,
+    layout: z.enum(DATASET_LAYOUTS).default('table'),
+    /**
+     * The fields to show, in order. Omitted: the title, then the fields with a
+     * role, then the rest, up to 8. The key field shows only when named here.
+     */
+    fields: z.array(fieldName).min(1).max(12).optional(),
+    /** Filters the module fixes for this view. A person cannot clear them. */
+    filters: z.record(fieldName, z.string().max(200)).optional(),
+    /** The order before a person picks one. Defaults to the dataset's defaultSort. */
+    sort: z
+        .object({ field: fieldName, direction: z.enum(['asc', 'desc']).default('asc') })
+        .optional(),
+    /** Rows per page for a table; the most cards for a board. */
+    limit: z.number().int().min(1).max(100).default(25),
+    /**
+     * The board's columns, or the chart's bars: an enum field. Defaults to the
+     * stage field, then the status field.
+     */
+    groupBy: fieldName.optional(),
+    /**
+     * For a chart. `bars`: one bar per option of `groupBy`. `funnel`: how many
+     * reached each step, in option order; an option with a destructive tone (a
+     * lost deal) is an exit, not a step. `measure` sums a number field instead
+     * of counting rows. A chart reads up to 200 rows.
+     */
+    chart: z
+        .object({
+        form: z.enum(['bars', 'funnel']).default('bars'),
+        measure: fieldName.optional(),
+    })
+        .optional(),
+    /**
+     * Pressing a row or card opens this screen, with the row's key under `param`.
+     * A list without it opens the row beside the list.
+     */
+    open: z.object({ screen: slug, param: slug.default('id') }).optional(),
+    /**
+     * The screen param that holds a row's key. A record shows that row. A list
+     * shows that row beside the list, and puts a pressed row's key there.
+     */
+    param: slug.default('id'),
+    /** Shown when no rows match. */
+    empty: z.string().min(1).max(80).default('Nothing here yet'),
+    /**
+     * Offer the dataset's create form above the rows, when the dataset declares
+     * `accepts.create`. False keeps this view read-only.
+     */
+    create: z.boolean().default(true),
+});
+/** Problems with a node against its dataset. Core shows these, never a broken view. */
+export function datasetNodeIssues(node, declaration) {
+    const issues = [];
+    const byName = new Map(declaration.fields.map((field) => [field.name, field]));
+    for (const name of node.fields ?? []) {
+        if (!byName.has(name))
+            issues.push(`"${name}" is not a field of ${declaration.name}`);
+    }
+    if (node.layout === 'board') {
+        const group = boardGroupField(node, declaration);
+        if (!group)
+            issues.push('a board needs an enum field to group by (a stage or a status)');
+        else if ((group.options?.length ?? 0) > 8)
+            issues.push('a board shows at most 8 columns');
+    }
+    if (node.layout === 'chart') {
+        if (!boardGroupField(node, declaration)) {
+            issues.push('a chart needs an enum field to group by (a stage or a status)');
+        }
+        const measure = node.chart?.measure;
+        if (measure && byName.get(measure)?.type !== 'number') {
+            issues.push(`a chart can only add up a number field, and "${measure}" is not one`);
+        }
+    }
+    if (node.chart && node.layout !== 'chart')
+        issues.push('only a chart takes chart settings');
+    return issues;
+}
+function boardGroupField(node, declaration) {
+    const enums = declaration.fields.filter((field) => field.type === 'enum');
+    if (node.groupBy)
+        return enums.find((field) => field.name === node.groupBy);
+    return enums.find((f) => f.role === 'stage') ?? enums.find((f) => f.role === 'status');
+}
+const NUMBER = new Intl.NumberFormat('en-US', { maximumFractionDigits: 2 });
+/** Bars or a funnel over the rows, with the totals above them. */
+function compileDatasetChart(node, declaration, response, hasMore) {
+    const group = boardGroupField(node, declaration);
+    const measure = node.chart?.measure
+        ? declaration.fields.find((field) => field.name === node.chart?.measure)
+        : undefined;
+    const funnel = node.chart?.form === 'funnel';
+    const valueOf = (row) => {
+        if (!measure)
+            return 1;
+        const value = row[measure.name];
+        return typeof value === 'number' ? value : 0;
+    };
+    const options = (group.options ?? []).filter((option) => !funnel || option.tone !== 'destructive');
+    const index = new Map(options.map((option, i) => [option.value, i]));
+    const values = options.map(() => 0);
+    for (const row of response.rows) {
+        const at = index.get(String(row[group.name]));
+        if (at === undefined)
+            continue;
+        // A funnel counts a row at its own step and at every step before it: it reached them.
+        if (funnel)
+            for (let i = 0; i <= at; i += 1)
+                values[i] += valueOf(row);
+        else
+            values[at] += valueOf(row);
+    }
+    const rounded = values.map((value) => Math.round(value * 100) / 100);
+    const total = response.rows.reduce((sum, row) => sum + valueOf(row), 0);
+    const unit = measure ? measure.label : declaration.label;
+    const stats = [
+        {
+            type: 'stat',
+            label: declaration.label.slice(0, 80),
+            value: NUMBER.format(response.rows.length),
+        },
+        ...(measure
+            ? [
+                {
+                    type: 'stat',
+                    label: `Total ${measure.label}`.slice(0, 80),
+                    value: NUMBER.format(total),
+                },
+            ]
+            : []),
+    ];
+    const out = [
+        { type: 'section', layout: 'row', children: stats },
+        {
+            type: 'chart',
+            chartType: 'bar',
+            title: `${unit} ${funnel ? 'reaching each' : 'by'} ${group.label.toLowerCase()}`.slice(0, 120),
+            orientation: funnel ? 'horizontal' : 'vertical',
+            showValues: true,
+            categories: options.map((option) => option.label.slice(0, 80)),
+            series: [{ name: unit.slice(0, 80), values: rounded }],
+        },
+    ];
+    if (funnel && options.length > 1) {
+        const steps = options.slice(1).map((option, i) => {
+            const before = rounded[i];
+            const share = before > 0 ? Math.round((rounded[i + 1] / before) * 100) : 0;
+            return `${option.label}: ${share}% of ${options[i].label}`;
+        });
+        out.push({ type: 'text', value: steps.join(' · ').slice(0, 5000), muted: true });
+    }
+    if (hasMore) {
+        out.push({
+            type: 'text',
+            value: `Counts the first ${response.rows.length} rows only.`,
+            muted: true,
+        });
+    }
+    return out;
+}
+/** Which page of a table the params ask for, 1 when none. */
+export function datasetPage(node, params) {
+    if (node.layout !== 'table' && node.layout !== 'list')
+        return 1;
+    const page = Number.parseInt(params.page ?? '1', 10);
+    return Number.isFinite(page) ? Math.min(Math.max(page, 1), DATASET_MAX_PAGE) : 1;
+}
+/**
+ * The key of the row a record shows, or a list opens beside it. Undefined when
+ * the node shows no single row, or the param is empty.
+ */
+export function datasetRecordKey(node, params) {
+    if (node.layout !== 'record' && node.layout !== 'list')
+        return undefined;
+    if (node.layout === 'list' && node.open)
+        return undefined;
+    const key = params[node.param];
+    return key && key.length <= 128 ? key : undefined;
+}
+/** The query for the one row a record shows. */
+export function datasetRecordQuery(key) {
+    return { keys: [key], limit: 1 };
+}
+/**
+ * The query a node and the screen's params make. The node's own filters win
+ * over a param of the same name; a param for a field the dataset does not let
+ * a person filter is ignored, never forwarded.
+ */
+export function datasetQueryFor(node, declaration, params) {
+    const filters = {};
+    for (const field of declaration.fields) {
+        const value = params[field.name];
+        if (!field.filterable || !value)
+            continue;
+        if (field.type === 'enum' && !field.options?.some((option) => option.value === value))
+            continue;
+        if (field.type === 'boolean' && value !== 'true' && value !== 'false')
+            continue;
+        filters[field.name] = value;
+    }
+    Object.assign(filters, node.filters ?? {});
+    const byName = new Map(declaration.fields.map((field) => [field.name, field]));
+    const asked = params.sort && byName.get(params.sort)?.sortable ? params.sort : undefined;
+    const sort = asked
+        ? {
+            field: asked,
+            direction: params.direction === 'desc' ? 'desc' : 'asc',
+        }
+        : (node.sort ?? declaration.defaultSort);
+    return {
+        filters,
+        ...(sort ? { sort } : {}),
+        limit: node.layout === 'chart'
+            ? DATASET_LIMITS.rows
+            : node.layout === 'board'
+                ? Math.min(DATASET_LIMITS.rows, node.limit * 4)
+                : node.limit,
+    };
+}
+/** The fields a view shows, in order. */
+function shownFields(node, declaration) {
+    const byName = new Map(declaration.fields.map((field) => [field.name, field]));
+    if (node.fields)
+        return node.fields.flatMap((name) => byName.get(name) ?? []);
+    const order = ['title', 'subtitle', 'status', 'stage', 'owner', 'due', 'amount'];
+    const withRole = declaration.fields
+        .filter((field) => field.role)
+        .sort((a, b) => order.indexOf(a.role) - order.indexOf(b.role));
+    const rest = declaration.fields.filter((field) => !field.role && field.name !== declaration.key);
+    return [...withRole, ...rest].slice(0, 8);
+}
+const DAY = new Intl.DateTimeFormat('en-GB', {
+    day: 'numeric',
+    month: 'short',
+    year: 'numeric',
+    timeZone: 'UTC',
+});
+/** One value as a table cell, or null when the row has none. */
+export function datasetCell(field, value) {
+    if (value === null || value === undefined || value === '')
+        return null;
+    switch (field.type) {
+        case 'enum': {
+            const option = field.options?.find((item) => item.value === value);
+            return {
+                kind: 'badge',
+                value: (option?.label ?? String(value)).slice(0, 40),
+                tone: option?.tone ?? 'default',
+            };
+        }
+        case 'boolean':
+            return { kind: 'badge', value: value ? 'Yes' : 'No', tone: value ? 'success' : 'default' };
+        case 'datetime': {
+            const ms = Date.parse(String(value));
+            return Number.isNaN(ms)
+                ? { kind: 'text', value: String(value) }
+                : { kind: 'date', value: new Date(ms).toISOString() };
+        }
+        case 'date': {
+            // A calendar date has no time and no zone. It is written out, not sent as
+            // a date cell, because a date cell is an instant the viewer's zone moves.
+            const ms = Date.parse(`${String(value)}T00:00:00Z`);
+            return Number.isNaN(ms)
+                ? { kind: 'text', value: String(value) }
+                : { kind: 'text', value: DAY.format(ms) };
+        }
+        case 'number':
+            return {
+                kind: 'text',
+                value: typeof value === 'number' ? value.toLocaleString('en-US') : String(value),
+            };
+        case 'tags':
+            return Array.isArray(value) ? { kind: 'text', value: value.join(', ').slice(0, 500) } : null;
+        default:
+            return { kind: 'text', value: String(value).slice(0, 500) };
+    }
+}
+function plain(field, row) {
+    if (!field)
+        return undefined;
+    const cell = datasetCell(field, row[field.name]);
+    return cell && cell.kind !== 'date' ? cell.value : undefined;
+}
+function keepParams(params, drop) {
+    return Object.fromEntries(Object.entries(params).filter(([name]) => !drop.includes(name)));
+}
+/** The most chips a list shows: `All` plus five options, the segmented block's limit. */
+const MAX_CHIP_OPTIONS = 5;
+/**
+ * The field a list's chips filter on: the stage, else the status, when a
+ * person may filter on it, the module does not fix it, and its options fit.
+ */
+function chipField(node, declaration) {
+    const fits = (field) => field &&
+        field.filterable &&
+        !node.filters?.[field.name] &&
+        (field.options?.length ?? 0) <= MAX_CHIP_OPTIONS
+        ? field
+        : undefined;
+    return (fits(declaration.fields.find((f) => f.role === 'stage')) ??
+        fits(declaration.fields.find((f) => f.role === 'status')));
+}
+/** The chip value that clears the chip filter. No option may hold it. */
+function allChip(field) {
+    return field.options?.some((option) => option.value === 'all') ? '*' : 'all';
+}
+/** The order a record lists its facts in: these roles first, then the rest. */
+const FACT_ROLES = ['owner', 'due', 'amount'];
+/** Roles a record shows in its header, not as facts. */
+const HEADER_ROLES = ['title', 'subtitle', 'status', 'stage'];
+/**
+ * One row as a record: its title, its subtitle, a tag for its status and its
+ * stage, and its other fields as facts. `row` undefined means the module did
+ * not find the key, and the record says so.
+ */
+export function compileDatasetRecord(opts) {
+    const { declaration, row } = opts;
+    if (!row) {
+        return [
+            {
+                type: 'alert',
+                tone: 'warning',
+                text: `This item is not in ${declaration.label} any more.`,
+            },
+        ];
+    }
+    const role = (name) => declaration.fields.find((field) => field.role === name);
+    const subtitle = plain(role('subtitle'), row);
+    const tags = ['status', 'stage'].flatMap((name) => {
+        const field = role(name);
+        const cell = field ? datasetCell(field, row[field.name]) : null;
+        return cell?.kind === 'badge' ? [{ label: cell.value, tone: cell.tone }] : [];
+    });
+    const rank = (field) => field.role && FACT_ROLES.includes(field.role)
+        ? FACT_ROLES.indexOf(field.role)
+        : FACT_ROLES.length;
+    const facts = declaration.fields
+        .filter((field) => field.name !== declaration.key && !(field.role && HEADER_ROLES.includes(field.role)))
+        .sort((a, b) => rank(a) - rank(b))
+        .flatMap((field) => {
+        const cell = datasetCell(field, row[field.name]);
+        return cell ? [{ label: field.label, value: cell }] : [];
+    })
+        .slice(0, 50);
+    return [
+        {
+            type: 'heading',
+            text: (plain(role('title'), row) || String(row[declaration.key])).slice(0, 120),
+        },
+        ...(subtitle ? [{ type: 'text', value: subtitle, muted: true }] : []),
+        ...(tags.length ? [{ type: 'tags', items: tags }] : []),
+        ...(facts.length ? [{ type: 'details', columns: 2, items: facts }] : []),
+    ];
+}
+/** The key of the root section that holds the record a list opened. */
+export const DATASET_RECORD_SECTION = 'dataset-record';
+/**
+ * The record a list opened, as the section the screen's right rail shows,
+ * with a button that closes it.
+ */
+export function compileDatasetRecordPanel(opts) {
+    const { node, screen } = opts;
+    return {
+        type: 'section',
+        key: DATASET_RECORD_SECTION,
+        layout: 'stack',
+        children: [
+            ...compileDatasetRecord(opts),
+            {
+                type: 'button',
+                label: 'Close',
+                variant: 'secondary',
+                onPress: {
+                    kind: 'navigate',
+                    screen: screen.screen,
+                    params: keepParams(screen.params, [node.param]),
+                },
+            },
+        ],
+    };
+}
+/**
+ * One page of rows as screen blocks. `rows` is the page to show; `total` and
+ * `hasMore` drive the pager. The output is plain screen nodes, ready to put in
+ * the node's place.
+ */
+export function compileDatasetNode(opts) {
+    const { node, declaration, response, screen, page } = opts;
+    if (node.layout === 'record') {
+        const key = datasetRecordKey(node, screen.params);
+        return compileDatasetRecord({
+            declaration,
+            row: response.rows.find((row) => String(row[declaration.key]) === key),
+        });
+    }
+    const byName = new Map(declaration.fields.map((field) => [field.name, field]));
+    const titleField = declaration.fields.find((field) => field.role === 'title');
+    const open = (row) => {
+        const key = row[declaration.key];
+        if (key === null || key === undefined)
+            return {};
+        if (node.open) {
+            return {
+                onPress: {
+                    kind: 'navigate',
+                    screen: node.open.screen,
+                    params: { [node.open.param]: String(key) },
+                },
+            };
+        }
+        // A list opens the row beside itself: the same screen and view, one more param.
+        return node.layout === 'list'
+            ? {
+                onPress: {
+                    kind: 'navigate',
+                    screen: screen.screen,
+                    params: { ...screen.params, [node.param]: String(key) },
+                },
+            }
+            : {};
+    };
+    const note = response.note ? [{ type: 'text', value: response.note, muted: true }] : [];
+    if (node.layout === 'chart') {
+        return [...compileDatasetChart(node, declaration, response, opts.hasMore), ...note];
+    }
+    if (node.layout === 'board') {
+        const group = boardGroupField(node, declaration);
+        const subtitleField = declaration.fields.find((f) => f.role === 'subtitle') ??
+            declaration.fields.find((f) => f.role === 'owner');
+        const valueFields = declaration.fields
+            .filter((f) => (f.role === 'amount' || f.role === 'due' || f.role === 'status') && f !== group)
+            .slice(0, 3);
+        const columns = (group.options ?? []).map((option, index) => ({
+            key: /^[a-z][a-z0-9_-]{0,63}$/.test(option.value) ? option.value : `column-${index + 1}`,
+            label: option.label.slice(0, 40),
+            tone: option.tone,
+            cards: response.rows
+                .filter((row) => row[group.name] === option.value)
+                .slice(0, 100)
+                .map((row) => {
+                const subtitle = plain(subtitleField, row);
+                // A card has no column headers, so a bare "35" says nothing: label
+                // the text values. Badges and dates already read on their own.
+                const values = valueFields.flatMap((field) => {
+                    const cell = datasetCell(field, row[field.name]);
+                    if (!cell)
+                        return [];
+                    return cell.kind === 'text'
+                        ? [{ kind: 'text', value: `${field.label}: ${cell.value}`.slice(0, 500) }]
+                        : [cell];
+                });
+                return {
+                    key: String(row[declaration.key]).slice(0, 128),
+                    title: (plain(titleField, row) || String(row[declaration.key])).slice(0, 120),
+                    ...(subtitle ? { subtitle: subtitle.slice(0, 200) } : {}),
+                    ...(values.length ? { values } : {}),
+                    ...open(row),
+                };
+            }),
+        }));
+        return [{ type: 'board', columns, empty: node.empty.slice(0, 80) }, ...note];
+    }
+    const fields = shownFields(node, declaration);
+    const here = { kind: 'navigate', screen: screen.screen };
+    const chips = node.layout === 'list' ? chipField(node, declaration) : undefined;
+    const chipBar = [];
+    if (chips) {
+        const all = allChip(chips);
+        const picked = screen.params[chips.name];
+        chipBar.push({
+            type: 'segmented',
+            name: chips.name,
+            label: chips.label,
+            value: picked && chips.options?.some((option) => option.value === picked) ? picked : all,
+            options: [
+                { value: all, label: 'All' },
+                ...(chips.options ?? []).map((option) => ({
+                    value: option.value,
+                    label: option.label.slice(0, 40),
+                })),
+            ],
+            // A new chip starts on page 1, and closes the open row: it may not match the chip.
+            onChange: { ...here, params: keepParams(screen.params, ['page', node.param]) },
+        });
+    }
+    const hasFilter = fields.some((field) => field.filterable && field.type === 'enum');
+    const hasSort = fields.some((field) => field.sortable);
+    const activeSort = screen.params.sort && byName.get(screen.params.sort)?.sortable
+        ? {
+            column: screen.params.sort,
+            direction: screen.params.direction === 'desc' ? 'desc' : 'asc',
+        }
+        : undefined;
+    const table = {
+        type: 'table',
+        columns: fields.map((field) => ({
+            key: field.name,
+            label: field.label,
+            sortable: field.sortable,
+            ...(field.filterable &&
+                field.type === 'enum' &&
+                !node.filters?.[field.name] &&
+                field.name !== chips?.name
+                ? {
+                    filter: {
+                        ...(screen.params[field.name] &&
+                            field.options?.some((option) => option.value === screen.params[field.name])
+                            ? { value: screen.params[field.name] }
+                            : {}),
+                        options: (field.options ?? []).map((option) => ({
+                            value: option.value,
+                            label: option.label,
+                        })),
+                    },
+                }
+                : {}),
+        })),
+        ...(activeSort && fields.some((f) => f.name === activeSort.column) ? { sort: activeSort } : {}),
+        ...(hasSort
+            ? { onSort: { ...here, params: keepParams(screen.params, ['sort', 'direction', 'page']) } }
+            : {}),
+        ...(hasFilter ? { onFilter: { ...here, params: keepParams(screen.params, ['page']) } } : {}),
+        rows: response.rows.map((row) => ({
+            key: String(row[declaration.key]).slice(0, 128),
+            cells: Object.fromEntries(fields.flatMap((field) => {
+                const cell = datasetCell(field, row[field.name]);
+                return cell ? [[field.name, cell]] : [];
+            })),
+            ...open(row),
+        })),
+        empty: node.empty,
+    };
+    // The numbered pager needs a true total. Without one, plain Previous and
+    // Next buttons say only what is known: whether there is another page.
+    const pageSize = node.limit;
+    const total = response.total;
+    const pageCount = total !== undefined ? Math.min(Math.max(1, Math.ceil(total / pageSize)), DATASET_MAX_PAGE) : 0;
+    const stay = keepParams(screen.params, ['page']);
+    const step = (label, to) => ({
+        type: 'button',
+        label,
+        variant: 'secondary',
+        onPress: { ...here, params: { ...stay, page: String(to) } },
+    });
+    const pager = total !== undefined
+        ? pageCount > 1
+            ? [
+                {
+                    type: 'pagination',
+                    page: Math.min(page, pageCount),
+                    pageCount,
+                    pageSize,
+                    total,
+                    onPage: { ...here, params: stay },
+                },
+            ]
+            : []
+        : [
+            ...(page > 1 ? [step('Previous page', page - 1)] : []),
+            ...(opts.hasMore && page < DATASET_MAX_PAGE ? [step('Next page', page + 1)] : []),
+        ];
+    return [...chipBar, table, ...pager, ...note];
+}
+/**
+ * The screen param that opens a dataset's create form: its value is the
+ * dataset's name. Reserved on every screen that shows a dataset.
+ */
+export const DATASET_NEW_PARAM = 'new';
+/**
+ * The action a create form submits. Core answers it itself: it checks the input
+ * against the declaration and calls the module's `create`. A module never
+ * receives it, so no module screen may name an action this.
+ */
+export const DATASET_CREATE_ACTION = 'kee-dataset-create';
+/** One form field for one dataset field. */
+function formField(field, required) {
+    const base = { name: field.name, label: field.label, required };
+    switch (field.type) {
+        case 'enum':
+            return {
+                ...base,
+                kind: 'select',
+                options: (field.options ?? []).map((option) => ({
+                    value: option.value,
+                    label: option.label,
+                })),
+            };
+        case 'number':
+            return { ...base, kind: 'number' };
+        case 'boolean':
+            return { ...base, kind: 'checkbox', required: false };
+        case 'date':
+            return { ...base, kind: 'date' };
+        case 'datetime':
+            return { ...base, kind: 'datetime' };
+        case 'tags':
+            return { ...base, kind: 'list' };
+        case 'url':
+            return { ...base, kind: 'text', placeholder: 'https://' };
+        default:
+            return { ...base, kind: 'text' };
+    }
+}
+/**
+ * The create affordance for a dataset node: a button that opens the form, or,
+ * once the `new` param names this dataset, the form itself with Cancel. Empty
+ * when the dataset takes no new rows, the node turns it off, or it is a record.
+ */
+export function compileDatasetCreate(opts) {
+    const { node, declaration, screen } = opts;
+    const create = declaration.accepts?.create;
+    if (!create || !node.create || node.layout === 'record' || node.layout === 'chart')
+        return [];
+    const here = { kind: 'navigate', screen: screen.screen };
+    if (screen.params[DATASET_NEW_PARAM] !== node.dataset) {
+        return [
+            {
+                type: 'button',
+                label: create.label,
+                variant: 'primary',
+                onPress: {
+                    ...here,
+                    params: {
+                        ...keepParams(screen.params, ['page', node.param]),
+                        [DATASET_NEW_PARAM]: node.dataset,
+                    },
+                },
+            },
+        ];
+    }
+    const byName = new Map(declaration.fields.map((field) => [field.name, field]));
+    const required = new Set(create.required);
+    const fields = create.fields.flatMap((name) => {
+        const field = byName.get(name);
+        return field ? [formField(field, required.has(name))] : [];
+    });
+    return [
+        {
+            type: 'section',
+            title: create.label,
+            layout: 'stack',
+            children: [
+                {
+                    type: 'form',
+                    key: `new-${node.dataset}`.slice(0, 64),
+                    fields,
+                    submit: { label: 'Save', action: DATASET_CREATE_ACTION },
+                },
+                {
+                    type: 'button',
+                    label: 'Cancel',
+                    variant: 'secondary',
+                    onPress: { ...here, params: keepParams(screen.params, [DATASET_NEW_PARAM]) },
+                },
+            ],
+        },
+    ];
+}