luxen-ui 0.22.0 → 0.23.0

package/dist/shared/styles/badge-core.css

@@ -0,0 +1,221 @@
+/*
+ * Shared `l-badge` appearance — the single source of truth for the badge's look.
+ * Lives in the HTML tree so it is both:
+ *   - `@import`ed (and layered) by src/css/elements/badge.css for light-DOM
+ *     badges, and
+ *   - imported `?inline` into shadow-DOM elements whose rendered content can
+ *     carry a badge (l-select / l-combobox copy each rich option's markup into
+ *     their shadow root, where the global badge stylesheet cannot reach).
+ *
+ * Intentionally UNLAYERED, like button-core.css: the light-DOM import wraps it in
+ * `@layer components` via `@import … layer(components)`, while shadow consumers
+ * want it unlayered alongside their own (also unlayered) styles.
+ */
+
+/*
+  Autonomous custom elements
+  https://blog.jim-nielsen.com/2021/custom-elements-without-js/
+*/
+l-badge {
+  /* Per-variant primitives — set by [variant], consumed by appearance. The
+     public hooks that override them are threaded at the declaration sites
+     below rather than here, so this whole machinery stays untouched: a
+     consumer value is not competing with `[variant]` / `[appearance]` /
+     `[pill]` on specificity, it sits under them.
+
+     Four hooks, and each one earns its place by hiding something a consumer
+     would otherwise have to know:
+
+       --text-color        the line is a tint of it, so one declaration
+                           repaints the whole chip
+       --background-color  which per-appearance token it is replacing
+       --border-color      the 30% mix, and that it holds through `filled`,
+                           whose default line is transparent
+       --border-radius     that the corner is a squircle, not a plain arc
+
+     Size and spacing get no hook on purpose. `--height` / `--font-size` /
+     `--padding-inline` would be pass-throughs to the identically named
+     properties declared a few lines below, hiding nothing — and `size` is
+     already the API for that axis. Three steps are the design; a badge that
+     can be dialled to any height stops being a size step and starts being a
+     box.
+
+     The line derives from `currentColor` rather than from `--_text-color`, so
+     it follows the ink whoever set it — the hook, a variant, or a consumer's
+     own `color` declaration. */
+  --_text-color: var(--l-color-text-neutral);
+  --_background-color: transparent;
+  --_border-color: color-mix(in oklab, currentColor 30%, transparent);
+  --_border-radius: var(--l-radius-md);
+
+  /* Size defaults (md) */
+  --_height: 1.375rem;
+  --_font-size: var(--l-text-xs);
+  --_padding-inline: 0.375rem;
+  --_gap: 0.25rem;
+
+  display: inline-flex;
+  align-items: center;
+  gap: var(--_gap);
+  min-height: var(--_height);
+  padding-block: 0.25rem;
+  padding-inline: var(--_padding-inline);
+  border: 1px solid var(--border-color, var(--_border-color));
+  border-radius: var(--border-radius, var(--_border-radius));
+  corner-shape: squircle;
+  background-color: var(--background-color, var(--_background-color));
+  color: var(--text-color, var(--_text-color));
+  font-family: var(--l-font-neo-grotesque);
+  font-size: var(--_font-size);
+  font-weight: var(--l-font-weight-medium);
+  line-height: 1;
+  text-box: trim-both cap alphabetic;
+
+  /*
+  ▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬
+   🆂🅸🆉🅴🆂
+  ▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬
+  */
+
+  &[size='sm'] {
+    --_height: 1.25rem;
+    --_padding-inline: 0.25rem;
+    --_gap: 0.125rem;
+  }
+  &[size='lg'] {
+    --_height: 1.5rem;
+    --_font-size: var(--l-text-sm);
+    --_padding-inline: 0.5rem;
+  }
+
+  /*
+  ▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬
+   🆅🅰🆁🅸🅰🅽🆃🆂
+  ▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬
+  */
+
+  &[variant='info'] {
+    --_text-color: var(--l-color-text-info);
+  }
+  &[variant='success'] {
+    --_text-color: var(--l-color-text-success);
+  }
+  &[variant='warning'] {
+    --_text-color: var(--l-color-text-warning);
+  }
+  &[variant='danger'] {
+    --_text-color: var(--l-color-text-danger);
+  }
+
+  /*
+  ▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬
+   🅰🅿🅿🅴🅰🆁🅰🅽🅲🅴
+  ▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬
+  */
+
+  &[appearance='filled'] {
+    --_background-color: var(--l-color-bg-fill-neutral-subtle);
+    --_border-color: transparent;
+
+    &[variant='info'] {
+      --_background-color: var(--l-color-bg-fill-info-subtle);
+    }
+    &[variant='success'] {
+      --_background-color: var(--l-color-bg-fill-success-subtle);
+    }
+    &[variant='warning'] {
+      --_background-color: var(--l-color-bg-fill-warning-subtle);
+    }
+    &[variant='danger'] {
+      --_background-color: var(--l-color-bg-fill-danger-subtle);
+    }
+  }
+
+  &[appearance='filled-outlined'] {
+    --_background-color: var(--l-color-bg-fill-neutral-subtle);
+
+    &[variant='info'] {
+      --_background-color: var(--l-color-bg-fill-info-subtle);
+    }
+    &[variant='success'] {
+      --_background-color: var(--l-color-bg-fill-success-subtle);
+    }
+    &[variant='warning'] {
+      --_background-color: var(--l-color-bg-fill-warning-subtle);
+    }
+    &[variant='danger'] {
+      --_background-color: var(--l-color-bg-fill-danger-subtle);
+    }
+  }
+
+  &[appearance='accent'] {
+    --_background-color: var(--l-color-bg-fill-neutral-strong);
+    --_text-color: var(--l-color-surface);
+    --_border-color: transparent;
+
+    &[variant='info'] {
+      --_background-color: var(--l-color-bg-fill-info-strong);
+      --_text-color: white;
+    }
+    &[variant='success'] {
+      --_background-color: var(--l-color-bg-fill-success-strong);
+    }
+    &[variant='warning'] {
+      --_background-color: var(--l-color-bg-fill-warning-strong);
+    }
+    &[variant='danger'] {
+      --_background-color: var(--l-color-bg-fill-danger-strong);
+      --_text-color: white;
+    }
+  }
+
+  /*
+  ▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬
+   🅿🅸🅻🅻
+  ▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬
+  */
+
+  /* `--border-radius` keeps the squircle; `pill` is what trades it for a true
+     arc, because a squircle at a full radius reads as a blob. */
+  &[pill] {
+    --_border-radius: var(--l-radius-full);
+    corner-shape: unset;
+  }
+
+  /*
+  ▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬
+   🅸🅲🅾🅽
+  ▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬
+  */
+
+  iconify-icon {
+    color: currentColor;
+    height: 1em;
+  }
+}
+
+/* A glyph against an edge earns a tighter padding on that side: its bounding
+   box already reads as air, so the label keeps the full gutter and the chip
+   does not go lopsided.
+
+   Matches whichever icon element the consumer composes — the library's own
+   `l-icon`, a raw `iconify-icon`, or the inline `<svg>` a framework Iconify
+   binding renders. `l-icon` needs naming explicitly: its `iconify-icon` sits
+   in a shadow root this selector cannot see, so matching the inner element
+   alone silently skipped the correction (the icon still laid out — `l-icon`
+   is `display: contents` — it just sat 2px too far in). Same element set
+   `toast.css` and `story.css` already use. */
+l-badge:has(:is(iconify-icon, l-icon, svg):first-child) {
+  padding-inline-start: 0.25rem;
+}
+
+/* `:not(:first-child)` is what makes a trailing icon addressable at all.
+   `:first-child` and `:last-child` count elements, not text, so an icon that
+   is the badge's only element child matches both — `<l-badge>Lyon <l-icon/>`
+   is indistinguishable from `<l-badge><l-icon/>Lyon`, and the rule above
+   already claims it. Requiring a preceding element keeps that case exactly as
+   it was and makes this one exact: wrap the label (`<span>Lyon</span>`) and
+   the icon is unambiguously at the end. */
+l-badge:has(:is(iconify-icon, l-icon, svg):last-child:not(:first-child)) {
+  padding-inline-end: 0.25rem;
+}

