Rename schema hooks to transforms

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

Author: janechu

packages/fast-element/DECLARATIVE_DESIGN.md

@@ -77,7 +77,7 @@ When connected to the DOM it:
 2. Publishes a template when a matching FAST element definition requests one.
 3. Delegates parsing of the inner `<template>` tag to `TemplateParser`, which
    converts declarative bindings into FAST `ViewTemplate` strings and values.
-4. Runs definition-scoped schema hooks, such as `attributeMap()` and
+4. Runs definition-scoped schema transforms, such as `attributeMap()` and
    `observerMap()`, before returning the concrete `ViewTemplate`.
 
 ### `TemplateParser` — declarative HTML parser
@@ -196,7 +196,7 @@ packages/fast-element/
 │       ├── index.ts           # Declarative barrel export
 │       ├── interfaces.ts      # Message enum (error codes)
 │       ├── debug.ts           # Human-readable declarative debug messages
-│       ├── definition-options.ts # Definition-scoped schema hook storage
+│       ├── definition-options.ts # Definition-scoped schema transform storage
 │       ├── template.ts        # declarativeTemplate(), internal <f-template> publisher, lifecycle orchestration
 │       ├── template-bridge.ts # Registry/name bridge between definitions and publishers
 │       ├── template-parser.ts # TemplateParser — converts declarative HTML to ViewTemplate strings/values
@@ -214,22 +214,22 @@ packages/fast-element/
 ### Module dependency direction
 
 The default `declarativeTemplate()` path avoids importing optional map
-implementations. Map helpers attach schema hooks to the definition only when the
-consumer passes them as define extensions.
+implementations. Map helpers attach schema transforms to the definition only
+when the consumer passes them as define extensions.
 
 ```
-template.ts ──imports──▶ definition-options.ts (schema hook reads)
+template.ts ──imports──▶ definition-options.ts (schema transform reads)
 template.ts ──imports──▶ schema.ts (Schema)
-attribute-map.ts ──imports──▶ definition-options.ts (register attribute-map hook)
-observer-map.ts ──imports──▶ definition-options.ts (register observer-map hook)
+attribute-map.ts ──imports──▶ definition-options.ts (register attribute-map transform)
+observer-map.ts ──imports──▶ definition-options.ts (register observer-map transform)
 observer-map.ts ──imports──▶ schema.ts (Schema types)
 attribute-map.ts ──imports──▶ schema.ts (Schema types)
 utilities.ts ──imports──▶ schema.ts (schemaRegistry for cross-element $ref resolution)
 ```
 
-Schema hooks are sorted by priority and insertion order. `attributeMap()` uses a
-higher-priority slot than `observerMap()`, so generated attributes are available
-before observer mapping runs.
+Schema transforms are sorted by priority and insertion order. `attributeMap()`
+uses a higher-priority slot than `observerMap()`, so generated attributes are
+available before observer mapping runs.
 
 ---
 
