@karyl-chan/ui 0.3.0 → 0.5.0

package/src/components/AppTabs.vue

@@ -1,9 +1,10 @@
 <script setup lang="ts">
-import { computed } from 'vue';
+import { computed, useId } from 'vue';
 import { Icon } from '@iconify/vue';
 import { useBreakpoint } from '../composables/use-breakpoint';
 import AppSelectField, { type SelectOption } from './AppSelectField.vue';
 import type { TabDef } from './tab-types';
+import { onTablistKeydown, rovingTabKey } from './tab-keyboard';
 
 export type { TabDef };
 
@@ -21,6 +22,12 @@ export type { TabDef };
  * Mobile (≤768px):
  *   - Both rows collapse to AppSelectField dropdowns stacked vertically.
  *
+ * Keyboard (desktop, WAI-ARIA tabs pattern): each tablist is a single
+ * Tab stop (roving tabindex on the selected tab); ArrowLeft/ArrowRight
+ * (ArrowUp/ArrowDown in the vertical sidebar) and Home/End move between
+ * tabs, skipping disabled ones, and select as they go. The panel is a
+ * `role="tabpanel"` labelled by the selected sub-tab (or primary tab).
+ *
  * If you need URL-synced tabs with deep-linkable hrefs, use
  * `AppTabsRouted` from this package (a thin wrapper that adds
  * `vue-router` integration on top).
