material 1.0.4 → 3.0.0-next.0

package/dist/core/shapes/polygon.js

@@ -0,0 +1,238 @@
+import { DISTANCE_EPSILON, circularArc, cubicBounds, direction, distance, dot, lerp, pointOnCurve, reverseCubic, splitCubic, rotate90, straightLine, transformCubic, zeroLength, } from "./cubic.js";
+export const UNROUNDED = { radius: 0, smoothing: 0 };
+const sub = (a, b) => [a[0] - b[0], a[1] - b[1]];
+const add = (a, b) => [a[0] + b[0], a[1] + b[1]];
+const mul = (a, k) => [a[0] * k, a[1] * k];
+const length = (a) => distance(a[0], a[1]);
+const unit = (a) => direction(a[0], a[1]);
+const mix = (a, b, t) => [lerp(a[0], b[0], t), lerp(a[1], b[1], t)];
+const lineIntersection = (p0, d0, p1, d1) => {
+    const rotatedD1 = rotate90(d1);
+    const den = dot(d0, rotatedD1);
+    if (Math.abs(den) < DISTANCE_EPSILON)
+        return null;
+    const num = dot(sub(p1, p0), rotatedD1);
+    if (Math.abs(den) < DISTANCE_EPSILON * Math.abs(num))
+        return null;
+    return add(p0, mul(d0, num / den));
+};
+const roundedCorner = (p0, p1, p2, rounding) => {
+    const v01 = sub(p0, p1);
+    const v21 = sub(p2, p1);
+    const d01 = length(v01);
+    const d21 = length(v21);
+    if (d01 > 0 && d21 > 0) {
+        const d1 = mul(v01, 1 / d01);
+        const d2 = mul(v21, 1 / d21);
+        const cornerRadius = rounding.radius;
+        const smoothing = rounding.smoothing ?? 0;
+        const cosAngle = dot(d1, d2);
+        const sinAngle = Math.sqrt(1 - cosAngle * cosAngle);
+        const expectedRoundCut = sinAngle > 1e-3 ? (cornerRadius * (cosAngle + 1)) / sinAngle : 0;
+        return {
+            p0, p1, p2, d1, d2, cornerRadius, smoothing, expectedRoundCut,
+            expectedCut: (1 + smoothing) * expectedRoundCut,
+        };
+    }
+    return { p0, p1, p2, d1: [0, 0], d2: [0, 0], cornerRadius: 0, smoothing: 0, expectedRoundCut: 0, expectedCut: 0 };
+};
+const actualSmoothing = (corner, allowedCut) => {
+    if (allowedCut > corner.expectedCut)
+        return corner.smoothing;
+    if (allowedCut > corner.expectedRoundCut) {
+        return (corner.smoothing * (allowedCut - corner.expectedRoundCut)) / (corner.expectedCut - corner.expectedRoundCut);
+    }
+    return 0;
+};
+const flankingCurve = (actualRoundCut, smoothing, corner, sideStart, circleSegmentIntersection, otherCircleSegmentIntersection, circleCenter, actualR) => {
+    const sideDirection = unit(sub(sideStart, corner));
+    const curveStart = add(corner, mul(sideDirection, actualRoundCut * (1 + smoothing)));
+    const p = mix(circleSegmentIntersection, mul(add(circleSegmentIntersection, otherCircleSegmentIntersection), 0.5), smoothing);
+    const curveEnd = add(circleCenter, mul(direction(p[0] - circleCenter[0], p[1] - circleCenter[1]), actualR));
+    const circleTangent = rotate90(sub(curveEnd, circleCenter));
+    const anchorEnd = lineIntersection(sideStart, sideDirection, curveEnd, circleTangent) ?? circleSegmentIntersection;
+    const anchorStart = mul(add(curveStart, mul(anchorEnd, 2)), 1 / 3);
+    return [curveStart[0], curveStart[1], anchorStart[0], anchorStart[1], anchorEnd[0], anchorEnd[1], curveEnd[0], curveEnd[1]];
+};
+const cornerCubics = (corner, allowedCut0, allowedCut1) => {
+    const allowedCut = Math.min(allowedCut0, allowedCut1);
+    const { p0, p1, p2, d1, d2, cornerRadius, expectedRoundCut } = corner;
+    if (expectedRoundCut < DISTANCE_EPSILON || allowedCut < DISTANCE_EPSILON || cornerRadius < DISTANCE_EPSILON) {
+        return [straightLine(p1[0], p1[1], p1[0], p1[1])];
+    }
+    const actualRoundCut = Math.min(allowedCut, expectedRoundCut);
+    const smoothing0 = actualSmoothing(corner, allowedCut0);
+    const smoothing1 = actualSmoothing(corner, allowedCut1);
+    const actualR = (cornerRadius * actualRoundCut) / expectedRoundCut;
+    const centerDistance = Math.sqrt(actualR * actualR + actualRoundCut * actualRoundCut);
+    const center = add(p1, mul(unit(mul(add(d1, d2), 0.5)), centerDistance));
+    const circleIntersection0 = add(p1, mul(d1, actualRoundCut));
+    const circleIntersection2 = add(p1, mul(d2, actualRoundCut));
+    const flanking0 = flankingCurve(actualRoundCut, smoothing0, p1, p0, circleIntersection0, circleIntersection2, center, actualR);
+    const flanking2 = reverseCubic(flankingCurve(actualRoundCut, smoothing1, p1, p2, circleIntersection2, circleIntersection0, center, actualR));
+    return [
+        flanking0,
+        circularArc(center[0], center[1], flanking0[6], flanking0[7], flanking2[0], flanking2[1]),
+        flanking2,
+    ];
+};
+export const roundedPolygon = (vertices, rounding = UNROUNDED, perVertexRounding, centerX, centerY) => {
+    if (vertices.length < 6)
+        throw new Error('Polygons must have at least 3 vertices');
+    if (vertices.length % 2 === 1)
+        throw new Error('The vertices array should have even size');
+    const n = vertices.length / 2;
+    if (perVertexRounding && perVertexRounding.length !== n) {
+        throw new Error('perVertexRounding should have one entry per vertex');
+    }
+    const vertex = (i) => [vertices[(i % n) * 2], vertices[(i % n) * 2 + 1]];
+    const corners = [];
+    for (let i = 0; i < n; i++) {
+        corners.push(roundedCorner(vertex(i + n - 1), vertex(i), vertex(i + 1), perVertexRounding?.[i] ?? rounding));
+    }
+    const cutAdjusts = [];
+    for (let i = 0; i < n; i++) {
+        const next = corners[(i + 1) % n];
+        const expectedRoundCut = corners[i].expectedRoundCut + next.expectedRoundCut;
+        const expectedCut = corners[i].expectedCut + next.expectedCut;
+        const a = vertex(i);
+        const b = vertex(i + 1);
+        const sideSize = distance(a[0] - b[0], a[1] - b[1]);
+        if (expectedRoundCut > sideSize) {
+            cutAdjusts.push([sideSize / expectedRoundCut, 0]);
+        }
+        else if (expectedCut > sideSize) {
+            cutAdjusts.push([1, (sideSize - expectedRoundCut) / (expectedCut - expectedRoundCut)]);
+        }
+        else {
+            cutAdjusts.push([1, 1]);
+        }
+    }
+    const cornerRuns = [];
+    for (let i = 0; i < n; i++) {
+        const corner = corners[i];
+        const allowed = [];
+        for (let delta = 0; delta <= 1; delta++) {
+            const [roundCutRatio, cutRatio] = cutAdjusts[(i + n - 1 + delta) % n];
+            allowed.push(corner.expectedRoundCut * roundCutRatio + (corner.expectedCut - corner.expectedRoundCut) * cutRatio);
+        }
+        cornerRuns.push(cornerCubics(corner, allowed[0], allowed[1]));
+    }
+    const features = [];
+    for (let i = 0; i < n; i++) {
+        const run = cornerRuns[i];
+        const last = run[run.length - 1];
+        const first = cornerRuns[(i + 1) % n][0];
+        features.push(run, [straightLine(last[6], last[7], first[0], first[1])]);
+    }
+    const first = features[0];
+    const split = first.length === 3 ? splitCubic(first[1], 0.5) : null;
+    const all = split ? [split[1], first[2], ...features.slice(1).flat(), first[0], split[0]] : features.flat();
+    const cubics = [];
+    for (const c of all) {
+        const last = cubics.length - 1;
+        if (!zeroLength(c))
+            cubics.push(c);
+        else if (last >= 0)
+            cubics[last] = [...cubics[last].slice(0, 6), c[6], c[7]];
+    }
+    let cx = centerX;
+    let cy = centerY;
+    if (cx === undefined || cy === undefined) {
+        let sx = 0;
+        let sy = 0;
+        for (let i = 0; i < n; i++) {
+            sx += vertices[i * 2];
+            sy += vertices[i * 2 + 1];
+        }
+        cx = sx / n;
+        cy = sy / n;
+    }
+    const last = cubics.length - 1;
+    if (last >= 0)
+        cubics[last] = [...cubics[last].slice(0, 6), cubics[0][0], cubics[0][1]];
+    else
+        cubics.push([cx, cy, cx, cy, cx, cy, cx, cy]);
+    return { cubics, centerX: cx, centerY: cy };
+};
+const radial = (radius, angle, cx, cy) => [cx + Math.cos(angle) * radius, cy + Math.sin(angle) * radius];
+export const regularPolygon = (numVertices, radius = 1, centerX = 0, centerY = 0, rounding = UNROUNDED, perVertexRounding) => {
+    const vertices = [];
+    for (let i = 0; i < numVertices; i++) {
+        vertices.push(...radial(radius, (Math.PI / numVertices) * 2 * i, centerX, centerY));
+    }
+    return roundedPolygon(vertices, rounding, perVertexRounding, centerX, centerY);
+};
+export const circle = (numVertices = 8, radius = 1, centerX = 0, centerY = 0) => {
+    if (numVertices < 3)
+        throw new Error('Circle must have at least three vertices');
+    const theta = Math.PI / numVertices;
+    return regularPolygon(numVertices, radius / Math.cos(theta), centerX, centerY, { radius });
+};
+export const star = (numVerticesPerRadius, radius = 1, innerRadius = 0.5, rounding = UNROUNDED, innerRounding, perVertexRounding, centerX = 0, centerY = 0) => {
+    if (radius <= 0 || innerRadius <= 0)
+        throw new Error('Star radii must both be greater than 0');
+    if (innerRadius >= radius)
+        throw new Error('innerRadius must be less than radius');
+    let pvRounding = perVertexRounding;
+    if (!pvRounding && innerRounding) {
+        pvRounding = [];
+        for (let i = 0; i < numVerticesPerRadius; i++)
+            pvRounding.push(rounding, innerRounding);
+    }
+    const vertices = [];
+    for (let i = 0; i < numVerticesPerRadius; i++) {
+        vertices.push(...radial(radius, (Math.PI / numVerticesPerRadius) * 2 * i, centerX, centerY));
+        vertices.push(...radial(innerRadius, (Math.PI / numVerticesPerRadius) * (2 * i + 1), centerX, centerY));
+    }
+    return roundedPolygon(vertices, rounding, pvRounding, centerX, centerY);
+};
+export const rectangle = (width = 2, height = 2, rounding = UNROUNDED, perVertexRounding, centerX = 0, centerY = 0) => {
+    const left = centerX - width / 2;
+    const top = centerY - height / 2;
+    const right = centerX + width / 2;
+    const bottom = centerY + height / 2;
+    return roundedPolygon([right, bottom, left, bottom, left, top, right, top], rounding, perVertexRounding, centerX, centerY);
+};
+export const transformPolygon = (polygon, f) => {
+    const center = f(polygon.centerX, polygon.centerY);
+    return { cubics: polygon.cubics.map((c) => transformCubic(c, f)), centerX: center[0], centerY: center[1] };
+};
+export const rotatePolygon = (polygon, degrees) => {
+    const a = (degrees * Math.PI) / 180;
+    const cos = Math.cos(a);
+    const sin = Math.sin(a);
+    return transformPolygon(polygon, (x, y) => [x * cos - y * sin, x * sin + y * cos]);
+};
+export const scalePolygon = (polygon, sx, sy = sx) => transformPolygon(polygon, (x, y) => [x * sx, y * sy]);
+export const polygonBounds = (polygon) => {
+    let minX = Infinity;
+    let minY = Infinity;
+    let maxX = -Infinity;
+    let maxY = -Infinity;
+    for (const c of polygon.cubics) {
+        const b = cubicBounds(c);
+        minX = Math.min(minX, b[0]);
+        minY = Math.min(minY, b[1]);
+        maxX = Math.max(maxX, b[2]);
+        maxY = Math.max(maxY, b[3]);
+    }
+    return [minX, minY, maxX, maxY];
+};
+export const polygonMaxRadius = (polygon) => {
+    let max = 0;
+    for (const c of polygon.cubics) {
+        const mid = pointOnCurve(c, 0.5);
+        max = Math.max(max, distance(c[0] - polygon.centerX, c[1] - polygon.centerY), distance(mid[0] - polygon.centerX, mid[1] - polygon.centerY));
+    }
+    return max;
+};
+export const normalizePolygon = (polygon) => {
+    const bounds = polygonBounds(polygon);
+    const width = bounds[2] - bounds[0];
+    const height = bounds[3] - bounds[1];
+    const side = Math.max(width, height);
+    const offsetX = (side - width) / 2 - bounds[0];
+    const offsetY = (side - height) / 2 - bounds[1];
+    return transformPolygon(polygon, (x, y) => [(x + offsetX) / side, (y + offsetY) / side]);
+};

