@pixerate/flair 0.15.0 → 0.17.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @pixerate/flair
 
+## 0.17.0
+
+### Minor Changes
+
+- 6bd52a7: Text effects suit headlines of any length and any theme:
+
+  - **Colours**: colour controls take CSS colours, through `effectDefaults` and the React and Svelte wrappers too. Before, `effectDefaults` silently replaced colour strings with defaults. Hex can be `#rgb`, `#rgba`, `#rrggbb` or `#rrggbbaa`, and `rgb()`/`rgba()` and `hsl()`/`hsla()` work too (see the new `parseColor`). Vector effects also take `currentColor` to follow the surrounding text colour, and colours mixed from it use CSS `color-mix`.
+  - **Long text**: inline text effects keep their full size and the picture gets wider, so long phrases are no longer shrunk. Drip text no longer squashes long words at any size: it scales the whole word down on its own stage and widens inline. Its drips now repeat along the word instead of crowding the middle.
+  - **Overhang**: text effects write `data-overhang="top right bottom left"` (ems) on their `<svg>`, saying how far they reach past their inline box. The new `svgInlineLayout(svg)` in `/vector` reads it with the aspect ratio. In React and Svelte, `contain` turns it into a margin.
+  - **Plays when seen**: in React and Svelte, an effect that plays once (`loop: false`, no trigger) now waits until it is scrolled into view by default. `playOnEnter: false` starts it at mount. `SvgPlayer`'s `playOnEnter` now plays at once where there is no `IntersectionObserver`.
+
+- 6bd52a7: Every text effect now takes `font`, `weight` and `inline` controls, like drip text: typewriter, scramble text, kinetic stagger, neon sign, stroke draw text, split reveal, highlighter, word cycle, liquid fill, glitch text and extruded text.
+
+  - `font` takes any CSS font-family, and `inherit` uses the surrounding text's. `weight` runs from 100 to 900. The defaults keep each effect's current look.
+  - `inline: true` frames just the text, from cap height to baseline, hides the backdrop and sets `overflow="visible"`, so the effect sits in a heading without adding leading. Give its container `display: inline-block; height: 0.72em` and the viewBox's aspect ratio.
+
+## 0.16.0
+
+### Minor Changes
+
+- 55fbb80: New `@pixerate/flair/svelte` entry point, with `svelte` (>= 5) as an optional peer dependency (its types only; nothing to compile):
+
+  - `use:vectorEffect={{ id: "drip-text", values: { word: "Slop" }, loop: false }}` plays a catalog vector effect (or `{ motion }`, any `SvgMotion`) in an element: it makes an `SvgPlayer` on mount, remakes it when the params change (values by content, `speed` without remaking) and disposes it on destroy. Works as an attachment through `fromAction`.
+  - `vectorEffectStill(params)` returns `{ markup, style }` for server rendering: `<span use:vectorEffect={params} style={still.style}>{@html still.markup}</span>` shows the last frame, sized from the viewBox, until the player takes over. The still stays under `prefers-reduced-motion` (`reducedMotion` overrides).
+  - Sized like the React components: a block with the viewBox's aspect ratio, or with `inline` (or an effect's `inline` control) an `inline-block` 0.72em high.
+
 ## 0.15.0
 
 ### Minor Changes

package/README.md

