@pictor-sdk/ui 0.1.0

package/src/panels/TextPanel.tsx

@@ -0,0 +1,177 @@
+import {
+  createId,
+  useEditor,
+  useEditorStore,
+  type TextLayerData,
+  type TextSpan,
+} from '@pictor-sdk/core'
+import React from 'react'
+import { Pressable, ScrollView, Text, TextInput, View } from 'react-native'
+import { useTheme } from '../theme'
+import { Slider } from '../components/Slider'
+
+const SWATCHES = ['#ffffff', '#000000', '#ed4956', '#ffe25c', '#78de85', '#4dc4ff', '#a15fed']
+const ALIGNS = ['left', 'center', 'right'] as const
+const FILL_MODES = [undefined, 'solid', 'perLine'] as const
+
+/**
+ * Text tab: add a text layer, then edit the selected one — content, font,
+ * size, color, alignment, and the fill treatment (solid / per-line
+ * @experimental). Editing happens in the panel for v0.2; DECISION:
+ * on-canvas edit-in-place needs a native text-input overlay pass, deferred.
+ */
+export function TextPanel() {
+  const { document, selection, dispatch, select } = useEditor()
+  const store = useEditorStore()
+  const theme = useTheme()
+
+  const selected = document.layers.find(
+    (l) => l.type === 'text' && selection.includes(l.id),
+  )
+  const data = selected ? (selected.data as TextLayerData) : null
+  const span: TextSpan | null = data?.spans[0] ?? null
+
+  const addText = () => {
+    const id = createId('text')
+    dispatch({
+      type: 'layer/add',
+      layer: {
+        id,
+        type: 'text',
+        transform: { x: 0.5, y: 0.4, scale: 1, rotation: 0 },
+        opacity: 1,
+        blendMode: 'normal',
+        data: {
+          spans: [{ text: 'Tap to edit', fontFamily: 'System', fontSize: 0.07, color: '#ffffff' }],
+          align: 'center',
+          maxWidth: 0.9,
+        } satisfies TextLayerData,
+      },
+    })
+    select([id])
+  }
+
+  const patchSpan = (patch: Partial<TextSpan>) => {
+    if (!selected || !span) return
+    dispatch({
+      type: 'layer/patchData',
+      id: selected.id,
+      patch: { spans: [{ ...span, ...patch }, ...(data!.spans.slice(1) ?? [])] },
+    })
+  }
+
+  const fonts = ['System', ...store.registry.fonts.map((f) => f.family)]
+
+  if (!selected || !span || !data) {
+    return (
+      <View style={{ backgroundColor: theme.colors.background, padding: theme.spacing.md, alignItems: 'center' }}>
+        <Pressable
+          onPress={addText}
+          style={{
+            paddingHorizontal: theme.spacing.lg,
+            paddingVertical: theme.spacing.sm,
+            borderRadius: theme.radii.md,
+            backgroundColor: theme.colors.surface,
+          }}
+        >
+          <Text style={{ color: theme.colors.accent, fontSize: theme.font.size, fontWeight: theme.font.weight }}>
+            + Add text
+          </Text>
+        </Pressable>
+      </View>
+    )
+  }
+
+  const cycleAlign = () => {
+    const next = ALIGNS[(ALIGNS.indexOf(data.align) + 1) % ALIGNS.length]!
+    dispatch({ type: 'layer/patchData', id: selected.id, patch: { align: next } })
+  }
+
+  const cycleFill = () => {
+    const current = data.fill?.mode
+    const index = FILL_MODES.indexOf(current as (typeof FILL_MODES)[number])
+    const next = FILL_MODES[(index + 1) % FILL_MODES.length]
+    dispatch({
+      type: 'layer/patchData',
+      id: selected.id,
+      patch: {
+        fill: next
+          ? { color: span.color === '#000000' ? '#ffffff' : '#000000', radius: 0.012, padding: 0.012, mode: next }
+          : undefined,
+      },
+    })
+  }
+
+  return (
+    <View style={{ backgroundColor: theme.colors.background }}>
+      <View style={{ paddingHorizontal: theme.spacing.md }}>
+        <TextInput
+          value={span.text}
+          onChangeText={(text) => patchSpan({ text })}
+          multiline
+          placeholder="Your text"
+          placeholderTextColor={theme.colors.textMuted}
+          style={{
+            color: theme.colors.text,
+            backgroundColor: theme.colors.surface,
+            borderRadius: theme.radii.sm,
+            padding: theme.spacing.sm,
+            fontSize: theme.font.size,
+          }}
+        />
+        <Slider
+          value={span.fontSize}
+          min={0.02}
+          max={0.2}
+          centered={false}
+          onStart={() => dispatch({ type: 'history/beginBatch', label: 'font size' })}
+          onChange={(fontSize) => patchSpan({ fontSize })}
+          onEnd={() => dispatch({ type: 'history/endBatch' })}
+        />
+      </View>
+      <ScrollView
+        horizontal
+        showsHorizontalScrollIndicator={false}
+        contentContainerStyle={{ gap: theme.spacing.sm, paddingHorizontal: theme.spacing.md, alignItems: 'center', paddingBottom: theme.spacing.sm }}
+        style={{ flexGrow: 0 }}
+      >
+        <Pressable onPress={cycleAlign} style={{ padding: theme.spacing.sm }}>
+          <Text style={{ color: theme.colors.text, fontWeight: theme.font.weight }}>
+            {data.align === 'left' ? '⇤' : data.align === 'center' ? '☰' : '⇥'}
+          </Text>
+        </Pressable>
+        <Pressable onPress={cycleFill} style={{ padding: theme.spacing.sm }}>
+          <Text style={{ color: data.fill ? theme.colors.accent : theme.colors.text, fontWeight: theme.font.weight }}>
+            {data.fill?.mode === 'perLine' ? 'A⃞⃞' : 'A⃞'}
+          </Text>
+        </Pressable>
+        {fonts.map((family) => (
+          <Pressable key={family} onPress={() => patchSpan({ fontFamily: family })} style={{ padding: theme.spacing.sm }}>
+            <Text
+              style={{
+                color: span.fontFamily === family ? theme.colors.accent : theme.colors.textMuted,
+                fontSize: theme.font.sizeSm,
+              }}
+            >
+              {family}
+            </Text>
+          </Pressable>
+        ))}
+        {SWATCHES.map((color) => (
+          <Pressable
+            key={color}
+            onPress={() => patchSpan({ color })}
+            style={{
+              width: 24,
+              height: 24,
+              borderRadius: 12,
+              backgroundColor: color,
+              borderWidth: span.color === color ? 3 : 1,
+              borderColor: span.color === color ? theme.colors.accent : theme.colors.track,
+            }}
+          />
+        ))}
+      </ScrollView>
+    </View>
+  )
+}

