@happyvertical/smrt-planner 0.0.0-stage → 0.0.1

package/dist/recipes/help.js

@@ -0,0 +1,262 @@
+/**
+ * Recipe help: the `help` contract of happyvertical/smrt#3591 and the one
+ * renderer that follows an app's options. Everything the contract needs lives
+ * here and imports nothing from the planner, so the module can be swapped for
+ * the core helper once #3591 is published, and `help.ts` deleted.
+ *
+ * Contract. A recipe entry carries `help: { markdown, fieldRefs }`. The
+ * Markdown is user-facing prose with an overview and tasks. A step names a
+ * field as `{field:name}` or `{field:Model.name}`, and a Markdown block (a
+ * heading, a paragraph or a list item) containing a reference is tied to that
+ * field. Field descriptions come from `@field({ description })` and are passed
+ * in with the models.
+ *
+ * Rendering. {@link renderHelp} replaces each reference with the field's
+ * effective label, drops the blocks tied to a field the app does not show
+ * (hidden, advanced or unknown) and builds the glossary from the effective
+ * label and help, falling back to the description. The output is an AST, never
+ * HTML, so no raw markup from content can reach the page: the host renders the
+ * nodes as ordinary elements. Only a small subset of Markdown is understood:
+ * `##`/`###`/`####` headings, paragraphs, flat `-`/`*`/`1.` lists, and
+ * `**bold**`, `*italic*` and `` `code` `` inline. Anything else is plain text.
+ */
+const FIELD_REF = /\{field:([A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)?)\}/;
+const INLINE = /\{field:[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)?\}|`[^`]+`|\*\*[^*]+\*\*|\*[^*\s][^*]*\*/;
+function parseInline(source) {
+    const out = [];
+    let rest = source;
+    while (rest) {
+        const match = INLINE.exec(rest);
+        if (!match)
+            break;
+        if (match.index > 0) {
+            out.push({ type: 'text', text: rest.slice(0, match.index) });
+        }
+        const token = match[0];
+        const ref = FIELD_REF.exec(token);
+        if (ref && ref[0] === token) {
+            out.push({ type: 'field', ref: ref[1] });
+        }
+        else if (token.startsWith('`')) {
+            out.push({ type: 'code', text: token.slice(1, -1) });
+        }
+        else if (token.startsWith('**')) {
+            out.push({ type: 'strong', children: parseInline(token.slice(2, -2)) });
+        }
+        else {
+            out.push({ type: 'em', children: parseInline(token.slice(1, -1)) });
+        }
+        rest = rest.slice(match.index + token.length);
+    }
+    if (rest)
+        out.push({ type: 'text', text: rest });
+    return out;
+}
+const HEADING = /^(#{2,4})\s+(.+?)\s*#*\s*$/;
+const BULLET = /^[-*]\s+(.*)$/;
+const NUMBERED = /^\d+[.)]\s+(.*)$/;
+/** Parse the supported Markdown subset into blocks. */
+export function parseHelp(markdown) {
+    const blocks = [];
+    let paragraph = [];
+    let list = null;
+    const flushParagraph = () => {
+        if (paragraph.length) {
+            blocks.push({
+                type: 'paragraph',
+                inlines: parseInline(paragraph.join(' ')),
+            });
+            paragraph = [];
+        }
+    };
+    const flushList = () => {
+        if (list) {
+            blocks.push({
+                type: 'list',
+                ordered: list.ordered,
+                items: list.items.map((item) => ({ inlines: parseInline(item) })),
+            });
+            list = null;
+        }
+    };
+    for (const raw of markdown.replace(/\r\n?/g, '\n').split('\n')) {
+        const line = raw.trimEnd();
+        const trimmed = line.trim();
+        if (!trimmed) {
+            flushParagraph();
+            flushList();
+            continue;
+        }
+        const heading = HEADING.exec(trimmed);
+        if (heading) {
+            flushParagraph();
+            flushList();
+            blocks.push({
+                type: 'heading',
+                level: heading[1].length,
+                inlines: parseInline(heading[2]),
+            });
+            continue;
+        }
+        const bullet = BULLET.exec(trimmed);
+        const numbered = bullet ? null : NUMBERED.exec(trimmed);
+        const marker = bullet ?? numbered;
+        // A marker at the start of the line (not indented) opens a list item.
+        if (marker && raw === raw.trimStart()) {
+            flushParagraph();
+            const ordered = numbered !== null;
+            if (list && list.ordered !== ordered)
+                flushList();
+            if (!list)
+                list = { ordered, items: [] };
+            list.items.push(marker[1]);
+            continue;
+        }
+        // An indented line continues the open list item, else the paragraph.
+        if (list) {
+            list.items[list.items.length - 1] += ` ${trimmed}`;
+        }
+        else {
+            paragraph.push(trimmed);
+        }
+    }
+    flushParagraph();
+    flushList();
+    return blocks;
+}
+function refsOf(inlines) {
+    return inlines.flatMap((node) => node.type === 'field'
+        ? [node.ref]
+        : node.type === 'strong' || node.type === 'em'
+            ? refsOf(node.children)
+            : []);
+}
+/** Every distinct field reference in the Markdown, as written, sorted. */
+export function extractFieldRefs(markdown) {
+    const refs = parseHelp(markdown).flatMap((block) => block.type === 'list'
+        ? block.items.flatMap((item) => refsOf(item.inlines))
+        : refsOf(block.inlines));
+    return [...new Set(refs)].sort();
+}
+/** Build a contract entry from Markdown, deriving `fieldRefs`. */
+export function createRecipeHelp(markdown) {
+    return { markdown, fieldRefs: extractFieldRefs(markdown) };
+}
+/** Find a reference's field: `name` in the first model declaring it, or `Model.name`. */
+export function findField(ref, models) {
+    const dot = ref.indexOf('.');
+    const modelName = dot === -1 ? null : ref.slice(0, dot);
+    const fieldName = dot === -1 ? ref : ref.slice(dot + 1);
+    for (const model of models) {
+        if (modelName !== null && model.name !== modelName)
+            continue;
+        const field = model.fields.find((f) => f.name === fieldName);
+        if (field)
+            return { model, field };
+    }
+    return undefined;
+}
+/**
+ * Problems that should fail a build: references to fields the recipe's models
+ * do not declare, and a `fieldRefs` list that disagrees with the Markdown.
+ */
+export function validateHelp(help, models) {
+    const problems = [];
+    if (!help.markdown.trim())
+        problems.push('help has no markdown');
+    const actual = extractFieldRefs(help.markdown);
+    for (const ref of actual) {
+        if (!findField(ref, models)) {
+            problems.push(`{field:${ref}} names a field the recipe's models lack`);
+        }
+    }
+    if (JSON.stringify([...help.fieldRefs].sort()) !== JSON.stringify(actual)) {
+        problems.push('fieldRefs does not match the references in the markdown');
+    }
+    return problems;
+}
+/** Replace references with labels, or `null` when any is not shown. */
+function resolveInlines(inlines, models) {
+    const out = [];
+    for (const node of inlines) {
+        if (node.type === 'field') {
+            const found = findField(node.ref, models);
+            if (!found)
+                return null;
+            if (found.field.visibility !== 'basic')
+                return null;
+            out.push({ type: 'text', text: found.field.label });
+        }
+        else if (node.type === 'strong' || node.type === 'em') {
+            const inner = resolveInlines(node.children, models);
+            if (!inner)
+                return null;
+            out.push({ type: node.type, children: inner.inlines });
+        }
+        else {
+            out.push(node);
+        }
+    }
+    return { inlines: out };
+}
+/** Does the section under the heading at `index` hold any non-heading block? */
+function sectionHasBody(entries, index, survivors) {
+    const heading = entries[index]?.source;
+    for (let i = index + 1; i < entries.length; i++) {
+        const next = entries[i];
+        if (next.source.type === 'heading') {
+            if (next.source.level <= heading.level)
+                return false;
+            continue;
+        }
+        if (!survivors || next.kept)
+            return true;
+    }
+    return false;
+}
+/** Resolve the Markdown against the app's options. */
+export function resolveHelp(help, models) {
+    const entries = parseHelp(help.markdown).map((source) => {
+        if (source.type === 'list') {
+            const items = source.items.flatMap((item) => {
+                const resolved = resolveInlines(item.inlines, models);
+                return resolved ? [{ inlines: resolved.inlines }] : [];
+            });
+            return { source, kept: items.length ? { ...source, items } : null };
+        }
+        const resolved = resolveInlines(source.inlines, models);
+        return {
+            source,
+            kept: resolved ? { ...source, inlines: resolved.inlines } : null,
+        };
+    });
+    // A heading whose section had content, all of it dropped, goes too.
+    return entries.flatMap((entry, index) => {
+        if (!entry.kept)
+            return [];
+        if (entry.source.type === 'heading' &&
+            sectionHasBody(entries, index, false) &&
+            !sectionHasBody(entries, index, true)) {
+            return [];
+        }
+        return [entry.kept];
+    });
+}
+/** One entry per shown field: effective label, then effective help or description. */
+export function buildGlossary(models) {
+    return models.flatMap((model) => model.fields.flatMap((field) => {
+        if (model.glossary === false || field.visibility !== 'basic')
+            return [];
+        const text = field.help?.trim() || model.descriptions?.[field.name] || '';
+        return text
+            ? [{ model: model.name, name: field.name, label: field.label, text }]
+            : [];
+    }));
+}
+/** The whole renderer: resolved blocks plus the field glossary. */
+export function renderHelp(help, models) {
+    return {
+        blocks: resolveHelp(help, models),
+        glossary: buildGlossary(models),
+    };
+}

