@solidrt/core 0.0.14 → 0.0.16

package/examples/README.md

@@ -0,0 +1,27 @@
+# @solidrt/core examples
+
+Single-concept SolidRT patterns. Each file is a complete, runnable app (ends in
+`render(() => <App />)`) demonstrating exactly one thing - copy one and adapt it.
+For the SolidJS 2.0 reactivity/control-flow model see `solid-js/CHEATSHEET.md`;
+for the element/prop model see `@solidrt/core/AGENTS.md`.
+
+## Host elements and layout
+- `window-root.tsx` - the minimal app; the root must be `<window>`.
+- `view-layout.tsx` - `<view>` as a flex container; containers do not paint.
+- `background-rect.tsx` - a `d-rect` filling its parent as a background.
+- `detached-positioning.tsx` - the `d-` prefix: x/y placement, no reflow, detached-only children.
+- `text-paint-styling.tsx` - the uniform `color` prop; `drawStyle="stroke"` vs fill.
+
+## Frame and lifecycle
+- `frame-animation.tsx` - `onFrame` driving a transform animation each frame.
+- `on-layout-connect.tsx` - `onLayout` + `getBoundingBox` connecting laid-out boxes with a `d-path`.
+
+## Window state
+- `window-signals.tsx` - reactive `windowSize()` / `safeArea()` accessors (prefer over `onResize`).
+
+## Overlays
+- `portal.tsx` - `createPortal` relocating content to the window root to escape clipping.
+
+## Images and GPU
+- `image.tsx` - `createImage` (async value: fetch + decode + upload) read inside a `<Loading>` boundary and shown with `<texture>`.
+- `gpu-shader.tsx` - a GLSL fragment shader rendered to a texture, animated via `setShaderParams`.

package/examples/background-rect.tsx

@@ -0,0 +1,15 @@
+// Containers do not paint, so a background is just a draw primitive placed behind
+// the content. A d- primitive with no x/y/w/h fills its parent, which is exactly
+// what you want for a background. Put it FIRST so siblings paint on top of it.
+import { render } from "@solidrt/core"
+
+function App() {
+  return (
+    <window alignItems="center" justifyContent="center">
+      <d-rect color="#1a3380" />
+      <text fontSize={28} color="#ffffff">Content on a full-bleed background</text>
+    </window>
+  )
+}
+
+render(() => <App />)

package/examples/detached-positioning.tsx

@@ -0,0 +1,21 @@
+// The d- prefix means "detached from layout": the layout engine ignores it and
+// you place it yourself with x/y. Because a detached node does not participate in
+// layout, moving it (animating x/y) does not reflow its siblings - which makes
+// d- elements the right choice for overlays, badges, and anything that moves
+// independently. The rule: a detached node can only contain other detached
+// nodes. Everything under a d- element must itself be a d- element (here d-rect +
+// d-text) - nesting a plain <view> or <text> inside a d- element is an error.
+import { render } from "@solidrt/core"
+
+function App() {
+  return (
+    <window>
+      <d-view x={40} y={60}>
+        <d-rect w={160} h={64} radius={12} color="#3366b3" />
+        <d-text x={16} y={20} fontSize={18} color="#ffffff">Badge</d-text>
+      </d-view>
+    </window>
+  )
+}
+
+render(() => <App />)

package/examples/frame-animation.tsx

@@ -0,0 +1,26 @@
+// onFrame(fn) is the per-frame animation hook. tick is runtime-paced time in ms
+// (smooth even when frame times jitter), frame is the present count, rate is the
+// refresh rate in Hz. Drive a signal from the tick and read it in JSX - the graph
+// repaints each frame. A pending onFrame is a standing request for the next
+// frame, so the loop runs only while something is animating and stops when the
+// callback is cleaned up (automatic within a reactive scope).
+//
+// Animate a transform (rotate / scale / x / y on a <view>), not a layout prop:
+// transforms are applied at paint time, while animating width/margin/etc would
+// re-run layout every frame.
+import { render, onFrame, createSignal } from "@solidrt/core"
+
+function App() {
+  let [angle, setAngle] = createSignal(0)
+  onFrame((tick) => setAngle(tick / 1000)) // radians; ~1 turn every 6.3s
+
+  return (
+    <window alignItems="center" justifyContent="center">
+      <view width={120} height={120} rotate={angle()}>
+        <rect width={120} height={120} radius={16} color="#3366b3" />
+      </view>
+    </window>
+  )
+}
+
+render(() => <App />)

