face-up 0.0.1 → 0.0.3

package/FaceUp.js

@@ -17,6 +17,11 @@
  *
  * `static formAssociated = true` is set automatically via `static onAssigned`.
  *
+ * Integration is seamless — because the feature is a getter-only property,
+ * `assignGingerly` merges directly into the instance. The consumer simply
+ * sets properties on the feature (e.g., `el.faceUp.value = x`) and the
+ * setters handle syncing to ElementInternals automatically.
+ *
  * @implements {FaceUpProps}
  */
 class FaceUp {
@@ -25,29 +30,23 @@ 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 {typeof HTMLElement} ctr - The custom element constructor
      * @param {object} _featureConfig - The feature config (unused)
      */
     static onAssigned(ctr, _featureConfig) {
+        // @ts-ignore — formAssociated is a custom element static property
         if (!ctr.formAssociated) {
+            // @ts-ignore
             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;
 
@@ -72,7 +71,6 @@ class FaceUp {
         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;
@@ -80,9 +78,10 @@ class FaceUp {
             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();
+        // Sync initial state to internals
+        this.#syncFormValue();
+        this.#validateInternal();
     }
 
     // ─── Public Properties ───────────────────────────────────────────
@@ -117,12 +116,6 @@ class FaceUp {
         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 */
@@ -200,68 +193,8 @@ class FaceUp {
         }
     }
 
-    // ─── 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.
      */

package/RAConfig.mjs

@@ -0,0 +1,88 @@
+// @ts-check
+/** @import {Merges} from './types/roundabout/types.d.ts' */
+
+/**
+ * @typedef {object} FaceUpForwardingProps
+ * @property {string | File | FormData | null} value
+ * @property {string | File | FormData | null} state
+ * @property {boolean} disabled
+ * @property {boolean} required
+ * @property {string} validationMessage
+ */
+
+/**
+ * Property key constants for FaceUp-relevant forwarding.
+ * @type {{ [K in keyof FaceUpForwardingProps]: K }}
+ */
+export const props = {
+    value: 'value',
+    state: 'state',
+    disabled: 'disabled',
+    required: 'required',
+    validationMessage: 'validationMessage',
+};
+
+/**
+ * Creates merges configuration for forwarding properties from the host view model
+ * to the faceUp feature instance via roundabout's reactive system.
+ *
+ * When any of these properties change on the view model, the corresponding
+ * setter on the feature fires, which syncs to ElementInternals automatically.
+ *
+ * @param {string} [featureKey='faceUp'] - The feature property name on the host element.
+ * @returns {Merges<FaceUpForwardingProps>}
+ *
+ * @example
+ * ```js
+ * import { getFaceUpMerges } from 'face-up/RAConfig.mjs';
+ *
+ * export const raConfig = {
+ *     merges: [
+ *         ...getFaceUpMerges(),          // uses default 'faceUp' key
+ *         // ...or with a custom key:
+ *         // ...getFaceUpMerges('formControl'),
+ *     ]
+ * };
+ * ```
+ */
+export function getFaceUpMerges(featureKey = 'faceUp') {
+    return [
+        {
+            ifKeyIn: [props.value],
+            assign: {
+                [`?.${featureKey}?.value`]: '?.value'
+            }
+        },
+        {
+            ifKeyIn: [props.state],
+            assign: {
+                [`?.${featureKey}?.state`]: '?.state'
+            }
+        },
+        {
+            ifKeyIn: [props.disabled],
+            assign: {
+                [`?.${featureKey}?.disabled`]: '?.disabled'
+            }
+        },
+        {
+            ifKeyIn: [props.required],
+            assign: {
+                [`?.${featureKey}?.required`]: '?.required'
+            }
+        },
+        {
+            ifKeyIn: [props.validationMessage],
+            assign: {
+                [`?.${featureKey}?.validationMessage`]: '?.validationMessage'
+            }
+        },
+    ];
+}
+
+/**
+ * Pre-built merges using the default 'faceUp' feature key.
+ * Convenience export for the common case.
+ * @type {Merges<FaceUpForwardingProps>}
+ */
+export const faceUpMerges = getFaceUpMerges();

package/README.md

@@ -20,17 +20,19 @@ 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'],
+            callbackForwarding: [
+                'formDisabledCallback',
+                'formResetCallback',
+                'formStateRestoreCallback'
+            ],
             getSharedContext(instance) {
                 return {
-                    internals: instance.#internals,
-                    hostPropagator: instance.propagator
+                    internals: instance.#internals
                 };
             }
         }
@@ -40,19 +42,6 @@ class MyInput extends HTMLElement {
         super();
         this.#internals = this.attachInternals();
     }
-
-    // Forward form lifecycle callbacks to the feature
-    formDisabledCallback(disabled) {
-        this.faceUp.formDisabledCallback(disabled);
-    }
-
-    formResetCallback() {
-        this.faceUp.formResetCallback();
-    }
-
-    formStateRestoreCallback(state, mode) {
-        this.faceUp.formStateRestoreCallback(state, mode);
-    }
 }
 
 // assignFeatures calls FaceUp.onAssigned which sets static formAssociated = true
@@ -63,25 +52,26 @@ await customElements.assignFeatures(MyInput, {
 customElements.define('my-input', MyInput);
 ```
 
-Note: `static formAssociated = true` is set automatically by `FaceUp.onAssigned` — you don't need to declare it yourself.
+That's it. No propagator, no manual callback forwarding, no event wiring.
+
+- `static formAssociated = true` is set automatically by `FaceUp.onAssigned`.
+- Form lifecycle callbacks are forwarded automatically via `callbackForwarding`.
+- Property changes sync to `ElementInternals` via the feature's setters.
 
 ## Setting Values
 
-Dispatch events on the host's `propagator` to update the form value:
+Because `faceUp` is a getter-only property, `assignGingerly` merges directly into the feature instance. Set properties however you like:
 
 ```js
-// From within the custom element:
-this.propagator.dispatchEvent(
-    new Event('value')
-);
-```
-
-Or set the value directly on the feature instance:
+// Direct property access
+el.faceUp.value = 'hello';
 
-```js
-el.faceUp.value = 'new value';
+// Via assignGingerly (merges into the feature instance)
+el.assignGingerly({ faceUp: { value: 'hello', required: true } });
 ```
 
+Both approaches trigger the setter, which calls `setFormValue()` on the internals automatically.
+
 ## Validation
 
 Set a custom validation message:
@@ -104,6 +94,8 @@ el.faceUp.validationMessage = '';
 el.faceUp.setValidity({});
 ```
 
+Built-in `required` validation is automatic — if `required` is `true` and `value` is `null` or `''`, the control is marked invalid with `valueMissing`.
+
 ## Form State Restoration
 
 Pass a `state` parameter alongside `value` to enable proper form restoration:
@@ -138,23 +130,57 @@ The `state` is stored internally by the browser and passed back to `formStateRes
 | `reportValidity()` | `boolean` | Shows browser validation UI if invalid |
 | `setValidity(flags, message?, anchor?)` | `void` | Sets custom validity flags |
 
-### Form Lifecycle Methods
+### Form Lifecycle Callbacks (forwarded via `callbackForwarding`)
 
-| Method | Description |
-|--------|-------------|
+| 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.
+
+## How it integrates
+
+The key insight: because `assignFeatures` installs `faceUp` as a **getter-only** property on the prototype, `assignGingerly` automatically merges object values into the existing feature instance rather than replacing it. This means:
+
+1. The feature's setters fire on every property assignment.
+2. Each setter syncs to `ElementInternals` immediately.
+3. No event bus, no propagator, no intermediate layer — just property access.
+
+```js
+// All of these trigger the setter → sync to internals:
+el.faceUp.value = 'x';
+el.assignGingerly({ faceUp: { value: 'x' } });
+```
+
 ## Requirements
 
 The host custom element **must**:
 
 1. Call `this.attachInternals()` in its constructor
 2. Pass the internals via `getSharedContext` in `supportedFeatures`
-3. Forward form lifecycle callbacks to the feature
+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.
+
+## Roundabout Integration
+
+For projects using [roundabout](https://github.com/bahrus/roundabout), `face-up` exports merge rules that wire up property forwarding automatically:
+
+```js
+import { faceUpMerges } from 'face-up/RAConfig.mjs';
+
+export const raConfig = {
+    propagate: ['value', 'disabled', 'required', /* ... */],
+    merges: [
+        ...faceUpMerges,
+        // ...your other merges
+    ]
+};
+```
 
-`static formAssociated = true` is handled automatically by `FaceUp.onAssigned` when `assignFeatures` is called.
+When `value`, `state`, `disabled`, `required`, or `validationMessage` change on the view model, roundabout forwards them to the `faceUp` feature's setters, which sync to `ElementInternals` automatically.
 
 ## Dev
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "face-up",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "A Custom Element Feature that Adds Form Associated Behavior to a Custom Element",
   "homepage": "https://github.com/bahrus/face-up#readme",
   "bugs": {
@@ -14,6 +14,10 @@
   "author": "Bruce B. Anderson <anderson.bruce.b@gmail.com>",
   "type": "module",
   "main": "FaceUp.js",
+  "exports": {
+    "./FaceUp.js": "./FaceUp.js",
+    "./RAConfig.mjs": "./RAConfig.mjs"
+  },
   "scripts": {
     "serve": "node ./node_modules/spa-ssi/serve.js",
     "test": "playwright test",
@@ -22,7 +26,7 @@
     "chrome": "npx playwright cr http://localhost:8000"
   },
   "devDependencies": {
-    "assign-gingerly": "0.0.42",
+    "assign-gingerly": "0.0.43",
     "@playwright/test": "1.60.0",
     "spa-ssi": "0.0.27"
   },

package/requirements/SupportAutoForwardingWithRoundabout.md

@@ -0,0 +1,57 @@
+# Support Auto Forwarding With Roundabout Merging
+
+---
+
+## Human Ask
+
+I am interested in making it really easy to provide property forwarding to this feature for those who make use of the [roundabout library](https://github.com/bahrus/roundabout).
+
+The *time-ticker* custom element library is such a scenario.  I've copied that project into this folder temporarily for easy inspection.  Note how, in that project, the cef.json file is built from cef.mjs via npm run build for good typescript support with a kiro hook.  Look closely at the "merges" section to see how property forwarding is done.  The roundabout library actually creates the properties automaically from these merges.
+
+Please create an RAConfig.mjs in this project that provides similar property forwarding configuration for all the relevant forwarding, which can then be imported by projects like time-ticker. 
+
+---
+
+## Implementation Notes
+
+### What was created
+
+`RAConfig.mjs` — exports `faceUpMerges` and `props` for consumers using roundabout.
+
+### How it works
+
+In the roundabout pattern, `merges` are reactive rules: when a property on the view model changes (detected via `ifKeyIn`), the `assign` block runs `assignFrom(vm, assign, { from: vm })` — resolving the RHS path against the vm and assigning the result into the LHS path on the vm.
+
+Since `faceUp` is a getter-only property (installed by `assignFeatures`), `assignGingerly` merges into the feature instance. This means the LHS path `?.faceUp?.value` triggers the feature's `value` setter, which calls `setFormValue()` on the internals.
+
+The forwarding properties exposed are:
+- `value` → `?.faceUp?.value` — the submittable form value
+- `state` → `?.faceUp?.state` — internal state for form restoration
+- `disabled` → `?.faceUp?.disabled` — disabled state
+- `required` → `?.faceUp?.required` — required constraint
+- `validationMessage` → `?.faceUp?.validationMessage` — custom validation error
+
+### Consumer usage (e.g., time-ticker's cef.mjs)
+
+```js
+import { faceUpMerges } from 'face-up/RAConfig.mjs';
+
+export const raConfig = {
+    propagate: ['value', 'disabled', 'required', /* ...other props */],
+    merges: [
+        ...faceUpMerges,
+        // ...project-specific merges
+    ],
+    // ...rest of config
+};
+```
+
+This eliminates the need for consumers to manually write the merge rules for form-associated behavior — they just spread `faceUpMerges` into their config.
+
+### Relationship to time-ticker
+
+In time-ticker's `cef.mjs`, the existing merges forward `duration` and `disabled` to the `timeTicker` feature. With `faceUpMerges`, the time-ticker project could additionally spread these merges to forward `value`, `disabled`, etc. to the `faceUp` feature. The `disabled` merge would forward to both features (roundabout handles this naturally since each merge is independent).
+
+### Note on `hostPropagator`
+
+The time-ticker's `time-ticker-element.js` still passes `hostPropagator` in `getSharedContext` for `faceUp`. Since we've removed the propagator dependency from FaceUp (it now relies purely on property setters + roundabout merges for reactivity), that `hostPropagator` field in `getSharedContext` is no longer needed for `faceUp`. The `getSharedContext` only needs to pass `internals`.

package/tests/test1.html

@@ -11,20 +11,23 @@
 
         /**
          * A test custom element that uses FaceUp to become form-associated.
-         * Note: static formAssociated = true is set automatically by FaceUp.onAssigned
+         * Note: static formAssociated = true is set automatically by FaceUp.onAssigned.
+         * Form lifecycle callbacks are forwarded automatically via callbackForwarding.
          */
         class TestInput extends HTMLElement {
-            propagator = new EventTarget();
             #internals;
 
             static supportedFeatures = {
                 faceUp: {
                     fallbackSpawn: FaceUp,
-                    callbackForwarding: ['connectedCallback', 'disconnectedCallback'],
+                    callbackForwarding: [
+                        'formDisabledCallback',
+                        'formResetCallback',
+                        'formStateRestoreCallback'
+                    ],
                     getSharedContext(instance) {
                         return {
-                            internals: instance.#internals,
-                            hostPropagator: instance.propagator
+                            internals: instance.#internals
                         };
                     }
                 }
@@ -46,36 +49,14 @@
             connectedCallback() {
                 const input = this.shadowRoot.querySelector('input');
                 input.addEventListener('input', () => {
-                    this.propagator.dispatchEvent(
-                        new CustomEvent('value', { detail: input.value })
-                    );
+                    // Simply set the feature property — the setter syncs to internals
+                    this.faceUp.value = input.value;
                 });
             }
 
             // Expose name for form submission
             get name() { return this.getAttribute('name'); }
             get type() { return this.localName; }
-
-            // Form lifecycle callbacks forwarded to the feature
-            formDisabledCallback(disabled) {
-                this.faceUp.formDisabledCallback(disabled);
-                const input = this.shadowRoot.querySelector('input');
-                input.disabled = disabled;
-            }
-
-            formResetCallback() {
-                this.faceUp.formResetCallback();
-                const input = this.shadowRoot.querySelector('input');
-                input.value = '';
-            }
-
-            formStateRestoreCallback(state, mode) {
-                this.faceUp.formStateRestoreCallback(state, mode);
-                if (state) {
-                    const input = this.shadowRoot.querySelector('input');
-                    input.value = typeof state === 'string' ? state : '';
-                }
-            }
         }
 
         // Inject the FaceUp feature (onAssigned sets static formAssociated = true)

package/types/NewCustomElementFeature.md

@@ -426,7 +426,7 @@ customElements.assignFeatures(MyElement, {
 3. On first `connectedCallback`, the lazy getter is triggered — spawning the feature at the correct lifecycle moment (when the element is in the DOM and computed styles are available).
 4. For async features, forwarding is skipped until the real instance is available.
 
-**Supported callbacks:** `connectedCallback`, `disconnectedCallback`, `attributeChangedCallback`, `adoptedCallback`
+**Supported callbacks:** `connectedCallback`, `disconnectedCallback`, `attributeChangedCallback`, `adoptedCallback`, `formAssociatedCallback`, `formDisabledCallback`, `formResetCallback`, `formStateRestoreCallback`
 
 **When to use it:**
 
@@ -434,6 +434,7 @@ customElements.assignFeatures(MyElement, {
 - The feature needs `getComputedStyle` (which requires the element to be in the DOM)
 - The feature sets up event listeners that should be cleaned up on disconnect
 - The feature needs to handle elements created via cloned templates (where the constructor fires before DOM insertion)
+- The feature manages form-associated behavior (`formDisabledCallback`, `formResetCallback`, `formStateRestoreCallback`) — e.g., face-up
 
 **Avoiding double-connect on initial spawn:**
 
@@ -480,7 +481,6 @@ This pattern eliminates all manual wiring in the consumer's constructor — the
 
 ```javascript
 class MyElement extends HTMLElement {
-    propagator = new EventTarget();
     #internals;
 
     static supportedFeatures = {
@@ -489,8 +489,7 @@ class MyElement extends HTMLElement {
             callbackForwarding: ['connectedCallback', 'disconnectedCallback'],
             getSharedContext(instance) {
                 return {
-                    internals: instance.#internals,
-                    hostPropagator: instance.propagator
+                    internals: instance.#internals
                 };
             }
         }
@@ -510,6 +509,18 @@ customElements.assignFeatures(MyElement, {
 customElements.define('my-element', MyElement);
 ```
 
+Because the feature is a getter-only property, `assignGingerly` merges directly into the instance. The consumer simply sets properties on the feature and the setters handle side effects:
+
+```javascript
+// Direct property access — triggers the setter
+el.myFeature.myProp = 'new value';
+
+// Via assignGingerly — merges into the existing instance
+el.assignGingerly({ myFeature: { myProp: 'new value' } });
+```
+
+This eliminates the need for an intermediate event bus or propagator — property access is the integration point.
+
 **Async features and `callbackForwarding`:**
 
 For async features (where `spawn` is an async function), the feature is instantiated when the async import resolves. Since the constructor already handles initial connection, `callbackForwarding` only needs to forward *subsequent* lifecycle events. If you wrap an async feature around a sync one (lazy-loading pattern), delegate lifecycle calls to the inner feature once it's loaded:

package/types/face-up/types.d.ts

@@ -1,14 +1,12 @@
 import { SpawnContext } from "../assign-gingerly/types";
 
 /**
- * Shared context passed via getSharedContext — contains everything
- * FaceUp needs to manage form association for the host element.
+ * Shared context passed via getSharedContext — contains the
+ * ElementInternals instance needed for form control APIs.
  */
 export interface FaceUpSharedContext {
     /** The ElementInternals instance for form control APIs */
     internals: ElementInternals;
-    /** The EventTarget the host dispatches property change events on */
-    hostPropagator: EventTarget;
 }
 
 /**
@@ -43,6 +41,11 @@ export interface ValidationFlags {
  * Properties that the FaceUp feature exposes.
  * These allow the host custom element to participate in HTML forms
  * via the ElementInternals API.
+ *
+ * Because the feature is installed as a getter-only property,
+ * assignGingerly merges directly into the instance. The consumer
+ * simply sets properties (e.g., el.faceUp.value = x) and the
+ * setters handle syncing to ElementInternals automatically.
  */
 export interface FaceUpProps {
     /**
@@ -72,12 +75,6 @@ export interface FaceUpProps {
      * marks the control as invalid with customError.
      */
     validationMessage: string;
-
-    /**
-     * The EventTarget that the host element uses to propagate property change events.
-     * Provided via getSharedContext.
-     */
-    hostPropagator: EventTarget | null;
 }
 
 /**
@@ -93,11 +90,6 @@ export interface AllProps extends FaceUpProps {
      * The ElementInternals instance from the host (for form control APIs)
      */
     internals: ElementInternals | null;
-
-    /**
-     * AbortController for cleaning up event listeners
-     */
-    abortController: AbortController | null;
 }
 
 export type AP = AllProps;