@db-ux/core-postcss-plugin 0.0.0 → 4.5.4-postcss-a42fe67

package/CHANGELOG.md

@@ -0,0 +1 @@
+# @db-ux/core-postcss-plugin

package/README.md

@@ -0,0 +1,299 @@
+# @db-ux/core-postcss-plugin
+
+PostCSS plugins for the DB UX Design System.
+
+## Plugins
+
+| Plugin        | Description                                                                                                  |
+| ------------- | ------------------------------------------------------------------------------------------------------------ |
+| `dbUxFlatten` | Flatten CSS custom properties by resolving `var()`, `@property`, `calc()`, `color-mix()`, and `light-dark()` |
+
+## Install
+
+```shell
+npm install @db-ux/core-postcss-plugin --save-dev
+```
+
+## Imports
+
+```ts
+// Named import (recommended)
+import { dbUxFlatten } from "@db-ux/core-postcss-plugin";
+
+// Default import (backward compatible — exports dbUxFlatten)
+import dbUxFlatten from "@db-ux/core-postcss-plugin";
+```
+
+## CSS Setup
+
+Use `@layer` to ensure the theme overrides base component styles. The plugin detects `@import ... layer()` rules to assign the correct layer to each file:
+
+```css
+/* styles.css */
+@layer db-ux, db-theme;
+@import "@db-ux/db-theme/build/styles/rollup.css" layer(db-theme);
+@import "@db-ux/core-components/build/styles/rollup.css" layer(db-ux);
+```
+
+## Framework Integration
+
+### Vite (React, Vue, Svelte, etc.)
+
+Configure the plugin directly in `vite.config.ts`:
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { dbUxFlatten } from "@db-ux/core-postcss-plugin";
+
+export default defineConfig({
+	css: {
+		transformer: "postcss", // required for Vite 8+ (default: 'lightningcss')
+		postcss: {
+			plugins: [dbUxFlatten()]
+		}
+	}
+});
+```
+
+> **Note**: Vite 8+ uses `lightningcss` as the default CSS transformer, which does not run PostCSS plugins. Set `css.transformer: 'postcss'` to enable PostCSS processing. Vite 7 and earlier use PostCSS by default and do not need this option.
+
+Works in both dev and build mode.
+
+### Angular
+
+Create a `postcss.config.json` in your project root:
+
+```json
+{
+	"plugins": {
+		"@db-ux/core-postcss-plugin": {}
+	}
+}
+```
+
+Angular CLI (`@angular/build:application`) only supports JSON-based PostCSS configs and loads plugins by name via `require()`. Works in both `ng build` and `ng serve`.
+
+### Next.js
+
+Create a `postcss.config.mjs` in your project root:
+
+```js
+// postcss.config.mjs
+import { dbUxFlatten } from "@db-ux/core-postcss-plugin";
+
+export default {
+	plugins: [dbUxFlatten()]
+};
+```
+
+Works with both webpack and turbopack.
+
+> **Note**: For CommonJS (`postcss.config.js`):
+>
+> ```js
+> const { dbUxFlatten } = require("@db-ux/core-postcss-plugin");
+> module.exports = { plugins: [dbUxFlatten()] };
+> ```
+
+### Webpack (standalone)
+
+```js
+// webpack.config.js
+const { dbUxFlatten } = require("@db-ux/core-postcss-plugin");
+
+module.exports = {
+	module: {
+		rules: [
+			{
+				test: /\.css$/,
+				use: [
+					"style-loader",
+					"css-loader",
+					{
+						loader: "postcss-loader",
+						options: {
+							postcssOptions: {
+								plugins: [dbUxFlatten()]
+							}
+						}
+					}
+				]
+			}
+		]
+	}
+};
+```
+
+---
+
+## `dbUxFlatten`
+
+Flattens DB UX Design System CSS custom properties by resolving `var()`, `@property`, `calc()`, `color-mix()`, and `light-dark()`.
+
+### What it does
+
+1. **Collects** all `@property` declarations and their `initial-value` as a resolution cache
+2. **Detects `@layer` priority** from `@layer` order declarations and `@import ... layer()` rules — theme values override base values regardless of processing order
+3. **Detects dynamic variables** that must stay as `var()` references:
+    - Variables re-declared in non-`:root`/`:host` selectors (e.g. `[data-density=functional]`)
+    - Variables re-declared inside `@media` queries
+    - Variables matching `dynamicPrefixes` (default: `--db-adaptive-*`)
+4. **Resolves** all static `var()` references recursively — including nested `var()` with fallbacks like `var(--a, var(--b))`
+5. **Evaluates** `calc()` expressions when all values are static
+6. **Evaluates** `color-mix(in srgb, ...)` when all colors are resolved
+7. **Collapses** `light-dark(x, y)` to `x` when both arguments are identical after resolution
+8. **Removes** `@property` rules and unused intermediate declarations
+
+### Options
+
+| Option             | Type       | Default              | Description                                                             |
+| ------------------ | ---------- | -------------------- | ----------------------------------------------------------------------- |
+| `removeAtProperty` | `boolean`  | `true`               | Remove `@property` rules after resolving                                |
+| `removeResolved`   | `boolean`  | `true`               | Remove declarations from `@property` that are no longer referenced      |
+| `dynamicPrefixes`  | `string[]` | `['--db-adaptive-']` | Variable prefixes that are always treated as dynamic and never resolved |
+
+```ts
+dbUxFlatten({
+	removeAtProperty: true,
+	removeResolved: true,
+	dynamicPrefixes: ["--db-adaptive-", "--my-custom-dynamic-"]
+});
+```
+
+### How it works
+
+#### Static vs. dynamic variables
+
+- **Static**: Only declared in `:root`/`:host` and `@property` — safe to inline everywhere
+- **Dynamic**: Re-declared in class selectors, data attributes, `@media` queries, or matching `dynamicPrefixes` — must stay as `var()` references
+
+```css
+/* Static — will be resolved */
+@property --db-neutral-0 {
+	syntax: "<color>";
+	initial-value: #0d0e10;
+	inherits: true;
+}
+
+/* Dynamic — stays as var() */
+:root {
+	--db-spacing-fixed-sm: 0.75rem;
+}
+[data-density="functional"] {
+	--db-spacing-fixed-sm: 0.5rem; /* re-declared → dynamic */
+}
+```
+
+#### `@layer` and `@import layer()` support
+
+The plugin detects layer priority from two sources:
+
+1. **`@layer` order declarations**: `@layer db-ux, db-theme;` — later in the list = higher priority
+2. **`@import ... layer()` rules**: `@import "file.css" layer(db-theme);` — maps each imported file to its layer
+
+This works even when the bundler processes each imported file independently (e.g. Angular), because the plugin sees the `@import` rules in the entry CSS file first and builds a file-to-layer mapping before the imported files are processed.
+
+```css
+@layer db-ux, db-theme;
+@import "@db-ux/db-theme/build/styles/rollup.css" layer(db-theme);
+@import "@db-ux/core-components/build/styles/rollup.css" layer(db-ux);
+```
+
+Unlayered CSS always wins over all layers, matching the CSS spec.
+
+#### Nested `var()` with fallbacks
+
+```css
+/* Input */
+font-family: var(--db-icon-font-family, var(--db-icon-default-font-family));
+
+/* Output (--db-icon-font-family unknown, --db-icon-default-font-family resolved) */
+font-family: var(--db-icon-font-family, "db-default", icon-font-fallback);
+```
+
+#### `light-dark()` collapsing
+
+When both arguments resolve to the same value, the function is collapsed:
+
+```css
+/* Input */
+--db-color: light-dark(
+	var(--db-neutral-origin-light-default),
+	var(--db-neutral-origin-dark-default)
+);
+
+/* Output (both resolve to #232529) */
+--db-color: #232529;
+
+/* Output (different values — kept) */
+--db-color: light-dark(#232529, #f0f0f0);
+```
+
+### Example
+
+**Input:**
+
+```css
+@layer db-ux, db-theme;
+
+@layer db-theme {
+	@property --db-brand-origin-light-default {
+		syntax: "<color>";
+		initial-value: #ec0016;
+		inherits: true;
+	}
+	@property --db-brand-origin-dark-default {
+		syntax: "<color>";
+		initial-value: #ec0016;
+		inherits: true;
+	}
+}
+
+@layer db-ux {
+	:root {
+		--db-brand-origin-default: light-dark(
+			var(--db-brand-origin-light-default),
+			var(--db-brand-origin-dark-default)
+		);
+	}
+	.button {
+		color: var(--db-adaptive-on-bg-basic-emphasis-100-default);
+		border-radius: var(--db-border-radius-xs);
+	}
+}
+```
+
+**Output:**
+
+```css
+:root {
+	--db-brand-origin-default: #ec0016;
+}
+.button {
+	color: var(--db-adaptive-on-bg-basic-emphasis-100-default);
+	border-radius: 0.25rem;
+}
+```
+
+- `--db-brand-origin-default`: both light/dark resolved to `#ec0016` (theme value) → `light-dark()` collapsed
+- `--db-adaptive-*`: kept as `var()` (dynamic prefix)
+- `--db-border-radius-xs`: resolved from `@property` (static)
+
+---
+
+## Package Structure
+
+```text
+src/
+├── index.ts                              # barrel export
+└── plugins/
+    └── flatten/
+        ├── index.ts                      # dbUxFlatten plugin
+        ├── data.ts                       # types & constants
+        └── helpers/
+            ├── css-parser.ts             # generic CSS string parsing
+            ├── resolve.ts                # var(), calc(), color-mix() resolution
+            ├── collect.ts                # PostCSS AST collection (layers, vars, imports)
+            └── transform.ts             # transformRoot + collapseLightDark
+```

package/build/index.d.ts

@@ -0,0 +1,3 @@
+export { dbUxFlatten } from './plugins/flatten/index.js';
+export type { FlattenOptions } from './plugins/flatten/index.js';
+export { dbUxFlatten as default } from './plugins/flatten/index.js';

package/build/index.js

@@ -0,0 +1,4 @@
+export { dbUxFlatten } from './plugins/flatten/index.js';
+// Default export for backward compatibility:
+// import dbUxFlatten from '@db-ux/postcss-plugin';
+export { dbUxFlatten as default } from './plugins/flatten/index.js';

package/build/plugins/flatten/data.d.ts

@@ -0,0 +1,17 @@
+export type FlattenOptions = {
+    /** Remove @property rules after resolving (default: true) */
+    removeAtProperty?: boolean;
+    /** Remove declarations whose variables came from @property and are no longer referenced (default: true) */
+    removeResolved?: boolean;
+    /**
+     * Variable prefixes that are always treated as dynamic (never resolved).
+     * Default: ['--db-adaptive-']
+     */
+    dynamicPrefixes?: string[];
+};
+export type VarEntry = {
+    value: string;
+    layer: string | null;
+    file: string;
+};
+export declare const DEFAULT_DYNAMIC_PREFIXES: string[];

package/build/plugins/flatten/data.js

@@ -0,0 +1 @@
+export const DEFAULT_DYNAMIC_PREFIXES = ['--db-adaptive-'];

package/build/plugins/flatten/helpers/collect.d.ts

@@ -0,0 +1,71 @@
+import type { ChildNode, Root } from 'postcss';
+import type { VarEntry } from '../data.js';
+/**
+ * Check whether a CSS selector targets only `:root` and/or `:host`.
+ * @param selector - The CSS selector string to check
+ * @returns True if the selector only contains `:root` and/or `:host`
+ */
+export declare const isRootSelector: (selector: string) => boolean;
+/**
+ * Walk up the PostCSS AST from a node to find the enclosing `@layer` name.
+ * @param node - The PostCSS child node to start from
+ * @returns The layer name, or null if not inside any `@layer`
+ */
+export declare const getLayerName: (node: ChildNode) => string | null;
+/**
+ * Parse `@layer` order declarations (e.g. `@layer db-ux, db-theme;`) from a root.
+ * Later names in the list get higher priority indices.
+ * @param root - The PostCSS root to scan
+ * @returns A map of layer name to priority index
+ */
+export declare const collectLayerOrder: (root: Root) => Map<string, number>;
+/**
+ * Parse `@import` rules to extract file-specifier to layer name mappings.
+ * @param root - The PostCSS root to scan
+ * @returns A map of import specifier to layer name
+ */
+export declare const collectImportLayers: (root: Root) => Map<string, string>;
+/**
+ * Get the numeric priority for a layer. Unlayered CSS (null) gets the highest
+ * priority (`MAX_SAFE_INTEGER`), matching the CSS spec.
+ * @param layer - The layer name, or null for unlayered CSS
+ * @param layerOrder - The layer priority map
+ * @returns The numeric priority (higher = wins)
+ */
+export declare const getLayerPriority: (layer: string | null, layerOrder: Map<string, number>) => number;
+/**
+ * Pick the best (highest-priority) value from multiple `VarEntry` entries
+ * for the same variable, based on `@layer` priority.
+ * @param entries - All collected entries for a single variable
+ * @param layerOrder - The layer priority map
+ * @returns The value string from the highest-priority entry
+ */
+export declare const pickBestVar: (entries: VarEntry[], layerOrder: Map<string, number>) => string;
+/**
+ * Look up the `@layer` name for a file by matching its path against
+ * known `@import ... layer()` specifiers.
+ * @param filePath - The absolute file path to look up
+ * @param importLayerMap - Map of import specifiers to layer names
+ * @returns The layer name, or null if not associated with any layer
+ */
+export declare const getFileLayer: (filePath: string, importLayerMap: Map<string, string>) => string | null;
+/**
+ * Collect all CSS custom property declarations and `@property` initial-values
+ * from a PostCSS root, assigning each a layer and detecting dynamic variables.
+ *
+ * A variable is marked as dynamic if:
+ * - Its name matches one of the `prefixes`
+ * - It is declared inside a non-`:root`/`:host` selector
+ * - It is declared inside `@media` within `:root`/`:host`
+ *
+ * Duplicate entries (same prop + file + layer) are skipped.
+ *
+ * @param root - The PostCSS root to scan
+ * @param varMap - Shared map to accumulate variable entries into
+ * @param propertyNames - Shared set to track `@property` variable names
+ * @param dynamicVars - Shared set to track dynamic variable names
+ * @param prefixes - Variable prefixes that are always treated as dynamic
+ * @param forceLayer - If set, overrides the detected layer for all entries
+ * @param file - The source file path for deduplication
+ */
+export declare const collectVarsWithLayer: (root: Root, varMap: Map<string, VarEntry[]>, propertyNames: Set<string>, dynamicVars: Set<string>, prefixes: string[], forceLayer: string | null, file: string) => void;

package/build/plugins/flatten/helpers/collect.js

@@ -0,0 +1,175 @@
+/**
+ * Check whether a CSS selector targets only `:root` and/or `:host`.
+ * @param selector - The CSS selector string to check
+ * @returns True if the selector only contains `:root` and/or `:host`
+ */
+export const isRootSelector = (selector) => {
+    const trimmed = selector.trim();
+    return /^(:root|:host)(\s*,\s*(:root|:host))*$/.test(trimmed);
+};
+/**
+ * Walk up the PostCSS AST from a node to find the enclosing `@layer` name.
+ * @param node - The PostCSS child node to start from
+ * @returns The layer name, or null if not inside any `@layer`
+ */
+export const getLayerName = (node) => {
+    let current = node.parent;
+    while (current) {
+        if (current.type === 'atrule' &&
+            current.name === 'layer' &&
+            current.params) {
+            return current.params.trim();
+        }
+        current = current.parent;
+    }
+    return null;
+};
+/**
+ * Parse `@layer` order declarations (e.g. `@layer db-ux, db-theme;`) from a root.
+ * Later names in the list get higher priority indices.
+ * @param root - The PostCSS root to scan
+ * @returns A map of layer name to priority index
+ */
+export const collectLayerOrder = (root) => {
+    const order = new Map();
+    root.walkAtRules('layer', (atRule) => {
+        if (atRule.nodes && atRule.nodes.length > 0)
+            return;
+        const names = atRule.params
+            .split(',')
+            .map((n) => n.trim())
+            .filter(Boolean);
+        for (let i = 0; i < names.length; i++) {
+            order.set(names[i], i);
+        }
+    });
+    return order;
+};
+/**
+ * Parse `@import` rules to extract file-specifier to layer name mappings.
+ * @param root - The PostCSS root to scan
+ * @returns A map of import specifier to layer name
+ */
+export const collectImportLayers = (root) => {
+    const importLayers = new Map();
+    root.walkAtRules('import', (atRule) => {
+        const params = atRule.params;
+        const layerMatch = params.match(/layer\(([^)]+)\)/);
+        if (!layerMatch)
+            return;
+        const layerName = layerMatch[1].trim();
+        const fileMatch = params.match(/(?:url\(\s*)?["']([^"']+)["'](?:\s*\))?/);
+        if (!fileMatch)
+            return;
+        importLayers.set(fileMatch[1], layerName);
+    });
+    return importLayers;
+};
+/**
+ * Get the numeric priority for a layer. Unlayered CSS (null) gets the highest
+ * priority (`MAX_SAFE_INTEGER`), matching the CSS spec.
+ * @param layer - The layer name, or null for unlayered CSS
+ * @param layerOrder - The layer priority map
+ * @returns The numeric priority (higher = wins)
+ */
+export const getLayerPriority = (layer, layerOrder) => {
+    if (layer === null)
+        return Number.MAX_SAFE_INTEGER;
+    return layerOrder.get(layer) ?? -1;
+};
+/**
+ * Pick the best (highest-priority) value from multiple `VarEntry` entries
+ * for the same variable, based on `@layer` priority.
+ * @param entries - All collected entries for a single variable
+ * @param layerOrder - The layer priority map
+ * @returns The value string from the highest-priority entry
+ */
+export const pickBestVar = (entries, layerOrder) => {
+    let best = entries[0];
+    for (let i = 1; i < entries.length; i++) {
+        if (getLayerPriority(entries[i].layer, layerOrder) >=
+            getLayerPriority(best.layer, layerOrder)) {
+            best = entries[i];
+        }
+    }
+    return best.value;
+};
+/**
+ * Look up the `@layer` name for a file by matching its path against
+ * known `@import ... layer()` specifiers.
+ * @param filePath - The absolute file path to look up
+ * @param importLayerMap - Map of import specifiers to layer names
+ * @returns The layer name, or null if not associated with any layer
+ */
+export const getFileLayer = (filePath, importLayerMap) => {
+    for (const [specifier, layer] of importLayerMap) {
+        if (filePath.replace(/\\/g, '/').endsWith(specifier.replace(/\\/g, '/'))) {
+            return layer;
+        }
+    }
+    return null;
+};
+/**
+ * Collect all CSS custom property declarations and `@property` initial-values
+ * from a PostCSS root, assigning each a layer and detecting dynamic variables.
+ *
+ * A variable is marked as dynamic if:
+ * - Its name matches one of the `prefixes`
+ * - It is declared inside a non-`:root`/`:host` selector
+ * - It is declared inside `@media` within `:root`/`:host`
+ *
+ * Duplicate entries (same prop + file + layer) are skipped.
+ *
+ * @param root - The PostCSS root to scan
+ * @param varMap - Shared map to accumulate variable entries into
+ * @param propertyNames - Shared set to track `@property` variable names
+ * @param dynamicVars - Shared set to track dynamic variable names
+ * @param prefixes - Variable prefixes that are always treated as dynamic
+ * @param forceLayer - If set, overrides the detected layer for all entries
+ * @param file - The source file path for deduplication
+ */
+export const collectVarsWithLayer = (root, varMap, propertyNames, dynamicVars, prefixes, forceLayer, file) => {
+    const addVar = (prop, value, layer) => {
+        const entries = varMap.get(prop);
+        if (entries) {
+            if (entries.some((e) => e.file === file && e.layer === layer))
+                return;
+            entries.push({ value, layer, file });
+        }
+        else {
+            varMap.set(prop, [{ value, layer, file }]);
+        }
+    };
+    root.walkAtRules('property', (atRule) => {
+        const propName = atRule.params.trim();
+        propertyNames.add(propName);
+        const layer = forceLayer ?? getLayerName(atRule);
+        atRule.walkDecls('initial-value', (decl) => {
+            addVar(propName, decl.value, layer);
+        });
+    });
+    root.walkDecls(/^--/, (decl) => {
+        const parent = decl.parent;
+        if (prefixes.some((p) => decl.prop.startsWith(p))) {
+            dynamicVars.add(decl.prop);
+        }
+        if (parent && parent.type === 'rule') {
+            const rule = parent;
+            if (!isRootSelector(rule.selector)) {
+                dynamicVars.add(decl.prop);
+            }
+        }
+        if (parent && parent.type === 'rule') {
+            const rule = parent;
+            if (isRootSelector(rule.selector) &&
+                rule.parent &&
+                rule.parent.type === 'atrule') {
+                const atRule = rule.parent;
+                if (atRule.name === 'media') {
+                    dynamicVars.add(decl.prop);
+                }
+            }
+        }
+        addVar(decl.prop, decl.value, forceLayer ?? getLayerName(decl));
+    });
+};

