ngwr 12.2.0 → 13.0.0

package/slider/styles/_index.scss

@@ -85,6 +85,14 @@
     font-variant-numeric: tabular-nums;
   }
 
+  // A read-only slider still takes focus and still announces its value, so it
+  // keeps the visual and only stops inviting the drag — `grab` on something that
+  // cannot move is the part that looks broken. Matches `wr-knob--readonly`.
+  &--readonly &__track,
+  &--readonly &__thumb {
+    cursor: default;
+  }
+
   &--disabled {
     --wr-slider-thumb-border: var(--wr-color-on-surface-muted);
     --wr-slider-fill: var(--wr-color-on-surface-muted);

package/spotlight-card/spotlight-card.scss

@@ -1 +1 @@
-@forward './styles';
+@forward './styles/rules';

package/spotlight-card/styles/_index.scss

@@ -1,52 +1,15 @@
-// Pull the whole theme so a standalone `@use 'ngwr/<name>'` brings in every
-// design token this stylesheet references. Sass deduplicates `@use` per
-// compilation, so the umbrella sheet still emits the theme only once.
-@use '../../theme/styles' as theme;
-
-// Cursor-tracked spotlight card (reactbits port). The `--wr-spotlight-x/y`
-// vars come from the host's mousemove handler; `--wr-spotlight-color` is
-// set inline from the `[spotlightColor]` input when provided — otherwise
-// the theme picks the default below. `--wr-color-on-surface-rgb` flips between
-// themes (dark on light surfaces, light on dark), so a single tint reads
-// as a dark-ish glow in light mode and a light beam in dark mode.
-
-.wr-spotlight-card {
-  --wr-spotlight-x: 50%;
-  --wr-spotlight-y: 50%;
-  --wr-spotlight-color: rgba(var(--wr-color-on-surface-rgb), 0.15);
-
-  position: relative;
-  display: block;
-  border-radius: 1.5rem;
-  border: 1px solid var(--wr-color-outline);
-  background-color: var(--wr-color-surface);
-  padding: 2rem;
-  overflow: hidden;
-  color: var(--wr-color-on-surface);
-
-  &::before {
-    content: '';
-    position: absolute;
-    inset: 0;
-    background: radial-gradient(
-      circle at var(--wr-spotlight-x) var(--wr-spotlight-y),
-      var(--wr-spotlight-color),
-      transparent var(--wr-spotlight-radius, 80%)
-    );
-    opacity: 0;
-    transition: opacity 0.5s ease;
-    pointer-events: none;
-  }
-
-  &:hover::before,
-  &:focus-within::before {
-    opacity: 0.6;
-  }
-}
-
-// Dark mode: `--wr-color-on-surface-rgb` already flips to a light value, so the
-// default tint above becomes a light beam on the navy surface — nudge the
-// alpha up a touch so it reads as bright as the classic spotlight.
-[data-theme='dark'] .wr-spotlight-card {
-  --wr-spotlight-color: rgba(var(--wr-color-on-surface-rgb), 0.22);
-}
+// Public Sass entry for `@use 'ngwr/spotlight-card'`.
+//
+// Pulls the whole theme so a standalone import still brings in every design
+// token these rules reference, then loads the rules themselves from `_rules`.
+//
+// The split is what keeps the token layer out of the JavaScript bundle.
+// `spotlight-card.scss` is the component's `styleUrl`, and a component stylesheet is
+// its OWN Sass compilation — `@use` only deduplicates within one. So while the
+// umbrella sheet emits the theme once, forwarding it from here would inline a
+// second, byte-identical copy of `:root`, `[data-theme='dark']` and the
+// box-sizing reset into the compiled component styles, which ng-packagr then
+// embeds in the FESM bundle as a string. `spotlight-card.scss` forwards `_rules`
+// instead, so it carries this component's own CSS and nothing else.
+@use '../../theme/styles';
+@forward 'rules';

package/spotlight-card/styles/_rules.scss

@@ -0,0 +1,47 @@
+// Cursor-tracked spotlight card (reactbits port). The `--wr-spotlight-x/y`
+// vars come from the host's mousemove handler; `--wr-spotlight-color` is
+// set inline from the `[spotlightColor]` input when provided — otherwise
+// the theme picks the default below. `--wr-color-on-surface-rgb` flips between
+// themes (dark on light surfaces, light on dark), so a single tint reads
+// as a dark-ish glow in light mode and a light beam in dark mode.
+
+.wr-spotlight-card {
+  --wr-spotlight-x: 50%;
+  --wr-spotlight-y: 50%;
+  --wr-spotlight-color: rgba(var(--wr-color-on-surface-rgb), 0.15);
+
+  position: relative;
+  display: block;
+  border-radius: 1.5rem;
+  border: 1px solid var(--wr-color-outline);
+  background-color: var(--wr-color-surface);
+  padding: 2rem;
+  overflow: hidden;
+  color: var(--wr-color-on-surface);
+
+  &::before {
+    content: '';
+    position: absolute;
+    inset: 0;
+    background: radial-gradient(
+      circle at var(--wr-spotlight-x) var(--wr-spotlight-y),
+      var(--wr-spotlight-color),
+      transparent var(--wr-spotlight-radius, 80%)
+    );
+    opacity: 0;
+    transition: opacity 0.5s ease;
+    pointer-events: none;
+  }
+
+  &:hover::before,
+  &:focus-within::before {
+    opacity: 0.6;
+  }
+}
+
+// Dark mode: `--wr-color-on-surface-rgb` already flips to a light value, so the
+// default tint above becomes a light beam on the navy surface — nudge the
+// alpha up a touch so it reads as bright as the classic spotlight.
+[data-theme='dark'] .wr-spotlight-card {
+  --wr-spotlight-color: rgba(var(--wr-color-on-surface-rgb), 0.22);
+}

package/star-border/star-border.scss

@@ -1 +1 @@
-@forward './styles';
+@forward './styles/rules';

package/star-border/styles/_index.scss

@@ -1,125 +1,15 @@
-// Pull the whole theme so a standalone `@use 'ngwr/<name>'` brings in every
-// design token this stylesheet references. Sass deduplicates `@use` per
-// compilation, so the umbrella sheet still emits the theme only once.
-@use '../../theme/styles' as theme;
-
-// Star border (reactbits port). Two oversized radial-gradient "comets"
-// sweep along the top and bottom edges of the rounded container; the
-// projected content sits on a token-themed inner panel above them.
-
-.wr-star-border {
-  // Light surfaces get a primary comet; dark theme flips to the classic
-  // white (see block below). `[color]` overrides both inline. The light
-  // comet gets a wider core + full opacity — a thin 10% tail washes out
-  // to gray on white surfaces.
-  --wr-star-border-color: var(--wr-color-primary);
-  --wr-star-border-speed: 6s;
-  --wr-star-border-radius: 20px;
-  --wr-star-border-stop: 16%;
-  --wr-star-border-opacity: 1;
-
-  display: inline-block;
-  position: relative;
-  border: 0;
-  background: transparent;
-  border-radius: var(--wr-star-border-radius);
-  overflow: hidden;
-  cursor: inherit;
-
-  &__ray {
-    position: absolute;
-    display: block;
-    width: 300%;
-    height: 50%;
-    opacity: var(--wr-star-border-opacity);
-    border-radius: 50%;
-    background: radial-gradient(circle, var(--wr-star-border-color), transparent var(--wr-star-border-stop));
-    animation: wr-star-border-bottom var(--wr-star-border-speed) linear infinite alternate;
-    z-index: 0;
-
-    &--bottom {
-      bottom: -12px;
-      // rtl-ok: the comet's off-screen start mark — `wr-star-border-bottom` sweeps it by `translate(-100%, 0%)`
-      right: -250%;
-    }
-
-    &--top {
-      top: -12px;
-      // rtl-ok: the comet's off-screen start mark — `wr-star-border-top` sweeps it by `translate(100%, 0%)`
-      left: -250%;
-      animation-name: wr-star-border-top;
-    }
-  }
-
-  // Single-ray variant — drop the top comet.
-  &--single &__ray--top {
-    display: none;
-  }
-
-  // Hover-only variant — rays sit hidden until the pointer is in. The
-  // idle state must drop the animation entirely (not pause it): a paused
-  // animation pins `opacity` at its 0% keyframe value, which beats the
-  // cascade and leaves a frozen comet visible.
-  &--hover &__ray {
-    opacity: 0;
-    animation: none;
-  }
-
-  &--hover:hover &__ray {
-    animation: wr-star-border-bottom var(--wr-star-border-speed) linear infinite alternate;
-  }
-
-  &--hover:hover &__ray--top {
-    animation-name: wr-star-border-top;
-  }
-
-  &__inner {
-    position: relative;
-    display: block;
-    border: 1px solid var(--wr-color-outline);
-    background: var(--wr-color-surface);
-    color: var(--wr-color-on-surface);
-    font-size: 1rem;
-    text-align: center;
-    padding: 1rem 1.625rem;
-    border-radius: var(--wr-star-border-radius);
-    z-index: 1;
-  }
-}
-
-[data-theme='dark'] .wr-star-border {
-  --wr-star-border-color: #ffffff;
-  --wr-star-border-stop: 10%;
-  --wr-star-border-opacity: 0.7;
-}
-
-@keyframes wr-star-border-bottom {
-  0% {
-    transform: translate(0%, 0%);
-    opacity: 1;
-  }
-  100% {
-    transform: translate(-100%, 0%);
-    opacity: 0;
-  }
-}
-
-@keyframes wr-star-border-top {
-  0% {
-    transform: translate(0%, 0%);
-    opacity: 1;
-  }
-  100% {
-    transform: translate(100%, 0%);
-    opacity: 0;
-  }
-}
-
-// Reduced motion: no sweeping comets — a frozen ray reads as a smudge,
-// so hide them and keep the panel border as the resting look.
-@media (prefers-reduced-motion: reduce) {
-  .wr-star-border__ray {
-    animation: none !important;
-    opacity: 0 !important;
-  }
-}
+// Public Sass entry for `@use 'ngwr/star-border'`.
+//
+// Pulls the whole theme so a standalone import still brings in every design
+// token these rules reference, then loads the rules themselves from `_rules`.
+//
+// The split is what keeps the token layer out of the JavaScript bundle.
+// `star-border.scss` is the component's `styleUrl`, and a component stylesheet is
+// its OWN Sass compilation — `@use` only deduplicates within one. So while the
+// umbrella sheet emits the theme once, forwarding it from here would inline a
+// second, byte-identical copy of `:root`, `[data-theme='dark']` and the
+// box-sizing reset into the compiled component styles, which ng-packagr then
+// embeds in the FESM bundle as a string. `star-border.scss` forwards `_rules`
+// instead, so it carries this component's own CSS and nothing else.
+@use '../../theme/styles';
+@forward 'rules';

package/star-border/styles/_rules.scss

@@ -0,0 +1,120 @@
+// Star border (reactbits port). Two oversized radial-gradient "comets"
+// sweep along the top and bottom edges of the rounded container; the
+// projected content sits on a token-themed inner panel above them.
+
+.wr-star-border {
+  // Light surfaces get a primary comet; dark theme flips to the classic
+  // white (see block below). `[color]` overrides both inline. The light
+  // comet gets a wider core + full opacity — a thin 10% tail washes out
+  // to gray on white surfaces.
+  --wr-star-border-color: var(--wr-color-primary);
+  --wr-star-border-speed: 6s;
+  --wr-star-border-radius: 20px;
+  --wr-star-border-stop: 16%;
+  --wr-star-border-opacity: 1;
+
+  display: inline-block;
+  position: relative;
+  border: 0;
+  background: transparent;
+  border-radius: var(--wr-star-border-radius);
+  overflow: hidden;
+  cursor: inherit;
+
+  &__ray {
+    position: absolute;
+    display: block;
+    width: 300%;
+    height: 50%;
+    opacity: var(--wr-star-border-opacity);
+    border-radius: 50%;
+    background: radial-gradient(circle, var(--wr-star-border-color), transparent var(--wr-star-border-stop));
+    animation: wr-star-border-bottom var(--wr-star-border-speed) linear infinite alternate;
+    z-index: 0;
+
+    &--bottom {
+      bottom: -12px;
+      // rtl-ok: the comet's off-screen start mark — `wr-star-border-bottom` sweeps it by `translate(-100%, 0%)`
+      right: -250%;
+    }
+
+    &--top {
+      top: -12px;
+      // rtl-ok: the comet's off-screen start mark — `wr-star-border-top` sweeps it by `translate(100%, 0%)`
+      left: -250%;
+      animation-name: wr-star-border-top;
+    }
+  }
+
+  // Single-ray variant — drop the top comet.
+  &--single &__ray--top {
+    display: none;
+  }
+
+  // Hover-only variant — rays sit hidden until the pointer is in. The
+  // idle state must drop the animation entirely (not pause it): a paused
+  // animation pins `opacity` at its 0% keyframe value, which beats the
+  // cascade and leaves a frozen comet visible.
+  &--hover &__ray {
+    opacity: 0;
+    animation: none;
+  }
+
+  &--hover:hover &__ray {
+    animation: wr-star-border-bottom var(--wr-star-border-speed) linear infinite alternate;
+  }
+
+  &--hover:hover &__ray--top {
+    animation-name: wr-star-border-top;
+  }
+
+  &__inner {
+    position: relative;
+    display: block;
+    border: 1px solid var(--wr-color-outline);
+    background: var(--wr-color-surface);
+    color: var(--wr-color-on-surface);
+    font-size: 1rem;
+    text-align: center;
+    padding: 1rem 1.625rem;
+    border-radius: var(--wr-star-border-radius);
+    z-index: 1;
+  }
+}
+
+[data-theme='dark'] .wr-star-border {
+  --wr-star-border-color: #ffffff;
+  --wr-star-border-stop: 10%;
+  --wr-star-border-opacity: 0.7;
+}
+
+@keyframes wr-star-border-bottom {
+  0% {
+    transform: translate(0%, 0%);
+    opacity: 1;
+  }
+  100% {
+    transform: translate(-100%, 0%);
+    opacity: 0;
+  }
+}
+
+@keyframes wr-star-border-top {
+  0% {
+    transform: translate(0%, 0%);
+    opacity: 1;
+  }
+  100% {
+    transform: translate(100%, 0%);
+    opacity: 0;
+  }
+}
+
+// Reduced motion: no sweeping comets — a frozen ray reads as a smudge,
+// so hide them and keep the panel border as the resting look.
+@media (prefers-reduced-motion: reduce) {
+  .wr-star-border__ray {
+    animation: none !important;
+    opacity: 0 !important;
+  }
+}

package/switch/styles/_index.scss

@@ -95,6 +95,13 @@
     }
   }
 