package/dist/recipes/index.d.ts

@@ -0,0 +1,65 @@
+import type { CatalogModel, CatalogPackage } from '../catalog/types.ts';
+import type { HelpModel } from './help.ts';
+import { type FieldPolicyRow } from './policy.ts';
+import { type RecipeSection } from './sections.ts';
+import type { Recipe } from './types.ts';
+export type { RecipeSection } from './sections.ts';
+export { buildNavSections, legacyNavSectionKeys, navItemId, navSectionOf, sectionId, } from './sections.ts';
+export type * from './types.ts';
+/**
+ * The recipes the planner offers, in the overlay's order (which is the order
+ * of sub-switches on a card). They are the ones the smrt packages declare
+ * (carried in the catalog), plus the planner-local `forms` and `extends` of
+ * `overlay.json`; see `merge.ts`.
+ */
+export declare const recipes: readonly Recipe[];
+export declare function getRecipe(id: string): Recipe | undefined;
+export declare const recipesById: ReadonlyMap<string, Recipe>;
+/** The navigation sections (see `sections.ts`), one Options and Help page each. */
+export declare const sections: readonly RecipeSection[];
+export declare function getSection(id: string): RecipeSection | undefined;
+/** The package that owns a recipe: the one its first model belongs to. */
+export declare function recipePackage(recipe: Recipe): CatalogPackage | undefined;
+export interface RecipeNavTarget {
+    label: string;
+    /** Shell icon name; see `RecipeNavEntry.icon`. */
+    icon: string;
+    /** The recipe's own line; see `RecipeNavEntry.description`. */
+    description: string;
+    /** The entry's fixed id key, if the model appears twice in the nav. */
+    key?: string;
+    /** Explicit noun for the New button; see `RecipeNavEntry.noun`. */
+    noun?: string;
+    /** Row filter of a keyed entry; see `RecipeNavEntry.filter`. */
+    filter?: {
+        field: string;
+        value: string;
+    };
+    model: CatalogModel;
+    /** Catalog package id, for the `/m/<package>/<model>/` route. */
+    packageId: string;
+}
+/** A recipe's `nav` entries resolved to catalog models; unknown ones are dropped. */
+export declare function recipeNav(recipe: Recipe): RecipeNavTarget[];
+/**
+ * In-app path of a nav entry, without the app query: `/m/<pkg>/<Model>/`, and
+ * `/m/<pkg>/<Model>/<key>/` for a keyed entry (the same model shown twice).
+ */
+export declare function navPath(entry: {
+    packageId: string;
+    model: {
+        name: string;
+    };
+    key?: string;
+}): string;
+/** A recipe's models resolved to catalog models, in declared order. */
+export declare function recipeModels(recipe: Recipe): {
+    model: CatalogModel;
+    packageId: string;
+}[];
+/**
+ * A recipe's models as the help renderer takes them: the effective field
+ * policies (the recipe's own hints plus the app's saved `rows`, whether or not
+ * the recipe is added yet) and the descriptions.
+ */
+export declare function helpModels(recipe: Recipe, rows?: readonly FieldPolicyRow[]): HelpModel[];

