ngwr 15.6.0 → 15.7.0

package/animations/aurora/styles/_index.scss

@@ -0,0 +1,44 @@
+@use '../../../theme/styles' as theme;
+@include theme.loaded('animations/aurora');
+
+// `<wr-aurora />`: a curtain of light hanging from one edge of a section,
+// like an aurora, behind the section's content. The component paints one
+// WebGL canvas and reads its three stops and the surface back from the hooks
+// below through `resolveCssColorChannels`, so a retheme and a scheme switch
+// both reach the pixels. How bright it is, how far it reaches and how it
+// moves are inputs and the shader's numbers, not the sheet's.
+.wr-aurora {
+  // The three stops the colour flows through across the width, from the
+  // inline start: green, blue, violet, the hues an aurora shows, in that
+  // order so the hue only ever turns one way between them. Bare intents, not
+  // inks: these are graphics, not text, and the roles are `light-dark()`
+  // pairs already, so the dark scheme gets the intents re-tuned for its
+  // canvas with nothing re-declared. The violet is mixed from two roles
+  // rather than a step, so a rebrand moves it.
+  --wr-aurora-color-1: var(--wr-color-success);
+  --wr-aurora-color-2: var(--wr-color-primary);
+  --wr-aurora-color-3: color-mix(in oklch, var(--wr-color-primary) 60%, var(--wr-color-danger));
+
+  position: absolute;
+  inset: 0;
+  // Under the content, over the page: the parent is positioned and isolated,
+  // so this is the floor of its stacking context.
+  z-index: -1;
+  display: block;
+  overflow: hidden;
+  pointer-events: none;
+  user-select: none;
+
+  // The canvas is drawn at half resolution at most and stretched to the host:
+  // the browser's upscale is the last blur the soft picture needs.
+  &__canvas {
+    display: block;
+    inline-size: 100%;
+    block-size: 100%;
+  }
+
+  // Nothing drawn: a tinted wash under system colours is noise, not decoration.
+  @media (forced-colors: active) {
+    display: none;
+  }
+}

package/animations/blur-reveal/styles/_index.scss

@@ -0,0 +1,70 @@
+@use '../../../theme/styles' as theme;
+@use '../../core/styles/mixins' as core;
+@include theme.loaded('animations/blur-reveal');
+
+// `[wrBlurReveal]`: the host's text comes in piece by piece the first time it
+// scrolls into view. At rest the block declares only its hooks, so the host
+// looks the way its own rules say; the pieces, the screen-reader copy and
+// `--run` exist only while the reveal plays, and the host holds its authored
+// children again when it ends.
+.wr-blur-reveal {
+  // In `em`, so a 40px heading and a 16px line soften by the same share of
+  // their size. 0.2em is where a 40px heading reads as soft rather than a
+  // smear in the first frames it can be seen in.
+  --wr-blur-reveal-blur: 0.2em;
+  --wr-blur-reveal-offset: 0.35em;
+  --wr-blur-reveal-duration: 0.6s;
+  // Eases out with no overshoot, so a piece settles rather than bounces.
+  --wr-blur-reveal-ease: var(--wr-ease-out);
+  --wr-blur-reveal-direction: 1;
+  // Written by the directive on the pieces wrapper: the pause before the first
+  // piece and the gap from one piece to the next.
+  --wr-blur-reveal-delay: 0ms;
+  --wr-blur-reveal-stagger: 70ms;
+
+  &--above {
+    --wr-blur-reveal-direction: -1;
+  }
+
+  // The graphemes of one word, in letter mode: a word never parts across lines.
+  &__word {
+    display: inline-block;
+    white-space: nowrap;
+  }
+
+  // `inline-block`, because a filter and a translate do nothing on an inline
+  // box. A word still wraps at the spaces between pieces, which stay real text.
+  &__piece {
+    display: inline-block;
+  }
+
+  &--run &__piece {
+    animation: wr-blur-reveal-in var(--wr-blur-reveal-duration) var(--wr-blur-reveal-ease) both;
+    animation-delay: calc(var(--wr-blur-reveal-delay) + var(--wr-blur-reveal-i, 0) * var(--wr-blur-reveal-stagger));
+  }
+
+  // The sentence for a screen reader, once, while the pieces are `aria-hidden`.
+  &__sr {
+    @include core.sr-only;
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    &--run &__piece {
+      animation: none;
+    }
+  }
+}
+
+@keyframes wr-blur-reveal-in {
+  from {
+    opacity: 0;
+    filter: blur(var(--wr-blur-reveal-blur));
+    translate: 0 calc(var(--wr-blur-reveal-offset) * var(--wr-blur-reveal-direction));
+  }
+
+  to {
+    opacity: 1;
+    filter: blur(0);
+    translate: 0 0;
+  }
+}

