Initial support for style module media query variations

Author: bheston

package-lock.json

@@ -9,7 +9,7 @@ import { CSSDesignToken } from '@microsoft/fast-foundation';
 import { CSSDirective } from '@microsoft/fast-element';
 import { DesignToken } from '@microsoft/fast-foundation';
 import { DesignTokenResolver } from '@microsoft/fast-foundation';
-import type { ElementStyles } from '@microsoft/fast-element';
+import { ElementStyles } from '@microsoft/fast-element';
 import type { ValuesOf } from '@microsoft/fast-foundation';
 
 // @public (undocumented)
@@ -521,6 +521,15 @@ export const focusStrokeWidth: CSSDesignToken<number>;
 // @public (undocumented)
 export const fontWeight: CSSDesignToken<number>;
 
+// @public (undocumented)
+export const forcedColorsButtonStyles: Styles;
+
+// @public (undocumented)
+export const forcedColorsHighlightStyles: Styles;
+
+// @public (undocumented)
+export const forcedColorsTextStyles: Styles;
+
 // @public @deprecated (undocumented)
 export const foregroundOnAccentActive: CSSDesignToken<Swatch>;
 
@@ -1261,7 +1270,7 @@ export interface RelativeLuminance {
 }
 
 // @public
-export function renderElementStyles(styles: Styles, params: StyleModuleEvaluateParameters): ElementStyles[];
+export function renderElementStyles(styles: Styles, params: StyleModuleEvaluateParameters): ElementStyles;
 
 // @public
 export function resolvePaletteDirection(direction: PaletteDirection): PaletteDirectionValue;
@@ -1380,7 +1389,7 @@ export interface StyleModuleTarget {
 }
 
 // @public
-export type StyleProperties = Partial<Record<StyleProperty, CSSDesignToken<any> | InteractiveTokenSet<any> | CSSDirective | string>>;
+export type StyleProperties = Partial<Record<StyleProperty, CSSDesignToken<any> | InteractiveTokenSet<any> | CSSDirective | string | InteractiveSet<string>>>;
 
 // @public
 export const StyleProperty: {
@@ -1417,8 +1426,10 @@ export class Styles {
     get composed(): Styles[] | undefined;
     get effectiveProperties(): StyleProperties;
     static fromProperties(properties: StyleProperties): Styles;
+    getMediaQueryStyles(): ReadonlyMap<string, Styles> | undefined;
     get properties(): StyleProperties | undefined;
     set properties(properties: StyleProperties | undefined);
+    withMediaQuery(query: string, styles: Styles): this;
 }
 
 // @public

packages/adaptive-ui/docs/api-report.md

@@ -35,7 +35,8 @@
     },
     "dependencies": {
         "@microsoft/fast-colors": "^5.3.1",
-        "@microsoft/fast-foundation": "3.0.0-alpha.27"
+        "@microsoft/fast-foundation": "3.0.0-alpha.27",
+        "@microsoft/fast-web-utilities": "^6.0.0"
     },
     "devDependencies": {
         "@microsoft/api-extractor": "^7.34.4",
@@ -52,4 +53,4 @@
             "default": "./dist/esm/index.js"
         }
     }
-}
+}

packages/adaptive-ui/package.json

@@ -3,5 +3,6 @@ export * from "./color.js";
 export * from "./elevation.js";
 export * from "./layer.js";
 export * from "./modules.js";
+export * from "./modules.forced-colors.js";
 export * from "./palette.js";
 export * from "./type.js";

packages/adaptive-ui/src/design-tokens/index.ts

@@ -0,0 +1,59 @@
+import { SystemColors } from "@microsoft/fast-web-utilities";
+import { InteractiveSet } from "../types.js";
+import { Styles } from "../modules/styles.js";
+
+/**
+ * Convenience function for styles that share rest/focus and hover/active states.
+ *
+ * @param restAndFocus - The value to use for rest and focus states.
+ * @param hoverAndActive - The value to use for hover and active states.
+ * @returns A full interactive color set.
+ */
+function set(
+    restAndFocus: string,
+    hoverAndActive: string,
+): InteractiveSet<string> {
+    return {
+        rest: restAndFocus,
+        hover: hoverAndActive,
+        active: hoverAndActive,
+        focus: restAndFocus,
+    };
+}
+
+/**
+ * @public
+ */
+export const forcedColorsButtonStyles: Styles = Styles.fromProperties({
+    backgroundFill: {
+        ...set(SystemColors.ButtonFace, SystemColors.HighlightText),
+    },
+    foregroundFill: {
+        ...set(SystemColors.ButtonText, SystemColors.Highlight),
+    },
+    borderFill: {
+        ...set(SystemColors.ButtonText, SystemColors.Highlight),
+    },
+});
+
+/**
+ * @public
+ */
+export const forcedColorsHighlightStyles: Styles = Styles.fromProperties({
+    backgroundFill: {
+        ...set(SystemColors.Highlight, SystemColors.ButtonFace),
+    },
+    foregroundFill: {
+        ...set(SystemColors.HighlightText, SystemColors.ButtonText),
+    },
+    borderFill: {
+        ...set(SystemColors.Highlight, SystemColors.ButtonText),
+    },
+});
+
+/**
+ * @public
+ */
+export const forcedColorsTextStyles: Styles = Styles.fromProperties({
+    foregroundFill: SystemColors.CanvasText,
+});