package/src/panels/TiltShiftPanel.tsx

@@ -0,0 +1,146 @@
+import {
+  createTiltShift,
+  needsTiltShift,
+  tiltShiftPatch,
+  useEditor,
+  MAX_TILT_BLUR,
+  MAX_TILT_FEATHER,
+  MAX_TILT_RADIUS,
+  type ImageLayerData,
+  type TiltShift,
+} from '@pictor-sdk/core'
+import React from 'react'
+import { Pressable, Text, View } from 'react-native'
+import { Slider } from '../components/Slider'
+import { useTheme } from '../theme'
+import { useTargetImageLayer } from './useTargetImageLayer'
+
+/**
+ * Selective focus: Off · Radial · Linear, then the shape of the region.
+ *
+ * The mode row is explicit rather than implied by a non-zero blur, because the
+ * research pass measured it that way and because "off" needs to be reachable
+ * without dragging a slider back to exactly zero.
+ *
+ * Position and size are set by dragging on the canvas, not here — see
+ * `TiltShiftGestureSurface`. The sliders cover what a gesture cannot express.
+ */
+
+const MODES = [
+  { key: 'off', label: 'Off' },
+  { key: 'radial', label: 'Radial' },
+  { key: 'linear', label: 'Linear' },
+] as const
+
+export function TiltShiftPanel() {
+  const { dispatch } = useEditor()
+  const theme = useTheme()
+  const layer = useTargetImageLayer()
+
+  if (!layer) return null
+  const data = layer.data as ImageLayerData
+  const tilt = needsTiltShift(data.tiltShift) ? data.tiltShift! : undefined
+  const mode = tilt?.mode ?? 'off'
+
+  const patch = (next: TiltShift | undefined) =>
+    dispatch({
+      type: 'layer/patchData',
+      id: layer.id,
+      patch: tiltShiftPatch(next) as unknown as Record<string, unknown>,
+    })
+
+  /**
+   * Switching mode keeps the region where the user put it.
+   *
+   * Only the shape changes; re-centring on every mode tap would throw away
+   * positioning work for no reason.
+   */
+  const setMode = (key: (typeof MODES)[number]['key']) => {
+    if (key === 'off') return patch(undefined)
+    patch(tilt ? { ...tilt, mode: key } : createTiltShift(key))
+  }
+
+  const set = (over: Partial<TiltShift>) => tilt && patch({ ...tilt, ...over })
+
+  const sliders: Array<{ key: keyof TiltShift; label: string; max: number }> = [
+    { key: 'blur', label: 'Blur', max: MAX_TILT_BLUR },
+    { key: 'radius', label: 'Size', max: MAX_TILT_RADIUS },
+    { key: 'feather', label: 'Feather', max: MAX_TILT_FEATHER },
+  ]
+
+  return (
+    <View style={{ backgroundColor: theme.colors.background, paddingBottom: theme.spacing.md }}>
+      <View
+        style={{
+          flexDirection: 'row',
+          justifyContent: 'center',
+          gap: theme.spacing.md,
+          paddingVertical: theme.spacing.sm,
+        }}
+      >
+        {MODES.map(({ key, label }) => {
+          const selected = key === mode
+          return (
+            <Pressable
+              key={key}
+              accessibilityRole="button"
+              accessibilityLabel={`Tilt shift ${label.toLowerCase()}`}
+              onPress={() => setMode(key)}
+              style={{
+                paddingHorizontal: theme.spacing.md,
+                paddingVertical: 6,
+                borderRadius: theme.radii.sm,
+                borderWidth: 1,
+                borderColor: selected ? theme.colors.accent : theme.colors.track,
+              }}
+            >
+              <Text
+                style={{
+                  color: selected ? theme.colors.accent : theme.colors.textMuted,
+                  fontSize: theme.font.sizeSm,
+                  fontWeight: theme.font.weight,
+                }}
+              >
+                {label}
+              </Text>
+            </Pressable>
+          )
+        })}
+      </View>
+
+      <View style={{ paddingHorizontal: theme.spacing.lg }}>
+        <Text
+          style={{
+            color: theme.colors.textMuted,
+            textAlign: 'center',
+            fontSize: theme.font.sizeSm,
+            minHeight: 20,
+          }}
+        >
+          {tilt ? 'Drag on the photo to place the focus' : 'Off'}
+        </Text>
+        {sliders.map(({ key, label, max }) => {
+          const value = (tilt?.[key] as number | undefined) ?? 0
+          return (
+            <View key={key}>
+              <Text style={{ color: theme.colors.textMuted, fontSize: theme.font.sizeSm }}>
+                {label} {tilt ? Math.round((value / max) * 100) : ''}
+              </Text>
+              <Slider
+                value={value}
+                min={0}
+                max={max}
+                centered={false}
+                testID={`tilt-${key}`}
+                disabled={!tilt}
+                onStart={() => dispatch({ type: 'history/beginBatch', label: `tilt-${key}` })}
+                onChange={(v) => set({ [key]: v } as Partial<TiltShift>)}
+                onEnd={() => dispatch({ type: 'history/endBatch' })}
+              />
+            </View>
+          )
+        })}
+      </View>
+    </View>
+  )
+}