package/dist/core/state/emitter.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @module core/state
+ */
+/**
+ * An event handler. A handler that declares its payload type is accepted as
+ * one, and a handler that doesn't gets `unknown` to narrow. It was
+ * `(...args: never[]) => void`, which inferred every such payload as `never`
+ * (FLO-295). The method-signature form keeps parameter bivariance, which is
+ * what lets a typed handler through.
+ */
+export type EventCallback = {
+    handler(...args: unknown[]): void;
+}["handler"];
+/**
+ * Interface for the event emitter
+ */
+export interface Emitter {
+    /**
+     * Subscribe to an event
+     * @param event - Event name
+     * @param callback - Event handler
+     * @returns Unsubscribe function
+     */
+    on(event: string, callback: EventCallback): () => void;
+    /**
+     * Unsubscribe from an event
+     * @param event - Event name
+     * @param callback - Event handler to remove
+     */
+    off(event: string, callback: EventCallback): void;
+    /**
+     * Emit an event
+     * @param event - Event name
+     * @param args - Event arguments
+     */
+    emit(event: string, ...args: unknown[]): void;
+    /**
+     * Clear all event listeners
+     */
+    clear(): void;
+}
+/**
+ * Creates an event emitter with subscription management
+ * @returns Event emitter interface
+ */
+export declare const createEmitter: () => Emitter;

