assign-gingerly 0.0.80 → 0.0.82

package/inferencer/types/NewJSFirstCustomElement.md

@@ -0,0 +1,278 @@
+
+
+## Reference Implementations
+
+- **[time-ticker](https://github.com/bahrus/time-ticker)** — A non-visual custom element that fires events periodically. Demonstrates extending `ElementMaker`, a custom feature (`TimeTicker`), roundabout wiring via `defRef.json`, and the `def.js` / `wireFeatures.js` pattern.
+
+
+## Step 5: Create the Element Class, if the complexity is too much for a "code-free" solution, which is probably the reason the custom element is js-first.
+
+
+Create `[element-name].js` (e.g., `my-element.js`):
+
+```javascript
+import { ElementMaker } from 'el-maker/ElementMaker.js';
+
+export class MyElementElement extends ElementMaker {
+    static supportedFeatures = {
+        ...ElementMaker.supportedFeatures,
+        myFeature: {},
+    };
+}
+```
+
+**Key patterns:**
+- Extends `ElementMaker` — inherits `propagator`, `#internals`, `attachInternals()`, and all shared features (`roundabout`, `truthSourcer`, `faceUp`, `reflector`, `templateMaker`)
+- Spreads `ElementMaker.supportedFeatures` to inherit the base feature slots
+- Only declares additional feature slots unique to this element
+- No need for `static formAssociated = true` — `FaceUp.onAssigned` sets it automatically
+- No constructor needed unless you have element-specific initialization
+
+## Optional Step 6: Create the Element-Specific Feature (if any)
+
+If your element has unique behavior beyond what the inherited features provide, but the functionality is more than trivial in implementing, consider creating a custom element feature for that functionality, following [NewCustomElementFeature.md](./NewCustomElementFeature.md).
+
+For example, `time-ticker` has a `TimeTicker.js` feature that provides precise drift-correcting ticking.
+
+If the feature proves useful beyond that one component, it is probably a good idea to move that feature into the el-maker package.
+
+## Step 7: Create defRef.mjs (Roundabout Configuration)
+
+Create `defRef.mjs` — this generates the JSON configuration that drives the roundabout reactive wiring:
+
+```javascript
+//@ts-check
+
+/** @import {RAConfig} from './types/roundabout/types' */
+/** @import {T} from './types/[project-name]/types' */
+/** @import {AttrPatterns} from './types/assign-gingerly/types' */
+
+/**
+ * @type {{ [K in keyof T]: K }}
+ */
+const props = {
+    myProp: 'myProp',
+    disabled: 'disabled',
+    // ... all properties that roundabout manages
+};
+
+/**
+ * @type {RAConfig<T,T,T>}
+ */
+export const raConfig = {
+    propagate: /** @type {Array<keyof T>} */ (Object.keys(props)),
+    compacts: {
+        // Reactive shorthand rules
+    },
+    merges: [
+        // Reactive assignment rules
+    ],
+    yields: {
+        // Derived property rules
+    }
+};
+
+/**
+ * @type {AttrPatterns<T>}
+ */
+const withAttrs = {
+    // Attribute-to-property mappings for truthSourcer
+};
+
+export const cef = {
+    features: {
+        roundabout: {
+            customData: {
+                raConfig
+            },
+            withAttrs
+        }
+    }
+};
+
+export function render() {
+    return JSON.stringify(cef, null, 4);
+}
+
+console.log(render());
+```
+
+**Key patterns:**
+- The `props` object provides type-safe property name references (keys must be in `T`, values must equal the key)
+- `raConfig` defines the reactive wiring: compacts (shorthand rules), merges (assignment rules), yields (derived values)
+- `withAttrs` maps HTML attributes to properties (used by `truthSourcer`)
+- The `render()` function outputs JSON for the build step
+
+Run `npm run build` to generate `defRef.json`.
+
+## Step 8:  build script
+
+Add the following to package.json:
+
+```JSON
+  "scripts": {
+    "build": "node defRef.mjs > defRef.json",
+   ...
+  },
+```
+
+## Step 9: Create wireFeatures.js
+
+This module resolves async fallback spawns and calls `assignFeatures` with the element-specific configuration:
+
+```javascript
+import { MyFeature } from './MyFeature.js';
+import { resolveAndAssignFeatures } from 'assign-gingerly/resolveAndAssignFeatures.js';
+
+export async function wireFeatures(ElementClass, cfg) {
+    const { roundabout } = cfg.features;
+    const { customData, withAttrs } = roundabout;
+
+    await resolveAndAssignFeatures(ElementClass, {
+        myFeature: { spawn: MyFeature },
+        truthSourcer: {
+            callbackForwarding: ['connectedCallback', 'attributeChangedCallback'],
+        },
+        faceUp: {
+            customData: { integrateWithRoundabout: true },
+            callbackForwarding: [
+                'connectedCallback', 'disconnectedCallback',
+                'formDisabledCallback', 'formResetCallback', 'formStateRestoreCallback',
+            ],
+        },
+        roundabout: {
+            customData,
+            withAttrs,
+            callbackForwarding: ['connectedCallback'],
+        },
+    });
+}
+```
+
+**Key patterns:**
+- Only eagerly imports the feature(s) unique to this element
+- Inherited features (`truthSourcer`, `faceUp`, `roundabout`, `reflector`) use their async `fallbackSpawn` from `ElementMaker` — no explicit `spawn` needed
+- `resolveAndAssignFeatures` resolves async fallback spawns before calling `assignFeatures`, ensuring `onAssigned` hooks (like `FaceUp.onAssigned` setting `static formAssociated = true`) run before `define()`
+- `callbackForwarding` and `customData` are per-element configuration that gets unioned with the author defaults from `supportedFeatures`
+
+## Step 10: Create def.js
+
+The side-effect module that registers the custom element with its canonical tag name and default feature wiring:
+
+```javascript
+import { MyElementElement } from './my-element-element.js';
+import { wireFeatures } from './wireFeatures.js';
+import defRef from './defRef.json' with { type: 'json' };
+
+await wireFeatures(MyElementElement, defRef);
+customElements.define('my-element', MyElementElement);
+```
+
+**Key patterns:**
+- `def.js` = "default define" — centralizes all side effects
+- Imports the JSON config and passes it to `wireFeatures`
+- Consumers who want a different tag name, scoped registry, or DI overrides write their own version of this file
+
+
+<details>
+    <summary>Kiro only</summary>
+
+
+## Step 10.5: Set Up Auto-Build Hook
+
+Create `.kiro/hooks/auto-build-config.kiro.hook`:
+
+```json
+{
+    "name": "Auto-build Configuration",
+    "version": "1.0.0",
+    "description": "Automatically runs npm run build when defRef.mjs is saved",
+    "when": {
+        "type": "fileEdited",
+        "patterns": ["**/*.mjs"]
+    },
+    "then": {
+        "type": "askAgent",
+        "prompt": "A .mjs file was changed. Run npm run build to regenerate the output."
+    }
+}
+```
+
+</details>
+
+## Step 11: Create Test HTML
+
+Create `tests/test1.html`:
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Test - my-element</title>
+    <!-- #include virtual="/imports.html" -->
+    <script type=module>
+        import '[project-name]/def.js';
+    </script>
+</head>
+<body>
+    <my-element></my-element>
+</body>
+</html>
+```
+
+
+
+
+
+## Architecture Overview
+
+```
+[project-name]/
+├── .kiro/
+│   ├── hooks/
+│   │   └── auto-build-config.kiro.hook
+│   └── steering/
+│       └── project-context.md
+├── .vscode/
+│   └── settings.json
+├── types/                              (git submodule)
+│   └── [project-name]/
+│       └── types.d.ts
+├── [element-name]-element.js           (element class — extends ElementMaker)
+├── [FeatureName].js                    (element-specific feature, if any)
+├── wireFeatures.js                     (resolves + assigns features)
+├── def.js                              (side-effect: wire + define)
+├── defRef.mjs                          (build script → defRef.json)
+├── defRef.json                         (generated — roundabout config)
+├── imports.html                        (import map for browser)
+├── package.json
+├── tests/
+│   └── test1.html
+└── README.md
+```
+
+## The Three-File Pattern
+
+Every custom element package exports three key modules:
+
+| File | Role | Side effects? |
+|------|------|---------------|
+| `[element-name]-element.js` | Class definition + `supportedFeatures` declaration | No |
+| `wireFeatures.js` | Resolves spawns + calls `assignFeatures` with config | No |
+| `def.js` | Imports config, wires features, calls `define()` | Yes |
+
+This separation enables:
+- **Different tag names** — write your own `def.js` with a different `define()` call
+- **Scoped registries** — call `scopedRegistry.define()` instead of `customElements.define()`
+- **DI / testing** — call `resolveAndAssignFeatures` directly with mock spawns
+- **Declarative definition** — use `defineWithFeatures` from a cede script without any JS class code
+
+## Tips
+
+- **Call `wireFeatures` before `customElements.define()`** — features must be on the prototype before instances exist
+- **Use `@ts-check`** in `.mjs` files — catches type errors in the build configuration
+- **Run `npm run build` after editing `defRef.mjs`** — the JSON must be regenerated
+- **Don't eagerly import inherited features** — let `fallbackSpawn` lazy-load them
+- **Keep `def.js` minimal** — it's the canonical handshake; consumers can deviate as needed

package/inferencer/types/roundabout/types.d.ts

@@ -54,6 +54,7 @@ export type Compacts<TProps = any, TActions = TProps, TEvents extends string = s
     | Partial<{[key in `on_${TEvents}_of_${keyof TProps & string}_inc_${keyof TProps & string}_by`]: number}>
     | Partial<{[key in `on_${TEvents}_of_${keyof TProps & string}_set_${keyof TProps & string}_to`]: any}>
     | Partial<{[key in `on_${TEvents}_of_${keyof TProps & string}_assign`]: Record<string, any>}>
+    | Partial<{[key in `on_${TEvents}_of_${keyof TProps & string}_assignFromEvent`]: Record<string, any>}>
 ;
 
 export type Hitches<TProps = any, TActions = TProps> = 
@@ -160,7 +161,7 @@ export interface RAConfig<
     initialPropVals?: Partial<{[key in keyof TProps & string]: unknown}>,
 }
 
-export interface RoundaboutOptions<TProps = unknown, TActions = TProps, ETProps = TProps> extends RAConfig<TProps, TActions, ETProps> {
+export interface RoundaboutOptions<TProps = unknown, TActions = TProps, ETProps = TProps, EventTypes extends string = string> extends RAConfig<TProps, TActions, ETProps, unknown, EventTypes> {
     vm?: TProps & TActions & RoundaboutReady,
     //for enhanced elements, pass in the container, referenced via $0.
     container?: EventTarget,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "assign-gingerly",
-  "version": "0.0.80",
+  "version": "0.0.82",
   "description": "This package provides a utility function for carefully merging one object into another.",
   "homepage": "https://github.com/bahrus/assign-gingerly#readme",
   "bugs": {