@bendyline/squisq 0.1.1

package/dist/types-DHiv_Pnm.d.ts

@@ -0,0 +1,496 @@
+/**
+ * Markdown DOM Types
+ *
+ * A complete hierarchical JSON representation of a Markdown document.
+ * Supports perfect-fidelity round-trip conversion between Markdown text
+ * and this JSON format: parseMarkdown(stringifyMarkdown(doc)) ≡ doc.
+ *
+ * Coverage:
+ * - CommonMark (headings, paragraphs, lists, code, blockquotes, etc.)
+ * - GFM (tables, strikethrough, task lists, autolinks, footnotes)
+ * - Math (inline $...$ and display $$...$$)
+ * - Directives (:::container, ::leaf, :text — used for admonitions, etc.)
+ * - Raw HTML (parsed into an HtmlNode sub-DOM for programmatic access)
+ * - Definition lists (type only — for programmatic construction)
+ */
+/**
+ * A specific point in the source markdown text.
+ */
+interface MarkdownPoint {
+    /** 1-based line number */
+    line: number;
+    /** 1-based column number */
+    column: number;
+    /** 0-based byte offset from start of document */
+    offset?: number;
+}
+/**
+ * Source position range for a node (start inclusive, end exclusive).
+ * Present when parsed from markdown, absent when constructed programmatically.
+ */
+interface MarkdownSourcePosition {
+    start: MarkdownPoint;
+    end: MarkdownPoint;
+}
+/**
+ * An HTML element with tag name, attributes, and children.
+ */
+interface HtmlElement {
+    type: 'htmlElement';
+    /** HTML tag name (lowercase, e.g., 'div', 'span', 'br') */
+    tagName: string;
+    /** HTML attributes as name→value pairs (uses HTML attribute names, e.g., 'class' not 'className') */
+    attributes: Record<string, string>;
+    /** Child nodes */
+    children: HtmlNode[];
+    /** Whether this is a void/self-closing element (br, hr, img, etc.) */
+    selfClosing: boolean;
+}
+/**
+ * A raw text node inside HTML.
+ */
+interface HtmlText {
+    type: 'htmlText';
+    value: string;
+}
+/**
+ * An HTML comment (<!-- ... -->).
+ */
+interface HtmlComment {
+    type: 'htmlComment';
+    value: string;
+}
+/** Any node in the HTML sub-DOM tree. */
+type HtmlNode = HtmlElement | HtmlText | HtmlComment;
+/**
+ * Root node of a parsed markdown document.
+ */
+interface MarkdownDocument {
+    type: 'document';
+    /** Top-level block content */
+    children: MarkdownBlockNode[];
+    /** Source position (present when parsed from markdown) */
+    position?: MarkdownSourcePosition;
+    /**
+     * YAML frontmatter key-value pairs extracted from the `---` block
+     * at the top of the document. Present only when the source contains
+     * frontmatter and `frontmatter` parsing is enabled (default: true).
+     */
+    frontmatter?: Record<string, unknown>;
+}
+/** Base properties shared by all markdown nodes. */
+interface MarkdownNodeBase {
+    /** Source position (present when parsed from markdown, absent when programmatically constructed) */
+    position?: MarkdownSourcePosition;
+}
+/**
+ * Template annotation extracted from a heading's trailing `{[templateName key=value …]}` syntax.
+ *
+ * @example
+ * ```markdown
+ * ### Report Data {[chart colorScheme=blue]}
+ * ```
+ * → `{ template: 'chart', params: { colorScheme: 'blue' } }`
+ */
+interface HeadingTemplateAnnotation {
+    /** Template name (first token inside `{[…]}`) */
+    template: string;
+    /** Optional key-value parameters (remaining `key=value` tokens) */
+    params?: Record<string, string>;
+}
+/**
+ * ATX or setext heading (# Heading).
+ */
+interface MarkdownHeading extends MarkdownNodeBase {
+    type: 'heading';
+    /** Heading level (1–6) */
+    depth: 1 | 2 | 3 | 4 | 5 | 6;
+    /** Inline content */
+    children: MarkdownInlineNode[];
+    /**
+     * Template annotation parsed from trailing `{[templateName …]}` syntax.
+     * Present only when the heading text ends with `{[…]}`. The annotation
+     * is stripped from `children` during parsing and re-injected during
+     * stringification, so it round-trips transparently.
+     */
+    templateAnnotation?: HeadingTemplateAnnotation;
+}
+/**
+ * A paragraph of inline content.
+ */
+interface MarkdownParagraph extends MarkdownNodeBase {
+    type: 'paragraph';
+    children: MarkdownInlineNode[];
+}
+/**
+ * A blockquote (> ...).
+ */
+interface MarkdownBlockquote extends MarkdownNodeBase {
+    type: 'blockquote';
+    children: MarkdownBlockNode[];
+}
+/**
+ * An ordered or unordered list.
+ */
+interface MarkdownList extends MarkdownNodeBase {
+    type: 'list';
+    /** Whether the list is ordered (numbered) or unordered (bulleted) */
+    ordered: boolean;
+    /** Starting number for ordered lists (default: 1) */
+    start?: number | null;
+    /** Whether items are separated by blank lines (loose list) */
+    spread?: boolean | null;
+    children: MarkdownListItem[];
+}
+/**
+ * A single item in a list. May be a task list item if `checked` is non-null.
+ */
+interface MarkdownListItem extends MarkdownNodeBase {
+    type: 'listItem';
+    /** null = not a task item, true = checked [x], false = unchecked [ ] */
+    checked?: boolean | null;
+    /** Whether this item contains blank lines (loose) */
+    spread?: boolean | null;
+    /** Block content (typically paragraphs, but can contain nested lists, etc.) */
+    children: MarkdownBlockNode[];
+}
+/**
+ * A fenced or indented code block.
+ */
+interface MarkdownCodeBlock extends MarkdownNodeBase {
+    type: 'code';
+    /** Language identifier (e.g., 'typescript', 'python') */
+    lang?: string | null;
+    /** Additional metadata after the language on the fence line */
+    meta?: string | null;
+    /** The code content (no trailing newline) */
+    value: string;
+}
+/**
+ * A thematic break (---, ***, or ___).
+ */
+interface MarkdownThematicBreak extends MarkdownNodeBase {
+    type: 'thematicBreak';
+}
+/**
+ * A GFM table.
+ */
+interface MarkdownTable extends MarkdownNodeBase {
+    type: 'table';
+    /** Column alignment: null = default, 'left', 'center', 'right' */
+    align?: (('left' | 'right' | 'center') | null)[];
+    /** First row is always the header row */
+    children: MarkdownTableRow[];
+}
+/**
+ * A row in a table.
+ */
+interface MarkdownTableRow extends MarkdownNodeBase {
+    type: 'tableRow';
+    children: MarkdownTableCell[];
+}
+/**
+ * A cell in a table row.
+ */
+interface MarkdownTableCell extends MarkdownNodeBase {
+    type: 'tableCell';
+    /** Whether this cell is in the header row */
+    isHeader?: boolean;
+    children: MarkdownInlineNode[];
+}
+/**
+ * A block of raw HTML.
+ *
+ * The `rawHtml` field contains the original HTML string and is used for
+ * serialization (round-tripping). The `htmlChildren` field contains a
+ * parsed HTML DOM tree for programmatic traversal.
+ *
+ * Note: For partial HTML tags (e.g., just `<div>` without `</div>`),
+ * `htmlChildren` may not fully represent the structure. The `rawHtml`
+ * field always preserves the exact original text.
+ */
+interface MarkdownHtmlBlock extends MarkdownNodeBase {
+    type: 'htmlBlock';
+    /** The original raw HTML string (source of truth for serialization) */
+    rawHtml: string;
+    /** Parsed HTML DOM tree (for programmatic access) */
+    htmlChildren: HtmlNode[];
+}
+/**
+ * A display math block ($$...$$).
+ */
+interface MarkdownMathBlock extends MarkdownNodeBase {
+    type: 'math';
+    /** The math content (without $$ delimiters) */
+    value: string;
+    /** Optional metadata after the opening $$ */
+    meta?: string | null;
+}
+/**
+ * A link reference definition: [id]: url "title"
+ * These are typically not rendered but define targets for reference links.
+ */
+interface MarkdownLinkDefinition extends MarkdownNodeBase {
+    type: 'definition';
+    /** Reference identifier (lowercase, normalized) */
+    identifier: string;
+    /** Original label text */
+    label?: string;
+    /** URL target */
+    url: string;
+    /** Optional title */
+    title?: string | null;
+}
+/**
+ * A footnote definition: [^id]: content
+ */
+interface MarkdownFootnoteDefinition extends MarkdownNodeBase {
+    type: 'footnoteDefinition';
+    /** Footnote identifier */
+    identifier: string;
+    /** Original label text */
+    label?: string;
+    /** Footnote content (block-level) */
+    children: MarkdownBlockNode[];
+}
+/**
+ * A container directive (:::name[label]{attrs}\ncontent\n:::).
+ * Used for admonitions, callouts, and other structural extensions.
+ */
+interface MarkdownContainerDirective extends MarkdownNodeBase {
+    type: 'containerDirective';
+    /** Directive name (e.g., 'note', 'warning', 'tip') */
+    name: string;
+    /** Key-value attributes from {attr=value} */
+    attributes?: Record<string, string>;
+    /** Label text from [label] (extracted from children for clean round-tripping) */
+    label?: string;
+    /** Block content inside the directive */
+    children: MarkdownBlockNode[];
+}
+/**
+ * A leaf directive (::name[label]{attrs}).
+ * Self-contained block-level directive with no content body.
+ */
+interface MarkdownLeafDirective extends MarkdownNodeBase {
+    type: 'leafDirective';
+    /** Directive name */
+    name: string;
+    /** Key-value attributes */
+    attributes?: Record<string, string>;
+    /** Inline content from [label] */
+    children: MarkdownInlineNode[];
+}
+/**
+ * A definition list (<dl>).
+ * This type is for programmatic construction — no standard remark parser
+ * produces these nodes, but they can be built and rendered.
+ */
+interface MarkdownDefinitionList extends MarkdownNodeBase {
+    type: 'definitionList';
+    children: (MarkdownDefinitionTerm | MarkdownDefinitionDescription)[];
+}
+/**
+ * A term in a definition list (<dt>).
+ */
+interface MarkdownDefinitionTerm extends MarkdownNodeBase {
+    type: 'definitionTerm';
+    children: MarkdownInlineNode[];
+}
+/**
+ * A description in a definition list (<dd>).
+ */
+interface MarkdownDefinitionDescription extends MarkdownNodeBase {
+    type: 'definitionDescription';
+    children: MarkdownBlockNode[];
+}
+/**
+ * Plain text content.
+ */
+interface MarkdownText extends MarkdownNodeBase {
+    type: 'text';
+    value: string;
+}
+/**
+ * Emphasized text (*text* or _text_).
+ */
+interface MarkdownEmphasis extends MarkdownNodeBase {
+    type: 'emphasis';
+    children: MarkdownInlineNode[];
+}
+/**
+ * Strong emphasis (**text** or __text__).
+ */
+interface MarkdownStrong extends MarkdownNodeBase {
+    type: 'strong';
+    children: MarkdownInlineNode[];
+}
+/**
+ * Strikethrough text (~~text~~). GFM extension.
+ */
+interface MarkdownStrikethrough extends MarkdownNodeBase {
+    type: 'delete';
+    children: MarkdownInlineNode[];
+}
+/**
+ * Inline code (`code`).
+ */
+interface MarkdownInlineCode extends MarkdownNodeBase {
+    type: 'inlineCode';
+    value: string;
+}
+/**
+ * A hyperlink [text](url "title").
+ */
+interface MarkdownLink extends MarkdownNodeBase {
+    type: 'link';
+    /** URL target */
+    url: string;
+    /** Optional title (shown on hover) */
+    title?: string | null;
+    /** Link text (inline content) */
+    children: MarkdownInlineNode[];
+}
+/**
+ * An image ![alt](url "title").
+ */
+interface MarkdownImage extends MarkdownNodeBase {
+    type: 'image';
+    /** Image URL */
+    url: string;
+    /** Alt text */
+    alt?: string;
+    /** Optional title */
+    title?: string | null;
+}
+/**
+ * A hard line break (two trailing spaces or backslash before newline).
+ */
+interface MarkdownBreak extends MarkdownNodeBase {
+    type: 'break';
+}
+/**
+ * Inline raw HTML.
+ *
+ * In markdown, individual HTML tags like `<em>` or `</em>` appear as
+ * separate inline nodes. The `rawHtml` preserves the exact tag text.
+ * The `htmlChildren` is a best-effort parse (partial tags may not
+ * produce meaningful trees).
+ */
+interface MarkdownInlineHtml extends MarkdownNodeBase {
+    type: 'htmlInline';
+    /** The original raw HTML string */
+    rawHtml: string;
+    /** Parsed HTML DOM tree (best-effort for partial tags) */
+    htmlChildren: HtmlNode[];
+}
+/**
+ * Inline math ($...$).
+ */
+interface MarkdownInlineMath extends MarkdownNodeBase {
+    type: 'inlineMath';
+    /** Math content (without $ delimiters) */
+    value: string;
+}
+/**
+ * A footnote reference [^id]. GFM extension.
+ */
+interface MarkdownFootnoteReference extends MarkdownNodeBase {
+    type: 'footnoteReference';
+    /** Footnote identifier */
+    identifier: string;
+    /** Original label text */
+    label?: string;
+}
+/**
+ * A link via reference [text][id] or [text][] or [text].
+ */
+interface MarkdownLinkReference extends MarkdownNodeBase {
+    type: 'linkReference';
+    /** Reference identifier (normalized) */
+    identifier: string;
+    /** Original label text */
+    label?: string;
+    /** How the reference is written */
+    referenceType: 'full' | 'collapsed' | 'shortcut';
+    /** Link text (inline content) */
+    children: MarkdownInlineNode[];
+}
+/**
+ * An image via reference ![alt][id].
+ */
+interface MarkdownImageReference extends MarkdownNodeBase {
+    type: 'imageReference';
+    /** Reference identifier (normalized) */
+    identifier: string;
+    /** Original label text */
+    label?: string;
+    /** How the reference is written */
+    referenceType: 'full' | 'collapsed' | 'shortcut';
+    /** Alt text */
+    alt?: string;
+}
+/**
+ * An inline text directive (:name[label]{attrs}).
+ */
+interface MarkdownTextDirective extends MarkdownNodeBase {
+    type: 'textDirective';
+    /** Directive name */
+    name: string;
+    /** Key-value attributes */
+    attributes?: Record<string, string>;
+    /** Inline content from [label] */
+    children: MarkdownInlineNode[];
+}
+/** Block-level content that can appear as direct children of the document root, blockquotes, list items, etc. */
+type MarkdownBlockNode = MarkdownHeading | MarkdownParagraph | MarkdownBlockquote | MarkdownList | MarkdownCodeBlock | MarkdownThematicBreak | MarkdownTable | MarkdownHtmlBlock | MarkdownMathBlock | MarkdownLinkDefinition | MarkdownFootnoteDefinition | MarkdownContainerDirective | MarkdownLeafDirective | MarkdownDefinitionList;
+/** Inline/phrasing content that appears inside paragraphs, headings, links, etc. */
+type MarkdownInlineNode = MarkdownText | MarkdownEmphasis | MarkdownStrong | MarkdownStrikethrough | MarkdownInlineCode | MarkdownLink | MarkdownImage | MarkdownBreak | MarkdownInlineHtml | MarkdownInlineMath | MarkdownFootnoteReference | MarkdownLinkReference | MarkdownImageReference | MarkdownTextDirective;
+/**
+ * Any node in the markdown tree. Includes structural nodes (listItem,
+ * tableRow, tableCell, etc.) that only appear as children of specific parents.
+ * Useful for generic tree-walking functions.
+ */
+type MarkdownNode = MarkdownDocument | MarkdownBlockNode | MarkdownInlineNode | MarkdownListItem | MarkdownTableRow | MarkdownTableCell | MarkdownDefinitionTerm | MarkdownDefinitionDescription;
+/**
+ * Options for parseMarkdown().
+ */
+interface ParseOptions {
+    /** Enable GFM extensions (tables, strikethrough, task lists, autolinks, footnotes). Default: true */
+    gfm?: boolean;
+    /** Enable math extensions ($...$ and $$...$$). Default: true */
+    math?: boolean;
+    /** Enable directive extensions (:::container, ::leaf, :text). Default: true */
+    directive?: boolean;
+    /** Parse raw HTML into HtmlNode sub-DOM trees. Default: true */
+    parseHtml?: boolean;
+    /** Enable YAML frontmatter parsing (--- blocks at top of document). Default: true */
+    frontmatter?: boolean;
+}
+/**
+ * Options for stringifyMarkdown().
+ */
+interface StringifyOptions {
+    /** Enable GFM extensions in output. Default: true */
+    gfm?: boolean;
+    /** Enable math extensions in output. Default: true */
+    math?: boolean;
+    /** Enable directive extensions in output. Default: true */
+    directive?: boolean;
+    /** Bullet character for unordered lists. Default: '-' */
+    bullet?: '-' | '*' | '+';
+    /** Ordered list delimiter. Default: '.' */
+    bulletOrdered?: '.' | ')';
+    /** Emphasis marker character. Default: '*' */
+    emphasis?: '*' | '_';
+    /** Strong emphasis marker character. Default: '*' */
+    strong?: '*' | '_';
+    /** Thematic break character. Default: '-' */
+    rule?: '-' | '*' | '_';
+    /** Code fence character. Default: '`' */
+    fence?: '`' | '~';
+    /** Use setext-style headings (underlined) for depth 1-2. Default: false */
+    setext?: boolean;
+}
+
+export type { MarkdownLinkReference as A, MarkdownList as B, MarkdownListItem as C, MarkdownMathBlock as D, MarkdownNode as E, MarkdownParagraph as F, MarkdownPoint as G, HeadingTemplateAnnotation as H, MarkdownSourcePosition as I, MarkdownStrikethrough as J, MarkdownStrong as K, MarkdownTable as L, MarkdownBlockNode as M, MarkdownTableCell as N, MarkdownTableRow as O, MarkdownText as P, MarkdownTextDirective as Q, MarkdownThematicBreak as R, ParseOptions as S, StringifyOptions as T, 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 };

