@microsoft/fast-build 0.4.0 → 0.6.0

package/README.md

@@ -25,7 +25,7 @@ import { render } from '@microsoft/fast-build';
 
 ## CLI usage
 
-Once installed, the `fast` binary is available. Use the `build` subcommand to render an HTML template with a JSON state file:
+Once installed, the `fast` binary is available. Use the `build` subcommand to render an HTML template with an optional JSON state file:
 
 ```shell
 fast build [options]
@@ -36,10 +36,10 @@ fast build [options]
 | Option | Default | Description |
 |---|---|---|
 | `--entry="<path>"` | `index.html` | Entry HTML template to render |
-| `--state="<path>"` | `state.json` | JSON file containing the template state |
+| `--state="<path>"` | `{}` when omitted | JSON file containing the template state. If omitted, no state file is loaded and rendering uses an empty state object. If `--state` is provided, the file must exist. |
 | `--output="<path>"` | `output.html` | Where to write the rendered HTML |
 | `--templates="<glob>"` | _(none)_ | Glob pattern(s) for custom element template HTML files. Separate multiple patterns with commas. A warning is printed if not provided or if no files match a pattern. |
-| `--attribute-name-strategy="<strategy>"` | `none` | Strategy for mapping HTML attribute names to state property names on custom elements. `"none"` preserves dashes (e.g. `foo-bar` → `foo-bar`). `"camelCase"` converts dashes to camelCase (e.g. `foo-bar` → `fooBar`). See [Attribute name strategy](#attribute-name-strategy). |
+| `--attribute-name-strategy="<strategy>"` | `camelCase` | Strategy for mapping HTML attribute names to state property names on custom elements. `"camelCase"` converts dashes to camelCase (e.g. `foo-bar` → `fooBar`). `"none"` preserves dashes (e.g. `foo-bar` → `foo-bar`). See [Attribute name strategy](#attribute-name-strategy). |
 | `--config="<path>"` | `fast-build.config.json` | Path to a JSON configuration file. If omitted, `fast-build.config.json` in the current directory is used when present. CLI arguments take precedence over config values. See [Configuration file](#configuration-file). |
 
 ### Example
@@ -81,6 +81,18 @@ Produces `output.html`:
 </html>
 ```
 
