ngwr 15.0.0-rc.2 → 15.0.0

package/README.md

@@ -9,7 +9,7 @@ Signals-first UI components for Angular.
 [![coverage](https://codecov.io/gh/thekhegay/ngwr/branch/main/graph/badge.svg)](https://codecov.io/gh/thekhegay/ngwr)
 [![license](https://img.shields.io/npm/l/ngwr)](https://github.com/thekhegay/ngwr/blob/main/LICENSE)
 
-[Documentation](https://ngwr.dev) · [Getting started](https://ngwr.dev/start/installation) · [Playground](https://ngwr.dev/start/playground) · [Why ngwr](https://ngwr.dev/start/comparison) · [Changelog](https://github.com/thekhegay/ngwr/blob/main/CHANGELOG.md)
+[Documentation](https://ngwr.dev) · [Getting started](https://ngwr.dev/docs/installation) · [Playground](https://stackblitz.com/github/thekhegay/ngwr/tree/main/projects/starter?file=src/app/app.ts) · [Changelog](https://github.com/thekhegay/ngwr/blob/main/CHANGELOG.md)
 
 ngwr's form controls implement `FormValueControl` and `FormCheckboxControl`
 from Signal Forms directly. `[formField]` binds to each component's own `value`
@@ -62,9 +62,10 @@ reactive forms bind too, with limits the
 - Angular CDK [test harnesses](https://ngwr.dev/guides/testing) for the form
   controls and overlays.
 
-Browse the [components](https://ngwr.dev/reference/components) and
-[animations](https://ngwr.dev/animations) with live demos. Directives, pipes,
-services and validators are in the [reference](https://ngwr.dev/reference).
+Browse the [components](https://ngwr.dev/reference/components),
+[charts](https://ngwr.dev/charts) and [bits](https://ngwr.dev/bits) (animations
+and visual effects) with live demos. Directives, pipes, services and validators
+are in the [reference](https://ngwr.dev/reference).
 
 ## Installation
 
@@ -85,8 +86,9 @@ npm install ngwr @angular/cdk
 yarn add ngwr @angular/cdk
 ```
 
-The optional packages (an icon set, ProseMirror for the editor) are listed in
-the [installation guide](https://ngwr.dev/start/installation).
+The optional packages are an icon set, shown in the
+[installation guide](https://ngwr.dev/docs/installation), and ProseMirror for
+the [editor](https://ngwr.dev/reference/components/editor).
 
 ## Styles
 
@@ -103,7 +105,8 @@ where `$base-colors` goes.
 @use 'ngwr/checkbox';
 ```
 
-Utilities are opt-in and come with nothing:
+Utilities are opt-in. Write them below `@use 'ngwr/theme'`, since some of them
+load the token layer too:
 
 ```scss
 @use 'ngwr/reset'; // box-sizing, body margin, sane defaults
@@ -132,6 +135,8 @@ providers: [
 ],
 ```
 
+`withDensity()` and the `[wrDensity]` directive also need
+`@use 'ngwr/density';` in your styles: no component loads the density scale.
 Icons and translations have calls of their own. The
 [configuration guide](https://ngwr.dev/docs/configuration) lists every feature.
 
@@ -142,9 +147,10 @@ ng update ngwr
 ```
 
 This installs the latest version and runs its migrations. The
-[migration guide](https://ngwr.dev/start/migration) describes the changes in
-each major. The Angular badge shows the lowest Angular version ngwr needs.
-[Versioning](https://ngwr.dev/start/versioning) explains the support policy.
+[migration guide](https://ngwr.dev/docs/migration) describes the changes in
+each major. The Angular badge shows the Angular versions ngwr supports, and
+[SECURITY.md](https://github.com/thekhegay/ngwr/blob/main/SECURITY.md) lists the
+majors that still get fixes.
 
 ## AI agents
 
@@ -159,8 +165,8 @@ and read component APIs. Add it to your client:
 }
 ```
 
-The [MCP guide](https://ngwr.dev/guides/mcp) covers each client. Agents without
-MCP can use the [agent skill](https://ngwr.dev/guides/agent-skill),
+The [MCP guide](https://ngwr.dev/docs/mcp-server) covers each client. Agents
+without MCP can use the [agent skill](https://ngwr.dev/docs/skills),
 [llms.txt](https://ngwr.dev/llms.txt), or any docs page as markdown by adding
 `.md` to its URL.
 

package/affix/styles/_index.scss

@@ -1,6 +1,6 @@
-// Almost nothing — the directive does the work inline. This layer owns one
-// declaration, the stacking order below, and otherwise only exposes the class
-// hook a consumer styles the "stuck" state with.
+// Almost nothing — the directive does the work inline. This layer owns the
+// stacking order below and the containing block of a flex or grid parent, and
+// otherwise only exposes the class hook a consumer styles the "stuck" state with.
 //
 // The directive sets `position: sticky; top: <offset>px` on the host and
 // toggles `wr-affix--active` via an IntersectionObserver sentinel.
@@ -13,3 +13,12 @@
   // the active modifier is the consumer's to style.
   z-index: 10;
 }
+
+// A flex or grid parent holds the sentinel out of the flow, absolutely
+// positioned, and has to be its containing block or the sentinel stops
+// scrolling with a nested scroller's content. Zero specificity on purpose: any
+// position the author gives the parent wins, a media query included, and a
+// positioned parent is a containing block all the same.
+:where(.wr-affix__container) {
+  position: relative;
+}

package/avatar/styles/_index.scss

@@ -152,6 +152,17 @@
   // a 96px one — and the colour and size written here never painted once.
   // Specificity, not order, so it holds for an app that `@use`s the two entry
   // points in either order.
+  // The failed image's name, kept for assistive technology when nothing else
+  // names the avatar. Taken out of the flex line so it moves nothing, and gone
+  // (from the tree too) when initials are projected, since they name it then.
+  &__alt {
+    position: absolute;
+  }
+
+  &__content:not(:empty) ~ &__alt {
+    display: none;
+  }
+
   &__spin.wr-spinner {
     position: absolute;
     // A loading indicator is a status GRAPHIC, which 1.4.11 holds to 3:1: the

package/badge/styles/_index.scss

@@ -105,10 +105,17 @@
   --wr-badge-color: var(--wr-color-on-surface);
   --wr-badge-border: var(--wr-border-base);
 
+  // An intent sets the three hooks rather than the properties they feed, the way
+  // `wr-tag` does, so the hooks the docs list still restyle a coloured badge —
+  // which is every badge by default, since `color` defaults to `primary`. Writing
+  // `background-color` and `color` here left `--wr-badge-bg` / `-color` / `-border`
+  // working only with `[color]="null"`.
   @each $name in theme.$colors {
     &--#{$name} {
-      background-color: var(--wr-color-#{$name});
-      color: var(--wr-color-#{$name}-contrast);
+      --wr-badge-bg: var(--wr-color-#{$name});
+      --wr-badge-color: var(--wr-color-#{$name}-contrast);
+      // Read only by the outlined ring below.
+      --wr-badge-border: var(--wr-color-#{$name}-soft-border);
     }
   }
 
@@ -125,17 +132,16 @@
   // draws the same ring from the same token; the tag keeps its 6% fill, because
   // a tag is a chip you can click and a badge is a label you cannot.
   &--outlined {
-    background-color: transparent;
-    // `--wr-badge-border` rather than `currentcolor` for the NEUTRAL case, for
-    // the reason the note above gives about the chromatic ones: a ring drawn in
-    // the text colour is a hairline at full label strength around text of
-    // exactly that strength. An intent overrides it in the loop below.
+    --wr-badge-bg: transparent;
+    // `--wr-badge-border` rather than `currentcolor`, for the reason the note
+    // above gives: a ring drawn in the text colour is a hairline at full label
+    // strength around text of exactly that strength. An intent sets the hook to
+    // its `-soft-border` in the loop above.
     box-shadow: inset 0 0 0 1px var(--wr-badge-border);
 
     @each $name in theme.$colors {
       &.wr-badge--#{$name} {
-        color: var(--wr-color-#{$name}-ink);
-        box-shadow: inset 0 0 0 1px var(--wr-color-#{$name}-soft-border);
+        --wr-badge-color: var(--wr-color-#{$name}-ink);
       }
     }
   }

package/bits/decrypt-text/decrypt-text.scss

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

package/bits/decrypt-text/styles/_index.scss

@@ -1,26 +1,15 @@
-.wr-decrypt-text {
-  display: inline-block;
-  white-space: pre-wrap;
-
-  &__sr-only {
-    position: absolute;
-    width: 1px;
-    height: 1px;
-    margin: -1px;
-    padding: 0;
-    overflow: hidden;
-    clip: rect(0, 0, 0, 0);
-    border: 0;
-  }
-
-  &__char {
-    display: inline;
-  }
-
-  // Hook for consumers to style the scrambled state distinctly (e.g. dim
-  // the scramble glyphs). Apply via `[encryptedClassName]`-style overrides
-  // by extending `.wr-decrypt-text__char--encrypted`.
-  &__char--encrypted {
-    /* default: no visual change; consumers override as needed */
-  }
-}
+// Public Sass entry for `@use 'ngwr/bits/decrypt-text'`.
+//
+// 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.
+// `decrypt-text.scss` is the component's `styleUrl`, and a component stylesheet
+// is its OWN Sass compilation — `@use` only deduplicates within one. So while
+// the app's global stylesheet emits the theme once, forwarding it from here
+// would inline a second, byte-identical copy of `:root` and the box-sizing
+// reset into the compiled component styles, which the library build then embeds
+// in the FESM bundle as a string. `decrypt-text.scss` forwards `_rules` instead,
+// so it carries this component's own CSS and nothing else.
+@use '../../../theme/styles';
+@forward 'rules';

package/bits/decrypt-text/styles/_rules.scss

@@ -0,0 +1,40 @@
+.wr-decrypt-text {
+  display: inline-block;
+  white-space: pre-wrap;
+
+  &__sr-only {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    margin: -1px;
+    padding: 0;
+    overflow: hidden;
+    clip: rect(0, 0, 0, 0);
+    border: 0;
+  }
+
+  &__char {
+    display: inline;
+  }
+
+  // `click` mode makes the host a button. The ring is written from the shared
+  // `--wr-focus-ring-*` tokens, the way `theme.focus-ring` writes it: this is the
+  // component stylesheet's half, which loads no theme module, since one that did
+  // would carry a second copy of the token layer.
+  &--interactive {
+    cursor: pointer;
+
+    &:focus-visible {
+      outline: var(--wr-focus-ring-width) solid var(--wr-focus-ring-color);
+      outline-offset: var(--wr-focus-ring-offset);
+      box-shadow: 0 0 0 var(--wr-focus-ring-offset) var(--wr-focus-ring-halo);
+    }
+  }
+
+  // Hook for consumers to style the scrambled state distinctly (e.g. dim
+  // the scramble glyphs). Apply via `[encryptedClassName]`-style overrides
+  // by extending `.wr-decrypt-text__char--encrypted`.
+  &__char--encrypted {
+    /* default: no visual change; consumers override as needed */
+  }
+}

package/bits/falling-text/styles/_rules.scss

@@ -2,10 +2,16 @@
   position: relative;
   display: block;
   overflow: hidden;
-  touch-action: none; // pointer-driven drag — disable browser scroll on touch
 
   &__words {
     line-height: 1.4;
+    // The words take their ORDER from the text (`dir="auto"` in the template)
+    // and their alignment from the page, which is what plain text does: a Latin
+    // sentence on an RTL page still sits at the right. Chromium knows only the
+    // prefixed keyword and drops the standard one, which Firefox needs.
+    // rtl-ok: `match-parent` IS direction-aware — `start` resolved against the parent
+    text-align: -webkit-match-parent;
+    text-align: match-parent;
   }
 
   &__word {
@@ -18,6 +24,13 @@
       cursor: grabbing;
     }
 
+    // Only a released word takes its touches for the drag. On the whole host this
+    // made the block a scroll dead zone on every touch screen — before the words
+    // fell, and under reduced motion, where they never do.
+    .wr-falling-text--released & {
+      touch-action: none;
+    }
+
     &--hl {
       // A highlighted WORD is text the user reads, decorative motion or not.
       color: var(--wr-color-primary-ink);

package/bits/marquee/styles/_rules.scss

@@ -15,6 +15,15 @@
   display: block;
   width: 100%;
   overflow: hidden;
+  // The loop is physical (see `&__item` below): the track starts at the left
+  // edge, its copies extend to the right, and `translate3d(-offset)` walks it
+  // left. Under an inherited RTL the host anchors the over-wide track at its
+  // RIGHT edge with the copies running left, and the same translate opened a
+  // blank gap of up to one sequence there every cycle. It has to be the host,
+  // not the track: which edge an over-wide block sticks to is decided by its
+  // containing block's direction. Each item restores the document's direction
+  // for its own content below.
+  direction: ltr;
 
   &--scale-hover {
     padding-top: calc(var(--wr-marquee-height) * 0.1);
@@ -50,6 +59,13 @@
     margin-right: var(--wr-marquee-gap);
     font-size: var(--wr-marquee-height);
     line-height: 1;
+
+    // `:dir()` reads the DOCUMENT's direction (the `dir` attribute), which the
+    // track's CSS `direction: ltr` does not change — so the text inside an item
+    // keeps the page's direction while the strip itself stays physical.
+    &:dir(rtl) {
+      direction: rtl;
+    }
   }
 
   &__item:last-child {
@@ -137,6 +153,39 @@
     );
   }
 
+  // Reduced motion. The loop is off and the component renders one copy, so a
+  // frozen `overflow: hidden` strip would put every item past the edge out of
+  // reach; the host scrolls instead. It is the named region, and it takes a tab
+  // stop of its own when no item has one (the component decides), so the
+  // keyboard can scroll it. Set from the live preference rather than from the
+  // media query below, because the copies that query cannot remove are what
+  // would scroll into view.
+  &--static {
+    overflow-x: auto;
+    // Not `visible`: next to an `auto` axis it computes to `auto`, and the
+    // scale-on-hover padding is sized to keep a scaled item inside the box.
+    overflow-y: hidden;
+    overscroll-behavior-x: contain;
+
+    // The ring is written from the shared `--wr-focus-ring-*` tokens, the way
+    // `theme.focus-ring` writes it (see `wr-decrypt-text`), and drawn INSIDE the
+    // box: the strip is full width, so an outset ring is cut off by whatever
+    // clips the page around it.
+    &:focus-visible {
+      outline: var(--wr-focus-ring-width) solid var(--wr-focus-ring-color);
+      outline-offset: calc(var(--wr-focus-ring-width) * -1);
+      box-shadow: inset 0 0 0 calc(var(--wr-focus-ring-width) + var(--wr-focus-ring-offset)) var(--wr-focus-ring-halo);
+    }
+  }
+
+  // The fades hide a seam that a still strip does not have, and on a scroller
+  // they would sit over the first and last items for good — absolutely placed
+  // inside the scroll container, they scroll away with the content.
+  &--static::before,
+  &--static::after {
+    display: none;
+  }
+
   @media (prefers-reduced-motion: reduce) {
     .wr-marquee__track {
       transform: translate3d(0, 0, 0) !important;

package/bits/typewriter/styles/_rules.scss

@@ -4,6 +4,18 @@
   display: inline-flex;
   align-items: baseline;
 
+  // Same shape as `wr-rotating-text`: the typed text is a fragment most of the
+  // time, so the whole sentence is carried once here for a screen reader.
+  &__sr-only {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    overflow: hidden;
+    clip: rect(0 0 0 0);
+    clip-path: inset(50%);
+    white-space: nowrap;
+  }
+
   &__content {
     white-space: pre;
   }

package/breadcrumbs/styles/_rules.scss

@@ -48,9 +48,12 @@
     align-items: center;
     gap: var(--wr-breadcrumbs-gap);
 
-    // Separator before every item except the first.
+    // Separator before every item except the first. The empty alternative text
+    // after the `/` keeps it out of the accessibility tree: generated content is
+    // read like any other text, so the trail was announced "Home, slash,
+    // Components, slash, …" and the current crumb as "slash Current page".
     &:not(:first-child)::before {
-      content: var(--wr-breadcrumbs-separator);
+      content: var(--wr-breadcrumbs-separator) / '';
       color: var(--wr-breadcrumbs-separator-color);
       user-select: none;
     }

package/button/styles/_index.scss

@@ -224,9 +224,15 @@
     flex-direction: row-reverse;
   }
 
-  // Loading — hide label/icon contents but keep their footprint
+  // Loading — hide label/icon contents but keep their footprint. The label by
+  // `opacity` rather than `visibility`: a `visibility: hidden` label leaves the
+  // accessibility tree, and the button was then named after its spinner, so every
+  // loading button on a page was called "Loading".
   &--loading {
-    .wr-btn__label,
+    .wr-btn__label {
+      opacity: 0;
+    }
+
     .wr-btn__icon {
       visibility: hidden;
     }
@@ -324,23 +330,27 @@
   }
 
   // Solid colored segments share border and background color, so adjacent
-  // buttons fuse into one slab — draw a subtle divider on the right edge of
-  // every non-last segment. Outlined/default variants keep their own visible
+  // buttons fuse into one slab — draw a subtle divider on the inline-end edge
+  // of every non-last segment. Outlined/default variants keep their own visible
   // borders. On hover/focus the segment raises its own border (z-index above
   // neighbours), which would otherwise double-paint that edge — so drop the
   // seam there and let the raised border own it cleanly.
   @each $name in theme.$colors {
     > .wr-btn--#{$name}:not(.wr-btn--outlined):not(:last-child) {
-      // `box-shadow` offsets are physical by spec — there is no logical form to
-      // convert to. The seam lands on the wrong edge under RTL; fixing it needs a
-      // `[dir]` rule or a real border, which is beyond a property-level rewrite.
+      // rtl-ok: `box-shadow` offsets are physical by spec, with no logical form,
+      // so the inline-end edge is spelled once per direction. `:dir()` reads the
+      // element's own direction, so no ancestor selector is involved.
       box-shadow: inset -1px 0 0 color-mix(in srgb, var(--wr-color-black) 20%, transparent);
 
+      &:dir(rtl) {
+        box-shadow: inset 1px 0 0 color-mix(in srgb, var(--wr-color-black) 20%, transparent);
+      }
+
+      // After the `:dir(rtl)` rule, which it ties on specificity.
       &:hover,
       &:focus-visible {
         box-shadow: none;
       }
-      // rtl-ok: box-shadow has no logical equivalent — see above
     }
   }
 }

package/carousel/styles/_index.scss

@@ -35,6 +35,14 @@
     height: 100%;
     transition: transform var(--wr-duration-slow) var(--wr-ease-out);
     will-change: transform;
+
+    // The slide still changes — autoplay included — it just no longer travels
+    // across the full width of the carousel to get there: a full-width panel
+    // moving on its own is the motion the preference asks to remove. Bootstrap's
+    // carousel makes the same call.
+    @media (prefers-reduced-motion: reduce) {
+      transition: none;
+    }
   }
 }
 
@@ -79,11 +87,17 @@
       background var(--wr-transition-base),
       transform var(--wr-transition-base);
 
-    &:hover {
+    &:hover:not(:disabled) {
       background: var(--wr-color-surface);
       transform: translateY(-50%) scale(1.05);
     }
 
+    // Only without `loop`, at the end the arrow points past.
+    &:disabled {
+      cursor: not-allowed;
+      opacity: var(--wr-disabled-opacity);
+    }
+
     // The track's motion is direction-aware now — `carousel.ts` signs its
     // `translateX` and its swipe threshold from `Directionality` — so the arrows
     // follow the reading direction too. "Previous" is where the earlier slides

package/charts/bar-chart/styles/_index.scss

@@ -35,19 +35,41 @@
     --wr-bar-chart-value-font-size: var(--wr-text-xs);
     --wr-bar-chart-value-line-height: var(--wr-leading-none);
 
+    flex: none;
+    // Bounded by its column and ellipsised, as the label under it is. With no bound,
+    // forty five-digit values at 1280px overlapped their neighbours into one smear and
+    // the outermost hung past the chart. The tooltip and the column's name carry the
+    // whole number.
+    max-width: 100%;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
     font-size: var(--wr-bar-chart-value-font-size);
     color: var(--wr-color-on-surface-muted);
     font-variant-numeric: tabular-nums;
     line-height: var(--wr-bar-chart-value-line-height);
   }
 
+  // The component writes the bar's share of the plot as its `flex-grow`, from 0
+  // to 1. Factors that sum to less than 1 hand out only that fraction of the free
+  // space, so the bar gets exactly its share of what the column has left after
+  // the value above it, and the value rides on the bar's top. It was a `height`
+  // percentage of the WHOLE column, so the tallest bars plus their value
+  // overflowed it and flex-shrink took the difference out of them alone:
+  // measured in Chromium, WebKit and Firefox, 24 drew at 183px beside 12 at
+  // 99.5px, and 22 at 182.4px — the same height as 24.
   &__bar {
     --wr-bar-chart-bar-radius: var(--wr-border-radius-sm);
 
+    flex: 0 0 0;
     width: 100%;
     border-radius: var(--wr-bar-chart-bar-radius) var(--wr-bar-chart-bar-radius) 0 0;
-    transition: height var(--wr-duration-slow) var(--wr-ease-out);
+    transition: flex-grow var(--wr-duration-slow) var(--wr-ease-out);
     min-height: 1px;
+    // The bar is an inline `background`, which forced colors resets to `Canvas`:
+    // every bar vanished into the page and left its value floating over the
+    // baseline. The SVG charts keep their fills there, so the HTML marks do too.
+    forced-color-adjust: none;
   }
 
   &__labels {

package/charts/calendar-heatmap/styles/_index.scss

@@ -90,6 +90,10 @@
     // border-radius tokens (5px+) would read as near-circles at this size.
     border-radius: 2px;
     transition: transform var(--wr-transition-base);
+    // An inline `background`, which forced colors resets to `Canvas`: the whole
+    // year vanished and left the month and weekday labels. The SVG charts keep
+    // their fills there, so the squares do too.
+    forced-color-adjust: none;
 
     &:hover {
       transform: scale(1.4);

package/charts/donut-chart/styles/_index.scss

@@ -89,6 +89,9 @@
     width: 0.625rem;
     height: 0.625rem;
     border-radius: 50%;
+    // The key to the slices, whose SVG fills forced colors keeps — so an inline
+    // `background` reset to `Canvas` left the legend pointing at nothing.
+    forced-color-adjust: none;
   }
 
   &__legend-label {