@thefarce/vellum.mods.managers.layouts.simple-web-component

A layout management plugin for the @thefarce/vellum framework, designed to register, push, and pop layouts, as well as manage content within those layouts using a stack-based approach.

Installation

npm install @thefarce/vellum.mods.managers.layouts.simple-web-component

Requires @thefarce/vellum and lit as peer dependencies.

Usage

Import and initialize the plugin within a Vellum application:

import { init } from '@thefarce/vellum.mods.managers.layouts.simple-web-component';

vellumToolkit.dispatchAction({
  type: 'action:register',
  detail: {
    actionType: 'layout:manager:init',
    handler: init,
    modName: 'layout-manager',
  },
});

The plugin registers several actions for managing layouts and content (see API below).

API

The plugin exposes the following actions via the Vellum toolkit.dispatchAction system:

layout:register

Registers a new layout template.

• Detail: { name: string, templateFn: () => Node | string | TemplateResult, slots?: string[] }
• Behavior: Stores the layout in a registry for later use. Ignores invalid inputs (missing name or non-function templateFn).

layout:push

Pushes a registered layout onto the stack, rendering it.

• Detail: { name: string }
• Behavior: Renders the layout using the provided renderer and adds it to the stack. Silently fails if name isn’t registered.

layout:content:append

Appends content to the active layout.

• Detail: { content: Node | string | TemplateResult, id?: string }
• Behavior: Renders content into the active layout’s DOM. Assigns id to the first element if provided.

layout:content:remove

Removes content from the active layout by ID.

• Detail: { id: string }
• Behavior: Removes the element with the specified id from the active layout.

layout:slot:clear

Clears all elements in a specified slot of the active layout.

• Detail: { slot: string }
• Behavior: Removes all elements with with the given slot attribute.

layout:get-active

Retrieves the currently active layout.

• Detail: { callback: (layout: { name: string, content: HTMLElement } | null) => void }
• Behavior: Calls callback with the active layout’s details or null if none exists.

layout:pop

Pops the top layout from the stack.

• Detail: { transferContent?: boolean, callback?: (result: { success: boolean, message?: string, layout?: { name: string, element: HTMLElement }, transferred?: { slot: string, element: HTMLElement }[] }) => void }
• Behavior: Removes the top layout, optionally transferring slotted content to the new active layout. Calls callback with results.

Critique

The following critique is based on an analysis of src/mod-layout-manager.mjs as of March 28, 2025:

Strengths

• Modular Design: Action handlers are cleanly separated, aligning with Vellum’s plugin architecture.
• State Immutability: Uses updateState with spread operators to avoid direct mutations.
• Flexibility: Supports dynamic layout and content management.

Weaknesses

1. State Management:
   • Mutable closure variable state with shallow-copied registry and stack can lead to unintended side effects.
   • No way to inspect state externally.
2. Action Registration:
   • Handlers are tightly coupled to state, reducing testability.
3. Error Handling:
   • Silent failures (e.g., pushing unregistered layouts) hinder debugging.
   • Minimal validation of inputs and renderer outputs.
4. Content Management:
   • Assumes renderer output is valid; doesn’t handle edge cases (e.g., empty content).
   • removeContent relies on unique IDs, ignoring duplicates.
5. Layout Stack Management:
   • Assumes renderer produces a single element, risking errors with unexpected output.
   • No cleanup of popped layouts’ DOM elements, risking memory leaks.
6. Dependencies:
   • Unused uuid dependency suggests incomplete implementation.
7. Testing:
   • Incomplete test suite (mod-layout-manager.test.mjs) lacks coverage for key functionality.
8. Documentation:
   • Lacks detailed comments or examples, making the API harder to understand.

Roadmap

Below is a prioritized list of improvements to enhance reliability, maintainability, and usability. The order reflects a balance of impact and effort:

1. Enhance State Management (High Priority, Medium Effort)

   • Why: Prevents side effects and improves testability.
   • How: Refactor to a reducer pattern, passing state to handlers and returning new states. Add a layout:get-state action for debugging.
   • Estimated Time: 2-3 hours.

2. Improve Error Handling (High Priority, Low Effort)

   • Why: Silent failures frustrate users; better feedback aids debugging.
   • How: Add validation and callbacks for all actions (e.g., report unregistered layouts in pushLayout). Log warnings for edge cases.
   • Estimated Time: 1-2 hours.

3. Expand Testing (High Priority, High Effort)

   • Why: Ensures reliability across use cases and prevents regressions.
   • How: Write unit tests for all actions, covering success and failure cases. Mock toolkit and renderer fully.
   • Estimated Time: 4-6 hours.

4. Refine Content Management (Medium Priority, Medium Effort)

   • Why: Robustness against invalid inputs improves stability.
   • How: Validate content in appendContent, support removal by slot in removeContent, and handle multi-element renderer outputs.
   • Estimated Time: 2-3 hours.

5. Strengthen Layout Stack Management (Medium Priority, Low Effort)

   • Why: Prevents DOM errors and memory leaks.
   • How: Validate renderer output in pushLayout and clean up popped elements in popLayout.
   • Estimated Time: 1-2 hours.

6. Add Documentation (Medium Priority, Low Effort)

   • Why: Improves usability for developers.
   • How: Add JSDoc comments to mod-layout-manager.mjs and expand this README with examples.
   • Estimated Time: 1 hour.

7. Resolve Dependency Issue (Low Priority, Low Effort)

   • Why: Removes confusion and reduces package size.
   • How: Either use uuid for unique IDs or remove it from package.json.
   • Estimated Time: 30 minutes.

Implementation Order

• Week 1: Steps 1 & 2 (State Management, Error Handling) – Core stability improvements.
• Week 2: Step 3 (Testing) – Ensure robustness before further changes.
• Week 3: Steps 4 & 5 (Content & Stack Management) – Refine functionality.
• Week 4: Steps 6 & 7 (Documentation, Dependencies) – Polish and finalize.

Contributing

Feel free to submit issues or pull requests to address the roadmap items or other enhancements. Run tests with:

npm test

License

MIT