face-up 0.0.0 → 0.0.2

package/.gitmodules

@@ -0,0 +1,3 @@
+[submodule "types"]
+	path = types
+	url = https://github.com/bahrus/types.git

package/.kiro/steering/project-context.md

@@ -0,0 +1,17 @@
+---
+inclusion: auto
+---
+
+# Project Context
+
+This project uses shared type definitions and documentation from the `types` submodule.
+
+## Key References
+
+#[[file:types/NewCustomElementFeature.md]]
+#[[file:types/NewEnhancementInstructions.md]]
+#[[file:types/EnhancementConversionInstructions.md]]
+
+## Coding Standards
+
+#[[file:types/.kiro/steering/coding-standards.md]]

package/.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "explorer.fileNesting.enabled": true
+}

package/FaceUp.js

@@ -0,0 +1,305 @@
+// @ts-check
+/** @import {FaceUpProps, AllProps, FeatureSpawnContext, FaceUpSharedContext, ValidationFlags} from './types/face-up/types' */
+
+/**
+ * FaceUp — A Custom Element Feature that adds Form Associated behavior
+ * to a custom element via the ElementInternals API.
+ *
+ * This feature enables a custom element to:
+ * - Participate in form submission (setFormValue)
+ * - Participate in form validation (setValidity)
+ * - Respond to form lifecycle callbacks (reset, restore, disabled state)
+ * - Be styled with :valid/:invalid/:disabled pseudo-classes
+ * - Be labeled with <label> elements
+ *
+ * The host custom element MUST:
+ * - Call `this.attachInternals()` and pass the result via getSharedContext
+ *
+ * `static formAssociated = true` is set automatically via `static onAssigned`.
+ *
+ * @implements {FaceUpProps}
+ */
+class FaceUp {
+
+    /**
+     * Called once by assignFeatures after registration.
+     * Sets `static formAssociated = true` on the host constructor so the
+     * consumer doesn't need to declare it manually.
+     * @param {Function} ctr - The custom element constructor
+     * @param {object} _featureConfig - The feature config (unused)
+     */
+    static onAssigned(ctr, _featureConfig) {
+        if (!ctr.formAssociated) {
+            ctr.formAssociated = true;
+        }
+    }
+    /** @type {WeakRef<HTMLElement> | undefined} */
+    #hostRef;
+
+    /** @type {ElementInternals | undefined} */
+    #internals;
+
+    /** @type {AbortController | undefined} */
+    #abortController;
+
+    /** @type {EventTarget | undefined} */
+    #hostPropagator;
+
+    /** @type {boolean} */
+    #hasDisconnected = false;
+
+    /** @type {string | File | FormData | null} */
+    #value = null;
+
+    /** @type {string | File | FormData | null} */
+    #state = null;
+
+    /** @type {boolean} */
+    #disabled = false;
+
+    /** @type {boolean} */
+    #required = false;
+
+    /** @type {string} */
+    #validationMessage = '';
+
+    /**
+     * @param {HTMLElement} hostElement
+     * @param {FeatureSpawnContext} ctx
+     * @param {Partial<FaceUpProps>} [initVals]
+     */
+    constructor(hostElement, ctx, initVals) {
+        this.#hostRef = new WeakRef(hostElement);
+        if (ctx.shared) {
+            this.#internals = ctx.shared.internals;
+            this.#hostPropagator = ctx.shared.hostPropagator;
+        }
+        if (initVals) {
+            if (initVals.value !== undefined) this.#value = initVals.value;
+            if (initVals.state !== undefined) this.#state = initVals.state;
+            if (initVals.disabled !== undefined) this.#disabled = initVals.disabled;
+            if (initVals.required !== undefined) this.#required = initVals.required;
+            if (initVals.validationMessage !== undefined) this.#validationMessage = initVals.validationMessage;
+            if (initVals.hostPropagator !== undefined) this.#hostPropagator = initVals.hostPropagator;
+        }
+        this.#connect();
+    }
+
+    // ─── Public Properties ───────────────────────────────────────────
+
+    get value() { return this.#value; }
+    set value(v) {
+        this.#value = v;
+        this.#syncFormValue();
+        this.#validateInternal();
+    }
+
+    get state() { return this.#state; }
+    set state(v) {
+        this.#state = v;
+        this.#syncFormValue();
+    }
+
+    get disabled() { return this.#disabled; }
+    set disabled(v) {
+        this.#disabled = !!v;
+    }
+
+    get required() { return this.#required; }
+    set required(v) {
+        this.#required = !!v;
+        this.#validateInternal();
+    }
+
+    get validationMessage() { return this.#validationMessage; }
+    set validationMessage(msg) {
+        this.#validationMessage = msg;
+        this.#validateInternal();
+    }
+
+    get hostPropagator() { return this.#hostPropagator ?? null; }
+    set hostPropagator(v) {
+        this.#hostPropagator = v ?? undefined;
+        this.#reconnectListeners();
+    }
+
+    // ─── Read-only Form Control Accessors ────────────────────────────
+
+    /** The form element the host is associated with */
+    get form() { return this.#internals?.form ?? null; }
+
+    /** The ValidityState of the control */
+    get validity() { return this.#internals?.validity ?? null; }
+
+    /** Whether the control will be validated */
+    get willValidate() { return this.#internals?.willValidate ?? false; }
+
+    // ─── Form Control Methods ────────────────────────────────────────
+
+    /** Runs constraint validation and returns true if valid */
+    checkValidity() {
+        return this.#internals?.checkValidity() ?? true;
+    }
+
+    /** Runs constraint validation and shows the browser validation UI if invalid */
+    reportValidity() {
+        return this.#internals?.reportValidity() ?? true;
+    }
+
+    /**
+     * Sets custom validity flags and message on the control.
+     * @param {ValidationFlags} flags - ValidityStateFlags object
+     * @param {string} [message] - Validation message (required if any flag is true)
+     * @param {HTMLElement} [anchor] - Element to anchor the validation popup to
+     */
+    setValidity(flags, message, anchor) {
+        if (!this.#internals) return;
+        if (message) {
+            this.#internals.setValidity(flags, message, anchor);
+        } else {
+            // Clear validity — no flags set
+            this.#internals.setValidity({});
+        }
+    }
+
+    // ─── Form Lifecycle Callbacks (forwarded via callbackForwarding) ─
+
+    /**
+     * Called when the host element's disabled state changes.
+     * @param {boolean} isDisabled
+     */
+    formDisabledCallback(isDisabled) {
+        this.#disabled = isDisabled;
+    }
+
+    /**
+     * Called when the form is reset.
+     * Resets value and state to null and clears validation.
+     */
+    formResetCallback() {
+        this.#value = null;
+        this.#state = null;
+        this.#validationMessage = '';
+        this.#syncFormValue();
+        if (this.#internals) {
+            this.#internals.setValidity({});
+        }
+    }
+
+    /**
+     * Called when the browser restores form state (navigation, restart)
+     * or when autofill sets a value.
+     * @param {string | File | FormData | null} state
+     * @param {'restore' | 'autocomplete'} mode
+     */
+    formStateRestoreCallback(state, mode) {
+        if (mode === 'restore') {
+            this.#state = state;
+            this.#value = state;
+            this.#syncFormValue();
+        }
+    }
+
+    // ─── Lifecycle (callbackForwarding) ──────────────────────────────
+
+    connectedCallback() {
+        if (this.#hasDisconnected) {
+            this.#hasDisconnected = false;
+            this.#connect();
+        }
+    }
+
+    disconnectedCallback() {
+        this.#hasDisconnected = true;
+        this.#cleanup();
+    }
+
+    // ─── Private Methods ─────────────────────────────────────────────
+
+    #connect() {
+        this.#abortController = new AbortController();
+        const signal = this.#abortController.signal;
+
+        // Listen for value/state/required changes from the host propagator
+        if (this.#hostPropagator) {
+            this.#hostPropagator.addEventListener('value', (/** @type {CustomEvent} */ e) => {
+                this.#value = e.detail?.value ?? e.detail;
+                this.#syncFormValue();
+                this.#validateInternal();
+            }, { signal });
+
+            this.#hostPropagator.addEventListener('state', (/** @type {CustomEvent} */ e) => {
+                this.#state = e.detail?.value ?? e.detail;
+                this.#syncFormValue();
+            }, { signal });
+
+            this.#hostPropagator.addEventListener('required', (/** @type {CustomEvent} */ e) => {
+                this.#required = !!(e.detail?.value ?? e.detail);
+                this.#validateInternal();
+            }, { signal });
+
+            this.#hostPropagator.addEventListener('disabled', (/** @type {CustomEvent} */ e) => {
+                this.#disabled = !!(e.detail?.value ?? e.detail);
+            }, { signal });
+        }
+
+        // Sync initial value if already set
+        this.#syncFormValue();
+        this.#validateInternal();
+    }
+
+    #cleanup() {
+        if (this.#abortController) {
+            this.#abortController.abort();
+            this.#abortController = undefined;
+        }
+    }
+
+    #reconnectListeners() {
+        this.#cleanup();
+        if (!this.#hasDisconnected) {
+            this.#connect();
+        }
+    }
+
+    /**
+     * Syncs the current value (and optional state) to ElementInternals.
+     */
+    #syncFormValue() {
+        if (!this.#internals) return;
+        if (this.#value === null) {
+            this.#internals.setFormValue(null);
+        } else if (this.#state !== null) {
+            this.#internals.setFormValue(this.#value, this.#state);
+        } else {
+            this.#internals.setFormValue(this.#value);
+        }
+    }
+
+    /**
+     * Runs internal validation based on required + custom validation message.
+     */
+    #validateInternal() {
+        if (!this.#internals) return;
+        const host = this.#hostRef?.deref();
+        if (!host) return;
+
+        if (this.#validationMessage) {
+            this.#internals.setValidity(
+                { customError: true },
+                this.#validationMessage,
+                host
+            );
+        } else if (this.#required && (this.#value === null || this.#value === '')) {
+            this.#internals.setValidity(
+                { valueMissing: true },
+                'Please fill out this field.',
+                host
+            );
+        } else {
+            this.#internals.setValidity({});
+        }
+    }
+}
+
+export { FaceUp };

