generate-swim-from-angular

name: generate-swim-from-angular description: Generate Lit Component from Angular Implementation disable-model-invocation: true

Generate Lit Component from Angular Implementation

Generate a Lit web component in @swimlane/swim-ui that mirrors the design and behavior of an Angular component from @swimlane/ngx-ui. The output must match existing Lit patterns and design system parity.

Input

• Use the Angular component the user has provided, has open, or @-mentioned. If the user typed a component name or path after this command (e.g. /generate-swim-from-angular checkbox), use that as the target.
• Include the component class file (.component.ts), template (.html), and styles (.scss) when converting.

Output Location and Structure

• All new files go under projects/swimlane/swim-ui/src/components/<name>/.
• Generate:
  • <name>.component.ts – main Lit class
  • <name>.styles.ts – component styles (Lit css template)
  • index.ts – re-exports for the component and any enums/interfaces
  • Optional: *.enum.ts, *.interface.ts when the Angular component defines enums or shared types
• Update projects/swimlane/swim-ui/src/index.ts to export the new component (add export * from './components/<name>';).

Reference Implementations (Quality Bar)

Follow these existing Lit components for structure, patterns, and style:

• Button (simpler): projects/swimlane/swim-ui/src/components/button/ – props, state, promise handling, styles
• Input (form control): projects/swimlane/swim-ui/src/components/input/ – form-associated, validation, slots, ElementInternals
• Select (complex): projects/swimlane/swim-ui/src/components/select/ – options, dropdown, filter, form association

Read their .component.ts, .styles.ts, and index.ts to match style and API documentation.

Angular → Lit Mapping

Apply these mappings consistently:

CSS: Colors and Variables

• Do not copy hex or raw color values from the Angular styles. Always use CSS variables from the ngx-ui design system. These are defined in projects/swimlane/swim-ui/src/styles/base.ts (and tokens) and mirror ngx-ui (e.g. var(--blue-500), var(--grey-600), var(--red-500), var(--radius-4), var(--font-size-m)). Refer to ngx-ui's SCSS variables/tokens to pick the correct variable names.
• Never hardcode #..., rgb(...), or rgba(...) for design tokens; use var(--...) so theming and consistency are preserved.

CSS: BEM Naming

• Use BEM (Block__element--modifier) for class names in the Lit component template and styles.
• Block: The component root (e.g. swim-button → class like swim-button or a short block name).
• Element: Descendant, double underscore: block__element (e.g. swim-button__content, swim-button__icon).
• Modifier: State/variant, double hyphen: block__element--modifier or block--modifier (e.g. swim-button--primary, swim-button__icon--spinning).
• Apply BEM classes in the render() template and style them in *.styles.ts so selectors are clear and predictable.

Design System and Quality

• Tokens and base: Use design tokens and baseStyles from projects/swimlane/swim-ui/src/styles/ (and styles/base.ts). Rely on CSS variables (see above); do not introduce new hardcoded colors or spacing that contradict ngx-ui.
• Custom element name: Map ngx-<name> to swim-<name> (e.g. ngx-button → swim-button). Use @customElement('swim-<name>').
• JSDoc: Document public API with @slot, @fires, and @csspart where applicable.
• Form controls: If the Angular component is used in forms, implement static formAssociated = true and use ElementInternals for value and validation (see input and select).
• Follow Accessibility (WCAG) and Performance sections below.

Accessibility (WCAG)

Components must meet WCAG 2.1 expectations so they are usable by keyboard, screen readers, and assistive tech. Apply these consistently:

• Semantics: Use the correct HTML element or ARIA role (e.g. role="button" only when not a <button>, role="tablist" / role="tab" / role="tabpanel", role="combobox", role="listbox").
• ARIA: Preserve or add ARIA from the Angular implementation: aria-label, aria-labelledby, aria-describedby, aria-expanded, aria-selected, aria-controls, aria-disabled, aria-invalid, aria-required, aria-hidden where they convey state or relationships. Keep id / aria-controls / aria-labelledby links valid and stable.
• Keyboard: Full keyboard operation: Tab into the component, Enter/Space to activate buttons and options, Arrow keys for lists/tabs/combos, Escape to close/cancel where appropriate. No keyboard traps; focus moves logically (e.g. roving tabindex or focus management in modals/dropdowns).
• Focus: Visible focus indicator (e.g. :focus-visible with outline) and no outline: none without a visible replacement. When opening overlays or changing active item, move focus as needed (e.g. to first focusable or selected item).
• Labels: All form controls and interactive regions have an accessible name (label, aria-label, or aria-labelledby). Use <label> + id or ElementInternals for form-associated controls.
• State: Expose state to assistive tech (e.g. aria-selected, aria-checked, aria-expanded, aria-disabled) and keep it in sync with the component.
• Contrast: Rely on design tokens for colors; ensure focus/active/disabled states meet contrast requirements (design system should already align with WCAG where applicable).