package/dist/core/state/emitter.js

@@ -0,0 +1,31 @@
+export const createEmitter = () => {
+    const events = new Map();
+    return {
+        on: (event, callback) => {
+            const callbacks = events.get(event) || [];
+            events.set(event, [...callbacks, callback]);
+            return () => {
+                const callbacks = events.get(event) || [];
+                events.set(event, callbacks.filter(cb => cb !== callback));
+            };
+        },
+        off(event, callback) {
+            const callbacks = events.get(event) || [];
+            events.set(event, callbacks.filter(cb => cb !== callback));
+        },
+        emit: (event, ...args) => {
+            const callbacks = events.get(event) || [];
+            callbacks.forEach(cb => {
+                try {
+                    cb(...args);
+                }
+                catch (error) {
+                    console.error(`A listener for "${event}" threw:`, error);
+                }
+            });
+        },
+        clear: () => {
+            events.clear();
+        }
+    };
+};

package/dist/core/state/events.d.ts

@@ -0,0 +1,37 @@
+import type { EventCallback } from "./emitter.js";
+/**
+ * Event manager interface for handling component events
+ */
+export interface EventManagerState {
+    /**
+     * Adds an event listener
+     * @param event - Event name
+     * @param handler - Event handler
+     * @returns EventManagerState instance for chaining
+     */
+    on: (event: string, handler: EventCallback) => EventManagerState;
+    /**
+     * Removes an event listener
+     * @param event - Event name
+     * @param handler - Event handler
+     * @returns EventManagerState instance for chaining
+     */
+    off: (event: string, handler: EventCallback) => EventManagerState;
+    /**
+     * Removes all event listeners and cleans up
+     */
+    destroy: () => void;
+    /**
+     * Gets all active handlers
+     * @returns Map of event names to handlers
+     */
+    getHandlers: () => Map<EventCallback, string>;
+}
+/**
+ * Creates an event manager for a component
+ * Simple event handling mechanism for components
+ *
+ * @param element - Component's DOM element
+ * @returns Event manager interface
+ */
+export declare const createEventManager: (element: HTMLElement) => EventManagerState;

