npm - prop-for-that - Versions diffs - 0.6.4 - Mend

prop-for-that 0.6.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (28) hide show

package/CHANGELOG.md +369 -0
package/LICENSE +21 -0
package/README.md +76 -0
package/dist/auto.cjs +1 -0
package/dist/auto.d.cts +2 -0
package/dist/auto.d.ts +2 -0
package/dist/auto.global.js +1 -0
package/dist/auto.js +1 -0
package/dist/chunk-6DXNWAGS.js +1 -0
package/dist/chunk-LWKH66VY.js +1 -0
package/dist/head.cjs +1 -0
package/dist/head.d.cts +2 -0
package/dist/head.d.ts +2 -0
package/dist/head.global.js +1 -0
package/dist/head.js +1 -0
package/dist/index.cjs +1 -0
package/dist/index.d.cts +37 -0
package/dist/index.d.ts +37 -0
package/dist/index.global.js +1 -0
package/dist/index.js +1 -0
package/dist/plugins.cjs +1 -0
package/dist/plugins.d.cts +328 -0
package/dist/plugins.d.ts +328 -0
package/dist/plugins.js +1 -0
package/dist/types-BYVnuPvd.d.cts +64 -0
package/dist/types-BYVnuPvd.d.ts +64 -0
package/llms.txt +204 -0
package/package.json +83 -0

package/llms.txt ADDED Viewed