Performance

Keep components efficient and avoid unnecessary work:

• Property vs state: Use @property() for public API and @state() for internal UI state. Avoid reflecting internal state as attributes unless needed for styling or accessibility.
• Updates: Only trigger requestUpdate() or change properties when data actually changes. In setters, guard with if (this._x !== next) before assigning and dispatching.
• Slot/children: Prefer slot.assignedElements() / slot.assignedNodes() in firstUpdated() or in response to slotchange; avoid querying on every render() or in tight loops.
• Event listeners: Attach in firstUpdated() or connectedCallback(); always remove in disconnectedCallback() (e.g. slotchange, document/window click-outside, resize, drag). Use bound handler references (e.g. this._slotChangeBound = () => this._onSlotChange();) so the same reference can be passed to removeEventListener. Prefer one delegated listener over many per-item listeners where practical.
• Heavy work: Defer non-critical work (e.g. requestAnimationFrame, setTimeout(..., 0)) so initial render stays fast. Avoid synchronous layout thrash (e.g. reading then writing layout properties repeatedly).
• Styles: Keep static styles as shared css template literals; avoid defining new style objects per instance. Reuse baseStyles and component-level css blocks.
• Re-renders: Use updated(changedProperties) to run logic only when specific properties change; avoid side effects in render().

Memory leaks: clean up in disconnectedCallback

To avoid leaks when components are removed from the DOM (e.g. navigation, conditional rendering), every component must clean up in disconnectedCallback():

1. Event listeners

   • Remove any listener added to document, window, or other elements (e.g. slot, child components): use the same bound reference for addEventListener and removeEventListener.
   • Examples: document click-outside, window resize, slot slotchange, handle drag/dblclick, panel mouseenter/mouseleave.
   • If you attach in firstUpdated() to a slot or element from @query, store the element and the bound handler so you can remove in disconnectedCallback().

2. Timers

   • Clear any setTimeout or setInterval (and requestAnimationFrame if recurring): call clearTimeout / clearInterval and set the stored id to undefined.
   • Clear throttle/debounce timeouts so no callback runs after disconnect.

3. Pattern

   • Store handlers as bound class fields (e.g. private _slotChangeBound = () => this._onSlotChange();) so the same reference is used for add and remove.
   • In disconnectedCallback(), remove listeners and clear timers before calling super.disconnectedCallback().

4. Components that add listeners on other elements

   • If the component adds listeners to slotted children or to elements created in firstUpdated() (e.g. overlay panel), keep a reference to that element and the bound handlers, and remove them in disconnectedCallback() (and optionally when the overlay closes, to avoid duplicate listeners on re-open).

Demo design: match Angular demos

Before writing the Lit demo, read the corresponding Angular demo page under the repo root src/app/ so the Lit demo is very close to how the Angular demo is designed.

• Structure: Mirror section order and titles. Angular demos use <ngx-tabs> with "Examples" and "API"; Lit uses <swim-section section-title="..."> for each logical block. Use the same section titles where applicable (e.g. "Demo", "Disabled", "Events and FormGroup", "Usage").
• Content: Use the same labels, option sets, and example text as the Angular demo (e.g. "Alert the SOC" for checkbox, "Attack Type" / Breach, DDOS, Physical for select, button variants in the same order).
• Sections: Include every subsection the Angular demo has (Basic, Variants, Sizes, States table, Interactive, Usage/API). Do not omit variants or states.

Finding the Angular demo (do this dynamically):

Do not rely on a fixed list of component paths. For the component you are converting (e.g. button, checkbox, tooltip):

