ngwr 12.2.0 → 13.0.1

package/types/ngwr-utils.d.ts

@@ -158,6 +158,52 @@ declare function round(value: number, decimals?: number): number;
  */
 declare const numAttr: (fallback: number) => (value: unknown) => number;
 
+/**
+ * @license
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://github.com/thekhegay/ngwr/blob/main/LICENSE
+ */
+/**
+ * Answers whether a value can be composed **into** a larger CSS expression
+ * without escaping the slot it was given — a colour inside a `linear-gradient()`
+ * the component builds, an entry the component joins into a custom property a
+ * stylesheet then substitutes.
+ *
+ * It is a containment check, not a colour parser. It says the value cannot
+ * terminate the construct the library wrapped around it; it says nothing about
+ * whether the value is a colour a browser will accept, and a rejected value
+ * should fall back to the component's own default rather than be repaired.
+ *
+ * **A value bound straight to `[style.background]` needs none of this.** There
+ * is nothing to break out of there, and Angular applies style values through
+ * CSSOM by design — validating those would amount to refusing style values in a
+ * style binding.
+ *
+ * Rejected, and each one is a way out of the slot:
+ *
+ * - a `)` the value never opened — `red), url(…), linear-gradient(red` is the
+ *   shape that turns a colour into an extra background layer the browser fetches;
+ * - a top-level `,` — a `<color>` is one value, so a comma at depth 0 means the
+ *   payload has reached the slot next to the one it was handed;
+ * - `;` `{` `}` a quote, a backslash, `!`, or a CSS comment delimiter;
+ * - any function outside {@link ALLOWED_FUNCTIONS} — `url()` above all.
+ *
+ * Top-level whitespace is allowed: `red 20%` is a legitimate gradient stop, and
+ * without a comma or a bare `)` it cannot reach anything.
+ *
+ * @example
+ * ```ts
+ * isSafeCssValue('var(--wr-color-primary)');                        // true
+ * isSafeCssValue('color-mix(in srgb, red 50%, blue)');              // true
+ * isSafeCssValue('red), url("https://x.test/beacon"), linear-gradient(red'); // false
+ * ```
+ *
+ * @param value Raw value handed to the component.
+ * @returns `true` when the value stays inside its slot.
+ */
+declare function isSafeCssValue(value: string): boolean;
+
 /**
  * @license
  *
@@ -446,5 +492,5 @@ declare function isPrintableKey(event: KeyboardEvent): boolean;
  */
 declare function badgeLog(badgeText: string, color: string, message: unknown): void;
 
-export { KEYS, badgeLog, clamp, debounce, getFocusableElements, getRootFontSize, hasModifier, isDefined, isNonEmptyArray, isObservable, isPrintableKey, noop, numAttr, randomId, resolveCssSize, round, throttle, trapFocus };
+export { KEYS, badgeLog, clamp, debounce, getFocusableElements, getRootFontSize, hasModifier, isDefined, isNonEmptyArray, isObservable, isPrintableKey, isSafeCssValue, noop, numAttr, randomId, resolveCssSize, round, throttle, trapFocus };
 export type { Maybe, ResolveCssSizeOptions, ResolvedCssSize, SafeAny, WrDebouncedFn, WrKey, WrThrottledFn };

package/types/ngwr-version.d.ts

@@ -16,7 +16,7 @@ import { InjectionToken } from '@angular/core';
  * Distinct from `Version` exported by `@angular/core`, which reports the
  * loaded Angular runtime version (e.g. `'22.0.0'`), not ngwr's.
  */
