@compact-design/core 0.2.0 → 0.3.0

package/dist/normalize.d.ts

@@ -1,4 +1,10 @@
-import type { InternalDocument, InternalPatchDocument } from "./types";
+import type { InternalDocument, InternalPatchDocument, JsonObject, PatchSetValues } from "./types";
 export declare function normalizeDocument(value: unknown): InternalDocument;
+/**
+ * Normalize a patch `set` without knowing the target. Only authored keys are
+ * produced; nothing is defaulted (no Arial, no TEXT fill). Unknown, deferred
+ * and immutable keys throw. Coordinates stay parent-relative.
+ */
+export declare function normalizePatchSet(set: JsonObject, path?: string): PatchSetValues;
 export declare function isPatchDocument(value: unknown): boolean;
 export declare function normalizePatchDocument(value: unknown): InternalPatchDocument;

package/dist/patch-definitions.d.ts

@@ -0,0 +1,41 @@
+import type { ComponentPropertyPatchEntry, DesignProperties, InternalNode } from "./types";
+export type AxisRename = {
+    from: string;
+    to: string;
+};
+export type OptionRename = {
+    axis: string;
+    from: string;
+    to: string;
+};
+/** Explicit variantAxes patch entry: array sets options (never renames); object renames explicitly. */
+export type VariantAxisPatchEntry = null | string[] | {
+    rename?: string;
+    options?: string[];
+    renameOptions?: Record<string, string>;
+};
+export type VariantAxesPatch = Record<string, VariantAxisPatchEntry>;
+/**
+ * Apply a variantAxes shallow-merge with **explicit** renames only.
+ * - `axis: string[]` — replace that axis's options. Never inferred as a rename.
+ * - `axis: { rename?, options?, renameOptions? }` — explicit axis/option renames.
+ * - `axis: null` — error (Figma cannot delete VARIANT properties).
+ * Unmentioned axes are kept.
+ */
+export declare function detectVariantRenames(current: Record<string, string[]>, patch: VariantAxesPatch): {
+    axes: Record<string, string[]>;
+    axisRenames: AxisRename[];
+    optionRenames: OptionRename[];
+    errors: string[];
+};
+/** After renames, ensure removed options are not still sitting on children without renameOptions. */
+export declare function variantAxesChildConflicts(set: InternalNode, previousAxes: Record<string, string[]>, nextAxes: Record<string, string[]>, optionRenames: OptionRename[], axisRenames: AxisRename[]): string[];
+/** Every declared option must appear on at least one COMPONENT child (Figma derives options from names). */
+export declare function variantAxesUncarriedOptions(set: InternalNode, axes: Record<string, string[]>): string[];
+export declare function applyVariantRenamesInForest(roots: InternalNode[], setId: string, axisRenames: AxisRename[], optionRenames: OptionRename[], axes: Record<string, string[]>, index?: Map<string, {
+    node: InternalNode;
+    parent: InternalNode | null;
+}>): void;
+export declare function applyComponentPropertiesPatch(props: DesignProperties, patch: Record<string, ComponentPropertyPatchEntry | null> | null, path: string): string[];
+export declare function applyVariantPatchOnComponent(node: InternalNode, parent: InternalNode | null, patch: Record<string, string | null> | null, path: string): string[];
+export declare function rewriteVariantChildNames(set: InternalNode): void;

package/dist/patch-duplicate.d.ts

@@ -0,0 +1,34 @@
+import type { InternalNode, JsonObject } from "./types";
+/** Collect every id in a subtree (root first, depth-first). */
+export declare function collectSubtreeIds(node: InternalNode): string[];
+export declare function subtreeContainsType(node: InternalNode, types: Set<string>): boolean;
+/**
+ * Build the deterministic id map for a duplicate.
+ * Default: `<sourceId><idSuffix>` for every id in the subtree.
+ * `ids` overrides specific source→new mappings; every key must be in the subtree.
+ */
+export declare function buildDuplicateIdMap(source: InternalNode, idSuffix: string, ids: Record<string, string> | undefined, path: string): {
+    map: Map<string, string>;
+    errors: string[];
+};
+/** Same as buildDuplicateIdMap but when only the id set is known (e.g. live Figma walk). */
+export declare function buildDuplicateIdMapFromIds(subtreeIds: Iterable<string>, idSuffix: string, ids: Record<string, string> | undefined, path: string): {
+    map: Map<string, string>;
+    errors: string[];
+};
+/** Deep-clone a node tree applying an id map (and re-pointing internal prototype destinations). */
+export declare function cloneSubtreeWithIds(node: InternalNode, idMap: Map<string, string>): InternalNode;
+/** Re-point prototype destinations that land inside the duplicated subtree. */
+export declare function rewritePrototypeDestinations(properties: JsonObject, idMap: Map<string, string>): void;
+/**
+ * Replace only delimited whole ids in text (quoted `'id'` / `"id"`, or path
+ * segments bounded by non-id characters). Longest source ids first so
+ * `card-title` is not corrupted by a shorter `card` mapping.
+ */
+export declare function remapDelimitedIds(text: string, idMap: Map<string, string>): string;
+/**
+ * Remap issue identity keys through a source→copy id map so duplicated
+ * pre-existing issues on the copy are exempt (with multiplicity).
+ * Owner is remapped exactly (`node:${id}`); path/message only via delimited ids.
+ */
+export declare function remapIssueKeyThroughDuplicate(key: string, idMap: Map<string, string>): string | null;

