@pictor-sdk/ui 0.1.0 → 0.2.0

package/README.md

@@ -8,7 +8,7 @@ photo and video editor SDK for React Native. Public APIs are pre-1.0 and experim
 ## Install
 
 ```sh
-pnpm add @pictor-sdk/ui@0.1.0
+pnpm add @pictor-sdk/ui@0.2.0
 ```
 
 Install the package's declared peer dependencies in your app. Keep React, React Native,
@@ -21,6 +21,17 @@ of device verification on every supported version/platform.
 
 ## Documentation and contributing
 
+### Story Layout in 0.2.0
+
+Upgrade `@pictor-sdk/core`, `@pictor-sdk/skia` and `@pictor-sdk/ui` together.
+`layoutCellBounds('6grid')` supplies a two-column, three-row grid;
+`fitImageToLayoutCell(cell, document.size, intrinsic, { zoom, center })` returns
+the fixed-cell transform, source crop and `pixelSnap` flag. Apply all three in
+one history batch. Zoom and pan change the crop, not the layer's cell bounds.
+See the [host integration guide](https://github.com/zahidhasanaunto/pictor/blob/main/docs/STORY-LAYOUT.md).
+
+### Project links
+
 - [Repository and example app](https://github.com/zahidhasanaunto/pictor)
 - [Public API inventory](https://github.com/zahidhasanaunto/pictor/blob/main/docs/API-SURFACE.md)
 - [Release and contributor guide](https://github.com/zahidhasanaunto/pictor/blob/main/docs/RELEASING.md)

package/dist/index.d.mts

@@ -758,7 +758,7 @@ declare function LayersPanel(): React__default.JSX.Element;
 declare function LayoutPanel(): React__default.JSX.Element;
 
 /** The bundled multi-photo arrangements, by cell count and split direction. */
-type LayoutPreset = '1' | '2v' | '2h' | '3v' | '4grid';
+type LayoutPreset = '1' | '2v' | '2h' | '3v' | '4grid' | '6grid';
 /** One slot in a layout: where its photo sits, in normalized document units. */
 interface LayoutCell {
     /** centre + scale in normalized document units */
@@ -773,6 +773,38 @@ interface LayoutCell {
  * canvas size works.
  */
 declare function layoutCells(preset: LayoutPreset, _doc: Size): LayoutCell[];
+/**
+ * Axis-aligned cell rectangles, row-major, normalized to document width/height.
+ * x/y are TOP-LEFT coordinates, unlike the centres in legacy LayoutCell.
+ * Returns fresh rectangles; no document aspect ratio is assumed.
+ */
+declare function layoutCellBounds(preset: LayoutPreset): Rect[];
+/** Source-window controls; pan is a source-space crop centre, not a layer translation. */
+interface LayoutCropOptions {
+    /** Magnification relative to crop-to-fill. Clamped to [1, 32]; default 1. */
+    zoom?: number;
+    /** Desired source-normalized crop centre; clamped so the crop stays in the source. */
+    center?: {
+        x: number;
+        y: number;
+    };
+}
+/** Crop and complete transform to apply together in one history batch. */
+interface LayoutImageFit {
+    crop: Rect;
+    transform: Transform;
+    /** Apply to ImageLayerData together with crop for seam-free cell edges. */
+    pixelSnap: true;
+}
+/**
+ * Fill a fixed cell without bleed. Zoom/pan alter only the source crop, never
+ * the cell bounds. intrinsic must describe the decoded, orientation-corrected
+ * source. Recompute after source replacement or document resize.
+ * Throws RangeError for non-finite controls, invalid sizes or out-of-document cells.
+ * Apply transform with layer/transform and crop + pixelSnap with layer/patchData in one batch.
+ * General layer gestures must not subsequently move/rotate/scale a fixed cell.
+ */
+declare function fitImageToLayoutCell(cell: Rect, documentSize: Size, intrinsic: Size, options?: LayoutCropOptions): LayoutImageFit;
 /** The transform patch that moves a layer into a cell, leaving its other fields alone. */
 declare function cellToTransformPatch(cell: LayoutCell): Partial<Transform>;
 
@@ -830,4 +862,4 @@ declare function UiStateProvider({ children }: {
 /** Read and write one key of the ephemeral UI state. Throws outside an `<Editor>`. */
 declare function useUiState<T>(key: string, fallback: T): [T, (value: T) => void];
 
-export { type AddPhotoController, type AddPhotoControllerOptions, AddPhotoPanel, AdjustPanel, type BrushConfig, CanvasStage, type CanvasStageProps, CropGestureSurface, type CropGestureSurfaceProps, CropGrid, CropPanel, DEFAULT_BRUSH, type DrawController, DrawPanel, DrawingSurface, Editor, EditorGestures, type EditorGesturesProps, type EditorProps, type EditorSlots, type EditorTheme, FilterStrip, type GestureController, type GestureControllerOptions, type GestureMetrics, type GestureSnapEvent, type GestureSurfaceKind, type HostCallbacks, HostCallbacksProvider, InteractionGuides, type InteractionGuidesProps, InteractionProvider, InvalidImageResultError, LayerGestureSurface, type LayerGestureSurfaceProps, LayersPanel, type LayoutCell, LayoutPanel, type LayoutPreset, MediaPanel, type PartialTheme, STRAIGHTEN_LIMIT, Slider, type SliderProps, type StickerAsset, StickerPanel, StoryMediaGestureSurface, type StoryMediaGestureSurfaceProps, StraightenRuler, type StraightenRulerProps, TextComposer, TextComposerHost, type TextComposerProps, TextPanel, type TextSessionController, ThemeContext, ToolPanelHost, ToolRail, TopBar, type TopBarProps, UiStateProvider, type UiStateStore, type UseTextSessionOptions, canvasSizeForAspect, cellToTransformPatch, centeredCropForAspect, createAddPhotoController, createDrawController, createGestureController, createUiStateStore, defaultTheme, layoutCells, mergeSlots, mergeTheme, radiansToStraighten, resolveGestureSurface, resolvePanel, straightenToRadians, useBaseImageLayer, useBaseMediaLayer, useHostCallbacks, useInteractionState, useTargetImageLayer, useTextSession, useTheme, useUiState };
+export { type AddPhotoController, type AddPhotoControllerOptions, AddPhotoPanel, AdjustPanel, type BrushConfig, CanvasStage, type CanvasStageProps, CropGestureSurface, type CropGestureSurfaceProps, CropGrid, CropPanel, DEFAULT_BRUSH, type DrawController, DrawPanel, DrawingSurface, Editor, EditorGestures, type EditorGesturesProps, type EditorProps, type EditorSlots, type EditorTheme, FilterStrip, type GestureController, type GestureControllerOptions, type GestureMetrics, type GestureSnapEvent, type GestureSurfaceKind, type HostCallbacks, HostCallbacksProvider, InteractionGuides, type InteractionGuidesProps, InteractionProvider, InvalidImageResultError, LayerGestureSurface, type LayerGestureSurfaceProps, LayersPanel, type LayoutCell, type LayoutCropOptions, type LayoutImageFit, LayoutPanel, type LayoutPreset, MediaPanel, type PartialTheme, STRAIGHTEN_LIMIT, Slider, type SliderProps, type StickerAsset, StickerPanel, StoryMediaGestureSurface, type StoryMediaGestureSurfaceProps, StraightenRuler, type StraightenRulerProps, TextComposer, TextComposerHost, type TextComposerProps, TextPanel, type TextSessionController, ThemeContext, ToolPanelHost, ToolRail, TopBar, type TopBarProps, UiStateProvider, type UiStateStore, type UseTextSessionOptions, canvasSizeForAspect, cellToTransformPatch, centeredCropForAspect, createAddPhotoController, createDrawController, createGestureController, createUiStateStore, defaultTheme, fitImageToLayoutCell, layoutCellBounds, layoutCells, mergeSlots, mergeTheme, radiansToStraighten, resolveGestureSurface, resolvePanel, straightenToRadians, useBaseImageLayer, useBaseMediaLayer, useHostCallbacks, useInteractionState, useTargetImageLayer, useTextSession, useTheme, useUiState };

package/dist/index.d.ts

@@ -758,7 +758,7 @@ declare function LayersPanel(): React__default.JSX.Element;
 declare function LayoutPanel(): React__default.JSX.Element;
 
 /** The bundled multi-photo arrangements, by cell count and split direction. */
-type LayoutPreset = '1' | '2v' | '2h' | '3v' | '4grid';
+type LayoutPreset = '1' | '2v' | '2h' | '3v' | '4grid' | '6grid';
 /** One slot in a layout: where its photo sits, in normalized document units. */
 interface LayoutCell {
     /** centre + scale in normalized document units */
@@ -773,6 +773,38 @@ interface LayoutCell {
  * canvas size works.
  */
 declare function layoutCells(preset: LayoutPreset, _doc: Size): LayoutCell[];
+/**
+ * Axis-aligned cell rectangles, row-major, normalized to document width/height.
+ * x/y are TOP-LEFT coordinates, unlike the centres in legacy LayoutCell.
+ * Returns fresh rectangles; no document aspect ratio is assumed.
+ */
+declare function layoutCellBounds(preset: LayoutPreset): Rect[];
+/** Source-window controls; pan is a source-space crop centre, not a layer translation. */
+interface LayoutCropOptions {
+    /** Magnification relative to crop-to-fill. Clamped to [1, 32]; default 1. */
+    zoom?: number;
+    /** Desired source-normalized crop centre; clamped so the crop stays in the source. */
+    center?: {
+        x: number;
+        y: number;
+    };
+}
+/** Crop and complete transform to apply together in one history batch. */
+interface LayoutImageFit {
+    crop: Rect;
+    transform: Transform;
+    /** Apply to ImageLayerData together with crop for seam-free cell edges. */
+    pixelSnap: true;
+}
+/**
+ * Fill a fixed cell without bleed. Zoom/pan alter only the source crop, never
+ * the cell bounds. intrinsic must describe the decoded, orientation-corrected
+ * source. Recompute after source replacement or document resize.
+ * Throws RangeError for non-finite controls, invalid sizes or out-of-document cells.
+ * Apply transform with layer/transform and crop + pixelSnap with layer/patchData in one batch.
+ * General layer gestures must not subsequently move/rotate/scale a fixed cell.
+ */
+declare function fitImageToLayoutCell(cell: Rect, documentSize: Size, intrinsic: Size, options?: LayoutCropOptions): LayoutImageFit;
 /** The transform patch that moves a layer into a cell, leaving its other fields alone. */
 declare function cellToTransformPatch(cell: LayoutCell): Partial<Transform>;
 
@@ -830,4 +862,4 @@ declare function UiStateProvider({ children }: {
 /** Read and write one key of the ephemeral UI state. Throws outside an `<Editor>`. */
 declare function useUiState<T>(key: string, fallback: T): [T, (value: T) => void];
 
-export { type AddPhotoController, type AddPhotoControllerOptions, AddPhotoPanel, AdjustPanel, type BrushConfig, CanvasStage, type CanvasStageProps, CropGestureSurface, type CropGestureSurfaceProps, CropGrid, CropPanel, DEFAULT_BRUSH, type DrawController, DrawPanel, DrawingSurface, Editor, EditorGestures, type EditorGesturesProps, type EditorProps, type EditorSlots, type EditorTheme, FilterStrip, type GestureController, type GestureControllerOptions, type GestureMetrics, type GestureSnapEvent, type GestureSurfaceKind, type HostCallbacks, HostCallbacksProvider, InteractionGuides, type InteractionGuidesProps, InteractionProvider, InvalidImageResultError, LayerGestureSurface, type LayerGestureSurfaceProps, LayersPanel, type LayoutCell, LayoutPanel, type LayoutPreset, MediaPanel, type PartialTheme, STRAIGHTEN_LIMIT, Slider, type SliderProps, type StickerAsset, StickerPanel, StoryMediaGestureSurface, type StoryMediaGestureSurfaceProps, StraightenRuler, type StraightenRulerProps, TextComposer, TextComposerHost, type TextComposerProps, TextPanel, type TextSessionController, ThemeContext, ToolPanelHost, ToolRail, TopBar, type TopBarProps, UiStateProvider, type UiStateStore, type UseTextSessionOptions, canvasSizeForAspect, cellToTransformPatch, centeredCropForAspect, createAddPhotoController, createDrawController, createGestureController, createUiStateStore, defaultTheme, layoutCells, mergeSlots, mergeTheme, radiansToStraighten, resolveGestureSurface, resolvePanel, straightenToRadians, useBaseImageLayer, useBaseMediaLayer, useHostCallbacks, useInteractionState, useTargetImageLayer, useTextSession, useTheme, useUiState };
+export { type AddPhotoController, type AddPhotoControllerOptions, AddPhotoPanel, AdjustPanel, type BrushConfig, CanvasStage, type CanvasStageProps, CropGestureSurface, type CropGestureSurfaceProps, CropGrid, CropPanel, DEFAULT_BRUSH, type DrawController, DrawPanel, DrawingSurface, Editor, EditorGestures, type EditorGesturesProps, type EditorProps, type EditorSlots, type EditorTheme, FilterStrip, type GestureController, type GestureControllerOptions, type GestureMetrics, type GestureSnapEvent, type GestureSurfaceKind, type HostCallbacks, HostCallbacksProvider, InteractionGuides, type InteractionGuidesProps, InteractionProvider, InvalidImageResultError, LayerGestureSurface, type LayerGestureSurfaceProps, LayersPanel, type LayoutCell, type LayoutCropOptions, type LayoutImageFit, LayoutPanel, type LayoutPreset, MediaPanel, type PartialTheme, STRAIGHTEN_LIMIT, Slider, type SliderProps, type StickerAsset, StickerPanel, StoryMediaGestureSurface, type StoryMediaGestureSurfaceProps, StraightenRuler, type StraightenRulerProps, TextComposer, TextComposerHost, type TextComposerProps, TextPanel, type TextSessionController, ThemeContext, ToolPanelHost, ToolRail, TopBar, type TopBarProps, UiStateProvider, type UiStateStore, type UseTextSessionOptions, canvasSizeForAspect, cellToTransformPatch, centeredCropForAspect, createAddPhotoController, createDrawController, createGestureController, createUiStateStore, defaultTheme, fitImageToLayoutCell, layoutCellBounds, layoutCells, mergeSlots, mergeTheme, radiansToStraighten, resolveGestureSurface, resolvePanel, straightenToRadians, useBaseImageLayer, useBaseMediaLayer, useHostCallbacks, useInteractionState, useTargetImageLayer, useTextSession, useTheme, useUiState };

package/dist/index.js

@@ -73,6 +73,8 @@ __export(index_exports, {
   createGestureController: () => createGestureController,
   createUiStateStore: () => createUiStateStore,
   defaultTheme: () => defaultTheme,
+  fitImageToLayoutCell: () => fitImageToLayoutCell,
+  layoutCellBounds: () => layoutCellBounds,
   layoutCells: () => layoutCells,
   mergeSlots: () => mergeSlots,
   mergeTheme: () => mergeTheme,
@@ -2829,38 +2831,70 @@ var import_react_native16 = require("react-native");
 
 // src/panels/layoutMath.ts
 function layoutCells(preset, _doc) {
-  switch (preset) {
-    case "1":
-      return [{ x: 0.5, y: 0.5, scale: 1 }];
-    case "2v":
-      return [
-        { x: 0.5, y: 0.25, scale: 1 },
-        { x: 0.5, y: 0.75, scale: 1 }
-      ];
-    case "2h":
-      return [
-        { x: 0.25, y: 0.5, scale: 0.5 },
-        { x: 0.75, y: 0.5, scale: 0.5 }
-      ];
-    case "3v":
-      return [
-        { x: 0.5, y: 1 / 6, scale: 1 },
-        { x: 0.5, y: 0.5, scale: 1 },
-        { x: 0.5, y: 5 / 6, scale: 1 }
-      ];
-    case "4grid":
-      return [
-        { x: 0.25, y: 0.25, scale: 0.5 },
-        { x: 0.75, y: 0.25, scale: 0.5 },
-        { x: 0.25, y: 0.75, scale: 0.5 },
-        { x: 0.75, y: 0.75, scale: 0.5 }
-      ];
-    default: {
-      const _exhaustive = preset;
-      void _exhaustive;
-      return [{ x: 0.5, y: 0.5, scale: 1 }];
+  return layoutCellBounds(preset).map((cell) => ({
+    x: (cell.x / cell.width + 0.5) * cell.width,
+    y: (cell.y / cell.height + 0.5) * cell.height,
+    scale: cell.width
+  }));
+}
+function layoutCellBounds(preset) {
+  const dimensions = {
+    "1": [1, 1],
+    "2v": [1, 2],
+    "2h": [2, 1],
+    "3v": [1, 3],
+    "4grid": [2, 2],
+    "6grid": [2, 3]
+  };
+  const grid = dimensions[preset];
+  if (!grid) throw new RangeError("Unknown layout preset");
+  const [columns, rows] = grid;
+  return Array.from({ length: columns * rows }, (_, index) => ({
+    x: index % columns / columns,
+    y: Math.floor(index / columns) / rows,
+    width: 1 / columns,
+    height: 1 / rows
+  }));
+}
+function fitImageToLayoutCell(cell, documentSize, intrinsic, options = {}) {
+  for (const size of [documentSize, intrinsic]) {
+    if (![size.width, size.height].every((v) => Number.isFinite(v) && v > 0)) {
+      throw new RangeError("Layout sizes must be finite and positive");
     }
   }
+  if (![cell.x, cell.y, cell.width, cell.height].every(Number.isFinite) || cell.x < 0 || cell.y < 0 || cell.width <= 0 || cell.height <= 0 || cell.x + cell.width > 1 + 1e-12 || cell.y + cell.height > 1 + 1e-12) {
+    throw new RangeError("Layout cell must lie inside the document");
+  }
+  const zoom = options.zoom ?? 1;
+  const center = options.center ?? { x: 0.5, y: 0.5 };
+  if (![zoom, center.x, center.y].every(Number.isFinite)) {
+    throw new RangeError("Layout controls must be finite");
+  }
+  const base = centeredCropForAspect(
+    intrinsic,
+    cell.width * documentSize.width / (cell.height * documentSize.height)
+  );
+  const factor = Math.max(1, Math.min(32, zoom));
+  const width = base.width / factor;
+  const height = base.height / factor;
+  return {
+    pixelSnap: true,
+    crop: {
+      x: Math.max(0, Math.min(1 - width, center.x - width / 2)),
+      y: Math.max(0, Math.min(1 - height, center.y - height / 2)),
+      width,
+      height
+    },
+    transform: {
+      x: cell.x + cell.width / 2,
+      y: cell.y + cell.height / 2,
+      scale: cell.width,
+      rotation: 0,
+      anchor: { x: 0.5, y: 0.5 },
+      flipX: false,
+      flipY: false
+    }
+  };
 }
 function cellToTransformPatch(cell) {
   return { x: cell.x, y: cell.y, scale: cell.scale, rotation: 0 };
@@ -2873,17 +2907,23 @@ var PRESETS = [
   { id: "2v", label: "2 rows" },
   { id: "2h", label: "2 cols" },
   { id: "3v", label: "3 rows" },
-  { id: "4grid", label: "Grid" }
+  { id: "4grid", label: "Grid" },
+  { id: "6grid", label: "6 grid" }
 ];
 function LayoutPanel() {
   const { document, dispatch } = (0, import_core18.useEditor)();
   const theme = useTheme();
   const apply = (preset) => {
-    const cells = layoutCells(preset, document.size);
+    const cells = layoutCellBounds(preset);
     const images = document.layers.filter((l) => l.type === "image");
+    const fits = images.slice(0, cells.length).map((layer, i) => ({
+      layer,
+      fit: fitImageToLayoutCell(cells[i], document.size, layer.data.intrinsic)
+    }));
     dispatch({ type: "history/beginBatch", label: "layout" });
-    images.slice(0, cells.length).forEach((layer, i) => {
-      dispatch({ type: "layer/transform", id: layer.id, patch: cellToTransformPatch(cells[i]) });
+    fits.forEach(({ layer, fit }) => {
+      dispatch({ type: "layer/transform", id: layer.id, patch: fit.transform });
+      dispatch({ type: "layer/patchData", id: layer.id, patch: { crop: fit.crop, pixelSnap: fit.pixelSnap } });
     });
     dispatch({ type: "history/endBatch" });
   };
@@ -4601,6 +4641,8 @@ function TextPanel() {
   createGestureController,
   createUiStateStore,
   defaultTheme,
+  fitImageToLayoutCell,
+  layoutCellBounds,
   layoutCells,
   mergeSlots,
   mergeTheme,