@snowcone-app/canvas 0.27.0 → 0.28.0

package/dist/{usePieceGuideBundle-DE21DQGZ.js.map → usePieceGuideBundle-CMe5br2a.js.map}

@@ -1 +1 @@
-{"version":3,"file":"usePieceGuideBundle-DE21DQGZ.js","sources":["../src/components/embed-realtime/usePieceGuideBundle.ts"],"sourcesContent":["'use client';\n\n/**\n * usePieceGuideBundle — fetch a product's printable-area guides for the embed.\n *\n * Some products hide part of the print file under hardware (a phone case's\n * camera module, a notebook's spine). snowcone.app's own editor draws the\n * printable-area / dead-zone overlay from the product's piece guides;\n * `<RealtimeEmbed>` uses this hook so embedders get the same overlay with\n * zero config — without it, a buyer can edit artwork the mockup will never\n * show, with no signal anywhere (#566).\n *\n * The endpoint is a public read (geometry only — piece rects, safe areas,\n * authored guides; same exposure class as the public catalog). Errors degrade\n * silently to \"no guides\": the editor keeps working, the overlay just doesn't\n * appear — same posture as snowcone.app's own loader.\n *\n * @module\n */\n\nimport { useEffect, useState } from 'react';\nimport type { PieceGuidesConfig } from '../embed/SnowconeCanvas.js';\nimport type {\n  PieceGuide,\n  PieceGuideRendererPiece,\n  PieceGuideRendererStyle,\n} from '../../rendering/PieceGuideRenderer.js';\n\n/** Backend base hosting `GET /printables/by-gvid/:gvid/piece-guides`. */\nexport const PIECE_GUIDES_API_BASE = 'https://api.snowcone.app';\n\n/** Wire shape of the piece-guides endpoint (the consumer-safe subset). */\ninterface RawPieceGuidesResponse {\n  artboardWidth: number;\n  artboardHeight: number;\n  /** Inches→px conversion factor for `safeAreaInsetInches`. */\n  templateDpi: number;\n  pieces: Array<{\n    id: string;\n    x: number;\n    y: number;\n    width: number;\n    height: number;\n    rotation?: number;\n    safeAreaInsetInches?: number;\n  }>;\n  pieceGuides?: Record<string, PieceGuide>;\n  pieceGuidesStyle?: PieceGuideRendererStyle;\n}\n\n/** A fetched bundle: the overlay config plus the artboard frame it was authored in. */\nexport interface PieceGuideBundle {\n  /** The print-file frame the piece coords live in. */\n  artboardWidth: number;\n  artboardHeight: number;\n  config: PieceGuidesConfig;\n}\n\n/** Convert the wire response into a renderer-ready bundle (inches → px, etc.). */\nexport function transformPieceGuides(raw: RawPieceGuidesResponse): PieceGuideBundle {\n  const pieces: PieceGuideRendererPiece[] = raw.pieces.map((p) => ({\n    id: p.id,\n    x: p.x,\n    y: p.y,\n    width: p.width,\n    height: p.height,\n    rotation: typeof p.rotation === 'number' ? p.rotation : undefined,\n    safeAreaInsetPx:\n      typeof p.safeAreaInsetInches === 'number' && p.safeAreaInsetInches > 0\n        ? p.safeAreaInsetInches * raw.templateDpi\n        : undefined,\n  }));\n  return {\n    artboardWidth: raw.artboardWidth,\n    artboardHeight: raw.artboardHeight,\n    config: {\n      pieces,\n      guides: raw.pieceGuides ?? {},\n      style: raw.pieceGuidesStyle,\n    },\n  };\n}\n\n/**\n * Gate the bundle on the design's artboard matching the print-file frame the\n * guides were authored in — the same gate snowcone.app's editor applies. A\n * design authored at other dims would render the overlay misaligned, so it's\n * skipped (with a dev hint, since the fix — author at the placement's dims —\n * is on the embedder's side).\n */\nexport function pieceGuidesForArtboard(\n  bundle: PieceGuideBundle,\n  artboard: { width: number; height: number } | undefined,\n): PieceGuidesConfig | undefined {\n  if (!artboard) return undefined;\n  if (artboard.width !== bundle.artboardWidth || artboard.height !== bundle.artboardHeight) {\n    if (typeof process !== 'undefined' && process.env?.NODE_ENV !== 'production') {\n      console.warn(\n        `[RealtimeEmbed] This product has printable-area guides (authored at ` +\n          `${bundle.artboardWidth}×${bundle.artboardHeight}), but the design's artboard is ` +\n          `${artboard.width}×${artboard.height} — the dead-zone overlay is skipped because the ` +\n          `coordinates wouldn't line up. Author the design at the placement's dimensions to get it.`,\n      );\n    }\n    return undefined;\n  }\n  return bundle.config;\n}\n\n/**\n * Fetch the piece-guide bundle for a variant (gvid). Returns null while\n * loading, when `gvid` is undefined, and on any error (silent degrade).\n */\nexport function usePieceGuideBundle(\n  gvid: string | undefined,\n  apiBase: string = PIECE_GUIDES_API_BASE,\n): PieceGuideBundle | null {\n  const [bundle, setBundle] = useState<PieceGuideBundle | null>(null);\n\n  useEffect(() => {\n    if (!gvid) {\n      setBundle(null);\n      return;\n    }\n    let cancelled = false;\n    fetch(`${apiBase}/printables/by-gvid/${encodeURIComponent(gvid)}/piece-guides`)\n      .then(async (res) => {\n        if (!res.ok) throw new Error(`status ${res.status}`);\n        return (await res.json()) as RawPieceGuidesResponse;\n      })\n      .then((raw) => {\n        if (!cancelled) setBundle(transformPieceGuides(raw));\n      })\n      .catch(() => {\n        // No guides is a degraded state, not a failure — the editor keeps\n        // working, the overlay just doesn't appear.\n        if (!cancelled) setBundle(null);\n      });\n    return () => {\n      cancelled = true;\n    };\n  }, [gvid, apiBase]);\n\n  return bundle;\n}\n"],"names":["PIECE_GUIDES_API_BASE","transformPieceGuides","raw","pieces","p","pieceGuidesForArtboard","bundle","artboard","process","usePieceGuideBundle","gvid","apiBase","setBundle","useState","useEffect","cancelled","res"],"mappings":";;AA6BO,MAAMA,IAAwB;AA8B9B,SAASC,EAAqBC,GAA+C;AAClF,QAAMC,IAAoCD,EAAI,OAAO,IAAI,CAACE,OAAO;AAAA,IAC/D,IAAIA,EAAE;AAAA,IACN,GAAGA,EAAE;AAAA,IACL,GAAGA,EAAE;AAAA,IACL,OAAOA,EAAE;AAAA,IACT,QAAQA,EAAE;AAAA,IACV,UAAU,OAAOA,EAAE,YAAa,WAAWA,EAAE,WAAW;AAAA,IACxD,iBACE,OAAOA,EAAE,uBAAwB,YAAYA,EAAE,sBAAsB,IACjEA,EAAE,sBAAsBF,EAAI,cAC5B;AAAA,EAAA,EACN;AACF,SAAO;AAAA,IACL,eAAeA,EAAI;AAAA,IACnB,gBAAgBA,EAAI;AAAA,IACpB,QAAQ;AAAA,MACN,QAAAC;AAAA,MACA,QAAQD,EAAI,eAAe,CAAA;AAAA,MAC3B,OAAOA,EAAI;AAAA,IAAA;AAAA,EACb;AAEJ;AASO,SAASG,EACdC,GACAC,GAC+B;;AAC/B,MAAKA,GACL;AAAA,QAAIA,EAAS,UAAUD,EAAO,iBAAiBC,EAAS,WAAWD,EAAO,gBAAgB;AACxF,MAAI,OAAOE,IAAY,SAAeA,IAAAA,EAAQ,QAARA,gBAAAA,EAAa,cAAa,gBAC9D,QAAQ;AAAA,QACN,uEACKF,EAAO,aAAa,IAAIA,EAAO,cAAc,mCAC7CC,EAAS,KAAK,IAAIA,EAAS,MAAM;AAAA,MAAA;AAI1C;AAAA,IACF;AACA,WAAOD,EAAO;AAAA;AAChB;AAMO,SAASG,EACdC,GACAC,IAAkBX,GACO;AACzB,QAAM,CAACM,GAAQM,CAAS,IAAIC,EAAkC,IAAI;AAElE,SAAAC,EAAU,MAAM;AACd,QAAI,CAACJ,GAAM;AACT,MAAAE,EAAU,IAAI;AACd;AAAA,IACF;AACA,QAAIG,IAAY;AAChB,iBAAM,GAAGJ,CAAO,uBAAuB,mBAAmBD,CAAI,CAAC,eAAe,EAC3E,KAAK,OAAOM,MAAQ;AACnB,UAAI,CAACA,EAAI,GAAI,OAAM,IAAI,MAAM,UAAUA,EAAI,MAAM,EAAE;AACnD,aAAQ,MAAMA,EAAI,KAAA;AAAA,IACpB,CAAC,EACA,KAAK,CAACd,MAAQ;AACb,MAAKa,KAAWH,EAAUX,EAAqBC,CAAG,CAAC;AAAA,IACrD,CAAC,EACA,MAAM,MAAM;AAGX,MAAKa,KAAWH,EAAU,IAAI;AAAA,IAChC,CAAC,GACI,MAAM;AACX,MAAAG,IAAY;AAAA,IACd;AAAA,EACF,GAAG,CAACL,GAAMC,CAAO,CAAC,GAEXL;AACT;"}
+{"version":3,"file":"usePieceGuideBundle-CMe5br2a.js","sources":["../src/components/embed-realtime/usePieceGuideBundle.ts"],"sourcesContent":["'use client';\n\n/**\n * usePieceGuideBundle — fetch a product's printable-area guides for the embed.\n *\n * Some products hide part of the print file under hardware (a phone case's\n * camera module, a notebook's spine). snowcone.app's own editor draws the\n * printable-area / dead-zone overlay from the product's piece guides;\n * `<RealtimeEmbed>` uses this hook so embedders get the same overlay with\n * zero config — without it, a buyer can edit artwork the mockup will never\n * show, with no signal anywhere (#566).\n *\n * The endpoint is a public read (geometry only — piece rects, safe areas,\n * authored guides; same exposure class as the public catalog). Errors degrade\n * silently to \"no guides\": the editor keeps working, the overlay just doesn't\n * appear — same posture as snowcone.app's own loader.\n *\n * @module\n */\n\nimport { useEffect, useState } from 'react';\nimport type { PieceGuidesConfig } from '../embed/SnowconeCanvas.js';\nimport type {\n  PieceGuide,\n  PieceGuideRendererPiece,\n  PieceGuideRendererStyle,\n} from '../../rendering/PieceGuideRenderer.js';\n\n/** Backend base hosting `GET /printables/by-gvid/:gvid/piece-guides`. */\nexport const PIECE_GUIDES_API_BASE = 'https://api.snowcone.app';\n\n/** Wire shape of the piece-guides endpoint (the consumer-safe subset). */\ninterface RawPieceGuidesResponse {\n  artboardWidth: number;\n  artboardHeight: number;\n  /** Inches→px conversion factor for `safeAreaInsetInches`. */\n  templateDpi: number;\n  pieces: Array<{\n    id: string;\n    x: number;\n    y: number;\n    width: number;\n    height: number;\n    rotation?: number;\n    safeAreaInsetInches?: number;\n  }>;\n  pieceGuides?: Record<string, PieceGuide>;\n  pieceGuidesStyle?: PieceGuideRendererStyle;\n}\n\n/** A fetched bundle: the overlay config plus the artboard frame it was authored in. */\nexport interface PieceGuideBundle {\n  /** The print-file frame the piece coords live in. */\n  artboardWidth: number;\n  artboardHeight: number;\n  config: PieceGuidesConfig;\n}\n\n/** Convert the wire response into a renderer-ready bundle (inches → px, etc.). */\nexport function transformPieceGuides(raw: RawPieceGuidesResponse): PieceGuideBundle {\n  const pieces: PieceGuideRendererPiece[] = raw.pieces.map((p) => ({\n    id: p.id,\n    x: p.x,\n    y: p.y,\n    width: p.width,\n    height: p.height,\n    rotation: typeof p.rotation === 'number' ? p.rotation : undefined,\n    safeAreaInsetPx:\n      typeof p.safeAreaInsetInches === 'number' && p.safeAreaInsetInches > 0\n        ? p.safeAreaInsetInches * raw.templateDpi\n        : undefined,\n  }));\n  return {\n    artboardWidth: raw.artboardWidth,\n    artboardHeight: raw.artboardHeight,\n    config: {\n      pieces,\n      guides: raw.pieceGuides ?? {},\n      style: raw.pieceGuidesStyle,\n    },\n  };\n}\n\n/**\n * Gate the bundle on the design's artboard matching the print-file frame the\n * guides were authored in — the same gate snowcone.app's editor applies. A\n * design authored at other dims would render the overlay misaligned, so it's\n * skipped (with a dev hint, since the fix — author at the placement's dims —\n * is on the embedder's side).\n */\nexport function pieceGuidesForArtboard(\n  bundle: PieceGuideBundle,\n  artboard: { width: number; height: number } | undefined,\n): PieceGuidesConfig | undefined {\n  if (!artboard) return undefined;\n  if (artboard.width !== bundle.artboardWidth || artboard.height !== bundle.artboardHeight) {\n    if (typeof process !== 'undefined' && process.env?.NODE_ENV !== 'production') {\n      console.warn(\n        `[RealtimeEmbed] This product has printable-area guides (authored at ` +\n          `${bundle.artboardWidth}×${bundle.artboardHeight}), but the design's artboard is ` +\n          `${artboard.width}×${artboard.height} — the dead-zone overlay is skipped because the ` +\n          `coordinates wouldn't line up. Author the design at the placement's dimensions to get it.`,\n      );\n    }\n    return undefined;\n  }\n  return bundle.config;\n}\n\n/**\n * Fetch the piece-guide bundle for a variant (gvid). Returns null while\n * loading, when `gvid` is undefined, and on any error (silent degrade).\n */\nexport function usePieceGuideBundle(\n  gvid: string | undefined,\n  apiBase: string = PIECE_GUIDES_API_BASE,\n): PieceGuideBundle | null {\n  const [bundle, setBundle] = useState<PieceGuideBundle | null>(null);\n\n  useEffect(() => {\n    if (!gvid) {\n      setBundle(null);\n      return;\n    }\n    let cancelled = false;\n    fetch(`${apiBase}/printables/by-gvid/${encodeURIComponent(gvid)}/piece-guides`)\n      .then(async (res) => {\n        if (!res.ok) throw new Error(`status ${res.status}`);\n        return (await res.json()) as RawPieceGuidesResponse;\n      })\n      .then((raw) => {\n        if (!cancelled) setBundle(transformPieceGuides(raw));\n      })\n      .catch(() => {\n        // No guides is a degraded state, not a failure — the editor keeps\n        // working, the overlay just doesn't appear.\n        if (!cancelled) setBundle(null);\n      });\n    return () => {\n      cancelled = true;\n    };\n  }, [gvid, apiBase]);\n\n  return bundle;\n}\n"],"names":["PIECE_GUIDES_API_BASE","transformPieceGuides","raw","pieces","p","pieceGuidesForArtboard","bundle","artboard","process","usePieceGuideBundle","gvid","apiBase","setBundle","useState","useEffect","cancelled","res"],"mappings":";;AA6BO,MAAMA,IAAwB;AA8B9B,SAASC,EAAqBC,GAA+C;AAClF,QAAMC,IAAoCD,EAAI,OAAO,IAAI,CAACE,OAAO;AAAA,IAC/D,IAAIA,EAAE;AAAA,IACN,GAAGA,EAAE;AAAA,IACL,GAAGA,EAAE;AAAA,IACL,OAAOA,EAAE;AAAA,IACT,QAAQA,EAAE;AAAA,IACV,UAAU,OAAOA,EAAE,YAAa,WAAWA,EAAE,WAAW;AAAA,IACxD,iBACE,OAAOA,EAAE,uBAAwB,YAAYA,EAAE,sBAAsB,IACjEA,EAAE,sBAAsBF,EAAI,cAC5B;AAAA,EAAA,EACN;AACF,SAAO;AAAA,IACL,eAAeA,EAAI;AAAA,IACnB,gBAAgBA,EAAI;AAAA,IACpB,QAAQ;AAAA,MACN,QAAAC;AAAA,MACA,QAAQD,EAAI,eAAe,CAAA;AAAA,MAC3B,OAAOA,EAAI;AAAA,IAAA;AAAA,EACb;AAEJ;AASO,SAASG,EACdC,GACAC,GAC+B;;AAC/B,MAAKA,GACL;AAAA,QAAIA,EAAS,UAAUD,EAAO,iBAAiBC,EAAS,WAAWD,EAAO,gBAAgB;AACxF,MAAI,OAAOE,IAAY,SAAeA,IAAAA,EAAQ,QAARA,gBAAAA,EAAa,cAAa,gBAC9D,QAAQ;AAAA,QACN,uEACKF,EAAO,aAAa,IAAIA,EAAO,cAAc,mCAC7CC,EAAS,KAAK,IAAIA,EAAS,MAAM;AAAA,MAAA;AAI1C;AAAA,IACF;AACA,WAAOD,EAAO;AAAA;AAChB;AAMO,SAASG,EACdC,GACAC,IAAkBX,GACO;AACzB,QAAM,CAACM,GAAQM,CAAS,IAAIC,EAAkC,IAAI;AAElE,SAAAC,EAAU,MAAM;AACd,QAAI,CAACJ,GAAM;AACT,MAAAE,EAAU,IAAI;AACd;AAAA,IACF;AACA,QAAIG,IAAY;AAChB,iBAAM,GAAGJ,CAAO,uBAAuB,mBAAmBD,CAAI,CAAC,eAAe,EAC3E,KAAK,OAAOM,MAAQ;AACnB,UAAI,CAACA,EAAI,GAAI,OAAM,IAAI,MAAM,UAAUA,EAAI,MAAM,EAAE;AACnD,aAAQ,MAAMA,EAAI,KAAA;AAAA,IACpB,CAAC,EACA,KAAK,CAACd,MAAQ;AACb,MAAKa,KAAWH,EAAUX,EAAqBC,CAAG,CAAC;AAAA,IACrD,CAAC,EACA,MAAM,MAAM;AAGX,MAAKa,KAAWH,EAAU,IAAI;AAAA,IAChC,CAAC,GACI,MAAM;AACX,MAAAG,IAAY;AAAA,IACd;AAAA,EACF,GAAG,CAACL,GAAMC,CAAO,CAAC,GAEXL;AACT;"}

