@bendyline/squisq 1.4.0 → 1.5.0

package/dist/{types-BdZkdJ3z.d.ts → types-DlAZ7MW4.d.ts}

@@ -1,3 +1,53 @@
+/**
+ * Shared transition vocabulary for block-to-block slide changes.
+ *
+ * The canonical names are based on PowerPoint / PresentationML transition
+ * names where possible, with a few legacy renderer aliases kept so older
+ * Squisq documents continue to work.
+ */
+declare const DEFAULT_TRANSITION_DURATION_SECONDS = 0.7;
+declare const TRANSITION_TYPES: readonly ["cut", "fade", "dissolve", "push", "wipe", "split", "reveal", "randomBars", "shape", "uncover", "cover", "zoom", "pan", "flash", "fallOver", "drape", "curtains", "wind", "prestige", "fracture", "crush", "peelOff", "pageCurl", "airplane", "origami", "checkerboard", "blinds", "clock", "ripple", "honeycomb", "glitter", "vortex", "shred", "switch", "flip", "gallery", "cube", "doors", "box", "ferrisWheel", "conveyor", "rotate", "window", "orbit", "flyThrough", "morph", "checker", "circle", "comb", "diamond", "newsflash", "plus", "pull", "random", "randomBar", "strips", "wedge", "wheel", "prism", "warp", "ferris", "flythrough", "wheelReverse", "pageCurlDouble", "pageCurlSingle", "slideLeft", "slideRight", "slideUp", "slideDown"];
+type TransitionType = (typeof TRANSITION_TYPES)[number];
+declare const TRANSITION_DIRECTIONS: readonly ["left", "right", "up", "down", "in", "out", "horizontal", "vertical"];
+type TransitionDirection = (typeof TRANSITION_DIRECTIONS)[number];
+/**
+ * Transition between blocks.
+ *
+ * A block's transition is the lead-in from the previous block. The same
+ * transition drives the entering block and the previous block's exit.
+ */
+interface Transition {
+    /** Transition type */
+    type: TransitionType;
+    /** Duration in seconds. Defaults to DEFAULT_TRANSITION_DURATION_SECONDS. */
+    duration?: number;
+    /** Optional direction/variant for directional transitions. */
+    direction?: TransitionDirection;
+}
+declare function isTransitionType(value: string): value is TransitionType;
+declare function normalizeTransitionType(value: string): TransitionType | null;
+declare function normalizeTransitionDirection(value: string): TransitionDirection | null;
+declare function resolveTransitionDuration(transition: Transition | undefined, fallback?: number): number;
+/**
+ * Resolve the effective transition for a block: the authored value wins
+ * (markdown frontmatter and transform styles both write `block.transition`
+ * upstream), then the theme's `renderStyle.defaultTransition`, then
+ * `undefined` (the player's built-in default).
+ *
+ * Block 0 never gets a theme default — an entrance transition on the first
+ * block would dim the opening frames of every exported video.
+ *
+ * The theme parameter is structural (not `Theme`) to avoid a schema import
+ * cycle; pass any resolved theme.
+ */
+declare function resolveBlockTransition(block: {
+    transition?: Transition;
+}, theme: {
+    renderStyle: {
+        defaultTransition?: Transition;
+    };
+}, blockIndex: number): Transition | undefined;
+
 /**
  * Markdown DOM Types
  *
@@ -100,6 +150,63 @@ interface HeadingTemplateAnnotation {
     /** Optional key-value parameters (remaining `key=value` tokens) */
     params?: Record<string, string>;
 }