package/dist/patch-keys.d.ts

@@ -0,0 +1,61 @@
+import type { JsonObject } from "./types";
+/**
+ * Single source of truth for `set` in patch operations. Every key a node may
+ * carry in the schema is either settable here or explicitly excluded. Core,
+ * the JSON schema test-suite, and the Figma adapter all read this list.
+ */
+export declare const PATCH_SET_EXCLUDED_NODE_KEYS: readonly ["id", "type", "children", "coordinateMode"];
+export declare const PATCH_SET_KEYS: readonly ["name", "x", "y", "w", "h", "rotation", "fill", "fills", "stroke", "strokes", "strokeWeight", "strokeTopWeight", "strokeRightWeight", "strokeBottomWeight", "strokeLeftWeight", "strokeAlign", "strokeCap", "strokeJoin", "dashPattern", "cornerRadius", "cornerRadii", "opacity", "blendMode", "visible", "locked", "isMask", "clipsContent", "effects", "elevation", "shadow", "layout", "constraints", "layoutSizingHorizontal", "layoutSizingVertical", "layoutAlign", "layoutGrow", "layoutPositioning", "minWidth", "maxWidth", "minHeight", "maxHeight", "layoutGrids", "text", "font", "lineHeight", "letterSpacing", "align", "verticalAlignment", "textDecoration", "textCase", "paragraphSpacing", "paragraphIndent", "listSpacing", "hangingPunctuation", "hangingList", "textAutoResize", "textTruncation", "maxLines", "runs", "pointCount", "innerRadius", "startingAngle", "endingAngle", "innerRadiusRatio", "svg", "vectorPaths", "componentId", "componentProperties", "instanceProperties", "componentPropertyReferences", "variantAxes", "variant", "operation", "prototype", "overflowDirection", "numberOfFixedChildren", "styleRefs", "bindings", "variableModes"];
+export type PatchSetKey = typeof PATCH_SET_KEYS[number];
+/**
+ * - `scalar`: the value replaces the previous value.
+ * - `merge`: objects deep-merge into the current value (unmentioned fields are kept).
+ * - `replace`: arrays (paint, effect, run, grid, path lists) replace the whole list.
+ * - `deferred`: recognised but not patchable yet; both engines reject it with PATCH_SET_UNSUPPORTED.
+* - object merge keys (`bindings`, `styleRefs`, `variableModes`, `instanceProperties`, `componentPropertyReferences`, `componentProperties`, `variantAxes`, `variant`): shallow-merge entries; a field set to `null` clears that entry (except variantAxes: deleting an axis is an error).
+ * - `immutable`: can never be patched in place; remove + insert instead.
+ */
+export type PatchSetSemantics = "scalar" | "merge" | "replace" | "deferred" | "immutable";
+export declare const PATCH_SET_SEMANTICS: Readonly<Record<PatchSetKey, PatchSetSemantics>>;
+export declare const PATCH_SET_DEFERRED_KEYS: readonly PatchSetKey[];
+/** Compact node types each key applies to. `null` means every type. */
+export declare const PATCH_SET_APPLIES_TO: Readonly<Record<PatchSetKey, readonly string[] | null>>;
+/** Keys that style a TEXT node and are owned by a linked text style. */
+export declare const PATCH_TEXT_STYLE_KEYS: readonly PatchSetKey[];
+export declare function isPatchSetKey(key: string): key is PatchSetKey;
+/**
+ * The state of a patch target as seen by an engine (core document tree or the
+ * Figma scene). Both engines build this and run the same rules, so a set that
+ * is rejected in one is rejected in the other.
+ */
+export interface PatchTargetContext {
+    /** Compact node type of the target (Figma maps its native type to the compact one). */
+    type: string;
+    /** Compact type of the parent, or null for a root canvas. */
+    parentType: string | null;
+    /** Parent currently has Auto Layout. */
+    parentAutoLayout: boolean;
+    /** Target currently has Auto Layout (before this set). */
+    autoLayout: boolean;
+    /** Current layoutPositioning of the target. */
+    layoutPositioning?: string;
+    /** TEXT with per-range styling (core: a run carrying font/fill/letterSpacing/textDecoration/link; Figma: some text property is "mixed" in Figma). */
+    mixedText: boolean;
+    /** TEXT whose fonts differ per range (core: a run with font.family/style; Figma: fontName is "mixed" in Figma). */
+    mixedFontName: boolean;
+    /** TEXT linked to a text style (core: styleRefs.text; Figma: textStyleId). */
+    textStyle: boolean;
+    /** Variable-bound fields on the target (compact binding field names). */
+    boundFields: readonly string[];
+    /** Number of direct children. */
+    childCount: number;
+}
+/** Variable-binding field names a set would overwrite (fill/stroke excluded: those detach — see docs). */
+export declare function patchSetBindingFields(set: JsonObject): string[];
+/** Shape checks that need no target. Returns `key: message` strings. */
+export declare function patchSetShapeIssues(set: JsonObject): string[];
+/**
+ * Target-dependent rules. Both engines call this with their own view of the
+ * target before applying a set. Returns `key: message` strings.
+ */
+export declare function patchSetTargetIssues(set: JsonObject, context: PatchTargetContext): string[];