@@ -32,10 +39,19 @@ const props = withDefaults(defineProps<{
     subTabs?: TabDef[];
     /** Where sub-tabs render on desktop. Has no effect on mobile. */
     subLayout?: 'top' | 'sidebar';
+    /**
+     * Primary-tab appearance (desktop only — mobile always uses the
+     * dropdown). `'pill'` (default) = filled/bordered pill buttons;
+     * `'underline'` = borderless tabs with an accent underline on the
+     * active one (the quieter, header-strip look). Sub-tabs are always
+     * underline-styled regardless.
+     */
+    variant?: 'pill' | 'underline';
 }>(), {
     subModelValue: undefined,
     subTabs: () => [],
-    subLayout: 'top'
+    subLayout: 'top',
+    variant: 'pill'
 });
 
 const emit = defineEmits<{
@@ -56,6 +72,27 @@ const primaryOptions = computed<SelectOption<string>[]>(() =>
 const subOptions = computed<SelectOption<string>[]>(() =>
     props.subTabs.map(t => ({ value: t.key, label: t.label }))
 );
+
+// ── ARIA wiring ──────────────────────────────────────────────────────
+// Ids are index-based (keys may contain characters that aren't valid in
+// an id). One panel serves every tab, so all tabs point at it.
+const uid = useId();
+const panelId = `${uid}-panel`;
+const tabId = (i: number) => `${uid}-tab-${i}`;
+const subTabId = (i: number) => `${uid}-sub-${i}`;
+const primaryRoving = computed(() => rovingTabKey(props.tabs, props.modelValue));
+const subRoving = computed(() => rovingTabKey(props.subTabs, props.subModelValue));
+const panelLabelledBy = computed(() => {
+    if (hasSub.value) {
+        const si = props.subTabs.findIndex(t => t.key === props.subModelValue);
+        if (si !== -1) return subTabId(si);
+    }
+    const pi = props.tabs.findIndex(t => t.key === props.modelValue);
+    return pi !== -1 ? tabId(pi) : undefined;
+});
+function onPrimaryKeydown(e: KeyboardEvent) { onTablistKeydown(e, props.tabs, pickPrimary); }
+function onSubKeydown(e: KeyboardEvent) { onTablistKeydown(e, props.subTabs, pickSub); }
+function onSubSideKeydown(e: KeyboardEvent) { onTablistKeydown(e, props.subTabs, pickSub, 'vertical'); }
 </script>
 
 <template>
@@ -82,16 +119,20 @@ const subOptions = computed<SelectOption<string>[]>(() =>
     <!-- Desktop, sub-tabs below primary. -->
     <div
         v-else-if="!hasSub || subLayout === 'top'"
-        class="tabs-root desktop top"
+        :class="['tabs-root', 'desktop', 'top', { underline: variant === 'underline' }]"
     >
-        <nav class="primary-row" role="tablist">
+        <nav class="primary-row" role="tablist" @keydown="onPrimaryKeydown">
             <button
-                v-for="t in tabs"
+                v-for="(t, i) in tabs"
+                :id="tabId(i)"
                 :key="t.key"
                 type="button"
                 role="tab"
                 :class="['tab', { active: t.key === modelValue }]"
                 :aria-selected="t.key === modelValue"
+                :aria-controls="panelId"
+                :tabindex="t.key === primaryRoving ? 0 : -1"
+                :data-tab-key="t.key"
                 :disabled="t.disabled"
                 @click="!t.disabled && pickPrimary(t.key)"
             >
@@ -99,14 +140,18 @@ const subOptions = computed<SelectOption<string>[]>(() =>
                 <span>{{ t.label }}</span>
             </button>
         </nav>
-        <nav v-if="hasSub" class="sub-row" role="tablist">
+        <nav v-if="hasSub" class="sub-row" role="tablist" @keydown="onSubKeydown">
             <button
-                v-for="t in subTabs"
+                v-for="(t, i) in subTabs"
+                :id="subTabId(i)"
                 :key="t.key"
                 type="button"
                 role="tab"
                 :class="['sub-tab', { active: t.key === subModelValue }]"
                 :aria-selected="t.key === subModelValue"
+                :aria-controls="panelId"
+                :tabindex="t.key === subRoving ? 0 : -1"
+                :data-tab-key="t.key"
                 :disabled="t.disabled"
                 @click="!t.disabled && pickSub(t.key)"
             >
@@ -114,21 +159,25 @@ const subOptions = computed<SelectOption<string>[]>(() =>
                 <span>{{ t.label }}</span>
             </button>
         </nav>
-        <div class="panel">
+        <div :id="panelId" class="panel" role="tabpanel" :aria-labelledby="panelLabelledBy">
             <slot />
         </div>
     </div>
 
     <!-- Desktop, sub-tabs as a vertical sidebar. -->
-    <div v-else class="tabs-root desktop sidebar">
-        <nav class="primary-row" role="tablist">
+    <div v-else :class="['tabs-root', 'desktop', 'sidebar', { underline: variant === 'underline' }]">
+        <nav class="primary-row" role="tablist" @keydown="onPrimaryKeydown">
             <button
-                v-for="t in tabs"
+                v-for="(t, i) in tabs"
+                :id="tabId(i)"
                 :key="t.key"
                 type="button"
                 role="tab"
                 :class="['tab', { active: t.key === modelValue }]"
                 :aria-selected="t.key === modelValue"
+                :aria-controls="panelId"
+                :tabindex="t.key === primaryRoving ? 0 : -1"
+                :data-tab-key="t.key"
                 :disabled="t.disabled"
                 @click="!t.disabled && pickPrimary(t.key)"
             >
@@ -137,14 +186,18 @@ const subOptions = computed<SelectOption<string>[]>(() =>
             </button>
         </nav>
         <div class="split">
-            <nav class="sub-side" role="tablist">
+            <nav class="sub-side" role="tablist" aria-orientation="vertical" @keydown="onSubSideKeydown">
                 <button
-                    v-for="t in subTabs"
+                    v-for="(t, i) in subTabs"
+                    :id="subTabId(i)"
                     :key="t.key"
                     type="button"
                     role="tab"
                     :class="['sub-side-tab', { active: t.key === subModelValue }]"
                     :aria-selected="t.key === subModelValue"
+                    :aria-controls="panelId"
+                    :tabindex="t.key === subRoving ? 0 : -1"
+                    :data-tab-key="t.key"
                     :disabled="t.disabled"
                     @click="!t.disabled && pickSub(t.key)"
                 >
@@ -152,7 +205,7 @@ const subOptions = computed<SelectOption<string>[]>(() =>
                     <span>{{ t.label }}</span>
                 </button>
             </nav>
-            <div class="panel side-panel">
+            <div :id="panelId" class="panel side-panel" role="tabpanel" :aria-labelledby="panelLabelledBy">
                 <slot />
             </div>
         </div>
@@ -213,6 +266,34 @@ const subOptions = computed<SelectOption<string>[]>(() =>
 }
 .tab:disabled { opacity: 0.45; cursor: default; }
 
+/* Underline variant — borderless primary tabs with an accent underline on
+   the active one (mirrors the plugin-aktest nav strip and the sub-tab
+   treatment). Railless: the row drops its bottom border so each tab owns
+   its own indicator. */
+.tabs-root.underline .primary-row {
+    border-bottom: none;
+    padding-bottom: 0;
+    gap: 0.15rem;
+}
+.tabs-root.underline .tab {
+    background: none;
+    border: none;
+    border-radius: 0;
+    border-bottom: 2px solid transparent;
+    color: var(--text-muted);
+    padding: 0.45rem 0.6rem;
+}
+.tabs-root.underline .tab:hover:not(:disabled) {
+    background: none;
+    color: var(--text);
+}
+.tabs-root.underline .tab.active {
+    background: none;
+    border-color: transparent;
+    border-bottom-color: var(--accent);
+    color: var(--accent-text-strong);
+}
+
 .sub-row {
     display: flex;
     gap: 0.6rem;

package/src/components/AppTabsRouted.vue

@@ -15,16 +15,22 @@
  * which does NOT import vue-router and so doesn't pull it into your
  * plugin SPA's bundle.
  *
+ * Keyboard / ARIA behaviour matches AppTabs (roving tabindex, Arrow /
+ * Home / End navigation skipping disabled tabs, tabpanel wiring); a
+ * keyboard move updates the URL with `router.replace` so arrowing across
+ * tabs does not flood the history stack.
+ *
  * NB: separate component (vs an `routed` prop on AppTabs) so that
  * plugin SPAs that never use routed tabs don't transitively depend on
  * `vue-router`.
  */
-import { computed, ref, watch } from 'vue';
+import { computed, ref, useId, watch } from 'vue';
 import { useRoute, useRouter, RouterLink, type LocationQueryRaw } from 'vue-router';
 import { Icon } from '@iconify/vue';
 import { useBreakpoint } from '../composables/use-breakpoint';
 import AppSelectField, { type SelectOption } from './AppSelectField.vue';
 import type { TabDef } from './tab-types';
+import { onTablistKeydown, rovingTabKey } from './tab-keyboard';
 
 const props = withDefaults(defineProps<{
     modelValue: string;
@@ -36,11 +42,16 @@ const props = withDefaults(defineProps<{
      *  routed AppTabs share a page. Empty (default) = plain `tab` /
      *  `sub`; non-empty = `${name}-tab` / `${name}-sub`. */
     name?: string;
+    /** Primary-tab appearance (desktop only). `'pill'` (default) = filled
+     *  pill buttons; `'underline'` = borderless with an accent underline on
+     *  the active tab. Matches AppTabs' `variant`. */
+    variant?: 'pill' | 'underline';
 }>(), {
     subModelValue: undefined,
     subTabs: () => [],
     subLayout: 'top',
-    name: ''
+    name: '',
+    variant: 'pill'
 });
 
 const emit = defineEmits<{
@@ -128,6 +139,27 @@ function subLinkTo(key: string) {
     q[subKey.value] = key === defaultSub.value ? undefined : key;
     return { path: route.path, query: q };
 }
+
+// -- ARIA wiring (mirrors AppTabs) --------------------------------------
+const uid = useId();
+const panelId = `${uid}-panel`;
+const tabId = (i: number) => `${uid}-tab-${i}`;
+const subTabId = (i: number) => `${uid}-sub-${i}`;
+const primaryRoving = computed(() => rovingTabKey(props.tabs, props.modelValue));
+const subRoving = computed(() => rovingTabKey(props.subTabs, props.subModelValue));
+const panelLabelledBy = computed(() => {
+    if (hasSub.value) {
+        const si = props.subTabs.findIndex(t => t.key === props.subModelValue);
+        if (si !== -1) return subTabId(si);
+    }
+    const pi = props.tabs.findIndex(t => t.key === props.modelValue);
+    return pi !== -1 ? tabId(pi) : undefined;
+});
+function keyPrimary(key: string) { router.replace(tabLinkTo(key)); }
+function keySub(key: string) { router.replace(subLinkTo(key)); }
+function onPrimaryKeydown(e: KeyboardEvent) { onTablistKeydown(e, props.tabs, keyPrimary); }
+function onSubKeydown(e: KeyboardEvent) { onTablistKeydown(e, props.subTabs, keySub); }
+function onSubSideKeydown(e: KeyboardEvent) { onTablistKeydown(e, props.subTabs, keySub, 'vertical'); }
 </script>
 
 <template>
@@ -154,26 +186,34 @@ function subLinkTo(key: string) {
     <!-- Desktop, sub-tabs below primary. -->
     <div
         v-else-if="!hasSub || subLayout === 'top'"
-        class="tabs-root desktop top"
+        :class="['tabs-root', 'desktop', 'top', { underline: variant === 'underline' }]"
     >
-        <nav class="primary-row" role="tablist">
-            <template v-for="t in tabs" :key="t.key">
+        <nav class="primary-row" role="tablist" @keydown="onPrimaryKeydown">
+            <template v-for="(t, i) in tabs" :key="t.key">
                 <RouterLink
                     v-if="!t.disabled"
+                    :id="tabId(i)"
                     :to="tabLinkTo(t.key)"
                     role="tab"
                     :class="['tab', { active: t.key === modelValue }]"
                     :aria-selected="t.key === modelValue"
+                    :aria-controls="panelId"
+                    :tabindex="t.key === primaryRoving ? 0 : -1"
+                    :data-tab-key="t.key"
                 >
                     <Icon v-if="t.icon" :icon="t.icon" width="16" height="16" />
                     <span>{{ t.label }}</span>
                 </RouterLink>
                 <button
                     v-else
+                    :id="tabId(i)"
                     type="button"
                     role="tab"
                     :class="['tab', { active: t.key === modelValue }]"
                     :aria-selected="t.key === modelValue"
+                    :aria-controls="panelId"
+                    tabindex="-1"
+                    :data-tab-key="t.key"
                     disabled
                 >
                     <Icon v-if="t.icon" :icon="t.icon" width="16" height="16" />
@@ -181,24 +221,32 @@ function subLinkTo(key: string) {
                 </button>
             </template>
         </nav>
-        <nav v-if="hasSub" class="sub-row" role="tablist">
-            <template v-for="t in subTabs" :key="t.key">
+        <nav v-if="hasSub" class="sub-row" role="tablist" @keydown="onSubKeydown">
+            <template v-for="(t, i) in subTabs" :key="t.key">
                 <RouterLink
                     v-if="!t.disabled"
+                    :id="subTabId(i)"
                     :to="subLinkTo(t.key)"
                     role="tab"
                     :class="['sub-tab', { active: t.key === subModelValue }]"
                     :aria-selected="t.key === subModelValue"
+                    :aria-controls="panelId"
+                    :tabindex="t.key === subRoving ? 0 : -1"
+                    :data-tab-key="t.key"
                 >
                     <Icon v-if="t.icon" :icon="t.icon" width="14" height="14" />
                     <span>{{ t.label }}</span>
                 </RouterLink>
                 <button
                     v-else
+                    :id="subTabId(i)"
                     type="button"
                     role="tab"
                     :class="['sub-tab', { active: t.key === subModelValue }]"
                     :aria-selected="t.key === subModelValue"
+                    :aria-controls="panelId"
+                    tabindex="-1"
+                    :data-tab-key="t.key"
                     disabled
                 >
                     <Icon v-if="t.icon" :icon="t.icon" width="14" height="14" />
@@ -206,31 +254,39 @@ function subLinkTo(key: string) {
                 </button>
             </template>
         </nav>
-        <div class="panel">
+        <div :id="panelId" class="panel" role="tabpanel" :aria-labelledby="panelLabelledBy">
             <slot />
         </div>
     </div>
 
     <!-- Desktop, sub-tabs as a vertical sidebar. -->
-    <div v-else class="tabs-root desktop sidebar">
-        <nav class="primary-row" role="tablist">
-            <template v-for="t in tabs" :key="t.key">
+    <div v-else :class="['tabs-root', 'desktop', 'sidebar', { underline: variant === 'underline' }]">
+        <nav class="primary-row" role="tablist" @keydown="onPrimaryKeydown">
+            <template v-for="(t, i) in tabs" :key="t.key">
                 <RouterLink
                     v-if="!t.disabled"
+                    :id="tabId(i)"
                     :to="tabLinkTo(t.key)"
                     role="tab"
                     :class="['tab', { active: t.key === modelValue }]"
                     :aria-selected="t.key === modelValue"
+                    :aria-controls="panelId"
+                    :tabindex="t.key === primaryRoving ? 0 : -1"
+                    :data-tab-key="t.key"
                 >
                     <Icon v-if="t.icon" :icon="t.icon" width="16" height="16" />
                     <span>{{ t.label }}</span>
                 </RouterLink>
                 <button
                     v-else
+                    :id="tabId(i)"
                     type="button"
                     role="tab"
                     :class="['tab', { active: t.key === modelValue }]"
                     :aria-selected="t.key === modelValue"
+                    :aria-controls="panelId"
+                    tabindex="-1"
+                    :data-tab-key="t.key"
                     disabled
                 >
                     <Icon v-if="t.icon" :icon="t.icon" width="16" height="16" />
@@ -239,24 +295,32 @@ function subLinkTo(key: string) {
             </template>
         </nav>
         <div class="split">
-            <nav class="sub-side" role="tablist">
-                <template v-for="t in subTabs" :key="t.key">
+            <nav class="sub-side" role="tablist" aria-orientation="vertical" @keydown="onSubSideKeydown">
+                <template v-for="(t, i) in subTabs" :key="t.key">
                     <RouterLink
                         v-if="!t.disabled"
+                        :id="subTabId(i)"
                         :to="subLinkTo(t.key)"
                         role="tab"
                         :class="['sub-side-tab', { active: t.key === subModelValue }]"
                         :aria-selected="t.key === subModelValue"
+                        :aria-controls="panelId"
+                        :tabindex="t.key === subRoving ? 0 : -1"
+                        :data-tab-key="t.key"
                     >
                         <Icon v-if="t.icon" :icon="t.icon" width="16" height="16" />
                         <span>{{ t.label }}</span>
                     </RouterLink>
                     <button
                         v-else
+                        :id="subTabId(i)"
                         type="button"
                         role="tab"
                         :class="['sub-side-tab', { active: t.key === subModelValue }]"
                         :aria-selected="t.key === subModelValue"
+                        :aria-controls="panelId"
+                        tabindex="-1"
+                        :data-tab-key="t.key"
                         disabled
                     >
                         <Icon v-if="t.icon" :icon="t.icon" width="16" height="16" />
@@ -264,7 +328,7 @@ function subLinkTo(key: string) {
                     </button>
                 </template>
             </nav>
-            <div class="panel side-panel">
+            <div :id="panelId" class="panel side-panel" role="tabpanel" :aria-labelledby="panelLabelledBy">
                 <slot />
             </div>
         </div>
@@ -277,6 +341,8 @@ function subLinkTo(key: string) {
     flex-direction: column;
     gap: 0.7rem;
     min-height: 0;
+    /* Span the parent's cross-axis - see AppTabs.vue. */
+    width: 100%;
     flex: 1;
 }
 
@@ -285,7 +351,10 @@ function subLinkTo(key: string) {
     gap: 0.4rem;
     border-bottom: 1px solid var(--border);
     padding-bottom: 0.5rem;
+    /* Horizontal scroll only; `overflow-y: hidden` stops the implicit
+       vertical scrollbar - see AppTabs.vue. */
     overflow-x: auto;
+    overflow-y: hidden;
     scrollbar-width: thin;
     flex-shrink: 0;
 }
@@ -313,11 +382,37 @@ function subLinkTo(key: string) {
 }
 .tab:disabled { opacity: 0.45; cursor: default; }
 
+/* Underline variant — see AppTabs.vue. Kept in sync with its plain sibling. */
+.tabs-root.underline .primary-row {
+    border-bottom: none;
+    padding-bottom: 0;
+    gap: 0.15rem;
+}
+.tabs-root.underline .tab {
+    background: none;
+    border: none;
+    border-radius: 0;
+    border-bottom: 2px solid transparent;
+    color: var(--text-muted);
+    padding: 0.45rem 0.6rem;
+}
+.tabs-root.underline .tab:hover:not(:disabled) {
+    background: none;
+    color: var(--text);
+}
+.tabs-root.underline .tab.active {
+    background: none;
+    border-color: transparent;
+    border-bottom-color: var(--accent);
+    color: var(--accent-text-strong);
+}
+
 .sub-row {
     display: flex;
     gap: 0.6rem;
     border-bottom: 1px solid var(--border);
     overflow-x: auto;
+    overflow-y: hidden;
     scrollbar-width: thin;
     margin-top: -0.3rem;
     flex-shrink: 0;

package/src/components/AppToast.vue

@@ -1,7 +1,35 @@
 <script setup lang="ts">
-import { useToastStore } from '../stores/toastStore';
+import { Icon } from '@iconify/vue';
+import { useToastStore, type ToastItem } from '../stores/toastStore';
+
+/**
+ * Toast host — mount once near the app root. Renders `useToastStore()`
+ * items bottom-right.
+ *
+ * - `error` / `warn` toasts are `role="alert"` (assertive); `info` /
+ *   `success` are `role="status"` + `aria-live="polite"`.
+ * - Timed toasts dismiss on click (as before); sticky toasts
+ *   (`duration: 0`) only via their close button, so a stray click
+ *   doesn't throw away a message the user is meant to act on.
+ */
+withDefaults(defineProps<{
+    /** Accessible label of a sticky toast's close button. */
+    closeLabel?: string;
+}>(), {
+    closeLabel: 'Dismiss'
+});
 
 const toast = useToastStore();
+
+function isSticky(item: ToastItem) {
+    return item.duration === 0;
+}
+function isAssertive(item: ToastItem) {
+    return item.type === 'error' || item.type === 'warn';
+}
+function onItemClick(item: ToastItem) {
+    if (!isSticky(item)) toast.dismiss(item.id);
+}
 </script>
 
 <template>
@@ -11,10 +39,21 @@ const toast = useToastStore();
                 v-for="item in toast.items"
                 :key="item.id"
                 class="toast-item"
-                :class="`toast-item--${item.type}`"
-                @click="toast.dismiss(item.id)"
+                :class="[`toast-item--${item.type}`, { 'toast-item--sticky': isSticky(item) }]"
+                :role="isAssertive(item) ? 'alert' : 'status'"
+                :aria-live="isAssertive(item) ? undefined : 'polite'"
+                @click="onItemClick(item)"
             >
-                {{ item.message }}
+                <span class="toast-message">{{ item.message }}</span>
+                <button
+                    v-if="isSticky(item)"
+                    type="button"
+                    class="toast-close"
+                    :aria-label="closeLabel"
+                    @click.stop="toast.dismiss(item.id)"
+                >
+                    <Icon icon="material-symbols:close-rounded" width="16" height="16" />
+                </button>
             </div>
         </TransitionGroup>
     </Teleport>
@@ -40,7 +79,34 @@ const toast = useToastStore();
     font-size: 0.82rem;
     line-height: 1.4;
     box-shadow: 0 4px 14px rgba(0, 0, 0, 0.25);
+    display: flex;
+    align-items: flex-start;
+    gap: 0.5rem;
+}
+.toast-item--sticky {
+    cursor: default;
+    padding-right: 0.35rem;
 }
+.toast-message {
+    flex: 1;
+    min-width: 0;
+    overflow-wrap: anywhere;
+}
+.toast-close {
+    flex-shrink: 0;
+    background: none;
+    border: none;
+    color: inherit;
+    opacity: 0.75;
+    cursor: pointer;
+    padding: 0.1rem;
+    margin: -0.1rem 0;
+    border-radius: var(--radius-sm, 4px);
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+}
+.toast-close:hover { opacity: 1; }
 .toast-item--error {
     background: var(--danger, #ef4444);
     color: #fff;
@@ -50,6 +116,16 @@ const toast = useToastStore();
     color: var(--text, #cdd6f4);
     border: 1px solid var(--border, #45475a);
 }
+.toast-item--success {
+    background: var(--success-bg, #d1fae5);
+    color: var(--success-text, #065f46);
+    border: 1px solid var(--border, #45475a);
+}
+.toast-item--warn {
+    background: var(--warn-bg, #fef3c7);
+    color: var(--warn-text, #92400e);
+    border: 1px solid var(--border, #45475a);
+}
 .toast-enter-active,
 .toast-leave-active {
     transition: all 0.25s ease;
@@ -62,4 +138,14 @@ const toast = useToastStore();
     opacity: 0;
     transform: translateX(1rem);
 }
+@media (prefers-reduced-motion: reduce) {
+    .toast-enter-active,
+    .toast-leave-active {
+        transition: opacity 0.15s ease;
+    }
+    .toast-enter-from,
+    .toast-leave-to {
+        transform: none;
+    }
+}
 </style>

package/src/components/Cluster.vue

@@ -0,0 +1,59 @@
+<script setup lang="ts">
+/**
+ * Cluster — a horizontal group that wraps, owning the gap between items.
+ *
+ * For toolbars, tag/badge rows, button groups — anywhere items flow
+ * horizontally and should wrap rather than overflow. Defaults to
+ * vertically-centered, wrapping items. Pair with <Spacer /> to push a
+ * trailing item to the end instead of a one-off `margin-left:auto`:
+ *
+ *   <Cluster>
+ *     <h2>Title</h2>
+ *     <Spacer />
+ *     <AppButton>Action</AppButton>
+ *   </Cluster>
+ *
+ * `gap` takes a spacing-scale step (0–8 → --space-*) or a raw CSS length.
+ */
+import { computed, type CSSProperties } from "vue";
+import {
+  resolveSpace,
+  ALIGN_ITEMS,
+  JUSTIFY_CONTENT,
+  type Align,
+  type Justify,
+} from "../lib/space";
+
+const props = withDefaults(
+  defineProps<{
+    gap?: string | number;
+    align?: Align;
+    justify?: Justify;
+    /** Wrap onto multiple lines when items don't fit. On by default —
+     *  that's the whole point of a cluster. */
+    wrap?: boolean;
+  }>(),
+  {
+    gap: 3,
+    align: "center",
+    justify: "start",
+    wrap: true,
+  },
+);
+
+const style = computed<CSSProperties>(() => ({
+  display: "flex",
+  flexWrap: props.wrap ? "wrap" : "nowrap",
+  gap: resolveSpace(props.gap),
+  alignItems: ALIGN_ITEMS[props.align],
+  justifyContent: JUSTIFY_CONTENT[props.justify],
+}));
+</script>
+
+<template>
+  <div class="ui-cluster" :style="style"><slot /></div>
+</template>
+
+<style scoped>
+.ui-cluster { min-width: 0; }
+</style>