@bendyline/squisq 2.1.0 → 2.3.0

package/src/imageEdit/state.ts

@@ -1,112 +0,0 @@
-/**
- * Pure helpers for constructing and mutating {@link ImageEditDoc} values.
- *
- * All functions are side-effect free and return new doc objects rather
- * than mutating their inputs, so they're safe to use from a reducer.
- */
-
-import type { ImageEditDoc, ImageEditLayer } from '../schemas/ImageEditDoc.js';
-
-/** Filename used for the persisted editor state inside the sidecar. */
-export const IMAGE_EDIT_STATE_FILENAME = 'state.json';
-
-/** Subfolder (inside the sidecar) for embedded asset bytes. */
-export const IMAGE_EDIT_ASSETS_PREFIX = 'assets/';
-
-/** Generate a short random layer id. */
-function nextLayerId(): string {
-  return `layer-${Math.random().toString(36).slice(2, 10)}`;
-}
-
-/**
- * Create an empty doc with the given canvas size and no layers.
- *
- * `meta.createdAt` and `meta.updatedAt` are set to the current time so
- * the doc has a complete metadata footprint from the start.
- */
-export function createEmptyImageEditDoc(
-  width: number,
-  height: number,
-  options: { background?: string; sourcePath?: string; now?: Date } = {},
-): ImageEditDoc {
-  const now = (options.now ?? new Date()).toISOString();
-  return {
-    version: 1,
-    canvas: {
-      width,
-      height,
-      background: options.background ?? 'transparent',
-    },
-    layers: [],
-    meta: {
-      sourcePath: options.sourcePath,
-      createdAt: now,
-      updatedAt: now,
-    },
-  };
-}
-
-/** Append a layer (top of stack). Assigns an id when missing. */
-export function addLayer(doc: ImageEditDoc, layer: ImageEditLayer): ImageEditDoc {
-  const withId: ImageEditLayer = layer.id ? layer : { ...layer, id: nextLayerId() };
-  return touch({ ...doc, layers: [...doc.layers, withId] });
-}
-
-/** Remove the layer with the given id. No-op if not found. */
-export function removeLayer(doc: ImageEditDoc, layerId: string): ImageEditDoc {
-  const next = doc.layers.filter((l) => l.id !== layerId);
-  if (next.length === doc.layers.length) return doc;
-  return touch({ ...doc, layers: next });
-}
-
-/**
- * Reorder a layer to a new index in the stack. The index is clamped to
- * the valid range; out-of-range / missing layers are no-ops.
- */
-export function reorderLayer(doc: ImageEditDoc, layerId: string, toIndex: number): ImageEditDoc {
-  const fromIndex = doc.layers.findIndex((l) => l.id === layerId);
-  if (fromIndex < 0) return doc;
-  const clamped = Math.max(0, Math.min(doc.layers.length - 1, Math.floor(toIndex)));
-  if (clamped === fromIndex) return doc;
-  const next = doc.layers.slice();
-  const [layer] = next.splice(fromIndex, 1);
-  next.splice(clamped, 0, layer!);
-  return touch({ ...doc, layers: next });
-}
-
-/**
- * Replace the layer with the given id by applying a partial update.
- * The patch is shallow-merged at the top level; callers updating
- * `content`, `position`, etc. must spread those sub-objects themselves.
- */
-export function updateLayer(
-  doc: ImageEditDoc,
-  layerId: string,
-  patch: Partial<ImageEditLayer>,
-): ImageEditDoc {
-  let changed = false;
-  const next = doc.layers.map((l) => {
-    if (l.id !== layerId) return l;
-    changed = true;
-    return { ...l, ...patch } as ImageEditLayer;
-  });
-  if (!changed) return doc;
-  return touch({ ...doc, layers: next });
-}
-
-/** Replace the canvas configuration. */
-export function setCanvas(doc: ImageEditDoc, canvas: ImageEditDoc['canvas']): ImageEditDoc {
-  return touch({ ...doc, canvas });
-}
-
-/** Bump `meta.updatedAt`. Pure: returns a new doc. */
-export function touch(doc: ImageEditDoc, now: Date = new Date()): ImageEditDoc {
-  return {
-    ...doc,
-    meta: {
-      ...doc.meta,
-      createdAt: doc.meta?.createdAt ?? now.toISOString(),
-      updatedAt: now.toISOString(),
-    },
-  };
-}

package/src/imageEdit/versionPaths.ts

