face-up 0.0.0 → 0.0.1

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

@@ -0,0 +1,174 @@
+# Tasks: Convert [PROJECT_NAME] to Modern Architecture
+
+## Task List
+
+- [ ] 1. Migrate Type Definitions
+  - [ ] 1.1 Check if ts-refs folder exists
+  - [ ] 1.2 Copy ts-refs/[project-name] to types/[project-name]
+  - [ ] 1.3 Delete ts-refs folder
+  - [ ] 1.4 Verify types accessible at new location
+
+- [ ] 2. Archive Legacy Implementation
+  - [ ] 2.1 Create legacy folder if needed
+  - [ ] 2.2 Empty legacy folder if it exists
+  - [ ] 2.3 Move all .js files to legacy (except package*.json)
+  - [ ] 2.4 Move all .mjs files to legacy
+  - [ ] 2.5 Move all .json files to legacy (except package*.json)
+  - [ ] 2.6 Verify legacy folder contains complete implementation
+
+- [ ] 3. Update package.json
+  - [ ] 3.1 Update scripts section with build, serve, test, safari, update
+  - [ ] 3.2 Update dependencies to be-hive, mount-observer, and roundabout-lib
+  - [ ] 3.3 Update devDependencies to @playwright/test and spa-ssi
+  - [ ] 3.4 Run npm run update
+  - [ ] 3.5 Verify npm install succeeds
+
+- [ ] 4. Configure Import Maps
+  - [ ] 4.1 Create or replace imports.html
+  - [ ] 4.2 Add assign-gingerly mapping
+  - [ ] 4.3 Add project mapping to "/"
+  - [ ] 4.4 Add be-hive mapping
+  - [ ] 4.5 Add mount-observer mapping
+  - [ ] 4.6 Add roundabout-lib mapping
+
+- [ ] 5. Establish Coding Standards
+  - [ ] 5.1 Create .kiro/steering directory
+  - [ ] 5.2 Create coding-standards.md
+  - [ ] 5.3 Document import map conventions
+  - [ ] 5.4 Document file extension conventions
+  - [ ] 5.5 Document TypeScript support conventions
+
+- [ ] 6. Modernize Type Definitions
+  - [ ] 6.1 Open types/[project-name]/types.d.ts
+  - [ ] 6.2 Remove import statements
+  - [ ] 6.3 Remove extends IEnhancement from EndUserProps
+  - [ ] 6.4 Add enhancedElement: Element to AllProps
+  - [ ] 6.5 Remove BAP type alias
+  - [ ] 6.6 Replace BAP with AP in Actions interface
+  - [ ] 6.7 Verify no TypeScript errors
+
+- [ ] 7. Create Build Configuration
+  - [ ] 7.1 Create emc.mjs file
+  - [ ] 7.2 Add imports and type annotations
+  - [ ] 7.3 Configure enhConfig with enhKey and spawn
+  - [ ] 7.4 Configure withAttrs for attribute mapping
+  - [ ] 7.5 Add weakRef configuration with enhancedElement
+  - [ ] 7.6 Copy actions from legacy static config to customData
+  - [ ] 7.7 Add 'enhancedElement' to ifAllOf for actions that reference it
+  - [ ] 7.8 Copy handlers from legacy static config to customData
+  - [ ] 7.9 Copy compacts from legacy static config to customData
+  - [ ] 7.10 Add render function
+  - [ ] 7.11 Add console.log(render())
+  - [ ] 7.12 Test build: npm run build (should generate emc.json)
+
+- [ ] 8. Configure VS Code
+  - [ ] 8.1 Create .vscode folder if needed
+  - [ ] 8.2 Create or open .vscode/settings.json
+  - [ ] 8.3 Add file nesting patterns
+  - [ ] 8.4 Enable file nesting
+  - [ ] 8.5 Verify JSON files nest under .mjs files in explorer
+
+- [ ] 8a. Configure Auto-Build Hook (Optional)
+  - [ ] 8a.1 Create .kiro/hooks folder if needed
+  - [ ] 8a.2 Create auto-build-config.kiro.hook
+  - [ ] 8a.3 Configure fileEdited event for emc.mjs and emoji .mjs
+  - [ ] 8a.4 Configure runCommand action with npm run build
+  - [ ] 8a.5 Test by saving emc.mjs and verifying JSON regenerates
+
+- [ ] 9. Create Modern Enhancement Class
+  - [ ] 9.1 Create be-[project-name].js file
+  - [ ] 9.2 Add imports (emc.json with type annotation, types)
+  - [ ] 9.3 Add class declaration
+  - [ ] 9.4 Add constructor with enhancedElement, ctx, initVals parameters
+  - [ ] 9.5 Add init method with enhancedElement parameter
+  - [ ] 9.6 Add roundabout integration in init
+  - [ ] 9.7 Add enhancedElement to assignGingerly call
+  - [ ] 9.8 Add default values to init via assignGingerly
+  - [ ] 9.9 Copy action methods from legacy
+  - [ ] 9.10 Replace BAP with AP in all methods
+  - [ ] 9.11 Remove legacy imports
+  - [ ] 9.12 Export class
+  - [ ] 9.13 Verify no TypeScript errors
+
+- [ ] 10. Create Emoji Shorthand (Optional)
+  - [ ] 10.1 Check README for emoji in title
+  - [ ] 10.2 Create [emoji].mjs file (if emoji exists)
+  - [ ] 10.3 Import emc.json
+  - [ ] 10.4 Configure enhConfig override
+  - [ ] 10.5 Add render function
+  - [ ] 10.6 Add console.log(render())
+  - [ ] 10.7 Test build: npm run build (should generate [emoji].json)
+
+- [ ] 11. Verification
+  - [ ] 11.1 Run npm run build (should succeed)
+  - [ ] 11.2 Verify emc.json generated
+  - [ ] 11.3 Verify [emoji].json generated (if applicable)
+  - [ ] 11.4 Run npm test (should pass)
+  - [ ] 11.5 Check for TypeScript errors
+  - [ ] 11.6 Verify legacy folder is complete
+  - [ ] 11.7 Compare behavior with legacy implementation
+
+## Task Dependencies
+
+```
+1 (Types) → 6 (Modernize Types)
+2 (Archive) → 7 (Build Config), 9 (Enhancement Class)
+3 (package.json) → 7 (Build Config)
+4 (imports.html) → 9 (Enhancement Class)
+5 (Standards) → 9 (Enhancement Class)
+6 (Types) → 7 (Build Config), 9 (Enhancement Class)
+7 (Build Config) → 9 (Enhancement Class), 10 (Emoji)
+8 (VS Code) → (no dependencies, can be done anytime)
+9 (Enhancement Class) → 11 (Verification)
+10 (Emoji) → 11 (Verification)
+```
+
+## Execution Notes
+
+### Step 1: Migrate Type Definitions
+- Check for ts-refs folder first
+- If not found, types may already be migrated
+- Verify types are accessible after migration
+
+### Step 2: Archive Legacy Implementation
+- This is critical - don't skip
+- Verify all files are moved before proceeding
+- Keep package.json and package-lock.json in root
+
+### Step 3: Update package.json
+- Note the emoji in README title for build script
+- If no emoji, omit the emoji build command
+- npm run update will fetch latest versions
+
+### Step 7: Create Build Configuration
+- Reference legacy emc.js for base/branches/map
+- Reference legacy be-*.js static config for actions/handlers/compacts
+- Add weakRef configuration with enhancedElement at minimum
+- For actions with ifAllOf, add 'enhancedElement' if the method code references it
+- Don't copy propDefaults or propInfo
+- Test the build immediately after creating
+
+### Step 9: Create Modern Enhancement Class
+- No WeakRef boilerplate needed - roundabout handles it
+- Constructor passes enhancedElement to init method
+- Init method receives enhancedElement as parameter
+- Add enhancedElement to assignGingerly call before other defaults
+- Copy action methods carefully
+- Replace all BAP with AP
+- Keep method implementations the same
+- Remove any be-enhanced specific code
+
+### Step 10: Create Emoji Shorthand
+- Only if emoji exists in README title
+- Very simple - just overrides enhKey and base
+- Test build to verify JSON generation
+
+### Step 11: Verification
+- This is the final validation
+- All tests should pass
+- Build should succeed
+- No TypeScript errors
+
+## Reference
+
+For detailed instructions on each step, see: `#[[file:../../ConversionInstructions.md]]`

