@solidrt/core 0.0.54 → 0.0.56

package/src/transform.ts

@@ -26,14 +26,18 @@ const ENGAGE = 0.6
 const QUIET_SMOOTH = 0.19
 
 export type TransformDelta = {
-  /** Focal-point movement since the previous frame, logical px. */
+  /** Focal-point movement since the previous frame, in the handler node's
+   * PARENT frame (the frame its own x/y live in: window pixels under no
+   * scaling ancestor, design pixels under a designSize fit), so it applies
+   * 1:1 to the node or to content inside it. */
   dx: number
   dy: number
   /** Multiplicative span change since the previous frame (1 = unchanged, >1 = fingers spreading). */
   scale: number
   /** Rotation of the pointer pair since the previous frame, radians (0 with a single pointer). */
   rotation: number
-  /** Current focal point in window coordinates (the clientX/clientY frame) - the zoom-about anchor. */
+  /** Current focal point in the handler node's LOCAL frame (its own
+   * pixels) - the zoom-about anchor for content inside it. */
   x: number
   y: number
   /** How many pointers are down right now. Consumers that give one- and
@@ -106,12 +110,25 @@ export interface TransformOptions {
 // path, so an active transform survives leaving the node or the window.
 // cancel() is the external-cancel hook; it ends an active gesture without
 // onTransformEnd. Options are read at event time.
+//
+// Frames: the slop, the span filter and its rate gates are finger-travel
+// thresholds, so they are measured in window pixels (clientX/clientY);
+// the focal movement (dx/dy) and the pair angle are measured in the node's
+// parent frame (parentX/parentY), the frame the node's own coordinates
+// live in, so a scaled ancestor (a designSize fit) is accounted for and
+// the delta applies unchanged to the node or to content inside it; the
+// focal point (x/y) is reported in the node's local frame (localX/localY),
+// the anchor a zoom-about-the-fingers needs. Scale and rotation are ratios
+// and angles, the same in every uniformly scaled frame. The event carries
+// all three frames exactly, on and off the node.
 export function createTransform(options: TransformOptions) {
+  type Tracked = { cx: number; cy: number; px: number; py: number; lx: number; ly: number }
+  let at = (e: PointerEvent): Tracked => ({ cx: e.clientX, cy: e.clientY, px: e.parentX, py: e.parentY, lx: e.localX, ly: e.localY })
   // All tracked pointers, in down order (the first two define the rotation pair).
-  let pointers = new Map<number, { x: number; y: number }>()
+  let pointers = new Map<number, Tracked>()
   let active = false
   // Slop baseline while armed; last delivered configuration while active.
-  let ref: { x: number; y: number; span: number; angle: number } | null = null
+  let ref: { cx: number; cy: number; px: number; py: number; span: number; angle: number } | null = null
   // The zoom gate and filter (see the zoom-noise note above): scale stays 1
   // until the SMOOTHED span leaves spanBase by SLOP, then streams smoothed
   // ratios for the rest of the gesture.
@@ -128,27 +145,41 @@ export function createTransform(options: TransformOptions) {
   // emits nothing.
   let rebase = false
 
+  // Centroids in all three frames, the span in window pixels (it feeds the
+  // finger-travel gates), the pair angle in the parent frame.
   let measure = () => {
     let n = pointers.size
-    let x = 0
-    let y = 0
+    let cx = 0
+    let cy = 0
+    let px = 0
+    let py = 0
+    let lx = 0
+    let ly = 0
     for (let p of pointers.values()) {
-      x += p.x
-      y += p.y
+      cx += p.cx
+      cy += p.cy
+      px += p.px
+      py += p.py
+      lx += p.lx
+      ly += p.ly
     }
-    x /= n
-    y /= n
+    cx /= n
+    cy /= n
+    px /= n
+    py /= n
+    lx /= n
+    ly /= n
     let span = 0
-    for (let p of pointers.values()) span += Math.hypot(p.x - x, p.y - y)
+    for (let p of pointers.values()) span += Math.hypot(p.cx - cx, p.cy - cy)
     span /= n
     let angle = 0
     if (n >= 2) {
       let pair = pointers.values()
       let a = pair.next().value!
       let b = pair.next().value!
-      angle = Math.atan2(b.y - a.y, b.x - a.x)
+      angle = Math.atan2(b.py - a.py, b.px - a.px)
     }
-    return { x, y, span, angle }
+    return { cx, cy, px, py, lx, ly, span, angle }
   }
 
   let reset = () => {
@@ -202,10 +233,10 @@ export function createTransform(options: TransformOptions) {
       if (rotation > Math.PI) rotation -= 2 * Math.PI
       else if (rotation < -Math.PI) rotation += 2 * Math.PI
     }
-    let dx = m.x - ref.x
-    let dy = m.y - ref.y
+    let dx = m.px - ref.px
+    let dy = m.py - ref.py
     ref = m
-    options.onTransformMove?.({ dx, dy, scale, rotation, x: m.x, y: m.y, pointers: pointers.size })
+    options.onTransformMove?.({ dx, dy, scale, rotation, x: m.lx, y: m.ly, pointers: pointers.size })
   }
 
   // An unmount mid-gesture must not leave resolved claims behind (or a live
@@ -226,24 +257,22 @@ export function createTransform(options: TransformOptions) {
         // A finger joining an established gesture belongs to it outright; if
         // the arena refuses (resolved elsewhere) the finger stays out.
         if (!arena.steal(e.pointerId, owner)) return
-        pointers.set(e.pointerId, { x: e.clientX, y: e.clientY })
+        pointers.set(e.pointerId, at(e))
         rebase = true
         return
       }
-      pointers.set(e.pointerId, { x: e.clientX, y: e.clientY })
+      pointers.set(e.pointerId, at(e))
       ref = measure()
     },
     onPointerMove: (e: PointerEvent) => {
-      let p = pointers.get(e.pointerId)
-      if (!p || !ref) return
-      p.x = e.clientX
-      p.y = e.clientY
+      if (!pointers.has(e.pointerId) || !ref) return
+      pointers.set(e.pointerId, at(e))
       if (!active) {
         // Arming runs per event: the slop test tolerates a mixed-age
         // measure (8px against <=1 frame of staleness), and the arena
         // steal must happen synchronously inside the dispatch walk.
         let m = measure()
-        let travel = Math.hypot(m.x - ref.x, m.y - ref.y)
+        let travel = Math.hypot(m.cx - ref.cx, m.cy - ref.cy)
         if (travel < SLOP && Math.abs(m.span - ref.span) < SLOP) return
         let taken: number[] = []
         let refused = false

package/src/types.d.ts

@@ -148,21 +148,75 @@ export interface LayoutProps extends FlexboxProps, GridProps {
   clear?: "left" | "right" | "both"
 }
 
-/** Colors are CSS color strings, parsed to a packed u32 by `parseColor`. */
+/**
+ * A CSS color string: hex (`#rgb`, `#rrggbb`, `#rrggbbaa`), `rgb()`/`rgba()`,
+ * `hsl()`/`hsla()`, `hwb()`, or a named color. The CSS Color 4 functions -
+ * `color-mix()`, `oklch()`, `lab()`, `color()` - are not parsed and throw
+ * `Invalid color`. To mix two colors, `mixColors(a, b, t)` (oklab, returns
+ * hex); for a color at a given opacity, `withAlpha(color, a)` (returns
+ * `#rrggbbaa`); `parseColor` gives the packed u32 the prop also accepts.
+ */
 export type Color = string
 
+export type BlendMode = "clear" | "source" | "destination" | "source-over" | "destination-over" | "source-in" | "destination-in" | "source-out" | "destination-out" | "source-atop" | "destination-atop" | "xor" | "plus" | "modulate" | "screen" | "overlay" | "darken" | "lighten" | "color-dodge" | "color-burn" | "hard-light" | "soft-light" | "difference" | "exclusion" | "multiply" | "hue" | "saturation" | "color" | "luminosity"
+export type DrawStyle = "fill" | "stroke" | "stroke-and-fill"
+export type StrokeCap = "butt" | "round" | "square"
+export type StrokeJoin = "miter" | "round" | "bevel"
+
 export interface PaintProps {
   // A solid color, or a gradient from createLinearGradient/createRadialGradient.
   color?: Color | Gradient
-  blendMode?: "clear" | "source" | "destination" | "source-over" | "destination-over" | "source-in" | "destination-in" | "source-out" | "destination-out" | "source-atop" | "destination-atop" | "xor" | "plus" | "modulate" | "screen" | "overlay" | "darken" | "lighten" | "color-dodge" | "color-burn" | "hard-light" | "soft-light" | "difference" | "exclusion" | "multiply" | "hue" | "saturation" | "color" | "luminosity"
+  blendMode?: BlendMode
   /** Default "fill"; "stroke" on line, whose segment has no interior (see LineProps). */
-  drawStyle?: "fill" | "stroke" | "stroke-and-fill"
-  strokeCap?: "butt" | "round" | "square"
-  strokeJoin?: "miter" | "round" | "bevel"
+  drawStyle?: DrawStyle
+  strokeCap?: StrokeCap
+  strokeJoin?: StrokeJoin
   strokeMiter?: number
   strokeWidth?: number
 }
 
+/**
+ * A drop shadow behind a shape (CSS box-shadow field semantics, one shadow):
+ * the shape's outer geometry, offset by x/y, grown by `spread`, softened by
+ * `blur` (a CSS-style radius in logical px), painted in `color` under the
+ * shape. It casts from the shape's outer box whatever the draw style (strokes
+ * paint inside, so the box is the outer edge) - except on `path`, where the
+ * shadow mirrors the element's own fill/stroke silhouette and `spread` is
+ * rejected (an arbitrary path cannot be inflated exactly). `color` is
+ * required; there is no currentColor to inherit.
+ */
+export interface ShadowProps {
+  x?: number
+  y?: number
+  blur?: number
+  spread?: number
+  color: Color
+}
+
+/**
+ * A subtree filter (the CSS filter functions, object form): the view's
+ * children are composited together, run through the set color operations -
+ * fused into one color matrix, applied in the fixed order grayscale, sepia,
+ * saturate, hueRotate, brightness, contrast, invert - and then blurred.
+ * `blur` is a CSS-style radius in logical px; `hueRotate` is radians (this
+ * API's angle convention); the rest are the CSS amounts (1 = unchanged for
+ * saturate/brightness/contrast, 0 = unchanged for the others; grayscale,
+ * sepia and invert saturate at 1). There is no `opacity` key - the view's
+ * own `opacity` prop is the same compositing layer. Like opacity, a filter
+ * on a non-boundary view costs a save_layer; on a repaintBoundary view it
+ * rides the composite for free. Hit testing is unaffected.
+ */
+export interface FilterProps {
+  blur?: number
+  grayscale?: number
+  sepia?: number
+  saturate?: number
+  hueRotate?: number
+  brightness?: number
+  contrast?: number
+  invert?: number
+}
+
 /** A percentage value, from `pct(50)`. Resolves against the element box. */
 export type Pct = { readonly __unit: "pct"; v: number }
 
@@ -357,22 +411,41 @@ export interface OvalGeometryProps extends PositionProps {
   h?: number
 }
 
-/** See {@link PositionProps}: detached-only, never affects layout. */
+/**
+ * See {@link PositionProps}: detached-only, never affects layout. A d-text
+ * is boxed or anchored. Boxed (no `anchor`): it wraps at `w`, or at the box
+ * inherited from the nearest laid-out ancestor, and `textAlign` aligns
+ * lines inside that width - so a right-aligned label needs a `w`. Anchored:
+ * `x` is a point on the line (SVG's text-anchor), which is what a label on a
+ * chart, an axis or a diagram wants. Either way the reported bounds
+ * (getBoundingBox, the tree) are the laid-out paragraph - widest line by
+ * line stack - unless `w`/`h` override a side.
+ */
 export interface TextGeometryProps extends PositionProps {
-  // Shaping (wrap) width. Detached text wraps at the inherited ancestor size
-  // by default; set w for an unwrapped natural line or an explicit wrap width.
+  /**
+   * Where `x` sits on each line: its start, middle or end. With `w` unset
+   * the text shapes at its natural width (no wrap; `\n` still breaks), and
+   * `textAlign` defaults to the anchor's side. With `w` set, the `w`-wide
+   * box is what gets anchored at `x`.
+   */
+  anchor?: "start" | "middle" | "end"
+  // Shaping (wrap) width; unset, boxed text wraps at the inherited box and
+  // anchored text does not wrap.
   w?: number
-  // Reported-bounds height only; paragraph height always falls out of the text.
+  // Reported-bounds height override only; paragraph height always falls out
+  // of the text.
   h?: number
 }
 
 /**
- * See {@link PositionProps}: detached-only, never affects layout. A line's
- * reported bounds (getBoundingBox, the tree, a detached capture) are its
- * painted box: the geometry's extent plus the stroke's reach, not the
+ * See {@link PositionProps}: detached-only, never affects layout. The
+ * endpoints (or `points`) are the line's own geometry; `x`/`y` offset all of
+ * it, the way a `d-path`'s offset its `d`, so one write moves a polyline. A
+ * line's reported bounds (getBoundingBox, the tree, a detached capture) are
+ * its painted box: the geometry's extent plus the stroke's reach, not the
  * inherited box.
  */
-export interface LineGeometryProps {
+export interface LineGeometryProps extends PositionProps {
   /** Endpoints default to spanning the box: (0,0) to (box width, box height). */
   x1?: number
   y1?: number
@@ -520,7 +593,9 @@ export interface TransitionProps {
    * its transform); the initial value never animates unless the entry sets
    * `from` (an enter animation), and a non-numeric write (e.g. null)
    * cancels the running animation and snaps. `null` clears the
-   * declaration; already-running animations finish.
+   * declaration; already-running animations finish. A spec built in a
+   * conditional widens `curve` to `string` for TypeScript; write
+   * `satisfies Transition` on the branch.
    */
   transition?:
     | ({
@@ -543,7 +618,7 @@ export interface TransitionProps {
 
 // Primitives
 
-export interface WindowProps extends LayoutProps, PointerProps {
+export interface WindowProps extends LayoutProps, PointerProps, TransitionProps {
   children?: Children
   title?: string
   fullscreen?: boolean
@@ -563,21 +638,24 @@ export interface WindowProps extends LayoutProps, PointerProps {
  * `uniform sampler2D uSource` (top-left origin, like every sampled texture -
  * so a vertex stage mapping it onto the window flips the v coordinate) and
  * is drawn attributeless as triangles, `vertexCount` vertices fetched via
- * gl_VertexID. `iResolution`, filled by name, is the window size in physical
- * pixels (the pass covers exactly that). The window is cleared to opaque
- * black first, so geometry that does not cover it still presents a defined
- * frame.
+ * gl_VertexID. `iResolution`, the window size in physical pixels (the pass
+ * covers exactly that), is filled by name into a uniform the program declares
+ * itself or gets from compileShader's `header` option. The window is cleared
+ * to opaque black first, so geometry that does not cover it still presents a
+ * defined frame.
  */
 export interface WindowShaderProps {
   /** Linked program handle from linkProgram. */
   program: ProgramId
   /**
    * Uniforms filled by name, paced to the next real repaint. A number drives
-   * a scalar (`float`/`int`); a flat number array drives the declared GLSL
-   * type: 2/3/4 for `vec2`/`vec3`/`vec4`, 16 (column-major) for `mat4`.
+   * a scalar (`float`/`int`); a flat number array (or a Float32Array /
+   * Float64Array) drives the declared GLSL type: 2/3/4 for
+   * `vec2`/`vec3`/`vec4`, 16 (column-major) for `mat4`. An undefined or null
+   * entry is skipped.
    */
-  params?: Record<string, number | number[]>
-  /** Extra sampler2D inputs: uniform name to texture id, or `{ id, filter?, wrap? }` for a per-binding sampling override. */
+  params?: Record<string, number | number[] | Float32Array | Float64Array>
+  /** Extra sampler2D inputs: uniform name to texture id, or `{ id, filter?, wrap? }` for a per-binding sampling override. An undefined or null entry is skipped. */
   textures?: TextureBindings
   /** Vertices drawn (attributeless triangles). Default 3, the covering triangle. */
   vertexCount?: number
@@ -637,7 +715,9 @@ export interface ViewOwnProps extends TransformProps, PointerProps {
    * skipping rasterization entirely. Costs texture memory and re-rasterizes
    * on layout-size or display-scale changes. Content painted outside the
    * element's layout box is cropped, and ancestor scale animations smear the
-   * bitmap; best for screen-aligned, static, raster-expensive content.
+   * bitmap; best for screen-aligned, static, raster-expensive content. On a
+   * d-view the box is the inherited frame (the nearest laid-out ancestor's
+   * box, or the design size under a designSize view), same as a capture.
    *
    * "snapshot-no-aa" is "snapshot" rasterized without anti-aliasing: cheaper
    * (no multisampled scratch, one render pass), but vector content - svg
@@ -667,25 +747,41 @@ export interface ViewOwnProps extends TransformProps, PointerProps {
    * unrotated, opaque content.
    */
   shader?: ViewShaderProps | null
+  filter?: FilterProps
+  /**
+   * Filters the pixels already painted BENEATH the view's box, in place,
+   * before the view's own content draws - frosted glass over live content
+   * (CSS `backdrop-filter`). Same keys and semantics as `filter`. The
+   * region is the layout box; give the view an overflow clip with
+   * `clipRadius` for rounded glass. Costs an offscreen capture of the
+   * pixels beneath at that point in the frame, so treat it as a deliberate
+   * panel, not a casual style. Inside a `repaintBoundary="snapshot"`
+   * subtree it sees only that boundary's own offscreen content, never what
+   * is behind the boundary (the same containment `blendMode` has there).
+   */
+  backdropFilter?: FilterProps
 }
 
 /**
  * A boundary shader declaration. The program contract matches shader targets,
  * not the window pass: the subtree's rasterization binds as
  * `uniform sampler2D uSource` (top-left origin, like every sampled texture)
- * and the pass draws the covering triangle attributeless. `iResolution`,
- * filled by name, is the boundary in physical pixels.
+ * and the pass draws the covering triangle attributeless. `iResolution`, the
+ * boundary in physical pixels, is filled by name into a uniform the program
+ * declares itself or gets from compileShader's `header` option.
  */
 export interface ViewShaderProps {
   /** Linked program handle from linkProgram. */
   program: ProgramId
   /**
    * Uniforms filled by name, paced to the next real repaint. A number drives
-   * a scalar (`float`/`int`); a flat number array drives the declared GLSL
-   * type: 2/3/4 for `vec2`/`vec3`/`vec4`, 16 (column-major) for `mat4`.
+   * a scalar (`float`/`int`); a flat number array (or a Float32Array /
+   * Float64Array) drives the declared GLSL type: 2/3/4 for
+   * `vec2`/`vec3`/`vec4`, 16 (column-major) for `mat4`. An undefined or null
+   * entry is skipped.
    */
-  params?: Record<string, number | number[]>
-  /** Extra sampler2D inputs: uniform name to texture id, or `{ id, filter?, wrap? }` for a per-binding sampling override. */
+  params?: Record<string, number | number[] | Float32Array | Float64Array>
+  /** Extra sampler2D inputs: uniform name to texture id, or `{ id, filter?, wrap? }` for a per-binding sampling override. An undefined or null entry is skipped. */
   textures?: TextureBindings
   /**
    * Transparent margin in logical px on every side of the layout box, for
@@ -719,20 +815,28 @@ export interface ViewProps extends ViewOwnProps, LayoutProps {}
 // A stroked rect paints inside its box, like a CSS border: the stroke's outer
 // edge sits on the box edge rather than straddling it, so nothing bleeds past
 // the box for a clip to cut. `path` and `line` strokes stay centered on their
-// geometry - there the geometry is the stroke, not a box.
-export interface RectProps extends PaintProps, PointerProps {
+// geometry - there the geometry is the stroke, not a box. A dashed stroke
+// dashes that same inset outline (see DashProps).
+export interface RectProps extends PaintProps, PointerProps, DashProps {
   // Corner radius, measured on the box (the stroke's outer edge). A single
   // number applies to all four corners; an array is [top-left, top-right,
   // bottom-right, bottom-left] (CSS border-radius order).
   radius?: number | [number, number, number, number]
+  shadow?: ShadowProps
 }
 
 // Strokes paint inside the box, same as `RectProps`.
-export interface OvalProps extends PaintProps, PointerProps {}
+export interface OvalProps extends PaintProps, PointerProps, DashProps {
+  shadow?: ShadowProps
+}
 
 /**
- * A stroke's dash pattern, on `line` and `path`. Both lengths must be set
- * to dash; with either unset, or a gap of 0, the stroke is solid.
+ * A stroke's dash pattern, on every stroked primitive (`rect`, `oval`,
+ * `line`, `path`). Both lengths must be set to dash; with either unset, or
+ * a gap of 0, the stroke is solid. A box primitive dashes its inset
+ * outline, the pattern starting where SVG's does (a rect on the top edge
+ * after the top-left corner, an oval at 3 o'clock) and running clockwise;
+ * its dashes stay inside the box like the solid stroke.
  */
 export interface DashProps {
   /**
@@ -807,15 +911,24 @@ export interface LineProps extends PaintProps, PointerProps, DashProps {
 export interface PathProps extends PaintProps, PointerProps, DashProps {
   d?: string
   fillRule?: "nonzero" | "evenodd"
+  /** Shadows the drawn silhouette (fill and/or stroke); `spread` is rejected here. */
+  shadow?: ShadowProps
 }
 
+export type FontFamily = "sans" | "serif" | "mono" | (string & {})
+export type FontStyle = "normal" | "italic"
+export type FontWeight = 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900
+export type TextDecoration = "none" | "underline"
+export type TextAlign = "left" | "right" | "center" | "justify"
+export type TextOverflow = "clip" | "ellipsis" | (string & {})
+
 /**
  * Per-run text style: the paragraph default on <text>, an override on <span>.
  * The cascade is intra-paragraph only: a span inherits from its enclosing
  * span, then from the <text>; nothing inherits across the tree.
  */
 export interface TextRunProps {
-  fontFamily?: "sans" | "serif" | "mono" | (string & {})
+  fontFamily?: FontFamily
   fontSize?: number
   /**
    * Line height as a MULTIPLIER of fontSize, not pixels (the theme uses
@@ -823,15 +936,15 @@ export interface TextRunProps {
    * font size, rendering the text as blank space.
    */
   lineHeight?: number
-  fontStyle?: "normal" | "italic"
-  fontWeight?: 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900
+  fontStyle?: FontStyle
+  fontWeight?: FontWeight
   /**
    * Underline in the run's own color, drawn straight through descenders
    * (no skip-ink). Position and thickness come from the font's own metrics
    * unless overridden; a font Impeller resolves through the system fallback
    * gets the shipped Noto values.
    */
-  textDecoration?: "none" | "underline"
+  textDecoration?: TextDecoration
   /** Pixels from the baseline to the top of the underline. */
   textUnderlineOffset?: number
   /** Underline thickness in pixels. */
@@ -851,14 +964,14 @@ export interface SpanProps extends TextRunProps, PointerProps {
 
 export interface TextProps extends PaintProps, PointerProps, TextRunProps {
   children?: Children
-  textAlign?: "left" | "right" | "center" | "justify"
+  textAlign?: TextAlign
   maxLines?: number
   /**
    * What happens to text cut off by maxLines: "clip" (default), "ellipsis"
    * (a U+2026 at the end of the last line), or any other string to use as
    * the ellipsis. Drawn in the paragraph's default style.
    */
-  textOverflow?: "clip" | "ellipsis" | (string & {})
+  textOverflow?: TextOverflow
   /**
    * A word (wrap unit) wider than the line: "anywhere" (default) splits it
    * at grapheme boundaries so it stays inside the box, "normal" keeps it
@@ -910,7 +1023,8 @@ export interface TextureProps extends PaintProps, PointerProps {
   // throws, and set src before params: a write with no src to route to
   // throws). However often a signal writes, the target renders once per
   // frame at the raster flush. A number drives a scalar (`float`/`int`); a
-  // flat number array drives the declared GLSL type: 2/3/4 for
-  // `vec2`/`vec3`/`vec4`, 16 (column-major) for `mat4`.
-  params?: Record<string, number | number[]>
+  // flat number array (or a Float32Array / Float64Array) drives the declared
+  // GLSL type: 2/3/4 for `vec2`/`vec3`/`vec4`, 16 (column-major) for `mat4`.
+  // An undefined or null entry is skipped.
+  params?: Record<string, number | number[] | Float32Array | Float64Array>
 }