package/dist/core/state/events.js

@@ -0,0 +1,32 @@
+export const createEventManager = (element) => {
+    const handlers = new Map();
+    return {
+        on(event, handler) {
+            element.addEventListener(event, handler);
+            let callbacks = handlers.get(event);
+            if (!callbacks)
+                handlers.set(event, callbacks = new Set());
+            callbacks.add(handler);
+            return this;
+        },
+        off(event, handler) {
+            element.removeEventListener(event, handler);
+            const callbacks = handlers.get(event);
+            callbacks?.delete(handler);
+            if (!callbacks?.size)
+                handlers.delete(event);
+            return this;
+        },
+        destroy() {
+            handlers.forEach((callbacks, event) => {
+                callbacks.forEach(handler => element.removeEventListener(event, handler));
+            });
+            handlers.clear();
+        },
+        getHandlers() {
+            const snapshot = new Map();
+            handlers.forEach((callbacks, event) => callbacks.forEach(handler => snapshot.set(handler, event)));
+            return snapshot;
+        }
+    };
+};

package/dist/core/state/index.d.ts

@@ -0,0 +1,6 @@
+export { createEmitter } from "./emitter.js";
+export type { Emitter, EventCallback } from "./emitter.js";
+export { createStore, loggingMiddleware, deriveFiltered } from "./store.js";
+export type { Store, StoreOptions, Selector, Computation, Updater, DerivedState } from "./store.js";
+export { createEventManager } from "./events.js";
+export type { EventManagerState } from "./events.js";