+/**
+ * A directed connection from one block to another, parsed from a heading
+ * attribute `connectsTo=target1,target2:type,target3`. Mirrors the schema
+ * `BlockConnection` type — duplicated here so this module stays
+ * dependency-free from the doc schema.
+ */
+interface BlockConnection {
+    /** Target block id. */
+    target: string;
+    /** Optional connection type/label (e.g., "flow", "requires"). */
+    type?: string;
+}
+/**
+ * Pandoc-style heading attribute block, parsed from `{#id .class key=value}`
+ * appearing at the end of a heading line (alongside, or instead of, the
+ * squisq-native `{[templateName …]}` block).
+ *
+ * @example
+ * ```markdown
+ * ## Architecture {#arch x=600 y=300 connectsTo=foo:flow,bar:requires}
+ * ```
+ * →
+ * ```ts
+ * {
+ *   id: 'arch',
+ *   params: { x: '600', y: '300', connectsTo: 'foo:flow,bar:requires' },
+ *   blockMeta: {
+ *     x: 600,
+ *     y: 300,
+ *     connectsTo: [{ target: 'foo', type: 'flow' }, { target: 'bar', type: 'requires' }],
+ *   },
+ * }
+ * ```
+ *
+ * `params` carries the raw pre-coercion strings (lossless for round-tripping),
+ * while `blockMeta` carries the typed values for known keys. Unknown keys flow
+ * to `metadata`.
+ */
+interface HeadingAttributes {
+    /** Block id from `#identifier` (overrides slug-from-heading). */
+    id?: string;
+    /** Class tokens from `.classname` (reserved for downstream use). */
+    classes?: string[];
+    /** All key=value attributes as raw strings (lossless source for serialization). */
+    params?: Record<string, string>;
+    /** Typed values for known block-meta keys (coerced from `params`). */
+    blockMeta?: {
+        x?: number;
+        y?: number;
+        startTime?: number;
+        duration?: number;
+        connectsTo?: BlockConnection[];
+        transition?: Transition;
+    };
+    /** Subset of `params` whose keys are NOT in the known-key registry. */
+    metadata?: Record<string, string>;
+}
 /**
  * ATX or setext heading (# Heading).
  */
