el-maker 0.0.0 → 0.0.1

package/.gitmodules

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

package/ElementMaker.js

@@ -0,0 +1,95 @@
+// @ts-check
+/** @import {SupportedFeaturesMap} from './types/assign-gingerly/types' */
+
+
+/**
+ * ElementMaker — Abstract base custom element class that declares support
+ * for a catalog of composable features via `static supportedFeatures`.
+ *
+ * Concrete elements are defined declaratively (via `defineWithFeatures` or
+ * cede scripts) by selecting which features to activate and providing
+ * per-element configuration — without writing any JavaScript class code.
+ *
+ * Features are lazily instantiated on first property access. Async fallback
+ * spawns ensure implementations are only loaded when a derived element
+ * actually uses them.
+ *
+ * @abstract
+ */
+export class ElementMaker extends HTMLElement {
+    /** @type {EventTarget} */
+    propagator = new EventTarget();
+
+    /** @type {ElementInternals} */
+    #internals;
+
+    /** @type {SupportedFeaturesMap} */
+    static supportedFeatures = {
+        roundabout: {
+            fallbackSpawn: () => import('roundabout-lib/roundaboutFeature.js')
+                .then(m => m.RoundaboutFeature),
+            callbackForwarding: ['connectedCallback'],
+            /** @param {ElementMaker} instance */
+            getSharedContext(instance) {
+                return {
+                    internals: instance.#internals,
+                    hostPropagator: instance.propagator,
+                };
+            },
+        },
+        truthSourcer: {
+            fallbackSpawn: () => import('truth-sourcer/TruthSourcer.js')
+                .then(m => m.TruthSourcer),
+            callbackForwarding: ['connectedCallback', 'attributeChangedCallback'],
+            /** @param {ElementMaker} instance */
+            getSharedContext(instance) {
+                return {
+                    hostPropagator: instance.propagator,
+                };
+            },
+        },
+        faceUp: {
+            fallbackSpawn: () => import('face-up/FaceUp.js')
+                .then(m => m.FaceUp),
+            callbackForwarding: [
+                'connectedCallback',
+                'disconnectedCallback',
+                'formDisabledCallback',
+                'formResetCallback',
+                'formStateRestoreCallback',
+            ],
+            /** @param {ElementMaker} instance */
+            getSharedContext(instance) {
+                return {
+                    internals: instance.#internals,
+                };
+            },
+        },
+        reflector: {
+            fallbackSpawn: () => import('be-reflective/ReflectorLazy.js')
+                .then(m => m.ReflectorLazy),
+            callbackForwarding: ['connectedCallback', 'disconnectedCallback'],
+            /** @param {ElementMaker} instance */
+            getSharedContext(instance) {
+                return {
+                    internals: instance.#internals,
+                    hostPropagator: instance.propagator,
+                };
+            },
+        },
+        templateMaker: {
+            fallbackSpawn: () => import('templ-maker/TemplateMaker.js')
+                .then(m => m.TemplateMaker),
+            callbackForwarding: ['connectedCallback'],
+        },
+    };
+
+    static featuresConfig = {
+        lifecycleKeys: true,
+    };
+
+    constructor() {
+        super();
+        this.#internals = this.attachInternals();
+    }
+}

package/Instructions.md

@@ -0,0 +1,9 @@
+# Instructions
+
+## Human ask
+
+Please become familiar with the documentation in types/NewCustomElementFeature.md (tangentially relevant) and deeply familiar with https://raw.githubusercontent.com/bahrus/assign-gingerly/refs/heads/baseline/docs/defineWithFeatures.md.
+
+Then take a look at the README.md. 
+
+If you then have the confidence to proceed implementing the ElementMaker.js abstract custom element class, please proceed.  Otherwise, post questions below.

package/README.md