@@ -1,44 +0,0 @@
-/**
- * Path conventions for image-editor version snapshots.
- *
- * Snapshots live inside the sidecar at
- * `.versions/<basename>.<timestamp>[<-suffix>].json`. The collision
- * suffix (`-2`, `-3`, ...) is appended only when two snapshots land on
- * the same UTC second.
- *
- * Mirrors `core/src/versions/paths.ts` but keyed on `.json` instead of
- * `.md` so the two histories live side-by-side without colliding.
- */
-
-import {
-  buildSnapshotPath,
-  parseSnapshotPath,
-  type SnapshotPathStrategy,
-} from '../versions/snapshotStore.js';
-
-/** Subfolder (inside the sidecar) that holds image-editor snapshots. */
-export const IMAGE_EDIT_VERSIONS_PREFIX = '.versions/';
-
-/** Default basename when none is supplied. Matches `IMAGE_EDIT_STATE_FILENAME` stem. */
-export const IMAGE_EDIT_DEFAULT_BASENAME = 'state';
-
-/** Internal strategy shared with the generic snapshot store. */
-export const IMAGE_EDIT_VERSION_PATHS: SnapshotPathStrategy = Object.freeze({
-  prefix: IMAGE_EDIT_VERSIONS_PREFIX,
-  extension: 'json',
-});
-
-/** Build a snapshot path. Optionally append a collision suffix. */
-export function buildImageEditVersionPath(basename: string, date: Date, collision = 0): string {
-  return buildSnapshotPath(IMAGE_EDIT_VERSION_PATHS, basename, date, collision);
-}
-
-/**
- * Parse a snapshot path. Returns `null` when the path doesn't match the
- * convention (so unrelated `.versions/*.json` files are ignored).
- */
-export function parseImageEditVersionPath(
-  path: string,
-): { basename: string; timestamp: Date; collision: number } | null {
-  return parseSnapshotPath(IMAGE_EDIT_VERSION_PATHS, path);
-}

package/src/imageEdit/versions.ts

