luxen-ui 0.6.2 → 0.8.0

package/dist/shared/controllers/has-slot-controller.d.ts

@@ -0,0 +1,37 @@
+import type { ReactiveController, ReactiveControllerHost } from 'lit';
+/**
+ * Reactive controller that tracks whether one or more slots have content, and
+ * requests a host update whenever that changes. Lets a template react to empty
+ * slots — e.g. collapse a footer row when nothing is slotted into it.
+ *
+ * Drives this off `slotchange` rather than a CSS selector because
+ * `:host(:has(> [slot='name']))` is invalid (`:has()` can't be nested inside
+ * `:host()`, so browsers drop the whole rule). Pair it with a data-attribute:
+ *
+ * ```ts
+ * private _slots = new HasSlotController(this, 'footer');
+ *
+ * render() {
+ *   return html`
+ *     <footer part="footer" ?data-empty=${!this._slots.test('footer')}>
+ *       <slot name="footer"></slot>
+ *     </footer>
+ *   `;
+ * }
+ * ```
+ *
+ * Pass `'[default]'` to test the default (unnamed) slot.
+ */
+export declare class HasSlotController implements ReactiveController {
+    private host;
+    private slotNames;
+    constructor(host: ReactiveControllerHost & Element, ...slotNames: string[]);
+    /** Whether the given slot currently has content. Use `'[default]'` for the default slot. */
+    test(slotName: string): boolean;
+    private hasNamedSlot;
+    private hasDefaultSlot;
+    private handleSlotChange;
+    hostConnected(): void;
+    hostDisconnected(): void;
+}
+//# sourceMappingURL=has-slot-controller.d.ts.map

package/dist/shared/controllers/has-slot-controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"has-slot-controller.d.ts","sourceRoot":"","sources":["../../../src/html/shared/controllers/has-slot-controller.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,KAAK,CAAC;AAEtE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,iBAAkB,YAAW,kBAAkB;IAC1D,OAAO,CAAC,IAAI,CAAmC;IAC/C,OAAO,CAAC,SAAS,CAAW;gBAEhB,IAAI,EAAE,sBAAsB,GAAG,OAAO,EAAE,GAAG,SAAS,EAAE,MAAM,EAAE;IAM1E,4FAA4F;IAC5F,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAM/B,OAAO,CAAC,YAAY;IAMpB,OAAO,CAAC,cAAc;IAYtB,OAAO,CAAC,gBAAgB,CAMtB;IAEF,aAAa;IAIb,gBAAgB;CAGjB"}

package/dist/shared/controllers/has-slot-controller.js

@@ -0,0 +1,66 @@
+/**
+ * Reactive controller that tracks whether one or more slots have content, and
+ * requests a host update whenever that changes. Lets a template react to empty
+ * slots — e.g. collapse a footer row when nothing is slotted into it.
+ *
+ * Drives this off `slotchange` rather than a CSS selector because
+ * `:host(:has(> [slot='name']))` is invalid (`:has()` can't be nested inside
+ * `:host()`, so browsers drop the whole rule). Pair it with a data-attribute:
+ *
+ * ```ts
+ * private _slots = new HasSlotController(this, 'footer');
+ *
+ * render() {
+ *   return html`
+ *     <footer part="footer" ?data-empty=${!this._slots.test('footer')}>
+ *       <slot name="footer"></slot>
+ *     </footer>
+ *   `;
+ * }
+ * ```
+ *
+ * Pass `'[default]'` to test the default (unnamed) slot.
+ */
+export class HasSlotController {
+    constructor(host, ...slotNames) {
+        this.handleSlotChange = (event) => {
+            const slot = event.target;
+            const watched = slot.name
+                ? this.slotNames.includes(slot.name)
+                : this.slotNames.includes('[default]');
+            if (watched)
+                this.host.requestUpdate();
+        };
+        this.host = host;
+        this.slotNames = slotNames;
+        host.addController(this);
+    }
+    /** Whether the given slot currently has content. Use `'[default]'` for the default slot. */
+    test(slotName) {
+        return slotName === '[default]' ? this.hasDefaultSlot() : this.hasNamedSlot(slotName);
+    }
+    // A direct child projected into the named slot. `:scope >` keeps it to direct
+    // children, so a nested `[slot="name"]` inside slotted content can't match.
+    hasNamedSlot(name) {
+        return this.host.querySelector(`:scope > [slot="${name}"]`) !== null;
+    }
+    // Any non-whitespace text node or any element without a `slot` attribute
+    // counts as default-slot content.
+    hasDefaultSlot() {
+        return [...this.host.childNodes].some((node) => {
+            if (node.nodeType === Node.TEXT_NODE) {
+                return (node.textContent ?? '').trim() !== '';
+            }
+            if (node.nodeType === Node.ELEMENT_NODE) {
+                return !node.hasAttribute('slot');
+            }
+            return false;
+        });
+    }
+    hostConnected() {
+        this.host.shadowRoot?.addEventListener('slotchange', this.handleSlotChange);
+    }
+    hostDisconnected() {
+        this.host.shadowRoot?.removeEventListener('slotchange', this.handleSlotChange);
+    }
+}