package/examples/gpu-shader.tsx

@@ -0,0 +1,36 @@
+// createShader compiles a GLSL ES 3.00 fragment shader and renders it into a
+// texture, returning a texture id you display with <texture src={id}>. The
+// fragment body may reference vUV (0..1, top-left origin), iResolution, iTime, and
+// any `uniform float` it declares; there is no #version line - the runtime injects
+// the preamble. The texture is freed automatically when the reactive owner is
+// disposed.
+//
+// iResolution is filled in for you, but iTime is NOT - drive it (and any other
+// uniform) yourself with setShaderParams from onFrame to animate. The shader's
+// size is baked in at creation.
+import { render, onFrame } from "@solidrt/core"
+import { createShader, setShaderParams } from "@solidrt/core/gpu"
+
+let FRAGMENT = `
+void main() {
+  vec2 uv = vUV;
+  float t = iTime * 2.0;
+  float a = 0.5 + 0.5 * sin(uv.x * 10.0 + t);
+  float b = 0.5 + 0.5 * sin(uv.y * 10.0 - t * 1.3);
+  float c = 0.5 + 0.5 * sin((uv.x + uv.y) * 8.0 + t * 0.7);
+  fragColor = vec4(a, b, c, 1.0);
+}
+`
+
+function App() {
+  let id = createShader(FRAGMENT, 512, 512, { iTime: 0 })
+  onFrame((tick) => setShaderParams(id, { iTime: tick / 1000 }))
+
+  return (
+    <window alignItems="center" justifyContent="center">
+      <texture src={id} width={400} height={400} />
+    </window>
+  )
+}
+
+render(() => <App />)

package/examples/image.tsx

@@ -0,0 +1,27 @@
+// createImage loads an image as a SolidJS 2.0 async value and returns an accessor
+// for its GPU texture id. It handles fetch, decode, GPU upload, and cleanup for
+// you. A string source is fetched; a Uint8Array is decoded directly. The texture
+// carries its own pixel size, so <texture> needs no width/height to show it at
+// natural size - pass them only to scale it.
+//
+// Reading img() suspends until ready, so read it inside a <Loading> boundary
+// (this is the 2.0 async mechanic, not a manual undefined-signal + <Show>); a
+// load failure surfaces to <Errored>. Pass an accessor (createImage(() => src()))
+// to make the source reactive - the image reloads and the old texture is freed.
+// For manual control, decodeImage + createTexture (from @solidrt/core/gpu) are
+// the primitives underneath.
+import { render, createImage, Loading } from "@solidrt/core"
+
+function App() {
+  let img = createImage("https://picsum.photos/seed/solidrt/400/300")
+
+  return (
+    <window alignItems="center" justifyContent="center">
+      <Loading fallback={<text color="#888">loading...</text>}>
+        <texture src={img()} />
+      </Loading>
+    </window>
+  )
+}
+
+render(() => <App />)

package/examples/on-layout-connect.tsx