@@ -45,6 +45,7 @@ Flair gives products a library of good-looking, configurable visual effects (her
 | `@pixerate/flair/catalog` | `EFFECTS`, `getEffect`, `findEffects`, `effectDefaults`, `renderVectorEffect`, `vectorControls`, GLSL helpers, sample images, `textImage` | None |
 | `@pixerate/flair/vector` | `SvgMotion`, `svgFrame`, `svgView`, `SvgPlayer`, `svgFrameMarkup`, `svgViewBox`, `animateCount`, `formatCount`, `morphPaths`, `morphSequence`, `svgMotionIssues` | None |
 | `@pixerate/flair/react` | `<VectorEffect>`, `<SvgPlayerView>`: vector effects as React components, server-rendered as a still | `react` ≥ 18 (optional peer) |
+| `@pixerate/flair/svelte` | `vectorEffect` action, `vectorEffectStill`: vector effects in Svelte, server-rendered as a still | `svelte` ≥ 5 (optional peer; types only) |
 | `@pixerate/flair/editor` | `EffectEditor`, effect documents, keyframe tracks, renderer bindings, parameter-panel binding, agent tools and instructions | `@pixerate/editor` ≥ 0.29 (optional peer; only its dependency-free `/history`, `/commands`, `/tools`, `/animation` and `/parameters` subpaths) |
 | `@pixerate/flair/node` | `exportMotionGraphic`: renders a shader to GIF/MP4 through headless Chrome and ffmpeg | Node.js |
 
@@ -133,12 +134,17 @@ animateCount({
 
 With `loop: false` a player plays once and stays on its last frame (like CSS `animation-fill-mode: forwards`); add `hideWhenPaused` to hide it at the end instead.
 
-Drip text can sit inside a heading. Set `inline: true` and the picture frames just the word, from cap height to baseline, while its outline and drips spill over the text around it. Give its container `display: inline-block`, `height: 0.72em` and the viewBox's aspect ratio. `font` and `weight` set its typeface, and `font: "inherit"` takes the heading's:
+Text effects (`category: "text"`) can sit inside a heading:
+
+- **`inline: true`** frames just the text, from cap height to baseline. The backdrop is hidden, and outlines, glows, underlines and drips spill over the text around it. Inline text keeps its full size at any length: the picture gets wider instead of the text shrinking. Give the container `display: inline-block`, `height: 0.72em` and the viewBox's aspect ratio.
+- **Overhang**: each text effect writes `data-overhang="top right bottom left"` (in ems) on its `<svg>`, saying how far it reaches past its box when it comes to rest. `svgInlineLayout(motion.svg)` (from `@pixerate/flair/vector`) reads the aspect ratio and the overhang. Use the overhang as a margin to keep room for drips and glows.
+- **Typeface**: every text effect takes `font` and `weight`, and `font: "inherit"` uses the heading's font.
+- **Colour**: colour controls take any CSS hex, `rgb()` or `hsl()` colour, or `currentColor` to follow the text colour around it, so one effect suits light and dark themes. Effects whose default text is light on a dark backdrop need an ink colour that shows on your page.
 
 ```ts
-const motion = renderVectorEffect(getEffect("drip-text") as VectorEffect, { word: "Slop", inline: true, font: "inherit" });
-const [, , w, h] = motion.svg.match(/viewBox="([^"]+)"/)![1]!.split(" ").map(Number);
-Object.assign(host.style, { display: "inline-block", height: "0.72em", aspectRatio: `${w} / ${h}` });
+const motion = renderVectorEffect(getEffect("drip-text") as VectorEffect, { word: "Slop", inline: true, font: "inherit", outline: "currentColor" });
+const { aspectRatio, overhang: o } = svgInlineLayout(motion.svg)!;
+Object.assign(host.style, { display: "inline-block", height: "0.72em", aspectRatio: `${aspectRatio}`, margin: `${o.top}em ${o.right}em ${o.bottom}em ${o.left}em` });
 new SvgPlayer(host, motion, { loop: false });
 ```
 
@@ -164,10 +170,31 @@ import { VectorEffect } from "@pixerate/flair/react";
 
 - **Server rendering**: both render a still of the last frame as markup (`"first"` for hover and press triggers; set `poster` for another), sized from the viewBox, so the page hydrates with the picture in place. The `SvgPlayer` takes over after mount and is disposed on unmount.
 - **Reduced motion**: under `prefers-reduced-motion: reduce` the still stays. `reducedMotion="always"` or `"never"` overrides it.
-- **Size**: a block as wide as its container, with the viewBox's aspect ratio. With `inline` (or an effect whose `inline` control is on, like drip text's) it is an `inline-block` 0.72em high, sitting on the baseline like a capital letter; pass a CSS length to `inline` for another height.
+- **Size**: a block as wide as its container, with the viewBox's aspect ratio. With `inline` (or an effect whose `inline` control is on) it is an `inline-block` 0.72em high, sitting on the baseline like a capital letter; pass a CSS length to `inline` for another height. Add `contain` to keep room for what spills past the text (a margin of its overhang).
+- **Plays when seen**: an effect that plays once (`loop={false}`, no trigger) waits until it is scrolled into view, so one further down the page doesn't finish before anyone sees it. Pass `playOnEnter={false}` to start at mount.
 - **Props**: player options (`loop`, `autoplay`, `speed`, `hold`, `trigger`, `steps`, `pauseWhenHidden`, `playOnEnter`, `clock` …), `values` and `preset` for an effect, `onPlayer` for the player itself, and any `<span>` attribute (`elementId` sets the host's `id` on `<VectorEffect>`). Values are compared by content, so an inline object does not restart it; pass `<SvgPlayerView>` a memoised `motion`.
 
-Without React, `svgFrameMarkup(motion, { at: "last" })` (from `@pixerate/flair/vector`) gives the same still as safe `<svg>` markup with no DOM, for any server or framework.
+Without React or Svelte, `svgFrameMarkup(motion, { at: "last" })` (from `@pixerate/flair/vector`) gives the same still as safe `<svg>` markup with no DOM, for any server or framework.
+
+### Svelte
+
+`@pixerate/flair/svelte` does the same for Svelte 5, as plain TypeScript (no `.svelte` files, so nothing to compile). The `vectorEffect` action plays an effect by `id` (or any `motion`) in its element, and `vectorEffectStill` gives the server-rendered still:
+
+```svelte
+<script>
+  import { vectorEffect, vectorEffectStill } from "@pixerate/flair/svelte";
+
+  let { word = "Slop" } = $props();
+  const params = $derived({ id: "drip-text", values: { word, inline: true, font: "inherit" }, loop: false });
+  const still = $derived(vectorEffectStill(params));
+</script>
+
+<h1>Stop the <span use:vectorEffect={params} style={still.style}>{@html still.markup}</span></h1>
+```
+
+- **Params**: the React props, as one object: `id` with `values` and `preset`, or `motion`; player options; `poster`, `reducedMotion`, `inline`, `contain`, `onPlayer`. An effect that plays once waits until it is scrolled into view, as in React. A change remakes the player (values by content; `speed` without remaking), and it is disposed when the element goes.
+- **Still**: `markup` is the still's layer and `style` the host's size from the viewBox, with the same rules as React. The action hides the still while the player runs and keeps it under `prefers-reduced-motion`. Without `vectorEffectStill` it makes its own still and sizes the element on the client.
+- **Attachments**: `{@attach fromAction(vectorEffect, () => params)}`, with `fromAction` from `svelte/attachments`.
 
 `shader-text` fills letters from a text image: set its `uText` control to `textImage("Your title", { weight: 900 })`, a transparent SVG `data:` URL of any Unicode text.
 

package/dist/catalog/index.d.ts

@@ -1,6 +1,6 @@
-import { a as ControlDef, C as ControlValue } from '../controls-Syr6drzO.js';
-import { E as EffectDefinition, a as EffectCategory, S as ShaderEffect } from '../types-9J6NWaN3.js';
-export { b as EFFECT_CATEGORIES, c as EffectPreset, d as VECTOR_CONTROL_TYPES, e as VectorControl, V as VectorEffect, f as colorControl, n as numberControl, r as renderVectorEffect, v as vectorControlDef, g as vectorControlIssues, h as vectorControls, i as vectorEffectControls } from '../types-9J6NWaN3.js';
+import { a as ControlDef, C as ControlValue } from '../controls-Ec6P0Vpy.js';
+import { E as EffectDefinition, a as EffectCategory, S as ShaderEffect } from '../types-C7g8-lTX.js';
+export { C as CURRENT_COLOR, b as EFFECT_CATEGORIES, c as EffectPreset, d as VECTOR_CONTROL_TYPES, e as VectorControl, V as VectorEffect, f as colorControl, i as isCurrentColor, n as numberControl, r as renderVectorEffect, v as vectorControlDef, g as vectorControlIssues, h as vectorControls, j as vectorEffectControls } from '../types-C7g8-lTX.js';
 import '../svg-XugR-6Ec.js';
 
 /**

package/dist/catalog/index.js

@@ -1,4 +1,5 @@
 import {
+  CURRENT_COLOR,
   EFFECTS,
   EFFECT_CATEGORIES,
   FBM,
@@ -16,6 +17,7 @@ import {
   findEffects,
   getEffect,
   glsl,
+  isCurrentColor,
   numberControl,
   renderVectorEffect,
   svgDataUrl,
@@ -24,11 +26,12 @@ import {
   vectorControlIssues,
   vectorControls,
   vectorEffectControls
-} from "../chunk-KWNFZ5NC.js";
+} from "../chunk-LURJMWYM.js";
 import "../chunk-OHW7UG6D.js";
 import "../chunk-EHDJ3CPJ.js";
-import "../chunk-WC3VADZC.js";
+import "../chunk-VYOMXE6I.js";
 export {
+  CURRENT_COLOR,
   EFFECTS,
   EFFECT_CATEGORIES,
   FBM,
@@ -46,6 +49,7 @@ export {
   findEffects,
   getEffect,
   glsl,
+  isCurrentColor,
   numberControl,
   renderVectorEffect,
   svgDataUrl,

package/dist/{chunk-SHHAIWUR.js → chunk-LKQM3GSQ.js}

@@ -1,3 +1,12 @@
+import {
+  CAMERA_MS,
+  CAMERA_STEP_MS,
+  EFFECT_TYPES,
+  MAX_TILT,
+  cameraAt,
+  cameraTrack,
+  sceneStage
+} from "./chunk-WAMA45G3.js";
 import {
   HOVER_SECONDS,
   MAX_CLICKS,
@@ -12,21 +21,12 @@ import {
   drawFrame,
   resetGlCaches,
   wrapSource
-} from "./chunk-YLJWC4N2.js";
+} from "./chunk-PMVJP5I4.js";
 import {
   controlValue,
   imageUrls,
   parseControls
-} from "./chunk-WC3VADZC.js";
-import {
-  CAMERA_MS,
-  CAMERA_STEP_MS,
-  EFFECT_TYPES,
-  MAX_TILT,
-  cameraAt,
-  cameraTrack,
-  sceneStage
-} from "./chunk-WAMA45G3.js";
+} from "./chunk-VYOMXE6I.js";
 
 // src/shader/renderer.ts
 var ShaderRenderer = class {
@@ -1617,4 +1617,4 @@ export {
   validateScene,
   standaloneSceneHtml
 };
-//# sourceMappingURL=chunk-SHHAIWUR.js.map
+//# sourceMappingURL=chunk-LKQM3GSQ.js.map