@bendyline/squisq 1.5.0 → 1.5.2

package/README.md

@@ -18,11 +18,24 @@ npm install @bendyline/squisq
 | Module       | Description                                                                      |
 | ------------ | -------------------------------------------------------------------------------- |
 | **schemas**  | Type definitions — `Doc`, `BlockTemplate`, `Viewport`, `Theme`, `LayoutStrategy` |
-| **doc**      | Template registry, 17 block templates, animation/theme utilities                 |
+| **doc**      | Template registry, 23 block templates, animation/theme utilities                 |
 | **markdown** | Markdown parsing, stringifying, AST types (`MarkdownDocument`), tree utilities   |
 | **spatial**  | Haversine distance, Geohash encode/decode                                        |
 | **storage**  | `StorageAdapter` interface, Memory + LocalStorage + LocalForage adapters         |
 
+## New in this release
+
+The Squiggly Square markdown standard (see [`docs/SquigglySquare.md`](../../docs/SquigglySquare.md)) gained several authoring capabilities:
+
+- **[Standalone annotations](../../docs/SquigglySquare.md#standalone-annotations)** — a top-level paragraph that is exactly `{[templateName …]}` becomes a heading-less template block; the body that follows it is its contents.
+- **[Inline attribute coercion](../../docs/SquigglySquare.md#inline-attribute-coercion)** — `{[map center="47.6,-122.3" zoom=9]}` and `{[twoColumn left="Espresso|Bold"]}` now render without a data fence (typed via `TEMPLATE_INPUT_DESCRIPTORS`).
+- **[Validation additions](../../docs/SquigglySquare.md#validation)** — new `unknown-input` / `invalid-input-value` / `missing-input` warnings plus `possible-data-fence` / `conflicting-annotation-key` info diagnostics (a new `info` severity).
+- **[YAML data fences](../../docs/SquigglySquare.md#structured-data-fences)** now accept one level of nested mappings (a `map` `center` can be pure YAML).
+- **[Multi-line frontmatter](../../docs/SquigglySquare.md#multi-line-frontmatter)** — `squisq-custom-templates` / `squisq-custom-themes` can be authored as pretty JSON via YAML literal block scalars (`key: |-`).
+- **Custom-template tokens v2** (see [`docs/SquigglySquare.md`](../../docs/SquigglySquare.md), "Registering custom templates") — `{attr:key}`, pipe defaults on every token, and per-layer `repeat` with `{item}` / `{index}` tokens.
+
+New `@bendyline/squisq/doc` exports powering the above: `coerceTemplateParams`, `lintTemplateParams`, `TEMPLATE_INPUT_DESCRIPTORS`, and `replaceDataFence`.
+
 ## Subpath Imports
 
 Import only what you need:

package/dist/{ContentContainer-DNx460y8.d.ts → ContentContainer-BXUlIf18.d.ts}

@@ -9,9 +9,9 @@
  * Paths are forward-slash separated strings relative to the container root
  * (e.g., 'images/hero.jpg', 'index.md'). No leading slash.
  *
- * Implementations:
+ * Implementations (in core):
  * - MemoryContentContainer — in-memory Map (for zip import, tests, transient use)
- * - SlotContentContainer — backed by IndexedDB slot storage (in the site package)
+ * - ScopedContentContainer — a prefix-scoped view onto a parent container
  */
 /**
  * Metadata about a file in a ContentContainer.
@@ -39,6 +39,10 @@ interface ContentContainer {
     removeFile(path: string): Promise<void>;
     /**
      * List files in the container.
+     *
+     * Returns file **entries** (`ContentEntry[]` with `.path`/`.mimeType`/`.size`),
+     * NOT bare path strings — despite the name. Read `entry.path` for the path;
+     * calling string methods (e.g. `.startsWith`) directly on an entry will throw.
      * @param prefix — Optional path prefix to filter by (e.g., 'images/')
      */
     listFiles(prefix?: string): Promise<ContentEntry[]>;

package/dist/{Doc-BsMkmzH8.d.ts → Doc-BBVGq1_9.d.ts}

@@ -1266,6 +1266,47 @@ declare function lookupRegisteredTheme(id: string | undefined): Theme | undefine
  * ratio to mount with, and the thumbnail renderer which viewBox to use.
  */
 
+/**
+ * Iteration directive for a custom-template layer.
+ *
+ * A layer that carries a `repeat` is cloned once per item of a source
+ * collection at render time (see `resolveTokens`). The clones are laid
+ * out in a row or column, offset from the base position by the layer's
+ * own width/height plus `gap`, and each clone resolves per-item tokens
+ * (`{item}`, `{item:src}`, `{item:label}`, `{index}`) against its item.
+ */
+interface LayerRepeat {
+    /**
+     * Which of the source Block's collections to iterate:
+     *   - `images`    — every image in the block body (alt + url)
+     *   - `children`  — child block titles
+     *   - `listItems` — top-level list-item text in the block body
+     */
+    source: 'images' | 'children' | 'listItems';
+    /**
+     * Layout axis for the clones. `column` (default) stacks them
+     * vertically (offsets `position.y`); `row` lays them out horizontally
+     * (offsets `position.x`).
+     */
+    direction?: 'row' | 'column';
+    /**
+     * Extra spacing added between consecutive clones, in the same unit as
+     * the layer's `width`/`height`. Defaults to 24.
+     */
+    gap?: number;
+    /** Cap on the number of clones rendered (omit for "all items"). */
+    max?: number;
+}
+/**
+ * A custom-template layer: a normal render `Layer` that may additionally
+ * carry a `repeat` directive. This is a strict superset of the core
+ * `Layer` type used only inside `CustomTemplateDefinition.layers`; the
+ * resolver strips `repeat` before emitting the final `Layer[]`, so the
+ * core `Layer` type is never widened.
+ */
+type CustomTemplateLayer = Layer & {
+    repeat?: LayerRepeat;
+};
 /**
  * A single user-defined template. Stored in `Doc.customTemplates`
  * (frontmatter-backed) or in the user's local library.
@@ -1297,12 +1338,20 @@ interface CustomTemplateDefinition {
      * `position.width` / `position.height` should be a `%`-string at
      * save time (the designer's normalizePositions step enforces this).
      *
-     * Tokens supported in v1:
+     * Tokens supported (grammar v2):
      *   - TextLayer.content.text — `{title}`, `{content}`, `{children}`,
-     *     `{image:N}` (substitutes the Nth image's alt text)
-     *   - ImageLayer.content.src — `{image:N}` (substitutes the URL)
+     *     `{image:N}` (Nth image's alt text), `{attr:key}` (block
+     *     attribute), plus a pipe default on any token
+     *     (`{attr:subtitle|Untitled}`).
+     *   - ImageLayer.content.src — `{image:N}` (the URL) and `{attr:key}`,
+     *     with pipe defaults (`{image:1|fallback.jpg}`).
+     *   - Inside a layer with `repeat`, per-item tokens: `{item}`,
+     *     `{item:src}`, `{item:label}`, `{index}` (1-based).
+     *
+     * A layer may carry a `repeat` directive (see {@link LayerRepeat}) to
+     * be cloned once per item of a source collection.
      */
-    layers: Layer[];
+    layers: CustomTemplateLayer[];
 }
 /**
  * Tag value for the YAML frontmatter key that carries inlined custom
@@ -1354,8 +1403,9 @@ interface StartBlockConfig {
 interface DocDiagnostic {
     /** `error` = the author's intent could not be honored (e.g. unparseable
      *  data fence); `warning` = something looks wrong but rendering proceeds
-     *  with a fallback (e.g. unknown template name). */
-    severity: 'error' | 'warning';
+     *  with a fallback (e.g. unknown template name); `info` = nothing is
+     *  broken, but the author may want to know (e.g. a redundant annotation). */
+    severity: 'error' | 'warning' | 'info';
     /** Stable machine-readable code (e.g. `unknown-template`, `duplicate-id`,
      *  `unresolved-connection`, `data-fence-parse`, `missing-asset`). */
     code: string;
@@ -1412,9 +1462,9 @@ interface Doc {
      *
      * Populated from the markdown frontmatter key
      * `squisq-custom-templates`. The template-expansion pipeline
-     * (`expandDocBlocks`) merges these into the registry before walking
-     * blocks, so a heading annotated `{[myhero]}` resolves against a
-     * doc-defined template named `myhero`.
+     * (`expandDocBlocks` in `doc/templates/index.ts`) merges these into
+     * the registry before walking blocks, so a heading annotated
+     * `{[myhero]}` resolves against a doc-defined template named `myhero`.
      *
      * Library templates (stored in localStorage on the editor side) are
      * NOT auto-loaded here — applying a library template to a block
@@ -1458,6 +1508,16 @@ interface Doc {
  * - `sourceHeading` references the original MarkdownHeading node
  * - `contents` holds the body markdown between this heading and the next
  * - `children` holds sub-heading blocks (e.g., H2s under an H1)
+ *
+ * Four adjacent fields carry template information — do not confuse them:
+ * - `template` — the *resolved* template id this block renders with.
+ * - `templateOverrides` — raw `{[…]}` inline params (always strings).
+ * - `templateData` — structured inputs from a data fence / GFM table
+ *   (parsed types, not strings).
+ * - `sourceAnnotation.template` — the raw *requested* template name for a
+ *   standalone-annotation block (before alias resolution).
+ * Merge order at render time: template defaults → `templateData` →
+ * `templateOverrides`.
  */
 interface Block {
     /** Unique identifier for this block.
@@ -1482,7 +1542,7 @@ interface Block {
     layers?: Layer[];
     /** Entry transition from previous block */
     transition?: Transition;
-    /** Template name that generated this block (for debugging) */
+    /** Resolved template id this block renders with (see the quartet note above). */
     template?: string;
     /**
      * True when `template` was chosen by content-aware auto-picking
@@ -1491,6 +1551,29 @@ interface Block {
      * annotations, keeping the markdown round-trip lossless.
      */
     autoTemplate?: boolean;
+    /**
+     * True when this block was produced from a *standalone* `{[templateName …]}`
+     * annotation paragraph in another block's body (rather than from a heading).
+     * Such blocks have no `sourceHeading`; `docToMarkdown` re-emits their
+     * annotation as a synthesized paragraph before their `contents` so the
+     * markdown round-trips. See `annotationBlocks.ts`.
+     *
+     * Presence-marker: only ever `true` (never `false`). Test with
+     * `block.standaloneAnnotation` presence, not as a boolean toggle.
+     */
+    standaloneAnnotation?: true;
+    /**
+     * The annotation a standalone block was built from — the raw (un-resolved)
+     * template name and its params, in author order. Round-tripped by
+     * `docToMarkdown` (via `serializeAnnotation`) and read by validation as the
+     * raw requested template name (symmetric with
+     * `sourceHeading.templateAnnotation`). Present only when
+     * `standaloneAnnotation` is true.
+     */
+    sourceAnnotation?: {
+        template?: string;
+        params?: Record<string, string>;
+    };
     /**
      * Display title for template rendering.
      * Extracted from the sourceHeading when the block is created by markdownToDoc().
@@ -2090,9 +2173,5 @@ declare function getBlockAtTime(blocks: Block[], time: number): Block | null;
  * Find the caption phrase that should be displayed at a given time.
  */
 declare function getCaptionAtTime(captions: CaptionTrack | undefined, time: number): CaptionPhrase | null;
-/**
- * Validate a Doc for completeness.
- */
-declare function validateDoc(script: Doc): string[];
 
-export { type MediaClip as $, type AccentImage as A, type Block as B, type CaptionPhrase as C, DARK_SURFACE as D, type DrawingBlockInput as E, FRONTMATTER_CUSTOM_TEMPLATES_KEY as F, FRONTMATTER_CUSTOM_THEMES_KEY as G, type FactCardInput as H, type FontFamily as I, type FontFamilyKind as J, type FullBleedQuoteInput as K, type GradientBackgroundConfig as L, type ImageBackgroundConfig as M, type ImageLayer as N, type ImageTreatment as O, type ImageWithCaptionInput as P, LIGHT_SURFACE as Q, type Layer as R, type LayoutHints as S, type LeftFeatureInput as T, type LinearGradient as U, type ListBlockInput as V, type MapBlockInput as W, type MapLayer as X, type MapMarker as Y, type MapTileStyle as Z, type MarkerStyle as _, type AccentPosition as a, getSegmentAtTime as a$, type PathLayer as a0, type PatternBackgroundConfig as a1, type PersistentLayer as a2, type PersistentLayerConfig as a3, type PersistentLayerTemplate as a4, type PersistentLayerTemplateConfig as a5, type PersistentLayerTemplateType as a6, type PhotoGridInput as a7, type Position as a8, type ProgressIndicatorConfig as a9, type ThemeSchemaVersion as aA, type ThemeSeedColors as aB, type ThemeStyle as aC, type ThemeTypography as aD, type TitleBlockInput as aE, type TitleCaptionConfig as aF, type TwoColumnInput as aG, VIEWPORT_PRESETS as aH, type VideoLayer as aI, type VideoPullQuoteInput as aJ, type VideoWithCaptionInput as aK, type ViewportConfig as aL, type ViewportOrientation as aM, type ViewportPreset as aN, type VignetteConfig as aO, applySurface as aP, calculateDuration as aQ, calculateFontScale as aR, createTemplateContext as aS, createTheme as aT, getAspectRatioString as aU, getBlockAtTime as aV, getCaptionAtTime as aW, getDocPlaybackDuration as aX, getLayoutHints as aY, getRegisteredThemes as aZ, getSafeTextBounds as a_, type PullQuoteInput as aa, type QuoteBlockInput as ab, type RawLayersInput as ac, type RenderStyle as ad, type RightFeatureInput as ae, type ScheduledClip as af, type SectionHeaderInput as ag, type ShapeFilter as ah, type ShapeLayer as ai, type ShapePattern as aj, type SolidBackgroundConfig as ak, type StartBlockConfig as al, type StatHighlightInput as am, type SurfaceScheme as an, THEME_SCHEMA_VERSION as ao, type TableLayer as ap, type TableLayerStyle as aq, type TemplateBlock as ar, type TemplateContext as as, type TemplateFunction as at, type TemplateRegistry as au, type TextLayer as av, type TextStyle as aw, type Theme as ax, type ThemeColorPalette as ay, type ThemeColorScheme as az, type AmbientGradientConfig as b, getTwoColumnPositions as b0, getViewport as b1, getViewportOrientation as b2, isPersistentLayerTemplate as b3, isTemplateBlock as b4, scaledFontSize$1 as b5, lookupRegisteredTheme as b6, registerTheme as b7, resolveMediaSchedule as b8, scaledFontSize as b9, unregisterTheme as ba, validateDoc as bb, type Animation as c, type AnimationType as d, type AudioBookmark as e, type AudioSegment as f, type AudioTimingData as g, type AudioTrack as h, type BlockConnection as i, type BorderStyle as j, type CaptionTrack as k, type CaptionWord as l, type ColorScheme as m, type ComparisonBarInput as n, type CornerBrandingConfig as o, type CustomTemplateDefinition as p, DEFAULT_DOC_FONT as q, DEFAULT_TITLE_FONT as r, type DataTableInput as s, type DateEventInput as t, type DeepPartial as u, type DefinitionCardInput as v, type DiagramBlockInput as w, type Doc as x, type DocBlock as y, type DocDiagnostic as z };
+export { type MapTileStyle as $, type AccentImage as A, type Block as B, type CaptionPhrase as C, DARK_SURFACE as D, type DocDiagnostic as E, type DrawingBlockInput as F, FRONTMATTER_CUSTOM_TEMPLATES_KEY as G, FRONTMATTER_CUSTOM_THEMES_KEY as H, type FactCardInput as I, type FontFamily as J, type FontFamilyKind as K, type FullBleedQuoteInput as L, type GradientBackgroundConfig as M, type ImageBackgroundConfig as N, type ImageLayer as O, type ImageTreatment as P, type ImageWithCaptionInput as Q, LIGHT_SURFACE as R, type Layer as S, type LayerRepeat as T, type LayoutHints as U, type LeftFeatureInput as V, type LinearGradient as W, type ListBlockInput as X, type MapBlockInput as Y, type MapLayer as Z, type MapMarker as _, type AccentPosition as a, getRegisteredThemes as a$, type MarkerStyle as a0, type MediaClip as a1, type PathLayer as a2, type PatternBackgroundConfig as a3, type PersistentLayer as a4, type PersistentLayerConfig as a5, type PersistentLayerTemplate as a6, type PersistentLayerTemplateConfig as a7, type PersistentLayerTemplateType as a8, type PhotoGridInput as a9, type ThemeColorPalette as aA, type ThemeColorScheme as aB, type ThemeSchemaVersion as aC, type ThemeSeedColors as aD, type ThemeStyle as aE, type ThemeTypography as aF, type TitleBlockInput as aG, type TitleCaptionConfig as aH, type TwoColumnInput as aI, VIEWPORT_PRESETS as aJ, type VideoLayer as aK, type VideoPullQuoteInput as aL, type VideoWithCaptionInput as aM, type ViewportConfig as aN, type ViewportOrientation as aO, type ViewportPreset as aP, type VignetteConfig as aQ, applySurface as aR, calculateDuration as aS, calculateFontScale as aT, createTemplateContext as aU, createTheme as aV, getAspectRatioString as aW, getBlockAtTime as aX, getCaptionAtTime as aY, getDocPlaybackDuration as aZ, getLayoutHints as a_, type Position as aa, type ProgressIndicatorConfig as ab, type PullQuoteInput as ac, type QuoteBlockInput as ad, type RawLayersInput as ae, type RenderStyle as af, type RightFeatureInput as ag, type ScheduledClip as ah, type SectionHeaderInput as ai, type ShapeFilter as aj, type ShapeLayer as ak, type ShapePattern as al, type SolidBackgroundConfig as am, type StartBlockConfig as an, type StatHighlightInput as ao, type SurfaceScheme as ap, THEME_SCHEMA_VERSION as aq, type TableLayer as ar, type TableLayerStyle as as, type TemplateBlock as at, type TemplateContext as au, type TemplateFunction as av, type TemplateRegistry as aw, type TextLayer as ax, type TextStyle as ay, type Theme as az, type AmbientGradientConfig as b, getSafeTextBounds as b0, getSegmentAtTime as b1, getTwoColumnPositions as b2, getViewport as b3, getViewportOrientation as b4, isPersistentLayerTemplate as b5, isTemplateBlock as b6, scaledFontSize$1 as b7, lookupRegisteredTheme as b8, registerTheme as b9, resolveMediaSchedule as ba, scaledFontSize as bb, unregisterTheme as bc, type Animation as c, type AnimationType as d, type AudioBookmark as e, type AudioSegment as f, type AudioTimingData as g, type AudioTrack as h, type BlockConnection as i, type BorderStyle as j, type CaptionTrack as k, type CaptionWord as l, type ColorScheme as m, type ComparisonBarInput as n, type CornerBrandingConfig as o, type CustomTemplateDefinition as p, type CustomTemplateLayer as q, DEFAULT_DOC_FONT as r, DEFAULT_TITLE_FONT as s, type DataTableInput as t, type DateEventInput as u, type DeepPartial as v, type DefinitionCardInput as w, type DiagramBlockInput as x, type Doc as y, type DocBlock as z };

package/dist/{ImageEditDoc-DvoeHMP9.d.ts → ImageEditDoc-FuyGtt6o.d.ts}

@@ -1,4 +1,4 @@
-import { N as ImageLayer, av as TextLayer, ai as ShapeLayer, a0 as PathLayer } from './Doc-BsMkmzH8.js';
+import { O as ImageLayer, ax as TextLayer, ak as ShapeLayer, a2 as PathLayer } from './Doc-BBVGq1_9.js';
 
 /**
  * ImageEditDoc — JSON document describing a layered, editable image.