@@ -1,152 +0,0 @@
-/**
- * Image-editor version operations against a sidecar
- * {@link ContentContainer}.
- *
- * Mirrors `core/src/versions/operations.ts` but operates on
- * {@link ImageEditDoc} JSON state at `.versions/<basename>.<timestamp>.json`
- * instead of the markdown document. Reuses {@link PrunePolicy} so hosts
- * can share their pruning configuration between the two histories. The
- * sidecar root gets a `.gitignore` rule for `.versions/` when snapshots
- * are retained.
- */
-
-import type { ContentContainer } from '../storage/ContentContainer.js';
-import type { ImageEditDoc } from '../schemas/ImageEditDoc.js';
-import type { CoalesceOptions, PrunePolicy, Version } from '../versions/types.js';
-import {
-  coalesceSnapshots,
-  listSnapshots,
-  pruneSnapshots,
-  readTextSnapshot,
-  saveTextSnapshot,
-} from '../versions/snapshotStore.js';
-import { readImageEditDoc, writeImageEditDoc } from './persistence.js';
-import { IMAGE_EDIT_STATE_FILENAME } from './state.js';
-import { IMAGE_EDIT_DEFAULT_BASENAME, IMAGE_EDIT_VERSION_PATHS } from './versionPaths.js';
-
-/** Options for {@link saveImageEditVersion}. */
-export interface SaveImageEditVersionOptions {
-  /** Override the doc to snapshot; otherwise `state.json` is read from the sidecar. */
-  doc?: ImageEditDoc;
-  /** Override the snapshot timestamp. Defaults to `new Date()`. */
-  now?: Date;
-  /** Skip the diff-vs-latest check and force a write. */
-  force?: boolean;
-  /** Override the basename used in version filenames. Defaults to `'state'`. */
-  basename?: string;
-  /** Override the source filename inside the sidecar. Defaults to `state.json`. */
-  stateFilename?: string;
-}
-
-/** Result of a {@link saveImageEditVersion} call. */
-export interface SaveImageEditVersionResult {
-  saved: boolean;
-  version: Version | null;
-  /** `'saved' | 'unchanged' | 'no-state'` — `'no-state'` means there was nothing to snapshot. */
-  reason: 'saved' | 'unchanged' | 'no-state';
-}
-
-/** Options for {@link revertToImageEditVersion}. */
-export interface RevertImageEditOptions {
-  /**
-   * Whether to snapshot the *current* state before replacing it. Defaults to `true`.
-   */
-  snapshotCurrent?: boolean;
-  /** Override the source filename. Defaults to `state.json`. */
-  stateFilename?: string;
-}
-
-/** List image-edit snapshots in the sidecar, newest-first. */
-export async function listImageEditVersions(
-  container: ContentContainer,
-  basename?: string,
-): Promise<Version[]> {
-  return listSnapshots(container, IMAGE_EDIT_VERSION_PATHS, basename);
-}
-
-/** Read a snapshot's JSON text. Returns `null` if the snapshot is missing. */
-export async function readImageEditVersionText(
-  container: ContentContainer,
-  version: Version | string,
-): Promise<string | null> {
-  return readTextSnapshot(container, version);
-}
-
-/** Read and parse a snapshot. Returns `null` if missing. */
-export async function readImageEditVersion(
-  container: ContentContainer,
-  version: Version | string,
-): Promise<ImageEditDoc | null> {
-  const text = await readImageEditVersionText(container, version);
-  if (text === null) return null;
-  return JSON.parse(text) as ImageEditDoc;
-}
-
-/**
- * Snapshot the current image-editor state if it differs from the latest
- * existing snapshot.
- *
- * Diff is computed on the *serialized* JSON (with stable 2-space
- * indentation) so semantically-equal states with different key order
- * still snapshot — accept the over-snapshot rather than running a deep
- * structural compare.
- */
-export async function saveImageEditVersion(
-  container: ContentContainer,
-  options: SaveImageEditVersionOptions = {},
-): Promise<SaveImageEditVersionResult> {
-  const stateFilename = options.stateFilename ?? IMAGE_EDIT_STATE_FILENAME;
-  const doc = options.doc ?? (await readImageEditDoc(container, stateFilename));
-  if (!doc) {
-    return { saved: false, version: null, reason: 'no-state' };
-  }
-  const basename = options.basename ?? IMAGE_EDIT_DEFAULT_BASENAME;
-  const serialized = JSON.stringify(doc, null, 2);
-
-  return saveTextSnapshot(container, IMAGE_EDIT_VERSION_PATHS, {
-    content: serialized,
-    basename,
-    mimeType: 'application/json',
-    now: options.now,
-    force: options.force,
-  });
-}
-
-/** Revert `state.json` to a prior snapshot. Snapshots the current state first by default. */
-export async function revertToImageEditVersion(
-  container: ContentContainer,
-  version: Version | string,
-  options: RevertImageEditOptions = {},
-): Promise<{ reverted: boolean; snapshotted: Version | null }> {
-  const doc = await readImageEditVersion(container, version);
-  if (!doc) {
-    return { reverted: false, snapshotted: null };
-  }
-
-  let snapshotted: Version | null = null;
-  if (options.snapshotCurrent !== false) {
-    const result = await saveImageEditVersion(container, { stateFilename: options.stateFilename });
-    snapshotted = result.version;
-  }
-
-  await writeImageEditDoc(container, doc, options.stateFilename);
-  return { reverted: true, snapshotted };
-}
-
-/** Delete snapshots that don't satisfy the policy. */
-export async function pruneImageEditVersions(
-  container: ContentContainer,
-  policy: PrunePolicy,
-  basename?: string,
-): Promise<Version[]> {
-  return pruneSnapshots(container, IMAGE_EDIT_VERSION_PATHS, policy, basename);
-}
-
-/** Collapse adjacent snapshots within `windowMs`, keeping the newer of each pair. */
-export async function coalesceImageEditVersions(
-  container: ContentContainer,
-  options: CoalesceOptions = {},
-  basename?: string,
-): Promise<Version[]> {
-  return coalesceSnapshots(container, IMAGE_EDIT_VERSION_PATHS, options, basename);
-}

package/src/index.ts

@@ -1,15 +0,0 @@
-export * from './schemas/index.js';
-export * from './doc/index.js';
-export * from './spatial/index.js';
-export * from './storage/index.js';
-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';
-export * from './narration/index.js';

package/src/internal/immutable.ts