@@ -1 +1,105 @@
-# element-maker
+# element-maker
+
+An abstract custom element base class (`ElementMaker`) that bundles a catalog of composable features behind async lazy-loading. Concrete elements are defined declaratively — picking which features to activate and providing per-element configuration — without writing any JavaScript class code.
+
+## How It Works
+
+`ElementMaker` extends `HTMLElement` and declares `static supportedFeatures` with async `fallbackSpawn` functions for each feature. Feature implementations are only imported when a derived element actually uses them, so unused features add zero overhead.
+
+Concrete elements are created via [`defineWithFeatures`](https://github.com/bahrus/assign-gingerly/blob/baseline/docs/defineWithFeatures.md), which:
+
+1. Waits for the base class to be defined
+2. Resolves async fallback spawns in parallel (cached per base class)
+3. Creates a subclass dynamically
+4. Calls `assignFeatures` with the resolved spawns + JSON config
+5. Registers the element
+
+This enables fully declarative element definition from JSON — including from [mount-observer cede scripts](https://github.com/bahrus/mount-observer#custom-element-definition-cede-scripts) embedded in HTML.
+
+## Usage
+
+### From JavaScript
+
+```js
+import { defineWithFeatures } from 'assign-gingerly/defineWithFeatures.js';
+
+await defineWithFeatures('time-ticker', 'el-maker', {
+    assignFeatures: {
+        roundabout: {
+            customData: { raConfig: { actions: {...}, compacts: {...} } },
+            withAttrs: { base: 'tt', duration: '${base}-duration', _duration: { instanceOf: 'Number' } },
+            callbackForwarding: ['connectedCallback']
+        },
+        truthSourcer: {
+            callbackForwarding: ['connectedCallback', 'attributeChangedCallback']
+        },
+        faceUp: {
+            customData: { integrateWithRoundabout: true },
+            callbackForwarding: ['connectedCallback', 'formDisabledCallback', 'formResetCallback', 'formStateRestoreCallback']
+        }
+    }
+});
+```
+
+### From a cede script in HTML
+
+```html
+<time-ticker>
+    <script type="cede" data-extends="el-maker">{
+        "assignFeatures": {
+            "roundabout": {
+                "customData": { "raConfig": { ... } },
+                "withAttrs": { "base": "tt", "duration": "${base}-duration" },
+                "callbackForwarding": ["connectedCallback"]
+            },
+            "truthSourcer": {
+                "callbackForwarding": ["connectedCallback", "attributeChangedCallback"]
+            }
+        }
+    }</script>
+</time-ticker>
+```
+
+## What the Base Class Provides
+
+`ElementMaker` sets up shared infrastructure that features depend on:
+
+| Resource | Purpose |
+|----------|---------|
+| `propagator` (EventTarget) | Property change event bus — used by truthSourcer and reflector to observe value changes |
+| `#internals` (ElementInternals) | Shared via `getSharedContext` with faceUp (form control), reflector (custom states), and roundabout |
+| `static featuresConfig` | Installs `whenFeatureReady()` for awaiting async feature resolution |
+
+Because all spawns are async, defining 10 elements that extend `el-maker` only imports each feature module once — results are cached per base class.
+
+## Feature Catalog
+
+| Package | Description | Source |
+|---------|-------------|--------|
+| [truth-sourcer](https://www.npmjs.com/package/truth-sourcer) | Attribute/property binding and truth-sourcing for custom elements | [GitHub](https://github.com/bahrus/truth-sourcer) |
+| [be-reflective](https://www.npmjs.com/package/be-reflective) | CSS custom state reflection from computed styles | [GitHub](https://github.com/bahrus/be-reflective) |
+| [face-up](https://www.npmjs.com/package/face-up) | Form Associated Custom Element behavior via ElementInternals | [GitHub](https://github.com/bahrus/face-up) |
+| [roundabout-lib](https://www.npmjs.com/package/roundabout-lib) | Reactive view-model binding with template rendering and computed property orchestration | [GitHub](https://github.com/bahrus/roundabout-lib) |
+| [templ-maker](https://www.npmjs.com/package/templ-maker) | Extracts a DOM fragment into a reusable template and clones it per instance (works with cede scripts) | [GitHub](https://github.com/bahrus/templ-maker) |
+
+### Example: time-ticker
+
+[time-ticker](https://github.com/bahrus/time-ticker) demonstrates a fully feature-based component with no code in the element class itself — all behavior comes from the `roundabout` and `timeTicker` features wired via `assignFeatures`.
+
+## Viewing Demos Locally
+
+1. Install git
+2. Fork/clone this repo
+3. Install node.js
+4. Open command window to folder where you cloned this repo
+5. > git submodule add https://github.com/bahrus/types.git types
+6. > git submodule update --init --recursive
+7. > npm install
+8. > npm run serve
+9. Open http://localhost:8000/demo/ in a modern browser
+
+## Running Tests
+
+```
+> npm run test
+```

package/SuggestionForExtending.md

@@ -0,0 +1,131 @@
+# Suggestion for Extending
+
+I like how you made a good call to treat the time-ticker feature as one that probably doesn't belong in an "abstract" class called ElementMaker that serves as general a purpose as element-maker does.  But the explanation provided for separating it out was a bit fuzzy, I think.
+
+The time-ticker package does in fact include both a [custom element feature](https://raw.githubusercontent.com/bahrus/time-ticker/refs/heads/baseline/TimeTicker.js) as well as a [custom element](https://raw.githubusercontent.com/bahrus/time-ticker/refs/heads/baseline/time-ticker-element.js).
+
+I would like to go back to that package, and make the custom element extend ElementMaker from this package so that the static features get "inherited" somehow, and add on the time-ticker package.  I guess there could be a separate file that could be referenced as an old-fashioned module that registers the custom element name, similar to [def.js](https://raw.githubusercontent.com/bahrus/time-ticker/refs/heads/baseline/def.js)
+
+After studying these links carefully, can you spell out what to do below, and I will then copy this file into that project and ask kiro to make the necessary adjustments.
+
+---
+
+## Instructions for Converting time-ticker to Extend ElementMaker
+
+### Overview
+
+Currently `time-ticker-element.js` is a standalone `HTMLElement` subclass that manually redeclares `propagator`, `#internals`, `attachInternals()`, and `static supportedFeatures` entries for `truthSourcer`, `faceUp`, and `roundabout`. All of that is already provided by `ElementMaker`. The goal is to:
+
+1. Extend `ElementMaker` instead of `HTMLElement`
+2. Inherit all of ElementMaker's features automatically
+3. Only declare the *additional* feature (`timeTicker`) that is specific to this package
+4. Simplify `wireFeatures.js` to only inject what's unique to this element
+5. Keep `def.js` as the side-effect module that registers the tag name
+
+### Step 1: Add `el-maker` as a dependency
+
+In `package.json`, add:
+
+```json
+"dependencies": {
+    "el-maker": "0.0.0"
+}
+```
+
+Also add it to `imports.html`:
+
+```html
+"el-maker/": "/node_modules/el-maker/"
+```
+
+### Step 2: Rewrite `time-ticker-element.js`
+
+Replace the entire file with:
+
+```js
+import { ElementMaker } from 'el-maker/ElementMaker.js';
+
+export class TimeTickerElement extends ElementMaker {
+    static supportedFeatures = {
+        ...ElementMaker.supportedFeatures,
+        timeTicker: {},
+    };
+}
+```
+
+Key points:
+- Extends `ElementMaker` instead of `HTMLElement`
+- No need to redeclare `propagator`, `#internals`, or `constructor` — inherited from `ElementMaker`
+- No need to redeclare `truthSourcer`, `faceUp`, `roundabout`, or `reflector` — inherited via the spread of `ElementMaker.supportedFeatures`
+- Only adds the `timeTicker` slot, which is specific to this package
+- `static formAssociated = true` is no longer needed here — `FaceUp.onAssigned` sets it automatically when `faceUp` is wired via `assignFeatures`
+
+### Step 3: Simplify `wireFeatures.js`
+
+The current `wireFeatures.js` eagerly imports all feature classes (RoundaboutFeature, TruthSourcer, FaceUp) and passes them as explicit `spawn` values. Since `ElementMaker` already declares async `fallbackSpawn` for all of those, you only need to provide:
+
+- The `timeTicker` spawn (unique to this package)
+- The `roundabout` config (`customData`, `withAttrs`) that comes from the cef.json
+- Any `callbackForwarding` or `customData` overrides specific to this element
+
+```js
+import { TimeTicker } from './TimeTicker.js';
+import 'assign-gingerly/assignFeatures.js';
+
+export async function wireFeatures(ElementClass, cfg) {
+    const { roundabout } = cfg.features;
+    const { customData, withAttrs } = roundabout;
+
+    await customElements.assignFeatures(ElementClass, {
+        timeTicker: { spawn: TimeTicker },
+        truthSourcer: {
+            callbackForwarding: ['connectedCallback', 'attributeChangedCallback'],
+        },
+        faceUp: {
+            customData: { integrateWithRoundabout: true },
+            callbackForwarding: [
+                'connectedCallback', 'disconnectedCallback',
+                'formDisabledCallback', 'formResetCallback', 'formStateRestoreCallback',
+            ],
+        },
+        roundabout: {
+            customData,
+            withAttrs,
+            callbackForwarding: ['connectedCallback'],
+        },
+    });
+}
+```
+
+Key changes:
+- Removed all explicit `spawn` entries for `truthSourcer`, `faceUp`, and `roundabout` — the async `fallbackSpawn` from `ElementMaker.supportedFeatures` will be used instead
+- Removed the eager imports of `RoundaboutFeature`, `TruthSourcer`, and `FaceUp` — they'll be lazy-loaded on first access
+- Still pass `callbackForwarding` and `customData` since those are per-element configuration (the consumer additions get unioned with the author defaults from `supportedFeatures`)
+
+### Step 4: `def.js` stays the same
+
+```js
+import { TimeTickerElement } from './time-ticker-element.js';
+import { wireFeatures } from './wireFeatures.js';
+import defRef from './defRef.json' with { type: 'json' };
+
+await wireFeatures(TimeTickerElement, defRef);
+customElements.define('time-ticker', TimeTickerElement);
+```
+
+No changes needed.
+
+### Step 5: Remove redundant dependencies
+
+Since `ElementMaker` brings in `truth-sourcer`, `face-up`, `be-reflective`, and `roundabout-lib` as its own dependencies, you can remove them from time-ticker's `package.json` dependencies (they'll be available transitively). Keep only:
+
+- `el-maker` (brings everything)
+- `assign-gingerly` (needed for `assignFeatures.js` import)
+- Any test/dev dependencies
+
+### Benefits
+
+1. **Less boilerplate** — no manual `propagator`, `#internals`, `attachInternals()`, or `getSharedContext` declarations per element
+2. **Lazy loading** — feature implementations are only imported when actually accessed, not eagerly at module load time
+3. **Consistency** — all elements extending `ElementMaker` get the same shared context wiring, reducing bugs from copy-paste divergence
+4. **Extensibility** — if a new feature is added to `ElementMaker` later, all extending elements inherit it automatically

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "el-maker",
-  "version": "0.0.0",
+  "version": "0.0.1",
   "description": "",
   "homepage": "https://github.com/bahrus/element-maker#readme",
   "bugs": {
@@ -13,8 +13,24 @@
   "license": "MIT",
   "author": "Bruce B. Anderson <anderson.bruce.b@gmail.com>",
   "type": "module",
-  "main": "index.js",
+  "main": "ElementMaker.js",
   "scripts": {
-    "test": "playwright test"
+    "build": "node emc.mjs > emc.json && node ⏻.mjs > ⏻.json",
+    "serve": "node ./node_modules/spa-ssi/serve.js",
+    "test": "playwright test",
+    "safari": "npx playwright wk http://localhost:8000",
+    "update": "ncu -u && npm install"
+  },
+  "dependencies": {
+    "be-reflective": "0.0.3",
+    "face-up": "0.0.4",
+    "roundabout-lib": "0.0.20",
+    "templ-maker": "0.0.1",
+    "truth-sourcer": "0.0.3",
+    "time-ticker": "0.0.31"
+  },
+  "devDependencies": {
+    "spa-ssi": "0.0.27",
+    "@playwright/test": "1.60.0"
   }
 }

package/types/.kiro/specs/conversion-template/README.md

@@ -0,0 +1,128 @@
+# Conversion Template
+
+This spec template provides a structured approach to converting legacy be-* enhancement projects to the modern architecture.
+
+## When to Use This Template
+
+Use this template when:
+- You want to track conversion progress step-by-step
+- You're converting a be-* project for the first time
+- You want to review each step before proceeding
+- Multiple people are involved in the conversion
+- You want a record of the conversion process
+
+## How to Use This Template
+
+### Option 1: Copy to Project (Recommended)
+
+1. Copy this entire folder to your project's `.kiro/specs/` directory:
+   ```bash
+   cp -r types/.kiro/specs/conversion-template .kiro/specs/conversion-[project-name]
+   ```
+
+2. Update placeholders in all files:
+   - Replace `[PROJECT_NAME]` with your project name (e.g., "be-clonable")
+   - Replace `[project-name]` with kebab-case name (e.g., "be-clonable")
+   - Replace `[ClassName]` with PascalCase name (e.g., "BeClonable")
+   - Replace `[emoji]` with actual emoji if applicable (e.g., "⿻")
+
+3. Work through the tasks in `tasks.md` sequentially
+
+4. Use Kiro to execute tasks: "execute task 1", "execute task 2", etc.
+
+### Option 2: Use as Reference
+
+Simply reference this template while doing a manual conversion:
+- Follow the requirements in `requirements.md`
+- Understand the architecture from `design.md`
+- Use `tasks.md` as a checklist
+
+## Template Structure
+
+### requirements.md
+- User stories for each conversion step
+- Correctness properties to verify
+- Success criteria
+- Non-functional requirements
+
+### design.md
+- Architecture overview with diagrams
+- Component design for each file type
+- Data flow explanations
+- Design decisions and rationale
+- Alternatives considered
+
+### tasks.md
+- Detailed task breakdown (11 major tasks, 60+ subtasks)
+- Task dependencies
+- Execution notes for each step
+- Reference to ConversionInstructions.md
+
+## Key Features
+
+### Comprehensive Coverage
+All 10 conversion steps from ConversionInstructions.md are covered with detailed subtasks
+
+### Verification Built-in
+Task 11 provides comprehensive verification steps to ensure conversion success
+
+### Reference Integration
+All files reference ConversionInstructions.md for detailed step-by-step instructions
+
+### Kiro-Optimized
+- Uses file references: `#[[file:../../ConversionInstructions.md]]`
+- Task format compatible with Kiro's task execution
+- Structured for spec-driven development workflow
+
+## Example Usage with Kiro
+
+```
+User: "I want to convert be-clonable to the modern architecture"
+
+Kiro: "I can help you with that. Would you like to:
+1. Create a tracked conversion spec (recommended for first-time conversions)
+2. Do a direct conversion (faster, for experienced users)
+
+User: "Create a spec"
+
+Kiro: [Creates spec from template, updates placeholders]
+      "I've created a conversion spec at .kiro/specs/conversion-be-clonable/
+       Let's start with Task 1: Migrate Type Definitions. Ready to begin?"
+
+User: "Yes"
+
+Kiro: [Executes Task 1, marks subtasks complete]
+      "Task 1 complete. Type definitions migrated to types/be-clonable/.
+       Ready for Task 2: Archive Legacy Implementation?"
+```
+
+## Success Criteria
+
+A successful conversion using this template should result in:
+- ✅ All tasks marked complete
+- ✅ `npm run build` succeeds
+- ✅ `npm test` passes
+- ✅ No TypeScript errors
+- ✅ Legacy code preserved in legacy/ folder
+- ✅ Modern architecture verified
+
+## Related Files
+
+- `../../ConversionInstructions.md` - Detailed step-by-step instructions
+- `../../.kiro/steering/conversion-guide.md` - Kiro steering guidance
+- Reference implementations:
+  - [be-a-beacon](https://github.com/bahrus/be-a-beacon)
+  - [be-committed](https://github.com/bahrus/be-committed)
+  - [be-decked-with](https://github.com/bahrus/be-decked-with)
+
+## Customization
+
+Feel free to customize this template for your specific needs:
+- Add project-specific tasks
+- Modify verification steps
+- Add additional correctness properties
+- Extend design documentation
+
+## Feedback
+
+If you find issues with this template or have suggestions for improvement, please update the template in the types repository so all projects benefit.