package/dist/static-tag.d.ts

@@ -0,0 +1,17 @@
+import { type StaticValue } from 'lit/static-html.js';
+import { type ElementBaseName } from './registry.js';
+/**
+ * Prefix-aware static tag for use in Lit static-html templates.
+ *
+ * Resolves a base name to the registered tag (e.g. `staticTag('icon')` → `po-icon`
+ * under `elementPrefix: 'po'`) so elements that render a child custom element inside
+ * their own template stay prefix-aware. Without this, the hardcoded `<l-icon>` literal
+ * is never defined under a custom prefix and the child never upgrades.
+ *
+ * Memoized: Lit keys its template cache on `StaticValue` identity, so a fresh
+ * `unsafeStatic()` per render would bust the cache. The prefix is set once at startup
+ * before any element renders, so a plain memo is correct. If runtime re-prefixing via
+ * `setPrefix()` becomes a supported scenario, clear `_cache` there.
+ */
+export declare function staticTag(baseName: ElementBaseName): StaticValue;
+//# sourceMappingURL=static-tag.d.ts.map

package/dist/static-tag.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"static-tag.d.ts","sourceRoot":"","sources":["../src/html/static-tag.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACpE,OAAO,EAAW,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AAI9D;;;;;;;;;;;;GAYG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,eAAe,GAAG,WAAW,CAIhE"}

package/dist/static-tag.js

@@ -0,0 +1,22 @@
+import { unsafeStatic } from 'lit/static-html.js';
+import { tagName } from './registry.js';
+const _cache = new Map();
+/**
+ * Prefix-aware static tag for use in Lit static-html templates.
+ *
+ * Resolves a base name to the registered tag (e.g. `staticTag('icon')` → `po-icon`
+ * under `elementPrefix: 'po'`) so elements that render a child custom element inside
+ * their own template stay prefix-aware. Without this, the hardcoded `<l-icon>` literal
+ * is never defined under a custom prefix and the child never upgrades.
+ *
+ * Memoized: Lit keys its template cache on `StaticValue` identity, so a fresh
+ * `unsafeStatic()` per render would bust the cache. The prefix is set once at startup
+ * before any element renders, so a plain memo is correct. If runtime re-prefixing via
+ * `setPrefix()` becomes a supported scenario, clear `_cache` there.
+ */
+export function staticTag(baseName) {
+    let t = _cache.get(baseName);
+    if (!t)
+        _cache.set(baseName, (t = unsafeStatic(tagName(baseName))));
+    return t;
+}

package/dist/templates/elements/avatar.md

@@ -6,10 +6,7 @@ outline: deep
 
 Avatars are used to represent a user or entity with a profile image, initials, or icon fallback. Commonly used in headers, comments, contact lists, and user cards.
 
-<ElementSpec
-  tag="l-avatar"
-  type="shadow"
-/>
+**`<l-avatar>`** — Custom Element · Shadow DOM
 
 ## Options
 
@@ -211,15 +208,14 @@ Wrap avatars in `.l-avatar-group` for an overlapping stack with a surface-colore
 
 ### Criteria
 
-| Check | Description |
-|-------|-------------|
-| Role | Default `role="img"` communicates the avatar as an image |
-| Accessible name | `aria-label` is set automatically from the `name` attribute |
-| Interactive mode | When `interactive` is set, renders as a `<button>` with focus ring and hover states |
-| Decorative elements | Badge count is hidden from assistive tech with `aria-hidden="true"` |
-| Image fallback | Falls back to initials (then default icon) if image fails to load |
+- **Role** — Default `role="img"` communicates the avatar as an image
+- **Accessible name** — `aria-label` is set automatically from the `name` attribute
+- **Interactive mode** — When `interactive` is set, renders as a `<button>` with focus ring and hover states
+- **Decorative elements** — Badge count is hidden from assistive tech with `aria-hidden="true"`
+- **Image fallback** — Falls back to initials (then default icon) if image fails to load
 
 ### Rules
