@webority/theme 0.13.4 → 0.14.0

package/README.md

@@ -24,12 +24,56 @@ load-bearing**:
 @import "@webority/theme/scss/wui-components";
 // Optional — marketing sites only (heroes, section-y, pill CTAs, reveal motion):
 // @import "@webority/theme/scss/marketing";
+// Optional, only if the site renders the phone input or country picker (see Country flags):
+// @import "@webority/theme/scss/flags";
 ```
 
 Importing part of the core chain is a bug: skipping `wui-aliases` leaves every
-`--color-*` reference unresolved. Country flags are pulled by `wui-components`
-for the phone control — do not import `flags` a second time (legacy `@import`
-does not dedupe).
+`--color-*` reference unresolved.
+
+### Country flags are opt-in
+
+The 245 `.wui-flag-*` rules are about 187 KB raw (38 KB Brotli) of inlined SVG, so
+`wui-components` does not include them. A site that renders `AppPhoneNumberInput`,
+`<app-phone-number-input>`, `AppCountrySelect` or `<app-country-select>` adds them once:
+
+- **Your own SCSS:** `@import "@webority/theme/scss/flags";` after `wui-components`. Import it once;
+  legacy `@import` does not dedupe, so a second import doubles every flag rule.
+- **Precompiled CSS:** link `@webority/theme/css/flags` (`dist/webority-flags.css`). The Razor
+  package serves the same file at `_content/Webority.Ui.Razor/css/webority-flags.css`.
+- **Per page:** on a site with one phone field, link the flags stylesheet only on the pages that
+  render it. Without it every flag is an empty grey box, and nothing reports the cause.
+
+### Purging unused CSS (PurgeCSS)
+
+A consuming site's PurgeCSS pass reads its own pages, but `Webority.Ui.Razor` ships as a DLL and the
+React and elements packages ship as bundles, so the markup they render at runtime is invisible to it.
+`@webority/theme` therefore ships `purge-safelist.json`, generated by `scripts/gen-purge-safelist.mjs`
+at theme build time from the tag helpers, custom elements, React components and the compiled CSS:
+
+- `classes`: every theme class the library's own markup names.
+- `patterns`: regular-expression sources (`^btn-`, `^wui-flag-`, ...) for classes the library builds
+  from a prefix at runtime, where the tail is only known in the browser.
+
+A Razor site already installs `@webority/theme` for its SCSS build, so the file is in its `node_modules`.
+Wire it into PurgeCSS (`purgecss.config.cjs`, run after `sass` and before the file is committed):
+
+```js
+const { classes, patterns } = require("@webority/theme/purge-safelist.json");
+
+module.exports = {
+    content: ["Pages/**/*.cshtml", "wwwroot/js/**/*.js"],
+    css: ["wwwroot/css/site.css"],
+    safelist: {
+        standard: [...classes, ...patterns.map((p) => new RegExp(p))],
+        // Bootstrap state classes and attribute selectors the library toggles at runtime.
+        greedy: [/^data-bs-/, /^wui-/],
+    },
+};
+```
+
+Add your own safelist entries for classes your page scripts add. PurgeCSS failures are silent, so
+compare every page before and after a purge.
 
 **`$secondary`** is quiet grey (de-emphasised text/buttons), not a second brand
 colour — intentional shared semantics (see `_variables.scss`).
@@ -178,7 +222,7 @@ Keep shipping all of these; classify for **when to use**, not for removal:
 | Tier | Components | Library? | Notes |
 |---|---|---|---|
 | **Portal core** | Shell, DataTable, fields/selects, Modal, Confirm, Tabs, Card, Alert, Badge, StatusBadge, Stepper, File*, Date*, Phone, OTP, Toast, Empty/Skeleton/Spinner | **Yes — never product-fork** | Daily product UI |
-| **Portal display** | `AppKpiTile`, `AppInfoList`, `AppTimeline`, `AppCallout`, `AppSplash`, `AppBanner`, `AppBreadcrumbs`, `AppProgress`, `AppMeter` | **Yes** | Shared across portals |
+| **Portal display** | `AppKpiTile`, `AppInfoList`, `AppTimeline`, `AppSplash`, `AppBanner`, `AppBreadcrumbs`, `AppProgress`, `AppMeter` | **Yes** | Shared across portals |
 | **Commercial / plan UI** | `AppPricingCard`, `AppCompareTable`, `AppResourceCard` | **Yes — keep** | Pricing pages **and** in-app plan/billing. Editorial shape, not a second design system. Moving them to products would break React↔Razor parity. |
 | **CSS marketing only** | section-y, btn-pill, reveal, marquee, … | **Opt-in partial** | Not App*; see marketing import above |