package/dist/core/state/index.js

@@ -0,0 +1,3 @@
+export { createEmitter } from "./emitter.js";
+export { createStore, loggingMiddleware, deriveFiltered } from "./store.js";
+export { createEventManager } from "./events.js";

package/dist/core/state/store.d.ts

@@ -0,0 +1,90 @@
+/**
+ * State store options
+ */
+export interface StoreOptions<T> {
+    /**
+     * Middleware functions that process state changes
+     */
+    middleware?: Array<(newState: T, oldState: T) => T>;
+}
+/**
+ * State selector function type
+ */
+export type Selector<T, R> = (state: T) => R;
+/**
+ * State computation function type for derived state
+ */
+export type Computation<T, R> = (state: T) => R;
+/**
+ * State updater function type
+ */
+export type Updater<T> = (state: T) => T;
+/**
+ * What derive() returns: call it to remove the derived value, or read the
+ * value, typed, through get(). getState() carries derived values at runtime
+ * but its type is the base state, so this is the typed way to read one.
+ */
+export type DerivedState<R> = (() => void) & {
+    get: () => R;
+};
+/**
+ * State store interface
+ */
+export interface Store<T> {
+    /**
+     * Gets current state including derived values
+     * @returns Current state
+     */
+    getState: <D extends object = Record<never, never>>() => T & D;
+    /**
+     * Updates state
+     * @param update - State update object or updater function
+     */
+    setState: (update: Partial<T> | Updater<T>) => void;
+    /**
+     * Subscribes to state changes
+     * @param listener - Change listener
+     * @returns Unsubscribe function
+     */
+    subscribe: (listener: (state: T, oldState: T) => void) => () => void;
+    /**
+     * Creates a derived state value
+     * @param key - Derived state key
+     * @param computation - Function to compute derived value
+     * @returns Function to remove derived state
+     */
+    derive: <K extends string, R>(key: K, computation: Computation<T, R>) => DerivedState<R>;
+    /**
+     * Selects a specific slice of state
+     * @param selector - State selector function
+     * @returns Selected state
+     */
+    select: <R>(selector: Selector<T, R>) => R;
+    /**
+     * Resets state to initial values
+     */
+    reset: () => void;
+}
+/**
+ * Creates a state store with support for derived state and middleware
+ *
+ * @param initialState - Initial state object
+ * @param options - Store options
+ * @returns State store interface
+ */
+export declare const createStore: <T extends object>(initialState?: T, options?: StoreOptions<T>) => Store<T>;
+/**
+ * Example middleware that logs state changes
+ *
+ * @param newState - New state after change
+ * @param oldState - Previous state before change
+ * @returns Processed state (unchanged in this middleware)
+ */
+export declare const loggingMiddleware: <T extends object>(newState: T, oldState: T) => T;
+/**
+ * Creates a derived state selector for filtering objects
+ *
+ * @param predicate - Filter predicate function
+ * @returns Computation function for derived state
+ */
+export declare const deriveFiltered: <T>(predicate: (value: T, key: string) => boolean) => (state: Record<string, T>) => Record<string, T>;