packages/adaptive-ui/src/design-tokens/modules.forced-colors.ts

@@ -3,6 +3,7 @@ import { InteractiveColorRecipe, InteractiveColorRecipeBySet, InteractiveSwatchS
 import { Swatch } from "../color/swatch.js";
 import type { InteractiveSet, InteractiveTokenSet } from "../types.js";
 import { StyleProperties, Styles } from "../modules/styles.js";
+import { MediaQuery } from "../modules/css.js";
 import {
     accentFillDiscernibleInteractiveSet,
     accentFillReadableInteractiveSet,
@@ -60,6 +61,7 @@ import {
     typeRampPlus6FontVariations,
     typeRampPlus6LineHeight,
 } from "./type.js";
+import { forcedColorsButtonStyles, forcedColorsHighlightStyles, forcedColorsTextStyles } from "./modules.forced-colors.js";
 
 /**
  * Creates a set of foreground tokens applied over the background tokens.
@@ -517,6 +519,9 @@ export const inputStyles: Styles = Styles.compose(
 export const selectableSelectedStyles: Styles = Styles.compose(
     typeRampBaseStyles,
     accentFillReadableControlStyles
+).withMediaQuery(
+    MediaQuery.ForcedColors,
+    forcedColorsHighlightStyles,
 );
 
 /**
@@ -525,6 +530,9 @@ export const selectableSelectedStyles: Styles = Styles.compose(
 export const selectableUnselectedStyles: Styles = Styles.compose(
     typeRampBaseStyles,
     neutralOutlineDiscernibleControlStyles
+).withMediaQuery(
+    MediaQuery.ForcedColors,
+    forcedColorsButtonStyles,
 );
 
 /**
@@ -549,4 +557,7 @@ export const plainTextStyles: Styles = Styles.compose(
 export const labelTextStyles: Styles = Styles.compose(
     typeRampBaseStyles,
     neutralForegroundStrongElementStyles
+).withMediaQuery(
+    MediaQuery.ForcedColors,
+    forcedColorsTextStyles,
 );

packages/adaptive-ui/src/design-tokens/modules.ts

@@ -1,5 +1,14 @@
 import { StyleProperty } from "./types.js";
 
+/**
+ * Convenience media queries for {@link Styles} variations.
+ */
+export const MediaQuery = {
+    ForcedColors: "(forced-colors)",
+    ColorsDark: "(prefers-color-scheme: dark)",
+    ColorsLight: "(prefers-color-scheme: light)",
+} as const;
+
 /**
  * Converts a {@link StyleProperty} to a css property name.
  *

packages/adaptive-ui/src/modules/css.ts

@@ -1,8 +1,8 @@
 import { css } from "@microsoft/fast-element";
-import type { CSSDirective, ElementStyles } from "@microsoft/fast-element";
-import { CSSDesignToken } from "@microsoft/fast-foundation";
+import { CSSDirective, ElementStyles } from "@microsoft/fast-element";
+import { CSSDesignToken, MatchMediaStyleSheetBehavior } from "@microsoft/fast-foundation";
 import type { StyleProperty } from "../modules/types.js";
-import type { InteractiveTokenSet } from "../types.js";
+import type { InteractiveSet } from "../types.js";
 import { makeSelector } from "./selector.js";
 import type { FocusSelector, StyleModuleEvaluateParameters } from "./types.js";
 import { stylePropertyToCssProperty } from "./css.js";
@@ -18,9 +18,9 @@ function propertySingle<T = string>(
         css`${makeSelector(params)} { ${property}: ${value}; }`;
 }
 
-function propertyInteractive<T = string>(
+function propertyInteractive(
     property: string,
-    values: InteractiveTokenSet<T>,
+    values: InteractiveSet<string | CSSDesignToken<any>>,
     focusSelector: FocusSelector = "focus-visible",
 ): StyleModuleEvaluate {
     return (params: StyleModuleEvaluateParameters): ElementStyles => css`
@@ -51,16 +51,17 @@ function createElementStyleModules(styles: Styles): StyleModuleEvaluate[] {
         } else if (value && typeof (value as any).createCSS === "function") {
             return propertySingle(property, value as CSSDirective);
         } else {
-            return propertyInteractive(property, value as InteractiveTokenSet<any>);
+            return propertyInteractive(property, value as InteractiveSet<any>);
         }
     });
     return modules;
 }
 
-function createElementStyles(modules: StyleModuleEvaluate[], params: StyleModuleEvaluateParameters): ElementStyles[] {
-    return modules.map((module) =>
+function createElementStyles(modules: StyleModuleEvaluate[], params: StyleModuleEvaluateParameters): ElementStyles {
+    const styles = modules.map((module) =>
         module(params)
     );
+    return new ElementStyles(styles);
 }
 
 /**
@@ -72,6 +73,15 @@ function createElementStyles(modules: StyleModuleEvaluate[], params: StyleModule
  *
  * @public
  */
-export function renderElementStyles(styles: Styles, params: StyleModuleEvaluateParameters): ElementStyles[] {
-    return createElementStyles(createElementStyleModules(styles), params);
+export function renderElementStyles(styles: Styles, params: StyleModuleEvaluateParameters): ElementStyles {
+    const elementStyles = createElementStyles(createElementStyleModules(styles), params);
+
+    styles.getMediaQueryStyles()?.forEach((queryStyles, query) => {
+        const queryElementStyles = createElementStyles(createElementStyleModules(queryStyles), params);
+        elementStyles.withBehaviors(
+            MatchMediaStyleSheetBehavior.with(
+                window.matchMedia(query))(queryElementStyles))
+    });
+
+    return elementStyles;
 }

packages/adaptive-ui/src/modules/element-styles-renderer.ts

@@ -1,14 +1,17 @@
 import type { CSSDirective } from "@microsoft/fast-element";
 import type { CSSDesignToken } from "@microsoft/fast-foundation";
-import { InteractiveTokenSet } from "../types.js";
+import { InteractiveSet, InteractiveTokenSet } from "../types.js";
 import { StyleProperty } from "./types.js";
 
 /**
  * A collection of style definitions, where the key is the {@link (StyleProperty:type)} and the value is the token or final value.
  *
  * @public
  */
-export type StyleProperties = Partial<Record<StyleProperty, CSSDesignToken<any> | InteractiveTokenSet<any> | CSSDirective | string>>;
+export type StyleProperties = Partial<Record<
+    StyleProperty,
+    CSSDesignToken<any> | InteractiveTokenSet<any> | CSSDirective | string | InteractiveSet<string>
+>>;
 
 /**
  * A modular definition of style properties, either an alias to another style module or a collection of style properties.
@@ -22,6 +25,8 @@ export class Styles {
     private _properties?: StyleProperties;
     // Effective properties from composed styles and additional properties
     private _composedProperties?: StyleProperties;
+    // Style overrides for a media query
+    private _mediaQueryVariations: Map<string, Styles>;
 
     private constructor(propertiesOrStyles: StyleProperties | Styles[]) {
         if (Array.isArray(propertiesOrStyles)) {
@@ -53,20 +58,41 @@ export class Styles {
     }
 
     /**
-     * Gets the local properties or composition overrides. See {@link }.
+     * The local properties or composition overrides.
      */
     public get properties(): StyleProperties | undefined {
         return this._properties;
     }
 
-    /**
-     * Sets the local properties or composition overrides.
-     */
     public set properties(properties: StyleProperties | undefined) {
         this._properties = properties;
         this.createEffectiveProperties();
     }
 
+    /**
+     * Adds a style variation for a media query like `forced-colors`.
+     *
+     * @param query - The media query, see {@link MediaQuery}.
+     * @param styles - The styles to apply for the provided media query
+     * @returns The `Styles` definition with media query variation.
+     */
+    public withMediaQuery(query: string, styles: Styles): this {
+        if (!this._mediaQueryVariations) {
+            this._mediaQueryVariations = new Map();
+        }
+        this._mediaQueryVariations.set(query, styles);
+        return this;
+    }
+
+    /**
+     * Gets the media query variations for this style.
+     *
+     * @returns The defined media query variations.
+     */
+    public getMediaQueryStyles(): ReadonlyMap<string, Styles> | undefined {
+        return this._mediaQueryVariations;
+    }
+
     /**
      * Gets the full effective set of properties, from composed styles and local properties as applicable.
      */

packages/adaptive-ui/src/modules/styles.ts

@@ -131,9 +131,7 @@ export class DesignSystem {
             for (const [target, styles] of options.styleModules) {
                 const params: StyleModuleEvaluateParameters = Object.assign({}, interactivity, target);
                 const renderedStyles = renderElementStyles(styles, params);
-                for (const s of renderedStyles) {
-                    componentStyles.push(s);
-                }
+                componentStyles.push(renderedStyles);
             }
         }