package/src/panels/addPhotoController.ts

@@ -0,0 +1,196 @@
+import {
+  createImageLayers,
+  insertImageCommands,
+  type Dispatch,
+  type InsertableImage,
+  type InsertImageOptions,
+  type InsertImageTransaction,
+} from '@pictor-sdk/core'
+
+/**
+ * Acquiring photos from the host, then inserting them.
+ *
+ * Deliberately **not** a React component. Acquisition is asynchronous and has
+ * to survive a re-render, refuse a second request while one is in flight, and
+ * do nothing at all if the panel is gone by the time the host answers — none of
+ * which is expressible as render logic, and all of which is worth testing
+ * without mounting anything.
+ *
+ * Acquisition is also kept separate from insertion so a host that wants neither
+ * this controller nor the default panel can call `createImageLayers` and
+ * `insertImageCommands` directly.
+ *
+ * @experimental
+ */
+
+export interface AddPhotoControllerOptions {
+  /**
+   * Supplied by the host. Resolving `null` or `[]` means the user cancelled,
+   * which must add nothing — no command, no selection change, no history entry.
+   */
+  requestImages?: () => Promise<readonly InsertableImage[] | null>
+  dispatch: Dispatch
+  select: (ids: string[]) => void
+  /** Anything the host's picker throws, or a result that is not usable. */
+  onError?: (error: unknown) => void
+  /** Presentation and transaction options forwarded to the core helpers. */
+  insert?: InsertImageOptions & InsertImageTransaction
+}
+
+/**
+ * A live add-photo session.
+ *
+ * @experimental
+ */
+export interface AddPhotoController {
+  /** Ask the host for photos and insert whatever comes back. */
+  request: () => Promise<void>
+  /** True while a request is in flight; a second press is ignored. */
+  isPending: () => boolean
+  /**
+   * Whether the host supplied a way to ask at all.
+   *
+   * **Session-scoped.** Captured when the controller is created, which for the
+   * bundled panel means when it mounts. A host that adds `requestImages` while
+   * the panel is open sees it unavailable until the tool is reopened — the
+   * mount is the session boundary everywhere else in this panel too, and a
+   * control that becomes live mid-session is a stranger surprise than one that
+   * waits for the next open.
+   */
+  isAvailable: () => boolean
+  /** Called when the panel unmounts: a late result is then discarded. */
+  dispose: () => void
+}
+
+/** An entry the library can actually insert. */
+function isInsertable(value: unknown): value is InsertableImage {
+  if (typeof value !== 'object' || value === null) return false
+  const source = (value as { source?: unknown }).source
+  // `source` is deliberately `unknown` in the document model — a URI, a
+  // `{ uri }`, a Metro asset id — so the only thing worth asserting is that the
+  // host gave us *something* to resolve.
+  return source !== undefined && source !== null && source !== ''
+}
+
+/**
+ * A dense list of insertable images, or `null` if the result is unusable.
+ *
+ * Every index is checked with `in` rather than by iterating, because a sparse
+ * array **skips its holes**: `new Array(3).every(fn)` is `true`, so a host
+ * returning one would pass validation and go on to produce sparse layers and a
+ * command list with `undefined` in it — dispatching `history/beginBatch` and
+ * then failing part-way, leaving a batch open.
+ *
+ * Copied into a dense array before anything is constructed, so nothing
+ * downstream has to think about holes again.
+ */
+function toDenseImages(value: unknown): InsertableImage[] | null {
+  if (!Array.isArray(value)) return null
+  const dense: InsertableImage[] = []
+  for (let index = 0; index < value.length; index++) {
+    if (!(index in value)) return null
+    const entry = value[index]
+    if (!isInsertable(entry)) return null
+    dense.push(entry)
+  }
+  return dense
+}
+
+/** A command the reducer could actually accept. */
+function isDispatchable(command: unknown): boolean {
+  return (
+    typeof command === 'object' &&
+    command !== null &&
+    typeof (command as { type?: unknown }).type === 'string'
+  )
+}
+
+/**
+ * The host resolved with something that is not a list of insertable images.
+ *
+ * Reported rather than coerced: guessing at a malformed result would insert
+ * layers the host did not mean to add.
+ *
+ * @experimental
+ */
+export class InvalidImageResultError extends Error {
+  constructor() {
+    super('requestImages resolved with something that is not a list of images')
+    this.name = 'InvalidImageResultError'
+  }
+}
+
+/**
+ * Wire a host's picker to the core insertion helpers.
+ *
+ * Acquisition stays separate from insertion, so a host that wants neither this
+ * controller nor the default panel can call `createImageLayers` and
+ * `insertImageCommands` itself.
+ *
+ * @experimental
+ */
+export function createAddPhotoController({
+  requestImages,
+  dispatch,
+  select,
+  onError,
+  insert,
+}: AddPhotoControllerOptions): AddPhotoController {
+  let pending = false
+  let disposed = false
+
+  return {
+    isPending: () => pending,
+    isAvailable: () => typeof requestImages === 'function',
+    dispose: () => {
+      disposed = true
+    },
+    async request() {
+      // A second press while the picker is open must not open a second picker,
+      // and must not ask the host twice for one intent.
+      if (!requestImages || pending || disposed) return
+      pending = true
+      try {
+        const result = await requestImages()
+        // Disposal is checked *first*, before the result is even looked at.
+        // Once the panel is gone the user has moved on, so nothing that comes
+        // back matters — not a success, not a malformed result, and not an
+        // error worth interrupting them about.
+        if (disposed) return
+        // Cancellation. Not an error, and nothing to do.
+        if (result === null || result === undefined) return
+
+        const images = toDenseImages(result)
+        if (!images) {
+          onError?.(new InvalidImageResultError())
+          return
+        }
+        if (images.length === 0) return
+
+        // Everything is built and checked before the *first* dispatch, so a
+        // problem discovered late cannot leave a `beginBatch` open with no
+        // matching end.
+        const layers = createImageLayers(images, insert)
+        const commands = insertImageCommands(layers, insert)
+        if (!commands.every(isDispatchable)) {
+          onError?.(new InvalidImageResultError())
+          return
+        }
+
+        for (const command of commands) dispatch(command)
+        // Only the last — the topmost photo, and the one the user ends up
+        // looking at. Selecting all of them would invite a bulk edit that is
+        // not designed.
+        const last = layers[layers.length - 1]
+        if (last) select([last.id])
+      } catch (error) {
+        // Same rule as a late success: after disposal, silence.
+        if (!disposed) onError?.(error)
+      } finally {
+        // Cleared even after a failure, so reopening — or simply pressing
+        // again — can try once more.
+        pending = false
+      }
+    },
+  }
+}