@@ -116,6 +223,13 @@ interface MarkdownHeading extends MarkdownNodeBase {
      * stringification, so it round-trips transparently.
      */
     templateAnnotation?: HeadingTemplateAnnotation;
+    /**
+     * Pandoc-style heading attributes parsed from trailing `{#id .class key=value}`
+     * syntax. Independent from `templateAnnotation` — both may appear on the
+     * same heading in either order. Stripped from `children` during parsing
+     * and re-injected during stringification.
+     */
+    attributes?: HeadingAttributes;
 }
 /**
  * A paragraph of inline content.
@@ -528,4 +642,4 @@ interface StringifyOptions {
     setext?: boolean;
 }
 
-export type { MarkdownLinkReference as A, MarkdownList as B, MarkdownListItem as C, MarkdownMathBlock as D, MarkdownMention as E, MarkdownNode as F, MarkdownParagraph as G, HeadingTemplateAnnotation as H, MarkdownPoint as I, MarkdownSourcePosition as J, MarkdownStrikethrough as K, MarkdownStrong as L, MarkdownBlockNode as M, MarkdownTable as N, MarkdownTableCell as O, MarkdownTableRow as P, MarkdownText as Q, MarkdownTextDirective as R, MarkdownThematicBreak as S, ParseOptions as T, StringifyOptions as U, HtmlComment as a, HtmlElement as b, HtmlNode as c, HtmlText as d, MarkdownBlockquote as e, MarkdownBreak as f, MarkdownCodeBlock as g, MarkdownContainerDirective as h, MarkdownDefinitionDescription as i, MarkdownDefinitionList as j, MarkdownDefinitionTerm as k, MarkdownDocument as l, MarkdownEmphasis as m, MarkdownFootnoteDefinition as n, MarkdownFootnoteReference as o, MarkdownHeading as p, MarkdownHtmlBlock as q, MarkdownImage as r, MarkdownImageReference as s, MarkdownInlineCode as t, MarkdownInlineHtml as u, MarkdownInlineMath as v, MarkdownInlineNode as w, MarkdownLeafDirective as x, MarkdownLink as y, MarkdownLinkDefinition as z };
+export { type TransitionType as $, type MarkdownLinkDefinition as A, type MarkdownLinkReference as B, type MarkdownList as C, DEFAULT_TRANSITION_DURATION_SECONDS as D, type MarkdownListItem as E, type MarkdownMathBlock as F, type MarkdownMention as G, type HeadingAttributes as H, type MarkdownNode as I, type MarkdownParagraph as J, type MarkdownPoint as K, type MarkdownSourcePosition as L, type MarkdownBlockNode as M, type MarkdownStrikethrough as N, type MarkdownStrong as O, type MarkdownTable as P, type MarkdownTableCell as Q, type MarkdownTableRow as R, type MarkdownText as S, type MarkdownTextDirective as T, type MarkdownThematicBreak as U, type ParseOptions as V, type StringifyOptions as W, TRANSITION_DIRECTIONS as X, TRANSITION_TYPES as Y, type Transition as Z, type TransitionDirection as _, type HeadingTemplateAnnotation as a, isTransitionType as a0, normalizeTransitionDirection as a1, normalizeTransitionType as a2, resolveBlockTransition as a3, resolveTransitionDuration as a4, type HtmlComment as b, type HtmlElement as c, type HtmlNode as d, type HtmlText as e, type MarkdownBlockquote as f, type MarkdownBreak as g, type MarkdownCodeBlock as h, type MarkdownContainerDirective as i, type MarkdownDefinitionDescription as j, type MarkdownDefinitionList as k, type MarkdownDefinitionTerm as l, type MarkdownDocument as m, type MarkdownEmphasis as n, type MarkdownFootnoteDefinition as o, type MarkdownFootnoteReference as p, type MarkdownHeading as q, type MarkdownHtmlBlock as r, type MarkdownImage as s, type MarkdownImageReference as t, type MarkdownInlineCode as u, type MarkdownInlineHtml as v, type MarkdownInlineMath as w, type MarkdownInlineNode as x, type MarkdownLeafDirective as y, type MarkdownLink as z };

package/dist/versions/index.d.ts

@@ -1,29 +1,128 @@
+import { C as CoalesceOptions, V as Version, P as PrunePolicy, R as RevertOptions, S as SaveVersionOptions, a as SaveVersionResult } from '../types-D98li1gV.js';
+import { C as ContentContainer } from '../ContentContainer-DNx460y8.js';
+
 /**
- * Document version history for Squisq.
+ * Pure-ish version operations against a {@link ContentContainer}.
  *
- * Snapshots of the primary markdown document live inside the same
- * {@link ContentContainer} at `.versions/<basename>.<timestamp>.md`.
- * Hosts call {@link DocumentVersionManager.saveVersion} (or the
- * underlying {@link saveVersion}) when they want to stamp a new version;
- * the editor's auto-save effect calls it on idle. Either way, snapshots
- * are written only when the document differs from the latest one.
+ * These functions are the canonical implementation. {@link DocumentVersionManager}
+ * is a thin wrapper that captures a container reference for ergonomics.
+ */
+
+/**
+ * List all snapshots in the container, newest-first.
+ *
+ * @param basename Optional filter: when set, only versions whose basename
+ *   matches are returned.
+ */
+declare function listVersions(container: ContentContainer, basename?: string): Promise<Version[]>;
+/**
+ * Read the markdown content of a snapshot. Returns null if the snapshot
+ * doesn't exist.
+ */
+declare function readVersion(container: ContentContainer, version: Version | string): Promise<string | null>;
+/**
+ * Save a new snapshot of the document if its content differs from the
+ * latest existing snapshot.
+ */
+declare function saveVersion(container: ContentContainer, options?: SaveVersionOptions): Promise<SaveVersionResult>;
+/**
+ * Revert the document to a prior snapshot. By default, the *current*
+ * document is snapshotted first so the revert is itself recoverable.
+ */
+declare function revertToVersion(container: ContentContainer, version: Version | string, options?: RevertOptions): Promise<{
+    reverted: boolean;
+    snapshotted: Version | null;
+}>;
+/**
+ * Delete snapshots that don't satisfy the policy. Returns the deleted
+ * versions in their original (newest-first) order.
+ */
+declare function pruneVersions(container: ContentContainer, policy: PrunePolicy, basename?: string): Promise<Version[]>;
+/**
+ * Collapse adjacent snapshots that occurred close together — keeping the
+ * newer one — to keep history readable across rapid edits.
+ */
+declare function coalesceVersions(container: ContentContainer, options?: CoalesceOptions, basename?: string): Promise<Version[]>;
+
+/**
+ * Convenience wrapper around the version operations that captures a
+ * {@link ContentContainer} reference and an optional basename override.
  *
- * @example
- * ```ts
- * import { DocumentVersionManager } from '@bendyline/squisq/versions';
+ * Hosts that prefer a stable handle (e.g. to pass into a UI component)
+ * use this; everything it does is also reachable as a free function.
+ */
+
+interface DocumentVersionManagerOptions {
+    /**
+     * Override the document basename used in version filenames. Defaults to
+     * the basename of `container.getDocumentPath()` resolved at call time.
+     */
+    basename?: string;
+}
+declare class DocumentVersionManager {
+    private readonly container;
+    private readonly basename;
+    constructor(container: ContentContainer, options?: DocumentVersionManagerOptions);
+    saveVersion(options?: SaveVersionOptions): Promise<SaveVersionResult>;
+    listVersions(): Promise<Version[]>;
+    readVersion(version: Version | string): Promise<string | null>;
+    revertToVersion(version: Version | string, options?: RevertOptions): Promise<{
+        reverted: boolean;
+        snapshotted: Version | null;
+    }>;
+    pruneVersions(policy: PrunePolicy): Promise<Version[]>;
+    coalesceVersions(options?: CoalesceOptions): Promise<Version[]>;
+}
+
+/**
+ * Sortable, human-readable timestamps for version filenames.
  *
- * const versioning = new DocumentVersionManager(container);
- * const result = await versioning.saveVersion();
- * if (result.saved) console.log('Stamped', result.version);
+ * Format: ISO 8601 basic, UTC, second precision, `Z` suffix —
+ * e.g. `20260430T152030Z`. Lexicographic order matches chronological order,
+ * so `listFiles` returns versions in time order without parsing.
+ */
+/**
+ * Format a Date as a sortable, filename-safe UTC timestamp string.
+ */
+declare function formatVersionTimestamp(date: Date): string;
+/**
+ * Parse a version timestamp string back to a Date. Returns null if the input
+ * doesn't match the expected format.
+ */
+declare function parseVersionTimestamp(stamp: string): Date | null;
+/**
+ * The pattern a valid version timestamp matches. Exported so other modules
+ * can validate filenames without re-deriving the regex.
+ */
+declare const VERSION_TIMESTAMP_PATTERN: RegExp;
+
+/**
+ * Path conventions for version snapshots.
  *
- * const history = await versioning.listVersions();
- * await versioning.revertToVersion(history[0]);
- * await versioning.pruneVersions({ type: 'keep-last-n', n: 50 });
- * ```
- */
-export type { Version, SaveVersionOptions, SaveVersionResult, PrunePolicy, RevertOptions, CoalesceOptions, } from './types.js';
-export { saveVersion, listVersions, readVersion, revertToVersion, pruneVersions, coalesceVersions, } from './operations.js';
-export { DocumentVersionManager, type DocumentVersionManagerOptions, } from './DocumentVersionManager.js';
-export { formatVersionTimestamp, parseVersionTimestamp, VERSION_TIMESTAMP_PATTERN, } from './timestamp.js';
-export { VERSIONS_PREFIX, getDocBasename, buildVersionPath, parseVersionPath } from './paths.js';
-//# sourceMappingURL=index.d.ts.map
+ * Snapshots live at `<VERSIONS_PREFIX><basename>.<timestamp>[<-suffix>].md`.
+ * The optional numeric suffix (`-2`, `-3`, ...) is appended only when two
+ * snapshots collide on the same UTC second.
+ */
+/** Subfolder (inside the ContentContainer) that holds version snapshots. */
+declare const VERSIONS_PREFIX = ".versions/";
+/**
+ * Strip the directory and extension from a document path to produce the
+ * basename used in version filenames. `subdir/index.md` -> `index`.
+ */
+declare function getDocBasename(documentPath: string): string;
+/**
+ * Build a version snapshot path. Optionally append a collision suffix
+ * (e.g. `2`, `3`) when two saves land on the same UTC second.
+ */
+declare function buildVersionPath(basename: string, date: Date, collision?: number): string;
+/**
+ * Parse a version snapshot path. Returns null if it doesn't match the
+ * convention (so unrelated files stored under `.versions/` are ignored).
+ */
+declare function parseVersionPath(path: string): {
+    basename: string;
+    timestamp: Date;
+    collision: number;
+} | null;
+
+export { CoalesceOptions, DocumentVersionManager, type DocumentVersionManagerOptions, PrunePolicy, RevertOptions, SaveVersionOptions, SaveVersionResult, VERSIONS_PREFIX, VERSION_TIMESTAMP_PATTERN, Version, buildVersionPath, coalesceVersions, formatVersionTimestamp, getDocBasename, listVersions, parseVersionPath, parseVersionTimestamp, pruneVersions, readVersion, revertToVersion, saveVersion };

