@dumiflex/wp-kit 0.0.0-stage → 0.3.0

package/src/Select.vue

@@ -0,0 +1,641 @@
+<script setup lang="ts">
+import { computed, nextTick, onBeforeUnmount, onMounted, ref, watch } from "vue";
+import Icon, { ICON_SM } from "./Icon.vue";
+
+// Declared in `./select-types` so plain `.ts` helpers can build option lists
+// (a `.ts` importer only sees the `*.vue` ambient shim). Re-exported here so
+// existing `from "./Select.vue"` imports keep resolving.
+import type { SelectOption } from "./select-types";
+export type { SelectOption };
+
+interface Props {
+  modelValue: string | number | null;
+  options: SelectOption[];
+  placeholder?: string | undefined;
+  clearable?: boolean | undefined;
+  size?: "sm" | "md" | "lg" | undefined;
+  disabled?: boolean | undefined;
+  error?: boolean | undefined;
+  ariaLabel?: string | undefined;
+  /** Type-to-filter. Default on. Turn OFF for a small fixed list (e.g. a
+   *  4-item mode picker) that needs neither the "Type to filter" hint nor the
+   *  height it adds — the hint row was what pushed the menu into a scrollbar
+   *  that overlapped the selected row's tick. */
+  filterable?: boolean | undefined;
+}
+const props = withDefaults(defineProps<Props>(), { size: "md", placeholder: "Select…", filterable: true });
+
+const emit = defineEmits<{
+  (e: "update:modelValue", v: string | number | null): void;
+  (e: "change", v: string | number | null): void;
+}>();
+
+const wrapRef = ref<HTMLDivElement | null>(null);
+const btnRef = ref<HTMLButtonElement | null>(null);
+const open = ref(false);
+const flip = ref(false);
+const active = ref(0);
+/** Type-to-filter query, built from printable keystrokes while the menu
+ *  is open. Reset every time the menu opens or closes. */
+const query = ref("");
+/** The teleported menu, so the outside-click guard can exclude it. */
+const menuRef = ref<HTMLElement | null>(null);
+
+/** Fixed-position coordinates for the teleported menu. */
+const menuStyle = ref<Record<string, string>>({});
+
+const selected = computed(() => props.options.find((o) => o.value === props.modelValue) ?? null);
+
+/**
+ * Width to reserve for the icon/dot gutter, or null when no option has one.
+ *
+ * Markers are per-option, so a list where only SOME options carry one used to
+ * render a ragged left edge — a categorised row sat 20px right of an
+ * uncategorised one, and the eye reads that indent as hierarchy that isn't
+ * there. Reserving the gutter for every row in a list where any row has a
+ * marker keeps the labels in one column.
+ *
+ * Measured off the widest marker actually present: icons are a 14px box, dots
+ * 8px, so a dots-only list does not pay for icon width it never uses.
+ */
+const markerWidth = computed<string | null>(() => {
+  let hasDot = false;
+  for (const o of props.options) {
+    if (o.icon) return "14px";
+    if (o.dot) hasDot = true;
+  }
+  return hasDot ? "8px" : null;
+});
+
+/** Whether to advertise type-to-filter. Only a single-option menu has nothing
+ *  to filter; anything above that benefits, and the capability was invisible
+ *  until you already knew about it. An earlier threshold of six hid the hint on
+ *  exactly the menus users were checking. */
+const FILTER_HINT_MIN_OPTIONS = 2;
+const showFilterHint = computed(() => props.filterable && props.options.length >= FILTER_HINT_MIN_OPTIONS);
+
+/** Options narrowed by `query` (case-insensitive substring on the label).
+ *  Empty query → all options, so every dropdown is type-to-filter. */
+const filtered = computed<SelectOption[]>(() => {
+  if (!props.filterable) return props.options;
+  const q = query.value.trim().toLowerCase();
+  if (!q) return props.options;
+  // Match `meta` too — when several rows share a label, the meta (option
+  // count + uuid) is the ONLY thing that tells them apart, so it has to be
+  // searchable or the duplicates stay unreachable by typing.
+  return props.options.filter((o) =>
+    o.label.toLowerCase().includes(q) || (o.meta?.toLowerCase().includes(q) ?? false),
+  );
+});
+
+const btnClasses = computed(() => [
+  "wp-select",
+  props.size === "sm" && "wp-select--sm",
+  props.size === "lg" && "wp-select--lg",
+]);
+
+/** Surface an aria-label only when there's no visible selected text —
+ *  otherwise the visible label IS the accessible name and an aria-label
+ *  override would just disagree with the visible text (axe rule
+ *  label-content-name-mismatch). When the trigger shows a placeholder
+ *  with no selection, fall through to the ariaLabel prop. */
+const composedAriaLabel = computed<string | undefined>(() => {
+  if (selected.value) return undefined;
+  return props.ariaLabel;
+});
+
+function onDocClick(e: MouseEvent) {
+  const t = e.target as Node | null;
+  if (!t) return;
+  // Close when the press is outside the trigger AND outside the menu. The menu
+  // is teleported to <body>, so it is NOT inside `wrapRef` — checking only the
+  // trigger meant a mousedown on the menu's own scrollbar counted as "outside"
+  // and dismissed it. The wheel worked, the scrollbar did not.
+  if (wrapRef.value?.contains(t)) return;
+  if (menuRef.value?.contains(t)) return;
+  open.value = false;
+}
+
+onMounted(() => {
+  document.addEventListener("mousedown", onDocClick, true);
+});
+onBeforeUnmount(() => {
+  document.removeEventListener("mousedown", onDocClick, true);
+  window.removeEventListener("scroll", followOnScroll, true);
+  window.removeEventListener("resize", reposition);
+});
+
+/** Any scroll in the page moves the menu with its trigger (like every kit
+ *  overlay), instead of closing it or leaving it where the trigger used to
+ *  be. Only once the trigger has scrolled right out of view does it close. */
+function followOnScroll(e: Event) {
+  // The menu's own list scroll changes nothing about where it sits.
+  const t = e.target as Element | null;
+  if (t && typeof t.closest === "function" && t.closest(".wp-select__menu")) return;
+  if (!open.value || !btnRef.value) return;
+  const r = btnRef.value.getBoundingClientRect();
+  if (r.bottom < 0 || r.top > window.innerHeight || r.right < 0 || r.left > window.innerWidth) {
+    open.value = false;
+    return;
+  }
+  computeMenuStyle();
+}
+function reposition() {
+  if (!open.value || !btnRef.value) return;
+  computeMenuStyle();
+}
+
+function computeMenuStyle() {
+  if (!btnRef.value) return;
+  const rect = btnRef.value.getBoundingClientRect();
+  // Ideal menu height = enough room for every option (~36px each + 12px
+  // padding), capped at 240px so a huge library doesn't blanket the
+  // viewport. The actual rendered height also gets capped by available
+  // screen space below — see `effectiveMaxHeight` — so the menu never
+  // bleeds past the viewport edge.
+  const idealHeight = Math.min(240, props.options.length * 36 + 12);
+  const gap = 4;       // spacing between trigger and menu
+  const margin = 8;    // breathing room from the viewport edge
+  const spaceBelow = window.innerHeight - rect.bottom - gap - margin;
+  const spaceAbove = rect.top - gap - margin;
+
+  // Flip above only when there isn't enough room below AND there's
+  // more room above than below — otherwise the menu still grows under
+  // the trigger and `effectiveMaxHeight` clamps it to whatever fits.
+  flip.value = spaceBelow < idealHeight && spaceAbove > spaceBelow;
+
+  const available = flip.value ? spaceAbove : spaceBelow;
+  // Floor at 80px so a tightly-cramped row (e.g. inside a modal near the
+  // viewport edge) still surfaces a usable scrolling list rather than
+  // collapsing to a 1-row sliver.
+  const effectiveMaxHeight = Math.max(80, Math.min(idealHeight, available));
+
+  menuStyle.value = flip.value
+    ? {
+        position: "fixed",
+        bottom: (window.innerHeight - rect.top + gap) + "px",
+        top: "auto",
+        left: rect.left + "px",
+        minWidth: rect.width + "px",
+        maxHeight: effectiveMaxHeight + "px",
+      }
+    : {
+        position: "fixed",
+        top: (rect.bottom + gap) + "px",
+        bottom: "auto",
+        left: rect.left + "px",
+        minWidth: rect.width + "px",
+        maxHeight: effectiveMaxHeight + "px",
+      };
+}
+
+watch(open, (v) => {
+  if (!v) {
+    query.value = "";
+    window.removeEventListener("scroll", followOnScroll, true);
+    window.removeEventListener("resize", reposition);
+    return;
+  }
+  if (!btnRef.value) return;
+  query.value = "";
+  computeMenuStyle();
+  // Highlight currently-selected option (or first).
+  const idx = props.options.findIndex((o) => o.value === props.modelValue);
+  active.value = idx >= 0 ? idx : 0;
+  window.addEventListener("scroll", followOnScroll, true);
+  window.addEventListener("resize", reposition);
+});
+
+function toggle() {
+  if (props.disabled) return;
+  open.value = !open.value;
+}
+
+function pick(opt: SelectOption) {
+  emit("update:modelValue", opt.value);
+  emit("change", opt.value);
+  open.value = false;
+  nextTick(() => btnRef.value?.focus());
+}
+
+function clear(e: MouseEvent) {
+  e.stopPropagation();
+  emit("update:modelValue", null);
+  emit("change", null);
+}
+
+function onKeydown(e: KeyboardEvent) {
+  if (props.disabled) return;
+  if (!open.value) {
+    if (e.key === "Enter" || e.key === " " || e.key === "ArrowDown") {
+      e.preventDefault();
+      open.value = true;
+    }
+    return;
+  }
+  const list = filtered.value;
+  if (e.key === "Escape") {
+    e.preventDefault();
+    open.value = false;
+  } else if (e.key === "ArrowDown") {
+    e.preventDefault();
+    if (list.length) active.value = (active.value + 1) % list.length;
+  } else if (e.key === "ArrowUp") {
+    e.preventDefault();
+    if (list.length) active.value = (active.value - 1 + list.length) % list.length;
+  } else if (e.key === "Enter") {
+    e.preventDefault();
+    const opt = list[active.value];
+    if (opt) pick(opt);
+  } else if (e.key === "Backspace") {
+    e.preventDefault();
+    query.value = query.value.slice(0, -1);
+    active.value = 0;
+  } else if (props.filterable && e.key.length === 1 && !e.ctrlKey && !e.metaKey && !e.altKey) {
+    // Printable key → type-to-filter; jump the highlight back to the top.
+    e.preventDefault();
+    query.value += e.key;
+    active.value = 0;
+  }
+}
+</script>
+
+<template>
+  <div ref="wrapRef" class="wp-select-wrap">
+    <button
+      ref="btnRef"
+      type="button"
+      :class="btnClasses"
+      :disabled="disabled"
+      :aria-label="composedAriaLabel"
+      :aria-expanded="open"
+      :aria-haspopup="'listbox'"
+      :aria-invalid="error || undefined"
+      data-test="select-trigger"
+      @click="toggle"
+      @keydown="onKeydown"
+    >
+      <!-- Selected label — optional color dot prefix. Consumers can
+           override the label text rendering via the `#label` scoped
+           slot (e.g. to render `@{uuid}` ref chips instead of raw text). -->
+      <!-- `title` on the label so a value clipped by the trigger's fixed width
+           is still readable on hover. Values here run long — a constraint
+           exception source can be a phrase plus a nested `@ref` — and the
+           ellipsis alone left no way to see the rest. -->
+      <span
+        class="wp-select__label-wrap"
+        :title="selected ? (selected.meta ? `${selected.label} — ${selected.meta}` : selected.label) : undefined"
+      >
+        <i
+          v-if="selected?.icon"
+          :class="`pi pi-${selected.icon} wp-select__icon`"
+          :style="selected.dot ? { color: selected.dot } : undefined"
+          aria-hidden="true"
+        />
+        <span
+          v-else-if="selected?.dot"
+          class="wp-select__dot"
+          :style="{ background: selected.dot }"
+        />
+        <span
+          v-else-if="selected && markerWidth"
+          class="wp-select__marker-gap"
+          :style="{ width: markerWidth }"
+          aria-hidden="true"
+        />
+        <span v-if="selected" class="wp-select__label-text">
+          <slot name="label" :option="selected">{{ selected.label }}</slot>
+        </span>
+        <!-- The meta repeats in the CLOSED trigger, not just in the open menu.
+             Disambiguating rows only while the menu is open solves half the
+             problem: pick one of five identical "Outfit" rows and the trigger
+             collapses straight back to "Outfit", so the thing you just took
+             care to choose becomes unverifiable again. Shown only when the
+             option carries meta, so every dropdown that sets none is
+             untouched. -->
+        <span v-if="selected?.meta" class="wp-select__label-meta">{{ selected.meta }}</span>
+        <span v-if="!selected" class="wp-select__placeholder">{{ placeholder }}</span>
+      </span>
+      <button
+        v-if="clearable && selected"
+        type="button"
+        class="wp-select__clear"
+        aria-label="Clear"
+        data-test="select-clear"
+        @click="clear"
+      >
+        <Icon name="times" :size="ICON_SM" />
+      </button>
+      <Icon class="wp-select__chevron" name="chevron-down" />
+    </button>
+
+    <!-- Menu teleported to <body> so it escapes any overflow:hidden ancestor
+         and renders above the sticky footer regardless of z-index stacking contexts. -->
+    <Teleport to="body">
+      <ul
+        v-if="open"
+        ref="menuRef"
+        class="wp-select__menu"
+        role="listbox"
+        :style="menuStyle"
+        data-test="select-menu"
+      >
+        <li
+          v-if="query"
+          class="wp-select__filter"
+          aria-hidden="true"
+          data-test="select-filter"
+          style="display:flex;align-items:center;padding:4px 12px;font-size:11px;opacity:0.6;"
+        >Filtering: {{ query }}</li>
+        <!-- Every one of these menus is type-to-filter, but the only sign of it
+             was the "Filtering:" line, which appears AFTER you have already
+             guessed. Users asked for it to be telegraphed. Shown only once the
+             list is long enough for filtering to be worth reaching for. -->
+        <li
+          v-else-if="showFilterHint"
+          class="wp-select__hint"
+          aria-hidden="true"
+          data-test="select-filter-hint"
+          style="display:flex;align-items:center;padding:4px 12px;font-size:11px;opacity:0.45;"
+        >Type to filter</li>
+        <li
+          v-for="(opt, i) in filtered"
+          :key="String(opt.value)"
+          class="wp-select__option"
+          role="option"
+          tabindex="-1"
+          :aria-selected="opt.value === modelValue"
+          :data-active="i === active ? 'true' : 'false'"
+          :data-selected="opt.value === modelValue ? 'true' : 'false'"
+          :title="opt.title ?? (opt.meta ? `${opt.label} — ${opt.meta}` : opt.label)"
+          @mousedown.prevent="pick(opt)"
+          @mouseenter="active = i"
+          @focusin="active = i"
+        >
+          <i
+            v-if="opt.icon"
+            :class="`pi pi-${opt.icon} wp-select__icon`"
+            :style="opt.dot ? { color: opt.dot } : undefined"
+            aria-hidden="true"
+          />
+          <span
+            v-else-if="opt.dot"
+            class="wp-select__dot"
+            :style="{ background: opt.dot }"
+          />
+          <span
+            v-else-if="markerWidth"
+            class="wp-select__marker-gap"
+            :style="{ width: markerWidth }"
+            aria-hidden="true"
+          />
+          <span class="wp-select__option-label">
+            <slot name="option" :option="opt">{{ opt.label }}</slot>
+          </span>
+          <span class="wp-spacer" />
+          <span v-if="opt.meta" class="wp-select__option-meta">{{ opt.meta }}</span>
+          <Icon v-if="opt.value === modelValue" name="check" :size="ICON_SM" />
+        </li>
+        <li
+          v-if="!filtered.length"
+          class="wp-select__empty"
+          aria-disabled="true"
+          data-test="select-empty"
+          style="padding:6px 12px;opacity:0.55;"
+        >No matches</li>
+      </ul>
+    </Teleport>
+  </div>
+</template>
+
+<!--
+  Self-contained styles so <Select> works everywhere it's used — including the
+  ComfyUI CANVAS widget bundle, which does NOT load the manager-global
+  tokens.css (that's why an unstyled Select rendered behind the modal there).
+  Class names stay wp-select* (global-namespaced, no collision); the menu is
+  teleported to <body>, so these are UNSCOPED — same pattern as the
+  RichTextInput autocomplete (wp-rt-suggestions), sharing its POPOVER tier
+  (10020) so the menu clears every modal overlay — those run up to 10010, so
+  the previous 9999 rendered the menu behind any modal above that. Vars fall
+  back to literals for the few the
+  canvas theme doesn't define (--wp-input-h[-sm], --wp-focus-ring). In the SPA
+  these duplicate tokens.css with identical rules — harmless.
+-->
+<style>
+.wp-select-wrap { position: relative; display: inline-block; width: 100%; }
+
+/* Trigger button — the manager .wp-input base (height/bg/border/…) inlined
+ * here + flex layout for label · spacer · chevron. */
+.wp-select {
+  display: flex;
+  align-items: center;
+  gap: 4px;
+  width: 100%;
+  height: var(--wp-input-h, 34px);
+  box-sizing: border-box;
+  padding: 0 10px;
+  text-align: left;
+  cursor: pointer;
+  appearance: none;
+  -webkit-appearance: none;
+  background: var(--wp-bg-2);
+  color: var(--wp-text);
+  border: 1px solid var(--wp-border, rgba(255, 255, 255, 0.08));
+  border-radius: var(--wp-radius-sm);
+  font-size: 12.5px;
+  font-family: inherit;
+  outline: none;
+  transition: border-color 0.12s, background 0.12s, box-shadow 0.12s;
+}
+.wp-select--sm { height: var(--wp-input-h-sm, 24px); font-size: 12px; padding: 0 8px; }
+.wp-select--lg { height: var(--wp-control-h-lg, 40px); font-size: 13.5px; padding: 0 12px; }
+.wp-select:focus-visible,
+.wp-select:focus {
+  border-color: var(--wp-accent-500);
+  box-shadow: var(--wp-focus-ring, 0 0 0 3px color-mix(in oklab, var(--wp-accent-500) 25%, transparent));
+  background: var(--wp-bg-1);
+}
+.wp-select[aria-invalid="true"] { border-color: var(--wp-error-border, var(--wp-danger, #ef4444)); }
+.wp-select:disabled { opacity: 0.45; cursor: not-allowed; }
+
+.wp-select__label-wrap {
+  display: flex; align-items: center; gap: 6px;
+  flex: 1; min-width: 0; overflow: hidden;
+}
+.wp-select__dot { width: 8px; height: 8px; border-radius: 50%; /* round: colour dot */ flex-shrink: 0; display: inline-block; }
+/* Empty stand-in that holds the icon/dot column open for options without one.
+ * Width is set inline from `markerWidth`, since it depends on what the list
+ * actually contains. */
+.wp-select__marker-gap { flex-shrink: 0; display: inline-block; }
+/* Fixed square, centred: an icon font's glyphs have varying advance widths and
+ * a line box taller than the mark itself, so a bare `<i>` sat off-centre next
+ * to the label and shifted horizontally between categories. Sizing the BOX and
+ * centring the glyph inside it fixes both, and keeps a constant offset to the
+ * label whether the option shows an icon or the dot it replaces.
+ * Falls back to the dim text colour when a category has an icon but no colour. */
+.wp-select__icon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 14px;
+  height: 14px;
+  font-size: 12px;
+  line-height: 1;
+  flex-shrink: 0;
+  color: var(--wp-text-dim);
+}
+.wp-select__label-text,
+.wp-select__placeholder {
+  flex: 1; min-width: 0;
+  overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
+}
+.wp-select__placeholder { color: var(--wp-text-dim); }
+/* Trigger-side twin of `.wp-select__option-meta`, same mono/dim treatment so
+ * the detail you picked in the menu is recognisably the same string once the
+ * menu closes.
+ *
+ * `flex: 0 1 auto` against the label's `flex: 1`: spare width goes to the
+ * NAME, which is what the user reads first, while both stay shrinkable so a
+ * long meta clips itself rather than pushing the name out of the trigger. */
+.wp-select__label-meta {
+  flex: 0 1 auto;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  font-family: var(--wp-font-mono);
+  font-size: 10px;
+  color: var(--wp-text-dim);
+}
+.wp-select__chevron { color: var(--wp-text-dim); font-size: 11px; margin-left: 6px; flex-shrink: 0; }
+/* Clear ✕: a plain glyph kept well clear of the chevron (a 1px rule and
+ * 8px either side) so it is not mis-clicked, and shown only while the
+ * field is hovered or focused. The ::after gives it a 20px click target. */
+.wp-select__clear {
+  position: relative;
+  display: inline-grid; place-items: center; flex-shrink: 0;
+  width: 14px; height: 14px; margin: 0 2px 0 8px; padding: 0;
+  background: none; border: none; color: var(--wp-text-dim); cursor: pointer; line-height: 0;
+  opacity: 0; transition: opacity .12s, color .12s;
+}
+.wp-select__clear::after { content: ""; position: absolute; inset: -3px; }
+.wp-select__clear + .wp-select__chevron {
+  align-self: stretch; display: inline-flex; align-items: center;
+  margin: 6px 0 6px 6px; padding-left: 8px; border-left: 1px solid var(--wp-border);
+}
+.wp-select:hover .wp-select__clear,
+.wp-select:focus-visible .wp-select__clear,
+.wp-select:focus .wp-select__clear,
+.wp-select__clear:focus-visible { opacity: 1; }
+.wp-select__clear:hover { color: var(--wp-text); }
+.wp-select__clear:focus-visible { outline: 2px solid var(--wp-accent-500); outline-offset: 1px; border-radius: min(2px, var(--wp-radius-cap, 999px)); }
+@media (hover: none) { .wp-select__clear { opacity: 1; } }
+.wp-spacer { flex: 1 1 auto; }
+
+/* Menu — teleported to <body>. z-index 9999 matches wp-rt-suggestions, which
+ * already renders above the canvas modals. */
+.wp-select__menu {
+  /* One line box for an option label, in px so a leading dot/icon can be
+   * centred against it without the em-resolves-against-its-own-font-size trap
+   * (the icon runs at 12px, the label at 12.5px, so `1.5em` means two
+   * different heights depending on which element it is declared on).
+   * The menu teleports to <body>, so it carries its own copy. */
+  --wp-select-line-h: 18.75px;
+  background: var(--wp-bg-3);
+  border: 1px solid var(--wp-border-strong);
+  border-radius: min(7px, var(--wp-radius-cap, 999px));
+  box-shadow: var(--wp-shadow-md);
+  z-index: 10020;
+  padding: 4px;
+  max-height: 240px;
+  overflow: auto;
+  list-style: none;
+  margin: 0;
+}
+.wp-select__option {
+  display: flex; align-items: center; gap: 6px;
+  padding: 6px 8px;
+  border-radius: min(6px, var(--wp-radius-cap, 999px));
+  color: var(--wp-text-muted);
+  cursor: pointer;
+  font-size: 12.5px;
+  user-select: none;
+}
+.wp-select__option:hover { background: var(--wp-bg-4); color: var(--wp-text); }
+.wp-select__option[data-active="true"] {
+  background: color-mix(in oklab, var(--wp-accent-500) 20%, transparent);
+  color: var(--wp-text);
+}
+.wp-select__option[data-selected="true"] {
+  background: color-mix(in oklab, var(--wp-accent-500) 18%, transparent);
+  color: var(--wp-text);
+}
+/* Option rows WRAP (to two lines) rather than ellipsis-clipping at the first.
+ * The menu is up to 620px wide and these values run long — a constraint
+ * exception source is a whole phrase plus a nested `@ref` — so clipping them
+ * to one line hid the part that distinguishes one option from another. The
+ * trigger still clips to a single line (it has a fixed height); the menu is
+ * where the user is actually reading. `min-width: 0` keeps the meta + tick on
+ * screen either way. */
+.wp-select__option-label {
+  /* `flex: 0 1 auto` not `1`: at basis 0 it split the row 50/50 with the
+     always-present .wp-spacer, so a SHORT option (a nowrap mode chip) got
+     squeezed to half-width and clipped by the overflow:hidden below — even
+     with room to spare. Sizing to content lets the spacer do the filling; a
+     long option still shrinks (flex-shrink:1) into the 2-line clamp. */
+  flex: 0 1 auto;
+  min-width: 0;
+  /* Explicit rather than `normal` so the leading dot/icon can be centred
+   * against exactly this height — and so `line-clamp` measures a known line. */
+  line-height: var(--wp-select-line-h);
+  white-space: normal;
+  overflow-wrap: anywhere;
+  display: -webkit-box;
+  -webkit-line-clamp: 2;
+  line-clamp: 2;
+  -webkit-box-orient: vertical;
+  overflow: hidden;
+}
+.wp-select__option { align-items: flex-start; }
+/* Because the row aligns to flex-start, a leading dot or icon lines up with the
+ * TOP of the label rather than its first line, and reads as sitting too high.
+ * Both are re-centred against one line box here — scoped to the option, since
+ * the trigger row is `align-items: center` and would be thrown off by it. */
+.wp-select__option > .wp-select__icon { height: var(--wp-select-line-h); }
+.wp-select__option > .wp-select__dot {
+  margin-top: calc((var(--wp-select-line-h) - 8px) / 2);
+}
+/* Disambiguating detail (option count + uuid). Never shrinks — it is the
+ * whole point of the row when several options share a label. */
+.wp-select__option-meta {
+  flex-shrink: 0;
+  margin-left: var(--wp-space-3, 8px);
+  font-family: var(--wp-font-mono);
+  font-size: 10px;
+  color: var(--wp-text-dim);
+}
+.wp-select__filter { display: flex; align-items: center; padding: 4px 12px; font-size: 11px; opacity: 0.6; }
+.wp-select__empty { padding: 6px 12px; opacity: 0.55; }
+
+/* Rich content (RichTextPreview / chips) rendered via the #label / #option
+ * slots defaults to pre-wrap (RichTextPreview's own scoped rule).
+ *
+ * The TRIGGER stays forced to one line: it has a fixed height, so wrapping
+ * blows up the surrounding row. `!important` beats RichTextPreview's scoped
+ * `.wp-rtp` rule from outside the component.
+ *
+ * OPTION rows deliberately do NOT get that treatment any more. Forcing them
+ * to one line was what truncated constraint-exception values — a phrase plus a
+ * nested `@ref` — at the point where they stop being distinguishable. They now
+ * wrap within the two-line clamp above, inside the menu's 620px max-width. */
+.wp-select__label-text .wp-rtp,
+.wp-select__label-text .wp-rtp__text {
+  white-space: nowrap !important;
+}
+.wp-select__option-label .wp-rtp,
+.wp-select__option-label .wp-rtp__text {
+  white-space: normal !important;
+  overflow-wrap: anywhere;
+}
+.wp-select__menu { max-width: min(620px, 92vw); }
+</style>

package/src/Separator.vue

@@ -0,0 +1,54 @@
+<script setup lang="ts">
+/**
+ * Separator: a thin line between groups, across or upright, with optional
+ * text in the middle ("or"). Works on the canvas and in the manager.
+ *
+ *   <Separator />
+ *   <Separator label="or" />
+ *   <Separator orientation="vertical" />   (inside a Toolbar or a row)
+ *
+ * It is decorative by default (screen readers skip it). Set
+ * `decorative=false` when it really divides two parts of the content.
+ */
+withDefaults(defineProps<{
+  orientation?: "horizontal" | "vertical" | undefined;
+  /** Text in the middle of a horizontal line. */
+  label?: string | undefined;
+  decorative?: boolean | undefined;
+  /** Room around the line. */
+  spacing?: "none" | "sm" | "md" | "lg" | undefined;
+}>(), { orientation: "horizontal", label: undefined, decorative: true, spacing: "sm" });
+</script>
+
+<template>
+  <div
+    class="wp-separator"
+    :data-orientation="orientation"
+    :data-spacing="spacing"
+    :data-labelled="label ? 'true' : undefined"
+    :role="decorative ? 'none' : 'separator'"
+    :aria-orientation="!decorative && orientation === 'vertical' ? 'vertical' : undefined"
+  >
+    <span v-if="label && orientation === 'horizontal'" class="wp-separator__label">{{ label }}</span>
+  </div>
+</template>
+
+<style scoped>
+.wp-separator { flex: none; align-self: stretch; }
+.wp-separator[data-orientation="horizontal"] { height: 1px; width: 100%; background: var(--wp-border); }
+.wp-separator[data-orientation="vertical"] { width: 1px; min-height: 1em; background: var(--wp-border); }
+.wp-separator[data-orientation="horizontal"][data-spacing="sm"] { margin: var(--wp-space-3) 0; }
+.wp-separator[data-orientation="horizontal"][data-spacing="md"] { margin: var(--wp-space-5) 0; }
+.wp-separator[data-orientation="horizontal"][data-spacing="lg"] { margin: var(--wp-space-7) 0; }
+.wp-separator[data-orientation="vertical"][data-spacing="sm"] { margin: 0 var(--wp-space-2); }
+.wp-separator[data-orientation="vertical"][data-spacing="md"] { margin: 0 var(--wp-space-4); }
+.wp-separator[data-orientation="vertical"][data-spacing="lg"] { margin: 0 var(--wp-space-6); }
+.wp-separator[data-labelled] {
+  display: flex; align-items: center; gap: var(--wp-space-4); height: auto; background: none;
+  color: var(--wp-text-dim); font: 600 var(--wp-text-xs)/1 var(--wp-font-sans);
+  text-transform: uppercase; letter-spacing: 0.06em;
+}
+.wp-separator[data-labelled]::before, .wp-separator[data-labelled]::after {
+  content: ""; flex: 1; height: 1px; background: var(--wp-border);
+}
+</style>