@pictor-sdk/ui 0.1.0

package/src/gestures/routing.ts

@@ -0,0 +1,42 @@
+/**
+ * Which gesture surface owns the canvas.
+ *
+ * Precedence is decided by the active tool and nothing else, so it is a pure
+ * function that can be tested without mounting anything — and so the rule is
+ * stated in one place rather than implied by JSX nesting.
+ */
+export type GestureSurfaceKind = 'media' | 'draw' | 'crop' | 'tilt' | 'text' | 'overlay'
+
+/**
+ * Resolve the surface for the active tool.
+ *
+ * - `text` — the full-screen composer owns the screen, so **no** canvas surface
+ *   is mounted at all. Not mounting is the strongest form of "disabled": there
+ *   is no recogniser to arbitrate with, so a tap meant for the caret cannot
+ *   start a canvas gesture, and a drag begins immediately once composing ends.
+ * - `media` — the base photo tool owns the surface, so the photo moves and
+ *   overlays are inert.
+ * - `draw` — drawing owns the surface, so strokes are never interpreted as
+ *   layer drags.
+ * - `crop` — the Post crop surface.
+ * - `tilt` — placing the selective-focus region, which needs the whole canvas;
+ *   overlay hit-testing would steal the drag to whatever sits under the finger.
+ * - anything else (including no active tool) — overlay hit-testing, which
+ *   excludes the base photo, so dragging text or a sticker cannot move it.
+ */
+export function resolveGestureSurface(activeTool: string | null | undefined): GestureSurfaceKind {
+  switch (activeTool) {
+    case 'text':
+      return 'text'
+    case 'media':
+      return 'media'
+    case 'draw':
+      return 'draw'
+    case 'crop':
+      return 'crop'
+    case 'tilt':
+      return 'tilt'
+    default:
+      return 'overlay'
+  }
+}

package/src/gestures/settleCoordinator.ts

@@ -0,0 +1,61 @@
+/**
+ * Coordinates the settle animation and the single document write that follows
+ * it.
+ *
+ * Committing *while* the animation runs is the trap: the commit changes the
+ * document, which re-seeds the live shared values from the committed
+ * transform, which cancels the animation that was still running. So the commit
+ * has to happen when the animation reports completion, not when it is started.
+ *
+ * Kept pure — the animator and the commit are injected — so the ordering rules
+ * below are unit-testable without Reanimated:
+ *
+ * - a settle commits exactly once, when its animation finishes;
+ * - an animation that is interrupted commits nothing;
+ * - a newer settle supersedes an older one, so a late completion from the
+ *   superseded animation cannot commit stale values;
+ * - `cancel()` (tool dismissed, unmount) prevents any pending commit.
+ */
+export interface SettleAnimation {
+  /** Run the animation; call `done(true)` on completion, `done(false)` if interrupted. */
+  (done: (finished: boolean) => void): void
+}
+
+export interface SettleCoordinator<T> {
+  /** Animate toward `target`, committing it when the animation completes. */
+  settle(target: T, animate: SettleAnimation): void
+  /** Abandon any settle in flight without committing. */
+  cancel(): void
+  /** True while an animation is running and its commit is still pending. */
+  isSettling(): boolean
+}
+
+export function createSettleCoordinator<T>(commit: (target: T) => void): SettleCoordinator<T> {
+  // Monotonic token: only the newest settle may commit. Cancelling bumps it too,
+  // so a completion callback that arrives afterwards is ignored.
+  let generation = 0
+  let settling = false
+
+  return {
+    settle(target, animate) {
+      generation += 1
+      const mine = generation
+      settling = true
+      animate((finished) => {
+        if (mine !== generation) return // superseded, cancelled, or already resolved
+        generation += 1 // one completion per settle, whatever the animator does
+        settling = false
+        if (finished) commit(target)
+      })
+    },
+
+    cancel() {
+      generation += 1
+      settling = false
+    },
+
+    isSettling() {
+      return settling
+    },
+  }
+}

package/src/gestures/transformOwnership.ts

