Updating palette base color token type for better type safety (#222)

bheston · web-flow · commit 6834958dc812 · 2024-08-13T10:55:59.000-07:00
diff --git a/change/@adaptive-web-adaptive-ui-7642ef95-7e3c-41a1-8163-c8b9a22b4ae6.json b/change/@adaptive-web-adaptive-ui-7642ef95-7e3c-41a1-8163-c8b9a22b4ae6.json
@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "Updating palette base color token type for better type safety",
+  "packageName": "@adaptive-web/adaptive-ui",
+  "email": "47367562+bheston@users.noreply.github.com",
+  "dependentChangeType": "patch"
+}
diff --git a/change/@adaptive-web-adaptive-ui-designer-core-5bdb15bf-85e4-4209-a9d5-2766c1acd51c.json b/change/@adaptive-web-adaptive-ui-designer-core-5bdb15bf-85e4-4209-a9d5-2766c1acd51c.json
@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "Updating palette base color token type for better type safety",
+  "packageName": "@adaptive-web/adaptive-ui-designer-core",
+  "email": "47367562+bheston@users.noreply.github.com",
+  "dependentChangeType": "patch"
+}
diff --git a/examples/use-adaptive-components/src/index.ts b/examples/use-adaptive-components/src/index.ts
@@ -25,6 +25,7 @@ import {
     layerFillFixedBase
 } from "@adaptive-web/adaptive-ui/reference";
 import { DesignToken, FASTRadioGroup, FASTSwitch } from "@microsoft/fast-foundation";
+import { Color } from '@adaptive-web/adaptive-ui';
 
 // This must be called during initialization for the Design Tokens to be setup so the component styling is applied.
 DesignToken.registerDefaultStyleTarget();
@@ -47,5 +48,5 @@ document.getElementById("accentColor").onchange = function(event) {
     const value = (event.target as FASTRadioGroup).value;
     console.log("accentColor change", value);
     // This Design Token causes the accent palette to update, including any components styled with recipes based on that palette.
-    accentBaseColor.withDefault("#" + value);
+    accentBaseColor.withDefault(Color.parse("#" + value));
 };
diff --git a/packages/adaptive-ui-designer-core/src/index.ts b/packages/adaptive-ui-designer-core/src/index.ts
@@ -13,7 +13,7 @@ export {
     AppliedDesignTokens,
     DesignTokenValues
 } from "./model.js";
-export { mapReplacer, mapReviver, deserializeMap } from "./serialization.js";
+export { mapReplacer, mapReviver, deserializeMap, serializeMap } from "./serialization.js";
 export { State, StatesState, PluginNode, focusIndicatorNodeName, } from "./node.js";
 export { DesignTokenDefinition, DesignTokenRegistry, FormControlId } from "./registry/design-token-registry.js";
 export { nameToTitle, registerAppliableTokens, registerTokens } from "./registry/recipes.js";
