@bendyline/squisq 1.2.2 → 1.4.0

package/src/imageEdit/state.ts

@@ -0,0 +1,112 @@
+/**
+ * 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

@@ -0,0 +1,57 @@
+/**
+ * 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 { formatVersionTimestamp, parseVersionTimestamp } from '../versions/timestamp.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';
+
+/** Build a snapshot path. Optionally append a collision suffix. */
+export function buildImageEditVersionPath(basename: string, date: Date, collision = 0): string {
+  const stamp = formatVersionTimestamp(date);
+  const suffix = collision > 0 ? `-${collision + 1}` : '';
+  return `${IMAGE_EDIT_VERSIONS_PREFIX}${basename}.${stamp}${suffix}.json`;
+}
+
+/**
+ * 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 {
+  if (!path.startsWith(IMAGE_EDIT_VERSIONS_PREFIX)) return null;
+  const rest = path.slice(IMAGE_EDIT_VERSIONS_PREFIX.length);
+  if (!rest.endsWith('.json')) return null;
+  const stem = rest.slice(0, -'.json'.length);
+  const lastDot = stem.lastIndexOf('.');
+  if (lastDot <= 0) return null;
+  const basename = stem.slice(0, lastDot);
+  const tail = stem.slice(lastDot + 1);
+  const dash = tail.indexOf('-');
+  let stamp: string;
+  let collision = 0;
+  if (dash >= 0) {
+    stamp = tail.slice(0, dash);
+    const n = Number(tail.slice(dash + 1));
+    if (!Number.isInteger(n) || n < 2) return null;
+    collision = n - 1;
+  } else {
+    stamp = tail;
+  }
+  const timestamp = parseVersionTimestamp(stamp);
+  if (!timestamp) return null;
+  return { basename, timestamp, collision };
+}

package/src/imageEdit/versions.ts

@@ -0,0 +1,231 @@
+/**
+ * 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.
+ */
+
+import type { ContentContainer } from '../storage/ContentContainer.js';
+import type { ImageEditDoc } from '../schemas/ImageEditDoc.js';
+import type { CoalesceOptions, PrunePolicy, Version } from '../versions/types.js';
+import { readImageEditDoc, writeImageEditDoc } from './persistence.js';
+import { IMAGE_EDIT_STATE_FILENAME } from './state.js';
+import {
+  IMAGE_EDIT_VERSIONS_PREFIX,
+  IMAGE_EDIT_DEFAULT_BASENAME,
+  buildImageEditVersionPath,
+  parseImageEditVersionPath,
+} from './versionPaths.js';
+
+const decoder = new TextDecoder();
+const encoder = new TextEncoder();
+
+/** 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[]> {
+  const entries = await container.listFiles(IMAGE_EDIT_VERSIONS_PREFIX);
+  const versions: Version[] = [];
+  for (const entry of entries) {
+    const parsed = parseImageEditVersionPath(entry.path);
+    if (!parsed) continue;
+    if (basename !== undefined && parsed.basename !== basename) continue;
+    versions.push({
+      path: entry.path,
+      basename: parsed.basename,
+      timestamp: parsed.timestamp,
+      size: entry.size,
+      collision: parsed.collision,
+    });
+  }
+  versions.sort((a, b) => {
+    const dt = b.timestamp.getTime() - a.timestamp.getTime();
+    if (dt !== 0) return dt;
+    return b.collision - a.collision;
+  });
+  return versions;
+}
+
+/** 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> {
+  const path = typeof version === 'string' ? version : version.path;
+  const data = await container.readFile(path);
+  if (!data) return null;
+  return decoder.decode(data);
+}
+
+/** 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);
+
+  const versions = await listImageEditVersions(container, basename);
+  if (!options.force && versions.length > 0) {
+    const latest = versions[0]!;
+    const existing = await readImageEditVersionText(container, latest);
+    if (existing === serialized) {
+      return { saved: false, version: null, reason: 'unchanged' };
+    }
+  }
+
+  const now = options.now ?? new Date();
+  let collision = 0;
+  let path = buildImageEditVersionPath(basename, now, collision);
+  while (await container.exists(path)) {
+    collision += 1;
+    path = buildImageEditVersionPath(basename, now, collision);
+  }
+
+  const data = encoder.encode(serialized);
+  await container.writeFile(path, data, 'application/json');
+
+  const version: Version = {
+    path,
+    basename,
+    timestamp: now,
+    size: data.byteLength,
+    collision,
+  };
+  return { saved: true, version, reason: 'saved' };
+}
+
+/** 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[]> {
+  const versions = await listImageEditVersions(container, basename);
+  const toDelete: Version[] = [];
+
+  if (policy.type === 'keep-last-n') {
+    const n = Math.max(0, Math.floor(policy.n));
+    toDelete.push(...versions.slice(n));
+  } else if (policy.type === 'older-than') {
+    const cutoff = policy.date.getTime();
+    for (const v of versions) {
+      if (v.timestamp.getTime() < cutoff) toDelete.push(v);
+    }
+  } else {
+    for (const v of versions) {
+      if (!policy.keep(v, versions)) toDelete.push(v);
+    }
+  }
+
+  for (const v of toDelete) {
+    await container.removeFile(v.path);
+  }
+  return toDelete;
+}
+
+/** Collapse adjacent snapshots within `windowMs`, keeping the newer of each pair. */
+export async function coalesceImageEditVersions(
+  container: ContentContainer,
+  options: CoalesceOptions = {},
+  basename?: string,
+): Promise<Version[]> {
+  const windowMs = options.windowMs ?? 60_000;
+  const versions = await listImageEditVersions(container, basename);
+  const toDelete: Version[] = [];
+  if (versions.length > 0) {
+    let anchor = versions[0]!;
+    for (let i = 1; i < versions.length; i++) {
+      const candidate = versions[i]!;
+      if (anchor.timestamp.getTime() - candidate.timestamp.getTime() <= windowMs) {
+        toDelete.push(candidate);
+      } else {
+        anchor = candidate;
+      }
+    }
+  }
+  for (const v of toDelete) {
+    await container.removeFile(v.path);
+  }
+  return toDelete;
+}

package/src/index.ts

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

package/src/jsonForm/chooseControl.ts

@@ -0,0 +1,88 @@
+/**
+ * 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

@@ -0,0 +1,59 @@
+/**
+ * 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

@@ -0,0 +1,22 @@
+/**
+ * `@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 { toPointer, pointerSegments, getByPointer, setByPointer, resolveRef } from './pointer.js';
+export { inferSchema } from './inferSchema.js';
+export type { InferSchemaOptions } from './inferSchema.js';

package/src/jsonForm/inferSchema.ts

@@ -0,0 +1,25 @@
+/**
+ * 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;
+}