@bendyline/squisq 1.4.0 → 1.5.0

package/src/imageEdit/persistence.ts

@@ -59,4 +59,55 @@ function assertImageEditDoc(value: unknown, filename: string): asserts value is
   if (!Array.isArray(v.layers)) {
     throw new Error(`readImageEditDoc: ${filename} layers must be an array`);
   }
+  v.layers.forEach((layer, i) => assertLayer(layer, i, filename));
+}
+
+const VALID_LAYER_TYPES = new Set(['image', 'text', 'shape', 'path']);
+
+function assertLayer(value: unknown, index: number, filename: string): void {
+  const ctx = `${filename} layers[${index}]`;
+  if (!value || typeof value !== 'object') {
+    throw new Error(`readImageEditDoc: ${ctx} must be an object`);
+  }
+  const layer = value as Record<string, unknown>;
+
+  if (typeof layer['id'] !== 'string') {
+    throw new Error(`readImageEditDoc: ${ctx} must have a string id`);
+  }
+  if (typeof layer['type'] !== 'string' || !VALID_LAYER_TYPES.has(layer['type'])) {
+    throw new Error(
+      `readImageEditDoc: ${ctx} type must be one of image|text|shape, got ${String(layer['type'])}`,
+    );
+  }
+
+  const pos = layer['position'];
+  if (
+    !pos ||
+    typeof pos !== 'object' ||
+    (typeof (pos as Record<string, unknown>)['x'] !== 'number' &&
+      typeof (pos as Record<string, unknown>)['x'] !== 'string') ||
+    (typeof (pos as Record<string, unknown>)['y'] !== 'number' &&
+      typeof (pos as Record<string, unknown>)['y'] !== 'string')
+  ) {
+    throw new Error(`readImageEditDoc: ${ctx} position must have numeric or string x and y`);
+  }
+
+  const content = layer['content'];
+  if (!content || typeof content !== 'object') {
+    throw new Error(`readImageEditDoc: ${ctx} content must be an object`);
+  }
+  const c = content as Record<string, unknown>;
+
+  if (layer['type'] === 'image' && typeof c['src'] !== 'string') {
+    throw new Error(`readImageEditDoc: ${ctx} (image) content.src must be a string`);
+  }
+  if (layer['type'] === 'text' && typeof c['text'] !== 'string') {
+    throw new Error(`readImageEditDoc: ${ctx} (text) content.text must be a string`);
+  }
+  if (layer['type'] === 'shape' && typeof c['shape'] !== 'string') {
+    throw new Error(`readImageEditDoc: ${ctx} (shape) content.shape must be a string`);
+  }
+  if (layer['type'] === 'path' && typeof c['d'] !== 'string') {
+    throw new Error(`readImageEditDoc: ${ctx} (path) content.d must be a string`);
+  }
 }

package/src/index.ts

@@ -6,7 +6,9 @@ export * from './markdown/index.js';
 export * from './timing/index.js';
 export * from './random/index.js';
 export * from './generate/index.js';
+export * from './transform/index.js';
 export * from './versions/index.js';
 export * from './jsonForm/index.js';
 export * from './imageEdit/index.js';
+export * from './icons/index.js';
 export * from './recommend/index.js';

package/src/markdown/annotationCoercion.ts