@@ -0,0 +1,91 @@
+import { isSameTransform, type Transform } from '@pictor-sdk/core'
+
+/**
+ * Who owns a layer's live transform: the gesture surface, or the document.
+ *
+ * The surface drives `live*` shared values while a gesture or its settle runs,
+ * and the canvas draws them as a delta from the transform the document holds.
+ * The handover back to the document is the delicate part, and getting it wrong
+ * is visible as a single-frame flash:
+ *
+ * - release ownership when `dispatch` is *called* and the resync can fire while
+ *   the document still holds the old transform, snapping `live` back to it for
+ *   one frame;
+ * - never release it and an undo or a Cancel cannot reseed `live` at all.
+ *
+ * So ownership ends when the document actually reports the transform that was
+ * committed — not before. Until then `live` is already correct and must be left
+ * alone. Pure and synchronous, so the ordering is unit-testable.
+ */
+export interface OwnershipState {
+  /** True while the surface, not the document, decides the transform. */
+  owning: boolean
+  /** A transform dispatched but not yet observed on the document. */
+  pending: Transform | null
+  /**
+   * What the document held when `pending` was dispatched.
+   *
+   * Needed to tell "our commit has not landed yet" from "something else
+   * changed the document": both merely differ from `pending`, and only the
+   * second should reseed.
+   */
+  previous: Transform | null
+}
+
+export const IDLE_OWNERSHIP: OwnershipState = { owning: false, pending: null, previous: null }
+
+/** A gesture or animation takes the transform. */
+export function beginOwnership(): OwnershipState {
+  return { owning: true, pending: null, previous: null }
+}
+
+/**
+ * The surface committed `target`.
+ *
+ * `dispatched` is false when the commit was a no-op — the transform never
+ * changed, so no document update is coming and ownership ends immediately.
+ */
+export function commitOwnership(
+  target: Transform,
+  dispatched: boolean,
+  previous?: Transform,
+): OwnershipState {
+  return dispatched
+    ? { owning: true, pending: target, previous: previous ?? null }
+    : IDLE_OWNERSHIP
+}
+
+export interface DocumentChange {
+  state: OwnershipState
+  /** Whether `live*` should be reseeded from the document. */
+  reseed: boolean
+}
+
+/**
+ * The document's transform for this layer changed, or the effect re-ran.
+ *
+ * Reseeding is for changes the surface did not make — undo, Cancel, a new
+ * photo. A change the surface itself dispatched needs no reseed: `live` is
+ * already sitting on exactly that value, and rewriting it is what introduces
+ * the flash.
+ */
+export function documentChanged(
+  state: OwnershipState,
+  committed: Transform | undefined,
+): DocumentChange {
+  if (!committed) return { state, reseed: false }
+  if (state.pending) {
+    // our commit landed: `live` is already on it, so hand back without touching
+    if (isSameTransform(state.pending, committed)) return { state: IDLE_OWNERSHIP, reseed: false }
+    // the document still holds what it did when we dispatched — the update has
+    // simply not rendered yet. Reseeding here is the one-frame flash.
+    if (state.previous && isSameTransform(state.previous, committed)) {
+      return { state, reseed: false }
+    }
+    // anything else means something outside changed the document first; that
+    // wins, and our pending commit is stale
+    return { state: IDLE_OWNERSHIP, reseed: true }
+  }
+  if (state.owning) return { state, reseed: false }
+  return { state, reseed: true }
+}

package/src/hostCallbacks.tsx

@@ -0,0 +1,62 @@
+import { type InsertableImage } from '@pictor-sdk/core'
+import React, { createContext, useContext, useRef } from 'react'
+
+/**
+ * Callbacks the host supplies to `<Editor>` that panels deep in the tree need.
+ *
+ * Held in a **ref** rather than state. A callback prop is usually an inline
+ * arrow recreated every render, so storing it in state would notify on every
+ * render and re-render forever; consumers read `.current` at call time instead
+ * and never re-render because the host re-created its closure.
+ *
+ * @experimental
+ */
+export interface HostCallbacks {
+  /**
+   * Asked to supply photos when the user presses the add-photo control.
+   *
+   * The library never touches the gallery itself: permissions, the picker and
+   * any HEIC/HEIF transcoding are the host's, which is what keeps the library
+   * free of Expo and of native code. Resolve `null` or `[]` for cancellation.
+   */
+  requestImages?: () => Promise<readonly InsertableImage[] | null>
+  /** Where a failed request is reported. */
+  onError?: (error: unknown) => void
+}
+
+const Context = createContext<{ current: HostCallbacks } | null>(null)
+
+/**
+ * Makes the host's callbacks reachable from panels deep in the tree.
+ *
+ * Mounted by `<Editor>`; a host composing its own editor from slots mounts it
+ * itself, or omits it and the controls render unavailable.
+ *
+ * @experimental
+ */
+export function HostCallbacksProvider({
+  value,
+  children,
+}: {
+  value: HostCallbacks
+  children?: React.ReactNode
+}) {
+  const ref = useRef<HostCallbacks>(value)
+  // Updated during render on purpose: a panel that calls one of these in the
+  // same commit must see the latest, and an effect would be a frame late.
+  ref.current = value
+  return <Context.Provider value={ref}>{children}</Context.Provider>
+}
+
+/**
+ * The host's callbacks, as a stable ref.
+ *
+ * Returns an empty set outside an `<Editor>` rather than throwing — a panel
+ * rendered standalone should degrade to "unavailable", not crash.
+ *
+ * @experimental
+ */
+export function useHostCallbacks(): { current: HostCallbacks } {
+  const fallback = useRef<HostCallbacks>({})
+  return useContext(Context) ?? fallback
+}