+  // A read-only switch still takes focus and still submits its value, so it
+  // keeps the full visual and only stops inviting the click — dimming it would
+  // say "disabled", which is the other state.
+  &--readonly &__label {
+    cursor: default;
+  }
+
   &--disabled {
     --wr-switch-color: var(--wr-color-on-surface-muted);
     pointer-events: none;

package/theme/styles/_dark.scss

@@ -3,13 +3,90 @@
 @use 'colors';
 @use 'variables';
 
-// Dark theme overrides — opt-in via `[data-theme="dark"]` on <html>.
-// Drive the toggle from `WrTheme` (provided automatically with
-// `provideWrTheme(...)`).
+// Dark theme overrides — opt-in via `[data-theme="dark"]` on <html>, or
+// whatever `$theme-attribute` below is configured to. Drive the toggle from
+// `WrTheme` (provided automatically with `provideWrTheme(...)`).
 //
 // Only semantic tokens flip — palette hues stay so brand-coloured
 // elements look the same regardless of theme.
 
+/// The attribute the dark block keys on. Must match the `attribute` passed to
+/// `provideWrTheme(...)`, and that pairing is the whole reason this variable
+/// exists: `WrThemeConfig.attribute` is a RUNTIME value, and no CSS selector can
+/// read one. Until v13 the selector below was the literal `[data-theme='dark']`,
+/// so an app that set `provideWrTheme({ attribute: 'data-color-mode' })` got a
+/// service reporting `resolved() === 'dark'`, the attribute written correctly
+/// onto `<html>`, and a page that stayed light forever — no error, no warning.
+///
+/// Configure the two together:
+///
+/// ```scss
+/// // styles.scss
+/// @use 'ngwr' with ($theme-attribute: 'data-color-mode');
+/// ```
+/// ```ts
+/// provideWrTheme({ attribute: 'data-color-mode' })
+/// ```
+///
+/// Only the configured attribute is emitted — the default is NOT kept as a
+/// second selector. Renaming it is what decouples ngwr from another design
+/// system that already owns `data-theme`, and emitting both would re-couple
+/// them: that system's own `data-theme="dark"` would flip ngwr's tokens behind
+/// the app's back, which is the exact collision the rename exists to avoid.
+///
+/// If the two disagree the page silently stays light, so `WrTheme` publishes a
+/// dev-mode check for it: the light block below writes the configured name into
+/// `--wr-theme-attribute`, and the service warns when what it reads there is not
+/// what it was configured with. A stylesheet that is missing or predates v13
+/// leaves the property empty and the check stays quiet — it can only fire on a
+/// real disagreement.
+$theme-attribute: 'data-theme' !default;
+
+/// The dark-theme selector, for a stylesheet that has to build its own.
+///
+/// @example scss
+///   #{dark.dark-selector()} .my-thing { ... }
+@function dark-selector() {
+  @return '[#{$theme-attribute}=\'dark\']';
+}
+
+/// Wrap a declaration block so it only applies in dark mode, honouring
+/// `$theme-attribute`. Prefer this over writing `[data-theme='dark']` by hand —
+/// a hand-written literal is exactly what BUG-3 was.
+///
+/// @example scss
+///   @use 'ngwr/theme' as theme;
+///
+///   .my-card {
+///     background: #fff;
+///
+///     @include theme.dark {
+///       background: #0b1120;
+///     }
+///   }
+@mixin dark() {
+  @if & {
+    @at-root #{dark-selector()} #{&} {
+      @content;
+    }
+  } @else {
+    #{dark-selector()} {
+      @content;
+    }
+  }
+}
+
+:root {
+  // The attribute this compiled stylesheet keys its dark block on, published so
+  // `WrTheme` can compare it against `WrThemeConfig.attribute` in dev mode and
+  // say so when the two were configured apart. Read with
+  // `getPropertyValue('--wr-theme-attribute')`, never with `var()`.
+  //
+  // unused-ok: read by `WrTheme` through the CSSOM rather than painted with —
+  // it carries a name, not a value, so no declaration can reference it.
+  --wr-theme-attribute: #{$theme-attribute};
+}
+
 // Intents re-tuned for the dark canvas. Looped (below) so each gets the
 // FULL symmetric shade set — the hand blocks used to ship only base+rgb,
 // leaving -light/-dark/-lighter/-darker baked from the LIGHT palette.