@@ -1,58 +0,0 @@
-/**
- * Clone JSON-shaped runtime configuration without relying on structuredClone
- * (which is unavailable in some of the ES2020/browser runtimes core supports).
- * Data objects are recreated with safe own-property definitions so even a key
- * named `__proto__` remains ordinary data.
- */
-export function cloneData<T>(value: T, seen: WeakMap<object, unknown> = new WeakMap()): T {
-  if (value === null || typeof value !== 'object') return value;
-
-  const existing = seen.get(value);
-  if (existing !== undefined) return existing as T;
-
-  const tag = Object.prototype.toString.call(value);
-  if (tag === '[object ArrayBuffer]') {
-    const source = new Uint8Array(value as unknown as ArrayBuffer);
-    const copy = new Uint8Array(source.byteLength);
-    copy.set(source);
-    return copy.buffer as T;
-  }
-  if (tag === '[object Date]') {
-    return new Date(Date.prototype.getTime.call(value)) as T;
-  }
-
-  if (Array.isArray(value)) {
-    const copy: unknown[] = [];
-    seen.set(value, copy);
-    for (const item of value) copy.push(cloneData(item, seen));
-    return copy as T;
-  }
-
-  const source = value as Record<string, unknown>;
-  const copy: Record<string, unknown> = {};
-  seen.set(value, copy);
-  for (const key of Object.keys(source)) {
-    Object.defineProperty(copy, key, {
-      value: cloneData(source[key], seen),
-      enumerable: true,
-      configurable: true,
-      writable: true,
-    });
-  }
-  return copy as T;
-}
-
-/** Recursively freeze a data graph. Cycles are supported. */
-export function deepFreezeData<T>(value: T, seen: WeakSet<object> = new WeakSet()): T {
-  if (value === null || typeof value !== 'object' || seen.has(value)) return value;
-  seen.add(value);
-  for (const key of Object.keys(value)) {
-    deepFreezeData((value as Record<string, unknown>)[key], seen);
-  }
-  return Object.freeze(value);
-}
-
-/** Take an immutable snapshot suitable for storing in a process registry. */
-export function cloneAndFreezeData<T>(value: T): T {
-  return deepFreezeData(cloneData(value));
-}

package/src/jsonForm/chooseControl.ts

@@ -1,88 +0,0 @@
-/**
- * Pick a `ControlKind` for a schema node. The single dispatcher used by
- * both `<JsonView>` and `<JsonEditor>` so view and edit modes always
- * agree on what each field _is_, even when their UIs differ.
- *
- * Order of precedence:
- *   1. Explicit `squisq.control` hint
- *   2. `format` keyword (color/date/time/datetime/markdown/textarea)
- *   3. Enum cardinality (segmented vs. combobox)
- *   4. Numeric range (slider when both min and max present)
- *   5. String length (multiline when maxLength > 200)
- *   6. Type-default (object/array/boolean/string/number)
- */
-
-import type { ControlKind, SquisqAnnotatedSchema } from './types.js';
-
-const ENUM_SEGMENTED_LIMIT = 4;
-const MULTILINE_LENGTH_THRESHOLD = 200;
-
-export function chooseControl(schema: SquisqAnnotatedSchema): ControlKind {
-  const hint = schema.squisq?.control;
-  if (hint) return hint;
-
-  const type = primaryType(schema);
-
-  if (schema.format && type === 'string') {
-    switch (schema.format) {
-      case 'color':
-        return 'color';
-      case 'date':
-        return 'date';
-      case 'time':
-        return 'time';
-      case 'date-time':
-        return 'datetime';
-      case 'markdown':
-        return 'richtext';
-      case 'textarea':
-        return 'multiline';
-    }
-  }
-
-  if (schema.enum && schema.enum.length > 0) {
-    return schema.enum.length <= ENUM_SEGMENTED_LIMIT ? 'segmented' : 'combobox';
-  }
-
-  if (schema.oneOf || schema.anyOf) return 'tabs';
-
-  switch (type) {
-    case 'array':
-      return arrayItemKind(schema) === 'object' ? 'card-stack' : 'chip-bin';
-    case 'object':
-      return 'group';
-    case 'boolean':
-      return 'toggle';
-    case 'integer':
-    case 'number':
-      return hasFiniteRange(schema) ? 'slider' : 'stepper';
-    case 'string':
-      if (typeof schema.maxLength === 'number' && schema.maxLength > MULTILINE_LENGTH_THRESHOLD) {
-        return 'multiline';
-      }
-      return 'text';
-    default:
-      return 'text';
-  }
-}
-
-/** Return the first concrete type of a schema, ignoring `null` for nullable shorthand. */
-export function primaryType(schema: SquisqAnnotatedSchema): string | undefined {
-  const t = schema.type;
-  if (typeof t === 'string') return t;
-  if (Array.isArray(t)) return t.find((x) => x !== 'null');
-  return undefined;
-}
-
-/** Inspect `items` to decide whether an array holds objects or primitives. */
-export function arrayItemKind(schema: SquisqAnnotatedSchema): 'object' | 'primitive' {
-  const items = Array.isArray(schema.items) ? schema.items[0] : schema.items;
-  if (!items) return 'primitive';
-  return primaryType(items) === 'object' ? 'object' : 'primitive';
-}
-
-function hasFiniteRange(schema: SquisqAnnotatedSchema): boolean {
-  const min = schema.minimum ?? schema.exclusiveMinimum;
-  const max = schema.maximum ?? schema.exclusiveMaximum;
-  return typeof min === 'number' && typeof max === 'number';
-}