package/dist/shared/styles/badge-core.styles.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Wrapper module for the shared `l-badge` appearance. `unsafeCSS()` is called
+ * once here so every shadow-DOM element that can render a badge (l-select,
+ * l-combobox rich options) shares one `CSSResult` (one constructed
+ * `CSSStyleSheet`, not one per importer).
+ */
+declare const _default: import("lit").CSSResult;
+export default _default;
+//# sourceMappingURL=badge-core.styles.d.ts.map

package/dist/shared/styles/badge-core.styles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"badge-core.styles.d.ts","sourceRoot":"","sources":["../../../src/html/shared/styles/badge-core.styles.ts"],"names":[],"mappings":"AAGA;;;;;GAKG"}

package/dist/shared/styles/badge-core.styles.js

@@ -0,0 +1,9 @@
+import { unsafeCSS } from 'lit';
+import raw from './badge-core.css?inline';
+/**
+ * Wrapper module for the shared `l-badge` appearance. `unsafeCSS()` is called
+ * once here so every shadow-DOM element that can render a badge (l-select,
+ * l-combobox rich options) shares one `CSSResult` (one constructed
+ * `CSSStyleSheet`, not one per importer).
+ */
+export default unsafeCSS(raw);

package/dist/shared/styles/button-core.styles.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"button-core.styles.d.ts","sourceRoot":"","sources":["../../../src/html/shared/styles/button-core.styles.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;;AACH,wBAA8B"}
+{"version":3,"file":"button-core.styles.d.ts","sourceRoot":"","sources":["../../../src/html/shared/styles/button-core.styles.ts"],"names":[],"mappings":"AAGA;;;;;GAKG"}

