ngwr 12.1.0 → 13.0.0

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/stepper/styles/_index.scss

@@ -1,5 +1,13 @@
 @use '../../theme/styles' as theme;
 
+// The label's own line box, and the header button's block padding. Both are
+// declared once below and read back by the alignment arithmetic — the indicator
+// centres on the label's FIRST LINE, and the connector centres on the indicator,
+// so a literal repeated in three places is a defect waiting for someone to
+// change one of them.
+$label-line-height: 1.25rem;
+$header-padding-block: 0.25rem;
+
 .wr-stepper {
   --wr-stepper-indicator-size: 1.75rem;
   --wr-stepper-connector: var(--wr-color-outline);
@@ -33,9 +41,19 @@
     flex-direction: column;
   }
 
+  // `flex-start`, not `center`: a step that carries a hint line
+  // (`description` / `optional`) is TALLER than its neighbours, and centring
+  // every button in the row it defines drops the short steps' circles by half
+  // the difference — the whole row reads as misaligned because of one step.
+  // Anchored at the block start, every button's first line sits at the same y,
+  // and the connector places itself against the indicator (see `&__connector`)
+  // instead of riding the row's centre.
+  //
+  // A row of same-height steps is unaffected: with equal heights `center` and
+  // `flex-start` resolve identically.
   &__header {
     display: flex;
-    align-items: center;
+    align-items: flex-start;
     flex: 1 1 auto;
     gap: 0.75rem;
     min-width: 0;
@@ -59,13 +77,20 @@
     flex: 0 0 auto;
   }
 
+  // `flex-start` here for the same reason, one level in: the indicator is a
+  // fixed-size circle and the label is a column that grows a line whenever the
+  // step has a `description` or is `optional`. Centred against the whole block,
+  // the circle slides down as the label grows and stops belonging to the step's
+  // NAME. The label carries the compensating offset (see `&__label`) rather
+  // than the indicator carrying a negative one, so the circle stays inside the
+  // button's own box.
   &__header-button {
     appearance: none;
     background: transparent;
     border: 0;
-    padding: 0.25rem 0;
+    padding: $header-padding-block 0;
     display: inline-flex;
-    align-items: center;
+    align-items: flex-start;
     gap: 0.625rem;
     color: var(--wr-color-on-surface);
     cursor: pointer;
@@ -119,7 +144,15 @@
     gap: 0.0625rem;
     font-size: var(--wr-text-sm);
     font-weight: 500;
-    line-height: 1.25rem;
+    line-height: $label-line-height;
+    // Centre the label's FIRST LINE on the indicator, now that both are anchored
+    // to the button's block start. Half the difference between the circle and one
+    // line box — derived, not typed, because `--wr-stepper-indicator-size` is a
+    // public custom property a consumer can retune. At the shipped 1.75rem this
+    // is 0.25rem, which is exactly where `align-items: center` used to put a
+    // single-line label: the one-line step renders pixel-for-pixel as before and
+    // only the multi-line one moves.
+    margin-block-start: calc((var(--wr-stepper-indicator-size) - #{$label-line-height}) / 2);
   }
 
   &__header--active &__label {
@@ -145,7 +178,13 @@
     height: 1.5px;
     background: var(--wr-stepper-connector);
     min-width: 1rem;
-    margin: 0 0.5rem;
+    // The row aligns its children to the block start now, so the line has to
+    // place itself on the indicator's centre instead of inheriting the row's.
+    // Button padding, plus half a circle, less half the line's own thickness.
+    // Same y the centred version produced for a row of equal-height steps — and
+    // unlike it, the same y when one step grows a hint line.
+    margin-block-start: calc(#{$header-padding-block} + var(--wr-stepper-indicator-size) / 2 - 0.75px);
+    margin-inline: 0.5rem;
   }
 
   &--vertical &__connector {

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/_mixins.scss

@@ -43,6 +43,16 @@
 /// }
 /// ```
 ///
+/// The reset has to sit on the element the mixin ran on. `corner-shape`
+/// does not inherit, so a component whose modifier is on the HOST while
+/// `smooth-br` is on a child needs to target that child — otherwise the
+/// declaration lands on an element that never had a squircle to undo,
+/// and, since `round` is the property's initial value, changes nothing
+/// at all. `wr-select` shipped that way: `.wr-select--rounded` set it on
+/// the host, the trigger kept `squircle` at the pill radius, and the
+/// control painted a near-rectangle — 2px of corner where a stadium
+/// wants 18.
+///
 /// @example scss
 ///   .thing {
 ///     @include smooth-br(0.625rem);