package/dist/versions/index.js

@@ -1,28 +1,35 @@
-/**
- * Document version history for Squisq.
- *
- * Snapshots of the primary markdown document live inside the same
- * {@link ContentContainer} at `.versions/<basename>.<timestamp>.md`.
- * Hosts call {@link DocumentVersionManager.saveVersion} (or the
- * underlying {@link saveVersion}) when they want to stamp a new version;
- * the editor's auto-save effect calls it on idle. Either way, snapshots
- * are written only when the document differs from the latest one.
- *
- * @example
- * ```ts
- * import { DocumentVersionManager } from '@bendyline/squisq/versions';
- *
- * const versioning = new DocumentVersionManager(container);
- * const result = await versioning.saveVersion();
- * if (result.saved) console.log('Stamped', result.version);
- *
- * const history = await versioning.listVersions();
- * await versioning.revertToVersion(history[0]);
- * await versioning.pruneVersions({ type: 'keep-last-n', n: 50 });
- * ```
- */
-export { saveVersion, listVersions, readVersion, revertToVersion, pruneVersions, coalesceVersions, } from './operations.js';
-export { DocumentVersionManager, } from './DocumentVersionManager.js';
-export { formatVersionTimestamp, parseVersionTimestamp, VERSION_TIMESTAMP_PATTERN, } from './timestamp.js';
-export { VERSIONS_PREFIX, getDocBasename, buildVersionPath, parseVersionPath } from './paths.js';
+import {
+  DocumentVersionManager,
+  VERSIONS_PREFIX,
+  buildVersionPath,
+  coalesceVersions,
+  getDocBasename,
+  listVersions,
+  parseVersionPath,
+  pruneVersions,
+  readVersion,
+  revertToVersion,
+  saveVersion
+} from "../chunk-VLJJHDAC.js";
+import {
+  VERSION_TIMESTAMP_PATTERN,
+  formatVersionTimestamp,
+  parseVersionTimestamp
+} from "../chunk-JELIRVDP.js";
+export {
+  DocumentVersionManager,
+  VERSIONS_PREFIX,
+  VERSION_TIMESTAMP_PATTERN,
+  buildVersionPath,
+  coalesceVersions,
+  formatVersionTimestamp,
+  getDocBasename,
+  listVersions,
+  parseVersionPath,
+  parseVersionTimestamp,
+  pruneVersions,
+  readVersion,
+  revertToVersion,
+  saveVersion
+};
 //# sourceMappingURL=index.js.map