package/dist/recipes/index.js

@@ -0,0 +1,95 @@
+import { catalog, getModelByQualifiedName } from "../catalog/index.js";
+import { FEATURE_ENTRY_ICON } from "./features.js";
+import descriptionsFile from './help/descriptions.json' with { type: 'json' };
+import { mergeRecipes } from "./merge.js";
+import overlay from './overlay.json' with { type: 'json' };
+import { resolveFields } from "./policy.js";
+import { buildSections, entryDescription, } from "./sections.js";
+export { buildNavSections, legacyNavSectionKeys, navItemId, navSectionOf, sectionId, } from "./sections.js";
+const descriptions = descriptionsFile;
+/**
+ * The recipes the planner offers, in the overlay's order (which is the order
+ * of sub-switches on a card). They are the ones the smrt packages declare
+ * (carried in the catalog), plus the planner-local `forms` and `extends` of
+ * `overlay.json`; see `merge.ts`.
+ */
+export const recipes = mergeRecipes(catalog.packages.flatMap((pkg) => pkg.recipes ?? []), overlay);
+const byId = new Map(recipes.map((recipe) => [recipe.id, recipe]));
+export function getRecipe(id) {
+    return byId.get(id);
+}
+export const recipesById = byId;
+/** The navigation sections (see `sections.ts`), one Options and Help page each. */
+export const sections = buildSections(recipes);
+export function getSection(id) {
+    return sections.find((section) => section.id === id);
+}
+/** The package that owns a recipe: the one its first model belongs to. */
+export function recipePackage(recipe) {
+    const first = recipe.models[0];
+    return first ? getModelByQualifiedName(first)?.pkg : undefined;
+}
+/** A recipe's `nav` entries resolved to catalog models; unknown ones are dropped. */
+export function recipeNav(recipe) {
+    return recipe.nav.flatMap((entry) => {
+        const found = getModelByQualifiedName(entry.model);
+        return found
+            ? [
+                {
+                    label: entry.label,
+                    icon: entry.icon ?? FEATURE_ENTRY_ICON,
+                    description: entryDescription(entry.description, found.model),
+                    ...(entry.key ? { key: entry.key } : {}),
+                    ...(entry.noun ? { noun: entry.noun } : {}),
+                    ...(entry.filter ? { filter: entry.filter } : {}),
+                    model: found.model,
+                    packageId: found.pkg.id,
+                },
+            ]
+            : [];
+    });
+}
+/**
+ * In-app path of a nav entry, without the app query: `/m/<pkg>/<Model>/`, and
+ * `/m/<pkg>/<Model>/<key>/` for a keyed entry (the same model shown twice).
+ */
+export function navPath(entry) {
+    return `/m/${entry.packageId}/${entry.model.name}/${entry.key ? `${entry.key}/` : ''}`;
+}
+/** A recipe's models resolved to catalog models, in declared order. */
+export function recipeModels(recipe) {
+    return recipe.models.flatMap((qualified) => {
+        const found = getModelByQualifiedName(qualified);
+        return found ? [{ model: found.model, packageId: found.pkg.id }] : [];
+    });
+}
+/**
+ * A recipe's models as the help renderer takes them: the effective field
+ * policies (the recipe's own hints plus the app's saved `rows`, whether or not
+ * the recipe is added yet) and the descriptions.
+ */
+export function helpModels(recipe, rows = []) {
+    // A recipe with no menu entry has no list or form, so no field is shown to
+    // describe (the assistant's session records, a policy table). Its prose can
+    // still name fields (Form customization's steps), so they resolve; they just
+    // get no glossary entry.
+    const listed = recipe.nav.length > 0;
+    return recipeModels(recipe).map(({ model }) => ({
+        id: model.id,
+        name: model.name,
+        ...(listed ? {} : { glossary: false }),
+        // The curated local text first (it is plain language, checked by tests);
+        // a field it does not cover falls back to the description its package
+        // declares, which is how feature recipes' models get a glossary.
+        descriptions: {
+            ...Object.fromEntries(model.fields.flatMap((f) => f.description ? [[f.name, f.description]] : [])),
+            ...descriptions[model.id],
+        },
+        fields: resolveFields(model, recipe.options?.[model.id], rows).map((r) => ({
+            name: r.field.name,
+            label: r.label,
+            help: r.help,
+            visibility: r.visibility,
+        })),
+    }));
+}