package/dist/patch-prototype.d.ts

@@ -0,0 +1,39 @@
+import type { InternalDocument, InternalNode, JsonObject } from "./types";
+/** Walk every destination-bearing action in a prototype array. */
+export declare function forEachPrototypeDestination(prototype: unknown, visit: (action: JsonObject, type: string, destination: string, actionPath: string) => void, basePath?: string): void;
+export declare function isAfterTimeoutReaction(reaction: JsonObject): boolean;
+/** True when `nodeId` is a document.nodes root (top-level canvas frame). */
+export declare function isTopLevelNodeId(roots: InternalNode[], nodeId: string): boolean;
+export type PrototypeLookup = {
+    has: (id: string) => boolean;
+    typeOf?: (id: string) => string | undefined;
+    /** Canvas root id for a node id (document.nodes root). */
+    canvasOf?: (id: string) => string | undefined;
+    /** Whether an id is a top-level canvas frame. */
+    isTopLevel?: (id: string) => boolean;
+};
+/**
+ * Shared destination checks (missing / CHANGE_TO / SCROLL_TO).
+ * Used by validateDocument. Does not require NAVIGATE destinations to be top-level
+ * (import stays lenient).
+ */
+export declare function assertPrototypeSetDestinations(prototype: unknown, lookup: PrototypeLookup, path: string, sourceId?: string): string[];
+/**
+ * Strict rules for patch `set.prototype` only: NAVIGATE/SWAP/OVERLAY destinations
+ * must be top-level frames; AFTER_TIMEOUT only on a top-level target.
+ */
+export declare function assertPrototypePatchRules(prototype: unknown, lookup: PrototypeLookup, path: string, sourceId: string | undefined, sourceIsTopLevel: boolean): string[];
+/** Top-level canvas id for a node (the document.nodes root containing it). */
+export declare function canvasRootId(roots: InternalNode[], nodeId: string): string | undefined;
+/**
+ * Document-wide prototype destination errors (missing / CHANGE_TO / SCROLL_TO).
+ * Used by validateDocument so end-of-patch remove of a destination fails.
+ * Import-lenient: nested NAVIGATE destinations are allowed here.
+ */
+export declare function prototypeDestinationErrors(document: InternalDocument): string[];
+/**
+ * Strict patch rules across the whole document (top-level NAVIGATE dest +
+ * AFTER_TIMEOUT only on top-level hosts). Used at end of patch with multiset
+ * exemption against the pre-patch document.
+ */
+export declare function prototypePatchStrictErrors(document: InternalDocument): string[];

package/dist/patch.d.ts