1. Discover demo pages: Search under the repo root src/app/ for directories named *-page (e.g. src/app/forms/, src/app/components/, src/app/dialogs/, src/app/elements/ contain such folders).
2. Match to this component: Find the demo that showcases the corresponding ngx component by either:
   • Matching folder name to the component (e.g. checkbox → checkbox-page, button → buttons-page, button-group → button-group-page, tooltip → tooltip-page), or
   • Searching for ngx-<name> (e.g. ngx-checkbox, ngx-button) in *.component.html files under src/app/ and opening the file that contains it.
3. Use that Angular demo page's template file (e.g. *-page.component.html) as the single source for section structure, titles, and example content.

This way every component's demo is found the same way and the command stays valid as new Angular demo pages are added.

Steps

1. Identify the target Angular component (from context or user message).
2. Read its class, template, and styles; list all inputs, outputs, content projection, and behavior.
3. Read the corresponding Angular demo page (see Demo design: match Angular demos above) to plan section titles, example content, and interactive behavior.
4. Create the component folder under projects/swimlane/swim-ui/src/components/<name>/.
5. Implement the Lit component, styles, and any enums/interfaces following the mapping, reference components, Accessibility (WCAG), Performance, and Memory leaks: clean up in disconnectedCallback sections.
6. Add index.ts exports and update projects/swimlane/swim-ui/src/index.ts.
7. Add a declare global { interface HTMLElementTagNameMap { 'swim-<name>': ComponentClass; } } block for TypeScript.
8. Add a demo for the new component so it is very close to the Angular demo (see Demo design: match Angular demos):
   • Avoid any inline styles, even in demo templates. Use demo CSS classes from index.html (e.g. .section-divider, .page-title, .section-desc, .demo-row--column, .demo-label--after, .demo-pre).
   • Collapsible panels (swim-section): Use <swim-section section-title="..."> with the same titles as the Angular demo's <ngx-section sectionTitle="..."> blocks. Wrap each <section class="section"> content in <swim-section section-title="...">. Use section-collapsible="false" only when the Angular demo does. Ensure section component is imported in demo/src/main.ts if used.
   • In demo: Add the new component block in projects/swimlane/swim-ui/demo/public/sections/<name>.html. Start the file with <hr class="section-divider"> then <h1 id="component-id" class="page-title">...</h1> and <p class="subtitle">...</p> so the nav link (e.g. href="#checkbox") works. Add <name> to the SECTION_FILES array in demo/src/main.ts. Add a nav link in demo/index.html (e.g. <a class="sub-nav-item" href="#component-id">Label</a> under the appropriate group). Structure of the section file:
     • Divider, then main heading (with id for nav) and subtitle.
     • One or more <section class="section"> with <swim-section section-title="..."> matching Angular section titles, showing: basic usage, all variants/sizes, states (e.g. disabled), interactive example, then Usage with <pre class="demo-pre"><code>...</code></pre> (import + minimal HTML).
   • In demo/src/main.ts: Add component import(s); add <name> to SECTION_FILES if using section files; add any DOMContentLoaded setup (e.g. event listeners, option data) so every interactive demo works.
9. Validate in the browser (see Browser validation below). Fix any broken behavior, then re-validate until the demo works.

Produce a complete, usable Lit component that mirrors the Angular implementation with best quality. Components must be accessible (WCAG 2.1) and efficient in performance; the demo must match the Angular demo design and all demo functionality must work after validation.

Browser validation

After generating the component and demo:

1. Request or use browser access to open the swim-ui demo app (e.g. the URL where the demo runs, such as the dev server for projects/swimlane/swim-ui/demo). If you have a way to open or inspect a browser tab (e.g. Cursor's browser tools or user opening the page), use it.
2. Check every functionality on the new component's demo section:
   • Each variant/size/state renders correctly.
   • All interactive examples work (clicks, form changes, keyboard, toggles, selects, etc.).
   • Any demo logic in demo/src/main.ts (e.g. buttons that set promise, select options, event handlers) is wired correctly and runs without errors in the console.
3. Fix any issues found: correct selectors (e.g. getElementById), event names, property names, or component API usage so the demo behaves as in the Angular version.
4. If browser access is not available or not granted: Tell the user explicitly: "Browser access was not provided, so I could not validate the demo in the browser. Please open the swim-ui demo page, go to the [Component Name] section, and verify that every example and interaction works. If something is broken, share what you see and I'll fix it. You can also grant browser access so I can validate and fix issues directly."
5. Do not mark the task complete until the demo has been validated (by you in the browser or by the user) and any reported issues are fixed.