package/dist/versions/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/versions/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAWH,OAAO,EACL,WAAW,EACX,YAAY,EACZ,WAAW,EACX,eAAe,EACf,aAAa,EACb,gBAAgB,GACjB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,sBAAsB,GAEvB,MAAM,6BAA6B,CAAC;AAErC,OAAO,EACL,sBAAsB,EACtB,qBAAqB,EACrB,yBAAyB,GAC1B,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bendyline/squisq",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Headless utilities for doc/block rendering, spatial math, Markdown, and storage",
   "license": "MIT",
   "author": "Bendyline",
@@ -106,6 +106,11 @@
       "import": "./dist/icons/index.js",
       "default": "./dist/icons/index.js"
     },
+    "./icon-marker": {
+      "types": "./dist/icons/inlineIconMarker.d.ts",
+      "import": "./dist/icons/inlineIconMarker.js",
+      "default": "./dist/icons/inlineIconMarker.js"
+    },
     "./recommend": {
       "types": "./dist/recommend/index.d.ts",
       "import": "./dist/recommend/index.js",

package/src/__tests__/animationUtils.test.ts

@@ -5,6 +5,7 @@ import {
   getTransitionClass,
   getAnimationProgress,
 } from '../doc/utils/animationUtils';
+import { TRANSITION_TYPES } from '../schemas/Transitions';
 
 describe('getAnimationStyle', () => {
   it('returns empty for undefined animation', () => {
@@ -57,6 +58,45 @@ describe('getTransitionClass', () => {
   it('returns exit class', () => {
     expect(getTransitionClass('dissolve', false)).toBe('transition-dissolve-exit');
   });
+
+  it('returns no class for cut', () => {
+    expect(getTransitionClass('cut', true)).toBe('');
+  });
+
+  it('maps PowerPoint-style transitions to supported visual classes', () => {
+    for (const type of TRANSITION_TYPES) {
+      if (type === 'cut') continue;
+      expect(getTransitionClass(type, true), type).toMatch(/^transition-.+-enter$/);
+      expect(getTransitionClass(type, false), type).toMatch(/^transition-.+-exit$/);
+    }
+  });
+
+  it('keeps the PowerPoint transition vocabulary visually expressive', () => {
+    const families = new Set(
+      TRANSITION_TYPES.flatMap((type) => {
+        const className = getTransitionClass(type, true);
+        const match = /^transition-(.+)-enter$/.exec(className);
+        return match ? [match[1]] : [];
+      }),
+    );
+
+    expect(families.size).toBeGreaterThanOrEqual(50);
+  });
+
+  it('maps aliases to stable visual families', () => {
+    expect(getTransitionClass('randomBars', true)).toBe('transition-randomBarsVertical-enter');
+    expect(getTransitionClass('flyThrough', true)).toBe('transition-flyThrough-enter');
+    expect(getTransitionClass('flythrough', true)).toBe('transition-flyThrough-enter');
+    expect(getTransitionClass('cube', true)).toBe('transition-cube-enter');
+    expect(getTransitionClass('ferris', true)).toBe('transition-ferrisWheel-enter');
+  });
+
+  it('honors transition directions for directional families', () => {
+    expect(getTransitionClass('wipe', true, 'right')).toBe('transition-wipeRight-enter');
+    expect(getTransitionClass('push', false, 'up')).toBe('transition-pushUp-exit');
+    expect(getTransitionClass('split', true, 'vertical')).toBe('transition-splitVertical-enter');
+    expect(getTransitionClass('blinds', false, 'vertical')).toBe('transition-blindsVertical-exit');
+  });
 });
 
 describe('getAnimationProgress', () => {