@@ -0,0 +1,295 @@
+/**
+ * Heading-attribute value coercion.
+ *
+ * The Pandoc-style heading attribute block `{#id .class key=value}` parses
+ * to a flat `Record<string, string>` of `key → raw value`. This module
+ * coerces a known subset of keys to typed values (numbers, time-in-seconds,
+ * `BlockConnection[]`) so downstream consumers don't have to re-parse them.
+ *
+ * Unknown keys are returned in `metadata` as raw strings. Malformed known-key
+ * values are dropped from the typed result and reported via `warnings` (the
+ * raw string is preserved in `params` upstream for lossless round-tripping —
+ * coercion failures do not corrupt the source).
+ */
+
+import type { BlockConnection } from './types.js';
+import type { TransitionDirection, TransitionType } from '../schemas/Transitions.js';
+import {
+  normalizeTransitionDirection,
+  normalizeTransitionType,
+  TRANSITION_TYPES,
+  TRANSITION_DIRECTIONS,
+} from '../schemas/Transitions.js';
+
+/**
+ * Registry of known block-meta keys and their coercion strategies.
+ *
+ * Adding a new typed key: add an entry here, add the typed field to
+ * `HeadingAttributes.blockMeta` in `types.ts`, and apply the coerced value
+ * in `markdownToDoc.ts`.
+ */
+export const KNOWN_BLOCK_META_KEYS = {
+  x: 'number',
+  y: 'number',
+  startTime: 'time',
+  duration: 'time',
+  connectsTo: 'connectionList',
+  transition: 'transition',
+  transitionDuration: 'time',
+  transitionDirection: 'transitionDirection',
+} as const;
+
+export type KnownBlockMetaKey = keyof typeof KNOWN_BLOCK_META_KEYS;
+
+/**
+ * Editor-facing description of a known block-meta key: what it does, and
+ * either its closed set of valid values or a free-form format hint. This is
+ * the single source the markdown editor's `{[name key=value]}` attribute
+ * autocomplete reads from, so the suggestion list stays in lockstep with
+ * `KNOWN_BLOCK_META_KEYS` and the transition vocabulary rather than drifting
+ * in a hand-maintained copy. `values`/`valueHint` are mutually exclusive: a
+ * key has a closed enum (`values`) or a format hint (`valueHint`), not both.
+ */
+export interface BlockMetaKeyDescriptor {
+  key: KnownBlockMetaKey;
+  /** One-line description, shown as the completion item's detail. */
+  description: string;
+  /** Closed set of valid values, for keys backed by an enum. */
+  values?: readonly string[];
+  /** Format hint shown when the value is free-form (no closed set). */
+  valueHint?: string;
+}
+
+/**
+ * Ordered descriptors for every key in `KNOWN_BLOCK_META_KEYS`. Order is the
+ * suggestion display order: the transition family first (the most common
+ * authoring case), then timeline timing, then diagram geometry/links.
+ */
+export const BLOCK_META_KEY_DESCRIPTORS: readonly BlockMetaKeyDescriptor[] = [
+  {
+    key: 'transition',
+    description: 'Block-to-block transition effect',
+    values: TRANSITION_TYPES,
+  },
+  {
+    key: 'transitionDuration',
+    description: 'How long the transition lasts',
+    valueHint: 'seconds — e.g. 0.7, 700ms',
+  },
+  {
+    key: 'transitionDirection',
+    description: 'Directional variant for the transition',
+    values: TRANSITION_DIRECTIONS,
+  },
+  {
+    key: 'startTime',
+    description: 'Timeline start time of this block',
+    valueHint: 'mm:ss or seconds — e.g. 01:30, 5, 1500ms',
+  },
+  {
+    key: 'duration',
+    description: 'How long this block lasts',
+    valueHint: 'mm:ss or seconds — e.g. 45, 1500ms',
+  },
+  {
+    key: 'x',
+    description: 'Horizontal position on the diagram canvas',
+    valueHint: 'number — e.g. 600',
+  },
+  {
+    key: 'y',
+    description: 'Vertical position on the diagram canvas',
+    valueHint: 'number — e.g. 300',
+  },
+  {
+    key: 'connectsTo',
+    description: 'Diagram connections to other blocks',
+    valueHint: 'comma-separated target or target:type — e.g. foo,bar:flow',
+  },
+];
+
+/**
+ * The shape of the typed values produced by coercion. Mirrors
+ * `HeadingAttributes.blockMeta` in `types.ts`.
+ */
+export interface CoercedBlockMeta {
+  x?: number;
+  y?: number;
+  startTime?: number;
+  duration?: number;
+  connectsTo?: BlockConnection[];
+  transition?: {
+    type: TransitionType;
+    duration?: number;
+    direction?: TransitionDirection;
+  };
+}
+
+export interface CoerceResult {
+  /** Typed values for known keys whose coercion succeeded. */
+  blockMeta: CoercedBlockMeta;
+  /** Raw string values for keys not in the known-key registry. */
+  metadata: Record<string, string>;
+  /** Human-readable diagnostics — currently emitted for coercion failures. */
+  warnings: string[];
+}
+
+/**
+ * Coerce a flat `key → raw string` map into typed block-meta + an
+ * untyped metadata bag, per the `KNOWN_BLOCK_META_KEYS` registry.
+ */
+export function coerceAnnotationValues(params: Record<string, string>): CoerceResult {
+  const blockMeta: CoercedBlockMeta = {};
+  const metadata: Record<string, string> = {};
+  const warnings: string[] = [];
+  let transitionType: TransitionType | null = null;
+  let transitionDuration: number | undefined;
+  let transitionDirection: TransitionDirection | undefined;
+
+  for (const [key, raw] of Object.entries(params)) {
+    const kind = (KNOWN_BLOCK_META_KEYS as Record<string, string>)[key];
+    if (!kind) {
+      metadata[key] = raw;
+      continue;
+    }
+    if (kind === 'number') {
+      const n = parseNumber(raw);
+      if (n == null) {
+        warnings.push(`Invalid number for "${key}": ${JSON.stringify(raw)}`);
+      } else {
+        (blockMeta as Record<string, unknown>)[key] = n;
+      }
+    } else if (kind === 'time') {
+      const s = parseTimeSeconds(raw);
+      if (s == null) {
+        warnings.push(`Invalid time for "${key}": ${JSON.stringify(raw)}`);
+      } else if (key === 'transitionDuration') {
+        transitionDuration = s;
+      } else {
+        (blockMeta as Record<string, unknown>)[key] = s;
+      }
+    } else if (kind === 'connectionList') {
+      const { list, warning } = parseConnectionList(raw);
+      if (warning) warnings.push(`"${key}": ${warning}`);
+      blockMeta.connectsTo = list;
+    } else if (kind === 'transition') {
+      const transition = normalizeTransitionType(raw);
+      if (transition == null) {
+        warnings.push(`Invalid transition for "${key}": ${JSON.stringify(raw)}`);
+      } else {
+        transitionType = transition;
+      }
+    } else if (kind === 'transitionDirection') {
+      const direction = normalizeTransitionDirection(raw);
+      if (direction == null) {
+        warnings.push(`Invalid transition direction for "${key}": ${JSON.stringify(raw)}`);
+      } else {
+        transitionDirection = direction;
+      }
+    }
+  }
+
+  if (transitionType) {
+    blockMeta.transition = {
+      type: transitionType,
+      ...(transitionDuration !== undefined ? { duration: transitionDuration } : {}),
+      ...(transitionDirection !== undefined ? { direction: transitionDirection } : {}),
+    };
+  }
+
+  return { blockMeta, metadata, warnings };
+}
+
+// ============================================
+// Coercers
+// ============================================
+
+/** Parse a finite number from a string. Returns null on failure. */
+function parseNumber(raw: string): number | null {
+  if (raw.trim() === '') return null;
+  const n = Number(raw);
+  return Number.isFinite(n) ? n : null;
+}
+
+const TIME_BARE_RE = /^\d+(?:\.\d+)?$/;
+const TIME_MS_RE = /^(\d+(?:\.\d+)?)ms$/;
+const TIME_MMSS_RE = /^(\d+):(\d{1,2})(?:\.(\d+))?$/;
+
+/**
+ * Parse a time value to seconds. Accepts:
+ * - bare number: `5` → 5, `5.5` → 5.5
+ * - `mm:ss`: `01:30` → 90
+ * - `mm:ss.ms`: `01:30.500` → 90.5
+ * - `1500ms` → 1.5
+ *
+ * Returns null on malformed input.
+ */
+export function parseTimeSeconds(raw: string): number | null {
+  const trimmed = raw.trim();
+  if (!trimmed) return null;
+
+  if (TIME_BARE_RE.test(trimmed)) {
+    const n = Number(trimmed);
+    return Number.isFinite(n) ? n : null;
+  }
+
+  const msMatch = trimmed.match(TIME_MS_RE);
+  if (msMatch) {
+    const n = Number(msMatch[1]);
+    return Number.isFinite(n) ? n / 1000 : null;
+  }
+
+  const mmssMatch = trimmed.match(TIME_MMSS_RE);
+  if (mmssMatch) {
+    const mins = Number(mmssMatch[1]);
+    const secs = Number(mmssMatch[2]);
+    const frac = mmssMatch[3] ? Number(`0.${mmssMatch[3]}`) : 0;
+    if (!Number.isFinite(mins) || !Number.isFinite(secs) || !Number.isFinite(frac)) {
+      return null;
+    }
+    if (secs >= 60) return null;
+    return mins * 60 + secs + frac;
+  }
+
+  return null;
+}
+
+/**
+ * Parse a comma-separated connection list. Each entry is `target` or
+ * `target:type`. Empty entries (`a,,b`) are filtered with a warning; an
+ * entirely empty input yields an empty list with no warning.
+ */
+export function parseConnectionList(raw: string): {
+  list: BlockConnection[];
+  warning: string | null;
+} {
+  const trimmed = raw.trim();
+  if (!trimmed) return { list: [], warning: null };
+
+  const list: BlockConnection[] = [];
+  let droppedEmpty = false;
+  for (const part of trimmed.split(',')) {
+    const entry = part.trim();
+    if (!entry) {
+      droppedEmpty = true;
+      continue;
+    }
+    const colonIdx = entry.indexOf(':');
+    if (colonIdx < 0) {
+      list.push({ target: entry });
+    } else {
+      const target = entry.slice(0, colonIdx).trim();
+      const type = entry.slice(colonIdx + 1).trim();
+      if (!target) {
+        droppedEmpty = true;
+        continue;
+      }
+      list.push(type ? { target, type } : { target });
+    }
+  }
+
+  return {
+    list,
+    warning: droppedEmpty ? 'dropped empty connection entries' : null,
+  };
+}