package/src/panels/cropMath.ts

@@ -0,0 +1,37 @@
+import { type Rect, type Size } from '@pictor-sdk/core'
+
+/**
+ * Pure crop math for the Crop tool (unit-tested in Node).
+ *
+ * Aspect selection: the document canvas takes the chosen aspect (constant
+ * width) and the image layer gets a maximal centred crop matching it.
+ */
+export function canvasSizeForAspect(current: Size, aspect: number | 'free'): Size {
+  if (aspect === 'free') return current
+  return { width: current.width, height: Math.round(current.width / aspect) }
+}
+
+/** Maximal centred crop (normalized within the source) with the given aspect. */
+export function centeredCropForAspect(intrinsic: Size, aspect: number): Rect {
+  const sourceAspect = intrinsic.width / intrinsic.height
+  if (sourceAspect > aspect) {
+    // source is wider → crop the sides
+    const width = aspect / sourceAspect
+    return { x: (1 - width) / 2, y: 0, width, height: 1 }
+  }
+  // source is taller → crop top/bottom
+  const height = sourceAspect / aspect
+  return { x: 0, y: (1 - height) / 2, width: 1, height }
+}
+
+/** The straighten dial's range: ±45°, in radians. */
+export const STRAIGHTEN_LIMIT = (45 * Math.PI) / 180
+
+/** Straighten dial value (-1..1) ↔ radians (±45°). */
+export function straightenToRadians(value: number): number {
+  return Math.max(-1, Math.min(1, value)) * STRAIGHTEN_LIMIT
+}
+/** Radians to dial value (-1..1), clamped to the limit. */
+export function radiansToStraighten(rad: number): number {
+  return Math.max(-1, Math.min(1, rad / STRAIGHTEN_LIMIT))
+}