@@ -37,7 +114,7 @@ $_light: #262f44;
 $_medium: #6d7682;
 $_dark: #e6ebf3;
 
-[data-theme='dark'] {
+#{dark-selector()} {
   // Canvas (was `--wr-color-white` in light mode)
   // Deeper than slate-900 so an elevated surface in slate-800 reads
   // as a real layer rather than vanishing into the background.

package/theme/styles/_index.scss

@@ -4,3 +4,4 @@
 @forward 'dark';
 @forward 'focus';
 @forward 'mixins';
+@forward 'motion';

package/theme/styles/_motion.scss

@@ -0,0 +1,94 @@
+// `prefers-reduced-motion` for the always-on chrome.
+//
+// Why this lives in the theme layer rather than in each component. The
+// animation catalogue (`ngwr/glitch-text`, `ngwr/gradient-text`, …) guards
+// itself, component by component — those are opt-in effects, and each one knows
+// what its own stillness should look like. The ten blocks below are the
+// opposite: chrome nobody opted into. A spinner and a skeleton animate on
+// essentially every page of every app, and four of the animations here never
+// stop at all (`wr-spinner-rotate`, `wr-spinner-dash`, `wr-skeleton-shimmer`,
+// `wr-card-spin`, `wr-lightbox-shimmer`), which is the case vestibular guidance
+// is most emphatic about. Collecting them in one place is what makes the set
+// reviewable — the gap this closes existed because nine separate stylesheets
+// each forgot, and nine separate stylesheets can each forget again.
+//
+// **Every declaration here is `!important`, and that is structural rather than
+// lazy.** The theme layer is loaded first — `styles.scss` forwards it before any
+// component, and a standalone `@use 'ngwr/spinner'` pulls it in ahead of the
+// spinner's own rules — so at equal specificity the component always wins on
+// source order. `!important` is the only lever a stylesheet that must come first
+// has. `.wr-overlay-sheet` needs one more: its animation is itself `!important`
+// (it has to beat four components' panel sizing), so the class is doubled here
+// to out-specify it.
+//
+// What reduced motion MEANS is decided per animation, not globally:
+//
+//   - An ENTER animation is removed. The panel still arrives, it just does not
+//     travel to get there. Every keyframe set below animates from a transparent,
+//     offset or scaled-down state TO the element's resting one, with no
+//     `forwards`, so removing it lands on exactly the frame the animation was
+//     heading for. Nothing in the library waits on `animationend`, so nothing
+//     is left un-dismissed.
+//   - A decorative INFINITE loop is removed outright — a skeleton's shimmer and
+//     a lightbox's shimmer say nothing the static placeholder does not.
+//   - A SPINNER is slowed, not stopped. Its rotation IS the message: a frozen
+//     spinner does not read as "reduced motion", it reads as "hung". So the
+//     rotation stays at half speed and the pulsing arc — the part that carries
+//     no information — is frozen at a fixed sweep. Same call Bootstrap makes,
+//     and the same reading as WCAG 2.3.3, which is about non-essential motion.
+//   - The TOAST progress bar is deliberately left alone. It is a countdown: it
+//     is the only thing on screen saying how long is left before the toast
+//     leaves, and freezing it would not remove information, it would state a
+//     falsehood — a full bar that never drains. It is also 2px tall and moves
+//     along one axis at constant speed, the mildest shape motion sensitivity
+//     takes. If that trade is ever revisited, revisit it here.
+
+@media (prefers-reduced-motion: reduce) {
+  // Overlay enter choreography — dialog, dropdown, popconfirm, toast, lightbox
+  // viewer, and all four drawer edges.
+  .wr-dialog-panel,
+  .wr-dropdown-menu,
+  .wr-popconfirm-overlay > .wr-popconfirm,
+  .wr-toast,
+  .wr-lightbox-viewer,
+  .wr-drawer__panel--left,
+  .wr-drawer__panel--right,
+  .wr-drawer__panel--top,
+  .wr-drawer__panel--bottom {
+    animation: none !important;
+  }
+
+  // The responsive bottom sheet, which slides a full panel height up the
+  // screen — the largest single translation the library performs. Doubled
+  // class: `overlay/styles/_index.scss` sets this animation `!important`, and it
+  // is loaded after this file.
+  .wr-overlay-sheet.wr-overlay-sheet {
+    animation: none !important;
+  }
+
+  // Decorative loading shimmers. Both ride a pseudo-element whose resting
+  // position is off-screen or at its gradient origin, so stopping them leaves a
+  // plain tinted placeholder rather than a half-drawn band.
+  .wr-skeleton--animated::after,
+  .wr-lightbox--loading::after {
+    animation: none !important;
+  }
+
+  // Spinners. The rotation survives at half speed; the arc stops pulsing and
+  // holds the sweep the dash animation spends most of its cycle at, so the
+  // shape stays a recognisable spinner instead of collapsing to the 1-unit dot
+  // its first keyframe starts from.
+  .wr-spinner svg {
+    animation-duration: 4s !important;
+  }
+
+  .wr-spinner__path {
+    animation: none !important;
+    stroke-dasharray: 90, 150 !important;
+    stroke-dashoffset: 0 !important;
+  }
+
+  .wr-card__spinner {
+    animation-duration: 1.4s !important;
+  }
+}