package/dist/shared/styles/checkbox-appearance.styles.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"checkbox-appearance.styles.d.ts","sourceRoot":"","sources":["../../../src/html/shared/styles/checkbox-appearance.styles.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;;AACH,wBAA8B"}
+{"version":3,"file":"checkbox-appearance.styles.d.ts","sourceRoot":"","sources":["../../../src/html/shared/styles/checkbox-appearance.styles.ts"],"names":[],"mappings":"AAGA;;;;;GAKG"}

package/dist/shared/styles/host.styles.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"host.styles.d.ts","sourceRoot":"","sources":["../../../src/html/shared/styles/host.styles.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;;AACH,wBAA8B"}
+{"version":3,"file":"host.styles.d.ts","sourceRoot":"","sources":["../../../src/html/shared/styles/host.styles.ts"],"names":[],"mappings":"AAGA;;;;;GAKG"}

package/dist/shared/styles/select-item-suffix.css

@@ -0,0 +1,60 @@
+/*
+ * Suffix of a rich option (`.l-select-item-suffix`) — a badge, count or
+ * status icon pinned to the inline-end of the row, after `.l-select-item-text`.
+ * One source for every tier, so they cannot drift apart:
+ *   - `@import`ed (and layered) by src/css/elements/select.css for the native
+ *     `select.l-select` picker, where `.l-select option` is the row, and
+ *   - imported `?inline` into the l-select / l-combobox shadow roots, which copy
+ *     each option's markup and cannot reach the global stylesheet; there
+ *     `:host .option-rich` is the row. `:host` never matches in a document, so
+ *     the light-DOM copy cannot reach a consumer's own `.option-rich`.
+ *
+ * A class, not a `slot="suffix"` attribute hook: in a customizable select the
+ * <option> has its own UA shadow root, so a child carrying a `slot` it has no
+ * slot for is not rendered at all. A class keeps one markup for every tier.
+ *
+ * Intentionally UNLAYERED, like button-core.css. Each tier hides the suffix in
+ * its own trigger next to its description rule.
+ */
+
+/* The row's line box as an absolute length — the title's line, since the title
+   inherits the row's font and line-height. Registered so `1lh` resolves on the
+   row and is inherited as a length; unregistered it would resolve on the
+   smaller suffix. A shadow root ignores this rule, so rich-option.ts also
+   registers it from JS. */
+@property --_select-item-line {
+  syntax: '<length>';
+  inherits: true;
+  initial-value: 0px;
+}
+
+:is(.l-select option, :host .option-rich) {
+  --_select-item-line: 1lh;
+}
+
+.l-select-item-suffix {
+  display: inline-flex;
+  /* Never shrinks: the text column gives way first and its title truncates. */
+  flex: 0 0 auto;
+  align-items: center;
+  /* Sits on the title's line rather than the row's middle — like the checkmark
+     and the media — so a wrapping description never moves it: a box exactly one
+     title line tall, pinned to the top, centres its content on that line. Content
+     taller than the line (a badge in a tight row, an avatar) overflows it evenly
+     above and below, into the row's padding, and never moves the title. */
+  align-self: flex-start;
+  block-size: var(--_select-item-line);
+  gap: 0.25rem;
+  margin-inline-start: auto;
+  white-space: nowrap;
+  color: var(--l-color-text-tertiary);
+  font-size: 0.75rem;
+}
+
+/* In a picker row that carries a suffix, the text column is pinned to the top
+   too, so the title shares the suffix's line in a centred row (l-combobox).
+   Scoped to the rows: the trigger's copy of the selected option (where the
+   suffix is hidden) keeps its own centring. */
+:is(.l-select option, :host .option-rich) > .l-select-item-text:has(~ .l-select-item-suffix) {
+  align-self: flex-start;
+}

