@solidrt/core 0.0.49 → 0.0.51

package/src/types.d.ts

@@ -131,6 +131,21 @@ export interface LayoutProps extends FlexboxProps, GridProps {
   overflow?: "visible" | "clip" | "hidden" | "scroll"
   overflowX?: "visible" | "clip" | "hidden" | "scroll"
   overflowY?: "visible" | "clip" | "hidden" | "scroll"
+
+  /**
+   * As an inline atom (an element child of <text>): leave the flow and sit
+   * against that side of the text, at the top of the line where the atom
+   * occurs; the lines it overlaps wrap around its margin box. Same-side
+   * floats overlapping vertically sit beside each other. The text's height
+   * includes the float. Meaningless outside a <text>.
+   */
+  float?: "left" | "right"
+  /**
+   * As an inline atom: start a new line below the text's earlier floats on
+   * that side (a floated atom goes below them instead of beside). An empty
+   * `<view clear="both" />` is the section break after an image.
+   */
+  clear?: "left" | "right" | "both"
 }
 
 /** Colors are CSS color strings, parsed to a packed u32 by `parseColor`. */
@@ -221,6 +236,14 @@ export interface PointerEvent {
    */
   parentX: number
   parentY: number
+  /**
+   * Pointer movement since the previous move event, in logical pixels. Mouse
+   * reports hardware deltas (summed, never lost, and the only motion signal
+   * while the pointer is locked); touch reports position diffs. 0 on
+   * non-move events.
+   */
+  movementX: number
+  movementY: number
   /** Node id whose handler is currently running (bubbling changes it per call). */
   currentTarget: number
   /** Deepest node id of the event's path (the hit leaf). */
@@ -351,6 +374,154 @@ export interface LineGeometryProps {
   y2?: number
 }
 
+// Native transitions (okf/done/native-transitions.md): declared once on
+// the element, applied by the runtime to every later write of the covered
+// properties. JS hands over targets; Rust interpolates every frame, so a
+// running animation costs no JS per frame.
+
+/** A cubic-bezier timing curve: a CSS name or [x1, y1, x2, y2] control values. */
+export type TransitionCurve = "linear" | "ease" | "ease-in" | "ease-out" | "ease-in-out" | [number, number, number, number]
+
+/**
+ * A perceptual spring - the default kind: a bare `{ duration }` is a
+ * critically damped spring. `duration` (ms) is the perceptual settling
+ * time, `bounce` in (-1, 1] the springiness - 0 (the default) settles
+ * without overshoot, positive values overshoot, negative values settle
+ * sluggishly. A new target while the spring runs keeps position and
+ * velocity, so the motion stays continuous - use springs for anything
+ * retargeted while moving.
+ */
+export interface TransitionSpring {
+  duration: number
+  bounce?: number
+  /** Hold each write for this long (ms) before it applies; a newer write during the hold replaces it and restarts the delay. */
+  delay?: number
+  /**
+   * Mount-time enter animation: at the element's first attach the property
+   * snaps to this value and animates to the value it mounted with. Numbers
+   * for the scalar properties; the color property takes a CSS color string
+   * or packed number. Per-property entries only (not under `all`); a later
+   * move or reorder re-runs nothing.
+   */
+  from?: number | string
+  /**
+   * Removal exit animation: an unmounted element stays visible, animates
+   * the property to this value (honoring `delay`), and is freed when its
+   * exit animations settle. Same value forms as `from`, per-property only.
+   * A move never plays it, the exiting element is hit-test invisible, its
+   * whole subtree stays painted with it, and no onTransitionEnd fires (the
+   * component is already disposed). An attached element keeps its layout
+   * slot until the exit finishes.
+   */
+  exit?: number | string
+}
+
+/**
+ * A duration/curve tween, opted into by naming the curve (a tween is
+ * always a specific curve; without one the spec reads as a spring).
+ * Duration in ms. A new target while the tween runs restarts it from the
+ * current value with the full duration (CSS semantics) - designer-timed,
+ * one-shot motion.
+ */
+export interface TransitionTween {
+  duration: number
+  curve: TransitionCurve
+  /** Hold each write for this long (ms) before it applies; a newer write during the hold replaces it and restarts the delay. */
+  delay?: number
+  /**
+   * Mount-time enter animation: at the element's first attach the property
+   * snaps to this value and animates to the value it mounted with. Numbers
+   * for the scalar properties; the color property takes a CSS color string
+   * or packed number. Per-property entries only (not under `all`); a later
+   * move or reorder re-runs nothing.
+   */
+  from?: number | string
+  /**
+   * Removal exit animation: an unmounted element stays visible, animates
+   * the property to this value (honoring `delay`), and is freed when its
+   * exit animations settle. Same value forms as `from`, per-property only.
+   * A move never plays it, the exiting element is hit-test invisible, its
+   * whole subtree stays painted with it, and no onTransitionEnd fires (the
+   * component is already disposed). An attached element keeps its layout
+   * slot until the exit finishes.
+   */
+  exit?: number | string
+}
+
+/**
+ * The shorthand string: `"<duration>ms [curve] [<delay>ms]"` - `"300ms"` is
+ * a bounce-0 spring, `"300ms ease-out"` a tween, `"300ms ease-out 100ms"`
+ * delayed (first time value the duration, second the delay; ms only).
+ * Bounce, bezier control values and `from` need the object form.
+ */
+export type TransitionShorthand = string
+
+export type Transition = TransitionSpring | TransitionTween | TransitionShorthand
+
+/** The property names a transition can cover (numeric scalars). */
+export type TransitionPropName =
+  | "x"
+  | "y"
+  | "w"
+  | "h"
+  | "x1"
+  | "y1"
+  | "x2"
+  | "y2"
+  | "opacity"
+  | "rotate"
+  | "rotateX"
+  | "rotateY"
+  | "scale"
+  | "scaleX"
+  | "scaleY"
+  | "strokeWidth"
+  | "radius"
+  | "color"
+
+/** Payload of onTransitionEnd: which animated property finished. */
+export interface TransitionEndEvent {
+  property: TransitionPropName
+}
+
+export interface TransitionProps {
+  /**
+   * A runtime-side transition of one of this element's properties reached
+   * its target (natural settles only; a cancelled or retargeted animation
+   * does not fire until it finally settles). Delivered to this element
+   * only, no bubbling.
+   */
+  onTransitionEnd?: (event: TransitionEndEvent) => void
+  /**
+   * Animate later writes of the listed properties instead of snapping:
+   * `transition={{ x: { duration: 400, bounce: 0.2 }, opacity: "200ms ease-out" }}`.
+   * `all` covers every animatable property the element has, and a bare
+   * string is shorthand for it: `transition="300ms ease-out"`. Only
+   * properties the element carries animate (a d-rect has x, a view's x is
+   * 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.
+   */
+  transition?:
+    | ({
+        all?: Omit<TransitionSpring, "from" | "exit"> | Omit<TransitionTween, "from" | "exit"> | TransitionShorthand
+        /**
+         * Group stagger (ms): every descendant enter (`from`) or exit that
+         * begins in the same frame under this element gets `index * stagger`
+         * of extra delay, in occurrence order (enters and exits cascade
+         * separately). Nearest declaring ancestor wins; it orchestrates
+         * descendants only - ordinary writes and this element's own
+         * lifecycle are unaffected. Adds on top of a per-entry `delay`.
+         */
+        stagger?: number
+      } & {
+        [P in TransitionPropName]?: Transition
+      })
+    | TransitionShorthand
+    | null
+}
+
 // Primitives
 
 export interface WindowProps extends LayoutProps, PointerProps {
@@ -447,9 +618,10 @@ export interface ViewOwnProps extends TransformProps, PointerProps {
   repaintBoundary?: boolean | "snapshot" | "snapshot-no-aa"
   /**
    * Run this view's rasterized subtree through a GPU program and composite
-   * the result in its place. Requires repaintBoundary="snapshot" (the cost
-   * is snapshot semantics, kept explicit; declared without it the shader is
-   * ignored with a warning). The pass is region-sized and split from content
+   * the result in its place. Requires a snapshot boundary
+   * (repaintBoundary="snapshot" or "snapshot-no-aa"; the cost is snapshot
+   * semantics, kept explicit; declared without one the shader is ignored
+   * with a warning). The pass is region-sized and split from content
    * invalidation: a params-only change re-runs just the pass against the
    * cached snapshot, so animating an effect over a static subtree never
    * re-rasterizes it.
@@ -545,8 +717,12 @@ export interface PathProps extends PaintProps, PointerProps {
   fillRule?: "nonzero" | "evenodd"
 }
 
-export interface TextProps extends PaintProps, PointerProps {
-  children?: Children
+/**
+ * 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 & {})
   fontSize?: number
   /**
@@ -557,8 +733,60 @@ export interface TextProps extends PaintProps, PointerProps {
   lineHeight?: number
   fontStyle?: "normal" | "italic"
   fontWeight?: 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900
+  /**
+   * 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"
+  /** Pixels from the baseline to the top of the underline. */
+  textUnderlineOffset?: number
+  /** Underline thickness in pixels. */
+  textDecorationThickness?: number
+}
+
+/**
+ * A styled run inside <text>. Inline text only: children are text and other
+ * spans. `color` takes what a text's color takes (solid or gradient).
+ * Pointer handlers fire for the boxes of the run's own text on each line it
+ * spans and bubble to the enclosing spans and text.
+ */
+export interface SpanProps extends TextRunProps, PointerProps {
+  children?: Children
+  color?: Color | Gradient
+}
+
+export interface TextProps extends PaintProps, PointerProps, TextRunProps {
+  children?: Children
   textAlign?: "left" | "right" | "center" | "justify"
   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 & {})
+  /**
+   * A word (wrap unit) wider than the line: "anywhere" (default) splits it
+   * at grapheme boundaries so it stays inside the box, "normal" keeps it
+   * whole and lets it overflow (CSS's default).
+   */
+  overflowWrap?: "normal" | "anywhere"
+  /**
+   * First-line indent in pixels. Negative hangs: the first line starts at 0
+   * and every following line is indented by the magnitude. A hard break does
+   * not start a new first line.
+   */
+  textIndent?: number
+  /**
+   * How lines are chosen beyond greedy fitting (CSS text-wrap): "wrap"
+   * (default) is greedy; "balance" evens the line lengths while keeping the
+   * line count (headings, captions); "pretty" is greedy except that a lone
+   * word on the last line pulls one down from the line above. Neither
+   * applies once maxLines truncates.
+   */
+  textWrap?: "wrap" | "balance" | "pretty"
 }
 
 /**

package/src/window.ts

@@ -1,5 +1,5 @@
 import { createSignal, onCleanup, onSettled, flush } from "@solidjs/signals"
-import { requestFrame } from "flux:rendertree"
+import { requestFrame, setPointerLock } from "flux:rendertree"
 import { renderFrame } from "srt:render"
 import { on, once } from "srt:events"
 import { exit } from "srt:app"
@@ -38,9 +38,12 @@ let refreshRate = 60
  * the present count, and `rate` is the current refresh rate in Hz. `tick` is paced
  * by the runtime (one refresh period per present, slow-corrected toward the wall
  * clock) so animations driven off it stay smooth even when swap-return times
- * jitter. performance.now() and timers report/march on this same paced timeline
- * (so the whole time surface freezes together under the dev tools' clock
- * control); for real wall-clock time use Date.now().
+ * jitter, and it is continuous across hot reloads: every tick an instance
+ * sees is on one timebase, so dt is well-defined from the second call on.
+ * Timers freeze together with frame callbacks under the dev tools' clock
+ * control, but measure their delays against the wall clock, not this paced
+ * timeline. performance.now() is not on it either: it is real elapsed time
+ * for measuring work; Date.now() is calendar time.
  * Returns a cleanup function; also auto-cleans within a reactive scope.
  */
 export function onFrame(fn: (tick: number, frame: number, rate: number) => void) {
@@ -161,6 +164,33 @@ export function windowFocused(): boolean {
   return focusedAccessor()
 }
 
+/**
+ * Lock the pointer to the window (relative mouse mode) or release it. While
+ * locked the cursor is hidden and confined, clientX/clientY freeze at the
+ * lock point, and mouse motion keeps reporting through the pointer events'
+ * movementX/movementY - the mouse-look primitive. Window-level, no
+ * permission dance: one app, one window. Observe the applied state through
+ * pointerLocked(); the platform can refuse (no relative mode) and the OS
+ * may drop the lock, e.g. on focus loss.
+ */
+export function lockPointer(locked: boolean) {
+  if (typeof locked !== "boolean") throw new Error(`lockPointer: expected a boolean, got ${typeof locked}`)
+  setPointerLock(locked)
+}
+
+let pointerLockedAccessor: (() => boolean) | undefined
+
+/** Whether the pointer is currently locked (relative mouse mode), as a reactive accessor. */
+export function pointerLocked(): boolean {
+  if (!pointerLockedAccessor) {
+    let [locked, setLocked] = createSignal(false)
+    // Sticky event: a subscriber after the lock still observes the state.
+    on("pointerLock", ({ locked }: { locked: boolean }) => setLocked(locked))
+    pointerLockedAccessor = locked
+  }
+  return pointerLockedAccessor()
+}
+
 let keyboardHeightAccessor: (() => number) | undefined
 
 /**
@@ -255,6 +285,7 @@ export function attachWindow(nodeId: number) {
   let unsubEnter: () => void = null!
   let unsubLeave: () => void = null!
   let unsubWheel: () => void = null!
+  let unsubTransitionEnd: () => void = null!
   let unsubKeyDown: () => void = null!
   let unsubKeyUp: () => void = null!
   let unsubBack: () => void = null!
@@ -263,8 +294,16 @@ export function attachWindow(nodeId: number) {
   let unsubRefreshRate: () => void = null!
   let unsubFirstResize: (() => void) | null = null
 
-  function runFrame(t: number, frame: number) {
-    if (animationFrames.size > 0) {
+  // `bootstrap` marks the synthetic first frame (see the first-resize
+  // subscription below): it flushes and paints the freshly initialized graph
+  // but does not invoke onFrame callbacks, because its timestamp is not a
+  // reading of the frame timeline - handing apps a zero tick gave every
+  // reloaded instance one enormous dt on the next real frame
+  // (okf/done/onframe-tick-reset-on-reload.md). The callbacks stay
+  // registered and run on the first real render event, before the first
+  // paint with their writes applied.
+  function runFrame(t: number, frame: number, bootstrap = false) {
+    if (!bootstrap && animationFrames.size > 0) {
       let frames = animationFrames
       animationFrames = new Map()
       for (let fn of frames.values()) fn(t, frame, refreshRate)
@@ -368,6 +407,17 @@ export function attachWindow(nodeId: number) {
       bubble(raw, "onWheel")
     })
 
+    // A native transition finished (runtime-side animation; see the
+    // `transition` prop). Target-only delivery, no bubbling: the element
+    // that declared the transition is the one interested in its end.
+    unsubTransitionEnd = on("transitionEnd", (raw: { target: number; property: string }) => {
+      try {
+        getEventHandler(raw.target, "onTransitionEnd")?.({ property: raw.property })
+      } catch (err) {
+        console.error("Error in onTransitionEnd handler:", err)
+      }
+    })
+
     // Key events dispatch along the focused node's ancestor chain, leaf->root
     // (the pointer bubbling contract), so a container hears keys from focused
     // descendants and the window root hears everything: <window onKeyDown> is
@@ -429,7 +479,7 @@ export function attachWindow(nodeId: number) {
     // where flush() is illegal (not reentrant). Defer runFrame to a microtask
     // so the first frame always runs after this callback returns.
     unsubFirstResize = once("resize", () => {
-      queueMicrotask(() => runFrame(0, 0))
+      queueMicrotask(() => runFrame(0, 0, true))
     })
   })
 
@@ -442,6 +492,7 @@ export function attachWindow(nodeId: number) {
     if (unsubEnter) unsubEnter()
     if (unsubLeave) unsubLeave()
     if (unsubWheel) unsubWheel()
+    if (unsubTransitionEnd) unsubTransitionEnd()
     if (unsubKeyDown) unsubKeyDown()
     if (unsubKeyUp) unsubKeyUp()
     if (unsubBack) unsubBack()