feat: remove CSS behavior composition

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: janechu

change/@microsoft-fast-element-724d29c9-2cdc-4940-83c1-70ec5d64095e.json

@@ -1,6 +1,6 @@
 {
   "type": "major",
-  "comment": "Remove ElementStyles.withBehaviors and move runtime style toggles to the element controller.",
+  "comment": "Remove ElementStyles.withBehaviors, CSS style behaviors, and CSS bindings in fast-element.",
   "packageName": "@microsoft/fast-element",
   "email": "7559015+janechu@users.noreply.github.com",
   "dependentChangeType": "none"

packages/fast-element/DESIGN.md

@@ -272,7 +272,7 @@ See [ARCHITECTURE_UPDATES.md](./ARCHITECTURE_UPDATES.md) for more detail.
 
 **Files**: `src/styles/css.ts`, `src/styles/element-styles.ts`, `src/styles/css-directive.ts`
 
-The `css` tag (analogous to `html`) builds `ElementStyles` objects. During `ElementController.connect()`, styles are applied to the element's shadow root either via `adoptedStylesheets` (preferred) or an appended `<style>` node, depending on platform support. Styles can also contain dynamic `CSSDirective`s (e.g., CSS custom property bindings) that register as `HostBehavior`s and connect/disconnect alongside the element. Arbitrary runtime style toggling is handled through `ElementController.addStyles()` / `removeStyles()`; `ElementStyles` itself is a static container and does not expose a public behavior-mutation API.
+The `css` tag (analogous to `html`) builds `ElementStyles` objects. During `ElementController.connect()`, styles are applied to the element's shadow root either via `adoptedStylesheets` (preferred) or an appended `<style>` node, depending on platform support. `CSSDirective`s can contribute additional static CSS during template composition, but runtime CSS bindings and style-attached `HostBehavior`s are not supported. Arbitrary runtime style toggling is handled through `ElementController.addStyles()` / `removeStyles()`; `ElementStyles` itself is a static container.
 
 ---
 

packages/fast-element/MIGRATION.md

@@ -109,14 +109,19 @@ The `install-hydratable-view-templates.js` side-effect import is still available
 | Removed | Replacement |
 |---|---|
 | `ElementStyles.withBehaviors()` | Move the runtime condition into the element and call `this.$fastController.addStyles()` / `this.$fastController.removeStyles()` directly. |
+| `ElementStyles.behaviors` | Move any runtime behavior out of the stylesheet and into the element or controller lifecycle. |
+| CSS bindings in `css` (for example ``css`color: ${x => x.color}```) | Move the dynamic value into the element and update classes, attributes, or inline styles from element code. |
+| `CSSDirective.createCSS(add)` | Update directives to implement `createCSS()` and return only static CSS content. |
 
 ### Changed behavior
 
-- `css` and `css.partial()` still compose internal behaviors for CSS directives and CSS bindings.
-- `ElementStyles` remains a static style container; attaching arbitrary `HostBehavior`s is no longer part of the public API.
+- `css` and `css.partial()` no longer compose `HostBehavior`s.
+- `css` no longer accepts function or `Binding` interpolations.
+- `ElementStyles` is now a fully static style container.
 
 ### Migration steps
 
 1. Keep the conditional `ElementStyles` in a separate `css` value.
 2. Move the external listener or condition (for example `matchMedia()` or an app event subscription) into the element lifecycle.
 3. Call `this.$fastController.addStyles(styles)` when the condition is active and `this.$fastController.removeStyles(styles)` when it is inactive or during cleanup.
+4. If you previously interpolated bindings or behavior-producing directives into `css`, replace them with element state and standard DOM or controller updates.

packages/fast-element/README.md

@@ -64,9 +64,10 @@ When runtime state or external signals need to add or remove styles, create the
 `this.$fastController.addStyles()` / `this.$fastController.removeStyles()` from
 the element lifecycle or change handlers.
 
-`css` templates remain static style definitions. CSS directives and CSS bindings
-still compose their internal behaviors automatically, but `ElementStyles` no
-longer exposes a public API for attaching arbitrary behaviors.
+`css` templates remain static style definitions. Runtime CSS bindings and
+behavior-producing CSS directives are no longer supported; keep the condition on
+the element and toggle a separate `ElementStyles` instance through the
+controller when styles need to change.
 
 ## Prerendered Content Optimization
 

packages/fast-element/SIZES.md

@@ -4,14 +4,14 @@ Bundle sizes for `@microsoft/fast-element` exports.
 
 | Export | Minified | Gzip | Brotli |
 |--------|----------|------|--------|
-| CDN Rollup Bundle | 66.02 KB | 19.60 KB | 17.61 KB |
-| FASTElement | 25.31 KB | 7.94 KB | 7.17 KB |
+| CDN Rollup Bundle | 64.21 KB | 19.14 KB | 17.18 KB |
+| FASTElement | 24.90 KB | 7.84 KB | 7.09 KB |
 | Updates | 3.61 KB | 1.48 KB | 1.26 KB |
 | Observable | 8.12 KB | 2.99 KB | 2.66 KB |
 | observable | 8.16 KB | 3.00 KB | 2.68 KB |
 | attr | 3.55 KB | 1.42 KB | 1.19 KB |
 | children | 6.15 KB | 2.34 KB | 2.06 KB |
-| css | 11.41 KB | 4.11 KB | 3.70 KB |
+| css | 4.63 KB | 1.83 KB | 1.59 KB |
 | ref | 5.12 KB | 2.02 KB | 1.76 KB |
 | slotted | 5.94 KB | 2.28 KB | 2.00 KB |
 | volatile | 8.22 KB | 3.02 KB | 2.69 KB |

packages/fast-element/docs/api-report.api.md

@@ -11,9 +11,6 @@ export interface Accessor {
     setValue(source: any, value: any): void;
 }
 
-// @public
-export type AddBehavior = (behavior: HostBehavior<HTMLElement>) => void;
-
 // @public
 export type AddViewBehaviorFactory = (factory: ViewBehaviorFactory) => string;
 
@@ -185,30 +182,9 @@ export interface ContentView {
 // @public
 export const css: CSSTemplateTag;
 
-// @public
-export class CSSBindingDirective implements HostBehavior, Subscriber, CSSDirective, BindingDirective {
-    constructor(dataBinding: Binding, targetAspect: string);
-    addedCallback(controller: HostController<HTMLElement & {
-        $cssBindings: Map<CSSBindingDirective, CSSBindingEntry>;
-    }>): void;
-    connectedCallback(controller: HostController<HTMLElement & {
-        $cssBindings: Map<CSSBindingDirective, CSSBindingEntry>;
-    }>): void;
-    createCSS(add: AddBehavior): ComposableStyles;
-    // (undocumented)
-    readonly dataBinding: Binding;
-    // @internal
-    handleChange(_: any, observer: ExpressionObserver): void;
-    removedCallback(controller: HostController<HTMLElement & {
-        $cssBindings: Map<CSSBindingDirective, CSSBindingEntry>;
-    }>): void;
-    // (undocumented)
-    readonly targetAspect: string;
-}
-
 // @public
 export interface CSSDirective {
-    createCSS(add: AddBehavior): ComposableStyles;
+    createCSS(): ComposableStyles;
 }
 
 // @public
@@ -227,12 +203,12 @@ export interface CSSDirectiveDefinition<TType extends Constructable<CSSDirective
 }
 
 // @public
-export type CSSTemplateTag = (<TSource = any, TParent = any>(strings: TemplateStringsArray, ...values: CSSValue<TSource, TParent>[]) => ElementStyles) & {
-    partial<TSource = any, TParent = any>(strings: TemplateStringsArray, ...values: CSSValue<TSource, TParent>[]): CSSDirective;
+export type CSSTemplateTag = ((strings: TemplateStringsArray, ...values: CSSValue[]) => ElementStyles) & {
+    partial(strings: TemplateStringsArray, ...values: CSSValue[]): CSSDirective;
 };
 
 // @public
-export type CSSValue<TSource, TParent = any> = Expression<TSource, any, TParent> | Binding<TSource, any, TParent> | ComposableStyles | CSSDirective;
+export type CSSValue = ComposableStyles | CSSDirective;
 
 // @public
 export function customElement(nameOrDef: string | PartialFASTElementDefinition): (type: Constructable<HTMLElement>) => void;
@@ -346,7 +322,6 @@ export class ElementStyles {
     constructor(styles: ReadonlyArray<ComposableStyles>);
     // @internal (undocumented)
     addStylesTo(target: StyleTarget): void;
-    get behaviors(): ReadonlyArray<HostBehavior<HTMLElement>> | null;
     // @internal (undocumented)
     isAttachedTo(target: StyleTarget): boolean;
     static normalize(styles: ComposableStyles | ComposableStyles[] | undefined): ElementStyles | undefined;
@@ -1114,7 +1089,6 @@ export function when<TSource = any, TReturn = any, TParent = any>(condition: Exp
 // dist/dts/components/fast-element.d.ts:60:5 - (ae-forgotten-export) The symbol "define" needs to be exported by the entry point index.d.ts
 // dist/dts/components/fast-element.d.ts:61:5 - (ae-forgotten-export) The symbol "compose" needs to be exported by the entry point index.d.ts
 // dist/dts/components/fast-element.d.ts:62:5 - (ae-forgotten-export) The symbol "from" needs to be exported by the entry point index.d.ts
-// dist/dts/styles/css-binding-directive.d.ts:35:9 - (ae-forgotten-export) The symbol "CSSBindingEntry" needs to be exported by the entry point index.d.ts
 
 // (No @packageDocumentation comment for this package)