feat: adds direction property to design system (microsoft#3535)

* adds direction design system property

* adds inline-start and inline-end behaviors

* update API reports

* update API docs with examples

packages/web-components/fast-components-msft/docs/api-report.md

@@ -17,6 +17,7 @@ import { DensityOffset } from '@microsoft/fast-components-styles-msft';
 import { DesignSystem } from '@microsoft/fast-components-styles-msft';
 import { DesignSystemProvider } from '@microsoft/fast-foundation';
 import { Dialog } from '@microsoft/fast-foundation';
+import { Direction } from '@microsoft/fast-web-utilities';
 import { Divider } from '@microsoft/fast-foundation';
 import { Flipper } from '@microsoft/fast-foundation';
 import { Menu } from '@microsoft/fast-foundation';
@@ -136,6 +137,8 @@ export class FASTAnchor extends Anchor {
     appearance: AnchorAppearance;
     // (undocumented)
     appearanceChanged(oldValue: AnchorAppearance, newValue: AnchorAppearance): void;
+    // @internal (undocumented)
+    connectedCallback(): void;
 }
 
 // @public
@@ -149,6 +152,8 @@ export class FASTButton extends Button {
     appearance: ButtonAppearance;
     // (undocumented)
     appearanceChanged(oldValue: ButtonAppearance, newValue: ButtonAppearance): void;
+    // @internal (undocumented)
+    connectedCallback(): void;
 }
 
 // @public
@@ -160,7 +165,7 @@ export class FASTCheckbox extends Checkbox {
 }
 
 // @public
-export class FASTDesignSystemProvider extends DesignSystemProvider implements Omit<DesignSystem, "contrast" | "direction" | "fontWeight" | "neutralForegroundDarkIndex" | "neutralForegroundLightIndex"> {
+export class FASTDesignSystemProvider extends DesignSystemProvider implements Omit<DesignSystem, "contrast" | "fontWeight" | "neutralForegroundDarkIndex" | "neutralForegroundLightIndex"> {
     // (undocumented)
     accentBaseColor: string;
     // (undocumented)
@@ -197,6 +202,8 @@ export class FASTDesignSystemProvider extends DesignSystemProvider implements Om
     // (undocumented)
     designUnit: number;
     // (undocumented)
+    direction: Direction;
+    // (undocumented)
     disabledOpacity: number;
     // (undocumented)
     elevatedCornerRadius: number;
@@ -383,6 +390,12 @@ export const heightNumber = "(var(--base-height-multiplier) + var(--density)) *
 // @internal (undocumented)
 export const HypertextStyles: import("@microsoft/fast-element").ElementStyles;
 
+// @public
+export const inlineEndBehavior: import("@microsoft/fast-foundation").CSSCustomPropertyBehavior;
+
+// @public
+export const inlineStartBehavior: import("@microsoft/fast-foundation").CSSCustomPropertyBehavior;
+
 // Warning: (ae-internal-missing-underscore) The name "LightweightButtonStyles" should be prefixed with an underscore because the declaration is marked as @internal
 //
 // @internal (undocumented)

packages/web-components/fast-components-msft/src/design-system-provider/index.ts

@@ -5,6 +5,7 @@ import {
     DesignSystemDefaults,
     neutralForegroundRest,
 } from "@microsoft/fast-components-styles-msft";
+import { Direction } from "@microsoft/fast-web-utilities";
 import {
     CSSCustomPropertyBehavior,
     designSystemProperty,
@@ -46,7 +47,6 @@ export class FASTDesignSystemProvider extends DesignSystemProvider
         Omit<
             DesignSystem,
             | "contrast"
-            | "direction"
             | "fontWeight"
             | "neutralForegroundDarkIndex"
             | "neutralForegroundLightIndex"
@@ -117,6 +117,13 @@ export class FASTDesignSystemProvider extends DesignSystemProvider
     })
     public designUnit: number;
 
+    @designSystemProperty({
+        attribute: "direction",
+        cssCustomProperty: false,
+        default: DesignSystemDefaults.direction,
+    })
+    public direction: Direction;
+
     @designSystemProperty({
         attribute: "base-height-multiplier",
         default: DesignSystemDefaults.baseHeightMultiplier,

packages/web-components/fast-components-msft/src/styles/behaviors.ts

@@ -28,8 +28,11 @@ import {
     neutralLayerL3,
     neutralLayerL4,
     neutralOutline,
+    DesignSystem,
+    direction,
 } from "@microsoft/fast-components-styles-msft";
 import { FASTDesignSystemProvider } from "../design-system-provider";
+import { Direction } from "@microsoft/fast-web-utilities";
 
 /**
  * Behavior to resolve and make available the neutral-foreground-rest CSS custom property.
@@ -580,3 +583,57 @@ export const neutralFocusInnerAccentBehavior = cssCustomPropertyBehaviorFactory(
     neutralFocusInnerAccent(accentBaseColor),
     FASTDesignSystemProvider.findProvider
 );
+
+/**
+ * Behavior to resolve and make available the inline-start CSS custom property.
+ *
+ * @remarks
+ * Replaces the inline-start value for the {@link https://developer.mozilla.org/en-US/docs/Web/CSS/float | float} property
+ * when the native value is not supported.
+ *
+ * @public
+ * @example
+ * ```ts
+ * import { css } from "@microsoft/fast-element";
+ * import { inlineStartBehavior } from "@microsoft/fast-components-msft";
+ *
+ * css`
+ *   :host {
+ *     float: ${inlineStartBehavior.var};
+ *   }
+ * `.withBehaviors(inlineStartBehavior)
+ * ```
+ */
+export const inlineStartBehavior = cssCustomPropertyBehaviorFactory(
+    "inline-start",
+    (designSystem: DesignSystem) =>
+        direction(designSystem) === Direction.ltr ? "left" : "right",
+    FASTDesignSystemProvider.findProvider
+);
+
+/**
+ * Behavior to resolve and make available the inline-end CSS custom property.
+ *
+ * @remarks
+ * Replaces the inline-end value for the {@link https://developer.mozilla.org/en-US/docs/Web/CSS/float | float} property
+ * when the native value is not supported.
+ *
+ * @public
+ * @example
+ * ```ts
+ * import { css } from "@microsoft/fast-element";
+ * import { inlineEndBehavior } from "@microsoft/fast-components-msft";
+ *
+ * css`
+ *   :host {
+ *     float: ${inlineEndBehavior.var};
+ *   }
+ * `.withBehaviors(inlineEndBehavior)
+ * ```
+ */
+export const inlineEndBehavior = cssCustomPropertyBehaviorFactory(
+    "inline-end",
+    (designSystem: DesignSystem) =>
+        direction(designSystem) === Direction.ltr ? "right" : "left",
+    FASTDesignSystemProvider.findProvider
+);

packages/web-components/fast-components/docs/api-report.md

@@ -15,6 +15,7 @@ import { Checkbox } from '@microsoft/fast-foundation';
 import { ColorRGBA64 } from '@microsoft/fast-colors';
 import { DesignSystemProvider } from '@microsoft/fast-foundation';
 import { Dialog } from '@microsoft/fast-foundation';
+import { Direction } from '@microsoft/fast-web-utilities';
 import { Divider } from '@microsoft/fast-foundation';
 import { Flipper } from '@microsoft/fast-foundation';
 import { Menu } from '@microsoft/fast-foundation';
@@ -266,6 +267,7 @@ export interface FASTDesignSystem {
     cornerRadius: number;
     density: number;
     designUnit: number;
+    direction: Direction;
     disabledOpacity: number;
     focusOutlineWidth: number;
     neutralDividerRestDelta: number;
@@ -393,6 +395,8 @@ export class FASTDesignSystemProvider extends DesignSystemProvider implements FA
     // (undocumented)
     designUnit: number;
     // (undocumented)
+    direction: Direction;
+    // (undocumented)
     disabledOpacity: number;
     // (undocumented)
     focusOutlineWidth: number;
@@ -568,6 +572,12 @@ export class FASTTreeItem extends TreeItem {
 export class FASTTreeView extends TreeView {
 }
 
+// @public
+export const inlineEndBehavior: import("@microsoft/fast-foundation").CSSCustomPropertyBehavior;
+
+// @public
+export const inlineStartBehavior: import("@microsoft/fast-foundation").CSSCustomPropertyBehavior;
+
 // @public
 export function isDarkMode(designSystem: FASTDesignSystem): boolean;
 

packages/web-components/fast-components/src/design-system-provider/index.ts

@@ -9,6 +9,7 @@ import {
 import { FASTDesignSystem, fastDesignSystemDefaults } from "../fast-design-system";
 import { neutralForegroundRest } from "../color";
 import { DesignSystemProviderStyles as styles } from "./design-system-provider.styles";
+import { Direction } from "@microsoft/fast-web-utilities";
 
 const color = new CSSCustomPropertyBehavior(
     "neutral-foreground-rest",
@@ -120,6 +121,13 @@ export class FASTDesignSystemProvider extends DesignSystemProvider
     })
     public designUnit: number;
 
+    @designSystemProperty({
+        attribute: "direction",
+        cssCustomProperty: false,
+        default: fastDesignSystemDefaults.direction,
+    })
+    public direction: Direction;
+
     @designSystemProperty({
         attribute: "base-height-multiplier",
         default: fastDesignSystemDefaults.baseHeightMultiplier,

packages/web-components/fast-components/src/fast-design-system.ts

@@ -2,6 +2,7 @@ import {
     accentPalette as defaultAccentPalette,
     neutralPalette as defaultNeutralPalette,
 } from "./default-palette";
+import { Direction } from "@microsoft/fast-web-utilities";
 
 export type DesignSystemResolver<T, Y = FASTDesignSystem> = (d: Y) => T;
 
@@ -67,6 +68,11 @@ export interface FASTDesignSystem {
      */
     designUnit: number;
 
+    /**
+     * The primary document direction.
+     */
+    direction: Direction;
+
     /**
      * The number of designUnits used for component height at the base density.
      */
@@ -206,18 +212,19 @@ export const fastDesignSystemDefaults: FASTDesignSystem = {
     typeRampPlus6FontSize: "60px",
     typeRampPlus6LineHeight: "72px",
 
+    accentBaseColor: "#DA1A5F",
+    accentPalette: defaultAccentPalette,
     backgroundColor: "#181818",
-    density: 0,
-    designUnit: 4,
     baseHeightMultiplier: 10,
     baseHorizontalSpacingMultiplier: 3,
     cornerRadius: 3,
-    focusOutlineWidth: 2,
+    density: 0,
+    designUnit: 4,
+    direction: Direction.ltr,
     disabledOpacity: 0.3,
-    outlineWidth: 1,
+    focusOutlineWidth: 2,
     neutralPalette: defaultNeutralPalette,
-    accentPalette: defaultAccentPalette,
-    accentBaseColor: "#DA1A5F",
+    outlineWidth: 1,
 
     /**
      * Recipe Deltas
@@ -368,12 +375,19 @@ export const focusOutlineWidth: DesignSystemResolver<number> = getDesignSystemVa
     "focusOutlineWidth"
 );
 /**
- * Retrieve the direction from the design system
+ * Retrieve the disabledOpacity from the design system
  */
 export const disabledOpacity: DesignSystemResolver<number> = getDesignSystemValue(
     "disabledOpacity"
 );
 
+/**
+ * Retrieve the disabledOpacity from the design system
+ */
+export const direction: DesignSystemResolver<Direction> = getDesignSystemValue(
+    "direction"
+);
+
 export const accentFillRestDelta: DesignSystemResolver<number> = getDesignSystemValue(
     "accentFillRestDelta"
 );

packages/web-components/fast-components/src/index.ts

@@ -18,6 +18,7 @@ export * from "./radio-group/index";
 export * from "./slider/index";
 export * from "./slider-label/index";
 export * from "./styles/recipes";
+export * from "./styles/direction";
 export * from "./switch/index";
 export * from "./tabs/index";
 export * from "./text-area/index";

packages/web-components/fast-components/src/styles/direction.ts

@@ -0,0 +1,57 @@
+import { cssCustomPropertyBehaviorFactory } from "@microsoft/fast-foundation";
+import { Direction } from "@microsoft/fast-web-utilities";
+import { FASTDesignSystem, direction } from "../fast-design-system";
+import { FASTDesignSystemProvider } from "../design-system-provider";
+/**
+ * Behavior to resolve and make available the inline-start CSS custom property.
+ *
+ * @remarks
+ * Replaces the inline-start value for the {@link https://developer.mozilla.org/en-US/docs/Web/CSS/float | float} property
+ * when the native value is not supported.
+ *
+ * @public
+ * @example
+ * ```ts
+ * import { css } from "@microsoft/fast-element";
+ * import { inlineStartBehavior } from "@microsoft/fast-components";
+ *
+ * css`
+ *   :host {
+ *     float: ${inlineStartBehavior.var};
+ *   }
+ * `.withBehaviors(inlineStartBehavior)
+ * ```
+ */
+export const inlineStartBehavior = cssCustomPropertyBehaviorFactory(
+    "inline-start",
+    (designSystem: FASTDesignSystem) =>
+        direction(designSystem) === Direction.ltr ? "left" : "right",
+    FASTDesignSystemProvider.findProvider
+);
+
+/**
+ * Behavior to resolve and make available the inline-end CSS custom property.
+ *
+ * @remarks
+ * Replaces the inline-end value for the {@link https://developer.mozilla.org/en-US/docs/Web/CSS/float | float} property
+ * when the native value is not supported.
+ *
+ * @public
+ * @example
+ * ```ts
+ * import { css } from "@microsoft/fast-element";
+ * import { inlineEndBehavior } from "@microsoft/fast-components";
+ *
+ * css`
+ *   :host {
+ *     float: ${inlineEndBehavior.var};
+ *   }
+ * `.withBehaviors(inlineEndBehavior)
+ * ```
+ */
+export const inlineEndBehavior = cssCustomPropertyBehaviorFactory(
+    "inline-end",
+    (designSystem: FASTDesignSystem) =>
+        direction(designSystem) === Direction.ltr ? "right" : "left",
+    FASTDesignSystemProvider.findProvider
+);

packages/web-components/fast-components/src/styles/index.ts

@@ -2,3 +2,4 @@ export * from "./elevation";
 export * from "./patterns/index";
 export * from "./recipes";
 export * from "./size";
+export * from "./direction";

packages/web-components/fast-components/temp/api-report.md

@@ -15,6 +15,7 @@ import { Checkbox } from '@microsoft/fast-foundation';
 import { ColorRGBA64 } from '@microsoft/fast-colors';
 import { DesignSystemProvider } from '@microsoft/fast-foundation';
 import { Dialog } from '@microsoft/fast-foundation';
+import { Direction } from '@microsoft/fast-web-utilities';
 import { Divider } from '@microsoft/fast-foundation';
 import { Flipper } from '@microsoft/fast-foundation';
 import { Menu } from '@microsoft/fast-foundation';
@@ -266,6 +267,7 @@ export interface FASTDesignSystem {
     cornerRadius: number;
     density: number;
     designUnit: number;
+    direction: Direction;
     disabledOpacity: number;
     focusOutlineWidth: number;
     neutralDividerRestDelta: number;
@@ -393,6 +395,8 @@ export class FASTDesignSystemProvider extends DesignSystemProvider implements FA
     // (undocumented)
     designUnit: number;
     // (undocumented)
+    direction: Direction;
+    // (undocumented)
     disabledOpacity: number;
     // (undocumented)
     focusOutlineWidth: number;