package/animations/click-sparks/styles/_index.scss

@@ -0,0 +1,88 @@
+@use '../../../theme/styles' as theme;
+@include theme.loaded('animations/click-sparks');
+
+// `[wrClickSparks]`: on a click, a ring of short strokes bursts out from the
+// click point, flies a short way, shrinks and fades. The directive makes one
+// layer per burst in `document.body`, fixed at the click's client coordinates,
+// with one span per stroke, and writes the point, the burst length and each
+// stroke's angle into custom properties; this sheet owns the paint. The layer
+// has no size and takes no pointer, so nothing on the page moves or misses a
+// click because of it. At rest a stroke is invisible, so a layer that outlives
+// its animation (a preference flipped mid-burst) paints nothing until the
+// directive's fallback timer takes it out.
+.wr-click-sparks {
+  // Written by the directive on the layer: where the burst is, in the viewport.
+  --wr-click-sparks-x: 0px;
+  --wr-click-sparks-y: 0px;
+  // Written by the directive on the layer: how long this burst lasts, so the
+  // strokes end exactly when the layer goes.
+  --wr-click-sparks-duration: 480ms;
+  // All in `em` of the host's font size, which the directive copies onto the
+  // layer: a large hero button throws longer, farther sparks than a small one.
+  // A stroke's length at the start; it shrinks to a tenth of this as it flies.
+  --wr-click-sparks-length: 0.55em;
+  // A stroke's thickness: never under two pixels, so a thin one still reads.
+  --wr-click-sparks-width: max(2px, 0.12em);
+  // Where a stroke's tail starts and ends, from the click point: it leaves a
+  // small clear ring round the point and stops well inside a button's reach.
+  --wr-click-sparks-from: 0.3em;
+  --wr-click-sparks-to: 1.7em;
+  // Fast out of the gate, settling as it fades: a spark, not a slide.
+  --wr-click-sparks-ease: var(--wr-ease-out);
+
+  // Physical on purpose: the point is a client coordinate, the same in either
+  // direction, and the layer measures from the viewport's top left corner.
+  // rtl-ok: client coordinates are physical by nature
+  position: fixed;
+  top: 0;
+  left: 0;
+  translate: var(--wr-click-sparks-x) var(--wr-click-sparks-y);
+  width: 0;
+  height: 0;
+  z-index: var(--wr-z-top);
+  pointer-events: none;
+  user-select: none;
+
+  // One stroke: a rounded bar in the layer's colour (the host's own colour, or
+  // the hook, both set inline by the directive), its inner end on the click
+  // point, centred on it across. The rotation turns it to its angle, the
+  // translation pushes it along that angle, and a scale from the inner end
+  // shortens it, so the tail catches up with the head as it flies.
+  &__spark {
+    position: absolute;
+    // rtl-ok: the stroke starts on the click point and `rotate()` turns it to its angle; the pair is physical
+    top: calc(var(--wr-click-sparks-width) / -2);
+    left: 0;
+    width: var(--wr-click-sparks-length);
+    height: var(--wr-click-sparks-width);
+    border-radius: var(--wr-click-sparks-width);
+    background: currentColor;
+    transform-origin: 0 50%;
+    opacity: 0;
+    will-change: transform, opacity;
+  }
+
+  @media (prefers-reduced-motion: no-preference) and (forced-colors: none) {
+    &__spark {
+      animation: wr-click-sparks-fly var(--wr-click-sparks-duration) var(--wr-click-sparks-ease) both;
+    }
+  }
+}
+
+// The flight of one stroke, from its own angle: out to the far distance, down
+// to a tenth of its length, solid for the first part and gone by the end.
+@keyframes wr-click-sparks-fly {
+  0% {
+    transform: rotate(var(--wr-click-sparks-angle, 0deg)) translateX(var(--wr-click-sparks-from)) scaleX(1);
+    opacity: 1;
+  }
+
+  55% {
+    opacity: 1;
+  }
+
+  100% {
+    transform: rotate(var(--wr-click-sparks-angle, 0deg)) translateX(var(--wr-click-sparks-to)) scaleX(0.1);
+    opacity: 0;
+  }
+}

