@refrakt-md/runes 0.38.0 → 0.40.0

package/dist/lib/composition.d.ts

@@ -0,0 +1,152 @@
+import type { Config, Node, RenderableTreeNodes, Schema, SchemaAttribute } from '@markdoc/markdoc';
+import type { ContentModel, ResolvedContent } from '@refrakt-md/types';
+import type { RuneConfig } from '@refrakt-md/transform';
+import type { SchemaTable } from './schema-table.js';
+import { SchemaSideTable } from './schema-side-table.js';
+import type { RegistersDeclaration } from './registers.js';
+/**
+ * A composition template, as `createContentModelSchema` receives it — the third
+ * of D5's three mutually exclusive emit paths, beside `transform` and `emits`.
+ */
+export interface CompositionTemplate {
+    /** The composed rune's kebab-case name — its `data-rune`. */
+    rune: string;
+    /** The root element. */
+    tag: string;
+    /** Other names the rune answers to. A template placing one of them places itself. */
+    aliases?: readonly string[];
+    /** The Markdoc template body. */
+    body: string;
+    /** The `blocks` the rune declares — what `{% metablock %}` may name (D7). */
+    blocks?: readonly string[];
+}
+/** One node of a composition's expansion, as the contract records it (D6). */
+export interface CompositionOutlineNode {
+    /** A rune the template places. */
+    rune?: string;
+    /** A slot, by name; `''` for a bare `{% slot /%}` inside an `each`. */
+    slot?: string;
+    /** The slot iterates its field. */
+    each?: true;
+    /** The slot carries fallback content. */
+    fallback?: true;
+    /** A Markdoc node the template writes itself (`heading`, `paragraph`, …). */
+    node?: string;
+    /** `if` — a branch the template takes on an attribute. */
+    conditional?: true;
+    /** A declared meta block placed with `{% metablock %}` (D7). */
+    metablock?: string;
+    children?: CompositionOutlineNode[];
+}
+/** What construction learned about a composition — recorded per schema. */
+export interface CompositionInfo {
+    rune: string;
+    /** Slot names in template order — the composed rune's published part names (D10c). */
+    slots: string[];
+    /** Every rune the template places, each with the nearest placed rune around it. */
+    placements: Array<{
+        rune: string;
+        parent?: string;
+    }>;
+    /** The template's structure, for `contracts` (D6). */
+    outline: CompositionOutlineNode[];
+    /** The schema type the composed rune declares, if any. */
+    schemaType?: string;
+    /** The generated block-less config (D2a), when built from a definition. */
+    config?: RuneConfig;
+    /** The config key the engine finds it under. */
+    typeName?: string;
+}
+/** Compositions by schema — the same pattern as `schemaTables`: tooling has only
+ *  the schema to read from. */
+export declare const schemaCompositions: SchemaSideTable<CompositionInfo>;
+/** The composition a schema renders, if it is one. */
+export declare function compositionFor(schema: unknown): CompositionInfo | undefined;
+/** Schema types a placed rune may emit under a composed type: a media object
+ *  that becomes a property of the outer entity, not a peer of it (D9). */
+export declare const SUBORDINATE_SCHEMA_TYPES: ReadonlySet<string>;
+export interface CompiledComposition {
+    /** The transform `createContentModelSchema` calls where it would call `transform`. */
+    transform: (resolved: ResolvedContent, attrs: Record<string, any>, config: Config, node: Node) => RenderableTreeNodes;
+    info: CompositionInfo;
+}
+export interface CompileCompositionOptions {
+    contentModel: ContentModel | ((attrs: Record<string, any>) => ContentModel);
+    /** The attributes the rune declares — what `$attrs` may name. */
+    attributes: readonly string[];
+    /** The rune's schema table, for its declared type (D9). */
+    schema?: SchemaTable;
+    /** The rune's registration, for D10b's copy into the field bag. */
+    registers?: RegistersDeclaration;
+}
+/**
+ * Check a template against the rune's content model and attributes, and build
+ * the transform that renders it. Called once, at schema construction. Throws,
+ * naming the rune and the offending tag, slot, field or name, rather than
+ * building anything it cannot honour.
+ */
+export declare function compileComposition(template: CompositionTemplate, options: CompileCompositionOptions): CompiledComposition;
+/**
+ * A composed rune's definition, parsed. The template is still source; it is
+ * checked and compiled by `createContentModelSchema`.
+ */
+export interface CompositionDefinition {
+    rune: string;
+    tag: string;
+    aliases?: string[];
+    description?: string;
+    attributes: Record<string, SchemaAttribute>;
+    contentModel: ContentModel;
+    schema?: SchemaTable;
+    registers?: RegistersDeclaration;
+    metaFields?: Record<string, unknown>;
+    blocks?: Record<string, unknown>;
+    provides?: string[];
+    template: string;
+}
+/** kebab-case → PascalCase: the config key the engine finds a rune under. */
+export declare function composedTypeName(rune: string): string;
+/**
+ * Split and parse a definition. The rune's name is the file's name (SPEC-153
+ * D9), passed in; a frontmatter key restating it is rejected rather than
+ * silently preferred.
+ */
+export declare function parseCompositionDefinition(rune: string, source: string): CompositionDefinition;
+/**
+ * The generated, block-less engine config of a composed rune (D2a). Not
+ * hand-written beside the definition: modifiers come from its enum attributes
+ * and from every attribute a `metaFields` entry reads, and `metaFields` /
+ * `blocks` are carried as declared.
+ *
+ * The second source is what lets a placed meta block render (D7): the engine
+ * resolves a field against the rune's modifier values, exactly as it does for a
+ * tree-owning rune — which must declare the same attributes as modifiers for
+ * its own blocks to fill.
+ */
+export declare function composedRuneConfig(def: CompositionDefinition): RuneConfig;
+/** One rune as the catalog-wide checks see it. */
+export interface CompositionCatalogEntry {
+    schema?: Schema;
+    /** The rune's `data-rune`, when it differs from its tag name (`tabs` renders
+     *  as `tab-group`). What `requiresParent` names. */
+    dataRune?: string;
+    seoType?: string;
+    /** Other names the rune answers to. */
+    aliases?: readonly string[];
+    /** From the rune's engine config (SPEC-084). */
+    requiresParent?: string;
+}
+/**
+ * The checks that need every rune in hand: a composition cycle (A places B
+ * places A), a composed type placed over a peer type (D9), and a placed rune
+ * that requires a parent the template does not give it (D12). Run once the
+ * catalog is assembled — by `mergePlugins`, before any page renders — and
+ * throws on the first problem, naming the runes involved.
+ *
+ * D9 is relational: a composition that declares no type of its own may place
+ * an entity rune, because then exactly one type exists in the subtree. The
+ * check fires only when the composed rune declares a type and a placed rune
+ * declares a non-subordinate one.
+ */
+export declare function checkCompositions(catalog: Record<string, CompositionCatalogEntry>, tableOf: (schema: Schema) => SchemaTable | undefined): void;
+//# sourceMappingURL=composition.d.ts.map

package/dist/lib/composition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"composition.d.ts","sourceRoot":"","sources":["../../src/lib/composition.ts"],"names":[],"mappings":"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"}