package/src/index.ts

@@ -0,0 +1,72 @@
+export { Editor, CanvasStage, mergeSlots, type CanvasStageProps, type EditorProps, type EditorSlots } from './Editor'
+export { TopBar, type TopBarProps } from './components/TopBar'
+export { ToolRail } from './components/ToolRail'
+export { ToolPanelHost, resolvePanel } from './ToolPanelHost'
+export { FilterStrip, useBaseImageLayer } from './panels/FilterStrip'
+export { useTargetImageLayer } from './panels/useTargetImageLayer'
+export { AddPhotoPanel } from './panels/AddPhotoPanel'
+export {
+  createAddPhotoController,
+  InvalidImageResultError,
+  type AddPhotoController,
+  type AddPhotoControllerOptions,
+} from './panels/addPhotoController'
+export { HostCallbacksProvider, useHostCallbacks, type HostCallbacks } from './hostCallbacks'
+export { AdjustPanel } from './panels/AdjustPanel'
+export { CropPanel } from './panels/CropPanel'
+export {
+  canvasSizeForAspect,
+  centeredCropForAspect,
+  radiansToStraighten,
+  straightenToRadians,
+  STRAIGHTEN_LIMIT,
+} from './panels/cropMath'
+export { Slider, type SliderProps } from './components/Slider'
+export { StraightenRuler, type StraightenRulerProps } from './components/StraightenRuler'
+export { defaultTheme, mergeTheme, useTheme, ThemeContext, type EditorTheme, type PartialTheme } from './theme'
+export { EditorGestures, type EditorGesturesProps } from './gestures/EditorGestures'
+export { LayerGestureSurface, type LayerGestureSurfaceProps } from './gestures/LayerGestureSurface'
+export { InteractionGuides, type InteractionGuidesProps } from './gestures/InteractionGuides'
+export {
+  StoryMediaGestureSurface,
+  useBaseMediaLayer,
+  type StoryMediaGestureSurfaceProps,
+} from './gestures/StoryMediaGestureSurface'
+export { resolveGestureSurface, type GestureSurfaceKind } from './gestures/routing'
+export { MediaPanel } from './panels/MediaPanel'
+// The worklet twins, the slider's detent maths, the built-in panel registry and
+// the composer's keyboard arithmetic stay internal. Unlike the panels and
+// surfaces above — which exist to be picked apart, so their broad surface is
+// deliberate — these describe how one component is wired, and a consumer
+// replacing that component replaces the wiring too. Their tests import by path.
+export { CropGestureSurface, type CropGestureSurfaceProps } from './gestures/CropGestureSurface'
+export { CropGrid } from './gestures/CropGrid'
+export { InteractionProvider, useInteractionState } from './gestures/interactionState'
+export {
+  createGestureController,
+  type GestureController,
+  type GestureControllerOptions,
+  type GestureMetrics,
+  type GestureSnapEvent,
+} from './gestures/controller'
+// Convenience re-exports so consumers of the default UI need one import
+export { POST_PROFILE, STORY_PROFILE } from '@pictor-sdk/core'
+export {
+  TextComposer,
+  TextComposerHost,
+  type TextComposerProps,
+} from './composer/TextComposer'
+export {
+  useTextSession,
+  type TextSessionController,
+  type UseTextSessionOptions,
+} from './composer/useTextSession'
+export { TextPanel } from './panels/TextPanel'
+export { DrawPanel } from './panels/DrawPanel'
+export { StickerPanel, type StickerAsset } from './panels/StickerPanel'
+export { LayersPanel } from './panels/LayersPanel'
+export { LayoutPanel } from './panels/LayoutPanel'
+export { layoutCells, cellToTransformPatch, type LayoutCell, type LayoutPreset } from './panels/layoutMath'
+export { DrawingSurface, DEFAULT_BRUSH } from './gestures/DrawingSurface'
+export { createDrawController, type BrushConfig, type DrawController } from './gestures/drawController'
+export { UiStateProvider, useUiState, createUiStateStore, type UiStateStore } from './uiState'

package/src/panels/AddPhotoPanel.tsx

