@texuli/deck 0.0.0-stage → 0.5.0

package/dist/model/deck.js

@@ -0,0 +1,338 @@
+/**
+ * The deck model v2 schemas (ADR-009, model-v2 §3.1, §3.2): `meta`, `style`,
+ * `navigation`, `outline` and 1 to 200 slides discriminated by `layout` (the
+ * 20 catalog layouts, `free`, `component` and `custom`), with
+ * `formatVersion: 2`. Built on the owned schema kit, so one definition gives
+ * all-issues validation, the `Infer` types and the JSON Schema export.
+ *
+ * The engine is L0: blocks and component props are checked here only as
+ * bounded JSON with a block head (`type`, `id`, step fields) and known
+ * nested containers. `parseDeck` hands each block and component to the
+ * host's validators (the slides stage injects `@texuli/blocks` and the
+ * component registry).
+ */
+import { t, toJsonSchema, validate, } from "../schema/index.js";
+import { deckBackground } from "./backgrounds/schema.js";
+import { DECK_CATALOG_LAYOUT_IDS, DECK_LAYOUTS, layoutPropsSchema, } from "./layouts/catalog.js";
+import { componentProps, deckTransition, FRAGMENT_TONES, line, MAX_SLIDE_STEPS, multiline, SLIDE_ID_PATTERN, slideId, stepFields, } from "./shared.js";
+import { deckStyle } from "./style/schema.js";
+import { deckThemeReference, styleSlug } from "./style/theme.js";
+/** The model's format version. */
+export const DECK_FORMAT_VERSION = 2;
+/** Deck-level limits (model-v2 §3.2). */
+export const DECK_MODEL_LIMITS = Object.freeze({
+    slides: 200,
+    sections: 200,
+    sectionSlides: 200,
+    titleLength: 200,
+    descriptionLength: 500,
+    authorLength: 120,
+    outlineTitleLength: 120,
+    notesLength: 6_000,
+    stepLabels: MAX_SLIDE_STEPS,
+    stepLabelLength: 80,
+    freeBlocks: 2_000,
+    autoSlideMinMs: 1_000,
+    autoSlideMaxMs: 600_000,
+});
+/** v1's eight free-slide arrangements (`master` on a free slide; default `content`). */
+export const SLIDE_MASTERS = [
+    'title',
+    'section',
+    'content',
+    'two-column',
+    'media-left',
+    'media-right',
+    'quote',
+    'closing',
+];
+/** The slide kinds that are not catalog layouts. */
+export const DECK_SLIDE_KINDS = ['free', 'component', 'custom'];
+/** Every `layout` value a slide may carry: 20 catalog layouts and the 3 slide kinds. */
+export const DECK_SLIDE_LAYOUTS = Object.freeze([
+    ...DECK_CATALOG_LAYOUT_IDS,
+    ...DECK_SLIDE_KINDS,
+]);
+export const DECK_DIRECTIONS = ['ltr', 'rtl', 'auto'];
+/** BCP 47 language tag syntax (`en`, `en-GB`, `pt-BR`). */
+export const LOCALE_PATTERN = '^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$';
+/** An ISO 8601 calendar date. */
+export const ISO_DATE_PATTERN = '^\\d{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\\d|3[01])$';
+/** Block `type` and catalog component ids: a lowercase slug starting with a letter. */
+export const BLOCK_TYPE_PATTERN = '^[a-z][a-z0-9-]{0,63}$';
+export const COMPONENT_ID_PATTERN = BLOCK_TYPE_PATTERN;
+/** Block tones (`@texuli/blocks` `BLOCK_TONES`): the fragment tones plus `neutral`. */
+export const BLOCK_TONES = ['neutral', ...FRAGMENT_TONES];
+/** Component item heights. */
+export const COMPONENT_HEIGHTS = ['sm', 'md', 'lg', 'fill'];
+/** Bounds for one free-slide item (the outer guard; the host block parser is tighter). */
+export const BLOCK_JSON_LIMITS = Object.freeze({
+    depth: 12,
+    maxKeys: 100,
+    maxItems: 2_000,
+    /** Room for a 192 KB base64 `data:` image; code and markdown are far smaller. */
+    maxString: 300_000,
+    maxKeyLength: 64,
+});
+/**
+ * Where nested blocks live inside a block, as the steps pass walks them:
+ * `blocks` and `children` (lists of blocks), `columns` (a list of lists) and
+ * `panels` (objects with `blocks`).
+ */
+export const BLOCK_CONTAINERS = Object.freeze({
+    lists: ['blocks', 'children'],
+    columns: 'columns',
+    panels: 'panels',
+});
+/** The step fields every slide item may carry (removed before the host block parser). */
+export const STEP_FIELD_KEYS = ['step', 'fragment', 'reveal'];
+// ---------------------------------------------------------------------------
+// Meta, navigation, outline
+export const deckMeta = t.object({
+    title: line(DECK_MODEL_LIMITS.titleLength, 1),
+    description: t.optional(line(DECK_MODEL_LIMITS.descriptionLength)),
+    locale: t.optional(t.string({ pattern: LOCALE_PATTERN, max: 35 })),
+    dir: t.optional(t.enum(DECK_DIRECTIONS), { description: "Default 'auto'." }),
+    author: t.optional(line(DECK_MODEL_LIMITS.authorLength)),
+    date: t.optional(t.string({ pattern: ISO_DATE_PATTERN, max: 10 })),
+}, { description: 'Deck metadata: title, description, language, direction, author and date.' });
+const autoSlideMs = t.refine(t.int({ min: 0, max: DECK_MODEL_LIMITS.autoSlideMaxMs }), {
+    code: 'out-of-range',
+    description: '0 turns auto-slide off; otherwise 1000 to 600000 ms.',
+    check(value, context) {
+        if (value !== 0 && value < DECK_MODEL_LIMITS.autoSlideMinMs) {
+            context.issue({
+                message: `Use 0 (off) or at least ${DECK_MODEL_LIMITS.autoSlideMinMs} ms.`,
+                fix: `Set 0, or a value from ${DECK_MODEL_LIMITS.autoSlideMinMs} to ${DECK_MODEL_LIMITS.autoSlideMaxMs}.`,
+            });
+        }
+    },
+});
+export const deckNavigation = t.object({
+    start: t.optional(slideId, {
+        description: 'The first slide shown (a visible slide id).',
+    }),
+    loop: t.optional(t.boolean(), { description: 'Default false.' }),
+    autoSlideMs: t.optional(autoSlideMs, { description: 'Default 0 (off).' }),
+}, { description: 'Navigation: start slide, looping and auto-slide.' });
+export const deckSection = t.object({
+    id: slideId,
+    title: t.optional(line(DECK_MODEL_LIMITS.outlineTitleLength)),
+    slideIds: t.array(slideId, { min: 1, max: DECK_MODEL_LIMITS.sectionSlides }),
+    stack: t.optional(t.boolean(), {
+        description: 'A vertical stack: the slides are adjacent in `slides` and navigate in 2D.',
+    }),
+});
+export const deckOutline = t.object({
+    title: t.optional(line(DECK_MODEL_LIMITS.outlineTitleLength)),
+    sections: t.array(deckSection, { min: 1, max: DECK_MODEL_LIMITS.sections }),
+}, {
+    description: 'Sections of slide ids: every id is a known slide, and a slide is in at most one section.',
+});
+const blockHead = t.object({
+    type: t.string({ pattern: BLOCK_TYPE_PATTERN, max: 64 }),
+    id: t.optional(slideId),
+    step: stepFields.step,
+    fragment: stepFields.fragment,
+    reveal: stepFields.reveal,
+    tone: t.optional(t.enum(BLOCK_TONES)),
+}, { strict: false });
+const objectProps = (description) => t.refine(componentProps, {
+    code: 'invalid-type',
+    description,
+    check(value, context) {
+        if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+            context.issue({ message: 'Expected an object.', fix: 'Pass the props as a JSON object.' });
+        }
+    },
+});
+/** A catalog component placed inline on a free slide. */
+export const componentItem = t.object({
+    type: t.literal('component'),
+    id: t.optional(slideId),
+    component: t.string({ pattern: COMPONENT_ID_PATTERN, max: 64 }),
+    props: objectProps('Component props (bounded JSON), validated by the host registry.'),
+    height: t.optional(t.enum(COMPONENT_HEIGHTS)),
+    ...stepFields,
+});
+function isBag(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+/** Check one item's head, then its nested blocks, reporting through the refine context. */
+function checkItem(value, path, context, depth) {
+    if (!isBag(value)) {
+        context.issue({
+            code: 'invalid-block',
+            path,
+            message: 'A slide item is a block object with a `type`.',
+            fix: 'Use {"type": "text", "markdown": "…"} or {"type": "component", "component": "…", "props": {}}.',
+        });
+        return;
+    }
+    const isComponent = value.type === 'component';
+    const head = {};
+    if (isComponent)
+        Object.assign(head, value);
+    else {
+        for (const key of ['type', 'id', 'step', 'fragment', 'reveal', 'tone']) {
+            if (Object.hasOwn(value, key))
+                head[key] = value[key];
+        }
+    }
+    const result = validate(isComponent ? componentItem : blockHead, head, { maxIssues: 50 });
+    for (const issue of result.issues) {
+        context.issue({
+            code: issue.code,
+            path: [...path, ...issue.path],
+            message: issue.message,
+            ...(issue.fix === undefined ? {} : { fix: issue.fix }),
+            severity: issue.severity,
+        });
+    }
+    if (isComponent || depth >= BLOCK_JSON_LIMITS.depth)
+        return;
+    forEachNested(value, path, (child, childPath) => {
+        checkItem(child, childPath, context, depth + 1);
+    });
+}
+/** Visit the nested blocks of a block (see `BLOCK_CONTAINERS`). */
+export function forEachNested(block, path, visit) {
+    for (const key of BLOCK_CONTAINERS.lists) {
+        const list = block[key];
+        if (Array.isArray(list)) {
+            list.forEach((child, i) => {
+                visit(child, [...path, key, i]);
+            });
+        }
+    }
+    const columns = block[BLOCK_CONTAINERS.columns];
+    if (Array.isArray(columns)) {
+        columns.forEach((column, c) => {
+            if (Array.isArray(column)) {
+                column.forEach((child, i) => {
+                    visit(child, [...path, BLOCK_CONTAINERS.columns, c, i]);
+                });
+            }
+        });
+    }
+    const panels = block[BLOCK_CONTAINERS.panels];
+    if (Array.isArray(panels)) {
+        panels.forEach((panel, p) => {
+            if (isBag(panel) && Array.isArray(panel.blocks)) {
+                panel.blocks.forEach((child, i) => {
+                    visit(child, [...path, BLOCK_CONTAINERS.panels, p, 'blocks', i]);
+                });
+            }
+        });
+    }
+}
+/**
+ * One free-slide item: a block (any `@texuli/blocks` block, checked here as
+ * bounded JSON with a block head) or a component item. Nested blocks in the
+ * known containers get the same head check.
+ */
+export const slideItem = t.refine(t.json({ ...BLOCK_JSON_LIMITS, text: 'multiline' }), {
+    code: 'invalid-block',
+    description: 'A block object: `type` (lowercase slug), optional `id` (slide id rules), step fields (`step` 0..1000, `fragment` or `reveal`, `tone`), nested blocks in `blocks`, `children`, `columns` and `panels[].blocks`; or a component item {type: "component", component, props, height?}. The host validates block bodies and component props.',
+    check(value, context) {
+        checkItem(value, [], context, 0);
+    },
+});
+// ---------------------------------------------------------------------------
+// Slides
+const slideBaseShape = {
+    id: slideId,
+    title: t.optional(line(DECK_MODEL_LIMITS.titleLength)),
+    notes: t.optional(multiline(DECK_MODEL_LIMITS.notesLength), {
+        description: 'Speaker notes (multi-line, at most 6000 code points).',
+    }),
+    hidden: t.optional(t.boolean(), {
+        description: 'Hidden slides stay out of navigation and print unless the host asks.',
+    }),
+    background: t.optional(deckBackground),
+    transition: t.optional(deckTransition),
+    theme: t.optional(deckThemeReference),
+    steps: t.optional(t.array(line(DECK_MODEL_LIMITS.stepLabelLength), { max: DECK_MODEL_LIMITS.stepLabels }), { description: 'Step labels: `steps[i]` names step i + 1.' }),
+};
+const slideBase = t.object(slideBaseShape);
+function layoutSlide(id) {
+    return t.object({
+        ...slideBaseShape,
+        layout: t.literal(id),
+        props: t.lazy(() => layoutPropsSchema(id), {
+            name: id,
+            description: `Props of the ${DECK_LAYOUTS[id].label.toLowerCase()} layout.`,
+        }),
+    }, { description: DECK_LAYOUTS[id].description });
+}
+export const freeSlide = t.object({
+    ...slideBaseShape,
+    layout: t.literal('free'),
+    master: t.optional(t.enum(SLIDE_MASTERS), { description: "Default 'content'." }),
+    blocks: t.array(slideItem, { max: DECK_MODEL_LIMITS.freeBlocks }),
+}, { description: 'A free slide: blocks and component items, arranged by a master.' });
+export const componentSlide = t.object({
+    ...slideBaseShape,
+    layout: t.literal('component'),
+    component: t.object({
+        component: t.string({ pattern: COMPONENT_ID_PATTERN, max: 64 }),
+        props: objectProps('Component props (bounded JSON), validated by the host registry.'),
+    }),
+}, { description: 'A whole-slide catalog component.' });
+export const customSlide = t.object({
+    ...slideBaseShape,
+    layout: t.literal('custom'),
+    props: t.object({
+        component: styleSlug,
+        data: t.optional(objectProps('Data for the host component (bounded JSON).')),
+    }),
+}, { description: 'A slide painted by a host-registered component (a placeholder without one).' });
+const SLIDE_OPTIONS = [
+    ...DECK_CATALOG_LAYOUT_IDS.map(layoutSlide),
+    freeSlide,
+    componentSlide,
+    customSlide,
+];
+/** One slide, told apart by `layout` (an unknown one is a single `unknown-layout` issue). */
+export const deckSlide = t.union(SLIDE_OPTIONS, {
+    discriminator: 'layout',
+    code: 'unknown-layout',
+    description: 'A slide: a catalog layout with props, a free slide, a component or a custom slide.',
+});
+// ---------------------------------------------------------------------------
+// The deck
+const deckShape = {
+    formatVersion: t.literal(DECK_FORMAT_VERSION, {
+        code: 'unsupported-version',
+        description: 'Always 2. Older decks convert with migrateDeck.',
+    }),
+    meta: deckMeta,
+    style: t.optional(deckStyle),
+    navigation: t.optional(deckNavigation),
+    outline: t.optional(deckOutline),
+    slides: t.array(deckSlide, { min: 1, max: DECK_MODEL_LIMITS.slides }),
+};
+/** The deck document (model v2). Cross-field rules run in `parseDeck`. */
+export const deckSchema = t.object(deckShape, {
+    description: 'A Texuli deck (model v2). Cross-field rules checked by parseDeck: unique slide, section and block ids; sections name known slides, each slide in at most one section, stack sections contiguous; navigation.start is a visible slide; not every slide hidden; at most 32 steps per slide; fragment and reveal exclusive.',
+});
+/** True when `layout` is a slide kind or a catalog layout id. */
+export function isSlideLayout(value) {
+    return typeof value === 'string' && DECK_SLIDE_LAYOUTS.includes(value);
+}
+/** True when `value` matches the slide id syntax. */
+export function isSlideId(value) {
+    return typeof value === 'string' && new RegExp(SLIDE_ID_PATTERN, 'u').test(value);
+}
+/**
+ * The JSON Schema 2020-12 document of a v2 deck, generated from the same
+ * schemas `parseDeck` validates with. Each catalog layout's props is a
+ * `$defs` entry named by its id (`#/$defs/title-hero`); cross-field rules are
+ * described in `description`.
+ */
+export function deckJsonSchema(options = {}) {
+    return toJsonSchema(deckSchema, {
+        ...(options.$id === undefined ? {} : { $id: options.$id }),
+        title: 'Texuli deck (model v2)',
+    });
+}

package/dist/model/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @texuli/deck/model: deck model v2 (ADR-009). The schemas and types,
+ * `parseDeck` with all-issues diagnostics, the untrusted loader, migration
+ * from Texuli v1, grammar trees and Protoyard, the JSON Schema export, the
+ * diagnostic code table, and the leaf modules: layouts, style and themes,
+ * backgrounds, steps and motion.
+ */
+export * from './backgrounds/index.js';
+export { DECK_CODES, type DeckCode, type DeckCodeInfo, type DeckIssue, isDeckCode, } from './codes.js';
+export { BLOCK_CONTAINERS, BLOCK_JSON_LIMITS, BLOCK_TONES, BLOCK_TYPE_PATTERN, COMPONENT_HEIGHTS, COMPONENT_ID_PATTERN, type ComponentSlide, type CustomSlide, componentItem, componentSlide, customSlide, DECK_DIRECTIONS, DECK_FORMAT_VERSION, DECK_MODEL_LIMITS, DECK_SLIDE_KINDS, DECK_SLIDE_LAYOUTS, type Deck, type DeckDirection, type DeckJsonSchemaOptions, type DeckMeta, type DeckNavigation, type DeckOutline, type DeckSection, type DeckSlide, type DeckSlideKind, type DeckSlideLayout, deckJsonSchema, deckMeta, deckNavigation, deckOutline, deckSchema, deckSection, deckSlide, type FreeSlide, forEachNested, freeSlide, ISO_DATE_PATTERN, isSlideId, isSlideLayout, type JsonObject, type LayoutSlide, LOCALE_PATTERN, SLIDE_MASTERS, type SlideBase, type SlideBlock, type SlideComponentItem, type SlideItem, type SlideMasterId, STEP_FIELD_KEYS, slideItem, } from './deck.js';
+export * from './layouts/index.js';
+export { DEFAULT_UNTRUSTED_DECK_LIMITS, jsonErrorOffset, jsonTextDepth, lineColumn, loadUntrustedDeck, type UntrustedDeckLimits, type UntrustedDeckOptions, type UntrustedDeckResult, } from './loader.js';
+export { DECK_SOURCES, type DeckMigration, type DeckSource, detectDeckShape, migrateDeck, } from './migrate.js';
+export * from './motion/index.js';
+export { type DeckComponentInput, type DeckHookResult, type DeckParseResult, type ParseDeckOptions, parseDeck, stripStepFields, } from './parse.js';
+export { copyPlainData, type PlainCopyOptions, type PlainCopyResult, stripHiddenCharacters, utf8Length, } from './plain.js';
+export * from './shared.js';
+export * from './steps/index.js';
+export * from './style/index.js';

package/dist/model/index.js

@@ -0,0 +1,19 @@
+/**
+ * @texuli/deck/model: deck model v2 (ADR-009). The schemas and types,
+ * `parseDeck` with all-issues diagnostics, the untrusted loader, migration
+ * from Texuli v1, grammar trees and Protoyard, the JSON Schema export, the
+ * diagnostic code table, and the leaf modules: layouts, style and themes,
+ * backgrounds, steps and motion.
+ */
+export * from "./backgrounds/index.js";
+export { DECK_CODES, isDeckCode, } from "./codes.js";
+export { BLOCK_CONTAINERS, BLOCK_JSON_LIMITS, BLOCK_TONES, BLOCK_TYPE_PATTERN, COMPONENT_HEIGHTS, COMPONENT_ID_PATTERN, componentItem, componentSlide, customSlide, DECK_DIRECTIONS, DECK_FORMAT_VERSION, DECK_MODEL_LIMITS, DECK_SLIDE_KINDS, DECK_SLIDE_LAYOUTS, deckJsonSchema, deckMeta, deckNavigation, deckOutline, deckSchema, deckSection, deckSlide, forEachNested, freeSlide, ISO_DATE_PATTERN, isSlideId, isSlideLayout, LOCALE_PATTERN, SLIDE_MASTERS, STEP_FIELD_KEYS, slideItem, } from "./deck.js";
+export * from "./layouts/index.js";
+export { DEFAULT_UNTRUSTED_DECK_LIMITS, jsonErrorOffset, jsonTextDepth, lineColumn, loadUntrustedDeck, } from "./loader.js";
+export { DECK_SOURCES, detectDeckShape, migrateDeck, } from "./migrate.js";
+export * from "./motion/index.js";
+export { parseDeck, stripStepFields, } from "./parse.js";
+export { copyPlainData, stripHiddenCharacters, utf8Length, } from "./plain.js";
+export * from "./shared.js";
+export * from "./steps/index.js";
+export * from "./style/index.js";