diff --git a/packages/adaptive-ui-designer-core/src/registry/custom-recipes.ts b/packages/adaptive-ui-designer-core/src/registry/custom-recipes.ts
@@ -2,7 +2,6 @@ import {
     ColorRecipeParams,
     contrastSwatch,
     createNonCss,
-    createTokenColor,
     createTokenColorRecipe,
     createTokenColorRecipeValue,
     createTokenSwatch,
@@ -11,6 +10,7 @@ import {
     PaletteRGB,
     StyleProperty,
     stylePropertyBorderFillAll,
+    Swatch,
 } from "@adaptive-web/adaptive-ui";
 import {
     blackOrWhiteDiscernibleRecipe,
@@ -25,7 +25,7 @@ import { DesignTokenResolver } from "@microsoft/fast-foundation";
 
 // Local recipes for use in documentation files.
 
-export const docBaseColor = createTokenColor("doc-base-color").withDefault("#E1477E");
+export const docBaseColor = createTokenSwatch("doc-base-color").withDefault(Swatch.parse("#E1477E")!);
 
 export const docPalette = createNonCss<Palette>("doc-palette").withDefault(
     (resolve: DesignTokenResolver) =>
diff --git a/packages/adaptive-ui-designer-core/src/registry/recipes.ts b/packages/adaptive-ui-designer-core/src/registry/recipes.ts
@@ -1,10 +1,10 @@
 import { sentenceCase } from "change-case";
 import type { DesignToken } from "@microsoft/fast-foundation";
 import {
+    Color,
     densityAdjustmentUnits,
     DesignTokenMetadata,
     DesignTokenType,
-    Swatch,
     TypedCSSDesignToken
 } from "@adaptive-web/adaptive-ui"
 import {
@@ -79,6 +79,7 @@ import {
     labelFontFamily,
     labelFontStyle,
     labelFontWeight,
+    layerFillActiveDelta,
     layerFillBaseLuminance,
     layerFillFixedBase,
     layerFillFixedMinus1,
@@ -89,7 +90,10 @@ import {
     layerFillFixedPlus2,
     layerFillFixedPlus3,
     layerFillFixedPlus4,
+    layerFillFocusDelta,
+    layerFillHoverDelta,
     layerFillInteractive,
+    layerFillRestDelta,
     neutralBaseColor,
     neutralFillDiscernible,
     neutralFillIdeal,
@@ -167,6 +171,10 @@ const designTokens: DesignTokenStore = [
     warningBaseColor,
     criticalBaseColor,
     layerFillBaseLuminance,
+    layerFillRestDelta,
+    layerFillHoverDelta,
+    layerFillActiveDelta,
+    layerFillFocusDelta,
     docBaseColor,
     wcagContrastLevel,
     densityAdjustmentUnits,
@@ -195,7 +203,7 @@ const designTokens: DesignTokenStore = [
     strokeStrongRestDelta,
 ];
 
-const colorTokens: DesignTokenStore<Swatch> = [
+const colorTokens: DesignTokenStore<Color> = [
     // Layer
     layerFillFixedMinus4,
     layerFillFixedMinus3,
@@ -208,36 +216,43 @@ const colorTokens: DesignTokenStore<Swatch> = [
     layerFillFixedPlus4,
     layerFillInteractive.rest,
     // Fill
+    accentBaseColor,
     accentFillStealth.rest,
     accentFillSubtle.rest,
     accentFillIdeal.rest,
     accentFillDiscernible.rest,
     accentFillReadable.rest,
+    highlightBaseColor,
     highlightFillStealth.rest,
     highlightFillSubtle.rest,
     highlightFillIdeal.rest,
     highlightFillDiscernible.rest,
     highlightFillReadable.rest,
+    criticalBaseColor,
     criticalFillStealth.rest,
     criticalFillSubtle.rest,
     criticalFillIdeal.rest,
     criticalFillDiscernible.rest,
     criticalFillReadable.rest,
+    warningBaseColor,
     warningFillStealth.rest,
     warningFillSubtle.rest,
     warningFillIdeal.rest,
     warningFillDiscernible.rest,
     warningFillReadable.rest,
+    successBaseColor,
     successFillStealth.rest,
     successFillSubtle.rest,
     successFillIdeal.rest,
     successFillDiscernible.rest,
     successFillReadable.rest,
+    infoBaseColor,
     infoFillStealth.rest,
     infoFillSubtle.rest,
     infoFillIdeal.rest,
     infoFillDiscernible.rest,
     infoFillReadable.rest,
+    neutralBaseColor,
     neutralFillStealth.rest,
     neutralFillSubtle.rest,
     neutralFillIdeal.rest,
diff --git a/packages/adaptive-ui-designer-figma-plugin/src/figma/node.ts b/packages/adaptive-ui-designer-figma-plugin/src/figma/node.ts
@@ -1,8 +1,6 @@
 import { type Color, modeLrgb, modeRgb, parse, type Rgb, useMode, wcagLuminance } from "culori/fn";
 import { Shadow, StyleProperty } from "@adaptive-web/adaptive-ui";
-import { Controller, STYLE_REMOVE } from "@adaptive-web/adaptive-ui-designer-core";
-import { AppliedStyleModules, AppliedStyleValues, PluginNodeData } from "@adaptive-web/adaptive-ui-designer-core";
-import { focusIndicatorNodeName, PluginNode, State, StatesState } from "@adaptive-web/adaptive-ui-designer-core";
+import { AppliedStyleModules, AppliedStyleValues, Controller, focusIndicatorNodeName, PluginNode, PluginNodeData, serializeMap, State, StatesState, STYLE_REMOVE } from "@adaptive-web/adaptive-ui-designer-core";
 import { FIGMA_SHARED_DATA_NAMESPACE } from "@adaptive-web/adaptive-ui-designer-figma";
 import { colorToRgba, variantBooleanHelper } from "./utility.js";
 
@@ -217,11 +215,11 @@ export class FigmaPluginNode extends PluginNode {
             });
 
             if (deserializedDesignTokens.size) {
-                // console.log("    reconciled design tokens", this.debugInfo, deserializedDesignTokens.serialize());
+                // console.log("    reconciled design tokens", this.debugInfo, serializeMap(deserializedDesignTokens));
             }
 
             if (deserializedAppliedDesignTokens.size) {
-                // console.log("    reconciled applied design tokens", this.debugInfo, deserializedAppliedDesignTokens.serialize());
+                // console.log("    reconciled applied design tokens", this.debugInfo, serializeMap(deserializedAppliedDesignTokens));
             }
         }
 
diff --git a/packages/adaptive-ui-designer-figma-plugin/src/ui/components/design-token-add/index.ts b/packages/adaptive-ui-designer-figma-plugin/src/ui/components/design-token-add/index.ts
@@ -88,7 +88,7 @@ export class DesignTokenAdd extends FASTElement {
             }
 
             if (this.field) {
-                this.field.value = this.selectedDesignToken?.token.default;
+                this.field.value = "" + this.selectedDesignToken?.token.default;
             }
         }
     }
diff --git a/packages/adaptive-ui-designer-figma-plugin/src/ui/ui-controller.ts b/packages/adaptive-ui-designer-figma-plugin/src/ui/ui-controller.ts
@@ -224,7 +224,7 @@ export class UIController {
                             source,
                         });
                     } else {
-                        console.error("Token not found:", applied.tokenID, node.name, node.type);
+                        console.error("Token not found:", applied.tokenID, node.name, node.type, node.id, applied.value);
                     }
                 } else { // Removed
                     allApplied.set(target, {
diff --git a/packages/adaptive-ui-explorer/src/components/control-pane/control-pane.template.ts b/packages/adaptive-ui-explorer/src/components/control-pane/control-pane.template.ts
@@ -1,5 +1,6 @@
 import { ElementViewTemplate, html, repeat } from "@microsoft/fast-element";
 import { twoWay } from "@microsoft/fast-element/binding/two-way.js";
+import { Color } from "@adaptive-web/adaptive-ui";
 import { WcagContrastLevel } from "@adaptive-web/adaptive-ui/reference";
 import { ComponentType } from "../../component-type.js";
 import { ControlPane } from "./control-pane.js";
@@ -34,7 +35,7 @@ export function controlPaneTemplate<T extends ControlPane>(): ElementViewTemplat
                 type="color"
                 value=${(x) => x.state.neutralColor}
                 @change=${(x, c) =>
-                    x.state.neutralColor = c.eventTarget<HTMLInputElement>().value
+                    x.state.neutralColor = Color.parse(c.eventTarget<HTMLInputElement>().value)!
                 }
             />
         </div>
@@ -50,7 +51,7 @@ export function controlPaneTemplate<T extends ControlPane>(): ElementViewTemplat
                 type="color"
                 value=${(x) => x.state.accentColor}
                 @change=${(x, c) =>
-                    x.state.accentColor = c.eventTarget<HTMLInputElement>().value
+                    x.state.accentColor = Color.parse(c.eventTarget<HTMLInputElement>().value)!
                 }
             />
         </div>
@@ -61,7 +62,7 @@ export function controlPaneTemplate<T extends ControlPane>(): ElementViewTemplat
                 type="color"
                 value=${(x) => x.state.highlightColor}
                 @change=${(x, c) =>
-                    x.state.highlightColor = c.eventTarget<HTMLInputElement>().value
+                    x.state.highlightColor = Color.parse(c.eventTarget<HTMLInputElement>().value)!
                 }
             />
         </div>
diff --git a/packages/adaptive-ui-explorer/src/state.ts b/packages/adaptive-ui-explorer/src/state.ts
@@ -1,34 +1,35 @@
 import { observable } from "@microsoft/fast-element";
 import { Context } from "@microsoft/fast-element/context.js";
+import { Color } from "@adaptive-web/adaptive-ui";
 import { WcagContrastLevel } from "@adaptive-web/adaptive-ui/reference";
 import { ComponentType } from "./component-type.js";
 
 export const State = Context.create<State>("State");
 export interface State {
     componentType: ComponentType;
-    neutralColor: string;
-    accentColor: string;
-    highlightColor: string;
+    neutralColor: Color;
+    accentColor: Color;
+    highlightColor: Color;
     showOnlyLayerBackgrounds: boolean;
     wcagContrastLevel: WcagContrastLevel;
     disabledState: boolean;
     showSwatches: boolean;
 }
 
-const PLACEHOLDER_COLOR = "#ff00ff";
+const PLACEHOLDER_COLOR = Color.parse("#ff00ff")!;
 
 export class DefaultState implements State {
     @observable
     public componentType: ComponentType = ComponentType.backplate;
 
     @observable
-    public neutralColor: string = PLACEHOLDER_COLOR;
+    public neutralColor: Color = PLACEHOLDER_COLOR;
 
     @observable
-    public accentColor: string = PLACEHOLDER_COLOR;
+    public accentColor: Color = PLACEHOLDER_COLOR;
 
     @observable
-    public highlightColor: string = PLACEHOLDER_COLOR;
+    public highlightColor: Color = PLACEHOLDER_COLOR;
 
     @observable
     public showOnlyLayerBackgrounds: boolean = true;
diff --git a/packages/adaptive-ui/docs/api-report.md b/packages/adaptive-ui/docs/api-report.md
@@ -71,6 +71,7 @@ export class Color implements RelativeLuminance, CSSDirective {
     static parse(color: string): Color | undefined;
     get relativeLuminance(): number;
     toColorString(): string;
+    toString: () => string;
 }
 
 // @public
@@ -154,7 +155,7 @@ export function createForegroundSetBySet(foregroundRecipe: TypedDesignToken<Inte
 export function createNonCss<T>(name: string): DesignToken<T>;
 
 // @public
-export function createTokenColor(name: string, intendedFor?: StyleProperty | StyleProperty[]): TypedCSSDesignToken<string>;
+export function createTokenColor(name: string, intendedFor?: StyleProperty | StyleProperty[]): TypedCSSDesignToken<Color>;
 
 // @public
 export function createTokenColorRecipe<T = Swatch>(baseName: string, intendedFor: StyleProperty | StyleProperty[], evaluate: ColorRecipeEvaluate<T>): TypedDesignToken<ColorRecipe<T>>;
diff --git a/packages/adaptive-ui/src/core/color/color.ts b/packages/adaptive-ui/src/core/color/color.ts
@@ -46,6 +46,11 @@ export class Color implements RelativeLuminance, CSSDirective {
         return this.color.alpha !== undefined && this.color.alpha < 1 ? formatRgb(this.color) : formatHex(this.color);
     }
 
+    /**
+     * {@inheritdoc Color.toColorString}
+     */
+    public toString = this.toColorString;
+
     /**
      * Gets the contrast between this Color and another.
      *
diff --git a/packages/adaptive-ui/src/core/token-helpers.ts b/packages/adaptive-ui/src/core/token-helpers.ts
@@ -1,5 +1,6 @@
 import { DesignToken } from "@microsoft/fast-foundation";
 import { DesignTokenType, TypedCSSDesignToken, TypedDesignToken } from "./adaptive-design-tokens.js";
+import { Color } from "./color/color.js";
 import { Swatch } from "./color/swatch.js";
 import { StyleProperty } from "./modules/types.js";
 import { Recipe, RecipeEvaluate } from "./recipes.js";
@@ -27,8 +28,8 @@ export const { createTyped } = TypedCSSDesignToken;
  *
  * @public
  */
-export function createTokenColor(name: string, intendedFor?: StyleProperty | StyleProperty[]): TypedCSSDesignToken<string> {
-    return TypedCSSDesignToken.createTyped<string>(name, DesignTokenType.color, intendedFor);
+export function createTokenColor(name: string, intendedFor?: StyleProperty | StyleProperty[]): TypedCSSDesignToken<Color> {
+    return TypedCSSDesignToken.createTyped<Color>(name, DesignTokenType.color, intendedFor);
 }
 
 /**
diff --git a/packages/adaptive-ui/src/reference/palette.ts b/packages/adaptive-ui/src/reference/palette.ts
@@ -1,10 +1,11 @@
 import type { DesignTokenResolver } from "@microsoft/fast-foundation";
 import { DesignTokenType } from "../core/adaptive-design-tokens.js";
-import { Palette, PaletteOkhsl } from "../core/color/index.js";
-import { createTokenNonCss } from "../core/token-helpers.js";
+import { Color, Palette, PaletteOkhsl } from "../core/color/index.js";
+import { createTokenColor, createTokenNonCss } from "../core/token-helpers.js";
+import { StyleProperty } from "../core/modules/types.js";
 
 /** @public */
-export const neutralBaseColor = createTokenNonCss<string>("color.neutral.base", DesignTokenType.color).withDefault("#808080");
+export const neutralBaseColor = createTokenColor("color.neutral.base", StyleProperty.backgroundFill).withDefault(Color.parse("#808080")!);
 
 /** @public */
 export const neutralPalette = createTokenNonCss<Palette>("color.neutral.palette", DesignTokenType.palette).withDefault(
@@ -13,7 +14,7 @@ export const neutralPalette = createTokenNonCss<Palette>("color.neutral.palette"
 );
 
 /** @public */
-export const accentBaseColor = createTokenNonCss<string>("color.accent.base", DesignTokenType.color).withDefault("#F26C0D");
+export const accentBaseColor = createTokenColor("color.accent.base", StyleProperty.backgroundFill).withDefault(Color.parse("#F26C0D")!);
 
 /** @public */
 export const accentPalette = createTokenNonCss<Palette>("color.accent.palette", DesignTokenType.palette).withDefault(
@@ -22,7 +23,7 @@ export const accentPalette = createTokenNonCss<Palette>("color.accent.palette",
 );
 
 /** @public */
-export const highlightBaseColor = createTokenNonCss<string>("color.highlight.base", DesignTokenType.color).withDefault("#0DA1F2");
+export const highlightBaseColor = createTokenColor("color.highlight.base", StyleProperty.backgroundFill).withDefault(Color.parse("#0DA1F2")!);
 
 /** @public */
 export const highlightPalette = createTokenNonCss<Palette>("color.highlight.palette", DesignTokenType.palette).withDefault(
@@ -31,7 +32,7 @@ export const highlightPalette = createTokenNonCss<Palette>("color.highlight.pale
 );
 
 /** @public */
-export const criticalBaseColor = createTokenNonCss<string>("color.critical.base", DesignTokenType.color).withDefault("#D92635");
+export const criticalBaseColor = createTokenColor("color.critical.base", StyleProperty.backgroundFill).withDefault(Color.parse("#D92635")!);
 
 /** @public */
 export const criticalPalette = createTokenNonCss<Palette>("color.critical.palette", DesignTokenType.palette).withDefault(
@@ -40,7 +41,7 @@ export const criticalPalette = createTokenNonCss<Palette>("color.critical.palett
 );
 
 /** @public */
-export const warningBaseColor = createTokenNonCss<string>("color.warning.base", DesignTokenType.color).withDefault("#D526D9");
+export const warningBaseColor = createTokenColor("color.warning.base", StyleProperty.backgroundFill).withDefault(Color.parse("#D526D9")!);
 
 /** @public */
 export const warningPalette = createTokenNonCss<Palette>("color.warning.palette", DesignTokenType.palette).withDefault(
@@ -49,7 +50,7 @@ export const warningPalette = createTokenNonCss<Palette>("color.warning.palette"
 );
 
 /** @public */
-export const successBaseColor = createTokenNonCss<string>("color.success.base", DesignTokenType.color).withDefault("#6AD926");
+export const successBaseColor = createTokenColor("color.success.base", StyleProperty.backgroundFill).withDefault(Color.parse("#6AD926")!);
 
 /** @public */
 export const successPalette = createTokenNonCss<Palette>("color.success.palette", DesignTokenType.palette).withDefault(
@@ -58,7 +59,7 @@ export const successPalette = createTokenNonCss<Palette>("color.success.palette"
 );
 
 /** @public */
-export const infoBaseColor = createTokenNonCss<string>("color.info.base", DesignTokenType.color).withDefault("#0DA1F2");
+export const infoBaseColor = createTokenColor("color.info.base", StyleProperty.backgroundFill).withDefault(Color.parse("#0DA1F2")!);
 
 /** @public */
 export const infoPalette = createTokenNonCss<Palette>("color.info.palette", DesignTokenType.palette).withDefault(

Original file line number	Diff line number	Diff line change
`@@ -1,8 +1,6 @@`
`1`	`1`	`import { type Color, modeLrgb, modeRgb, parse, type Rgb, useMode, wcagLuminance } from "culori/fn";`
`2`	`2`	`import { Shadow, StyleProperty } from "@adaptive-web/adaptive-ui";`
`3`		`-import { Controller, STYLE_REMOVE } from "@adaptive-web/adaptive-ui-designer-core";`
`4`		`-import { AppliedStyleModules, AppliedStyleValues, PluginNodeData } from "@adaptive-web/adaptive-ui-designer-core";`
`5`		`-import { focusIndicatorNodeName, PluginNode, State, StatesState } from "@adaptive-web/adaptive-ui-designer-core";`
	`3`	`+import { AppliedStyleModules, AppliedStyleValues, Controller, focusIndicatorNodeName, PluginNode, PluginNodeData, serializeMap, State, StatesState, STYLE_REMOVE } from "@adaptive-web/adaptive-ui-designer-core";`
`6`	`4`	`import { FIGMA_SHARED_DATA_NAMESPACE } from "@adaptive-web/adaptive-ui-designer-figma";`
`7`	`5`	`import { colorToRgba, variantBooleanHelper } from "./utility.js";`
`8`	`6`
`@@ -217,11 +215,11 @@ export class FigmaPluginNode extends PluginNode {`
`217`	`215`	`});`
`218`	`216`
`219`	`217`	`if (deserializedDesignTokens.size) {`
`220`		`- // console.log(" reconciled design tokens", this.debugInfo, deserializedDesignTokens.serialize());`
	`218`	`+ // console.log(" reconciled design tokens", this.debugInfo, serializeMap(deserializedDesignTokens));`
`221`	`219`	`}`
`222`	`220`
`223`	`221`	`if (deserializedAppliedDesignTokens.size) {`
`224`		`- // console.log(" reconciled applied design tokens", this.debugInfo, deserializedAppliedDesignTokens.serialize());`
	`222`	`+ // console.log(" reconciled applied design tokens", this.debugInfo, serializeMap(deserializedAppliedDesignTokens));`
`225`	`223`	`}`
`226`	`224`	`}`
`227`	`225`
Original file line number	Diff line number	Diff line change
`@@ -88,7 +88,7 @@ export class DesignTokenAdd extends FASTElement {`
`88`	`88`	`}`
`89`	`89`
`90`	`90`	`if (this.field) {`
`91`		`- this.field.value = this.selectedDesignToken?.token.default;`
	`91`	`+ this.field.value = "" + this.selectedDesignToken?.token.default;`
`92`	`92`	`}`
`93`	`93`	`}`
`94`	`94`	`}`
Original file line number	Diff line number	Diff line change
`@@ -224,7 +224,7 @@ export class UIController {`
`224`	`224`	`source,`
`225`	`225`	`});`
`226`	`226`	`} else {`
`227`		`- console.error("Token not found:", applied.tokenID, node.name, node.type);`
	`227`	`+ console.error("Token not found:", applied.tokenID, node.name, node.type, node.id, applied.value);`
`228`	`228`	`}`
`229`	`229`	`} else { // Removed`
`230`	`230`	`allApplied.set(target, {`