package/dist/core/state/store.js

@@ -0,0 +1,62 @@
+import { createEmitter } from "./emitter.js";
+export const createStore = (initialState = {}, options = {}) => {
+    let state = { ...initialState };
+    const emitter = createEmitter();
+    const derivedStates = new Map();
+    const middleware = options.middleware || [];
+    const notifyListeners = (newState, oldState) => {
+        emitter.emit('change', newState, oldState);
+    };
+    const applyMiddleware = (newState, oldState) => {
+        return middleware.reduce((state, fn) => fn(state, oldState), newState);
+    };
+    return {
+        getState: () => {
+            const derivedValues = {};
+            derivedStates.forEach((compute, key) => {
+                derivedValues[key] = compute(state);
+            });
+            return { ...state, ...derivedValues };
+        },
+        setState: (update) => {
+            const oldState = { ...state };
+            const newState = typeof update === 'function'
+                ? update(state)
+                : { ...state, ...update };
+            state = applyMiddleware(newState, oldState);
+            notifyListeners(state, oldState);
+        },
+        subscribe: (listener) => emitter.on('change', listener),
+        derive: (key, computation) => {
+            derivedStates.set(key, computation);
+            const remove = () => {
+                derivedStates.delete(key);
+            };
+            return Object.assign(remove, { get: () => computation(state) });
+        },
+        select: (selector) => selector(state),
+        reset: () => {
+            state = { ...initialState };
+            notifyListeners(state, {});
+        }
+    };
+};
+export const loggingMiddleware = (newState, oldState) => {
+    console.log('State change:', {
+        old: oldState,
+        new: newState,
+        diff: Object.keys(newState).reduce((acc, key) => {
+            if (newState[key] !== oldState[key]) {
+                acc[key] = { from: oldState[key], to: newState[key] };
+            }
+            return acc;
+        }, {})
+    });
+    return newState;
+};
+export const deriveFiltered = (predicate) => (state) => Object.keys(state).reduce((acc, key) => {
+    if (predicate(state[key], key)) {
+        acc[key] = state[key];
+    }
+    return acc;
+}, {});

package/dist/core/theme/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @module core/theme
+ */
+export { schemeToTokens, THEME_ROLES } from "./tokens.js";
+export { cornerToken } from "./shape.js";
+export type { ShapeStep } from "./shape.js";
+export type { ThemeRole, SchemeRoles, SchemeToTokensOptions, ThemeTokens } from "./tokens.js";

package/dist/core/theme/index.js

@@ -0,0 +1,2 @@
+export { schemeToTokens, THEME_ROLES } from "./tokens.js";
+export { cornerToken } from "./shape.js";

package/dist/core/theme/shape.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The shape scale's corner tokens, for a radius a component writes from
+ * script (FLO-331): as the stylesheets read it, the token with the compiled
+ * value as its fallback, so a theme's corners reach inline styles too.
+ */
+/** A step of M3's shape scale, as `$shape` in src/styles/abstract/_variables.scss names it. */
+export type ShapeStep = "none" | "extra-small" | "small" | "medium" | "large" | "large-increased" | "extra-large" | "extra-large-increased" | "extra-extra-large";
+/** `var(--mtrl-sys-shape-corner-small, 8px)`: a step's token, its px the fallback. */
+export declare const cornerToken: (step: ShapeStep, px: number, prefix?: string) => string;

package/dist/core/theme/shape.js

@@ -0,0 +1 @@
+export const cornerToken = (step, px, prefix = "mtrl") => `var(--${prefix}-sys-shape-corner-${step}, ${px}px)`;

package/dist/core/theme/tokens.d.ts