package/types/.kiro/steering/coding-standards.md

@@ -0,0 +1,17 @@
+# Coding Standards
+
+## JavaScript Module Conventions
+
+### Import Maps
+- Use import maps with explicit, bare specifiers ending with `*.js` for all JavaScript references that run in the browser
+- Example: `"be-hive/": "/node_modules/be-hive/"`
+
+### File Extensions
+- Use `*.mjs` files exclusively for npm build scripts, not for browser code
+- Use `*.js` files (not `*.ts`) for all browser-executable code
+- Enable TypeScript support in `*.js` files via `@ts-check` directive at the top of files
+
+### TypeScript Support
+- Add `// @ts-check` at the beginning of JavaScript files to enable TypeScript checking
+- Use JSDoc comments for type annotations when needed
+- Leverage type definitions from the `types` submodule

package/types/.kiro/steering/conversion-guide.md

@@ -0,0 +1,103 @@
+# be-* Enhancement Conversion Guide
+
+## Purpose
+
+This steering file provides guidance for converting legacy "be-*" enhancement projects to the modern architecture. When a user requests help with converting a be-* project, use this guide to structure the conversion process.
+
+**Important:** This guide is specifically for **enhancements** (declarative behaviors added to existing HTML elements via attributes). It does NOT apply to custom elements.
+
+## Reference Documentation
+
+- **Converting legacy enhancements:** `EnhancementConversionInstructions.md` in the types repository root
+- **Creating new enhancements from scratch:** `NewEnhancementInstructions.md` in the types repository root
+
+Always reference the appropriate document based on whether the project is a legacy conversion or a brand new enhancement.
+
+## Conversion Approach
+
+### When to Use Spec-Based Conversion
+
+For systematic, trackable conversions, create a spec using the conversion template:
+- User wants to track progress through the conversion
+- User wants to review each step before proceeding
+- User is learning the conversion process
+- Multiple people are involved in the conversion
+
+### When to Use Direct Conversion
+
+For quick, automated conversions:
+- User is familiar with the conversion process
+- User wants rapid execution without step-by-step review
+- The project is straightforward with no special cases
+
+## Key Principles
+
+1. **Preserve Legacy Code**: Always move existing implementation to the `legacy` folder before making changes
+2. **Follow the Order**: The conversion steps have dependencies - follow them in sequence
+3. **Verify Each Step**: After each major step, verify the changes work as expected
+4. **Reference Examples**: Point to **be-clonable** (most up-to-date), be-committed, and be-decked-with as reference implementations. Prefer be-clonable as it has the latest architectural improvements. Note: be-a-beacon is too simple to serve as a good example - it doesn't use roundabout due to its minimal requirements.
+
+## Common Patterns
+
+### Project Structure Recognition
+
+Identify legacy projects by these characteristics:
+- Has `be-enhanced` or `trans-render` dependencies
+- Class extends `BE` from be-enhanced
+- Has static `config` object in the enhancement class
+- Uses `emc.js` with `base`, `branches`, `map` pattern
+- Has `ts-refs` submodule for types
+
+### Modern Architecture Indicators
+
+Recognize already-converted projects by:
+- Has `be-hive` and `roundabout-lib` dependencies
+- Has `emc.mjs` build script
+- Has `types` submodule (not `ts-refs`)
+- Class doesn't extend anything
+- Uses constructor with `enhancedElement`, `ctx`, `initVals` parameters
+
+## Conversion Workflow
+
+When a user asks to convert a be-* project:
+
+1. **Assess the project**: Determine if it's legacy or already converted
+2. **Offer spec creation**: Ask if they want a tracked conversion (spec) or direct conversion
+3. **Execute systematically**: Follow the 10 steps in ConversionInstructions.md
+4. **Run npm run update**: After Step 3 (updating package.json), ALWAYS run `npm run update` to install dependencies before proceeding
+5. **Verify at milestones**: After steps 3, 7, and 10, suggest running `npm run build` and `npm test`
+6. **Reference the guide**: Point users to specific sections of ConversionInstructions.md as needed
+7. **Use be-clonable as reference**: When implementation details are unclear, refer to [be-clonable](https://github.com/bahrus/be-clonable) as it has the most refined patterns
+
+## Special Cases
+
+### No Emoji Shorthand
+If the README doesn't have an emoji in the title:
+- Skip Step 10 (emoji .mjs creation)
+- Update package.json build script to only generate emc.json
+
+### Complex Static Config
+If the legacy static config has unusual patterns:
+- Carefully map `propDefaults` to the init method
+- Preserve any custom logic in action methods
+- Document any patterns that don't fit the standard conversion
+
+### Custom Dependencies
+If the project uses trans-render utilities:
+- Keep those imports in the action methods
+- Don't remove them unless they're only used in static config
+
+## Success Criteria
+
+A successful conversion should:
+- ✅ Build without errors (`npm run build`)
+- ✅ Pass existing tests (`npm test`)
+- ✅ Have all legacy files in the `legacy` folder
+- ✅ Have modern architecture files (emc.mjs, be-*.js, types)
+- ✅ Have updated dependencies (be-hive, roundabout-lib)
+- ✅ Generate valid JSON configuration files
+
+## File Reference
+
+Always reference `#[[file:EnhancementConversionInstructions.md]]` for the complete step-by-step conversion instructions.
+For new enhancements, reference `#[[file:NewEnhancementInstructions.md]]`.

package/types/.kiro/steering/declarative-configuration.md

@@ -0,0 +1,108 @@
+# Declarative Configuration Principle
+
+## Overview
+
+Move as much "code" out of JavaScript into JSON configuration as possible. JSON is faster to parse than JavaScript, and declarative configuration makes the code more maintainable and easier to understand.
+
+## When to Apply
+
+This principle applies when:
+- Creating or configuring DOM elements with known properties
+- Setting element attributes, classes, or other properties
+- The logic is primarily about setting values rather than complex computation
+
+## Pattern: Element Creation Settings
+
+Instead of imperatively creating and configuring elements in JavaScript:
+
+```javascript
+// ❌ Imperative approach
+async addDeleteBtn(self){
+    // ... find or create trigger ...
+    if(trigger === null){
+        trigger = document.createElement('button');
+        trigger.type = 'button';
+        trigger.classList.add('be-delible-trigger');
+        trigger.ariaLabel = 'Delete this.';
+        trigger.title = 'Delete this.';
+        enhancedElement.insertAdjacentElement(triggerInsertPosition, trigger);
+    }
+    return { trigger: new WeakRef(trigger), byob };
+}
+```
+
+Move the configuration to JSON in emc.mjs:
+
+```javascript
+// ✅ Declarative approach in emc.mjs
+customData: {
+    customData: {
+        triggerSettings: {
+            type: 'button',
+            '?.classList?.add': 'be-delible-trigger',
+            ariaLabel: 'Delete this.',
+            title: 'Delete this.',
+        },
+        withMethods: ['add']
+    }
+}
+```
+
+Then use assignGingerly to apply the settings:
+
+```javascript
+// ✅ Simplified JavaScript
+async addDeleteBtn(self) {
+    // ... find or create trigger ...
+    if (trigger === null) {
+        trigger = document.createElement('button');
+        const {triggerSettings, withMethods} = customData.customData;
+        (await import('assign-gingerly/assignGingerly.js')).assignGingerly(trigger, triggerSettings, {withMethods});
+        enhancedElement.insertAdjacentElement(triggerInsertPosition, trigger);
+    }
+    return { trigger, resolved: true, byob };
+}
+```
+
+## Benefits
+
+1. **Performance**: JSON parsing is faster than JavaScript execution
+2. **Maintainability**: Configuration is centralized and easier to modify
+3. **Clarity**: Declarative intent is clearer than imperative code
+4. **Separation of concerns**: Configuration is separate from logic
+
+## assignGingerly Special Syntax
+
+The `assignGingerly` utility supports special property syntax:
+
+- `'?.classList?.add'`: Safely calls `classList.add()` method
+- `'?.classList?.remove'`: Safely calls `classList.remove()` method
+- `'?.classList?.toggle'`: Safely calls `classList.toggle()` method
+- Use `withMethods` option to specify which methods to enable (e.g., `{withMethods: ['add', 'remove']}`)
+
+## WeakRef Handling
+
+When using roundabout's `weakRef.properties` configuration:
+
+- Properties listed in `weakRef.properties` are automatically wrapped in WeakRef by roundabout
+- In your action methods, access these properties directly (roundabout unwraps them automatically)
+- Return the raw element reference, not `new WeakRef(element)` - roundabout handles the wrapping
+
+```javascript
+// ✅ Correct - return raw element
+return { trigger, resolved: true, byob };
+
+// ❌ Wrong - don't manually wrap in WeakRef
+return { trigger: new WeakRef(trigger), resolved: true, byob };
+```
+
+## When NOT to Apply
+
+Don't force declarative configuration when:
+- The logic involves complex conditionals or computations
+- The configuration depends on runtime state that can't be known at build time
+- The imperative code is actually clearer and simpler
+
+## Reference Implementation
+
+See [be-clonable](https://github.com/bahrus/be-clonable/blob/baseline/emc.mjs) for a complete example of this pattern in action.