mtrl 0.9.6 → 0.10.0-next.0

package/README.md

@@ -167,6 +167,26 @@ const createNote = (config: NoteConfig): NoteComponent =>
 
 The element gets the `mtrl-note` class, `withEvents` adds `on`, `off` and `emit`, and `destroy()` removes the element. Add `withLifecycle()` from `mtrl/core/compose/features` when features need to register cleanup.
 
+## Markup and sanitizing
+
+Icons and `content` options are markup strings, written with `innerHTML`. Every such write goes through one sink, so you can decide once how markup is treated. Set a policy when the strings can come from users or a CMS, or when your page enforces Trusted Types:
+
+```typescript
+import { configureHTML } from 'mtrl';
+
+// A sanitizer
+configureHTML({ sanitize: (html) => DOMPurify.sanitize(html) });
+
+// Trusted Types: under `require-trusted-types-for 'script'` a plain string
+// assignment throws, so return a TrustedHTML from a policy your CSP allows
+const policy = window.trustedTypes.createPolicy('mtrl', {
+  createHTML: (html) => DOMPurify.sanitize(html),
+});
+configureHTML({ sanitize: (html) => policy.createHTML(html) });
+```
+
+The policy sees every string, the library's own icons included; a `TrustedHTML` value passed as an icon or content skips it. With no policy set, markup is written as it is. Text options (`text`, a card's `text`) never go through `innerHTML`.
+
 ## Upgrading from 0.7
 
 0.8.0 aligns the components with Material 3 expressive, and some of that changes the API or the styles:

package/dist/README.md

@@ -167,6 +167,26 @@ const createNote = (config: NoteConfig): NoteComponent =>
 
 The element gets the `mtrl-note` class, `withEvents` adds `on`, `off` and `emit`, and `destroy()` removes the element. Add `withLifecycle()` from `mtrl/core/compose/features` when features need to register cleanup.
 
+## Markup and sanitizing
+
+Icons and `content` options are markup strings, written with `innerHTML`. Every such write goes through one sink, so you can decide once how markup is treated. Set a policy when the strings can come from users or a CMS, or when your page enforces Trusted Types:
+
+```typescript
+import { configureHTML } from 'mtrl';
+
+// A sanitizer
+configureHTML({ sanitize: (html) => DOMPurify.sanitize(html) });
+
+// Trusted Types: under `require-trusted-types-for 'script'` a plain string
+// assignment throws, so return a TrustedHTML from a policy your CSP allows
+const policy = window.trustedTypes.createPolicy('mtrl', {
+  createHTML: (html) => DOMPurify.sanitize(html),
+});
+configureHTML({ sanitize: (html) => policy.createHTML(html) });
+```
+
+The policy sees every string, the library's own icons included; a `TrustedHTML` value passed as an icon or content skips it. With no policy set, markup is written as it is. Text options (`text`, a card's `text`) never go through `innerHTML`.
+
 ## Upgrading from 0.7
 
 0.8.0 aligns the components with Material 3 expressive, and some of that changes the API or the styles:

package/dist/components/badge/api.d.ts

@@ -1,37 +1,31 @@
-import { BadgeComponent } from "./types.js";
+import { BadgeComponent, BadgeFeatureHost, BadgeVisibility } from "./types.js";
 /**
  * API configuration options for badge component
  * @category Components
  * @internal
  */
 interface ApiOptions {
-    visibility: {
-        show: () => void;
-        hide: () => void;
-        toggle: (visible?: boolean) => void;
-        isVisible: () => boolean;
-    };
+    visibility: BadgeVisibility;
     lifecycle: {
         destroy: () => void;
     };
 }
 /**
- * Component with required elements and methods for API enhancement
+ * What withAPI needs from the component it wraps: everything a badge feature
+ * needs, plus the events withEvents installs.
+ *
+ * This was a hand-written interface that described `config` as three optional
+ * properties. All-optional made it a weak type, so the real component -- whose
+ * config is the badge's own -- had "no properties in common" with it, and
+ * `addClass` was declared as returning the interface itself, which is the
+ * narrowing #120 removed from the source.
+ *
  * @category Components
  * @internal
  */
-interface ComponentWithElements {
-    element: HTMLElement;
-    wrapper?: HTMLElement;
-    config: {
-        max?: number;
-        label?: string | number;
-        variant?: string;
-    };
-    getClass: (name: string) => string;
-    addClass: (...classes: string[]) => ComponentWithElements;
-    on: (event: string, handler: Function) => ComponentWithElements;
-    off: (event: string, handler: Function) => ComponentWithElements;
+interface ComponentWithElements extends BadgeFeatureHost {
+    on(event: string, handler: Function): this;
+    off(event: string, handler: Function): this;
 }
 /**
  * Enhances a badge component with API methods.

package/dist/components/badge/api.js

@@ -1,3 +1,4 @@
+import { isBadgeOverflow, isEmptyBadgeLabel } from "./config.js";
 import { formatBadgeLabel } from "./config.js";
 const VARIANT_SMALL = "small";
 const ALL_COLORS = [
@@ -25,12 +26,10 @@ export const withAPI = ({ visibility, lifecycle }) => (component) => {
             const formattedLabel = formatBadgeLabel(label, component.config.max);
             component.element.textContent = formattedLabel;
             component.element.classList.remove(`${component.getClass("badge")}--overflow`);
-            if (typeof label === "number" &&
-                component.config.max !== undefined &&
-                label > component.config.max) {
+            if (isBadgeOverflow(label, component.config.max)) {
                 component.element.classList.add(`${component.getClass("badge")}--overflow`);
             }
-            if (formattedLabel === "" || formattedLabel === "0") {
+            if (isEmptyBadgeLabel(formattedLabel)) {
                 badgeComponent.hide();
             }
             else {
@@ -109,7 +108,7 @@ export const withAPI = ({ visibility, lifecycle }) => (component) => {
                 component.wrapper.removeChild(component.element);
             }
             const wrapper = document.createElement("div");
-            wrapper.classList.add(component.getClass("badge-wrapper"));
+            wrapper.classList.add(component.getClass("badge__wrapper"));
             wrapper.style.position = "relative";
             const parent = target.parentNode;
             if (parent) {