+
 - Always provide the `name` attribute — it drives both `aria-label` and the initials fallback
 - Add `interactive` only when the avatar triggers an action (e.g., opens a profile menu)
 
@@ -227,11 +223,9 @@ Wrap avatars in `.l-avatar-group` for an overlapping stack with a surface-colore
 
 When `interactive` is set:
 
-| Key | Description |
-|-----|-------------|
-| Enter | Activates the avatar button |
-| Space | Activates the avatar button |
-| Tab | Moves focus to the next focusable element |
+- `Enter` — Activates the avatar button
+- `Space` — Activates the avatar button
+- `Tab` — Moves focus to the next focusable element
 
 ## API reference
 
@@ -243,17 +237,20 @@ import 'luxen-ui/avatar';
 
 ### Attributes & Properties
 
-<ApiTable :data="attributes" />
+- **src**: `string`
+- **name**: `string`
+- **size**: `string` (default: `'md'`)
+- **badge**: `number` (default: `0`)
+- **interactive**: `boolean` (default: `false`)
 
 ### CSS classes
 
-<ApiTable :data="[
-  { Class: '.l-avatar-group', Description: 'Flex container with negative margins and surface-colored ring for overlapping avatars' },
-]" />
+- `.l-avatar-group` — Flex wrapper that overlaps a row of stacked avatars.
 
 ### CSS custom properties
 
-<ApiTable :data="[
-  { Property: '--color', Description: 'Base color for initials/icon background. Text color is auto-derived via relative color syntax' },
-  { Property: '--appearance', Description: 'Set to `circle` for a fully circular shape (default is rounded square)' },
-]" />
+- **src**: `string`
+- **name**: `string`
+- **size**: `string` (default: `'md'`)
+- **badge**: `number` (default: `0`)
+- **interactive**: `boolean` (default: `false`)

package/dist/templates/elements/badge.md

@@ -6,10 +6,7 @@ outline: deep
 
 Badges are used to draw attention and display statuses or counts. Commonly used in tabular data, lists, and navigation to indicate state or category.
 
-<ElementSpec
-  tag="l-badge"
-  type="custom"
-/>
+**`<l-badge>`** — Custom Element (no Shadow DOM)
 
 ## Options
 