package/package.json

@@ -0,0 +1,91 @@
+{
+  "name": "@bendyline/squisq",
+  "version": "0.1.1",
+  "description": "Headless utilities for doc/block rendering, spatial math, Markdown, and storage",
+  "license": "MIT",
+  "author": "Bendyline",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nicknisi/squisq.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/nicknisi/squisq",
+  "keywords": [
+    "doc",
+    "block",
+    "template",
+    "spatial",
+    "geohash",
+    "markdown",
+    "storage"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./schemas": {
+      "types": "./dist/schemas/index.d.ts",
+      "import": "./dist/schemas/index.js",
+      "default": "./dist/schemas/index.js"
+    },
+    "./spatial": {
+      "types": "./dist/spatial/index.d.ts",
+      "import": "./dist/spatial/index.js",
+      "default": "./dist/spatial/index.js"
+    },
+    "./story": {
+      "types": "./dist/story/index.d.ts",
+      "import": "./dist/story/index.js",
+      "default": "./dist/story/index.js"
+    },
+    "./doc": {
+      "types": "./dist/doc/index.d.ts",
+      "import": "./dist/doc/index.js",
+      "default": "./dist/doc/index.js"
+    },
+    "./storage": {
+      "types": "./dist/storage/index.d.ts",
+      "import": "./dist/storage/index.js",
+      "default": "./dist/storage/index.js"
+    },
+    "./markdown": {
+      "types": "./dist/markdown/index.d.ts",
+      "import": "./dist/markdown/index.js",
+      "default": "./dist/markdown/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "hast-util-from-html": "^2.0.0",
+    "localforage": "^1.10.0",
+    "ngeohash": "^0.6.3",
+    "remark-directive": "^3.0.0",
+    "remark-frontmatter": "^5.0.0",
+    "remark-gfm": "^4.0.0",
+    "remark-math": "^6.0.0",
+    "remark-parse": "^11.0.0",
+    "remark-stringify": "^11.0.0",
+    "unified": "^11.0.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0"
+  }
+}

