@microsoft/fast-html 1.0.0-alpha.1

package/CHANGELOG.json

@@ -0,0 +1,26 @@
+{
+  "name": "@microsoft/fast-html",
+  "entries": [
+    {
+      "date": "Mon, 24 Mar 2025 18:06:22 GMT",
+      "version": "1.0.0-alpha.1",
+      "tag": "@microsoft/fast-html_v1.0.0-alpha.1",
+      "comments": {
+        "prerelease": [
+          {
+            "author": "7559015+janechu@users.noreply.github.com",
+            "package": "@microsoft/fast-html",
+            "commit": "9740d42f280b335b0b5b45c5fe63d1251bae263e",
+            "comment": "Update private flag for initial release"
+          },
+          {
+            "author": "beachball",
+            "package": "@microsoft/fast-html",
+            "comment": "Bump @microsoft/fast-element to v2.2.0",
+            "commit": "not available"
+          }
+        ]
+      }
+    }
+  ]
+}

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Change Log - @microsoft/fast-html
+
+<!-- This log was last generated on Mon, 24 Mar 2025 18:06:22 GMT and should not be manually modified. -->
+
+<!-- Start content -->
+
+## 1.0.0-alpha.1
+
+Mon, 24 Mar 2025 18:06:22 GMT
+
+### Changes
+
+- Update private flag for initial release (7559015+janechu@users.noreply.github.com)
+- Bump @microsoft/fast-element to v2.2.0

package/README.md