package/animations/confetti/styles/_index.scss

@@ -0,0 +1,35 @@
+@use '../../../theme/styles' as theme;
+@include theme.loaded('animations/confetti');
+
+// `WrConfetti.burst()`: one fixed, full-viewport canvas in `document.body` for as
+// long as pieces are in the air, then gone. The service paints every piece
+// itself; this sheet places the canvas and names the colours it resolves at
+// each burst. The canvas takes no pointer and has no content, so nothing on the
+// page moves or misses a click while it is there.
+.wr-confetti {
+  // Read by the service through the cascade when a burst starts, so a
+  // `light-dark()` token paints the scheme the reader is in. Bare intents, not
+  // `-ink`: confetti is a graphic, and the text role is for text.
+  --wr-confetti-color-1: var(--wr-color-primary);
+  --wr-confetti-color-2: var(--wr-color-success);
+  --wr-confetti-color-3: var(--wr-color-warning);
+  --wr-confetti-color-4: var(--wr-color-danger);
+  --wr-confetti-color-5: var(--wr-color-info);
+
+  // Physical on purpose: the pieces fly in client coordinates, the same in
+  // either direction, and the canvas covers the whole viewport.
+  // rtl-ok: client coordinates are physical by nature
+  position: fixed;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  z-index: var(--wr-z-top);
+  pointer-events: none;
+  user-select: none;
+
+  // The service mounts nothing under forced colours; this covers a preference
+  // that flips while a burst is in the air.
+  @media (forced-colors: active) {
+    display: none;
+  }
+}

package/animations/core/styles/_mixins.scss

@@ -0,0 +1,21 @@
+// Sass shared by the animation sheets. Not a public entry: there is no
+// `styles/_index.scss` here, so `@use 'ngwr/animations/core'` resolves to
+// nothing and the manifest carries no `sass` condition for it. An effect's own
+// `_index.scss` loads this file by its relative path.
+
+/// Text that exists for assistive technology and not for the eye: the one copy
+/// of a sentence a screen reader hears while the pieces it is drawn as are
+/// `aria-hidden`. Out of flow rather than hidden, since `display: none` and
+/// `visibility: hidden` take it out of the accessible tree too.
+@mixin sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  overflow: hidden;
+  // `clip-path`, not the deprecated `clip`: same effect, and it survives
+  // `forced-colors`, where a clipped element is still measured.
+  clip-path: inset(50%);
+  white-space: nowrap;
+  border: 0;
+}

package/animations/decode/styles/_index.scss