@@ -0,0 +1,101 @@
+import { useEditor } from '@pictor-sdk/core'
+import React, { useEffect, useMemo, useState } from 'react'
+import { Pressable, Text, View } from 'react-native'
+import { useHostCallbacks } from '../hostCallbacks'
+import { useTheme } from '../theme'
+import { createAddPhotoController } from './addPhotoController'
+
+/**
+ * The add-photo control: one press, one picker, one undo entry.
+ *
+ * Nothing happens on mount. Opening a picker because a panel appeared would
+ * take the choice away from the user and make a stray tool tap launch the
+ * gallery, so acquisition waits for an explicit press.
+ *
+ * All the asynchronous behaviour lives in `createAddPhotoController`, which is
+ * testable without mounting anything. This is the shell.
+ *
+ * @experimental
+ */
+export function AddPhotoPanel() {
+  const { dispatch, select } = useEditor()
+  const host = useHostCallbacks()
+  const theme = useTheme()
+  const [pending, setPending] = useState(false)
+
+  const controller = useMemo(
+    () =>
+      createAddPhotoController({
+        // Read through the ref at call time, so a host re-creating its closure
+        // does not rebuild the controller mid-request.
+        requestImages: host.current.requestImages
+          ? () => host.current.requestImages!()
+          : undefined,
+        dispatch,
+        select,
+        onError: (error) => host.current.onError?.(error),
+      }),
+    [dispatch, select, host],
+  )
+
+  // Disposal is what makes a late result harmless: the picker can resolve long
+  // after the user has closed the tool.
+  useEffect(() => () => controller.dispose(), [controller])
+
+  // Session-scoped, like the panel's image target: whether a picker exists is
+  // decided at mount. A host that wires `requestImages` while this is open sees
+  // it on the next open.
+  const available = controller.isAvailable()
+
+  const press = async () => {
+    if (!available || pending) return
+    setPending(true)
+    try {
+      await controller.request()
+    } finally {
+      setPending(false)
+    }
+  }
+
+  return (
+    <View style={{ backgroundColor: theme.colors.background, padding: theme.spacing.lg }}>
+      <Pressable
+        accessibilityRole="button"
+        accessibilityLabel="Add photos"
+        accessibilityState={{ disabled: !available || pending }}
+        disabled={!available || pending}
+        onPress={press}
+        style={{
+          paddingVertical: theme.spacing.md,
+          borderRadius: theme.radii.sm,
+          borderWidth: 1,
+          borderColor: available ? theme.colors.accent : theme.colors.track,
+          alignItems: 'center',
+          opacity: available && !pending ? 1 : 0.45,
+        }}
+      >
+        <Text
+          style={{
+            color: available ? theme.colors.accent : theme.colors.textMuted,
+            fontSize: theme.font.size,
+            fontWeight: theme.font.weight,
+          }}
+        >
+          {pending ? 'Choosing…' : 'Add photos'}
+        </Text>
+      </Pressable>
+      <Text
+        style={{
+          color: theme.colors.textMuted,
+          fontSize: theme.font.sizeSm,
+          textAlign: 'center',
+          marginTop: theme.spacing.sm,
+        }}
+      >
+        {available
+          ? 'Pick one or more photos to place on the story'
+          : `Unavailable — pass \`requestImages\` to <Editor>`}
+      </Text>
+    </View>
+  )
+}

package/src/panels/AdjustPanel.tsx