package/dist/shared/styles/select-item-suffix.styles.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Wrapper module for the shared rich-option trailing zone. `unsafeCSS()` is
+ * called once here so l-select and l-combobox share one `CSSResult` (one
+ * constructed `CSSStyleSheet`, not one per importer).
+ */
+declare const _default: import("lit").CSSResult;
+export default _default;
+//# sourceMappingURL=select-item-suffix.styles.d.ts.map

package/dist/shared/styles/select-item-suffix.styles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"select-item-suffix.styles.d.ts","sourceRoot":"","sources":["../../../src/html/shared/styles/select-item-suffix.styles.ts"],"names":[],"mappings":"AAGA;;;;GAIG"}

package/dist/shared/styles/select-item-suffix.styles.js

@@ -0,0 +1,8 @@
+import { unsafeCSS } from 'lit';
+import raw from './select-item-suffix.css?inline';
+/**
+ * Wrapper module for the shared rich-option trailing zone. `unsafeCSS()` is
+ * called once here so l-select and l-combobox share one `CSSResult` (one
+ * constructed `CSSStyleSheet`, not one per importer).
+ */
+export default unsafeCSS(raw);

package/dist/templates/elements/combobox.md

@@ -94,6 +94,8 @@ Add `allow-custom` to accept a typed value that matches no option.
 
 Put markup inside each `<option>` — the same `.l-select-item-media` / `.l-select-item-text` / `.l-select-item-title` / `.l-select-item-description` classes as [`<select>`](/elements/select). Set a `label` (or `.l-select-item-title`) so filtering and the input display use the title.
 