@@ -257,13 +254,12 @@ Add `variant="info"`, `variant="success"`, `variant="warning"`, or `variant="dan
 
 ### Criteria
 
-| Check | Description |
-|-------|-------------|
-| Color contrast | Text and background meet minimum contrast ratio across all appearances and variants |
-| Non-text contrast | Badge borders meet non-text contrast minimum against adjacent surfaces |
-| Not color alone | Do not rely on badge color alone to convey status — always include a text label |
+- **Color contrast** — Text and background meet minimum contrast ratio across all appearances and variants
+- **Non-text contrast** — Badge borders meet non-text contrast minimum against adjacent surfaces
+- **Not color alone** — Do not rely on badge color alone to convey status — always include a text label
 
 ### Rules
+
 - Always include visible text inside the badge — do not use color alone to convey meaning
 - When a badge conveys dynamic status, wrap it in a `role="status"` container so screen readers announce changes
 
@@ -281,9 +277,7 @@ import 'luxen-ui/badge';
 
 ### Attributes & Properties
 
-<ApiTable :data="[
-  { Attribute: 'size', Description: 'Badge size (`sm`, `lg`). Default is md.' },
-  { Attribute: 'appearance', Description: 'Visual appearance (`filled`, `filled-outlined`, `accent`). Default is outlined.' },
-  { Attribute: 'variant', Description: 'Style variant (`info`, `success`, `warning`, `danger`). Default is neutral.' },
-  { Attribute: 'pill', Description: 'Fully rounded pill shape' },
-]" />
+- **variant**: `BadgeVariant | undefined` — Style variant: `info`, `success`, `warning`, `danger`, or `neutral` (default)
+- **pill**: `boolean` (default: `false`) — Display as pill shape
+- **size**: `BadgeSize | undefined` — Badge size: `sm`, `lg`. Default is md.
+- **appearance**: `BadgeAppearance | undefined` — Visual appearance: `filled`, `filled-outlined`, `accent`. Default is outlined.

package/dist/templates/elements/button.md

@@ -6,10 +6,7 @@ outline: deep
 
 Buttons are used to trigger actions such as submitting forms, confirming dialogs, or navigating. They are the primary interactive control in any interface.
 
-<ElementSpec
-  tag="button"
-  type="native"
-/>
+**`.l-button`** — Native HTML Element
 
 ## Options
 
@@ -244,17 +241,16 @@ Add an `<l-spinner>` inside the button. The spinner inherits the button's text c
 
 ### Criteria
 
-| Check | Description |
-|-------|-------------|
-| Color | Text and background colors meet AA contrast ratios across all variants |
-| Focus state | Visible 2px focus ring for keyboard users |
-| Hover state | Clear visual change on hover |
-| Active state | Visual feedback on press |
-| Disabled state | Reduced opacity, `cursor: not-allowed`, not focusable when disabled |
-| Icon-only | Icon-only buttons must have `aria-label` for an accessible name |
-| Role | Uses native `<button>` or `<a>` — no extra ARIA role needed |
+- **Color** — Text and background colors meet AA contrast ratios across all variants
+- **Focus state** — Visible 2px focus ring for keyboard users
+- **Hover state** — Clear visual change on hover
+- **Active state** — Visual feedback on press
+- **Disabled state** — Reduced opacity, `cursor: not-allowed`, not focusable when disabled
+- **Icon-only** — Icon-only buttons must have `aria-label` for an accessible name
+- **Role** — Uses native `<button>` or `<a>` — no extra ARIA role needed
 
 ### Rules
+
 - Use a native `<button>` element — never a `<div>` or `<span>`
 - Always add `aria-label` to icon-only buttons
 - Include `type="button"` to prevent form submission (except for submit buttons)
@@ -262,12 +258,10 @@ Add an `<l-spinner>` inside the button. The spinner inherits the button's text c
 
 ### Keyboard interactions
 
-| Key | Description |
-|-----|-------------|
-| Enter | Activates the button |
-| Space | Activates the button |
-| Tab | Moves focus to the next focusable element |
-| Shift + Tab | Moves focus to the previous focusable element |
+- `Enter` — Activates the button
+- `Space` — Activates the button
+- `Tab` — Moves focus to the next focusable element
+- `Shift + Tab` — Moves focus to the previous focusable element
 
 ## API reference
 
@@ -279,31 +273,27 @@ Add an `<l-spinner>` inside the button. The spinner inherits the button's text c
 
 ### Attributes & Properties
 
-<ApiTable :data="[
-  { Attribute: 'disabled', Description: 'Disables the button' },
-  { Attribute: 'command', Description: 'Invoker command (`show-modal`, `close`, `show-popover`, etc.)' },
-  { Attribute: 'commandfor', Description: 'ID of the target element for `command`' },
-  { Attribute: 'data-variant', Description: 'Visual variant (`primary`, `destructive`)' },
-  { Attribute: 'data-size', Description: 'Size (`sm`, `lg`, `xl`). Default is md.' },
-  { Attribute: 'data-icon-only', Description: 'Icon-only mode (square button, width equals height)' },
-  { Attribute: 'data-press-effect', Description: 'Press effect (scale + translate on active)' },
-]" />
+- **disabled** — Disables the button.
+- **command** — Invoker command (`show-modal`, `close`, `show-popover`, etc.).
+- **commandfor** — ID of the target element for `command`.
+- **data-variant**: `primary | destructive` — Visual variant. Default is the secondary style.
+- **data-size**: `sm | lg | xl` — Control size. Default is md.
+- **data-icon-only** — Icon-only mode (square button, width equals height). Auto-detected for a single icon child.
+- **data-press-effect** — Press effect (scale + translate on active).
 
 ### CSS classes
 
-<ApiTable :data="cssClasses" />
+- `.l-button` — Base button style.
 
 ### CSS custom properties
 
-<ApiTable :data="[
-  { Name: '--height', Description: 'Button height' },
-  { Name: '--padding-inline', Description: 'Horizontal padding' },
-  { Name: '--background-color', Description: 'Background color' },
-  { Name: '--background-color-hover', Description: 'Background on hover' },
-  { Name: '--background-color-active', Description: 'Background on press' },
-  { Name: '--text-color', Description: 'Text color' },
-  { Name: '--text-hover', Description: 'Text color on hover' },
-  { Name: '--border-color', Description: 'Border color' },
-  { Name: '--border-color-hover', Description: 'Border color on hover' },
-  { Name: '--font-size', Description: 'Font size' },
-]" />
+- `--height` (default: `32px`) — Button height (md size).
+- `--padding-inline` (default: `0.625rem`) — Horizontal padding.
+- `--background-color` — Background color.
+- `--background-color-hover` — Background color on hover.
+- `--background-color-active` — Background color on press.
+- `--text-color` — Text color.
+- `--text-color-hover` — Text color on hover.
+- `--border-color` — Border color.
+- `--border-color-hover` — Border color on hover.
+- `--font-size` — Font size.

package/dist/templates/elements/close-button.md

@@ -6,10 +6,7 @@ outline: deep
 
 Close buttons are used to dismiss overlays such as dialogs, drawers, toasts, and popovers. They render a close icon without any visible label.
 
-<ElementSpec
-  tag="button"
-  type="native"
-/>
+**`.l-close`** — Native HTML Element
 
 ## Options
 
@@ -66,31 +63,28 @@ Pick a visual style via `data-appearance`. Each appearance has its own CSS impor
 
 ### Criteria
 
-| Check | Description |
-|-------|-------------|
-| Color | Icon and background colors meet AA contrast ratios |
-| Size | Minimum 24×24px target size; larger for touch contexts |
-| Icon | Decorative icon; `aria-label` on the button provides the accessible name |
-| Hover state | Clear visual change on hover |
-| Focus state | Visible focus ring for keyboard users |
-| Active state | Visual feedback on press |
-| Disabled state | Appears inactive, not focusable when disabled |
-| Accessible name | Always provide `aria-label` or context-specific label |
-| Role | Uses native `<button>` — no extra ARIA role needed |
+- **Color** — Icon and background colors meet AA contrast ratios
+- **Size** — Minimum 24×24px target size; larger for touch contexts
+- **Icon** — Decorative icon; `aria-label` on the button provides the accessible name
+- **Hover state** — Clear visual change on hover
+- **Focus state** — Visible focus ring for keyboard users
+- **Active state** — Visual feedback on press
+- **Disabled state** — Appears inactive, not focusable when disabled
+- **Accessible name** — Always provide `aria-label` or context-specific label
+- **Role** — Uses native `<button>` — no extra ARIA role needed
 
 ### Rules
+
 - Always add `aria-label="Close"` (or a context-specific label like `aria-label="Close dialog"`)
 - Use a native `<button>` element — never a `<div>` or `<span>`
 - Include `type="button"` to prevent form submission
 
 ### Keyboard interactions
 
-| Key | Description |
-|-----|-------------|
-| Enter | Activates the close button |
-| Space | Activates the close button |
-| Tab | Moves focus to the next focusable element |
-| Shift + Tab | Moves focus to the previous focusable element |
+- `Enter` — Activates the close button
+- `Space` — Activates the close button
+- `Tab` — Moves focus to the next focusable element
+- `Shift + Tab` — Moves focus to the previous focusable element
 
 ## API reference
 
@@ -102,24 +96,18 @@ Pick a visual style via `data-appearance`. Each appearance has its own CSS impor
 
 ### Attributes & Properties
 
-<ApiTable :data="[
-  { Attribute: 'data-appearance', Description: '`ring` · `square` · `circle`' },
-  { Attribute: 'command', Description: 'Invoker command (typically `close`)' },
-  { Attribute: 'commandfor', Description: 'ID of the target element to close' },
-]" />
+- **data-appearance**: `ring | square | circle` — Visual appearance (matches the imported appearance CSS).
+- **command** — Invoker command (typically `close`).
+- **commandfor** — ID of the target element to close.
 
 ### CSS classes
 
-<ApiTable :data="[
-  { Class: '.l-close', Description: 'Base close button with X icon via CSS mask' },
-]" />
+- `.l-close` — Base close button with X icon via CSS mask.
 
 ### CSS custom properties
 
-<ApiTable :data="[
-  { Name: '--size', Description: 'Button size (default: 36px)' },
-  { Name: '--icon-color', Description: 'Icon color' },
-  { Name: '--icon-size', Description: 'Icon size (default: 24px)' },
-  { Name: '--ring-color', Description: 'Hover ring color (`ring` appearance only)' },
-  { Name: '--ring-tickness', Description: 'Hover ring thickness (`ring` appearance only)' },
-]" />
+- `--size` (default: `36px`) — Button size.
+- `--icon-color` — Icon color.
+- `--icon-size` (default: `24px`) — Icon size.
+- `--ring-color` — Hover ring color (`ring` appearance only).
+- `--ring-tickness` — Hover ring thickness (`ring` appearance only).