package/dist/utils/alignDistribute.d.ts

@@ -0,0 +1,41 @@
+import { BoundingBox } from '../types/index.js';
+/** Minimum number of movable elements for a distribute operation. */
+export declare const DISTRIBUTE_MIN_COUNT = 3;
+/** Minimum number of elements for aligning relative to the selection itself
+ *  (below this the caller should align relative to the artboard). */
+export declare const ALIGN_SELECTION_MIN_COUNT = 2;
+export type AlignMode = 'left' | 'center-h' | 'right' | 'top' | 'center-v' | 'bottom';
+export type DistributeMode = 'horizontal' | 'vertical';
+/** Geometry of one alignable element. `x`/`y` is the element's position
+ *  field (center point for canvas elements); `bbox` its conceptual
+ *  `getBoundingBox()` rect in the same world coordinates. */
+export interface AlignableItem {
+    id: string;
+    x: number;
+    y: number;
+    bbox: BoundingBox;
+}
+/** New value for an element's position field. */
+export interface PositionUpdate {
+    id: string;
+    x: number;
+    y: number;
+}
+/** Union of the items' bboxes. Returns null for an empty list. */
+export declare function combinedBounds(items: readonly AlignableItem[]): BoundingBox | null;
+/**
+ * Align every item's bbox to `frame` (the selection's combined bounds, or the
+ * artboard rect for a single element). Returns position updates ONLY for
+ * items that actually move, so callers can batch exactly the real changes.
+ */
+export declare function computeAlign(items: readonly AlignableItem[], mode: AlignMode, frame: BoundingBox): PositionUpdate[];
+/**
+ * Distribute items along one axis with EQUAL GAPS between bbox edges. The
+ * outermost items (first/last along the axis) stay put; everything between
+ * is repositioned. Requires at least {@link DISTRIBUTE_MIN_COUNT} items —
+ * with fewer there is nothing between the ends to distribute, so calling
+ * this is a contradiction and throws (`E_DISTRIBUTE_MIN_THREE`), never a
+ * silent no-op. UI callers must not render distribute affordances below the
+ * threshold (see `useAlignDistribute().canDistribute`).
+ */
+export declare function computeDistribute(items: readonly AlignableItem[], mode: DistributeMode): PositionUpdate[];