@pictor-sdk/ui 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pictor-sdk/ui",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Default slot-based editor UI for Pictor, built entirely on the public headless API.",
   "license": "MIT",
   "sideEffects": false,
@@ -33,8 +33,8 @@
     "react-native-gesture-handler": ">=2.20.0",
     "react-native-reanimated": ">=3.16.0",
     "react-native-worklets": ">=0.5.1",
-    "@pictor-sdk/core": "^0.2.0",
-    "@pictor-sdk/skia": "^0.3.0"
+    "@pictor-sdk/core": "^0.3.0",
+    "@pictor-sdk/skia": "^0.4.0"
   },
   "devDependencies": {
     "@shopify/react-native-skia": "^2.0.0",
@@ -44,8 +44,8 @@
     "react-native-gesture-handler": "^2.28.0",
     "react-native-reanimated": "^4.1.0",
     "react-native-worklets": "0.5.1",
-    "@pictor-sdk/core": "0.2.0",
-    "@pictor-sdk/skia": "0.3.0"
+    "@pictor-sdk/skia": "0.4.0",
+    "@pictor-sdk/core": "0.3.0"
   },
   "publishConfig": {
     "access": "public",

package/src/components/Slider.tsx

@@ -60,8 +60,9 @@ export function Slider({
   valueRef.current = value
 
   const onLayout = (e: LayoutChangeEvent) => {
-    setWidth(e.nativeEvent.layout.width)
-    widthRef.current = e.nativeEvent.layout.width
+    const next = e.nativeEvent.layout.width
+    widthRef.current = next
+    setWidth((previous) => (previous === next ? previous : next))
   }
 
   const handlers = useMemo(() => {

package/src/composer/TextComposer.tsx

@@ -17,17 +17,25 @@ import {
   TextInput,
   View,
   type TextInputSelectionChangeEventData,
+  type TextLayoutEventData,
+  type TextStyle,
   type NativeSyntheticEvent,
 } from 'react-native'
 import { Slider } from '../components/Slider'
 import { useTheme } from '../theme'
 import { useRenderer } from '@pictor-sdk/skia'
 import {
+  composerCaretBox,
   composerInputBox,
+  composerInputOpacity,
   composerInsets,
   HIDDEN_KEYBOARD,
+  sameCaretLine,
+  type CanvasRect,
+  type CaretLine,
   type ComposerInsets,
 } from './keyboardLayout'
+import { pressMoved } from './tapGesture'
 import { useTextSession, type TextSessionController } from './useTextSession'
 
 const SWATCHES = ['#ffffff', '#000000', '#ed4956', '#ffe25c', '#78de85', '#4dc4ff', '#a15fed']
@@ -60,6 +68,11 @@ export interface TextComposerProps {
   onDone(): void
   /** Abandon, restoring the document. */
   onCancel(): void
+  /**
+   * The canvas rectangle in this composer's coordinates, when the host draws a
+   * cover canvas. Omitted, the composer assumes a centred contain fit.
+   */
+  canvas?: CanvasRect
 }
 
 /**
@@ -70,13 +83,15 @@ export interface TextComposerProps {
  * `renderDocument` — so what is on screen while composing is what exports.
  *
  * The `TextInput` itself is invisible and stretched over the canvas: it owns
- * the caret, the platform selection handles and the IME, while the *visible*
- * text is the real Skia layer underneath. That is what keeps preview and export
- * identical without giving up native text editing.
+ * focus and the IME, while the *visible* text is the real Skia layer
+ * underneath. On Android the platform paints composing glyphs black regardless
+ * of the input's colour, so the input is fully hidden and a caret is drawn at
+ * the measured selection instead. That is what keeps preview and export
+ * identical without giving up text editing.
  *
  * @experimental
  */
-export function TextComposer({ session, insets, onDone, onCancel }: TextComposerProps) {
+export function TextComposer({ session, insets, onDone, onCancel, canvas }: TextComposerProps) {
   const theme = useTheme()
   const store = useEditorStore()
   const { document } = useEditor()
@@ -88,6 +103,8 @@ export function TextComposer({ session, insets, onDone, onCancel }: TextComposer
   const [selectionRange, setSelectionRange] = useState<{ start: number; end: number } | undefined>(
     undefined,
   )
+  const [focused, setFocused] = useState(false)
+  const [caretLine, setCaretLine] = useState<CaretLine | null>(null)
 
   const data = session.data
   const span = session.span
@@ -107,7 +124,14 @@ export function TextComposer({ session, insets, onDone, onCancel }: TextComposer
       setMeasured(null)
       return
     }
-    const refresh = () => setMeasured(renderer.textMeasures.get(layerId) ?? null)
+    const refresh = () => {
+      const next = renderer.textMeasures.get(layerId) ?? null
+      setMeasured((previous) =>
+        previous && next && previous.width === next.width && previous.height === next.height
+          ? previous
+          : next,
+      )
+    }
     const unsubscribe = renderer.textMeasures.subscribe(refresh)
     refresh()
     return unsubscribe
@@ -133,6 +157,7 @@ export function TextComposer({ session, insets, onDone, onCancel }: TextComposer
         centerY: session.layer?.transform.y ?? 0.42,
         measured,
         lines: session.value.split('\n').length,
+        ...(canvas ? { canvas } : {}),
       }),
     [
       container,
@@ -142,6 +167,7 @@ export function TextComposer({ session, insets, onDone, onCancel }: TextComposer
       session.layer?.transform.y,
       session.value,
       measured,
+      canvas,
     ],
   )
   const fonts = useMemo(() => fontChoices(store.registry.fonts), [store.registry.fonts])
@@ -149,17 +175,68 @@ export function TextComposer({ session, insets, onDone, onCancel }: TextComposer
   // Focus once the overlay is up. A frame's delay lets the mount settle so the
   // keyboard animates in rather than appearing half-drawn.
   useEffect(() => {
-    const handle = setTimeout(() => input.current?.focus(), 50)
+    const handle = setTimeout(() => {
+      input.current?.focus()
+      // Opening an existing layer should put the caret after its text, not at
+      // the start, which is what an untouched native input defaults to.
+      if (session.kind === 'existing' && session.value.length > 0) {
+        const end = session.value.length
+        setSelectionRange({ start: end, end })
+        input.current?.setNativeProps({ selection: { start: end, end } })
+      }
+    }, 50)
     return () => clearTimeout(handle)
+    // Once, when the session opens; later value changes come from typing.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [])
 
   const onSelectionChange = useCallback(
     (event: NativeSyntheticEvent<TextInputSelectionChangeEventData>) => {
-      setSelectionRange(event.nativeEvent.selection)
+      const next = event.nativeEvent.selection
+      setSelectionRange((previous) =>
+        previous && previous.start === next.start && previous.end === next.end
+          ? previous
+          : next,
+      )
     },
     [],
   )
 
+  const caretAt = selectionRange?.end ?? session.value.length
+  const caretSource = session.value.slice(0, Math.max(0, caretAt))
+
+  /*
+    Measure where the caret belongs.
+
+    The hidden input cannot draw its own caret on Android without also drawing
+    its glyphs, so the visible caret is an overlay. A second, fully transparent
+    Text holds everything before the selection with the same font, size, width
+    and alignment as the input. React Native reports the laid-out lines; the end
+    of the last one is the caret position. This tracks wrapping and every
+    alignment because the platform is doing the layout, not an estimate here.
+  */
+  const onCaretLayout = useCallback((event: NativeSyntheticEvent<TextLayoutEventData>) => {
+    const lines = event.nativeEvent.lines
+    const last = lines[lines.length - 1]
+    const next = last
+      ? { x: last.x, y: last.y, width: last.width, height: last.height }
+      : null
+    /*
+      Layout events can fire again after the state update they cause. Returning
+      the previous object for an unchanged measurement lets React bail out;
+      always allocating a new one re-rendered the composer from inside its own
+      layout pass and reached "Maximum update depth exceeded" after a size
+      change.
+    */
+    setCaretLine((previous) => (sameCaretLine(previous, next) ? previous : next))
+  }, [])
+
+  const caret = composerCaretBox(layout, caretLine)
+  const letterSpacing =
+    span?.letterSpacing && span.fontSize > 0
+      ? (span.letterSpacing * layout.fontSize) / span.fontSize
+      : undefined
+
   /**
    * Apply a style without disturbing the caret.
    *
@@ -247,6 +324,16 @@ export function TextComposer({ session, insets, onDone, onCancel }: TextComposer
     return () => subscription.remove()
   }, [onCancel, insets.keyboardVisible])
 
+  /*
+    A tap, with the movement measured ourselves.
+
+    Pressable alone can report a press after a short move, and the canvas is
+    exactly where a person drags. The touch-down point is kept and the release
+    point compared: past eight points this was a drag, so it does not finish the
+    session.
+  */
+  const tapStart = useRef<{ x: number; y: number } | null>(null)
+
   const controlRow = {
     flexDirection: 'row' as const,
     alignItems: 'center' as const,
@@ -271,13 +358,73 @@ export function TextComposer({ session, insets, onDone, onCancel }: TextComposer
         style={{ position: 'absolute', left: 0, right: 0, top: 0, bottom: 0, backgroundColor: '#00000055' }}
       />
 
-      {/* The invisible editing surface. The visible glyphs are the Skia layer
-          underneath; this owns the caret, selection handles and IME. */}
+      {/*
+        Empty canvas finishes editing.
+
+        The input and the controls are later siblings, so they sit above this
+        and still receive their own touches. A measured drag leaves the session open.
+      */}
+      <Pressable
+        accessible
+        collapsable={false}
+        accessibilityRole="button"
+        accessibilityLabel="Finish editing text"
+        onAccessibilityTap={onDone}
+        onPressIn={(event) => {
+          tapStart.current = {
+            x: event.nativeEvent.pageX,
+            y: event.nativeEvent.pageY,
+          }
+        }}
+        onPress={(event) => {
+          const start = tapStart.current
+          const end = { x: event.nativeEvent.pageX, y: event.nativeEvent.pageY }
+          if (!pressMoved(start, end)) onDone()
+        }}
+        style={{ position: 'absolute', left: 0, right: 0, top: 0, bottom: 0 }}
+      />
+
+      {/*
+        Caret measurement. Transparent and non-interactive; it never exports
+        and never duplicates a glyph, because it is painted at zero opacity.
+      */}
+      <Text
+        key={`${caretSource}:${caretAt}`}
+        accessible={false}
+        importantForAccessibility="no-hide-descendants"
+        pointerEvents="none"
+        onTextLayout={onCaretLayout}
+        style={{
+          position: 'absolute',
+          left: layout.left,
+          width: layout.width,
+          top: layout.top,
+          height: layout.height,
+          opacity: 0,
+          fontSize: layout.fontSize,
+          lineHeight: layout.lineHeight,
+          fontFamily: span?.fontFamily,
+          fontWeight: span?.fontWeight
+            ? (`${span.fontWeight}` as TextStyle['fontWeight'])
+            : undefined,
+          letterSpacing,
+          textAlign: data?.align ?? 'center',
+          padding: 0,
+        }}
+      >
+        {`${caretSource}\u200B`}
+      </Text>
+
+      {/* The editing surface. Its glyphs are hidden on Android because the IME
+          paints composing text black regardless of colour; the Skia layer is
+          the only visible copy. It still owns focus, selection and the IME. */}
       <TextInput
         ref={input}
         value={session.value}
         onChangeText={session.setValue}
         onSelectionChange={onSelectionChange}
+        onFocus={() => setFocused(true)}
+        onBlur={() => setFocused(false)}
         multiline
         // Enter inserts a newline. Without this, a submit blurs the input and
         // the session ends on the first line break the user types.
@@ -309,6 +456,7 @@ export function TextComposer({ session, insets, onDone, onCancel }: TextComposer
           // rgba rather than the 'transparent' keyword because the keyword is
           // not reliably honoured for TextInput colour on Android.
           color: 'rgba(0,0,0,0)',
+          opacity: composerInputOpacity(Platform.OS),
           fontSize: layout.fontSize,
           lineHeight: layout.lineHeight,
           textAlign: data?.align ?? 'center',
@@ -321,6 +469,25 @@ export function TextComposer({ session, insets, onDone, onCancel }: TextComposer
         cursorColor={theme.colors.accent}
       />
 
+      {/* Android hides the native caret with the input, so draw the replacement
+          at the measured end of the text before the selection. Preview-only; it
+          is not inside renderDocument. */}
+      {focused && caret ? (
+        <View
+          pointerEvents="none"
+          accessible={false}
+          style={{
+            position: 'absolute',
+            left: caret.left,
+            top: caret.top,
+            width: caret.width,
+            height: caret.height,
+            borderRadius: caret.width / 2,
+            backgroundColor: theme.colors.accent,
+          }}
+        />
+      ) : null}
+
       {/* Top bar: Cancel / Done, below the status bar and any notch. */}
       <View
         style={{
@@ -510,6 +677,7 @@ export function TextComposer({ session, insets, onDone, onCancel }: TextComposer
 export function TextComposerHost({
   Composer = TextComposer,
   safeArea,
+  canvas,
 }: {
   /** Replace the default composer without replacing the canvas or editor. */
   Composer?: React.ComponentType<TextComposerProps>
@@ -521,6 +689,8 @@ export function TextComposerHost({
    * its bar at the very top, which on a device with a notch means under one.
    */
   safeArea?: { top?: number; bottom?: number }
+  /** The canvas rectangle, for a host that draws a cover canvas. */
+  canvas?: CanvasRect
 }) {
   const { setActiveTool } = useEditor()
   const session = useTextSession()
@@ -574,6 +744,7 @@ export function TextComposerHost({
       insets={insets}
       onDone={() => finish(true)}
       onCancel={() => finish(false)}
+      {...(canvas ? { canvas } : {})}
     />
   )
 }

package/src/composer/keyboardLayout.ts

@@ -157,6 +157,15 @@ export interface InputBoxRequest {
   measured?: Box | null
   /** Lines in the value — the estimate used until a measurement arrives. */
   lines: number
+  /**
+   * The canvas rectangle, when the host already knows it.
+   *
+   * A host that draws a *cover* canvas (a story filling the screen, with the
+   * sides clipped) cannot use a contain fit here: the glyphs would sit one
+   * inset below the caret. Such a host passes the rectangle it draws into.
+   * Omitted means contain, which is what the bare editor does.
+   */
+  canvas?: CanvasRect
 }
 
 export interface InputBox extends CanvasRect {
@@ -179,7 +188,11 @@ export interface InputBox extends CanvasRect {
  * the line count is the estimate, which is exact until a line wraps.
  */
 export function composerInputBox(request: InputBoxRequest): InputBox {
-  const canvas = fitCanvasRect(request.container, request.document)
+  const provided = request.canvas
+  const canvas =
+    provided && provided.width > 0 && provided.height > 0
+      ? provided
+      : fitCanvasRect(request.container, request.document)
   const fontSize = Math.max(1, request.fontSize * canvas.width)
   const lineHeight = Math.max(1, fontSize * request.lineHeight)
 
@@ -211,3 +224,83 @@ export function composerInputBox(request: InputBoxRequest): InputBox {
     lineHeight,
   }
 }
+
+/** A line rectangle as React Native's `onTextLayout` reports it, in dp. */
+export interface CaretLine {
+  x: number
+  y: number
+  width: number
+  height: number
+}
+
+/**
+ * Whether two layout reports describe the same caret line.
+ *
+ * `onTextLayout` can fire again after the state update it causes. The composer
+ * uses this to return the previous object for an unchanged line, so React can
+ * bail out instead of re-rendering from inside its own layout pass.
+ */
+export function sameCaretLine(previous: CaretLine | null, next: CaretLine | null): boolean {
+  return (
+    previous === next ||
+    (previous !== null &&
+      next !== null &&
+      previous.x === next.x &&
+      previous.y === next.y &&
+      previous.width === next.width &&
+      previous.height === next.height)
+  )
+}
+
+export interface CaretRect {
+  left: number
+  top: number
+  width: number
+  height: number
+}
+
+/** Width of the drawn caret, in dp. Two points reads at phone density. */
+export const CARET_WIDTH = 2
+
+/**
+ * Opacity of the native input's glyphs.
+ *
+ * Android's IME paints composing text black even when the input's colour is
+ * transparent, so the whole input is hidden there and only the Skia layer is
+ * visible. Other platforms keep the native input's own glyphs aligned under the
+ * Skia layer; there is no composing ghost to hide.
+ */
+export function composerInputOpacity(platform: string): number {
+  return platform === 'android' ? 0 : 1
+}
+
+/**
+ * Place the visible caret at the end of a measured line.
+ *
+ * The native input is fully hidden on Android because its IME paints composing
+ * glyphs black even when its text colour is transparent. Hiding it also hides
+ * the native caret, so the composer draws one over the same glyphs. A hidden
+ * `Text` containing the text before the selection is laid out with the input's
+ * own width and style; the last line's end is where the caret belongs.
+ *
+ * Returns null until a line has been measured, rather than guessing a position
+ * and then jumping when the measurement arrives.
+ */
+export function composerCaretBox(box: InputBox, line: CaretLine | null): CaretRect | null {
+  if (
+    !line ||
+    !Number.isFinite(line.x) ||
+    !Number.isFinite(line.y) ||
+    !Number.isFinite(line.width) ||
+    !Number.isFinite(line.height)
+  ) {
+    return null
+  }
+  const height = Math.max(1, line.height || box.lineHeight)
+  return {
+    left: box.left + line.x + line.width - CARET_WIDTH / 2,
+    top: box.top + line.y,
+    width: CARET_WIDTH,
+    height,
+  }
+}

package/src/composer/tapGesture.ts

@@ -0,0 +1,31 @@
+/**
+ * Whether a press moved far enough to be a drag.
+ *
+ * Pressable can report a press after a short move, and the composer's backdrop
+ * is exactly where a person drags the canvas. The decision is measured from the
+ * press event itself — not from a flag set by `onPressOut` — because Android can
+ * deliver the release before the press callback runs.
+ *
+ * @experimental
+ */
+
+export interface Point {
+  x: number
+  y: number
+}
+
+/** Movement at or below this many dp is still a tap. */
+export const TAP_SLOP = 8
+
+export function pressMoved(start: Point | null, end: Point | null, slop = TAP_SLOP): boolean {
+  if (!start || !end) return false
+  if (
+    !Number.isFinite(start.x) ||
+    !Number.isFinite(start.y) ||
+    !Number.isFinite(end.x) ||
+    !Number.isFinite(end.y)
+  ) {
+    return false
+  }
+  return Math.hypot(end.x - start.x, end.y - start.y) > Math.max(0, slop)
+}

package/src/gestures/LayerGestureSurface.tsx

@@ -26,11 +26,18 @@ import {
 } from './layerGestureWorklet'
 import { useInteractionState } from './interactionState'
 import { type GestureSnapEvent } from './controller'
+import { selectedLayerTapId } from './selectionTap'
 
 /** Overrides for overlay-layer gestures, defaulting to the profile's settings. */
 export interface LayerGestureSurfaceProps {
   /** Fired once per snap engagement — hook up haptics here if you want them. */
   onSnap?: (event: GestureSnapEvent) => void
+  /**
+   * Fired when a tap lands on a layer that was already selected when the
+   * gesture began. Hosts use this for a second-tap action such as opening the
+   * text composer; the SDK itself stays unaware of what a layer means.
+   */
+  onSelectedLayerTap?: (layerId: string) => void
 }
 
 /**
@@ -49,8 +56,8 @@ export interface LayerGestureSurfaceProps {
  * - **One history entry.** The document is written exactly once, when the
  *   gesture settles, and not at all if nothing actually moved.
  */
-export function LayerGestureSurface({ onSnap }: LayerGestureSurfaceProps) {
-  const { document, dispatch, profile } = useEditor()
+export function LayerGestureSurface({ onSnap, onSelectedLayerTap }: LayerGestureSurfaceProps) {
+  const { document, dispatch, profile, selection } = useEditor()
   const store = useEditorStore()
   const metrics = useCanvasMetrics()
   // Destructure the setters: the context value's identity changes on every
@@ -195,11 +202,12 @@ export function LayerGestureSurface({ onSnap }: LayerGestureSurfaceProps) {
    * callbacks + a mutable snapshot gives both fresh data and a gesture object
    * that never needs rebuilding.
    */
-  const latest = useRef({ document, metrics, store, dispatch, onSnap, profile })
-  latest.current = { document, metrics, store, dispatch, onSnap, profile }
+  const latest = useRef({ document, metrics, store, dispatch, onSnap, profile, selection, onSelectedLayerTap })
+  latest.current = { document, metrics, store, dispatch, onSnap, profile, selection, onSelectedLayerTap }
 
   const grabbedId = useRef<string | null>(null)
   const grabbedFrom = useRef<Transform | null>(null)
+  const tapWasSelected = useRef(false)
   const snapState = useRef<LayerSnapState>(NO_SNAP)
 
   const onGrabLayer = useCallback((id: string) => {
@@ -214,9 +222,32 @@ export function LayerGestureSurface({ onSnap }: LayerGestureSurfaceProps) {
     setLayerDragActive(true)
   }, [setPreview, setLayerDragActive, previewTransform])
 
+  /**
+   * Record whether the layer under the first touch was already selected.
+   *
+   * This has to happen on touch-down, not when the pan grabs: a tap does not
+   * activate the pan, so a snapshot taken there never existed and every tap
+   * looked like a first tap. It also runs before the pan's grab selects the
+   * layer, which is what would otherwise turn a first tap into a second one.
+   */
+  const snapshotTapAt = useCallback((xDp: number, yDp: number) => {
+    const { document: doc, metrics: m, store: s, selection: selected } = latest.current
+    if (!m) return
+    const layerInteraction = latest.current.profile.interaction?.layers
+    const hit = hitTestDocument(
+      doc,
+      { x: xDp / m.width, y: yDp / m.height },
+      s.registry,
+      (layer, index) => isDirectManipulationLayer(layer, index, layerInteraction),
+    )
+    tapWasSelected.current = Boolean(hit && selected.includes(hit.id))
+  }, [])
+
   const onSelectAt = useCallback((xDp: number, yDp: number) => {
     const { document: doc, metrics: m, store: s } = latest.current
     if (!m) return
+    const wasSelected = tapWasSelected.current
+    tapWasSelected.current = false
     const layerInteraction = latest.current.profile.interaction?.layers
     const hit = hitTestDocument(
       doc,
@@ -225,6 +256,8 @@ export function LayerGestureSurface({ onSnap }: LayerGestureSurfaceProps) {
       (layer, index) => isDirectManipulationLayer(layer, index, layerInteraction),
     )
     s.select(hit && !hit.locked ? [hit.id] : [])
+    const editId = selectedLayerTapId(hit ?? null, wasSelected)
+    if (editId) latest.current.onSelectedLayerTap?.(editId)
   }, [])
 
   const onSnapChanged = useCallback(
@@ -388,6 +421,8 @@ export function LayerGestureSurface({ onSnap }: LayerGestureSurfaceProps) {
       .onTouchesDown((e) => {
         'worklet'
         livePointers.value = e.allTouches.length
+        const touch = e.changedTouches[0] ?? e.allTouches[0]
+        if (touch) runOnJS(snapshotTapAt)(touch.x, touch.y)
       })
       .onTouchesUp((e) => {
         'worklet'
@@ -493,6 +528,7 @@ export function LayerGestureSurface({ onSnap }: LayerGestureSurfaceProps) {
     deleteTarget,
     aspect,
     onGrabLayer,
+    snapshotTapAt,
     onSelectAt,
     onSnapChanged,
     onHoverChanged,

package/src/gestures/selectionTap.ts

@@ -0,0 +1,22 @@
+/**
+ * Resolve whether a tap should open the selected layer for editing.
+ *
+ * A tap has two jobs. The first one selects the layer under the finger; a tap
+ * on a layer that was already selected opens it for editing. The selection is
+ * snapshotted when the gesture begins, before the pan's grab selects the layer,
+ * otherwise every first tap would look like a second one.
+ *
+ * @experimental
+ */
+export interface SelectionTapHit {
+  id: string
+  locked?: boolean
+}
+
+export function selectedLayerTapId(
+  hit: SelectionTapHit | null,
+  wasSelectedAtStart: boolean,
+): string | null {
+  if (!hit || hit.locked || !wasSelectedAtStart) return null
+  return hit.id
+}