@appshell/webpack-plugin 1.0.0-alpha.22 → 1.0.0-alpha.24

package/dist/types/config/src/index.d.ts

@@ -11,6 +11,6 @@ export { default as outdated } from './outdated';
 export { activate, publish } from './publish';
 export type { PublishOptions, PublishResult } from './publish';
 export { default as sync } from './sync';
-export type { AppshellComposition, AppshellConfig, AppshellConfigRemote, AppshellIndex, AppshellManifest, AppshellRemote, AppshellTemplate, ComparisonResult, ComparisonResults, ComparisonTarget, Metadata, ModuleFederationPluginOptions, PackageSpec, ResolvedRemote, Schema, SharedConfig, SharedModuleSpec, } from './types';
+export type { AppshellComposition, AppshellConfig, AppshellConfigRemote, AppshellIndex, AppshellManifest, AppshellRemote, AppshellTemplate, AppshellTokenUsage, ComparisonResult, ComparisonResults, ComparisonTarget, Metadata, ModuleFederationPluginOptions, PackageSpec, ResolvedRemote, Schema, SharedConfig, SharedModuleSpec, } from './types';
 export * as utils from './utils';
 export * as validators from './validators';

package/dist/types/config/src/types.d.ts

@@ -68,6 +68,7 @@ export type AppshellTemplate<TMetadata = Metadata> = {
     remotes?: Record<string, AppshellConfigRemote<TMetadata>>;
     module: ModuleFederationPluginOptions;
     vars?: Record<string, unknown>;
+    tokens?: Record<string, AppshellTokenUsage>;
     overrides?: AppshellOverrides;
 };
 /** Appshell manifest types */