package/dist/recipes/merge.d.ts

@@ -0,0 +1,26 @@
+import type { Recipe, RecipeForm, RecipeFormExtension } from './types.ts';
+/**
+ * What the planner keeps locally because no smrt package declares it: the
+ * save-together `forms` and the `extends` that add to another recipe's form.
+ * Everything else about a recipe comes from the package that owns it.
+ */
+export interface RecipeOverlayEntry {
+    forms?: RecipeForm[];
+    extends?: RecipeFormExtension[];
+}
+export interface RecipeOverlay {
+    /**
+     * Card and sub-switch order. Package declaration order is alphabetical by
+     * package, so the planner pins the order it shows; recipes not listed
+     * follow, in catalog order.
+     */
+    order: string[];
+    /** Keyed by recipe id; every key must be a recipe a package declares. */
+    recipes: Record<string, RecipeOverlayEntry>;
+}
+/**
+ * The recipe list: every recipe the catalog's packages declare, with the
+ * overlay's local parts merged in. An overlay entry or `order` id naming no
+ * upstream recipe is an error: a recipe must exist in its package first.
+ */
+export declare function mergeRecipes(upstream: readonly Recipe[], overlay: RecipeOverlay): Recipe[];

package/dist/recipes/merge.js

@@ -0,0 +1,21 @@
+/**
+ * The recipe list: every recipe the catalog's packages declare, with the
+ * overlay's local parts merged in. An overlay entry or `order` id naming no
+ * upstream recipe is an error: a recipe must exist in its package first.
+ */
+export function mergeRecipes(upstream, overlay) {
+    const byId = new Map(upstream.map((recipe) => [recipe.id, recipe]));
+    const orphans = [...Object.keys(overlay.recipes), ...overlay.order].filter((id) => !byId.has(id));
+    if (orphans.length > 0) {
+        throw new Error(`Recipes only declared locally, not in a smrt package: ${[...new Set(orphans)].join(', ')}`);
+    }
+    const ordered = [
+        ...overlay.order,
+        ...upstream.map((r) => r.id).filter((id) => !overlay.order.includes(id)),
+    ];
+    return [...new Set(ordered)].map((id) => {
+        const recipe = byId.get(id);
+        const local = overlay.recipes[id];
+        return local ? { ...recipe, ...local } : recipe;
+    });
+}