Initial support for style module media query variations

Author: bheston

package-lock.json

@@ -55,6 +55,6 @@ export class AdaptiveComponent extends FASTElement {
         //     prev.forEach((s) => this.$fastController.removeStyles(s));
         // }
         const elementStyles = renderElementStyles(next, params);
-        elementStyles.forEach((s) => this.$fastController.addStyles(s));
+        this.$fastController.addStyles(elementStyles);
     }
 }

packages/adaptive-ui-explorer/src/components/adaptive-component.ts

@@ -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 { TypedCSSDesignToken as TypedCSSDesignToken_2 } from '../adaptive-design-tokens.js';
 import { ValuesOf } from '@microsoft/fast-foundation';
 
@@ -593,6 +593,15 @@ export const fontFamily: TypedCSSDesignToken_2<string>;
 // @public (undocumented)
 export const fontWeight: TypedCSSDesignToken_2<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: TypedCSSDesignToken<Swatch>;
 
@@ -1339,7 +1348,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;
@@ -1461,7 +1470,7 @@ export interface StyleModuleTarget {
 }
 
 // @public
-export type StyleProperties = Partial<Record<StyleProperty, CSSDesignToken<any> | InteractiveTokenGroup<any> | CSSDirective | string>>;
+export type StyleProperties = Partial<Record<StyleProperty, CSSDesignToken<any> | InteractiveTokenGroup<any> | CSSDirective | string | InteractiveSet<string>>>;
 
 // @public
 export const StyleProperty: {
@@ -1498,8 +1507,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

@@ -4,5 +4,6 @@ export * from "./create.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

@@ -4,6 +4,7 @@ import { Swatch } from "../color/swatch.js";
 import type { InteractiveSet, InteractiveTokenGroup } from "../types.js";
 import { StyleProperties, Styles } from "../modules/styles.js";
 import { TypedCSSDesignToken } from "../adaptive-design-tokens.js";
+import { MediaQuery } from "../modules/css.js";
 import { cornerRadiusControl, cornerRadiusLayer, strokeThickness } from "./appearance.js";
 import {
     accentFillDiscernible,
@@ -63,6 +64,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.
@@ -553,6 +555,9 @@ export const selectableSelectedStyles: Styles = Styles.compose(
     controlShapeStyles,
     typeRampBaseStyles,
     accentFillReadableControlStyles
+).withMediaQuery(
+    MediaQuery.ForcedColors,
+    forcedColorsHighlightStyles,
 );
 
 /**
@@ -562,6 +567,9 @@ export const selectableUnselectedStyles: Styles = Styles.compose(
     controlShapeStyles,
     typeRampBaseStyles,
     neutralOutlineDiscernibleControlStyles
+).withMediaQuery(
+    MediaQuery.ForcedColors,
+    forcedColorsButtonStyles,
 );
 
 /**
@@ -587,4 +595,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,6 +1,6 @@
 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 { InteractiveTokenGroup } from "../types.js";
 import { makeSelector } from "./selector.js";
@@ -18,9 +18,9 @@ function propertySingle<T = string>(
         css`${makeSelector(params)} { ${property}: ${value}; }`;
 }
 
-function propertyInteractive<T = string>(
+function propertyInteractive(
     property: string,
-    values: InteractiveTokenGroup<T>,
+    values: InteractiveTokenGroup<string | CSSDesignToken<any>>,
     focusSelector: FocusSelector = "focus-visible",
 ): StyleModuleEvaluate {
     return (params: StyleModuleEvaluateParameters): ElementStyles => css`
@@ -57,10 +57,11 @@ function createElementStyleModules(styles: Styles): StyleModuleEvaluate[] {
     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 { InteractiveTokenGroup } from "../types.js";
+import { InteractiveSet, InteractiveTokenGroup } 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> | InteractiveTokenGroup<any> | CSSDirective | string>>;
+export type StyleProperties = Partial<Record<
+    StyleProperty,
+    CSSDesignToken<any> | InteractiveTokenGroup<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)) {
@@ -64,6 +69,30 @@ export class Styles {
         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.
      */