@solidrt/core 0.0.51 → 0.0.52

package/src/scroll.ts

@@ -4,7 +4,7 @@
 // momentum, scrollbars and styling are policy and belong to the component (the
 // "skin") that composes this, the same way createTextEditorLayout backs TextInput.
 
-import { createSignal, flush } from "@solidjs/signals"
+import { createSignal } from "@solidjs/signals"
 import { getBoundingBox } from "./core"
 import { onLayout } from "./window"
 
@@ -12,6 +12,15 @@ export type ScrollAxis = "vertical" | "horizontal" | "both"
 
 export type ScrollOffset = { x: number; y: number }
 
+/** The web's scroll behavior word, simplified: "instant" asks the skin for no
+ * motion; "auto" (the default) and "smooth" both mean its usual motion, since
+ * the default already animates. */
+export type ScrollBehavior = "auto" | "instant" | "smooth"
+
+/** Target of scrollTo/scrollBy. An omitted axis keeps its offset (scrollTo)
+ * or moves by 0 (scrollBy). */
+export type ScrollToOptions = { x?: number; y?: number; behavior?: ScrollBehavior }
+
 export type ScrollOptions = {
   /** Which axes can scroll. Locked axes are pinned to 0. Default "vertical". */
   axis?: ScrollAxis
@@ -20,10 +29,18 @@ export type ScrollOptions = {
 export type Scroll = {
   /** Current clamped offset, as a reactive accessor. */
   offset(): ScrollOffset
-  /** Scroll by a delta (positive moves content up/left), clamped to range. */
-  scrollBy(dx: number, dy: number): void
+  /** Largest reachable offset per axis (content overflow, 0 on a locked axis),
+   * as a reactive accessor refreshed each layout. Watching it is how a scroll
+   * policy learns that the content or the viewport changed size. */
+  range(): ScrollOffset
+  /** Behavior of the latest scrollTo/scrollBy, as a reactive accessor: the
+   * skin reads it to withhold its motion for an instant write. Layout
+   * re-clamps leave it alone. */
+  behavior(): ScrollBehavior
   /** Scroll to an absolute offset, clamped to range. */
-  scrollTo(x: number, y: number): void
+  scrollTo(options: ScrollToOptions): void
+  /** Scroll by a delta (positive moves content up/left), clamped to range. */
+  scrollBy(options: ScrollToOptions): void
 }
 
 /**
@@ -32,7 +49,9 @@ export type Scroll = {
  * current content-vs-viewport overflow, so the view stays valid when content
  * grows or shrinks (e.g. an offset that scrolled to the bottom snaps up when the
  * list gets shorter). scrollBy/scrollTo clamp against the most recently measured
- * range. Pure geometry: no input handling and no visual policy.
+ * range. Pure geometry: no input handling and no visual policy. Anything beyond
+ * clamping (following a growing log, keeping an item in view) is a policy the
+ * caller writes against `range()` and `offset()`.
  *
  * The viewport node is the clipping box (overflow hidden); the content node is
  * the inner wrapper that holds the children and takes their natural size. Apply
@@ -48,6 +67,11 @@ export function createScroll(
   let canY = axis === "vertical" || axis === "both"
 
   let [offset, setOffset] = createSignal<ScrollOffset>({ x: 0, y: 0 })
+  let [range, setRange] = createSignal<ScrollOffset>({ x: 0, y: 0 })
+  let [behavior, setBehavior] = createSignal<ScrollBehavior>("auto")
+  // Mirrors the signal: a setter's value is not readable until the flush, and
+  // two writes in one batch must still compare against the latest.
+  let lastBehavior: ScrollBehavior = "auto"
 
   // A scroll viewport with no explicit main-axis size resolves to 0 in flex
   // layout and its content silently vanishes - a classic trap (maxHeight alone
@@ -59,6 +83,8 @@ export function createScroll(
 
   // Last measured overflow, refreshed each layout. scrollBy/scrollTo clamp
   // against these between layouts; onLayout re-clamps once new sizes are known.
+  // Kept as plain values beside the `range` signal because a signal write is
+  // not readable until the flush, and clamping needs the number now.
   let maxX = 0
   let maxY = 0
 
@@ -67,10 +93,14 @@ export function createScroll(
     y: canY ? Math.max(0, Math.min(y, maxY)) : 0,
   })
 
-  let set = (x: number, y: number) => {
+  let set = (x: number, y: number, b: ScrollBehavior = "auto") => {
     let cur = offset()
     let next = clamp(x, y)
     if (next.x !== cur.x || next.y !== cur.y) setOffset(next)
+    if (b !== lastBehavior) {
+      lastBehavior = b
+      setBehavior(b)
+    }
   }
 
   onLayout(() => {
@@ -94,20 +124,26 @@ export function createScroll(
     }
     maxX = Math.max(0, cb.width - vb.width)
     maxY = Math.max(0, cb.height - vb.height)
+    let r = range()
+    let rx = canX ? maxX : 0
+    let ry = canY ? maxY : 0
+    if (r.x !== rx || r.y !== ry) setRange({ x: rx, y: ry })
     let cur = offset()
     let next = clamp(cur.x, cur.y)
-    if (next.x !== cur.x || next.y !== cur.y) {
-      setOffset(next)
-      flush()
-    }
+    if (next.x !== cur.x || next.y !== cur.y) setOffset(next)
   })
 
   return {
     offset,
-    scrollBy: (dx, dy) => {
+    range,
+    behavior,
+    scrollTo: (o) => {
       let cur = offset()
-      set(cur.x + dx, cur.y + dy)
+      set(o.x ?? cur.x, o.y ?? cur.y, o.behavior)
+    },
+    scrollBy: (o) => {
+      let cur = offset()
+      set(cur.x + (o.x ?? 0), cur.y + (o.y ?? 0), o.behavior)
     },
-    scrollTo: (x, y) => set(x, y),
   }
-}
+}

package/src/svg.ts

@@ -46,7 +46,7 @@ export type SvgDocument = {
  * that fits the document's coordinate space into its box:
  *
  *     let doc = createMemo(() => parseSvg(src))
- *     <view repaintBoundary viewBox={[doc().width, doc().height]} width={48} height={48}>
+ *     <view repaintBoundary designSize={[doc().width, doc().height]} width={48} height={48}>
  *       {doc().draws.map((draw) => <d-path {...draw} />)}
  *     </view>
  *

package/src/text-input.ts

@@ -397,7 +397,6 @@ export function createTextEditorLayout(
 
     setScrollX(wrap ? 0 : follow(scrollX(), c.x, caretWidth, vw, contentWidth + caretWidth))
     setScrollY(follow(scrollY(), c.y, c.height, vh, contentHeight))
-    flush()
   })
 
   return { lines, caret, caretLine, offsetAtX, lineAtY, step, scrollX, scrollY }

package/src/types.d.ts

@@ -2,7 +2,7 @@
 /// <reference path="./runtime-modules.d.ts" />
 
 import type { Gradient } from "./color"
-import type { ProgramId, TextureId } from "flux:gpu"
+import type { ProgramId, TextureBindings, TextureId } from "flux:gpu"
 import type { TextInputHints } from "flux:rendertree"
 import type { Element } from "solid-js"
 
@@ -155,6 +155,7 @@ 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"
+  /** 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"
@@ -365,7 +366,12 @@ export interface TextGeometryProps extends PositionProps {
   h?: number
 }
 
-/** See {@link PositionProps}: detached-only, never affects layout. */
+/**
+ * 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
+ * inherited box.
+ */
 export interface LineGeometryProps {
   /** Endpoints default to spanning the box: (0,0) to (box width, box height). */
   x1?: number
@@ -468,7 +474,20 @@ export type TransitionPropName =
   | "y1"
   | "x2"
   | "y2"
+  | "scrollX"
+  | "scrollY"
   | "opacity"
+  | "originX"
+  | "originY"
+  | "perspective"
+  | "clipRadius"
+  | "srcX"
+  | "srcY"
+  | "srcW"
+  | "srcH"
+  | "onLength"
+  | "offLength"
+  | "dashOffset"
   | "rotate"
   | "rotateX"
   | "rotateY"
@@ -558,8 +577,8 @@ export interface WindowShaderProps {
    * type: 2/3/4 for `vec2`/`vec3`/`vec4`, 16 (column-major) for `mat4`.
    */
   params?: Record<string, number | number[]>
-  /** Extra sampler2D inputs: uniform name to texture id. */
-  textures?: Record<string, TextureId>
+  /** Extra sampler2D inputs: uniform name to texture id, or `{ id, filter?, wrap? }` for a per-binding sampling override. */
+  textures?: TextureBindings
   /** Vertices drawn (attributeless triangles). Default 3, the covering triangle. */
   vertexCount?: number
   /**
@@ -580,18 +599,28 @@ export interface ViewOwnProps extends TransformProps, PointerProps {
   children?: Children
   trace?: boolean
   /**
-   * Design-space size `[w, h]` for the children: content drawn in that
-   * coordinate space is uniformly scaled to fit and centered in the element's
-   * box (SVG's default preserveAspectRatio, generalized). A pure fit
-   * transform - it never sizes the element, so give the box its size with
-   * layout props. Composed innermost: the transform props still operate in
-   * box space, and pointer events on children arrive in design coordinates.
-   * The overflow clip and scrollX/scrollY stay box properties too: the clip
-   * rect is the layout box and scroll offsets are box pixels, regardless of
-   * fit scale. The natural wrapper for parseSvg draws, or any d-* subtree
-   * authored in fixed design units.
-   */
-  viewBox?: [number, number]
+   * Design-space size `[w, h]` (both positive) for the children: everything
+   * under the view - layout, paint, input - happens in that coordinate space,
+   * which is uniformly scaled to fit and centered in the element's box (SVG's
+   * viewBox with its default preserveAspectRatio, generalized off the graphics
+   * format and onto a layout element; the fit is always "contain"). Laid-out
+   * children resolve flex, percentages and text wrapping against the design
+   * size, so a subtree scales into any box without reflowing. The view itself
+   * sizes like a replaced element: its intrinsic size is the design size, one
+   * sized axis derives the other from the design aspect, layout props
+   * override, and it always shrinks to fit (its min-content size is zero). As
+   * a flex item it still stretches like any other under the default alignment:
+   * a width-only design-size view in a row takes the line's height, not the
+   * design height, unless the row's alignItems or its own alignSelf is not
+   * "stretch" (CSS's rule for an <img> in a flex row). Composed innermost: the
+   * transform props still operate in box space, and pointer events on children
+   * arrive in design coordinates. The overflow clip and scrollX/scrollY stay
+   * box properties: the clip rect is the layout box and scroll offsets are box
+   * pixels, regardless of fit scale. The natural wrapper for parseSvg draws,
+   * any d-* subtree authored in fixed design units, or a whole panel that
+   * should scale rather than reflow.
+   */
+  designSize?: [number, number]
   /**
    * Corner radii for the clip applied when overflow is non-visible (hidden,
    * clip, scroll on both axes). A single number rounds all four corners; an
@@ -614,6 +643,9 @@ export interface ViewOwnProps extends TransformProps, PointerProps {
    * (no multisampled scratch, one render pass), but vector content - svg
    * paths, rounded corners, rotated edges - comes out hard-edged. Text and
    * axis-aligned rects look identical, so prefer it for plain UI panels.
+   *
+   * A snapshot boundary's pixels are available to the GPU stack as a live
+   * texture id through `snapshotTexture(ref)`.
    */
   repaintBoundary?: boolean | "snapshot" | "snapshot-no-aa"
   /**
@@ -653,8 +685,8 @@ export interface ViewShaderProps {
    * type: 2/3/4 for `vec2`/`vec3`/`vec4`, 16 (column-major) for `mat4`.
    */
   params?: Record<string, number | number[]>
-  /** Extra sampler2D inputs: uniform name to texture id. */
-  textures?: Record<string, TextureId>
+  /** Extra sampler2D inputs: uniform name to texture id, or `{ id, filter?, wrap? }` for a per-binding sampling override. */
+  textures?: TextureBindings
   /**
    * Transparent margin in logical px on every side of the layout box, for
    * the effect to write into - glow, drop shadow, blur that bleeds past the
@@ -698,21 +730,81 @@ export interface RectProps extends PaintProps, PointerProps {
 // Strokes paint inside the box, same as `RectProps`.
 export interface OvalProps extends PaintProps, PointerProps {}
 
-// A line's geometry is numbers, not a path string: the segment primitive to
-// reach for when endpoints move (each endpoint is one property write; a path
-// animates by rebuilding its `d` string). Endpoints (x1/y1/x2/y2) exist on
-// the detached `d-line` only. A laid-out `<line>` is practically a rule -
-// give it a thin box (length x strokeWidth); in general it draws its layout
-// box's top-left-to-bottom-right diagonal. For arbitrary angles and
-// connectors use `d-line`; for polylines and curves, a path.
-export interface LineProps extends PaintProps, PointerProps {
-  /** Dash pattern in local units: the drawn segment length. Both onLength and offLength must be set to dash; with either unset the line is solid. */
+/**
+ * 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.
+ */
+export interface DashProps {
+  /**
+   * The drawn length, in local units. The pattern runs continuously along
+   * the geometry - through a polyline's vertices and along a path's curves,
+   * restarting at each subpath of a path; 0 draws a dot per period (given
+   * round or square caps).
+   */
   onLength?: number
-  /** Dash pattern in local units: the gap length. Both onLength and offLength must be set to dash; with either unset the line is solid. */
+  /** The gap length, in local units. */
   offLength?: number
+  /**
+   * Distance into the dash pattern at which the stroke starts, in local
+   * units (SVG stroke-dashoffset). Wraps around the pattern's period;
+   * negative values allowed. Raising it marches the dashes toward the
+   * geometry's start: write it every frame for marching ants, or transition
+   * it for a one-shot slide. Default 0.
+   */
+  dashOffset?: number
+  /**
+   * What the geometry's length counts as, in the pattern's units (SVG
+   * pathLength): when set, `onLength`, `offLength` and `dashOffset` are
+   * scaled by the actual length over it. `pathLength={1}` makes them
+   * fractions: `onLength={0.77} offLength={1}` draws the first 77%, and
+   * transitioning `onLength` from 0 to 1 draws the geometry on. Must be
+   * positive; unset, the pattern is in local units.
+   */
+  pathLength?: number
+}
+
+// A line's geometry is numbers, not a path string: the primitive to reach
+// for when the geometry moves (each endpoint is one property write, a
+// polyline is one array write; a path animates by rebuilding its `d` string).
+// Two forms: the segment, whose endpoints (x1/y1/x2/y2) exist on the
+// detached `d-line` only, and the polyline (`points`), which exists on both.
+// A laid-out `<line>` without points is practically a rule - give it a thin
+// box (length x strokeWidth); in general it draws its layout box's
+// top-left-to-bottom-right diagonal. For arbitrary angles and connectors use
+// `d-line`; for curves, a path. A line's stroke is centered on its geometry,
+// so it straddles the box (a rect's paints inside), and the bounds it
+// reports are the painted box: geometry plus stroke, on both forms.
+//
+// The paint defaults to `drawStyle="stroke"` (the box primitives default to
+// fill). On a polyline "fill" and "stroke-and-fill" fill the polygon
+// (nonzero, implicitly closed) and hit-test its interior; on the two-point
+// form fill has no effect, a segment has no interior.
+export interface LineProps extends PaintProps, PointerProps, DashProps {
+  /**
+   * Polyline vertices as a flat [x0, y0, x1, y1, ...] in the element's local
+   * space (the space x1..y2 use). Takes precedence over the endpoints while
+   * set. Content, not box geometry: a laid-out <line points> measures its
+   * box from the points' extent, like a <path> from `d`, and draws them
+   * unscaled. Fewer than two points draws nothing; an odd count throws. Not
+   * covered by transitions: animate by writing a new array.
+   */
+  points?: number[] | Float32Array | Float64Array
+  /**
+   * Close the polyline's stroke: the segment back to the first point, joined
+   * there instead of capped. A fill always covers the polygon (closed
+   * implicitly), so this is a stroke distinction. Default false.
+   */
+  closed?: boolean
 }
 
-export interface PathProps extends PaintProps, PointerProps {
+/**
+ * `d` is an SVG path string; the stroke is centered on the geometry. The
+ * bounds a path reports (getBoundingBox, the tree, a detached capture) are
+ * its painted box: the geometry's tight extent (curve extrema, not control
+ * points) plus the stroke's reach, at a `d-path`'s x/y - not its layout box
+ * or the inherited one.
+ */
+export interface PathProps extends PaintProps, PointerProps, DashProps {
   d?: string
   fillRule?: "nonzero" | "evenodd"
 }

package/src/window.ts

@@ -208,14 +208,49 @@ export function keyboardHeight(): number {
   return keyboardHeightAccessor()
 }
 
+// Post-layout handlers run in registration order from one bus subscription,
+// then pending reactive writes are flushed once. The postLayout emit is a JS
+// entry inside the frame (layout has run, paint has not), and the runtime's
+// microtask checkpoint only comes after the whole frame closure, so a signal
+// write made by a handler would otherwise reach its node a frame late. The
+// drain lives here, the way runFrame drains before renderFrame, so that no
+// handler has to flush for itself. A throwing handler skips neither the
+// handlers after it nor the flush.
+let layoutHandlers: (() => void)[] = []
+let layoutSubscribed = false
+
+function runLayoutHandlers() {
+  for (let fn of [...layoutHandlers]) {
+    try {
+      fn()
+    } catch (err) {
+      console.error("Error in onLayout handler:", err)
+    }
+  }
+  try {
+    flush()
+  } catch (err) {
+    console.error("Error in reactive flush:", err)
+  }
+}
+
 /**
  * Fires after layout has been computed for the current frame but before paint.
- * Setting properties that affect layout from this callback will be picked up
- * by a re-layout pass before painting (one extra pass; cascades beyond that
- * paint stale).
+ * Property writes made from this callback, direct or through signals (pending
+ * reactive writes are flushed once every handler has run), are picked up by a
+ * re-layout pass before painting (one extra pass; cascades beyond that paint
+ * stale).
  */
 export function onLayout(fn: () => void) {
-  let unsubscribe = on("postLayout", fn)
+  if (!layoutSubscribed) {
+    layoutSubscribed = true
+    on("postLayout", runLayoutHandlers)
+  }
+  layoutHandlers.push(fn)
+  let unsubscribe = () => {
+    let i = layoutHandlers.indexOf(fn)
+    if (i >= 0) layoutHandlers.splice(i, 1)
+  }
   onCleanup(unsubscribe)
   return unsubscribe
 }
@@ -274,10 +309,20 @@ export function onBack(fn: (e: BackEvent) => void) {
 
 // ------ Window ----------------
 
-export function attachWindow(nodeId: number) {
+// The window root's id: the key-routing fallback target and the pointer
+// interest root. Set by attachWindow, moved by setWindowRoot when render()'s
+// error boundary swaps the app's window for the error window and back.
+let windowRootId = 0
+
+export function setWindowRoot(nodeId: number) {
+  windowRootId = nodeId
   // The root carries the ambient move-interest bit for global onPointerMove
   // subscribers (it is on every hit path); see core.setInterestRoot.
   setInterestRoot(nodeId)
+}
+
+export function attachWindow(nodeId: number) {
+  setWindowRoot(nodeId)
   let unsubscribe: () => void = null!
   let unsubDown: () => void = null!
   let unsubUp: () => void = null!
@@ -426,13 +471,13 @@ export function attachWindow(nodeId: number) {
     // at dispatch time from current focus (nothing to freeze: keyup follows
     // focus, as in the DOM).
     let dispatchKey = (raw: any, handler: string) => {
-      let target = focusedNode() ?? nodeId
+      let target = focusedNode() ?? windowRootId
       let stopped = false
       let e = { ...raw, target, stopPropagation: () => (stopped = true) }
       let path = getNodePath(target)
       // A focused node detached this tick has no chain to the root; the
       // window root must still hear the key.
-      if (path[path.length - 1] !== nodeId) path.push(nodeId)
+      if (path[path.length - 1] !== windowRootId) path.push(windowRootId)
       for (let id of path) {
         e.currentTarget = id
         getEventHandler(id, handler)?.(e)