@@ -332,7 +332,7 @@ via registry + name bridge"]
     G --> H[transformInnerHTML normalises HTML entities]
     H --> I["TemplateParser parses bindings/directives
 builds Schema, strings, values"]
-    I --> J["Run definition schema hooks
+    I --> J["Run definition schema transforms
 attributeMap before observerMap"]
     J --> K["ViewTemplate.create(strings, values)
 returned to definition"]
@@ -358,17 +358,18 @@ to the parser, keeping method signatures lean.
 
 ### Architecture
 
-The parsing pipeline is split across two classes plus definition-scoped hooks:
+The parsing pipeline is split across two classes plus definition-scoped
+transforms:
 
 - **Internal `<f-template>` publisher** (`template.ts`) — Custom element
   lifecycle, registry/name bridge registration, lifecycle callback dispatch, and
-  schema-hook execution. It is a native `HTMLElement`, not a `FASTElement`.
+  schema-transform execution. It is a native `HTMLElement`, not a `FASTElement`.
 - **`TemplateParser`** (`template-parser.ts`) — Synchronous template parser:
   converts declarative HTML into `strings`/`values` arrays for
   `ViewTemplate.create()`. Uses a `StringsAccumulator` to track the running
   previous-string in O(1) per binding site instead of O(N) `join("")` calls.
   Independently testable without DOM.
-- **Schema hooks** (`definition-options.ts`) — Extension-provided callbacks run
+- **Schema transforms** (`definition-options.ts`) — Extension-provided callbacks run
   after parsing and before `ViewTemplate.create()`. `attributeMap()` runs before
   `observerMap()`.
 
@@ -379,7 +380,7 @@ sequenceDiagram
     participant TP as TemplateParser
     participant U as utilities.ts
     participant S as Schema
-    participant Hooks as schema hooks
+    participant Transforms as schema transforms
 
     DOM->>FTE: connectedCallback()
     FTE->>FTE: register publisher with bridge
@@ -413,7 +414,7 @@ sequenceDiagram
         end
     end
     TP-->>FTE: { strings, values }
-    FTE->>Hooks: attributeMap(), then observerMap()
+    FTE->>Transforms: attributeMap(), then observerMap()
     FTE->>TP: parser.createTemplate(strings, values)
     FTE-->>DOM: return ViewTemplate to definition resolver
 ```
@@ -518,11 +519,11 @@ When an `ObserverMapConfig` with a `properties` key is provided, `ObserverMap.de
 
 ### AttributeMap and leaf bindings
 
-When `attributeMap()` is enabled, it registers a definition schema hook. After
-parsing, the hook constructs an `AttributeMap` implementation and calls
-`defineProperties()`. It iterates `Schema.getRootProperties()` and skips any
-property whose schema entry contains `properties`, `type`, or `anyOf` — keeping
-only plain leaf bindings. For each leaf:
+When `attributeMap()` is enabled, it registers a definition schema transform.
+After parsing, the transform constructs an `AttributeMap` implementation and
+calls `defineProperties()`. It iterates `Schema.getRootProperties()` and skips
+any property whose schema entry contains `properties`, `type`, or `anyOf` —
+keeping only plain leaf bindings. For each leaf:
 
 1. The schema key is used as the **JS property name**.
 2. The **HTML attribute name** depends on the `attribute-name-strategy`:
@@ -536,7 +537,7 @@ accessed via bracket notation (e.g. `element["foo-bar"]`). When using
 `"camelCase"`, property names are standard JS identifiers (e.g.
 `element.fooBar`).
 
-Because schema hooks are priority sorted, attribute mapping runs before observer
+Because schema transforms are priority sorted, attribute mapping runs before observer
 mapping when both extensions are supplied.
 
 ---
@@ -560,7 +561,7 @@ sequenceDiagram
     FTE->>FTE: bridge matches registry + name
     FTE->>PerEl: elementDidRegister('my-el')
     FTE->>PerEl: templateWillUpdate('my-el')
-    FTE->>FTE: parse template → schema → hooks → ViewTemplate
+    FTE->>FTE: parse template → schema → transforms → ViewTemplate
     FTE->>FER: return viewTemplate to resolver
     FER->>PerEl: templateDidUpdate('my-el')
     FER->>FER: customElements.define('my-el', MyElement)
@@ -608,7 +609,7 @@ tagged templates produce.
 |---|---|
 | `FASTElement` | Base class for user components; the internal `<f-template>` publisher is a native `HTMLElement` |
 | `FASTElementDefinition.register()` / template resolvers | Deferred element registration — element waits for its template |
-| `FASTElementExtension` | Extension callback mechanism used by `attributeMap()` and `observerMap()` to attach schema hooks before template resolution |
+| `FASTElementExtension` | Extension callback mechanism used by `attributeMap()` and `observerMap()` to attach schema transforms before template resolution |
 | `ViewTemplate.create(strings, values)` | Compiles the resolved strings/values arrays into a `ViewTemplate` |
 | `ElementController` | Automatically detects prerendered content (`isPrerendered`) and hydrates server-rendered DOM using `fe-b` comment/dataset markers via `template.hydrate()` |
 | `Observable.defineProperty()` | Defines observable root properties on element prototypes (ObserverMap) |

packages/fast-element/DESIGN.md

@@ -339,8 +339,8 @@ the imperative `html` API:
 - `TemplateParser` lowers declarative syntax to the same `strings` / `values`
   shape used by `ViewTemplate.create()`.
 - `attributeMap()` and `observerMap()` are `FASTElementExtension` factories.
-  They register schema hooks on the element definition, and those hooks run
-  after parsing in deterministic order (`attributeMap()` before
+  They register schema transforms on the element definition, and those
+  transforms run after parsing in deterministic order (`attributeMap()` before
   `observerMap()`).
 
 The `src/declarative.ts` entrypoint is pure at module evaluation time. Running a
@@ -557,7 +557,7 @@ src/
 │   ├── template.ts        # declarativeTemplate() and internal f-template publisher
 │   ├── template-parser.ts # Declarative HTML parser → ViewTemplate strings/values
 │   ├── schema.ts          # Binding schema builder + schemaRegistry
-│   ├── definition-options.ts # Definition-scoped declarative schema hooks
+│   ├── definition-options.ts # Definition-scoped declarative schema transforms
 │   ├── observer-map.ts    # observerMap() extension and proxy-backed observation helpers
 │   ├── attribute-map.ts   # attributeMap() extension and automatic @attr helpers
 │   ├── utilities.ts       # Declarative parsing and proxy utilities

packages/fast-element/SIZES.md

@@ -20,6 +20,6 @@ Bundle sizes for `@microsoft/fast-element` exports.
 | css | 2.43 KB | 1.00 KB | 911 B |
 | enableHydration | 43.23 KB | 13.21 KB | 11.88 KB |
 | ArrayObserver | 12.51 KB | 4.45 KB | 4.01 KB |
-| declarativeTemplate | 58.66 KB | 18.50 KB | 16.46 KB |
-| observerMap | 13.62 KB | 5.08 KB | 4.58 KB |
-| attributeMap | 15.52 KB | 5.48 KB | 4.94 KB |
+| declarativeTemplate | 58.67 KB | 18.50 KB | 16.46 KB |
+| observerMap | 13.63 KB | 5.08 KB | 4.59 KB |
+| attributeMap | 15.53 KB | 5.49 KB | 4.94 KB |

packages/fast-element/src/declarative/attribute-map.ts

@@ -5,7 +5,7 @@ import {
     trackLateAttributeDefinition,
 } from "../components/fast-definitions.js";
 import { Observable } from "../observation/observable.js";
-import { setDefinitionSchemaHook } from "./definition-options.js";
+import { setDefinitionSchemaTransform } from "./definition-options.js";
 import type { Schema } from "./schema.js";
 
 /**
@@ -28,8 +28,8 @@ export interface AttributeMapConfig {
     "attribute-name-strategy"?: "none" | "camelCase";
 }
 
-const attributeMapSchemaHookKey = "attribute-map";
-const attributeMapSchemaHookPriority = 0;
+const attributeMapSchemaTransformKey = "attribute-map";
+const attributeMapSchemaTransformPriority = 0;
 
 /**
  * Creates a FAST element extension that enables declarative attribute mapping
@@ -39,9 +39,9 @@ const attributeMapSchemaHookPriority = 0;
  */
 export function attributeMap(config: AttributeMapConfig = {}): FASTElementExtension {
     return definition => {
-        setDefinitionSchemaHook(
+        setDefinitionSchemaTransform(
             definition,
-            attributeMapSchemaHookKey,
+            attributeMapSchemaTransformKey,
             ({ definition, schema }) => {
                 new AttributeMap(
                     definition.type.prototype,
@@ -50,7 +50,7 @@ export function attributeMap(config: AttributeMapConfig = {}): FASTElementExtens
                     config,
                 ).defineProperties();
             },
-            attributeMapSchemaHookPriority,
+            attributeMapSchemaTransformPriority,
         );
     };
 }

packages/fast-element/src/declarative/definition-options.ts

@@ -1,58 +1,60 @@
 import type { FASTElementDefinition } from "../components/fast-definitions.js";
 import type { Schema } from "./schema.js";
 
-const definitionSchemaHooksKey = Symbol("definitionSchemaHooks");
+const definitionSchemaTransformsKey = Symbol("definitionSchemaTransforms");
 
-let schemaHookOrder = 0;
+let schemaTransformOrder = 0;
 
-type FASTElementDefinitionWithSchemaHooks = FASTElementDefinition & {
-    [definitionSchemaHooksKey]?: DefinitionSchemaHookRecord[];
+type FASTElementDefinitionWithSchemaTransforms = FASTElementDefinition & {
+    [definitionSchemaTransformsKey]?: DefinitionSchemaTransformRecord[];
 };
 
-interface DefinitionSchemaHookRecord {
+interface DefinitionSchemaTransformRecord {
     key: string;
-    hook: DeclarativeSchemaHook;
+    transform: DeclarativeSchemaTransform;
     order: number;
     priority: number;
 }
 
-export interface DeclarativeSchemaHookContext {
+export interface DeclarativeSchemaTransformContext {
     definition: FASTElementDefinition;
     schema: Schema;
 }
 
-export type DeclarativeSchemaHook = (context: DeclarativeSchemaHookContext) => void;
+export type DeclarativeSchemaTransform = (
+    context: DeclarativeSchemaTransformContext,
+) => void;
 
-export function setDefinitionSchemaHook(
+export function setDefinitionSchemaTransform(
     definition: FASTElementDefinition,
     key: string,
-    hook: DeclarativeSchemaHook,
+    transform: DeclarativeSchemaTransform,
     priority: number,
 ): void {
-    const target = definition as FASTElementDefinitionWithSchemaHooks;
-    const hooks = (target[definitionSchemaHooksKey] ??= []);
-    const existingIndex = hooks.findIndex(record => record.key === key);
+    const target = definition as FASTElementDefinitionWithSchemaTransforms;
+    const transforms = (target[definitionSchemaTransformsKey] ??= []);
+    const existingIndex = transforms.findIndex(record => record.key === key);
 
     if (existingIndex !== -1) {
-        hooks.splice(existingIndex, 1);
+        transforms.splice(existingIndex, 1);
     }
 
-    hooks.push({
+    transforms.push({
         key,
-        hook,
-        order: schemaHookOrder++,
+        transform,
+        order: schemaTransformOrder++,
         priority,
     });
 
-    hooks.sort((a, b) => a.priority - b.priority || a.order - b.order);
+    transforms.sort((a, b) => a.priority - b.priority || a.order - b.order);
 }
 
-export function getDefinitionSchemaHooks(
+export function getDefinitionSchemaTransforms(
     definition?: FASTElementDefinition,
-): readonly DeclarativeSchemaHook[] {
-    const hooks = (definition as FASTElementDefinitionWithSchemaHooks | undefined)?.[
-        definitionSchemaHooksKey
-    ];
+): readonly DeclarativeSchemaTransform[] {
+    const transforms = (
+        definition as FASTElementDefinitionWithSchemaTransforms | undefined
+    )?.[definitionSchemaTransformsKey];
 
-    return hooks?.map(record => record.hook) ?? [];
+    return transforms?.map(record => record.transform) ?? [];
 }

packages/fast-element/src/declarative/observer-map.ts

@@ -1,6 +1,6 @@
 import type { FASTElementExtension } from "../components/fast-definitions.js";
 import { Observable } from "../observation/observable.js";
-import { setDefinitionSchemaHook } from "./definition-options.js";
+import { setDefinitionSchemaTransform } from "./definition-options.js";
 import type { JSONSchema, Schema } from "./schema.js";
 import { assignObservables, deepMerge } from "./utilities.js";
 
@@ -46,8 +46,8 @@ export interface ObserverMapConfig {
     };
 }
 
-const observerMapSchemaHookKey = "observer-map";
-const observerMapSchemaHookPriority = 1;
+const observerMapSchemaTransformKey = "observer-map";
+const observerMapSchemaTransformPriority = 1;
 
 /**
  * Creates a FAST element extension that enables declarative observer mapping
@@ -57,17 +57,17 @@ const observerMapSchemaHookPriority = 1;
  */
 export function observerMap(config: ObserverMapConfig = {}): FASTElementExtension {
     return definition => {
-        setDefinitionSchemaHook(
+        setDefinitionSchemaTransform(
             definition,
-            observerMapSchemaHookKey,
+            observerMapSchemaTransformKey,
             ({ definition, schema }) => {
                 new ObserverMap(
                     definition.type.prototype,
                     schema,
                     config,
                 ).defineProperties();
             },
-            observerMapSchemaHookPriority,
+            observerMapSchemaTransformPriority,
         );
     };
 }

packages/fast-element/src/declarative/template.ts

@@ -5,7 +5,7 @@ import type {
 } from "../components/fast-definitions.js";
 import { FAST } from "../platform.js";
 import type { ElementViewTemplate } from "../templating/template.js";
-import { getDefinitionSchemaHooks } from "./definition-options.js";
+import { getDefinitionSchemaTransforms } from "./definition-options.js";
 import { Message } from "./interfaces.js";
 import { ensureDeclarativeRuntime } from "./runtime.js";
 import { Schema } from "./schema.js";
@@ -203,8 +203,8 @@ class FTemplateElement extends HTMLElement implements TemplatePublisher {
         const parser = new TemplateParser();
         const { strings, values } = parser.parse(innerHTML, schema);
 
-        for (const hook of getDefinitionSchemaHooks(definition)) {
-            hook({ definition, schema });
+        for (const transform of getDefinitionSchemaTransforms(definition)) {
+            transform({ definition, schema });
         }
 
         return parser.createTemplate(strings, values);