@@ -0,0 +1,204 @@
+# prop-for-that
+> Expose runtime state that JavaScript knows but CSS can't see, as batched, diffed
+> CSS custom properties. CSS then computes and reacts to it via `var()` (continuous
+> values) or `@container style()` (discrete values), with no JS in the animation path.
+prop-for-that reads browser/runtime state (pointer, viewport, element size,
+visibility, slider values, network, battery, sensors, and more) and writes it into
+`--live-*` (reactive) and `--const-*` (write-once) custom properties. A single
+`requestAnimationFrame` writer coalesces all updates and only calls `setProperty`
+when a value actually changed. Zero runtime dependencies, tree-shakeable, TypeScript.
+## Entry points
+- `prop-for-that`: the core API (`configure`, `register`, `unregister`, `propsFor`, `unbind`, `reset`).
+- `prop-for-that/auto`: side-effecting. On load it attaches the default globals (`viewport`, `pointer`) to `:root`, scans the DOM for `[data-props-for="key1 key2"]` and binds those sources, and watches the DOM with a `MutationObserver`. If the root `<html>` has the boolean attribute `data-props-typed`, it calls `configure({ typed: true })` first (markup equivalent; read once on load; global, no per-key subset).
+- `prop-for-that/head`: side-effecting. Synchronously writes FOUC-safe constants before first paint. Inline it in `<head>`.
+- `prop-for-that/plugins`: opt-in plugin sources, plus `registerPlugins` and `allPlugins`.
+Build outputs: ESM + CJS + `.d.ts`. Browser-only; entries guard `typeof document`, so importing is SSR-safe (sources attach client-side).
+## Install
+```bash
+npm i prop-for-that
+```
+## Mental model
+1. A **source** reads one group of state. It has a `key` (used in `propsFor`/`data-props-for`), a `scope` (`global` → writes to `:root`; `element` → writes to the bound element), and a `start(ctx)` that attaches listeners/observers and returns a disposer.
+2. Sources call `ctx.write(localName, value, cadence?)`, never `setProperty` directly. The **Writer** queues writes and flushes once per `requestAnimationFrame`, diffing against the last value written.
+3. CSS consumes the resulting custom properties:
+   - **`var()`** for continuous values (ratios, dimensions), composed with `calc()`.
+   - **`@container style()`** for discrete/boolean/integer values (equality match). Every element is a style-query container by default; no `container-type` needed.
+## API
+```ts
+import { configure, register, unregister, propsFor, unbind, reset, pause, resume } from 'prop-for-that'
+configure(opts: Partial<Config>): void   // call once, before any propsFor()
+register(source: Source): void           // add a custom/plugin source by key
+unregister(key: SourceKey): void         // remove a source from the registry
+propsFor(keys: string[]): Disposer       // global: attach sources to config.root (:root)
+propsFor(target: Element | NodeList | Element[], keys: string[]): Disposer  // per element(s)
+unbind(target: HTMLElement, keys?: string[]): void    // detach some/all
+reset(): void                            // tear down every binding + shared observers/listeners
+pause(): void                            // freeze the loop (no sampling/flushing); idempotent
+resume(): void                           // unfreeze; flushes anything queued while paused
+// propsFor is global unless the first arg is a Node, NodeList, or array of elements.
+// Its disposer tears down only what that call started and removes the properties it wrote.
+interface Config { livePrefix: string; constPrefix: string; root: HTMLElement; typed: boolean; defaults?: Record<string, string|number>; liveHz?: number }
+// defaults: livePrefix '--live-', constPrefix '--const-', root document.documentElement, typed false, liveHz unset (every frame)
+// config.defaults are typed @property initial values, keyed by a source's local name
+// liveHz caps loop sampling+flushing rate (e.g. 30); fewer writes = less style recalc + calmer DevTools
+interface Source {
+  key: SourceKey
+  scope: 'global' | 'element'
+  start(ctx: SourceContext): Disposer
+}
+interface SourceContext {
+  target: HTMLElement
+  config: Config
+  write(localName: string, value: string | number, cadence?: 'live' | 'const'): void
+}
+type Disposer = () => void
+```
+Plugins:
+```ts
+import { registerPlugins, allPlugins, battery /* …named exports */ } from 'prop-for-that/plugins'
+registerPlugins()                 // register every plugin
+registerPlugins(battery, clock)   // register a subset
+```
+`propsFor()` returns a disposer; re-attaching an already-active key on the same target is a no-op.
+## Variable catalog (canonical)
+All names below are the full property names. Reactive values use the `--live-`
+prefix; constants use `--const-`. Values are unitless numbers unless noted.
+### Core sources (in the main bundle)
+| key | scope | properties |
+| --- | --- | --- |
+| `viewport` | global | `--live-vw`, `--live-vh` |
+| `pointer` | global | `--live-pointer-x`, `--live-pointer-y`, `--live-pointer-x-ratio` (0–1), `--live-pointer-y-ratio` (0–1) |
+| `size` | element | `--live-w`, `--live-h`, `--live-aspect` (w/h) |
+| `visibility` | element | `--live-visible` (1/0, whole element in viewport), `--const-has-entered` (1/0, latches once entirely in viewport, never resets) |
+| `range` | element | `--live-value`, `--live-value-pct` (0–1). Bind the `<input>` or a container holding one. |
+### Head constants (`prop-for-that/head`)
+| property | value |
+| --- | --- |
+| `--const-scrollbar-w` | scrollbar width in px |
+| `--const-scrollbar-thin-w` | scrollbar width in px with `scrollbar-width: thin` (= `--const-scrollbar-w` where unsupported) |
+| `--const-dpr` | `devicePixelRatio` |
+| `--const-cores` | `navigator.hardwareConcurrency` |
+| `--const-mem` | `navigator.deviceMemory` in GiB (Chromium-only, coarse; `0` elsewhere) |
+### Plugins (`prop-for-that/plugins`)
+Import name is camelCase; the key for `propsFor`/`data-props-for` is the dashed form.
+| import | key | scope | properties |
+| --- | --- | --- | --- |
+| `scrollVelocity` | `scroll-velocity` | global | `--live-scroll-velocity` (signed px/frame), `--live-scroll-direction` (1/-1/0) |
+| `online` | `online` | global | `--live-online` (1/0) |
+| `pageFocused` | `page-focused` | global | `--live-page-focused` (1/0 — tab frontmost and window focused; `0` when switched away) |
+| `pageVisible` | `page-visible` | global | `--live-page-visible` (1/0 — tab foreground vs hidden/backgrounded; `document.visibilityState`. A visible tab can still be unfocused) |
+| `navType` | `nav-type` | global | `--const-nav-type` (write-once string — how the user arrived: `navigate` / `reload` / `back_forward` / `prerender`, from `performance.getEntriesByType('navigation')[0].type`. Pairs with `@container style(--const-nav-type: reload)`) |
+| `network` | `network` | global | `--live-net-downlink`, `--live-net-rtt`, `--live-net-save-data` (1/0), `--live-net-type` (slow-2g=1…4g=4, else 0) |
+| `battery` | `battery` | global | `--live-battery-level` (0–1), `--live-battery-charging` (1/0) |
+| `clock` | `clock` | global | `--live-now` (epoch seconds), `--live-hours`, `--live-minutes`, `--live-seconds` |
+| `fps` | `fps` | global | `--live-fps` |
+| `visualViewport` | `visual-viewport` | global | `--live-vvp-scale`, `--live-vvp-offset-top`, `--live-vvp-height` |
+| `orientation` | `orientation` | global | `--live-orient-alpha`, `--live-orient-beta`, `--live-orient-gamma` (deg) |
+| `motion` | `motion` | global | `--live-accel-x`, `--live-accel-y`, `--live-accel-z` (m/s²) |
+| `geo` | `geo` | global | `--live-geo-lat`, `--live-geo-lng`, `--live-geo-accuracy` (m) |
+| `cpuPressure` | `cpu-pressure` | global | `--live-cpu-pressure` (Compute Pressure tier: nominal=0, fair=1, serious=2, critical=3) |
+| `pointerLocal` | `pointer-local` | element | `--live-local-pointer-x-ratio`, `--live-local-pointer-y-ratio` (0–1 within the element), `--live-local-pointer-inside` (1/0) |
+| `media` | `media` | element | `--live-current-time`, `--live-duration`, `--live-progress` (0–1), `--live-paused` (1/0), `--live-volume` (0–1) |
+| `field` | `field` | element | `--live-length`, `--live-empty` (1/0), `--live-valid` (1/0); per-reason validity flags (each 1/0) `--live-value-missing`, `--live-type-mismatch`, `--live-pattern-mismatch`, `--live-too-long`, `--live-too-short`, `--live-range-underflow`, `--live-range-overflow`, `--live-step-mismatch`, `--live-bad-input`, `--live-custom-error`; and with `maxlength`: `--live-remaining`, `--live-fill-pct` (0–1) |
+| `select` | `select` | element | `--live-index` (selectedIndex, -1 if none), `--live-option-count`, `--live-index-pct` (0–1), `--live-value-num` (numeric value only), `--live-selected-count`, `--live-selected-pct` (0–1, counts a `<select multiple>` CSS can't tally). Bind the `<select>` or a container. |
+| `colorInput` | `color-input` | element | `--live-color` (the `<input type="color">` value as sRGB hex; typed mode registers it `<color>`). Bind the input or a container. |
+| `fieldState` | `field-state` | element | form interaction history (all 1/0): `--live-dirty`/`--live-pristine` (user has edited it; latches), `--live-touched`/`--live-untouched` (blurred at least once; latches), `--live-changed` (current value ≠ mount value; un-latches), `--live-submitted` (owning `<form>` submitted). Bind a single field for its state, or a `<form>`/wrapper for the aggregate over all its fields. |
+| `formState` | `form-state` | element | form-level validity/completion CSS can't count: `--live-field-count`, `--live-valid-count`, `--live-invalid-count`, `--live-all-valid` (1/0 submit gate), `--live-completion` (0–1, valid required ÷ required). Bind a `<form>`/wrapper. |
+| `img` | `img` | element | `--live-natural-w`, `--live-natural-h` (intrinsic px), `--live-loaded` (1/0), `--live-broken` (1/0). Bind the `<img>` or a container holding one. |
+| `imgColor` | `img-color` | element | a palette from an `<img>`, all from one 16×16 bucketing pass (createImageBitmap+OffscreenCanvas). Each swatch is a single sRGB hex colour (no channel props — use relative colour syntax / color-mix to extract): `--live-img` (dominant), `--live-img-accent` (most vibrant), `--live-img-dark` (darkest non-black), `--live-img-light` (lightest non-white), `--live-img-avg` (mean). Plus `--live-img-temp` (−1 cool…+1 warm). Accent reuses the dominant for grayscale. Cross-origin needs `crossorigin` + CORS, else no-ops. Bind the `<img>` or a container. |
+| `videoColor` | `video-color` | element | live colours of a playing `<video>`, each a single sRGB hex colour: `--live-video` (dominant) + `--live-video-accent` (most vibrant; reuses the dominant for a grayscale frame). Both from one 16×16 read on `requestVideoFrameCallback` (stops when paused/offscreen/backgrounded), throttled to ~4 Hz; seeds a paused/poster frame; falls back to `timeupdate`. Cross-origin needs `crossorigin` + CORS, else no-ops. Bind the `<video>` or a container. |
+## Recipes
+Zero-config (attributes):
+```html
+<script type="module">import 'prop-for-that/auto'</script>
+<input type="range" data-props-for="range">
+<section data-props-for="size visibility">…</section>
+```
+Imperative:
+```js
+import { propsFor } from 'prop-for-that'
+propsFor(['pointer'])                 // writes pointer vars to :root
+propsFor(el, ['size', 'visibility'])  // writes element vars to el
+```
+A plugin:
+```js
+import { register, propsFor } from 'prop-for-that'
+import { battery } from 'prop-for-that/plugins'
+register(battery)
+propsFor(['battery'])
+```
+Container-bound range (so siblings can read the value):
+```js
+// the source finds the inner <input> but writes the vars on the wrapper
+propsFor(document.querySelector('.meter'), ['range'])
+```
+Continuous reaction with `var()`:
+```css
+.card { transform: rotateY(calc((var(--live-pointer-x-ratio) - 0.5) * 16deg)); }
+```
+Discrete reaction with a style query:
+```css
+@container style(--live-online: 0) { .banner { display: block; } }
+@container style(--live-value: 100) { .badge { color: var(--accent); } }
+```
+## Gotchas (read before writing CSS)
+- **Custom properties inherit downward only.** An `element`-scoped source writes its vars on the bound element. To let *sibling* elements react, bind a common ancestor. `range` and `field` help here: bind them to a container and they find the inner `<input>`, writing the vars on the container.
+- **Pick the right consumer.** Continuous numbers go through `var()` + `calc()`. Discrete/boolean/integer values use `@container style()`, which matches on **equality only** (range comparisons like `style(--x < 5)` are not stable yet). Emit booleans/tiers when you need thresholds.
+- **`visibility` is binary + latched, not a ratio.** It writes `--live-visible` and `--const-has-entered`. There is no continuous visible-ratio and no scroll-position source: use native `animation-timeline: scroll()` / `view()` for continuous scroll-driven effects.
+- **Values are unitless.** Multiply by `1px`, `1deg`, `100%`, etc. in CSS.
+- **Configure prefixes before attaching.** `configure({ livePrefix, constPrefix })` must run before any `propsFor()`.
+- **Typed properties are opt-in.** `configure({ typed: true })` (before attaching) registers each written `--live-*` with `@property` so it interpolates (consumers add `transition`/`@keyframes`) and resolves to `0` before a value arrives. With the `auto` entry, `<html data-props-typed>` is the markup equivalent (boolean, read once on load; typing is global per `@property` name, so no per-key subset). It is a one-way door (no unregister), uses `inherits: true`, is feature-detected, and skips names already registered. Sources can declare per-property `props: { name: { syntax, initial, inherits } }` (default `<number>` / `0` / inherited); consumers can set initials with `configure({ typed: true, defaults: { 'pointer-x-ratio': 0.5 } })` (keyed by local name).
+- **Permission-gated plugins** (`orientation`, `motion`, `geo`) and unsupported APIs feature-detect and no-op; registering them is always safe. On iOS some need a user-gesture permission grant before values arrive. `cpuPressure` is Chromium-only and needs a secure context + the `compute-pressure` Permissions Policy; it seeds `--live-cpu-pressure: 0` where supported, writes nothing where not.
+- **Global writes land in an adopted stylesheet, not `<html>` inline style.** Root `--live-*` go into one constructable, adopted `:root {}` rule (element-scoped writes stay inline; the `head` entry still writes `--const-*` inline for first paint). Keeps the DevTools Styles panel usable under per-frame churn; `var()`/`calc()` consumption is identical (still inherits). Reading `documentElement.style` directly won't show them — read computed style. Falls back to inline where constructable stylesheets are unsupported.
+- **Freeze or throttle the loop.** `pause()` / `resume()` stop and restart sampling+flushing (values hold steady; bindings stay attached). `configure({ liveHz: 30 })` caps the rate to reduce mutations/recalc, throttling samplers (`fps`, `scroll-velocity`) too.
+## Links
+- [Documentation](https://prop-for-that.netlify.app/docsite/): full guides, concepts, and API.
+- [Plugin & source reference](https://prop-for-that.netlify.app/docsite/reference/plugins/): every source, key, and property.
+- [Live demos](https://prop-for-that.netlify.app/): interactive examples of each source.
+- [Under consideration](https://prop-for-that.netlify.app/docsite/considered/): deferred/proposed sources and voting.
+- [Repository](https://github.com/argyleink/prop-for-that): source, issues, changelog, contributing.

package/package.json ADDED Viewed

@@ -0,0 +1,83 @@
+{
+  "name": "prop-for-that",
+  "version": "0.6.4",
+  "description": "Expose what JavaScript knows but CSS can't see, as batched, diffed CSS custom properties.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/argyleink/prop-for-that.git"
+  },
+  "author": "Adam Argyle (https://github.com/argyleink)",
+  "keywords": [
+    "css",
+    "custom-properties",
+    "css-variables",
+    "reactive",
+    "state",
+    "dom",
+    "battery",
+    "network",
+    "geolocation",
+    "device-orientation",
+    "scroll-velocity",
+    "fps"
+  ],
+  "sideEffects": [
+    "./dist/auto.js",
+    "./dist/auto.cjs",
+    "./dist/head.js",
+    "./dist/head.cjs"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./auto": {
+      "types": "./dist/auto.d.ts",
+      "import": "./dist/auto.js",
+      "require": "./dist/auto.cjs"
+    },
+    "./head": {
+      "types": "./dist/head.d.ts",
+      "import": "./dist/head.js",
+      "require": "./dist/head.cjs"
+    },
+    "./plugins": {
+      "types": "./dist/plugins.d.ts",
+      "import": "./dist/plugins.js",
+      "require": "./dist/plugins.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "llms.txt",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsup",
+    "build:demos": "cd demos && npm install && npm run build",
+    "build:docs": "cd docs && npm install && DOCS_BASE=/docsite npm run build",
+    "build:site": "npm run build:demos && npm run build:docs && node scripts/assemble-site.mjs",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:e2e": "playwright test",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.49.1",
+    "jsdom": "^25.0.1",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  }
+}