@@ -0,0 +1,39 @@
+// onLayout(fn) fires after layout is computed but before paint - the one point
+// where measured geometry is available via getBoundingBox (a window-relative
+// snapshot, valid only here or in an event handler). Its canonical use is to
+// connect or annotate laid-out elements with detached drawing: let the layout
+// engine place the boxes, read their boxes, then draw a d-path between them.
+//
+// Two rules make it safe:
+//  1. Write the result to something that does NOT affect layout - a d-path's `d`,
+//     a detached node's position. Writing a layout-affecting prop here forces an
+//     extra layout pass every frame.
+//  2. Call flush() after the write so it lands before the display list is built
+//     (onLayout runs after the frame's normal flush).
+import { render, onLayout, getBoundingBox, createSignal, flush } from "@solidrt/core"
+
+function App() {
+  let boxA!: { id: number }
+  let boxB!: { id: number }
+  let [d, setD] = createSignal("")
+
+  onLayout(() => {
+    let a = getBoundingBox(boxA)
+    let b = getBoundingBox(boxB)
+    if (!a || !b) return
+    let ax = a.x + a.width / 2, ay = a.y + a.height / 2
+    let bx = b.x + b.width / 2, by = b.y + b.height / 2
+    setD(`M ${ax} ${ay} L ${bx} ${by}`)
+    flush()
+  })
+
+  return (
+    <window flexDirection="row" justifyContent="space-between" alignItems="center" padding={48}>
+      <rect ref={n => (boxA = n)} width={80} height={80} radius={8} color="#3366b3" />
+      <rect ref={n => (boxB = n)} width={80} height={80} radius={8} color="#6699e6" />
+      <d-path d={d()} color="#e0245e" drawStyle="stroke" strokeWidth={3} />
+    </window>
+  )
+}
+
+render(() => <App />)

package/examples/portal.tsx

@@ -0,0 +1,38 @@
+// createPortal relocates an already-built node to the window root (or a given
+// mount), so content declared deep in the tree can escape the layout, clipping,
+// and stacking of its surroundings - the primitive behind overlays like modals,
+// menus, and tooltips. It moves one concrete node and removes it again when the
+// surrounding reactive scope disposes.
+//
+// Key points:
+//  - A JSX element's runtime value IS the built node, so pass the JSX straight to
+//    createPortal. It returns void, so `return createPortal(...)` renders nothing
+//    in place while the content lives at the mount.
+//  - The default mount is the window's flex root, so the portaled node must be
+//    position="absolute" - otherwise it takes flow space and displaces content.
+//  - Pass a second argument (a node captured from a ref) to mount elsewhere.
+import { render, createPortal } from "@solidrt/core"
+
+// Declared inside the clipped card below, but drawn at the window root, on top of
+// everything and outside the card's overflow clip.
+function Banner() {
+  return createPortal(
+    <view position="absolute" top={0} left={0} right={0} padding={12}>
+      <d-rect color="#e0245e" />
+      <text color="#ffffff">Portaled banner - escaped the card</text>
+    </view>
+  )
+}
+
+function App() {
+  return (
+    <window padding={40}>
+      <view flex={1} overflow="hidden" alignItems="center" justifyContent="center">
+        <rect width={140} height={140} radius={8} color="#3366b3" />
+        <Banner />
+      </view>
+    </window>
+  )
+}
+
+render(() => <App />)

package/examples/text-paint-styling.tsx

@@ -0,0 +1,18 @@
+// Painting is uniform across primitives: the `color` prop sets the paint (a CSS
+// color string or a gradient). There is no fill / stroke / background prop. To
+// outline instead of fill, set drawStyle="stroke" and strokeWidth; "stroke-and-
+// fill" does both. The same color prop styles <text>, alongside fontSize /
+// fontWeight / fontFamily.
+import { render } from "@solidrt/core"
+
+function App() {
+  return (
+    <window flexDirection="column" gap={16} padding={24} alignItems="center" justifyContent="center">
+      <text fontSize={28} fontWeight={700} color="#1a3380">Filled text</text>
+      <rect width={160} height={64} radius={12} color="#3366b3" />
+      <oval width={120} height={64} drawStyle="stroke" strokeWidth={4} color="#1a3380" />
+    </window>
+  )
+}
+
+render(() => <App />)

package/examples/view-layout.tsx