package/src/jsonForm/evaluateWhen.ts

@@ -1,59 +0,0 @@
-/**
- * Evaluate a `SquisqWhen` rule against the current root data. Pure;
- * renderers call this on every render with fresh data.
- */
-
-import type { SquisqWhen } from './types.js';
-import { getByPointer } from './pointer.js';
-
-export function evaluateWhen(when: SquisqWhen, rootData: unknown): boolean {
-  const actual = getByPointer(rootData, when.field);
-
-  if (when.equals !== undefined) {
-    return deepEqual(actual, when.equals);
-  }
-  if (when.oneOf !== undefined) {
-    return when.oneOf.some((v) => deepEqual(actual, v));
-  }
-  if (when.matches !== undefined) {
-    if (typeof actual !== 'string') return false;
-    try {
-      return new RegExp(when.matches).test(actual);
-    } catch {
-      return false;
-    }
-  }
-  if (when.truthy !== undefined) {
-    return Boolean(actual) === when.truthy;
-  }
-  // No operator specified — defaults to "field has any defined value".
-  return actual !== undefined && actual !== null;
-}
-
-/**
- * Resolve a `boolean | SquisqWhen` flag (used by `hidden`/`disabled`)
- * to a final boolean. Literal booleans pass through.
- */
-export function resolveFlag(flag: boolean | SquisqWhen | undefined, rootData: unknown): boolean {
-  if (flag === undefined) return false;
-  if (typeof flag === 'boolean') return flag;
-  return evaluateWhen(flag, rootData);
-}
-
-function deepEqual(a: unknown, b: unknown): boolean {
-  if (a === b) return true;
-  if (a === null || b === null) return false;
-  if (typeof a !== typeof b) return false;
-  if (typeof a !== 'object') return false;
-  if (Array.isArray(a)) {
-    if (!Array.isArray(b) || a.length !== b.length) return false;
-    return a.every((v, i) => deepEqual(v, b[i]));
-  }
-  if (Array.isArray(b)) return false;
-  const ao = a as Record<string, unknown>;
-  const bo = b as Record<string, unknown>;
-  const ak = Object.keys(ao);
-  const bk = Object.keys(bo);
-  if (ak.length !== bk.length) return false;
-  return ak.every((k) => deepEqual(ao[k], bo[k]));
-}

package/src/jsonForm/index.ts

@@ -1,32 +0,0 @@
-/**
- * `@bendyline/squisq/jsonForm` — headless JSON Form logic.
- *
- * Pure utilities consumed by `<JsonView>` (read-only) in
- * `@bendyline/squisq-react` and `<JsonEditor>` (editable) in
- * `@bendyline/squisq-editor-react`. Zero React deps.
- */
-
-export type {
-  ControlKind,
-  SquisqHints,
-  SquisqWhen,
-  SquisqAnnotatedSchema,
-  JsonFormValidationError,
-  JsonFormValidator,
-} from './types.js';
-
-export { chooseControl, primaryType, arrayItemKind } from './chooseControl.js';
-export { evaluateWhen, resolveFlag } from './evaluateWhen.js';
-export {
-  escapePointerSegment,
-  appendPointer,
-  toPointer,
-  pointerSegments,
-  getByPointer,
-  setByPointer,
-  resolveRef,
-} from './pointer.js';
-export { inferSchema } from './inferSchema.js';
-export type { InferSchemaOptions } from './inferSchema.js';
-export { buildJsonFormTokens, resolveJsonFormTheme } from './tokens.js';
-export type { BuildJsonFormTokensOptions } from './tokens.js';

package/src/jsonForm/inferSchema.ts

@@ -1,25 +0,0 @@
-/**
- * Infer a JSON Schema from an example JSON value. Thin facade over
- * `genson-js` so consumers don't depend on it directly and we can swap
- * the implementation later.
- */
-
-import { createSchema, mergeSchemas } from 'genson-js';
-import type { SquisqAnnotatedSchema } from './types.js';
-
-export interface InferSchemaOptions {
-  /** Additional samples merged into the inferred schema for broader coverage. */
-  additionalSamples?: readonly unknown[];
-}
-
-export function inferSchema(
-  sample: unknown,
-  options: InferSchemaOptions = {},
-): SquisqAnnotatedSchema {
-  const base = createSchema(sample) as SquisqAnnotatedSchema;
-  if (!options.additionalSamples || options.additionalSamples.length === 0) {
-    return base;
-  }
-  const extras = options.additionalSamples.map((s) => createSchema(s) as SquisqAnnotatedSchema);
-  return mergeSchemas([base, ...extras] as never[]) as SquisqAnnotatedSchema;
-}