@@ -0,0 +1,158 @@
+import {
+  adjustmentResetPatch,
+  hasAdjustment,
+  useEditor,
+  useEditorStore,
+  type Adjustments,
+  type ImageLayerData,
+} from '@pictor-sdk/core'
+import React, { useState } from 'react'
+import { Pressable, ScrollView, Text, View } from 'react-native'
+import { useTheme } from '../theme'
+import { Slider } from '../components/Slider'
+import { useTargetImageLayer } from './useTargetImageLayer'
+
+const LABELS: Record<string, string> = {
+  brightness: 'Brightness',
+  contrast: 'Contrast',
+  saturation: 'Saturation',
+  warmth: 'Warmth',
+  tint: 'Tint',
+  exposure: 'Exposure',
+  highlights: 'Highlights',
+  shadows: 'Shadows',
+  fade: 'Fade',
+  structure: 'Structure',
+  sharpen: 'Sharpen',
+  grain: 'Grain',
+  vignette: 'Vignette',
+}
+
+/**
+ * The Adjust tab: the 13 tools from profile/registry order, one centred
+ * slider with a detent at 0 (a 0 adjustment is a provable render no-op).
+ */
+export function AdjustPanel() {
+  const { dispatch } = useEditor()
+  const store = useEditorStore()
+  const theme = useTheme()
+  const layer = useTargetImageLayer()
+  const keys = store.registry.adjustments
+  const [activeKey, setActiveKey] = useState(keys[0] ?? 'brightness')
+
+  if (!layer) return null
+  const adjustments: Adjustments = (layer.data as ImageLayerData).color.adjustments ?? {}
+  const value = adjustments[activeKey] ?? 0
+  const touchedActive = hasAdjustment(adjustments, activeKey)
+
+  /**
+   * Clear the active adjustment, and only it.
+   *
+   * No batch of its own: the adjust tool session already opened one, so this
+   * belongs to that session's single undo entry — Cancel rolls it back with
+   * everything else, and Done commits it as part of the whole.
+   */
+  const resetActive = () =>
+    dispatch({
+      type: 'layer/patchData',
+      id: layer.id,
+      patch: adjustmentResetPatch(activeKey) as Record<string, unknown>,
+    })
+
+  return (
+    <View style={{ backgroundColor: theme.colors.background }}>
+      <View style={{ paddingHorizontal: theme.spacing.lg }}>
+        {/* Value readout, with an inline reset once the adjustment is set —
+            the affordance Instagram uses, and the one the milestone asks for:
+            it clears this adjustment only. */}
+        <View
+          style={{
+            flexDirection: 'row',
+            alignItems: 'center',
+            justifyContent: 'center',
+            gap: theme.spacing.sm,
+            minHeight: 28,
+          }}
+        >
+          <Text
+            style={{
+              color: theme.colors.textMuted,
+              textAlign: 'center',
+              fontSize: theme.font.sizeSm,
+            }}
+          >
+            {LABELS[activeKey] ?? activeKey}{' '}
+            {value === 0 ? '' : (value > 0 ? '+' : '') + Math.round(value * 100)}
+          </Text>
+          {touchedActive ? (
+            <Pressable
+              accessibilityRole="button"
+              accessibilityLabel={`Reset ${LABELS[activeKey] ?? activeKey}`}
+              onPress={resetActive}
+              hitSlop={8}
+              style={{
+                paddingHorizontal: theme.spacing.sm,
+                paddingVertical: 2,
+                borderRadius: theme.radii.sm,
+                borderWidth: 1,
+                borderColor: theme.colors.track,
+              }}
+            >
+              <Text style={{ color: theme.colors.text, fontSize: theme.font.sizeSm }}>Reset</Text>
+            </Pressable>
+          ) : null}
+        </View>
+        <Slider
+          value={value}
+          min={-1}
+          max={1}
+          centered
+          valueLabel={`${value > 0 ? '+' : ''}${Math.round(value * 100)}`}
+          onStart={() => dispatch({ type: 'history/beginBatch', label: activeKey })}
+          onChange={(v) =>
+            dispatch({
+              type: 'layer/patchData',
+              id: layer.id,
+              patch: { color: { adjustments: { [activeKey]: v } } },
+            })
+          }
+          onEnd={() => dispatch({ type: 'history/endBatch' })}
+        />
+      </View>
+      <ScrollView
+        horizontal
+        showsHorizontalScrollIndicator={false}
+        contentContainerStyle={{ gap: theme.spacing.sm, padding: theme.spacing.md }}
+        style={{ flexGrow: 0 }}
+      >
+        {keys.map((key) => {
+          const touched = (adjustments[key] ?? 0) !== 0
+          const active = key === activeKey
+          return (
+            <Pressable
+              key={key}
+              onPress={() => setActiveKey(key)}
+              style={{ alignItems: 'center', gap: 6, width: 76 }}
+            >
+              <View style={{ width: 48, height: 48, borderRadius: 24, borderWidth: 1, borderColor: active ? theme.colors.accent : theme.colors.textMuted, backgroundColor: active ? theme.colors.surface : 'transparent', alignItems: 'center', justifyContent: 'center' }}>
+                <Text style={{ color: active ? theme.colors.accent : theme.colors.text, fontSize: 18 }}>
+                  {(LABELS[key] ?? key).slice(0, 1)}
+                </Text>
+              </View>
+              <Text
+                style={{
+                  color: active ? theme.colors.accent : touched ? theme.colors.text : theme.colors.textMuted,
+                  fontSize: theme.font.sizeSm,
+                  fontWeight: theme.font.weight,
+                }}
+              >
+                {LABELS[key] ?? key}
+                {touched ? ' •' : ''}
+              </Text>
+            </Pressable>
+          )
+        })}
+      </ScrollView>
+    </View>
+  )
+}