@@ -83,10 +84,25 @@ export type AppshellRemote<TMetadata = Metadata> = {
 export type AppshellOverrides = {
     vars: Record<string, Record<string, string | number | undefined>>;
 };
+/**
+ * Which design tokens a package's own output reaches for. Observed from the emitted
+ * assets rather than declared: the CSS already says it, and a hand-kept list is a copy
+ * that drifts the first time someone adds a token and forgets the yaml.
+ *
+ * `required` is a reference with no fallback — the package has no plan B. `optional` is
+ * `var(--appshell-x, something)`, which degrades on its own. That split is read off what
+ * the author wrote rather than asked of them.
+ */
+export type AppshellTokenUsage = {
+    required: string[];
+    optional: string[];
+};
 export type AppshellManifest<TMetadata = Metadata> = {
     remotes: Record<string, AppshellRemote<TMetadata>>;
     modules: Record<string, ModuleFederationPluginOptions>;
     vars: Record<string, Record<string, string | number | undefined>>;
+    /** Keyed by federation scope, so a merged manifest still says which package needs what. */
+    tokens?: Record<string, AppshellTokenUsage>;
     overrides?: AppshellOverrides;
 };
 export type AppshellIndex = Record<string, string>;

package/dist/types/tokens/src/contract.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The token contract: the complete, fixed vocabulary a package may consume and an
+ * Application must supply.
+ *
+ * Small and stable is the property that matters. A package authors against these names
+ * with fallbacks (`var(--appshell-primary, #0af)`) and renders standalone; an Application
+ * supplies the values and every package it composes moves together.
+ */
+export type Mode = 'light' | 'dark';
+/** Colour roles an Application's *base* supplies — everything not tied to the accent. */
+export declare const BASE_COLOR_ROLES: readonly ["surface", "on-surface", "surface-raised", "on-surface-raised", "text-muted", "border", "danger", "on-danger", "warning", "on-warning", "success", "on-success"];
+/** Colour roles an Application's *accent* supplies. */
+export declare const ACCENT_COLOR_ROLES: readonly ["primary", "on-primary", "secondary", "on-secondary"];
+/**
+ * Derived rather than authored. Hover and active are computed from their accent with
+ * `color-mix`, and the focus ring is picked per base+accent so it stays visible. A theme
+ * may override any of them; none has to be supplied.
+ */
+export declare const DERIVED_COLOR_ROLES: readonly ["primary-hover", "primary-active", "secondary-hover", "secondary-active", "focus-ring"];
+/**
+ * Named for their role, not their size. A numeric scale would reintroduce exactly the
+ * divergence this contract exists to prevent — one author mapping `h1` to `2xl` and
+ * another to `xl` is how headings stop matching across a composed page.
+ */
+export declare const TYPE_ROLES: readonly ["font-body", "font-mono", "font-size-h1", "font-size-h2", "font-size-h3", "font-size-h4", "font-size-h5", "font-size-h6", "font-size-body", "font-size-small", "line-height-tight", "line-height-normal"];
+/** Genuinely a scale. Nobody wants `--appshell-space-card-padding`. */
+export declare const DIMENSION_ROLES: readonly ["space-xs", "space-sm", "space-md", "space-lg", "space-xl", "radius-sm", "radius-md", "radius-lg"];
+export type BaseColorRole = (typeof BASE_COLOR_ROLES)[number];
+export type AccentColorRole = (typeof ACCENT_COLOR_ROLES)[number];
+export type DerivedColorRole = (typeof DERIVED_COLOR_ROLES)[number];
+export type TypeRole = (typeof TYPE_ROLES)[number];
+export type DimensionRole = (typeof DIMENSION_ROLES)[number];
+export type TokenRole = BaseColorRole | AccentColorRole | DerivedColorRole | TypeRole | DimensionRole;
+export declare const TOKEN_ROLES: readonly TokenRole[];
+export type BaseTokens = Record<BaseColorRole, string>;
+export type AccentTokens = Record<AccentColorRole, string>;
+export type Theme = Record<TokenRole, string>;
+/** The custom property a role is published as. */
+export declare const cssVar: (role: TokenRole) => string;
+/**
+ * Pairs the registry checks for contrast. Because every role that carries text has an
+ * `on-` partner, a theme cannot express illegible text without failing this list — which
+ * is the failure that actually reaches users, and the one a CSS parser alone never catches.
+ */
+export declare const TEXT_PAIRS: readonly (readonly [TokenRole, TokenRole])[];
+/** Muted text has no `on-` partner; it is read against both surfaces. */
+export declare const MUTED_AGAINST: readonly TokenRole[];
+/** Non-text, so 3:1 rather than 4.5:1 — WCAG 1.4.11. */
+export declare const NON_TEXT_PAIRS: readonly (readonly [TokenRole, TokenRole])[];
+export declare const AA_TEXT = 4.5;
+export declare const AA_NON_TEXT = 3;

package/dist/types/tokens/src/contrast.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Contrast checking for a theme.
+ *
+ * Syntax validation on its own earns little: it catches `--appshell-primary: bananas` and
+ * misses `--appshell-on-primary: #fff` on `--appshell-primary: #fff`, which is valid CSS
+ * and invisible text. Checking the `on-` pairs catches the failure that reaches users, and
+ * subsumes syntax validation for free — a value that will not parse cannot be measured.
+ */
+import { type Theme, type TokenRole } from './contract';
+type Rgb = [number, number, number];
+/** Returns undefined rather than throwing — an unmeasurable value is reported, not fatal. */
+export declare const parseColor: (value: string) => Rgb | undefined;
+/** WCAG 2.1 contrast ratio, 1–21. */
+export declare const contrastRatio: (a: Rgb, b: Rgb) => number;
+/**
+ * A colour as `#rrggbb`.
+ *
+ * `<meta name="theme-color">` takes a CSS colour, but browser support for `oklch` there
+ * is not something to rely on for a hint the page cannot detect the failure of — a
+ * value the browser does not understand is simply ignored, silently.
+ */
+export declare const toHex: (value: string) => string | undefined;
+export type ContrastFinding = {
+    roles: [TokenRole, TokenRole];
+    ratio?: number;
+    required: number;
+    reason: 'below-threshold' | 'unparseable';
+};
+/**
+ * Every finding for a theme. Empty means it passes.
+ *
+ * `color-mix` values are skipped rather than failed: hover and active are derived from
+ * roles that are themselves checked, and resolving them needs a browser.
+ */
+export declare const validateTheme: (theme: Theme) => ContrastFinding[];
+export declare const describeFinding: ({ roles, ratio, required, reason }: ContrastFinding) => string;
+export {};

package/dist/types/tokens/src/index.d.ts

@@ -0,0 +1,4 @@
+export * from './contract';
+export { contrastRatio, describeFinding, parseColor, toHex, validateTheme, type ContrastFinding, } from './contrast';
+export { ACCENTS, BASES, FOCUS_RINGS } from './presets';
+export { composeTheme, DEFAULT_TYPE_AND_DIMENSIONS, pinnedMode, toCss, type ColorScheme, type ThemeSelection, } from './theme';

package/dist/types/tokens/src/presets.d.ts

@@ -0,0 +1,4 @@
+import type { AccentTokens, BaseTokens, Mode } from './contract';
+export declare const BASES: Record<string, Record<Mode, BaseTokens>>;
+export declare const ACCENTS: Record<string, AccentTokens>;
+export declare const FOCUS_RINGS: Record<string, Record<string, Record<Mode, string>>>;

package/dist/types/tokens/src/theme.d.ts

@@ -0,0 +1,30 @@
+import { type AccentTokens, type BaseTokens, type Mode, type Theme } from './contract';
+/**
+ * `system` follows the viewer's preference. Pinning a scheme is for an application that
+ * ships one look on purpose, and it is honoured all the way down: the palette stops
+ * varying, the root is stamped so the tokens cannot be swapped underneath it, and the
+ * browser is told which scheme to render its own scrollbars and form controls in.
+ */
+export type ColorScheme = 'system' | 'light' | 'dark';
+export type ThemeSelection = {
+    /** A base preset name, or the base's own token values. */
+    base: string | Record<Mode, BaseTokens>;
+    /** An accent preset name, or the accent's own token values. */
+    accent: string | AccentTokens;
+    /** Defaults to `system`. */
+    colorScheme?: ColorScheme;
+    /** Overrides applied last, so an Application can adjust a preset without forking it. */
+    overrides?: Partial<Theme>;
+};
+/** The mode a pinned scheme resolves to, or undefined when it follows the viewer. */
+export declare const pinnedMode: (selection: ThemeSelection) => Mode | undefined;
+/** Type and dimensions do not vary by mode, and no preset currently changes them. */
+export declare const DEFAULT_TYPE_AND_DIMENSIONS: Record<string, string>;
+/** The full token map for one mode. */
+export declare const composeTheme: (selection: ThemeSelection, mode: Mode) => Theme;
+/**
+ * Three states, not two: an explicit choice in either direction, and the system default
+ * when nothing is stamped on the root. A theme that only handled `prefers-color-scheme`
+ * would give a viewer no way to override it.
+ */
+export declare const toCss: (selection: ThemeSelection) => string;

package/dist/types/webpack-plugin/src/AppshellPlugin.d.ts

@@ -24,6 +24,29 @@ export default class AppshellPlugin {
     static findModuleFederationPlugin(webpackConfig: WebpackOptionsNormalized): ModuleFederationPluginInstance | undefined;
     static createTemplate(config: AppshellConfig, plugin: ModuleFederationPluginInstance): AppshellTemplate;
     static validate(template: AppshellTemplate): boolean;
+    /**
+     * Which tokens this package's output actually reaches for.
+     *
+     * Read from the emitted assets rather than declared. The CSS already states it, and a
+     * hand-kept list is a second copy that goes stale the first time somebody adds a token
+     * and forgets to update it. This cannot drift, because it *is* the usage.
+     *
+     * A role referenced both with and without a fallback counts as required: one place in
+     * the package has nothing to fall back to.
+     *
+     * The blind spot is a reference built at runtime from a constructed string, which no
+     * static scan sees — the same limit Tailwind has with dynamic class names. It fails
+     * toward under-reporting, never toward inventing a requirement.
+     *
+     * Takes file contents rather than webpack assets: by `afterEmit` the compilation has
+     * swapped its sources for `SizeOnlySource`, which knows a length and nothing else.
+     * The files are on disk by then, which is what the hook means.
+     */
+    static tokenUsage(sources?: Record<string, string>): {
+        required: string[];
+        optional: string[];
+        unknown: string[];
+    };
     /**
      * Whether a request is shared, and shared as a singleton. `shared` has four shapes —
      * an object, an array of names, an array of objects, or a mix — and a bare name shares

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appshell/webpack-plugin",
-  "version": "1.0.0-alpha.22",
+  "version": "1.0.0-alpha.24",
   "description": "Webpack plugin used to generate a global Appshell configuration for micro-frontends built with Module Federation",
   "main": "dist/main.js",
   "types": "dist/types/webpack-plugin/src/index.d.ts",
@@ -32,5 +32,8 @@
     "plugin"
   ],
   "license": "MIT",
-  "gitHead": "6f194cbc3e1c53146b827ca3eb38ece3ccd59797"
+  "gitHead": "41f2ce7eee90490c80273dfe4a5df46295730a0e",
+  "dependencies": {
+    "@appshell/tokens": "^1.0.0-alpha.24"
+  }
 }