-declare const NGWR_VERSION = "12.2.0";
+declare const NGWR_VERSION = "13.0.1";
 
 /**
  * @license

package/typewriter/styles/_index.scss

@@ -1,38 +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;
-
-.wr-typewriter {
-  --wr-typewriter-cursor-blink: 0.5s;
-
-  display: inline-flex;
-  align-items: baseline;
-
-  &__content {
-    white-space: pre;
-  }
-
-  &__cursor {
-    display: inline-block;
-    margin-inline-start: 1px;
-    animation: wr-typewriter-blink var(--wr-typewriter-cursor-blink) ease-in-out infinite alternate;
-  }
-}
-
-@keyframes wr-typewriter-blink {
-  from {
-    opacity: 1;
-  }
-  to {
-    opacity: 0;
-  }
-}
-
-// Reduced motion: solid cursor — the blink is decorative.
-@media (prefers-reduced-motion: reduce) {
-  .wr-typewriter__cursor {
-    animation: none;
-    opacity: 1;
-  }
-}
+// Public Sass entry for `@use 'ngwr/typewriter'`.
+//
+// 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.
+// `typewriter.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. `typewriter.scss` forwards `_rules`
+// instead, so it carries this component's own CSS and nothing else.
+@use '../../theme/styles';
+@forward 'rules';

package/typewriter/styles/_rules.scss

@@ -0,0 +1,33 @@
+.wr-typewriter {
+  --wr-typewriter-cursor-blink: 0.5s;
+
+  display: inline-flex;
+  align-items: baseline;
+
+  &__content {
+    white-space: pre;
+  }
+
+  &__cursor {
+    display: inline-block;
+    margin-inline-start: 1px;
+    animation: wr-typewriter-blink var(--wr-typewriter-cursor-blink) ease-in-out infinite alternate;
+  }
+}
+
+@keyframes wr-typewriter-blink {
+  from {
+    opacity: 1;
+  }
+  to {
+    opacity: 0;
+  }
+}
+
+// Reduced motion: solid cursor — the blink is decorative.
+@media (prefers-reduced-motion: reduce) {
+  .wr-typewriter__cursor {
+    animation: none;
+    opacity: 1;
+  }
+}

package/typewriter/typewriter.scss

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

package/virtual-scroll/styles/_index.scss

@@ -1,32 +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;
-
-// Fixed-size virtual scroll wrapper. Most of the layout work is done by
-// CDK's `<cdk-virtual-scroll-viewport>`; this stylesheet just makes the
-// host a block-level container and tames default overflow behaviour.
-
-.wr-virtual-scroll {
-  display: block;
-  width: 100%;
-  overflow: hidden;
-
-  &__viewport {
-    width: 100%;
-    height: 100%;
-    // CDK already sets `overflow: auto`; just add a discreet scrollbar
-    // skin via the platform defaults — a discreet custom thumb that still matches the
-    // host application's chrome.
-    scrollbar-width: thin;
-
-    &::-webkit-scrollbar {
-      width: 0.5rem;
-      height: 0.5rem;
-    }
-    &::-webkit-scrollbar-thumb {
-      background: rgba(var(--wr-color-on-surface-rgb), 0.2);
-      border-radius: 999px;
-    }
-  }
-}
+// Public Sass entry for `@use 'ngwr/virtual-scroll'`.
+//
+// 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.
+// `virtual-scroll.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. `virtual-scroll.scss` forwards `_rules`
+// instead, so it carries this component's own CSS and nothing else.
+@use '../../theme/styles';
+@forward 'rules';

package/virtual-scroll/styles/_rules.scss

@@ -0,0 +1,27 @@
+// Fixed-size virtual scroll wrapper. Most of the layout work is done by
+// CDK's `<cdk-virtual-scroll-viewport>`; this stylesheet just makes the
+// host a block-level container and tames default overflow behaviour.
+
+.wr-virtual-scroll {
+  display: block;
+  width: 100%;
+  overflow: hidden;
+
+  &__viewport {
+    width: 100%;
+    height: 100%;
+    // CDK already sets `overflow: auto`; just add a discreet scrollbar
+    // skin via the platform defaults — a discreet custom thumb that still matches the
+    // host application's chrome.
+    scrollbar-width: thin;
+
+    &::-webkit-scrollbar {
+      width: 0.5rem;
+      height: 0.5rem;
+    }
+    &::-webkit-scrollbar-thumb {
+      background: rgba(var(--wr-color-on-surface-rgb), 0.2);
+      border-radius: 999px;
+    }
+  }
+}

package/virtual-scroll/virtual-scroll.scss

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

package/waves/styles/_index.scss

@@ -1,50 +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;
-
-// Wave-field background (reactbits port). The host fills its nearest
-// positioned ancestor; the line colour is theme-aware via
-// `--wr-waves-line-color` unless `[lineColor]` overrides it.
-
-.wr-waves {
-  --wr-waves-line-color: rgba(var(--wr-color-on-surface-rgb), 0.12);
-  // Mirrors the `xGap` input; the component publishes it so the stand-in below
-  // lands on the same pitch as the real grid.
-  --wr-waves-x-gap: 10px;
-
-  position: absolute;
-  inset: 0;
-  display: block;
-  margin: 0;
-  padding: 0;
-  overflow: hidden;
-
-  // Stand-in grid, shown until the canvas has painted.
-  //
-  // A canvas cannot be prerendered, so on an SSR'd or prerendered page this
-  // element is blank until the JS bundle has loaded and hydrated — measured at
-  // ~2.8s on ngwr.dev's own home page, where it reads as the background hanging
-  // and then popping in. These are straight lines rather than the drifting
-  // curves, at the same colour and pitch, so the handover reads as the grid
-  // coming alive rather than as content appearing.
-  background-image: repeating-linear-gradient(
-    to right,
-    var(--wr-waves-line-color) 0 1px,
-    transparent 1px var(--wr-waves-x-gap)
-  );
-
-  &--painted {
-    background-image: none;
-  }
-
-  &__canvas {
-    display: block;
-    width: 100%;
-    height: 100%;
-  }
-}
-
-[data-theme='dark'] .wr-waves {
-  --wr-waves-line-color: rgb(255 255 255 / 14%);
-}
+// Public Sass entry for `@use 'ngwr/waves'`.
+//
+// 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.
+// `waves.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. `waves.scss` forwards `_rules`
+// instead, so it carries this component's own CSS and nothing else.
+@use '../../theme/styles';
+@forward 'rules';

package/waves/styles/_rules.scss

@@ -0,0 +1,45 @@
+// Wave-field background (reactbits port). The host fills its nearest
+// positioned ancestor; the line colour is theme-aware via
+// `--wr-waves-line-color` unless `[lineColor]` overrides it.
+
+.wr-waves {
+  --wr-waves-line-color: rgba(var(--wr-color-on-surface-rgb), 0.12);
+  // Mirrors the `xGap` input; the component publishes it so the stand-in below
+  // lands on the same pitch as the real grid.
+  --wr-waves-x-gap: 10px;
+
+  position: absolute;
+  inset: 0;
+  display: block;
+  margin: 0;
+  padding: 0;
+  overflow: hidden;
+
+  // Stand-in grid, shown until the canvas has painted.
+  //
+  // A canvas cannot be prerendered, so on an SSR'd or prerendered page this
+  // element is blank until the JS bundle has loaded and hydrated — measured at
+  // ~2.8s on ngwr.dev's own home page, where it reads as the background hanging
+  // and then popping in. These are straight lines rather than the drifting
+  // curves, at the same colour and pitch, so the handover reads as the grid
+  // coming alive rather than as content appearing.
+  background-image: repeating-linear-gradient(
+    to right,
+    var(--wr-waves-line-color) 0 1px,
+    transparent 1px var(--wr-waves-x-gap)
+  );
+
+  &--painted {
+    background-image: none;
+  }
+
+  &__canvas {
+    display: block;
+    width: 100%;
+    height: 100%;
+  }
+}
+
+[data-theme='dark'] .wr-waves {
+  --wr-waves-line-color: rgb(255 255 255 / 14%);
+}

package/waves/waves.scss

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