package/build/plugins/flatten/helpers/css-parser.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Find the matching closing paren for a CSS function call starting at a given position.
+ * Assumes the opening `(` has already been consumed (depth starts at 1).
+ * @param value - The full CSS value string
+ * @param openIndex - The index right after the opening `(`
+ * @returns The index right after the matching `)`, or -1 if unbalanced
+ */
+export declare const findMatchingParenthesis: (value: string, openIndex: number) => number;
+/**
+ * Find the index of the first top-level comma in a string,
+ * skipping commas inside nested parentheses.
+ * @param value - The string to search
+ * @returns The index of the first top-level comma, or -1 if none found
+ */
+export declare const findTopLevelComma: (value: string) => number;
+/**
+ * Find the next occurrence of a CSS function by name and extract its span and inner content.
+ * Uses paren counting to handle nested parentheses.
+ * @param value - The CSS value string to search
+ * @param funcName - The function name (e.g. "var", "calc", "light-dark")
+ * @param fromIndex - The index to start searching from
+ * @returns An object with `start`, `end`, and `inner` content, or null if not found
+ */
+export declare const findCssFunction: (value: string, funcName: string, fromIndex?: number) => {
+    start: number;
+    end: number;
+    inner: string;
+} | null;

package/build/plugins/flatten/helpers/css-parser.js