@@ -0,0 +1,20 @@
+// <view> is the layout container: a flexbox box positioned by the layout engine.
+// It does NOT paint anything itself - it has no color. To make a box visible you
+// place a draw primitive inside it (here an attached <rect>, which is both laid
+// out and painted). Flex props (flexDirection, gap, padding, alignItems) work as
+// in CSS.
+import { render } from "@solidrt/core"
+
+function App() {
+  return (
+    <window>
+      <view flex={1} flexDirection="column" gap={12} padding={24} justifyContent="center">
+        <rect height={48} radius={8} color="#3366b3" />
+        <rect height={48} radius={8} color="#6699e6" />
+        <rect height={48} radius={8} color="#99c2f0" />
+      </view>
+    </window>
+  )
+}
+
+render(() => <App />)

package/examples/window-root.tsx

@@ -0,0 +1,14 @@
+// The minimal valid app. render() is called once at the top level and the root
+// element MUST be <window> - anything else throws. <window> takes layout props
+// (it is a flex container), so children can be centered here directly.
+import { render } from "@solidrt/core"
+
+function App() {
+  return (
+    <window title="Hello" alignItems="center" justifyContent="center">
+      <text fontSize={24} color="#222">Hello SolidRT</text>
+    </window>
+  )
+}
+
+render(() => <App />)

package/examples/window-signals.tsx

@@ -0,0 +1,29 @@
+// Window state is exposed as reactive accessors - read them in JSX and the UI
+// updates when the window changes. Prefer these over the onResize event callback:
+// they are reactive, sticky (the first read sees the current value), and live for
+// the whole app.
+//
+//   windowSize()   -> { width, height }
+//   safeArea()     -> { top, left, right, bottom } inset distances from each edge
+//   displayScale() -> device pixel ratio
+//
+// safeArea is mostly an interactivity boundary: the platform may intercept
+// touches/gestures inside the insets (system bars, notch, home indicator), so do
+// not place interactive content there. For plain drawing it is usually fine to
+// extend into the left/right insets (full-bleed backgrounds); top and bottom are
+// what matter, since content there - text especially - can be covered. So pad the
+// top/bottom by the inset and let the background fill the whole window.
+import { render, windowSize, safeArea } from "@solidrt/core"
+
+function App() {
+  return (
+    <window>
+      <d-rect color="#101418" />
+      <view flex={1} flexDirection="column" gap={8} paddingTop={safeArea().top} paddingBottom={safeArea().bottom}>
+        <text fontSize={18} color="#e6e6e6">{windowSize().width} x {windowSize().height}</text>
+      </view>
+    </window>
+  )
+}
+
+render(() => <App />)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/core",
-  "version": "0.0.14",
+  "version": "0.0.16",
   "license": "MIT",
   "author": "Antoine van Wel",
   "type": "module",
@@ -19,6 +19,7 @@
   },
   "files": [
     "src/",
+    "examples/",
     "jsx-runtime.d.ts",
     "AGENTS.md"
   ],

package/src/gpu.ts

@@ -6,12 +6,13 @@
 import { getOwner, onCleanup } from "@solidjs/signals"
 import * as gpu from "flux:gpu"
 