+As you type, the match is highlighted inside `.l-select-item-title` and `.l-select-item-description`, with the same accent/case-insensitive matching as plain options. Only the text is wrapped in `<mark>`; the option's markup is kept as authored.
+
 ```html
 <div class="w-72">
   <l-combobox
@@ -136,6 +138,71 @@ Put markup inside each `<option>` — the same `.l-select-item-media` / `.l-sele
 </div>
 ```
 
+#### Suffix
+
+Add a `.l-select-item-suffix` after `.l-select-item-text` to pin a badge, a count or a status icon to the end of the row, before the checkmark. It sits on the title's line, keeps its natural width while the title truncates, and is never matched by the filter or written into the input. Rich options are copied into the popover's shadow root: an [`<l-badge>`](/elements/badge) is styled there, but your page's own selectors don't reach that copy. To theme it, set the badge's CSS custom properties on the `<l-combobox>`: they inherit into the popover. Screen readers announce the suffix with its option, so write it as words ("12 members", not "12").
+
+```html
+<div class="w-80">
+  <l-combobox
+    label="Team"
+    placeholder="Search a team…"
+  >
+    <datalist>
+      <option
+        value="design"
+        label="Design"
+      >
+        <span class="l-select-item-text">
+          <span class="l-select-item-title">Design</span>
+          <span class="l-select-item-description">Product and brand design</span>
+        </span>
+        <span class="l-select-item-suffix">
+          <l-badge
+            size="sm"
+            appearance="filled"
+            >12 members</l-badge
+          >
+        </span>
+      </option>
+      <option
+        value="engineering"
+        label="Engineering"
+      >
+        <span class="l-select-item-text">
+          <span class="l-select-item-title">Engineering</span>
+          <span class="l-select-item-description">Platform, web and mobile apps</span>
+        </span>
+        <span class="l-select-item-suffix">
+          <l-badge
+            size="sm"
+            appearance="filled"
+            >48 members</l-badge
+          >
+        </span>
+      </option>
+      <option
+        value="support"
+        label="Support"
+      >
+        <span class="l-select-item-text">
+          <span class="l-select-item-title">Support</span>
+          <span class="l-select-item-description">Customer success and onboarding</span>
+        </span>
+        <span class="l-select-item-suffix">
+          <l-badge
+            size="sm"
+            appearance="filled"
+            variant="warning"
+            >Full</l-badge
+          >
+        </span>
+      </option>
+    </datalist>
+  </l-combobox>
+</div>
+```
+
 ### Disabled
 
 Native `disabled` attribute.
@@ -159,6 +226,84 @@ Native `disabled` attribute.
 
 By default options are matched case- and accent-insensitively (every space-separated keyword must appear). Override the `filter` property — `(item, query) => boolean` — for `startsWith`, fuzzy, or remote-driven filtering.
 
+The default filter only reads the label (a rich option's title). To search the description too, match against the text of `item.html` — the match is then highlighted in the description as well. Try a capital or a continent:
+
+```html
+<div class="w-72">
+  <l-combobox
+    id="demo-combobox-filter"
+    label="Country"
+    placeholder="Search a country or capital…"
+  >
+    <datalist>
+      <option
+        value="fr"
+        label="France"
+      >
+        <span class="l-select-item-text">
+          <span class="l-select-item-title">France</span>
+          <span class="l-select-item-description">Capital: Paris · Europe</span>
+        </span>
+      </option>
+      <option
+        value="jp"
+        label="Japan"
+      >
+        <span class="l-select-item-text">
+          <span class="l-select-item-title">Japan</span>
+          <span class="l-select-item-description">Capital: Tokyo · Asia</span>
+        </span>
+      </option>
+      <option
+        value="br"
+        label="Brazil"
+      >
+        <span class="l-select-item-text">
+          <span class="l-select-item-title">Brazil</span>
+          <span class="l-select-item-description">Capital: Brasília · South America</span>
+        </span>
+      </option>
+      <option
+        value="ke"
+        label="Kenya"
+      >
+        <span class="l-select-item-text">
+          <span class="l-select-item-title">Kenya</span>
+          <span class="l-select-item-description">Capital: Nairobi · Africa</span>
+        </span>
+      </option>
+    </datalist>
+  </l-combobox>
+</div>
+```
+
+```js
+const combobox = document.querySelector('l-combobox');
+
+// `item.html` is the rich option's markup: compare against its text, not its tags.
+const textOf = (html) => {
+  const template = document.createElement('template');
+  template.innerHTML = html;
+  return template.content.textContent;
+};
+
+combobox.filter = (item, query) =>
+  `${item.label} ${item.html ? textOf(item.html) : ''}`
+    .toLowerCase()
+    .includes(query.trim().toLowerCase());
+```
+
+### Match highlight
+
+The part of each option that matches the query is wrapped in `<mark>`. Theme it with two form-control tokens, or set the `highlight` property to `false` to turn it off.
+
+```css
+:root {
+  --l-form-control-match-background-color: transparent;
+  --l-form-control-match-font-weight: var(--l-font-weight-bold);
+}
+```
+
 ### Dynamic options
 
 The `<datalist>` is watched: re-labelling, adding, removing, or disabling an `<option>` after mount updates the input and the listbox immediately — no reopen, no remount. Text the user is typing is left alone.
@@ -206,7 +351,8 @@ import 'luxen-ui/combobox';
 - **size**: `ComboboxSize` (default: `'md'`) — Control size.
 - **with-clear**: `boolean` (default: `false`) — Show a button to clear the value.
 - **allow-custom**: `boolean` (default: `false`) — Accept a typed value that matches no option.
-- **highlight**: `boolean` (default: `true`) — Wrap the matching substring of each option in `<mark>`.
+- **highlight**: `boolean` (default: `true`) — Wrap the matching substring of each option in `<mark>` — the label of a
+plain option, the title and description of a rich one.
 - **placement**: `Placement` (default: `'bottom-start'`) — Panel placement relative to the control.
 - **filter**: `ComboboxFilter` (default: `defaultFilter`) — Override the option filter. `(item, query) => boolean`.
 
@@ -227,6 +373,14 @@ import 'luxen-ui/combobox';
 - `option` — Each option row.
 - `empty` — The "no results" message.
 
+### CSS classes
+
+- `.l-select-item-media` — Rich option: leading image or icon.
+- `.l-select-item-text` — Rich option: column holding the title and the description.
+- `.l-select-item-title` — Rich option: title, truncated with an ellipsis. Used as the label when the option has no `label`.
+- `.l-select-item-description` — Rich option: secondary line, shown in the listbox only.
+- `.l-select-item-suffix` — Rich option: trailing badge, count or status icon on the title's line. Kept out of the input and the filter.
+
 ### CSS custom properties
 
 - `--height` — Control height. Defaults to the form-control height.

package/dist/templates/elements/prose-editor.md

@@ -127,7 +127,8 @@ The editor participates in forms via its `name` attribute. The submitted value i
 - `Ctrl/Cmd + U` — Toggles underline
 - `Ctrl/Cmd + Z` — Undo
 - `Ctrl/Cmd + Shift + Z` — Redo
-- `Escape` — Closes the emoji picker when open
+- `Escape` — Closes the emoji picker when open and returns focus to where it was before: the editor, or the Emoji button when the picker was opened from the toolbar
+- `Tab / Shift + Tab` — In the emoji picker, moves between its controls; tabbing out of it closes it, moving on to the editor (Tab) or back to the Emoji button (Shift + Tab)
 
 ## API reference
 

package/dist/templates/elements/radio-group.md

@@ -324,8 +324,8 @@ Add `disabled` to a segment's input. Arrow keys skip it, and it drops out of the
 ### Keyboard interactions
 
 - `Tab` — Moves focus into the group, onto the checked segment
-- `ArrowRight` — Selects and focuses the next segment, wrapping
-- `ArrowLeft` — Selects and focuses the previous segment, wrapping
+- `ArrowRight` — Selects and focuses the next segment; wraps at the end in Chrome and Firefox, stops there in Safari (the browser’s own radio behaviour)
+- `ArrowLeft` — Selects and focuses the previous segment; wraps at the start in Chrome and Firefox, stops there in Safari
 - `ArrowDown` — Same as ArrowRight
 - `ArrowUp` — Same as ArrowLeft
 - `Space` — Selects the focused segment when none was selected