+### Missing or omitted state
+
+State is optional. When `--state` is omitted and no `state` path is provided by config, `fast build` does not look for `state.json`; rendering uses an empty object (`{}`). An explicit `--state` path, or a `state` path from config, must exist or the command exits with an error.
+
+> **Breaking change:** Earlier versions implicitly loaded `state.json` from the current working directory when `--state` was omitted. To use a state file, pass `--state=state.json` or set `"state": "state.json"` in `fast-build.config.json`.
+
+When a binding value is not present in state:
+
+- Content bindings render nothing, including unresolved dot paths: `<p>{{foo.bar}}</p>` becomes `<p></p>`.
+- Attribute bindings omit the entire attribute, including unresolved dot paths: `<div class="{{foo.bar}}"></div>` becomes `<div></div>`.
+- `<f-repeat>` treats a missing list binding, including unresolved dot paths, as an empty array and renders zero iterations. If the binding is present but is not an array, rendering still errors.
+
 ### Custom element templates
 
 Pass a glob pattern (or comma-separated list of patterns) to `--templates` to expand custom elements into [Declarative Shadow DOM](https://developer.chrome.com/docs/css-ui/declarative-shadow-dom):
@@ -107,14 +119,16 @@ Template files must use the following format:
 
 If an `<f-template>` element has no `name` attribute, a warning is printed and it is ignored. Exact file paths (no wildcards) are also accepted as patterns, making it possible to register a single template file.
 
+Any `shadowroot*` attributes on `<f-template>` are forwarded to the rendered Declarative Shadow DOM `<template>`. The CLI normalizes `shadowrootmode` and legacy `shadowroot` for compatibility: when neither has a non-empty value, it emits `shadowrootmode="open" shadowroot="open"`; when exactly one has a non-empty value, that value is mirrored to the other; when both have explicit non-empty values, both are preserved as authored, even if they conflict.
+
 ### Attribute name strategy
 
 The `--attribute-name-strategy` option controls how HTML attribute names on custom elements are mapped to state property names in their shadow templates.
 
 | Strategy | Behaviour | Template binding |
 |---|---|---|
-| `none` (default) | Attribute names lowercased as-is, dashes preserved | `foo-bar` → `{{foo-bar}}` |
-| `camelCase` | Dashed attribute names converted to camelCase | `foo-bar` → `{{fooBar}}` |
+| `camelCase` (default) | Dashed attribute names converted to camelCase | `foo-bar` → `{{fooBar}}` |
+| `none` | Attribute names lowercased as-is, dashes preserved | `foo-bar` → `{{foo-bar}}` |
 
 The `camelCase` strategy only affects "plain" custom element attributes. It does **not** change:
 - `data-*` attributes (always use `dataset.*` grouping)
@@ -153,7 +167,7 @@ fast build --config=configs/my-build.json
 
 **Path resolution:** File paths in the config file (`entry`, `state`, `output`, `templates`) are resolved relative to the config file's directory, not the current working directory. This ensures the config works correctly regardless of where the CLI is invoked.
 
-All keys are optional. Only the following keys are allowed: `entry`, `state`, `output`, `templates`, `attribute-name-strategy`. Unknown keys or non-string values produce an error.
+All keys are optional. Only the following keys are allowed: `entry`, `state`, `output`, `templates`, `attribute-name-strategy`. Unknown keys or non-string values produce an error. If `state` is omitted, rendering uses `{}`; if `state` is present, the referenced file must exist.
 
 ## Template syntax
 

package/bin/fast.js

@@ -218,24 +218,28 @@ function staticPrefixDir(pattern) {
 
 /**
  * Parse all `<f-template>` elements from an HTML string using the WASM module.
- * Returns [{name, content}] for templates that have a `name` attribute.
+ * Returns template metadata for templates that have a `name` attribute.
  * Emits a warning to stderr for any `<f-template>` without a `name`.
  * @param {string} html
  * @param {string} filePath - used in warning messages
  * @param {object} wasm - the loaded WASM module
- * @returns {{ name: string, content: string }[]}
+ * @returns {{ name: string, content: string, shadowrootAttributes: { name: string, value: string | null }[] }[]}
  */
 function parseFTemplates(html, filePath, wasm) {
-    /** @type {{ name: string | null, content: string }[]} */
+    /** @type {{ name: string | null, content: string, shadowrootAttributes?: { name: string, value: string | null }[] }[]} */
     const parsed = JSON.parse(wasm.parse_f_templates(html));
     const results = [];
-    for (const { name, content } of parsed) {
+    for (const { name, content, shadowrootAttributes } of parsed) {
         if (name === null) {
             process.stderr.write(
                 `Warning: <f-template> without a 'name' attribute in '${filePath}': ${content.trim()}\n`
             );
         } else {
-            results.push({ name, content });
+            results.push({
+                name,
+                content,
+                shadowrootAttributes: shadowrootAttributes || [],
+            });
         }
     }
     return results;
@@ -248,7 +252,7 @@ function parseFTemplates(html, filePath, wasm) {
  * Warns (but does not error) if the base directory does not exist.
  * @param {string} pattern
  * @param {object} wasm - the loaded WASM module
- * @returns {{ name: string, content: string }[]}
+ * @returns {{ name: string, content: string, shadowrootAttributes: { name: string, value: string | null }[] }[]}
  */
 function resolvePattern(pattern, wasm) {
     const baseDir = staticPrefixDir(pattern);
@@ -262,8 +266,8 @@ function resolvePattern(pattern, wasm) {
         if (globMatch(pattern, file)) {
             const html = fs.readFileSync(file, "utf8");
             const templates = parseFTemplates(html, file, wasm);
-            for (const { name, content } of templates) {
-                results.push({ name, content });
+            for (const { name, content, shadowrootAttributes } of templates) {
+                results.push({ name, content, shadowrootAttributes });
             }
         }
     }
@@ -278,7 +282,10 @@ async function runBuild(args) {
     const templatesArg = resolveOption(args, config, configDir, "templates");
     const output = resolveOption(args, config, configDir, "output", "output.html");
     const entry = resolveOption(args, config, configDir, "entry", "index.html");
-    const stateFile = resolveOption(args, config, configDir, "state", "state.json");
+    const stateFile = resolveOption(args, config, configDir, "state");
+    const stateWasProvided =
+        Object.prototype.hasOwnProperty.call(args, "state") ||
+        Object.prototype.hasOwnProperty.call(config, "state");
     const attributeNameStrategy = resolveOption(args, config, configDir, "attribute-name-strategy");
 
     if (attributeNameStrategy && attributeNameStrategy !== "none" && attributeNameStrategy !== "camelCase") {
@@ -306,13 +313,13 @@ async function runBuild(args) {
                     `Warning: No template files found for pattern "${pattern}".\n`
                 );
             }
-            for (const { name, content } of matches) {
+            for (const { name, content, shadowrootAttributes } of matches) {
                 if (name in templatesMap) {
                     process.stderr.write(
                         `Warning: Duplicate template name "${name}" — later file overwrites earlier.\n`
                     );
                 }
-                templatesMap[name] = content;
+                templatesMap[name] = { content, shadowrootAttributes };
             }
         }
     }
@@ -324,18 +331,28 @@ async function runBuild(args) {
     }
     const entryContent = fs.readFileSync(entry, "utf8");
 
-    // Read state file
-    if (!fs.existsSync(stateFile)) {
-        process.stderr.write(`Error: State file "${stateFile}" not found.\n`);
-        process.exit(1);
+    // Read state only when explicitly provided; omitted state is handled by WASM as `{}`.
+    let stateContent;
+    if (stateWasProvided) {
+        if (stateFile === undefined || stateFile === "" || !fs.existsSync(stateFile)) {
+            const stateFileLabel =
+                stateFile === undefined || stateFile === ""
+                    ? "(no path provided)"
+                    : `"${stateFile}"`;
+            process.stderr.write(`Error: State file ${stateFileLabel} not found.\n`);
+            process.exit(1);
+        }
+        stateContent = fs.readFileSync(stateFile, "utf8");
     }
-    const stateContent = fs.readFileSync(stateFile, "utf8");
 
     // Render
     let rendered;
     if (Object.keys(templatesMap).length > 0) {
         rendered = wasm.render_entry_with_templates(
-            entryContent, JSON.stringify(templatesMap), stateContent, attributeNameStrategy || "none"
+            entryContent,
+            JSON.stringify(templatesMap),
+            stateContent,
+            attributeNameStrategy || "",
         );
     } else {
         rendered = wasm.render(entryContent, stateContent);
@@ -356,10 +373,11 @@ async function main() {
             '                         Separate multiple patterns with commas.\n' +
             '  --output="output.html" Output file path (default: output.html)\n' +
             '  --entry="index.html"   Entry HTML template file (default: index.html)\n' +
-            '  --state="state.json"   State JSON file (default: state.json)\n' +
-            '  --attribute-name-strategy="none"\n' +
+            '  --state="state.json"   State JSON file. If omitted, rendering uses\n' +
+            '                         an empty state object.\n' +
+            '  --attribute-name-strategy="camelCase"\n' +
             '                         Strategy for mapping attribute names to property names.\n' +
-            '                         "none" (default) or "camelCase".\n' +
+            '                         "camelCase" (default) or "none".\n' +
             '  --config="<path>"      Path to a fast-build config JSON file.\n' +
             '                         Defaults to "fast-build.config.json" in the\n' +
             '                         current directory if it exists. File paths in\n' +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microsoft/fast-build",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "CLI and Node.js API for server-side rendering of FAST declarative HTML templates.",
   "author": {
     "name": "Microsoft",

package/wasm/microsoft_fast_build.d.ts

@@ -3,38 +3,46 @@
 
 /**
  * Parse all `<f-template>` elements from an HTML string.
- * Returns a JSON array of `{"name": string | null, "content": string}` objects,
+ * Returns a JSON array of template metadata objects,
  * one per `<f-template>` element found. `name` is `null` when the element has
  * no `name` attribute.
  */
 export function parse_f_templates(html: string): string;
 
 /**
- * Render a FAST HTML template with a JSON state string.
+ * Render a FAST HTML template with an optional JSON state string.
+ * Omitted state is treated as an empty object.
  * Returns the rendered HTML or throws a JavaScript error.
  */
-export function render(entry: string, state: string): string;
+export function render(entry: string, state?: string | null): string;
 
 /**
- * Render the top-level **entry HTML** with custom element templates and a JSON state string.
- * Custom elements found at the root level of `entry` receive the full root state rather than
- * building their child state from HTML attributes. For `{{binding}}` attributes on root custom
+ * Render the top-level **entry HTML** with custom element templates and an optional JSON state string.
+ * Omitted state is treated as an empty object.
+ * Custom elements found at the root level of `entry` build child state from the full root
+ * state with HTML attributes overlaid on top. For `{{binding}}` attributes on root custom
  * elements, primitive results (`string`, `number`, and `bool`) are preserved in the rendered
- * output, while non-primitive values (`array`, `object`, `null`) are stripped.
+ * output, while missing and non-primitive values (`array`, `object`, `null`) are stripped.
  *
- * `templates_json` is a JSON object mapping element names to their HTML template strings.
- * `attribute_name_strategy` controls attribute-to-property mapping: `"none"` (default)
- * or `"camelCase"`. Pass an empty string for the default.
+ * `templates_json` is a JSON object mapping element names to their HTML template strings,
+ * e.g. `{"my-button": "<template>...</template>"}`, or template metadata objects.
+ * `attribute_name_strategy` controls attribute-to-property mapping: `"camelCase"` (default)
+ * or `"none"`. Pass an empty string for the default.
  * Returns the rendered HTML or throws a JavaScript error.
  */
-export function render_entry_with_templates(entry: string, templates_json: string, state: string, attribute_name_strategy: string): string;
+export function render_entry_with_templates(entry: string, templates_json: string, state?: string | null, attribute_name_strategy?: string | null): string;
 
 /**
- * Render a FAST HTML template with custom element templates and a JSON state string.
+ * Render a FAST HTML template with custom element templates and an optional JSON state string.
+ * Omitted state is treated as an empty object.
+ *
+ * This preserves the original non-entry rendering semantics for this export.
+ * Use `render_entry_with_templates` for top-level entry HTML rendering.
+ *
  * `templates_json` is a JSON object mapping element names to their HTML template strings,
- * e.g. `{"my-button": "<template>...</template>"}`.
- * `attribute_name_strategy` controls attribute-to-property mapping: `"none"` (default)
- * or `"camelCase"`. Pass an empty string for the default.
+ * e.g. `{"my-button": "<template>...</template>"}`, or template metadata objects.
+ * `attribute_name_strategy` controls attribute-to-property mapping: `"camelCase"` (default)
+ * or `"none"`. Pass an empty string for the default.
  * Returns the rendered HTML or throws a JavaScript error.
  */
-export function render_with_templates(entry: string, templates_json: string, state: string, attribute_name_strategy: string): string;
+export function render_with_templates(entry: string, templates_json: string, state?: string | null, attribute_name_strategy?: string | null): string;

package/wasm/microsoft_fast_build.js

@@ -2,7 +2,7 @@
 
 /**
  * Parse all `<f-template>` elements from an HTML string.
- * Returns a JSON array of `{"name": string | null, "content": string}` objects,
+ * Returns a JSON array of template metadata objects,
  * one per `<f-template>` element found. `name` is `null` when the element has
  * no `name` attribute.
  * @param {string} html
@@ -25,10 +25,11 @@ function parse_f_templates(html) {
 exports.parse_f_templates = parse_f_templates;
 
 /**
- * Render a FAST HTML template with a JSON state string.
+ * Render a FAST HTML template with an optional JSON state string.
+ * Omitted state is treated as an empty object.
  * Returns the rendered HTML or throws a JavaScript error.
  * @param {string} entry
- * @param {string} state
+ * @param {string | null} [state]
  * @returns {string}
  */
 function render(entry, state) {
@@ -37,8 +38,8 @@ function render(entry, state) {
     try {
         const ptr0 = passStringToWasm0(entry, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
         const len0 = WASM_VECTOR_LEN;
-        const ptr1 = passStringToWasm0(state, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
-        const len1 = WASM_VECTOR_LEN;
+        var ptr1 = isLikeNone(state) ? 0 : passStringToWasm0(state, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        var len1 = WASM_VECTOR_LEN;
         const ret = wasm.render(ptr0, len0, ptr1, len1);
         var ptr3 = ret[0];
         var len3 = ret[1];
@@ -56,20 +57,22 @@ function render(entry, state) {
 exports.render = render;
 
 /**
- * Render the top-level **entry HTML** with custom element templates and a JSON state string.
- * Custom elements found at the root level of `entry` receive the full root state rather than
- * building their child state from HTML attributes. For `{{binding}}` attributes on root custom
+ * Render the top-level **entry HTML** with custom element templates and an optional JSON state string.
+ * Omitted state is treated as an empty object.
+ * Custom elements found at the root level of `entry` build child state from the full root
+ * state with HTML attributes overlaid on top. For `{{binding}}` attributes on root custom
  * elements, primitive results (`string`, `number`, and `bool`) are preserved in the rendered
- * output, while non-primitive values (`array`, `object`, `null`) are stripped.
+ * output, while missing and non-primitive values (`array`, `object`, `null`) are stripped.
  *
- * `templates_json` is a JSON object mapping element names to their HTML template strings.
- * `attribute_name_strategy` controls attribute-to-property mapping: `"none"` (default)
- * or `"camelCase"`. Pass an empty string for the default.
+ * `templates_json` is a JSON object mapping element names to their HTML template strings,
+ * e.g. `{"my-button": "<template>...</template>"}`, or template metadata objects.
+ * `attribute_name_strategy` controls attribute-to-property mapping: `"camelCase"` (default)
+ * or `"none"`. Pass an empty string for the default.
  * Returns the rendered HTML or throws a JavaScript error.
  * @param {string} entry
  * @param {string} templates_json
- * @param {string} state
- * @param {string} attribute_name_strategy
+ * @param {string | null} [state]
+ * @param {string | null} [attribute_name_strategy]
  * @returns {string}
  */
 function render_entry_with_templates(entry, templates_json, state, attribute_name_strategy) {
@@ -80,10 +83,10 @@ function render_entry_with_templates(entry, templates_json, state, attribute_nam
         const len0 = WASM_VECTOR_LEN;
         const ptr1 = passStringToWasm0(templates_json, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
         const len1 = WASM_VECTOR_LEN;
-        const ptr2 = passStringToWasm0(state, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
-        const len2 = WASM_VECTOR_LEN;
-        const ptr3 = passStringToWasm0(attribute_name_strategy, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
-        const len3 = WASM_VECTOR_LEN;
+        var ptr2 = isLikeNone(state) ? 0 : passStringToWasm0(state, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        var len2 = WASM_VECTOR_LEN;
+        var ptr3 = isLikeNone(attribute_name_strategy) ? 0 : passStringToWasm0(attribute_name_strategy, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        var len3 = WASM_VECTOR_LEN;
         const ret = wasm.render_entry_with_templates(ptr0, len0, ptr1, len1, ptr2, len2, ptr3, len3);
         var ptr5 = ret[0];
         var len5 = ret[1];
@@ -101,16 +104,21 @@ function render_entry_with_templates(entry, templates_json, state, attribute_nam
 exports.render_entry_with_templates = render_entry_with_templates;
 
 /**
- * Render a FAST HTML template with custom element templates and a JSON state string.
+ * Render a FAST HTML template with custom element templates and an optional JSON state string.
+ * Omitted state is treated as an empty object.
+ *
+ * This preserves the original non-entry rendering semantics for this export.
+ * Use `render_entry_with_templates` for top-level entry HTML rendering.
+ *
  * `templates_json` is a JSON object mapping element names to their HTML template strings,
- * e.g. `{"my-button": "<template>...</template>"}`.
- * `attribute_name_strategy` controls attribute-to-property mapping: `"none"` (default)
- * or `"camelCase"`. Pass an empty string for the default.
+ * e.g. `{"my-button": "<template>...</template>"}`, or template metadata objects.
+ * `attribute_name_strategy` controls attribute-to-property mapping: `"camelCase"` (default)
+ * or `"none"`. Pass an empty string for the default.
  * Returns the rendered HTML or throws a JavaScript error.
  * @param {string} entry
  * @param {string} templates_json
- * @param {string} state
- * @param {string} attribute_name_strategy
+ * @param {string | null} [state]
+ * @param {string | null} [attribute_name_strategy]
  * @returns {string}
  */
 function render_with_templates(entry, templates_json, state, attribute_name_strategy) {
@@ -121,10 +129,10 @@ function render_with_templates(entry, templates_json, state, attribute_name_stra
         const len0 = WASM_VECTOR_LEN;
         const ptr1 = passStringToWasm0(templates_json, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
         const len1 = WASM_VECTOR_LEN;
-        const ptr2 = passStringToWasm0(state, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
-        const len2 = WASM_VECTOR_LEN;
-        const ptr3 = passStringToWasm0(attribute_name_strategy, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
-        const len3 = WASM_VECTOR_LEN;
+        var ptr2 = isLikeNone(state) ? 0 : passStringToWasm0(state, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        var len2 = WASM_VECTOR_LEN;
+        var ptr3 = isLikeNone(attribute_name_strategy) ? 0 : passStringToWasm0(attribute_name_strategy, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        var len3 = WASM_VECTOR_LEN;
         const ret = wasm.render_with_templates(ptr0, len0, ptr1, len1, ptr2, len2, ptr3, len3);
         var ptr5 = ret[0];
         var len5 = ret[1];
@@ -178,6 +186,10 @@ function getUint8ArrayMemory0() {
     return cachedUint8ArrayMemory0;
 }
 
+function isLikeNone(x) {
+    return x === undefined || x === null;
+}
+
 function passStringToWasm0(arg, malloc, realloc) {
     if (realloc === undefined) {
         const buf = cachedTextEncoder.encode(arg);