@@ -0,0 +1,59 @@
+/**
+ * Find the matching closing paren for a CSS function call starting at a given position.
+ * Assumes the opening `(` has already been consumed (depth starts at 1).
+ * @param value - The full CSS value string
+ * @param openIndex - The index right after the opening `(`
+ * @returns The index right after the matching `)`, or -1 if unbalanced
+ */
+export const findMatchingParenthesis = (value, openIndex) => {
+    let depth = 1;
+    let i = openIndex;
+    while (i < value.length && depth > 0) {
+        if (value[i] === '(')
+            depth++;
+        if (value[i] === ')')
+            depth--;
+        i++;
+    }
+    return depth === 0 ? i : -1;
+};
+/**
+ * Find the index of the first top-level comma in a string,
+ * skipping commas inside nested parentheses.
+ * @param value - The string to search
+ * @returns The index of the first top-level comma, or -1 if none found
+ */
+export const findTopLevelComma = (value) => {
+    let depth = 0;
+    for (let i = 0; i < value.length; i++) {
+        if (value[i] === '(')
+            depth++;
+        else if (value[i] === ')')
+            depth--;
+        else if (value[i] === ',' && depth === 0)
+            return i;
+    }
+    return -1;
+};
+/**
+ * Find the next occurrence of a CSS function by name and extract its span and inner content.
+ * Uses paren counting to handle nested parentheses.
+ * @param value - The CSS value string to search
+ * @param funcName - The function name (e.g. "var", "calc", "light-dark")
+ * @param fromIndex - The index to start searching from
+ * @returns An object with `start`, `end`, and `inner` content, or null if not found
+ */
+export const findCssFunction = (value, funcName, fromIndex = 0) => {
+    const prefix = `${funcName}(`;
+    const idx = value.indexOf(prefix, fromIndex);
+    if (idx === -1)
+        return null;
+    const end = findMatchingParenthesis(value, idx + prefix.length);
+    if (end === -1)
+        return null;
+    return {
+        start: idx,
+        end,
+        inner: value.slice(idx + prefix.length, end - 1)
+    };
+};