@@ -1,6 +1,30 @@
-import type { InternalDocument, InternalPatchDocument } from "./types";
+import { type RepairIssue } from "./lint";
+import { type PatchTargetContext } from "./patch-keys";
+import type { InternalDocument, InternalNode, InternalPatchDocument } from "./types";
 export interface PatchResult {
     document: InternalDocument;
     affectedIds: string[];
+    warnings: string[];
 }
+/** Thrown by applyPatch. `issues` carries every problem as structured repair output. */
+export declare class PatchError extends Error {
+    readonly issues: RepairIssue[];
+    constructor(issues: RepairIssue[]);
+}
+/** Core's view of a target, mirrored by the Figma adapter's figmaPatchContext. */
+export declare function corePatchContext(node: InternalNode, parent: InternalNode | null): PatchTargetContext;
+/**
+ * Apply a normalized patch to a canonical document. The input is never
+ * mutated. Throws PatchError (with structured issues) when an operation is
+ * rejected or when the patched document fails validateDocument.
+ */
 export declare function applyDocumentPatch(document: InternalDocument, patch: InternalPatchDocument): PatchResult;
+/**
+ * Issues present in `after` but not in `before`. Issues already in the input
+ * document never block a patch, even on nodes the patch touches; only issues
+ * the patch introduces (directly or through a move/insert/remove) are
+ * reported. Identity is code + owner (node id / variable / document) + the
+ * property path inside the owner + message, never an array index, and the
+ * comparison is a multiset so a second copy of an existing issue counts as new.
+ */
+export declare function newDocumentIssues(before: InternalDocument, after: InternalDocument, duplicateMaps?: Array<Map<string, string>>): RepairIssue[];

package/dist/types.d.ts

@@ -22,13 +22,20 @@ export interface Constraints {
     horizontal: "MIN" | "CENTER" | "MAX" | "STRETCH" | "SCALE";
     vertical: "MIN" | "CENTER" | "MAX" | "STRETCH" | "SCALE";
 }
-export type ComponentPropertyType = "BOOLEAN" | "TEXT" | "INSTANCE_SWAP" | "VARIANT";
+/** Authorable component property types. VARIANT axes use variantAxes/variant on COMPONENT_SET instead; Figma SLOT is out of scope. */
+export type ComponentPropertyType = "BOOLEAN" | "TEXT" | "INSTANCE_SWAP";
 export interface ComponentPropertyOptions {
     preferredValues?: Array<{
         type: "COMPONENT" | "COMPONENT_SET";
         key: string;
     }>;
 }
+/** Child-layer links to the nearest ancestor COMPONENT's componentProperties (Figma componentPropertyReferences). Values are authored property names. */
+export interface ComponentPropertyReferences {
+    characters?: string;
+    visible?: string;
+    mainComponent?: string;
+}
 export type OverflowDirection = "NONE" | "HORIZONTAL" | "VERTICAL" | "BOTH";
 export type BlendMode = "PASS_THROUGH" | "NORMAL" | "DARKEN" | "MULTIPLY" | "LINEAR_BURN" | "COLOR_BURN" | "LIGHTEN" | "SCREEN" | "LINEAR_DODGE" | "COLOR_DODGE" | "OVERLAY" | "SOFT_LIGHT" | "HARD_LIGHT" | "DIFFERENCE" | "EXCLUSION" | "HUE" | "SATURATION" | "COLOR" | "LUMINOSITY";
 export type StrokeCap = "NONE" | "ROUND" | "SQUARE" | "LINE_ARROW" | "TRIANGLE_ARROW" | "DIAMOND_FILLED" | "CIRCLE_FILLED" | "TRIANGLE_FILLED" | "WASHI_TAPE_1" | "WASHI_TAPE_2" | "WASHI_TAPE_3" | "WASHI_TAPE_4" | "WASHI_TAPE_5" | "WASHI_TAPE_6";
@@ -156,6 +163,7 @@ export interface DesignProperties {
         options?: ComponentPropertyOptions;
     }>;
     instanceProperties?: Record<string, string | boolean | VariableAlias>;
+    componentPropertyReferences?: ComponentPropertyReferences;
     operation?: "UNION" | "SUBTRACT" | "INTERSECT" | "EXCLUDE";
     overflowDirection?: OverflowDirection;
     numberOfFixedChildren?: number;
@@ -262,13 +270,71 @@ export interface InternalDocument {
     variables: VariableCollectionDefinition[];
 }
 export type ImportMode = "CREATE" | "REPLACE" | "UPDATE";