package/src/__tests__/animationUtils.test.ts

@@ -0,0 +1,77 @@
+import { describe, it, expect } from 'vitest';
+import {
+  getAnimationStyle,
+  getDefaultAnimationDuration,
+  getTransitionClass,
+  getAnimationProgress,
+} from '../doc/utils/animationUtils';
+
+describe('getAnimationStyle', () => {
+  it('returns empty for undefined animation', () => {
+    const result = getAnimationStyle(undefined);
+    expect(result.className).toBe('');
+    expect(result.style).toEqual({});
+  });
+
+  it('returns empty for type "none"', () => {
+    const result = getAnimationStyle({ type: 'none' });
+    expect(result.className).toBe('');
+  });
+
+  it('returns correct class for fadeIn', () => {
+    const result = getAnimationStyle({ type: 'fadeIn' });
+    expect(result.className).toBe('anim-fadeIn');
+  });
+
+  it('returns correct class for slowZoom with pan', () => {
+    const result = getAnimationStyle({ type: 'slowZoom', panDirection: 'left' });
+    expect(result.className).toBe('anim-slowZoom-panLeft');
+  });
+
+  it('includes CSS custom properties for duration and delay', () => {
+    const result = getAnimationStyle({ type: 'fadeIn', duration: 2, delay: 0.5 });
+    expect(result.style['--anim-duration']).toBe('2s');
+    expect(result.style['--anim-delay']).toBe('0.5s');
+  });
+});
+
+describe('getDefaultAnimationDuration', () => {
+  it('returns 8 for slowZoom', () => {
+    expect(getDefaultAnimationDuration('slowZoom')).toBe(8);
+  });
+
+  it('returns 1 for fadeIn', () => {
+    expect(getDefaultAnimationDuration('fadeIn')).toBe(1);
+  });
+
+  it('returns 0.5 for zoomIn', () => {
+    expect(getDefaultAnimationDuration('zoomIn')).toBe(0.5);
+  });
+});
+
+describe('getTransitionClass', () => {
+  it('returns enter class', () => {
+    expect(getTransitionClass('fade', true)).toBe('transition-fade-enter');
+  });
+
+  it('returns exit class', () => {
+    expect(getTransitionClass('dissolve', false)).toBe('transition-dissolve-exit');
+  });
+});
+
+describe('getAnimationProgress', () => {
+  it('returns 0 before delay', () => {
+    const progress = getAnimationProgress({ type: 'fadeIn', delay: 1, duration: 2 }, 0.5, 5);
+    expect(progress).toBe(0);
+  });
+
+  it('returns 1 after completion', () => {
+    const progress = getAnimationProgress({ type: 'fadeIn', delay: 0, duration: 2 }, 3, 5);
+    expect(progress).toBe(1);
+  });
+
+  it('returns 0.5 at midpoint', () => {
+    const progress = getAnimationProgress({ type: 'fadeIn', delay: 0, duration: 2 }, 1, 5);
+    expect(progress).toBeCloseTo(0.5);
+  });
+});