package/build/plugins/flatten/helpers/resolve.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Recursively resolve `var()` references in a CSS value string.
+ * Uses a `seen` set per resolution chain to prevent circular references.
+ * If a var is known, it replaces the entire `var(...)` with the resolved value.
+ * If unknown but has a fallback, it resolves vars inside the fallback.
+ * @param value - The CSS value string containing `var()` references
+ * @param varMap - Map of variable names to their resolved values
+ * @param seen - Set of variable names already visited in the current chain
+ * @returns The value with all resolvable `var()` references inlined
+ */
+export declare const resolveVars: (value: string, varMap: Map<string, string>, seen?: Set<string>) => string;
+/**
+ * Collect all CSS variable names referenced in a value, including
+ * names inside nested `var()` fallbacks.
+ * @param value - The CSS value string to scan
+ * @param refs - Set to add discovered variable names to
+ */
+export declare const collectVarReferences: (value: string, refs: Set<string>) => void;
+/**
+ * Resolve all fully-static `calc()` expressions in a CSS value.
+ * Skips expressions that still contain unresolved `var()` or nested CSS functions.
+ * @param value - The CSS value string potentially containing `calc()` expressions
+ * @returns The value with all evaluable `calc()` expressions replaced
+ */
+export declare const resolveCalc: (value: string) => string;
+/**
+ * Resolve all fully-static `color-mix()` expressions in a CSS value.
+ * Skips expressions that still contain unresolved `var()` references.
+ * @param value - The CSS value string potentially containing `color-mix()` expressions
+ * @returns The value with all evaluable `color-mix()` expressions replaced
+ */
+export declare const resolveColorMix: (value: string) => string;