@@ -0,0 +1,68 @@
+@use '../../../theme/styles' as theme;
+@use '../../core/styles/mixins' as core;
+@include theme.loaded('animations/decode');
+
+// `[wrDecode]`: the host's text shows random glyphs that lock on to the real
+// characters one after another. At rest the block declares only its hooks, so
+// the host looks the way its own rules say; the slots, the screen-reader copy
+// and `--run` exist only while the effect plays, and the host holds its
+// authored children again when it ends.
+.wr-decode {
+  // What a glyph that has not locked yet paints in: the host's own text colour
+  // at reduced strength, so a primary chip scrambles in a quieter primary and a
+  // body line in a quieter ink, and each slot eases up to the full colour as it
+  // locks. Mixed from `currentColor`, never from a ramp step.
+  --wr-decode-tint: color-mix(in srgb, currentColor 45%, transparent);
+  // Written by the directive on the slots wrapper: how long a locked slot takes
+  // to reach the text colour.
+  --wr-decode-settle: 240ms;
+  --wr-decode-ease: var(--wr-ease-out);
+
+  // One character. Inline, not inline-block, so the line breaks and the
+  // baseline are exactly what the plain text had. The real character is the
+  // slot's only text and stays in flow throughout: it is what gives the slot
+  // its width, so a glyph never moves the line.
+  &__slot {
+    position: relative;
+    transition: color var(--wr-decode-settle) var(--wr-decode-ease);
+  }
+
+  // Scrambled: the real character is hidden, not removed, so the slot keeps
+  // its width, and the glyph in `data-glyph` is painted over it out of flow.
+  // `visibility`, not `color: transparent`, so the lock can ease the colour
+  // from the tint up to the text's.
+  &__slot--scramble {
+    color: var(--wr-decode-tint);
+    visibility: hidden;
+
+    // Centred in the slot by flex, whose default `center` is unsafe: a glyph
+    // wider than the slot hangs over both neighbours by the same amount
+    // instead of only the end one. Centred on the block axis too, so the glyph
+    // box sits where the real character's does and the baselines coincide.
+    &::after {
+      content: attr(data-glyph);
+      position: absolute;
+      inset: 0;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      visibility: visible;
+      white-space: pre;
+      pointer-events: none;
+    }
+  }
+
+  // The text for a screen reader, once, while the slots are `aria-hidden`.
+  // Out of the selection, so a copy of the line gives the slots' text once.
+  &__sr {
+    @include core.sr-only;
+
+    user-select: none;
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    &__slot {
+      transition: none;
+    }
+  }
+}

package/animations/destruct/styles/_index.scss

@@ -0,0 +1,31 @@
+@use '../../../theme/styles' as theme;
+@include theme.loaded('animations/destruct');
+
+// `[wrDestruct]`: while a pointer is over the host, or focus is in it, its
+// text wobbles with a fine, living noise, and settles back to crisp text when
+// the pointer leaves. The text stays real text: the directive mounts one 0 by 0
+// `<svg>` with a fractal-noise displacement filter beside the host, drives the
+// displacement every frame, and puts `--on` with the filter's url on the host
+// only while the noise is above zero. At rest the block declares nothing, so
+// the host renders exactly as its own rules say.
+.wr-destruct {
+  @media (prefers-reduced-motion: no-preference) and (forced-colors: none) {
+    &--on {
+      // Written by the directive: `url(#id)` of this instance's filter.
+      filter: var(--wr-destruct-filter);
+      // Only while the directive drives it: a promoted layer costs memory, and
+      // still text has no reason to hold one.
+      will-change: filter;
+    }
+  }
+
+  // The filter's home: no box, no hit area, nothing a reader can land on. Not
+  // `display: none`, which would take the filter out of rendering with it.
+  &__filter {
+    position: absolute;
+    inline-size: 0;
+    block-size: 0;
+    overflow: hidden;
+    pointer-events: none;
+  }
+}

package/animations/dot-grid/styles/_index.scss

