use-swim-ui

Using Swimlane swim-ui

Use this skill when building custom solutions or widgets for Swimlane Turbine with Swimlane swim-ui (swim-* web components). All UI must use these elements; do not invent tag names or assume other component libraries.

Base and runtime

• Custom elements: Extend SwimlaneElement (from @swimlane/swimlane-element@2), not raw LitElement. Use css, html, svg, unsafeCSS from that package.
• Widget docs: Turbine Widgets — record widgets and report widgets; implementations are web components / custom elements.
• Component source: Full APIs (properties, events, slots) live in projects/swimlane/swim-ui/src/components/<name>/. For precise attribute names and event payloads, read the component .component.ts and index.ts files.

CDN usage (solutions without build)

import { SwimlaneElement, css, html } from '@swimlane/swimlane-element@2';  // or https://esm.sh/@swimlane/swimlane-element@2
import 'https://cdn.jsdelivr.net/gh/surya-pabbineedi/swim-ui@gh-pages/swim-ui.js?v=1';

Ensure the lit specifier is available (e.g. via import map) so the swim-ui bundle resolves. Load SwimlaneElement (or Lit) before the swim-ui bundle.

Attribute naming

• Lit properties are exposed as kebab-case attributes: sectionCollapsed → section-collapsed, closeOnOutsideClick → close-on-outside-click, fontIcon → font-icon.
• Booleans: presence = true; use attribute="false" or close-on-outside-click="false" where the component uses a custom converter for false.

Events

Host-only custom events (confirmed contract)

Swim-ui custom events are dispatched only on the swim-* element host (the custom element node: event.target is that element). They use bubbles: false and composed: false, so they do not propagate to ancestors, document, or past shadow boundaries.

How to listen

• Lit: use @event on the swim-* node that emits it (for example @change on swim-input, @close on swim-dialog), not on a wrapping div expecting the event to bubble up.
• Vanilla: element.addEventListener('change', ...) where element is the swim-* reference from querySelector, ref, or createElement.

Do not rely on event delegation on a parent, document, or window for these custom events—they will not fire there. (Native click on swim-button is separate: it behaves like a normal control.)

Naming: Because custom events stay on the host, conventional names (change, close, open, select, etc.) are safe. If a future API ever required bubbles: true, prefer a non-generic, swim-specific event name to avoid clashes.

Use event.detail for payloads where the component defines it.

Propagation summary (bubbles / composed)

Repro: The swim-ui demo Event propagation (#event-bubbling-matrix) shows swim-checkbox in light DOM vs inside another shadow root.

Per-event reference

Slots

Common patterns:

• Default slot: main content (e.g. swim-card, swim-dialog, swim-drawer, swim-tab body).
• Named slots: slot="header", slot="footer", slot="hint", slot="prefix", slot="suffix", slot="content" (tooltip), slot="label" (tab), slot="avatar", slot="title", slot="subtitle".

Use the component’s JSDoc @slot in projects/swimlane/swim-ui/src/components/<name>/*.component.ts for the exact list.

Imperative APIs

Drawer

• Declarative: <swim-drawer open> plus show() / hide() on the element reference.
• Imperative: openDrawer(options) from @swimlane/swim-ui (or the drawer controller). Options: direction, size, zIndex, closeOnOutsideClick, isRoot, parentContainer, content (HTMLElement | DocumentFragment | string), cssClass. Returns { close(), drawer }. Listen to the drawer’s close event for cleanup.

import { openDrawer } from '@swimlane/swim-ui/drawer';  // or from the CDN bundle if it exports it
const { close, drawer } = openDrawer({ direction: 'left', size: 80, content: fragmentOrElement });
// later: close();

When using the CDN bundle, the drawer may be created with document.createElement('swim-drawer'), set properties, append content, append to body, then call drawer.show() and on close remove from DOM. See projects/swimlane/swim-ui/src/components/drawer/drawer-controller.ts.

Component list (quick reference)

Design and accessibility

• Use lit-elements as-is: no extra visual styling (colors, borders, shadows, typography) on swim-*; only layout (flex, grid, spacing).
• Use design tokens where needed (e.g. --spacing-16, --radius-4 from the demo).
• Preserve semantics and ARIA; ensure labels, focus, and keyboard behavior. See the generate-swimlane-lit-solution skill for full a11y and leak-free rules.

Relationship to generate-swimlane-lit-solution

This skill is the single source for the swim-ui component list, CDN/base usage, design rules, and API (see reference.md). When the task is to generate a full solution file (single .js in projects/swimlane/swim-ui/demo/solutions), apply the generate-swimlane-lit-solution skill for output location, create vs update, WCAG, and no memory leaks; it references use-swim-ui for components and design.

Detailed API reference

For per-component properties, events, slots, and enums, see reference.md and the source under projects/swimlane/swim-ui/src/components/<name>/.