package/src/markdown/attrTokens.ts

@@ -0,0 +1,222 @@
+/**
+ * Shared key=value attribute machinery for the two heading annotation forms:
+ * the squisq-native `{[templateName key=value …]}` template annotation and
+ * the Pandoc-style `{#id .class key=value}` attribute block.
+ *
+ * Both forms share one interior grammar — whitespace-separated tokens whose
+ * values may be quoted (double or single) to include spaces, brackets, or
+ * quote characters. This module is the single implementation of that
+ * grammar: one tokenizer, one value un/escaper, one quoting rule. The
+ * trailing-annotation recognizers live here too so the editor bridge
+ * (packages/editor-react/src/tiptapBridge.ts) stays in sync by importing
+ * them rather than copying regexes.
+ *
+ * Value syntax:
+ * - Unquoted: no whitespace, quotes, or `[ ] { }` (those would collide with
+ *   the surrounding annotation delimiters), e.g. `columns=3`, `name=O'Brien`
+ *   (a quote *inside* an unquoted value is literal).
+ * - Quoted: `key="value with spaces"` or `key='…'`. Inside a quoted run,
+ *   `\` escapes the active quote character and itself; any other `\` is
+ *   literal. Quoted values may contain `]` and `}`.
+ * - Serialization emits double quotes, switching to single quotes when the
+ *   value contains a double quote (markdown character-escape resolution
+ *   makes backslash-escaped quotes fragile in `.md` source, so picking the
+ *   other quote character is preferred over escaping). A value containing
+ *   BOTH quote characters falls back to double quotes with `\"` escapes —
+ *   that survives the API path but is best avoided in markdown source.
+ */
+
+// ============================================
+// Trailing-annotation recognizers
+// ============================================
+
+/** Regex source for a double-quoted run with `\"` / `\\` escapes. */
+const DQ_RUN = `"(?:[^"\\\\]|\\\\.)*"`;
+/** Regex source for a single-quoted run with `\'` / `\\` escapes. */
+const SQ_RUN = `'(?:[^'\\\\]|\\\\.)*'`;
+
+/**
+ * Quote-aware match for a trailing `{[…]}` annotation: the interior is any
+ * mix of quoted runs and characters other than `]` and quotes, so quoted
+ * values may contain `]`. The trailing `[\s\]}]*` tolerates an accidental
+ * doubled `]}` that users sometimes type when learning the syntax.
+ */
+const TEMPLATE_STRICT_RE = new RegExp(
+  `\\s*\\{\\[((?:[^\\]"']|${DQ_RUN}|${SQ_RUN})+)\\]\\}[\\s\\]}]*$`,
+);
+
+/**
+ * Legacy fallback matching the pre-quote-aware grammar (`[^\]]+` interior).
+ * Tried after the strict form so inputs with unbalanced quotes keep parsing
+ * exactly as they did before quote support landed.
+ */
+const TEMPLATE_LEGACY_RE = /\s*\{\[([^\]]+)\]\}[\s\]}]*$/;
+
+/**
+ * Quote-aware match for a trailing Pandoc `{…}` block. The negative
+ * lookahead `(?!\[)` keeps it from colliding with the `{[…]}` template
+ * form. Quoted values may contain `}`.
+ */
+const PANDOC_STRICT_RE = new RegExp(`\\s*\\{(?!\\[)((?:[^}"']|${DQ_RUN}|${SQ_RUN})*)\\}\\s*$`);
+
+/** Legacy fallback for the Pandoc block (`[^}]*` interior). */
+const PANDOC_LEGACY_RE = /\s*\{(?!\[)([^}]*)\}\s*$/;
+
+/** Result of matching a trailing annotation against a text run. */
+export interface TrailingAnnotationMatch {
+  /** Interior of the brace block (between `{[`/`{` and `]}`/`}`), untrimmed. */
+  inner: string;
+  /** Offset of the match start (including leading whitespace) in the input. */
+  index: number;
+}
+
+function matchTrailing(
+  text: string,
+  strict: RegExp,
+  legacy: RegExp,
+): TrailingAnnotationMatch | null {
+  const m = strict.exec(text) ?? legacy.exec(text);
+  return m ? { inner: m[1], index: m.index } : null;
+}
+
+/**
+ * Match a trailing `{[templateName key=value …]}` annotation. Quote-aware
+ * (values may contain `]` when quoted), with a legacy fallback so inputs
+ * the old `[^\]]+` grammar accepted still match.
+ */
+export function matchTrailingTemplateAnnotation(text: string): TrailingAnnotationMatch | null {
+  return matchTrailing(text, TEMPLATE_STRICT_RE, TEMPLATE_LEGACY_RE);
+}
+
+/**
+ * Match a trailing Pandoc `{#id .class key=value}` block. Quote-aware
+ * (values may contain `}` when quoted), with a legacy fallback.
+ */
+export function matchTrailingPandocAttr(text: string): TrailingAnnotationMatch | null {
+  return matchTrailing(text, PANDOC_STRICT_RE, PANDOC_LEGACY_RE);
+}
+
+// ============================================
+// Tokenizer
+// ============================================
+
+const WHITESPACE_RE = /\s/;
+
+/**
+ * Quote-aware whitespace tokenizer for the interior of either annotation
+ * form.
+ *
+ * A quote run starts only at the beginning of a token or immediately after
+ * `=` — a quote elsewhere (e.g. `name=O'Brien`) is a literal character.
+ * Inside a run, `\` escapes the active quote character and itself; the
+ * escape pair is preserved in the returned token (callers strip and
+ * unescape via {@link splitKeyValueToken} / {@link unquoteAttrValue}).
+ * An unbalanced opening quote is tolerated: the run extends to the end of
+ * the input.
+ */
+export function tokenizeAttrTokens(input: string): string[] {
+  const tokens: string[] = [];
+  let i = 0;
+  const n = input.length;
+  while (i < n) {
+    while (i < n && WHITESPACE_RE.test(input[i])) i++;
+    if (i >= n) break;
+
+    let token = '';
+    while (i < n && !WHITESPACE_RE.test(input[i])) {
+      const ch = input[i];
+      const atValueStart = token === '' || token.endsWith('=');
+      if ((ch === '"' || ch === "'") && atValueStart) {
+        token += ch;
+        i++;
+        while (i < n && input[i] !== ch) {
+          if (input[i] === '\\' && i + 1 < n && (input[i + 1] === ch || input[i + 1] === '\\')) {
+            token += input[i] + input[i + 1];
+            i += 2;
+          } else {
+            token += input[i];
+            i++;
+          }
+        }
+        if (i < n && input[i] === ch) {
+          token += ch;
+          i++;
+        }
+      } else {
+        token += ch;
+        i++;
+      }
+    }
+    if (token) tokens.push(token);
+  }
+  return tokens;
+}
+
+// ============================================
+// Value un/escaping
+// ============================================
+
+const DQ_UNESCAPE_RE = /\\([\\"])/g;
+const SQ_UNESCAPE_RE = /\\([\\'])/g;
+
+/**
+ * Strip surrounding quotes from a raw token value and unescape the active
+ * quote character and backslash. Values not wrapped in matching quotes are
+ * returned verbatim (including any interior quotes or backslashes).
+ */
+export function unquoteAttrValue(raw: string): string {
+  if (raw.length >= 2) {
+    const q = raw[0];
+    if ((q === '"' || q === "'") && raw.endsWith(q)) {
+      const body = raw.slice(1, -1);
+      return body.replace(q === '"' ? DQ_UNESCAPE_RE : SQ_UNESCAPE_RE, '$1');
+    }
+  }
+  return raw;
+}
+
+/**
+ * Split a `key=value` token into its parts, unquoting/unescaping the value.
+ * Returns null for tokens with no `=` past the first character (bare words,
+ * `#id`, `.class`, or a leading `=`).
+ */
+export function splitKeyValueToken(token: string): { key: string; value: string } | null {
+  const eqIdx = token.indexOf('=');
+  if (eqIdx <= 0) return null;
+  return { key: token.slice(0, eqIdx), value: unquoteAttrValue(token.slice(eqIdx + 1)) };
+}
+
+// ============================================
+// Serialization
+// ============================================
+
+const NEEDS_QUOTING_RE = /[\s"'[\]{}]/;
+const DQ_ESCAPE_RE = /[\\"]/g;
+const SQ_ESCAPE_RE = /[\\']/g;
+
+/**
+ * Whether a value must be quoted to survive tokenization and the outer
+ * annotation regexes: any whitespace, quote character, bracket, or brace —
+ * or an empty value, which would otherwise serialize as a bare `key=`.
+ */
+export function needsQuoting(value: string): boolean {
+  return value === '' || NEEDS_QUOTING_RE.test(value);
+}
+
+/**
+ * Serialize an attribute value, quoting when {@link needsQuoting} says the
+ * bare form would not round-trip.
+ *
+ * Double quotes are canonical; a value containing a double quote (but no
+ * single quote) is single-quoted instead, because markdown resolves
+ * backslash escapes in text runs before our parser sees them — switching
+ * the quote character round-trips through `.md` source where `\"` would
+ * not. Backslashes and the active quote character are escaped.
+ */
+export function quoteAttrValue(value: string): string {
+  if (!needsQuoting(value)) return value;
+  if (value.includes('"') && !value.includes("'")) {
+    return `'${value.replace(SQ_ESCAPE_RE, (ch) => `\\${ch}`)}'`;
+  }
+  return `"${value.replace(DQ_ESCAPE_RE, (ch) => `\\${ch}`)}"`;
+}