-// The imperative destroy, surfaced here for the manual-cleanup path documented
-// on the create* helpers (textures made outside a reactive scope, e.g. after an
-// await, are not auto-freed). Re-exported so callers that depend on
-// @solidrt/core -- like @solidrt/components -- can free textures without
-// importing flux directly.
-export { destroyTexture } from "flux:gpu"
+// Imperative companions to the reactive create* helpers, re-exported so callers
+// that depend on @solidrt/core -- like @solidrt/components -- need not import flux
+// directly: destroyTexture for the manual-cleanup path (textures made outside a
+// reactive scope, e.g. after an await, are not auto-freed), setShaderParams to
+// drive a shader's uniforms over time, and uploadTexture to push new pixels into
+// a mutable texture.
+export { destroyTexture, setShaderParams, uploadTexture } from "flux:gpu"
 
 /**
  * Uploads raw RGBA8 pixels to an immutable GPU texture and returns its id (use

package/src/image.ts

@@ -1,7 +1,10 @@
-// CPU image codec: decode encoded image bytes into raw RGBA8 pixels (and, in
-// future, encode them back). Kept separate from the GPU/texture APIs because no
-// GPU is involved; pair decodeImage with createTexture from "@solidrt/core/gpu"
-// to upload the result.
+// CPU image codec plus the reactive load-and-upload convenience. decodeImage is
+// the raw primitive (no GPU involved); createImage is the owner-aware layer on
+// top that fetches/decodes/uploads for you and swaps the texture when the source
+// changes - the same relationship createTexture/createShader have to flux:gpu.
+
+import { createMemo, onCleanup, NotReadyError } from "@solidjs/signals"
+import { createTexture, destroyTexture } from "./gpu"
 
 export type DecodedImage = {
   data: Uint8Array
@@ -12,8 +15,51 @@ export type DecodedImage = {
 /**
  * Decodes encoded image bytes (PNG, JPEG, and the other formats the runtime's
  * image decoder supports) into raw, tightly-packed RGBA8 pixels plus the
- * decoded dimensions. Feed the result straight into `createTexture`.
+ * decoded dimensions. Feed the result straight into `createTexture`. Use this
+ * when you want manual control; for the common case reach for `createImage`.
  */
 export function decodeImage(bytes: Uint8Array): DecodedImage {
   return image.decodeImage(bytes)
+}
+
+export type ImageSource = string | Uint8Array
+
+/**
+ * Loads an image as an async computation and returns a reactive accessor for its
+ * GPU texture id. This is a SolidJS 2.0 async value: reading it suspends until
+ * the image is ready, so read it inside a `<Loading>` boundary (a load failure
+ * surfaces to `<Errored>`). A string source is fetched; a Uint8Array is decoded
+ * directly. Pass an accessor instead of a value to make the source reactive -
+ * the image reloads and the old texture is freed whenever it changes; the
+ * current texture is freed when the owner is disposed. Display it with
+ * `<texture src={id()} />`; the texture carries its own pixel size, so no
+ * width/height is needed unless you want to scale it.
+ */
+export function createImage(src: ImageSource | (() => ImageSource)): () => number {
+  let getSrc = typeof src === "function" ? src : () => src
+  let generation = 0
+
+  return createMemo<number>(async () => {
+    let source = getSrc()
+    let mine = ++generation
+
+    // Register cleanup synchronously, before the await: an onCleanup added after
+    // an await is orphaned because the reactive owner is not restored across it.
+    // The holder is filled in once the texture exists.
+    let holder = { id: -1 }
+    onCleanup(() => {
+      if (holder.id >= 0) destroyTexture(holder.id)
+    })
+
+    let bytes = typeof source === "string" ? await (await fetch(source)).bytes() : source
+
+    // If the source changed while we were loading, this run is superseded. Skip
+    // the GPU upload and stay pending: a texture created here would leak, since
+    // superseded async runs are not otherwise cleaned up. The newer run wins.
+    if (mine !== generation) throw new NotReadyError()
+
+    let { data, width, height } = decodeImage(bytes)
+    holder.id = createTexture(data, width, height)
+    return holder.id
+  })
 }

package/src/index.ts

@@ -6,8 +6,8 @@ export type { Gradient, GradientStop } from "./color"
 export { onFrame, onLayout, onResize, onWindowFocus, onWindowBlur } from "./window"
 export { windowSize, safeArea, displayScale, windowFocused, keyboardHeight } from "./window"
 export { createTexture } from "./gpu"
-export { decodeImage } from "./image"
-export type { DecodedImage } from "./image"
+export { createImage, decodeImage } from "./image"
+export type { DecodedImage, ImageSource } from "./image"
 export type {
   LayoutProps,
   TransformProps,
@@ -52,6 +52,7 @@ export {
   mapArray,
   repeat,
   untrack,
+  flush,
   onCleanup,
   onSettled,
 } from "@solidjs/signals"