Generate Swim From Angular

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).