package/src/panels/layoutMath.ts

@@ -0,0 +1,58 @@
+import { type Size, type Transform } from '@pictor-sdk/core'
+
+/** The bundled multi-photo arrangements, by cell count and split direction. */
+export type LayoutPreset = '1' | '2v' | '2h' | '3v' | '4grid'
+
+/** One slot in a layout: where its photo sits, in normalized document units. */
+export interface LayoutCell {
+  /** centre + scale in normalized document units */
+  x: number
+  y: number
+  /** width of the cell as a fraction of document width */
+  scale: number
+}
+
+/**
+ * Story layout grids: cell centres and scales for placing the first N image
+ * layers. Pure — unit tested. Cells are defined as document fractions so any
+ * canvas size works.
+ */
+export function layoutCells(preset: LayoutPreset, _doc: Size): LayoutCell[] {
+  switch (preset) {
+    case '1':
+      return [{ x: 0.5, y: 0.5, scale: 1 }]
+    case '2v': // two rows
+      return [
+        { x: 0.5, y: 0.25, scale: 1 },
+        { x: 0.5, y: 0.75, scale: 1 },
+      ]
+    case '2h': // two columns
+      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: never = preset
+      void _exhaustive
+      return [{ x: 0.5, y: 0.5, scale: 1 }]
+    }
+  }
+}
+
+/** The transform patch that moves a layer into a cell, leaving its other fields alone. */
+export function cellToTransformPatch(cell: LayoutCell): Partial<Transform> {
+  return { x: cell.x, y: cell.y, scale: cell.scale, rotation: 0 }
+}