package/build/plugins/flatten/helpers/resolve.js

@@ -0,0 +1,333 @@
+import { findCssFunction, findTopLevelComma } from './css-parser.js';
+// ── var() ───────────────────────────────────────────────────────────────
+/**
+ * Find the next `var(` occurrence and parse it into name and optional fallback.
+ * @param value - The CSS value string to search
+ * @param fromIndex - The index to start searching from
+ * @returns The parsed var reference, or null if not found
+ */
+const findNextVar = (value, fromIndex) => {
+    const found = findCssFunction(value, 'var', fromIndex);
+    if (!found)
+        return null;
+    const commaIdx = findTopLevelComma(found.inner);
+    if (commaIdx === -1) {
+        return {
+            start: found.start,
+            end: found.end,
+            name: found.inner.trim(),
+            fallback: null
+        };
+    }
+    return {
+        start: found.start,
+        end: found.end,
+        name: found.inner.slice(0, commaIdx).trim(),
+        fallback: found.inner.slice(commaIdx + 1).trim()
+    };
+};
+/**
+ * Recursively resolve `var()` references in a CSS value string.
+ * Uses a `seen` set per resolution chain to prevent circular references.
+ * If a var is known, it replaces the entire `var(...)` with the resolved value.
+ * If unknown but has a fallback, it resolves vars inside the fallback.
+ * @param value - The CSS value string containing `var()` references
+ * @param varMap - Map of variable names to their resolved values
+ * @param seen - Set of variable names already visited in the current chain
+ * @returns The value with all resolvable `var()` references inlined
+ */
+export const resolveVars = (value, varMap, seen = new Set()) => {
+    let result = value;
+    let searchFrom = 0;
+    while (searchFrom < result.length) {
+        const found = findNextVar(result, searchFrom);
+        if (!found)
+            break;
+        const { start, end, name, fallback } = found;
+        if (seen.has(name)) {
+            searchFrom = end;
+            continue;
+        }
+        const resolved = varMap.get(name);
+        if (resolved !== undefined) {
+            const childSeen = new Set(seen);
+            childSeen.add(name);
+            const resolvedValue = resolveVars(resolved, varMap, childSeen);
+            result = result.slice(0, start) + resolvedValue + result.slice(end);
+            searchFrom = start + resolvedValue.length;
+        }
+        else if (fallback !== null) {
+            const resolvedFallback = resolveVars(fallback, varMap, seen);
+            const replacement = `var(${name}, ${resolvedFallback})`;
+            result = result.slice(0, start) + replacement + result.slice(end);
+            searchFrom = start + replacement.length;
+        }
+        else {
+            searchFrom = end;
+        }
+    }
+    return result;
+};
+/**
+ * Collect all CSS variable names referenced in a value, including
+ * names inside nested `var()` fallbacks.
+ * @param value - The CSS value string to scan
+ * @param refs - Set to add discovered variable names to
+ */
+export const collectVarReferences = (value, refs) => {
+    let searchFrom = 0;
+    while (searchFrom < value.length) {
+        const found = findNextVar(value, searchFrom);
+        if (!found)
+            break;
+        refs.add(found.name);
+        if (found.fallback) {
+            collectVarReferences(found.fallback, refs);
+        }
+        searchFrom = found.end;
+    }
+};
+// ── Generic CSS function resolver ───────────────────────────────────────
+/**
+ * Find and evaluate all occurrences of a CSS function in a value string.
+ * Skips occurrences that still contain unresolved `var()` references.
+ * @param value - The CSS value string to process
+ * @param funcName - The CSS function name to match (e.g. "calc", "color-mix")
+ * @param evaluate - Callback that receives the inner content and returns the
+ *                   evaluated result, or null to skip
+ * @param skipNestedFunctions - If true, skip when inner content contains other CSS functions
+ * @returns The value with all evaluable occurrences replaced
+ */
+const resolveCssFunction = (value, funcName, evaluate, skipNestedFunctions = false) => {
+    let result = value;
+    let searchFrom = 0;
+    while (searchFrom < result.length) {
+        const found = findCssFunction(result, funcName, searchFrom);
+        if (!found)
+            break;
+        if (found.inner.includes('var(')) {
+            searchFrom = found.end;
+            continue;
+        }
+        if (skipNestedFunctions && /[a-z-]+\(/i.test(found.inner)) {
+            searchFrom = found.end;
+            continue;
+        }
+        const evaluated = evaluate(found.inner);
+        if (evaluated !== null) {
+            result =
+                result.slice(0, found.start) +
+                    evaluated +
+                    result.slice(found.end);
+            searchFrom = found.start + evaluated.length;
+        }
+        else {
+            searchFrom = found.end;
+        }
+    }
+    return result;
+};
+// ── calc() ──────────────────────────────────────────────────────────────
+/**
+ * Parse a CSS unit value like "0.75rem" into its numeric value and unit.
+ * @param str - The string to parse (e.g. "0.75rem", "100%", "2")
+ * @returns An object with `value` and `unit`, or null if not parseable
+ */
+const parseUnit = (str) => {
+    const match = str.trim().match(/^(-?[\d.]+)\s*(%|[a-z]*)$/i);
+    if (!match)
+        return null;
+    return { value: Number.parseFloat(match[1]), unit: match[2] || '' };
+};
+/**
+ * Evaluate a simple `calc()` expression with static values.
+ * Supports `+`, `-`, `*`, `/` with a single unit type (e.g. `calc(2 * 0.75rem)`).
+ * @param expr - The inner content of a `calc()` expression
+ * @returns The evaluated result as a string (e.g. "1.5rem"), or null if not evaluable
+ */
+const evaluateCalc = (expr) => {
+    const tokens = expr.trim().split(/\s+/).filter(Boolean);
+    if (tokens.length === 0)
+        return null;
+    let result = 0;
+    let resultUnit = '';
+    let operator = '+';
+    for (const token of tokens) {
+        if (['+', '-', '*', '/'].includes(token)) {
+            operator = token;
+            continue;
+        }
+        const parsed = parseUnit(token);
+        if (!parsed)
+            return null;
+        if (parsed.unit && !resultUnit) {
+            resultUnit = parsed.unit;
+        }
+        else if (parsed.unit && parsed.unit !== resultUnit && resultUnit) {
+            return null;
+        }
+        switch (operator) {
+            case '+':
+                result += parsed.value;
+                break;
+            case '-':
+                result -= parsed.value;
+                break;
+            case '*':
+                result *= parsed.value;
+                break;
+            case '/':
+                if (parsed.value === 0)
+                    return null;
+                result /= parsed.value;
+                break;
+        }
+    }
+    const rounded = Math.abs(result) < 1e-10 ? 0 : Math.round(result * 1e6) / 1e6;
+    return `${rounded}${resultUnit}`;
+};
+/**
+ * Resolve all fully-static `calc()` expressions in a CSS value.
+ * Skips expressions that still contain unresolved `var()` or nested CSS functions.
+ * @param value - The CSS value string potentially containing `calc()` expressions
+ * @returns The value with all evaluable `calc()` expressions replaced
+ */
+export const resolveCalc = (value) => resolveCssFunction(value, 'calc', evaluateCalc, true);
+// ── color-mix() ─────────────────────────────────────────────────────────
+/**
+ * Parse a hex color string to an RGBA tuple.
+ * Supports `#rgb`, `#rrggbb`, `#rgba`, and `#rrggbbaa`.
+ * @param hex - The hex color string
+ * @returns An [r, g, b, a] tuple (0-255 for rgb, 0-1 for alpha), or null if not parseable
+ */
+const parseHexColor = (hex) => {
+    const h = hex.replace('#', '');
+    let r, g, b;
+    let a = 1;
+    if (h.length === 3) {
+        r = Number.parseInt(h[0] + h[0], 16);
+        g = Number.parseInt(h[1] + h[1], 16);
+        b = Number.parseInt(h[2] + h[2], 16);
+    }
+    else if (h.length === 4) {
+        r = Number.parseInt(h[0] + h[0], 16);
+        g = Number.parseInt(h[1] + h[1], 16);
+        b = Number.parseInt(h[2] + h[2], 16);
+        a = Number.parseInt(h[3] + h[3], 16) / 255;
+    }
+    else if (h.length === 6) {
+        r = Number.parseInt(h.slice(0, 2), 16);
+        g = Number.parseInt(h.slice(2, 4), 16);
+        b = Number.parseInt(h.slice(4, 6), 16);
+    }
+    else if (h.length === 8) {
+        r = Number.parseInt(h.slice(0, 2), 16);
+        g = Number.parseInt(h.slice(2, 4), 16);
+        b = Number.parseInt(h.slice(4, 6), 16);
+        a = Number.parseInt(h.slice(6, 8), 16) / 255;
+    }
+    else {
+        return null;
+    }
+    if (Number.isNaN(r) ||
+        Number.isNaN(g) ||
+        Number.isNaN(b) ||
+        Number.isNaN(a))
+        return null;
+    return [r, g, b, a];
+};
+/**
+ * Convert a number (0-255) to a two-digit hex string.
+ * @param n - The number to convert
+ * @returns A zero-padded hex string (e.g. "0a", "ff")
+ */
+const toHex = (n) => Math.round(Math.max(0, Math.min(255, n)))
+    .toString(16)
+    .padStart(2, '0');
+/**
+ * Evaluate a `color-mix(in srgb, ...)` expression with two color arguments.
+ * Supports hex colors and `transparent`. Handles percentage-based mixing
+ * with premultiplied alpha blending.
+ * @param args - The inner arguments of `color-mix()`
+ * @returns The mixed color as a hex string, "transparent", or null if not evaluable
+ */
+const evaluateColorMix = (args) => {
+    const srgbMatch = args.match(/^in\s+srgb\s*,\s*([\s\S]+?)\s*,\s*([\s\S]+?)\s*$/);
+    if (!srgbMatch)
+        return null;
+    const parseColorArg = (arg) => {
+        const parts = arg.trim().split(/\s+/);
+        if (parts.length === 1)
+            return { color: parts[0], percentage: null };
+        if (parts.length === 2) {
+            const pctMatch = parts[1].match(/^([\d.]+)%$/);
+            if (!pctMatch)
+                return null;
+            return {
+                color: parts[0],
+                percentage: Number.parseFloat(pctMatch[1])
+            };
+        }
+        return null;
+    };
+    const arg1 = parseColorArg(srgbMatch[1]);
+    const arg2 = parseColorArg(srgbMatch[2]);
+    if (!arg1 || !arg2)
+        return null;
+    let p1 = arg1.percentage;
+    let p2 = arg2.percentage;
+    if (p1 === null && p2 === null) {
+        p1 = 50;
+        p2 = 50;
+    }
+    else if (p1 !== null && p2 === null) {
+        p2 = 100 - p1;
+    }
+    else if (p1 === null && p2 !== null) {
+        p1 = 100 - p2;
+    }
+    const pct1 = p1 / 100;
+    const pct2 = p2 / 100;
+    const isTransparent = (c) => c === 'transparent';
+    let rgb1, alpha1 = 1;
+    if (isTransparent(arg1.color)) {
+        rgb1 = [0, 0, 0];
+        alpha1 = 0;
+    }
+    else {
+        const parsed = parseHexColor(arg1.color);
+        if (!parsed)
+            return null;
+        rgb1 = [parsed[0], parsed[1], parsed[2]];
+        alpha1 = parsed[3];
+    }
+    let rgb2, alpha2 = 1;
+    if (isTransparent(arg2.color)) {
+        rgb2 = [0, 0, 0];
+        alpha2 = 0;
+    }
+    else {
+        const parsed = parseHexColor(arg2.color);
+        if (!parsed)
+            return null;
+        rgb2 = [parsed[0], parsed[1], parsed[2]];
+        alpha2 = parsed[3];
+    }
+    const mixedAlpha = alpha1 * pct1 + alpha2 * pct2;
+    if (mixedAlpha === 0)
+        return 'transparent';
+    const mix = (c1, c2) => (c1 * alpha1 * pct1 + c2 * alpha2 * pct2) / mixedAlpha;
+    const r = mix(rgb1[0], rgb2[0]);
+    const g = mix(rgb1[1], rgb2[1]);
+    const b = mix(rgb1[2], rgb2[2]);
+    if (mixedAlpha >= 0.995)
+        return `#${toHex(r)}${toHex(g)}${toHex(b)}`;
+    return `#${toHex(r)}${toHex(g)}${toHex(b)}${toHex(mixedAlpha * 255)}`;
+};
+/**
+ * Resolve all fully-static `color-mix()` expressions in a CSS value.
+ * Skips expressions that still contain unresolved `var()` references.
+ * @param value - The CSS value string potentially containing `color-mix()` expressions
+ * @returns The value with all evaluable `color-mix()` expressions replaced
+ */
+export const resolveColorMix = (value) => resolveCssFunction(value, 'color-mix', evaluateColorMix);

package/build/plugins/flatten/helpers/transform.d.ts

@@ -0,0 +1,22 @@
+import type { Root } from 'postcss';
+/**
+ * Collapse `light-dark(x, y)` to just `x` when both arguments are identical
+ * after trimming whitespace. Handles nested parentheses correctly.
+ * @param value - The CSS value string potentially containing `light-dark()` calls
+ * @returns The value with identical-argument `light-dark()` calls collapsed
+ */
+export declare const collapseLightDark: (value: string) => string;
+/**
+ * Transform all declarations in a PostCSS root by resolving static `var()`,
+ * evaluating `calc()` and `color-mix()`, collapsing identical `light-dark()`,
+ * and optionally removing `@property` rules and unused declarations.
+ *
+ * @param root - The PostCSS root to transform
+ * @param staticVarMap - Map of static variable names to their resolved values
+ * @param referencedVars - Set to track which variables are still referenced after resolution
+ * @param propertyNames - Set of variable names that came from `@property`
+ * @param dynamicVars - Set of dynamic variable names (never removed)
+ * @param removeAtProperty - Whether to remove `@property` rules
+ * @param removeResolved - Whether to remove unused `@property`-sourced declarations
+ */
+export declare const transformRoot: (root: Root, staticVarMap: Map<string, string>, referencedVars: Set<string>, propertyNames: Set<string>, dynamicVars: Set<string>, removeAtProperty: boolean, removeResolved: boolean) => void;

package/build/plugins/flatten/helpers/transform.js

@@ -0,0 +1,85 @@
+import { findCssFunction, findTopLevelComma } from './css-parser.js';
+import { collectVarReferences, resolveCalc, resolveColorMix, resolveVars } from './resolve.js';
+/**
+ * Collapse `light-dark(x, y)` to just `x` when both arguments are identical
+ * after trimming whitespace. Handles nested parentheses correctly.
+ * @param value - The CSS value string potentially containing `light-dark()` calls
+ * @returns The value with identical-argument `light-dark()` calls collapsed
+ */
+export const collapseLightDark = (value) => {
+    let result = value;
+    let searchFrom = 0;
+    while (searchFrom < result.length) {
+        const found = findCssFunction(result, 'light-dark', searchFrom);
+        if (!found)
+            break;
+        const commaIdx = findTopLevelComma(found.inner);
+        if (commaIdx === -1) {
+            searchFrom = found.end;
+            continue;
+        }
+        const light = found.inner.slice(0, commaIdx).trim();
+        const dark = found.inner.slice(commaIdx + 1).trim();
+        if (light === dark) {
+            result =
+                result.slice(0, found.start) + light + result.slice(found.end);
+            searchFrom = found.start + light.length;
+        }
+        else {
+            searchFrom = found.end;
+        }
+    }
+    return result;
+};
+/**
+ * Transform all declarations in a PostCSS root by resolving static `var()`,
+ * evaluating `calc()` and `color-mix()`, collapsing identical `light-dark()`,
+ * and optionally removing `@property` rules and unused declarations.
+ *
+ * @param root - The PostCSS root to transform
+ * @param staticVarMap - Map of static variable names to their resolved values
+ * @param referencedVars - Set to track which variables are still referenced after resolution
+ * @param propertyNames - Set of variable names that came from `@property`
+ * @param dynamicVars - Set of dynamic variable names (never removed)
+ * @param removeAtProperty - Whether to remove `@property` rules
+ * @param removeResolved - Whether to remove unused `@property`-sourced declarations
+ */
+export const transformRoot = (root, staticVarMap, referencedVars, propertyNames, dynamicVars, removeAtProperty, removeResolved) => {
+    root.walkDecls((decl) => {
+        const hasVar = decl.value.includes('var(');
+        const hasCalc = decl.value.includes('calc(');
+        const hasColorMix = decl.value.includes('color-mix(');
+        const hasLightDark = decl.value.includes('light-dark(');
+        if (!hasVar && !hasCalc && !hasColorMix && !hasLightDark)
+            return;
+        let resolved = decl.value;
+        if (hasVar) {
+            resolved = resolveVars(resolved, staticVarMap);
+        }
+        if (resolved.includes('calc(')) {
+            resolved = resolveCalc(resolved);
+        }
+        if (resolved.includes('color-mix(')) {
+            resolved = resolveColorMix(resolved);
+        }
+        if (resolved.includes('light-dark(')) {
+            resolved = collapseLightDark(resolved);
+        }
+        collectVarReferences(resolved, referencedVars);
+        decl.value = resolved;
+    });
+    if (removeAtProperty) {
+        root.walkAtRules('property', (atRule) => {
+            atRule.remove();
+        });
+    }
+    if (removeResolved) {
+        root.walkDecls(/^--/, (decl) => {
+            if (propertyNames.has(decl.prop) &&
+                !referencedVars.has(decl.prop) &&
+                !dynamicVars.has(decl.prop)) {
+                decl.remove();
+            }
+        });
+    }
+};

package/build/plugins/flatten/index.d.ts

@@ -0,0 +1,16 @@
+import type { PluginCreator } from 'postcss';
+import type { FlattenOptions } from './data.js';
+/**
+ * PostCSS plugin that flattens DB UX Design System CSS custom properties
+ * by resolving `var()`, `@property`, `calc()`, `color-mix()`, and `light-dark()`.
+ *
+ * Detects dynamic variables (re-declared in non-`:root` selectors, `@media`,
+ * or matching `dynamicPrefixes`) and leaves them as `var()` references.
+ * Respects `@layer` priority via `@layer` order declarations and `@import ... layer()` rules.
+ *
+ * @param opts - Plugin options
+ * @returns A PostCSS plugin instance
+ */
+declare const dbUxFlatten: PluginCreator<FlattenOptions>;
+export { dbUxFlatten };
+export type { FlattenOptions };

package/build/plugins/flatten/index.js

@@ -0,0 +1,52 @@
+import { DEFAULT_DYNAMIC_PREFIXES } from './data.js';
+import { collectImportLayers, collectLayerOrder, collectVarsWithLayer, getFileLayer, pickBestVar } from './helpers/collect.js';
+import { transformRoot } from './helpers/transform.js';
+/**
+ * PostCSS plugin that flattens DB UX Design System CSS custom properties
+ * by resolving `var()`, `@property`, `calc()`, `color-mix()`, and `light-dark()`.
+ *
+ * Detects dynamic variables (re-declared in non-`:root` selectors, `@media`,
+ * or matching `dynamicPrefixes`) and leaves them as `var()` references.
+ * Respects `@layer` priority via `@layer` order declarations and `@import ... layer()` rules.
+ *
+ * @param opts - Plugin options
+ * @returns A PostCSS plugin instance
+ */
+const dbUxFlatten = (opts = {}) => {
+    const removeAtProperty = opts.removeAtProperty ?? true;
+    const removeResolved = opts.removeResolved ?? true;
+    const dynamicPrefixes = opts.dynamicPrefixes ?? DEFAULT_DYNAMIC_PREFIXES;
+    const varMap = new Map();
+    const propertyNames = new Set();
+    const dynamicVars = new Set();
+    const referencedVars = new Set();
+    const layerOrder = new Map();
+    const importLayerMap = new Map();
+    return {
+        postcssPlugin: 'postcss-flatten-db-variables',
+        Once(root) {
+            const filePath = root.source?.input?.file ?? '';
+            const fileLayerOrder = collectLayerOrder(root);
+            for (const [name, priority] of fileLayerOrder) {
+                layerOrder.set(name, priority);
+            }
+            const fileImportLayers = collectImportLayers(root);
+            for (const [specifier, layer] of fileImportLayers) {
+                importLayerMap.set(specifier, layer);
+            }
+            const fileLayer = getFileLayer(filePath, importLayerMap);
+            collectVarsWithLayer(root, varMap, propertyNames, dynamicVars, dynamicPrefixes, fileLayer, filePath);
+        },
+        OnceExit(root) {
+            const staticVarMap = new Map();
+            for (const [key, entries] of varMap) {
+                if (!dynamicVars.has(key)) {
+                    staticVarMap.set(key, pickBestVar(entries, layerOrder));
+                }
+            }
+            transformRoot(root, staticVarMap, referencedVars, propertyNames, dynamicVars, removeAtProperty, removeResolved);
+        }
+    };
+};
+dbUxFlatten.postcss = true;
+export { dbUxFlatten };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@db-ux/core-postcss-plugin",
-  "version": "0.0.0",
+  "version": "4.5.4-postcss-a42fe67",
   "type": "module",
   "description": "PostCSS plugins for DB UX Design System",
   "repository": {
@@ -8,6 +8,41 @@
     "url": "git+https://github.com/db-ux-design-system/core-web.git"
   },
   "license": "Apache-2.0",
+  "exports": {
+    ".": {
+      "types": "./build/index.d.ts",
+      "default": "./build/index.js"
+    }
+  },
+  "files": [
+    "CHANGELOG.md",
+    "build"
+  ],
+  "keywords": [
+    "postcss",
+    "postcss-plugin",
+    "db-ux",
+    "css-variables",
+    "light-dark"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "copy-output": "npm-run-all copy:*",
+    "copy:changelog": "cpr CHANGELOG.md ../../build-outputs/postcss-plugin/CHANGELOG.md --overwrite",
+    "copy:outputs": "cpr build ../../build-outputs/postcss-plugin/build -o",
+    "copy:package.json": "cpr package.json ../../build-outputs/postcss-plugin/package.json -o",
+    "copy:readme": "cpr README.md ../../build-outputs/postcss-plugin/README.md -o",
+    "test": "vitest run --config vitest.config.ts",
+    "test:update": "vitest run --config vitest.config.ts --update"
+  },
+  "peerDependencies": {
+    "postcss": "^8.0.0"
+  },
+  "devDependencies": {
+    "postcss": "8.5.8",
+    "typescript": "5.9.3",
+    "vitest": "3.2.4"
+  },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"