+/**
+ * Normalized values of a patch `set`, independent of the target type. Only
+ * keys present in the authored set appear here: no defaults are added.
+ * Coordinates are parent-relative (the authoring convention).
+ */
+export interface ComponentPropertyPatchEntry {
+    type?: ComponentPropertyType;
+    defaultValue?: string | boolean;
+    options?: ComponentPropertyOptions;
+}
+/** variantAxes patch value: string[] replaces options (never renames); object form renames explicitly. */
+export type VariantAxisPatchEntry = null | string[] | {
+    rename?: string;
+    options?: string[];
+    renameOptions?: Record<string, string>;
+};
+export interface PatchSetValues extends Omit<Partial<DesignProperties>, "position" | "size" | "styles" | "font" | "constraints" | "layout" | "bindings" | "styleRefs" | "variableModes" | "instanceProperties" | "componentPropertyReferences" | "componentProperties" | "variantAxes" | "variant"> {
+    name?: string;
+    position?: {
+        x?: number;
+        y?: number;
+    };
+    size?: {
+        width?: number;
+        height?: number;
+    };
+    styles?: {
+        fills?: DesignPaint[];
+        strokes?: DesignPaint[];
+        effects?: DesignEffect[];
+    };
+    font?: Partial<DesignFont>;
+    constraints?: Partial<Constraints>;
+    layout?: DesignLayout;
+    /** Shallow-merge; field `null` clears that entry; whole-key `null` clears the map. */
+    bindings?: Record<string, string | null> | null;
+    styleRefs?: Record<string, string | null> | null;
+    variableModes?: Record<string, string | null> | null;
+    instanceProperties?: Record<string, string | boolean | VariableAlias | null> | null;
+    componentPropertyReferences?: {
+        characters?: string | null;
+        visible?: string | null;
+        mainComponent?: string | null;
+    } | null;
+    /** Name-keyed upsert of COMPONENT property definitions; `null` deletes a TEXT/BOOLEAN/INSTANCE_SWAP def. */
+    componentProperties?: Record<string, ComponentPropertyPatchEntry | null> | null;
+    /** Shallow-merge axes; array replaces options (never renames); object form `{ rename, options, renameOptions }` is explicit. Null axis deletes are rejected. */
+    variantAxes?: Record<string, VariantAxisPatchEntry> | null;
+    /** Merge variant selection on a COMPONENT inside a set. Whole-key or per-axis null is rejected. */
+    variant?: Record<string, string | null> | null;
+}
 export interface PatchOperation {
-    op: "SET" | "REMOVE" | "APPEND";
+    op: "SET" | "REMOVE" | "APPEND" | "INSERT" | "MOVE" | "DUPLICATE";
     id?: string;
     parent?: string;
+    index?: number;
+    /** Authored set object (keys from PATCH_SET_KEYS). */
     set?: JsonObject;
-    normalized?: DesignProperties;
+    /** Type-agnostic normalized set values; target-type rules run at apply time. */
+    normalized?: PatchSetValues;
     node?: InternalNode;
+    /** Required for DUPLICATE: non-empty suffix appended to every subtree id (unless overridden). */
+    idSuffix?: string;
+    /** Optional DUPLICATE overrides: sourceId → newId (keys must be in the source subtree). */
+    ids?: Record<string, string>;
 }
 export interface InternalPatchDocument {
     patch: {

package/dist/validate.d.ts

@@ -1,2 +1,16 @@
 import type { InternalDocument } from "./types";
-export declare function validateDocument(document: InternalDocument): string[];
+/** Validate a canonical document. Reports at most `limit` errors (default 30; pass Infinity for all). */
+export declare function validateDocument(document: InternalDocument, limit?: number): string[];
+/**
+ * A stable identity for a validateDocument issue that survives index shifts.
+ * Node issues are keyed on the owning node's id plus the property path inside
+ * that node (e.g. `node:card .bindings.fill`); variable issues on collection
+ * and variable names; anything else on its path. Array indexes in node paths
+ * (nodes[i].children[j]) never appear in the key, so an insert, move or remove
+ * elsewhere does not make an old issue look new.
+ */
+export declare function documentIssueOwners(document: InternalDocument): (path: string) => {
+    owner: string;
+    nodeId?: string;
+    rest: string;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compact-design/core",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Reusable parser, normalizer, validator, patch engine, and linter for Compact Design JSON.",
   "license": "MPL-2.0",
   "type": "module",