package/src/panels/useTargetImageLayer.ts

@@ -0,0 +1,41 @@
+import {
+  pinnedTargetImageLayer,
+  resolveTargetImageLayer,
+  useEditor,
+  type Layer,
+} from '@pictor-sdk/core'
+import { useRef } from 'react'
+
+/**
+ * The image an open panel edits, **pinned for the whole session**.
+ *
+ * Resolved once, from the selection at the moment the panel mounts, and then
+ * held by id. `ToolPanelHost` mounts a fresh panel per tool activation, so a
+ * mount *is* a session, and closing and reopening resolves again.
+ *
+ * The pinning is the point. Re-resolving each render would let a selection
+ * change mid-drag redirect the next slider movement to a different photo — an
+ * edit landing silently on the wrong image, which is worse than an edit that
+ * does nothing. So when the target is deleted, locked or hidden mid-session
+ * this returns `null` and the panel disables its controls; it never quietly
+ * falls back to the base.
+ *
+ * `useBaseImageLayer` is unchanged and still means *the base photo*. Use it
+ * where a capability is genuinely base-only — Story media layout, the derived
+ * background — rather than by inertia.
+ *
+ * @experimental
+ */
+export function useTargetImageLayer(): Layer | null {
+  const { document, selection } = useEditor()
+  const pinned = useRef<string | null>(null)
+
+  // Resolved on the first render of this mount and never again. A ref rather
+  // than an effect: an effect would leave the first render targeting nothing,
+  // and a panel that renders once with no target flashes disabled controls.
+  if (pinned.current === null) {
+    pinned.current = resolveTargetImageLayer(document, selection)?.id ?? null
+  }
+
+  return pinnedTargetImageLayer(document, pinned.current) ?? null
+}