package/README.md

@@ -1,2 +1,162 @@
-# face-it
-A Custom Element Feature that Adds Form Associated Behavior to a Custom Element
+# face-up
+
+A Custom Element Feature that adds Form Associated behavior to a custom element via the [ElementInternals](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals) API.
+
+## What it does
+
+`FaceUp` enables any custom element to fully participate in HTML forms — matching the capabilities described in [More Capable Form Controls](https://web.dev/articles/more-capable-form-controls):
+
+- **Form submission** — The control's value is automatically submitted with the form via `setFormValue()`.
+- **Form validation** — The control participates in constraint validation with `:valid`/`:invalid` pseudo-classes.
+- **Form reset** — The control resets to its default state when the form is reset.
+- **Form state restoration** — The browser can restore the control's state after navigation or restart.
+- **Disabled state** — The control responds to `disabled` attribute changes on itself or ancestor `<fieldset>`.
+- **Label association** — The control can be labeled with `<label>` elements.
+
+## Usage
+
+```js
+import 'assign-gingerly/assignFeatures.js';
+import { FaceUp } from 'face-up/FaceUp.js';
+
+class MyInput extends HTMLElement {
+    propagator = new EventTarget();
+    #internals;
+
+    static supportedFeatures = {
+        faceUp: {
+            fallbackSpawn: FaceUp,
+            callbackForwarding: [
+                'connectedCallback',
+                'disconnectedCallback',
+                'formDisabledCallback',
+                'formResetCallback',
+                'formStateRestoreCallback'
+            ],
+            getSharedContext(instance) {
+                return {
+                    internals: instance.#internals,
+                    hostPropagator: instance.propagator
+                };
+            }
+        }
+    };
+
+    constructor() {
+        super();
+        this.#internals = this.attachInternals();
+    }
+}
+
+// assignFeatures calls FaceUp.onAssigned which sets static formAssociated = true
+await customElements.assignFeatures(MyInput, {
+    faceUp: { spawn: FaceUp }
+});
+
+customElements.define('my-input', MyInput);
+```
+
+Note: `static formAssociated = true` is set automatically by `FaceUp.onAssigned` — you don't need to declare it yourself.
+
+Form lifecycle callbacks (`formDisabledCallback`, `formResetCallback`, `formStateRestoreCallback`) are forwarded automatically via `callbackForwarding` — no manual forwarding code needed in the host element.
+
+## Setting Values
+
+Dispatch events on the host's `propagator` to update the form value:
+
+```js
+// From within the custom element:
+this.propagator.dispatchEvent(
+    new Event('value')
+);
+```
+
+Or set the value directly on the feature instance:
+
+```js
+el.faceUp.value = 'new value';
+```
+
+## Validation
+
+Set a custom validation message:
+
+```js
+el.faceUp.validationMessage = 'This value is not allowed.';
+```
+
+Or use the lower-level `setValidity()` API:
+
+```js
+el.faceUp.setValidity({ rangeUnderflow: true }, 'Value must be at least 0.');
+```
+
+Clear validation:
+
+```js
+el.faceUp.validationMessage = '';
+// or
+el.faceUp.setValidity({});
+```
+
+## Form State Restoration
+
+Pass a `state` parameter alongside `value` to enable proper form restoration:
+
+```js
+el.faceUp.state = 'palette/#7fff00';
+el.faceUp.value = '#7fff00';
+```
+
+The `state` is stored internally by the browser and passed back to `formStateRestoreCallback` when the form is restored.
+
+## API
+
+### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `value` | `string \| File \| FormData \| null` | The submittable form value |
+| `state` | `string \| File \| FormData \| null` | Internal state for form restoration |
+| `disabled` | `boolean` | Whether the control is disabled |
+| `required` | `boolean` | Whether the control requires a value |
+| `validationMessage` | `string` | Custom validation error message |
+| `form` | `HTMLFormElement \| null` | The associated form (read-only) |
+| `validity` | `ValidityState \| null` | The validity state (read-only) |
+| `willValidate` | `boolean` | Whether the control will be validated (read-only) |
+
+### Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `checkValidity()` | `boolean` | Returns true if the control is valid |
+| `reportValidity()` | `boolean` | Shows browser validation UI if invalid |
+| `setValidity(flags, message?, anchor?)` | `void` | Sets custom validity flags |
+
+### Form Lifecycle Callbacks (forwarded via `callbackForwarding`)
+
+| Callback | Description |
+|----------|-------------|
+| `formDisabledCallback(disabled)` | Called when disabled state changes |
+| `formResetCallback()` | Called when the form is reset |
+| `formStateRestoreCallback(state, mode)` | Called when browser restores form state |
+
+These are forwarded automatically by `assign-gingerly`'s `callbackForwarding` mechanism — the host element does not need to implement them manually.
+
+## Requirements
+
+The host custom element **must**:
+
+1. Call `this.attachInternals()` in its constructor
+2. Pass the internals via `getSharedContext` in `supportedFeatures`
+3. Include the form lifecycle callbacks in `callbackForwarding`
+
+Both `static formAssociated = true` and form lifecycle callback forwarding are handled automatically — no manual boilerplate needed in the host element.
+
+## Dev
+
+```bash
+npm install
+npm run serve
+# Open http://localhost:8000/tests/test1.html
+```

package/imports.html

@@ -0,0 +1,8 @@
+<script type=importmap>
+    {
+        "imports": {
+            "assign-gingerly/": "/node_modules/assign-gingerly/",
+            "face-up/": "/"
+        }
+    }
+</script>

package/package.json

@@ -1,20 +1,30 @@
-{
-  "name": "face-up",
-  "version": "0.0.0",
-  "description": "A Custom Element Feature that Adds Form Associated Behavior to a Custom Element",
-  "homepage": "https://github.com/bahrus/face-it#readme",
-  "bugs": {
-    "url": "https://github.com/bahrus/face-it/issues"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/bahrus/face-it.git"
-  },
-  "license": "MIT",
-  "author": "Bruce B. Anderson <anderson.bruce.b@gmail.com>",
-  "type": "module",
-  "main": "FaceIt.js",
-  "scripts": {
-    "test": "playwright test"
-  }
-}
+{
+  "name": "face-up",
+  "version": "0.0.2",
+  "description": "A Custom Element Feature that Adds Form Associated Behavior to a Custom Element",
+  "homepage": "https://github.com/bahrus/face-up#readme",
+  "bugs": {
+    "url": "https://github.com/bahrus/face-up/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bahrus/face-up.git"
+  },
+  "license": "MIT",
+  "author": "Bruce B. Anderson <anderson.bruce.b@gmail.com>",
+  "type": "module",
+  "main": "FaceUp.js",
+  "scripts": {
+    "serve": "node ./node_modules/spa-ssi/serve.js",
+    "test": "playwright test",
+    "update": "ncu -u && npm install",
+    "safari": "npx playwright wk http://localhost:8000",
+    "chrome": "npx playwright cr http://localhost:8000"
+  },
+  "devDependencies": {
+    "assign-gingerly": "0.0.43",
+    "@playwright/test": "1.60.0",
+    "spa-ssi": "0.0.27"
+  },
+  "dependencies": {}
+}

package/tests/test1.html

@@ -0,0 +1,115 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Test - FaceUp Feature</title>
+    <!-- #include virtual="/imports.html" -->
+    <script type=module>
+        import 'assign-gingerly/assignFeatures.js';
+        import {FaceUp} from 'face-up/FaceUp.js';
+
+        /**
+         * A test custom element that uses FaceUp to become form-associated.
+         * Note: static formAssociated = true is set automatically by FaceUp.onAssigned
+         */
+        class TestInput extends HTMLElement {
+            propagator = new EventTarget();
+            #internals;
+
+            static supportedFeatures = {
+                faceUp: {
+                    fallbackSpawn: FaceUp,
+                    callbackForwarding: [
+                        'connectedCallback',
+                        'disconnectedCallback',
+                        'formDisabledCallback',
+                        'formResetCallback',
+                        'formStateRestoreCallback'
+                    ],
+                    getSharedContext(instance) {
+                        return {
+                            internals: instance.#internals,
+                            hostPropagator: instance.propagator
+                        };
+                    }
+                }
+            };
+
+            constructor() {
+                super();
+                this.#internals = this.attachInternals();
+                this.attachShadow({ mode: 'open' });
+                this.shadowRoot.innerHTML = `
+                    <style>
+                        :host { display: inline-block; }
+                        input { font: inherit; }
+                    </style>
+                    <input type="text" part="input">
+                `;
+            }
+
+            connectedCallback() {
+                const input = this.shadowRoot.querySelector('input');
+                input.addEventListener('input', () => {
+                    this.propagator.dispatchEvent(
+                        new CustomEvent('value', { detail: input.value })
+                    );
+                });
+            }
+
+            // Expose name for form submission
+            get name() { return this.getAttribute('name'); }
+            get type() { return this.localName; }
+        }
+
+        // Inject the FaceUp feature (onAssigned sets static formAssociated = true)
+        await customElements.assignFeatures(TestInput, {
+            faceUp: { spawn: FaceUp }
+        });
+
+        customElements.define('test-input', TestInput);
+    </script>
+</head>
+<body>
+    <h1>FaceUp Feature Test</h1>
+
+    <form id="test-form">
+        <fieldset>
+            <legend>Form-Associated Custom Element</legend>
+
+            <label>
+                Name:
+                <test-input name="username"></test-input>
+            </label>
+
+            <br><br>
+
+            <label>
+                Required field:
+                <test-input name="required-field" required></test-input>
+            </label>
+
+            <br><br>
+
+            <button type="submit">Submit</button>
+            <button type="reset">Reset</button>
+        </fieldset>
+    </form>
+
+    <h2>Form Data Output</h2>
+    <pre id="output"></pre>
+
+    <script type=module>
+        const form = document.getElementById('test-form');
+        const output = document.getElementById('output');
+
+        form.addEventListener('submit', (e) => {
+            e.preventDefault();
+            const formData = new FormData(form);
+            const entries = [...formData.entries()];
+            output.textContent = JSON.stringify(Object.fromEntries(entries), null, 2);
+        });
+    </script>
+</body>
+</html>