@cliquify.me/state 8.0.6 → 8.1.0

package/dist/utils/normalize-design.d.ts

@@ -0,0 +1,50 @@
+import { IDesign, ISize } from '@cliquify.me/types';
+
+/**
+ * Bring a design onto the shape the render layer expects.
+ *
+ * A design can arrive in several historical shapes. Until now every consumer
+ * translated between them by hand, which meant three copies of the same logic
+ * and one place it was missing:
+ *
+ *   react-editor          `src/app.tsx` and `src/appTemplate.tsx`
+ *   video-renderer-site   `src/version2/MyComp.tsx`
+ *   video-remotion-previewer  — nothing, so a generated design crashed it with
+ *                             "undefined is not iterable" before frame 1
+ *
+ * That last one is why this function exists. `elements-ui`'s caption element
+ * reads `details.words`, and `ICaptionDetails.words` is a *required* field, but
+ * the editor writes caption words to `metadata.words`. Whoever forgot to bridge
+ * the two got a hard crash rather than a missing caption.
+ *
+ * Call this once, wherever a design enters your process. It is pure: the input
+ * is left alone and only the items that actually changed are re-created, so
+ * normalising a design that is already normal is close to free.
+ */
+/** What a design may look like on the way in, before normalisation. */
+export interface DenormalizedDesign extends Omit<IDesign, "size"> {
+    size?: ISize;
+    /** Older payloads carried the canvas size here. */
+    frame?: ISize;
+    /**
+     * Legacy split of item details into a parallel map. Superseded by inline
+     * `details` on each track item.
+     */
+    trackItemDetailsMap?: Record<string, {
+        details?: Record<string, unknown>;
+    }>;
+}
+export interface NormalizeDesignOptions {
+    /**
+     * Ensure every caption has a `details.words` array, inserting an empty one
+     * where nothing supplied it. Defaults to true: `ICaptionDetails.words` is
+     * required, and the caption element destructures it without a guard.
+     */
+    ensureCaptionWords?: boolean;
+}
+/**
+ * Returns `T` rather than promising a populated `size`: if the input carried
+ * neither `size` nor `frame` there is nothing to fill it from, and claiming
+ * otherwise in the type would just move the crash somewhere less obvious.
+ */
+export declare function normalizeDesign<T extends DenormalizedDesign>(design: T, options?: NormalizeDesignOptions): T;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cliquify.me/state",
-  "version": "8.0.6",
+  "version": "8.1.0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -28,7 +28,8 @@
     "typescript": "5.4.5",
     "vite": "^5.2.0",
     "vite-plugin-dts": "^3.9.1",
-    "@cliquify.me/types": "8.0.6",
+    "vitest": "^3.2.7",
+    "@cliquify.me/types": "8.0.7",
     "@cliquify.me/typescript-config": "0.0.2"
   },
   "dependencies": {
@@ -42,11 +43,12 @@
   },
   "peerDependencies": {
     "@designcombo/events": "^1.0.2",
-    "@cliquify.me/types": "8.0.6"
+    "@cliquify.me/types": "8.0.7"
   },
   "scripts": {
     "dev": "vite",
     "build": "tsc && vite build",
-    "format": "prettier --write ."
+    "format": "prettier --write .",
+    "test": "vitest run"
   }
 }