@@ -0,0 +1,45 @@
+/**
+ * M3 colour roles to mtrl's colour tokens (FLO-308).
+ *
+ * One function turns a scheme's role colours into the `--mtrl-sys-color-*`
+ * declarations a theme sets, light and dark. The theme generator
+ * (`scripts/generate-themes.ts`) calls it with material-color-utilities'
+ * output, and md3.io's theme builder calls it the same way, so a theme made on
+ * the site and a theme shipped in the package cannot drift. It has no
+ * dependency: the colour science stays in the caller.
+ *
+ * @module core/theme
+ */
+/**
+ * The colour roles a theme sets: the baseline theme's, in its order. Every
+ * generated theme declares exactly these (a test holds the list to baseline).
+ */
+export declare const THEME_ROLES: readonly ["error", "on-error", "error-container", "on-error-container", "primary", "on-primary", "primary-container", "on-primary-container", "secondary", "on-secondary", "secondary-container", "on-secondary-container", "tertiary", "on-tertiary", "tertiary-container", "on-tertiary-container", "primary-fixed", "primary-fixed-dim", "on-primary-fixed", "on-primary-fixed-variant", "secondary-fixed", "secondary-fixed-dim", "on-secondary-fixed", "on-secondary-fixed-variant", "tertiary-fixed", "tertiary-fixed-dim", "on-tertiary-fixed", "on-tertiary-fixed-variant", "surface", "surface-dim", "surface-bright", "surface-variant", "surface-container-lowest", "surface-container-low", "surface-container", "surface-container-high", "surface-container-highest", "on-surface", "on-surface-variant", "outline", "outline-variant", "shadow", "scrim", "inverse-surface", "inverse-on-surface", "inverse-primary"];
+export type ThemeRole = (typeof THEME_ROLES)[number];
+/**
+ * A scheme's colours by role. Keys are the M3 role names, kebab-case
+ * (`primary-container`) or camelCase as material-color-utilities spells them
+ * (`primaryContainer`); values are `#rrggbb` hex strings.
+ */
+export type SchemeRoles = Record<string, string>;
+export interface SchemeToTokensOptions {
+    /** The token prefix, as `--{prefix}-sys-color-*`. Default `mtrl`. */
+    prefix?: string;
+}
+/** A theme's declarations: custom property to value, light and dark. */
+export interface ThemeTokens {
+    light: Record<string, string>;
+    dark: Record<string, string>;
+}
+/**
+ * Turns a light and a dark scheme's role colours into a theme's colour
+ * tokens. Every role in {@link THEME_ROLES} must be present in both.
+ *
+ * @example
+ * const tokens = schemeToTokens({ light, dark });
+ * tokens.light["--mtrl-sys-color-primary"]; // "#6750a4"
+ */
+export declare const schemeToTokens: (schemes: {
+    light: SchemeRoles;
+    dark: SchemeRoles;
+}, options?: SchemeToTokensOptions) => ThemeTokens;

package/dist/core/theme/tokens.js

@@ -0,0 +1,36 @@
+export const THEME_ROLES = [
+    "error", "on-error", "error-container", "on-error-container",
+    "primary", "on-primary", "primary-container", "on-primary-container",
+    "secondary", "on-secondary", "secondary-container", "on-secondary-container",
+    "tertiary", "on-tertiary", "tertiary-container", "on-tertiary-container",
+    "primary-fixed", "primary-fixed-dim", "on-primary-fixed", "on-primary-fixed-variant",
+    "secondary-fixed", "secondary-fixed-dim", "on-secondary-fixed", "on-secondary-fixed-variant",
+    "tertiary-fixed", "tertiary-fixed-dim", "on-tertiary-fixed", "on-tertiary-fixed-variant",
+    "surface", "surface-dim", "surface-bright", "surface-variant",
+    "surface-container-lowest", "surface-container-low", "surface-container",
+    "surface-container-high", "surface-container-highest",
+    "on-surface", "on-surface-variant",
+    "outline", "outline-variant", "shadow", "scrim",
+    "inverse-surface", "inverse-on-surface", "inverse-primary",
+];
+const kebab = (name) => name.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`);
+const HEX = /^#([0-9a-f]{6})$/i;
+const mode = (roles, name, prefix) => {
+    const byRole = new Map();
+    for (const [key, value] of Object.entries(roles))
+        byRole.set(kebab(key), value);
+    const tokens = {};
+    for (const role of THEME_ROLES) {
+        const hex = byRole.get(role);
+        if (hex === undefined)
+            throw new Error(`schemeToTokens: ${name} scheme has no ${role}`);
+        if (!HEX.test(hex))
+            throw new Error(`schemeToTokens: ${name} ${role} is not #rrggbb: ${hex}`);
+        tokens[`--${prefix}-sys-color-${role}`] = hex.toLowerCase();
+    }
+    return tokens;
+};
+export const schemeToTokens = (schemes, options = {}) => {
+    const prefix = options.prefix ?? "mtrl";
+    return { light: mode(schemes.light, "light", prefix), dark: mode(schemes.dark, "dark", prefix) };
+};