@@ -0,0 +1,129 @@
+# FAST HTML
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![npm version](https://badge.fury.io/js/%40microsoft%2Ffast-html.svg)](https://badge.fury.io/js/%40microsoft%2Ffast-html)
+
+The `@microsoft/fast-html` package contains a method to interpret FAST declarative HTML syntax as a template for a FAST web component.
+
+## Installation
+
+### From NPM
+
+To install the latest `fast-html` library using `npm`:
+
+```shell
+npm install --save @microsoft/fast-html
+```
+
+## Declarative HTML
+
+### Usage
+
+In your JS bundle you will need to include the `@microsoft/fast-html` package:
+
+```typescript
+import { TemplateElement } from "@microsoft/fast-html";
+
+TemplateElement.define({
+    name: "f-template",
+});
+```
+
+This will include the `<f-template>` custom element and all logic for interpreting the declarative HTML syntax for a FAST web component.
+
+The template must be wrapped in `<f-template name="[custom-element-name]"><template>[template logic]</template></f-template>` with a `name` attribute for the custom elements name, and the template logic inside.
+
+Example:
+```html
+<my-custom-element greeting="Hello world">
+    <template shadowrootmode="open">
+        Hello world
+    </template>
+</my-custom-element>
+<f-template name="my-custom-element">
+    <template>{{greeting}}</template>
+</f-template>
+```
+
+### Syntax
+
+All bindings use a handlebars syntax.
+
+#### Content binding
+
+```html
+{{text}}
+```
+
+#### Event binding
+
+Event bindings must include the `()` as well as being preceeded by `@` in keeping with `@microsoft/fast-element` tagged template `html` syntax.
+
+```html
+<button @click="{{handleClick()}}"></button>
+```
+
+#### Directives
+
+Directives are assumed to be either an attribute directive or a directive that also serves a template. Both are prepended by `f-`. The logic of these directives and what their use cases are is explained in the [FAST html documentation](https://fast.design/docs/getting-started/html-directives).
+
+Attribute directives include:
+- **slotted**
+
+    Example:
+    ```html
+    <slot f-slotted="{{slottedNodes}}"></slot>
+    ```
+
+- **children**
+
+    Example:
+    ```html
+    <ul f-children="{{listItems}}"><f-repeat value="{{item in list}}"><li>{{item}}</li></f-repeat></ul>
+    ```
+
+- **ref**
+
+    Example:
+    ```html
+    <video f-ref="{{video}}"></video>
+    ```
+
+Template directives include:
+- **when**
+
+    Example:
+    ```html
+    <f-when value="{{show}}">Hello world</f-when>
+    ```
+
+- **repeat**
+
+    Example:
+    ```html
+    <ul><f-repeat value="{{item in list}}"><li>{{item}}</li></f-repeat></ul>
+    ```
+
+- **partial & apply**
+
+    These directives are new to the declarative HTML model and allow for the ability to declare a `partial` directive containing a template partial which can then be referenced by an `apply` directive.
+
+    Example:
+    ```html
+    <f-partial id="test">
+        <ul>
+            <f-repeat value="{{item in items}}">
+                <li>{{item.text}}<f-apply partial="test" value="{{item.items}}"></f-apply></li>
+            </f-repeat>
+        </ul>
+    </f-partial>
+    <f-apply partial="test" value="{{items}}"></f-apply>
+    ```
+
+### Writing Components
+
+When writing components with the intention of using the declarative HTML syntax, it is imperative that components are written with styling and rendering of the component to be less reliant on any JavaScript state management. An example of this is relying on `elementInterals` state to style a component.
+
+## Acknowledgements
+
+This project has been heavily inspired by [Handlebars](https://handlebarsjs.com/) and [Vue.js](https://vuejs.org/).

package/docs/api-report.api.md

@@ -0,0 +1,18 @@
+## API Report File for "@microsoft/fast-html"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+
+import { FASTElement } from '@microsoft/fast-element';
+
+// @public
+export class TemplateElement extends FASTElement {
+    // (undocumented)
+    connectedCallback(): void;
+    name?: string;
+}
+
+// (No @packageDocumentation comment for this package)
+
+```

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "@microsoft/fast-html",
+  "version": "1.0.0-alpha.1",
+  "type": "module",
+  "author": {
+    "name": "Microsoft",
+    "url": "https://discord.gg/FcSNfg4"
+  },
+  "homepage": "https://www.fast.design/",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Microsoft/fast.git",
+    "directory": "packages/web-components/fast-html"
+  },
+  "bugs": {
+    "url": "https://github.com/Microsoft/fast/issues/new/choose"
+  },
+  "scripts": {
+    "clean": "tsc -b --clean src",
+    "clean:dist": "node ../../../build/clean.js dist",
+    "build": "tsc -b src && npm run doc",
+    "build:attribute": "webpack --config ./src/fixtures/attribute/webpack.config.js",
+    "build:event": "webpack --config ./src/fixtures/event/webpack.config.js",
+    "build:binding": "webpack --config ./src/fixtures/binding/webpack.config.js",
+    "build:children": "webpack --config ./src/fixtures/children/webpack.config.js",
+    "build:dot-syntax": "webpack --config ./src/fixtures/dot-syntax/webpack.config.js",
+    "build:partial": "webpack --config ./src/fixtures/partial/webpack.config.js",
+    "build:when": "webpack --config ./src/fixtures/when/webpack.config.js",
+    "build:ref": "webpack --config ./src/fixtures/ref/webpack.config.js",
+    "build:repeat": "webpack --config ./src/fixtures/repeat/webpack.config.js",
+    "build:slotted": "webpack --config ./src/fixtures/slotted/webpack.config.js",
+    "build-app": "npm run build:attribute && npm run build:dot-syntax && npm run build:partial && npm run build:event && npm run build:children && npm run build:binding && npm run build:when && npm run build:ref && npm run build:repeat && npm run build:slotted",
+    "build-server": "tsc -b server",
+    "doc": "api-extractor run --local",
+    "doc:ci": "api-extractor run",
+    "eslint": "eslint . --ext .ts",
+    "eslint:fix": "eslint . --ext .ts --fix",
+    "prepublishOnly": "npm run clean && npm run build",
+    "pretest": "npm run build && npm run build-server",
+    "prettier:diff": "prettier --config ../../../.prettierrc \"**/*.{ts,html}\" --list-different",
+    "prettier": "prettier --config ../../../.prettierrc --write \"**/*.{ts,html}\"",
+    "test": "npm run build-app && playwright test --config=playwright.config.cjs",
+    "test-server": "node server/dist/server.js",
+    "install-playwright-browsers": "npm run playwright install",
+    "dev": "npm run build && npm run build-app && npm run build-server && npm run test-server"
+  },
+  "description": "A package for facilitating rendering FAST Web Components in a non-browser environment.",
+  "exports": {
+    ".": {
+      "types": "./dist/dts/index.d.ts",
+      "default": "./dist/esm/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": [
+    "./dist/esm/index.js"
+  ],
+  "peerDependencies": {
+    "@microsoft/fast-element": "^2.2.0"
+  },
+  "devDependencies": {
+    "@microsoft/api-extractor": "^7.47.0",
+    "@microsoft/fast-element": "^2.2.0",
+    "@playwright/test": "^1.49.0",
+    "@types/express": "^4.17.21",
+    "@types/node": "^17.0.17",
+    "express": "^4.19.2",
+    "typescript": "~5.3.0",
+    "webpack": "^5.97.1",
+    "webpack-cli": "^6.0.1",
+    "webpack-merge": "^6.0.1"
+  },
+  "beachball": {
+    "disallowedChangeTypes": [
+      "major",
+      "minor",
+      "patch"
+    ],
+    "tag": "alpha"
+  }
+}

package/webpack.common.config.js

@@ -0,0 +1,18 @@
+export default {
+  mode: "production",
+  devServer: {
+    static: "./public",
+    port: 3001
+  },
+  resolve: {
+    extensions: [".ts", ".js"],
+    extensionAlias: {
+     ".js": [".js", ".ts"],
+    }
+  },
+  module: {
+    rules: [
+      { test: /\.([cm]?ts)$/, loader: "ts-loader" }
+    ]
+  },
+};