@@ -0,0 +1,41 @@
+@use '../../../theme/styles' as theme;
+@include theme.loaded('animations/dot-grid');
+
+// `<wr-dot-grid />`: an even field of small, faint dots behind a section's
+// content. The component paints one canvas and reads its two colours back
+// from the hooks below through `resolveCssColorChannels`, so a retheme and a
+// scheme switch both reach the pixels. The strengths (how much of each colour
+// a dot shows at rest and lit) and the dot sizes live in `dot-grid.ts`: they
+// are the canvas's numbers, not the sheet's.
+.wr-dot-grid {
+  // A dot at rest: the muted role, the bare intent, since a dot is a graphic
+  // and not text. The canvas shows it at about a third, so the text and the
+  // cards over the field read as they do on the plain surface.
+  --wr-dot-grid-ink: var(--wr-color-on-surface-muted);
+  // A dot under the pointer: the primary intent, never at full strength, so
+  // the lit patch stays under the content's own accents.
+  --wr-dot-grid-glow: var(--wr-color-primary);
+
+  position: absolute;
+  inset: 0;
+  // Under the content, over the page: the parent is positioned and isolated,
+  // so this is the floor of its stacking context.
+  z-index: -1;
+  display: block;
+  overflow: hidden;
+  pointer-events: none;
+  user-select: none;
+  // Gone at the edges, so there is no rectangle where the section ends.
+  mask-image: radial-gradient(ellipse 70% 72% at 50% 50%, #000 35%, transparent 100%);
+
+  &__canvas {
+    display: block;
+    inline-size: 100%;
+    block-size: 100%;
+  }
+
+  // Nothing drawn: a field of dots under system colours is noise, not decoration.
+  @media (forced-colors: active) {
+    display: none;
+  }
+}

package/animations/falling-letters/styles/_index.scss

@@ -0,0 +1,72 @@
+@use '../../../theme/styles' as theme;
+@include theme.loaded('animations/falling-letters');
+
+// `[wrFallingLetters]`: click a line of text and its letters let go, fall,
+// and pile into a heap on the floor of a container; click again, or wait, and
+// they spring back into the line. At rest the block declares only the anchor
+// for the pieces, so the target looks the way its own rules say; the wrapper,
+// the pieces and `--out` exist only while the letters are out, and the target
+// holds its authored children again when they are back. The directive owns
+// every position (it measures, integrates and writes one transform per piece
+// per frame); the sheet owns what a piece is.
+.wr-falling-letters {
+  // The anchor for the pieces: each is placed from this box, so the pieces
+  // scroll with the page and a letter in flight never moves the line.
+  position: relative;
+
+  // The authored nodes while the pieces are out: in flow, so the line keeps
+  // exactly its space and a screen reader and the clipboard still get the real
+  // text once; invisible, so it is not drawn under the pieces. `opacity`, not
+  // `visibility`, which would take the text out of the accessibility tree.
+  &--out &__text {
+    opacity: 0;
+  }
+
+  // One grapheme during the measurement: an inline-block, so its box is the
+  // line's height and a piece with the same font puts the glyph at the same
+  // offset in its own box. Exists for one synchronous layout, never painted.
+  &__glyph {
+    display: inline-block;
+    white-space: pre;
+  }
+
+  // The pieces' layer over the target's box: out of the selection, under no
+  // pointer, so a button a letter falls across stays clickable.
+  &__pieces {
+    position: absolute;
+    inset: 0;
+    pointer-events: none;
+    user-select: none;
+  }
+
+  // One letter: a block at the origin of the layer, moved by transform alone,
+  // so every frame is composited and nothing under it reflows. It inherits the
+  // font and the colour from the target, as the line it left did. The
+  // directive sets each piece's `transform-origin` inline, at the centre of
+  // the glyph's ink, so a letter turns about the letter and not about the air
+  // of its line box; the centre here is the fallback for a piece it could not
+  // measure.
+  &__piece {
+    position: absolute;
+    // rtl-ok: the directive places each piece from measured geometry on the
+    // physical axes, from the layer's top-left corner in either direction.
+    top: 0;
+    left: 0;
+    display: block;
+    white-space: pre;
+    transform-origin: center;
+    will-change: transform;
+  }
+
+  // Belt and braces: the directive puts the text back the moment the
+  // preference flips, but a frame in between must not show a doubled line.
+  @media (prefers-reduced-motion: reduce) {
+    &--out &__text {
+      opacity: 1;
+    }
+
+    &__pieces {
+      display: none;
+    }
+  }
+}

package/animations/flow-lines/styles/_index.scss

@@ -0,0 +1,39 @@
+@use '../../../theme/styles' as theme;
+@include theme.loaded('animations/flow-lines');
+
+// `<wr-flow-lines />`: a dense field of thin parallel lines behind a section's
+// content, bent in slow waves and pushed aside round the pointer. The component
+// paints one WebGL canvas and reads its two colours and the surface back from
+// the hooks below through `resolveCssColorChannels`, so a retheme and a scheme
+// switch both reach the pixels. How much of a colour a line lays and its
+// thickness live in the component and its shader: they are the canvas's
+// numbers, not the sheet's.
+.wr-flow-lines {
+  // A line: the muted ink, a graphic and so the bare role; the canvas lays it
+  // at a fraction, as ink on a light surface and as light on a dark one.
+  --wr-flow-lines-color: var(--wr-color-on-surface-muted);
+  // A pushed line and a ripple's crest: the primary intent, never at full
+  // strength, so they stay under the content's own accents.
+  --wr-flow-lines-accent: var(--wr-color-primary);
+
+  position: absolute;
+  inset: 0;
+  // Under the content, over the page: the parent is positioned and isolated,
+  // so this is the floor of its stacking context.
+  z-index: -1;
+  display: block;
+  overflow: hidden;
+  pointer-events: none;
+  user-select: none;
+
+  &__canvas {
+    display: block;
+    inline-size: 100%;
+    block-size: 100%;
+  }
+
+  // Nothing drawn: hairlines under system colours are noise, not decoration.
+  @media (forced-colors: active) {
+    display: none;
+  }
+}

package/animations/fluid-cursor/styles/_index.scss

@@ -0,0 +1,44 @@
+@use '../../../theme/styles' as theme;
+@include theme.loaded('animations/fluid-cursor');
+
+// `<wr-fluid-cursor />`: coloured ink behind a region's content, stirred by
+// the pointer and gone a few seconds later. The component paints one WebGL
+// canvas and reads its palette back from the hooks below through
+// `resolveCssColorChannels`, so a retheme and a scheme switch both reach the
+// pixels. How the ink covers the surface (as ink on a light one, lifted on a
+// dark one) and the splat sizes live in the component and its model: they
+// are the canvas's numbers, not the sheet's.
+.wr-fluid-cursor {
+  // The palette a stroke cycles through, in order: the bare intents, since
+  // the ink is a graphic and not text. Warm and cool alternate, so neighbours
+  // in the cycle stay apart.
+  --wr-fluid-cursor-color-1: var(--wr-color-primary);
+  --wr-fluid-cursor-color-2: var(--wr-color-danger);
+  --wr-fluid-cursor-color-3: var(--wr-color-warning);
+  --wr-fluid-cursor-color-4: var(--wr-color-success);
+  --wr-fluid-cursor-color-5: var(--wr-color-info);
+
+  position: absolute;
+  inset: 0;
+  // Under the content, over the page: the parent is positioned and isolated,
+  // so this is the floor of its stacking context.
+  z-index: -1;
+  display: block;
+  overflow: hidden;
+  pointer-events: none;
+  user-select: none;
+  // Gone at the edges, so ink carried to the border dissolves rather than
+  // ending in a straight cut. Symmetric, so it needs no mirroring.
+  mask-image: radial-gradient(ellipse 85% 90% at 50% 50%, #000 45%, transparent 100%);
+
+  &__canvas {
+    display: block;
+    inline-size: 100%;
+    block-size: 100%;
+  }
+
+  // Nothing drawn: ink under system colours is noise, not decoration.
+  @media (forced-colors: active) {
+    display: none;
+  }
+}