@dumiflex/wp-kit 0.3.0 → 0.5.0

package/src/Toolbar.vue

@@ -1,110 +1,110 @@
-<script setup lang="ts">
-/**
- * Toolbar: a row of controls that is one Tab stop. Inside it the arrow keys
- * move between the controls, Home/End jump to the ends, and the toolbar
- * remembers where you were (APG toolbar). `attached` joins its buttons into
- * one button group. Works on the canvas and in the manager.
- *
- *   <Toolbar label="Text">
- *     <Button variant="ghost" icon="pi-bold" aria-label="Bold" />
- *     <Separator orientation="vertical" />
- *     <Button variant="ghost" icon="pi-copy" aria-label="Copy" />
- *   </Toolbar>
- *
- * Put buttons, toggles and selects in it. A text box inside a toolbar keeps
- * its own left/right keys.
- */
-import { onMounted, onUpdated, ref } from "vue";
-
-const props = withDefaults(defineProps<{
-  /** The toolbar's name for screen readers. */
-  label: string;
-  orientation?: "horizontal" | "vertical" | undefined;
-  /** Join the buttons into one group with shared borders. */
-  attached?: boolean | undefined;
-  /** Gap between controls. */
-  size?: "sm" | "md" | undefined;
-}>(), { orientation: "horizontal", size: "md" });
-
-const rootEl = ref<HTMLElement | null>(null);
-const last = ref(0);
-
-const ITEMS = "button:not([disabled]), [role=button]:not([aria-disabled=true]), a[href], input:not([disabled]), select:not([disabled]), [role=switch], [role=checkbox], [role=radio]";
-
-function items(): HTMLElement[] {
-  return rootEl.value ? [...rootEl.value.querySelectorAll<HTMLElement>(ITEMS)] : [];
-}
-
-/** Roving tabindex: only the remembered control is in the Tab order. */
-function sync(): void {
-  const list = items();
-  if (!list.length) return;
-  const at = Math.min(last.value, list.length - 1);
-  list.forEach((el, i) => el.setAttribute("tabindex", i === at ? "0" : "-1"));
-}
-
-function isTextField(el: Element | null): boolean {
-  return !!el && el.tagName === "INPUT" && !["checkbox", "radio", "button"].includes((el as HTMLInputElement).type);
-}
-
-function onKeydown(ev: KeyboardEvent): void {
-  const list = items();
-  const at = list.indexOf(document.activeElement as HTMLElement);
-  if (at < 0) return;
-  const fwd = props.orientation === "horizontal" ? "ArrowRight" : "ArrowDown";
-  const back = props.orientation === "horizontal" ? "ArrowLeft" : "ArrowUp";
-  if (isTextField(document.activeElement) && (ev.key === "ArrowLeft" || ev.key === "ArrowRight" || ev.key === "Home" || ev.key === "End")) return;
-  let next: number;
-  if (ev.key === fwd) next = (at + 1) % list.length;
-  else if (ev.key === back) next = (at - 1 + list.length) % list.length;
-  else if (ev.key === "Home") next = 0;
-  else if (ev.key === "End") next = list.length - 1;
-  else return;
-  ev.preventDefault();
-  last.value = next;
-  sync();
-  list[next].focus();
-}
-
-function onFocusin(ev: FocusEvent): void {
-  const i = items().indexOf(ev.target as HTMLElement);
-  if (i >= 0 && i !== last.value) { last.value = i; sync(); }
-}
-
-onMounted(sync);
-onUpdated(sync);
-</script>
-
-<!-- role="toolbar" moves focus between its own controls. -->
-<!-- eslint-disable vuejs-accessibility/no-static-element-interactions -->
-<template>
-  <div
-    ref="rootEl"
-    class="wp-tools"
-    role="toolbar"
-    :aria-label="label"
-    :aria-orientation="orientation"
-    :data-orientation="orientation"
-    :data-attached="attached || undefined"
-    :data-size="size"
-    @keydown="onKeydown"
-    @focusin="onFocusin"
-  >
-    <slot />
-  </div>
-</template>
-
-<style scoped>
-.wp-tools { display: inline-flex; align-items: center; gap: var(--wp-space-2); flex-wrap: wrap; min-width: 0; }
-.wp-tools[data-size="md"] { gap: var(--wp-space-3); }
-.wp-tools[data-orientation="vertical"] { flex-direction: column; align-items: stretch; flex-wrap: nowrap; }
-.wp-tools[data-attached] { gap: 0; flex-wrap: nowrap; }
-.wp-tools[data-attached] > :deep(*) { border-radius: 0; }
-.wp-tools[data-attached] > :deep(*:not(:first-child)) { margin-left: -1px; }
-.wp-tools[data-attached] > :deep(*:first-child) { border-top-left-radius: var(--wp-radius); border-bottom-left-radius: var(--wp-radius); }
-.wp-tools[data-attached] > :deep(*:last-child) { border-top-right-radius: var(--wp-radius); border-bottom-right-radius: var(--wp-radius); }
-.wp-tools[data-attached] > :deep(*:focus-visible) { position: relative; z-index: 1; }
-.wp-tools[data-attached][data-orientation="vertical"] > :deep(*:not(:first-child)) { margin-left: 0; margin-top: -1px; }
-.wp-tools[data-attached][data-orientation="vertical"] > :deep(*:first-child) { border-radius: var(--wp-radius) var(--wp-radius) 0 0; }
-.wp-tools[data-attached][data-orientation="vertical"] > :deep(*:last-child) { border-radius: 0 0 var(--wp-radius) var(--wp-radius); }
-</style>
+<script setup lang="ts">
+/**
+ * Toolbar: a row of controls that is one Tab stop. Inside it the arrow keys
+ * move between the controls, Home/End jump to the ends, and the toolbar
+ * remembers where you were (APG toolbar). `attached` joins its buttons into
+ * one button group. Works on the canvas and in the manager.
+ *
+ *   <Toolbar label="Text">
+ *     <Button variant="ghost" icon="pi-bold" aria-label="Bold" />
+ *     <Separator orientation="vertical" />
+ *     <Button variant="ghost" icon="pi-copy" aria-label="Copy" />
+ *   </Toolbar>
+ *
+ * Put buttons, toggles and selects in it. A text box inside a toolbar keeps
+ * its own left/right keys.
+ */
+import { onMounted, onUpdated, ref } from "vue";
+
+const props = withDefaults(defineProps<{
+  /** The toolbar's name for screen readers. */
+  label: string;
+  orientation?: "horizontal" | "vertical" | undefined;
+  /** Join the buttons into one group with shared borders. */
+  attached?: boolean | undefined;
+  /** Gap between controls. */
+  size?: "sm" | "md" | undefined;
+}>(), { orientation: "horizontal", size: "md" });
+
+const rootEl = ref<HTMLElement | null>(null);
+const last = ref(0);
+
+const ITEMS = "button:not([disabled]), [role=button]:not([aria-disabled=true]), a[href], input:not([disabled]), select:not([disabled]), [role=switch], [role=checkbox], [role=radio]";
+
+function items(): HTMLElement[] {
+  return rootEl.value ? [...rootEl.value.querySelectorAll<HTMLElement>(ITEMS)] : [];
+}
+
+/** Roving tabindex: only the remembered control is in the Tab order. */
+function sync(): void {
+  const list = items();
+  if (!list.length) return;
+  const at = Math.min(last.value, list.length - 1);
+  list.forEach((el, i) => el.setAttribute("tabindex", i === at ? "0" : "-1"));
+}
+
+function isTextField(el: Element | null): boolean {
+  return !!el && el.tagName === "INPUT" && !["checkbox", "radio", "button"].includes((el as HTMLInputElement).type);
+}
+
+function onKeydown(ev: KeyboardEvent): void {
+  const list = items();
+  const at = list.indexOf(document.activeElement as HTMLElement);
+  if (at < 0) return;
+  const fwd = props.orientation === "horizontal" ? "ArrowRight" : "ArrowDown";
+  const back = props.orientation === "horizontal" ? "ArrowLeft" : "ArrowUp";
+  if (isTextField(document.activeElement) && (ev.key === "ArrowLeft" || ev.key === "ArrowRight" || ev.key === "Home" || ev.key === "End")) return;
+  let next: number;
+  if (ev.key === fwd) next = (at + 1) % list.length;
+  else if (ev.key === back) next = (at - 1 + list.length) % list.length;
+  else if (ev.key === "Home") next = 0;
+  else if (ev.key === "End") next = list.length - 1;
+  else return;
+  ev.preventDefault();
+  last.value = next;
+  sync();
+  list[next].focus();
+}
+
+function onFocusin(ev: FocusEvent): void {
+  const i = items().indexOf(ev.target as HTMLElement);
+  if (i >= 0 && i !== last.value) { last.value = i; sync(); }
+}
+
+onMounted(sync);
+onUpdated(sync);
+</script>
+
+<!-- role="toolbar" moves focus between its own controls. -->
+<!-- eslint-disable vuejs-accessibility/no-static-element-interactions -->
+<template>
+  <div
+    ref="rootEl"
+    class="wp-tools"
+    role="toolbar"
+    :aria-label="label"
+    :aria-orientation="orientation"
+    :data-orientation="orientation"
+    :data-attached="attached || undefined"
+    :data-size="size"
+    @keydown="onKeydown"
+    @focusin="onFocusin"
+  >
+    <slot />
+  </div>
+</template>
+
+<style scoped>
+.wp-tools { display: inline-flex; align-items: center; gap: var(--wp-space-2); flex-wrap: wrap; min-width: 0; }
+.wp-tools[data-size="md"] { gap: var(--wp-space-3); }
+.wp-tools[data-orientation="vertical"] { flex-direction: column; align-items: stretch; flex-wrap: nowrap; }
+.wp-tools[data-attached] { gap: 0; flex-wrap: nowrap; }
+.wp-tools[data-attached] > :deep(*) { border-radius: 0; }
+.wp-tools[data-attached] > :deep(*:not(:first-child)) { margin-left: -1px; }
+.wp-tools[data-attached] > :deep(*:first-child) { border-top-left-radius: var(--wp-radius); border-bottom-left-radius: var(--wp-radius); }
+.wp-tools[data-attached] > :deep(*:last-child) { border-top-right-radius: var(--wp-radius); border-bottom-right-radius: var(--wp-radius); }
+.wp-tools[data-attached] > :deep(*:focus-visible) { position: relative; z-index: 1; }
+.wp-tools[data-attached][data-orientation="vertical"] > :deep(*:not(:first-child)) { margin-left: 0; margin-top: -1px; }
+.wp-tools[data-attached][data-orientation="vertical"] > :deep(*:first-child) { border-radius: var(--wp-radius) var(--wp-radius) 0 0; }
+.wp-tools[data-attached][data-orientation="vertical"] > :deep(*:last-child) { border-radius: 0 0 var(--wp-radius) var(--wp-radius); }
+</style>

package/src/VirtualList.vue

@@ -1,87 +1,87 @@
-<script setup lang="ts" generic="T">
-/**
- * Virtual list: a long list (thousands of options, every library item)
- * where only the rows in view are built, so it scrolls smoothly. Rows have
- * one fixed height. Works on the canvas and in the manager.
- *
- *   <VirtualList :items="options" :item-height="32" height="320px" :item-key="(o) => o.id" label="Options">
- *     <template #item="{ item, index }">…</template>
- *   </VirtualList>
- *
- * The rows keep their place in the list for screen readers
- * (`aria-setsize` / `aria-posinset`). `scrollToIndex(i)` brings a row into
- * view, e.g. the one a keyboard user moved to.
- */
-import { computed, onBeforeUnmount, onMounted, ref } from "vue";
-
-const props = withDefaults(defineProps<{
-  items: T[];
-  itemKey: (item: T, index: number) => string | number;
-  /** Every row's height in px. */
-  itemHeight: number;
-  /** CSS height of the scrolling box. */
-  height?: string | undefined;
-  /** Rows built above and below the view. */
-  overscan?: number | undefined;
-  label?: string | undefined;
-}>(), { height: "320px", overscan: 6, label: undefined });
-
-const boxEl = ref<HTMLElement | null>(null);
-const top = ref(0);
-const viewH = ref(320);
-
-const first = computed(() => Math.max(0, Math.floor(top.value / props.itemHeight) - props.overscan));
-const last = computed(() => Math.min(props.items.length, Math.ceil((top.value + viewH.value) / props.itemHeight) + props.overscan));
-const shown = computed(() => props.items.slice(first.value, last.value).map((item, k) => ({ item, index: first.value + k })));
-
-function onScroll(): void {
-  top.value = boxEl.value?.scrollTop ?? 0;
-}
-
-let ro: ResizeObserver | null = null;
-onMounted(() => {
-  viewH.value = boxEl.value?.clientHeight || viewH.value;
-  if (typeof ResizeObserver !== "undefined" && boxEl.value) {
-    ro = new ResizeObserver(() => { viewH.value = boxEl.value?.clientHeight || viewH.value; });
-    ro.observe(boxEl.value);
-  }
-});
-onBeforeUnmount(() => ro?.disconnect());
-
-/** Scroll so row `i` is in view (nearest edge). */
-function scrollToIndex(i: number): void {
-  const el = boxEl.value;
-  if (!el) return;
-  const y = i * props.itemHeight;
-  if (y < el.scrollTop) el.scrollTop = y;
-  else if (y + props.itemHeight > el.scrollTop + el.clientHeight) el.scrollTop = y + props.itemHeight - el.clientHeight;
-  onScroll();
-}
-
-defineExpose({ scrollToIndex });
-</script>
-
-<template>
-  <div ref="boxEl" class="wp-vlist" :style="{ height }" tabindex="0" role="list" :aria-label="label" @scroll.passive="onScroll">
-    <div class="wp-vlist__space" :style="{ height: `${items.length * itemHeight}px` }">
-      <div
-        v-for="row in shown"
-        :key="itemKey(row.item, row.index)"
-        class="wp-vlist__row"
-        role="listitem"
-        :aria-setsize="items.length"
-        :aria-posinset="row.index + 1"
-        :style="{ top: `${row.index * itemHeight}px`, height: `${itemHeight}px` }"
-      >
-        <slot name="item" :item="row.item" :index="row.index" />
-      </div>
-    </div>
-  </div>
-</template>
-
-<style scoped>
-.wp-vlist { position: relative; overflow-y: auto; overscroll-behavior: contain; min-width: 0; outline: none; border-radius: var(--wp-radius); }
-.wp-vlist:focus-visible { box-shadow: inset 0 0 0 2px var(--wp-border-focus); }
-.wp-vlist__space { position: relative; width: 100%; }
-.wp-vlist__row { position: absolute; left: 0; right: 0; display: flex; align-items: center; min-width: 0; box-sizing: border-box; }
-</style>
+<script setup lang="ts" generic="T">
+/**
+ * Virtual list: a long list (thousands of options, every library item)
+ * where only the rows in view are built, so it scrolls smoothly. Rows have
+ * one fixed height. Works on the canvas and in the manager.
+ *
+ *   <VirtualList :items="options" :item-height="32" height="320px" :item-key="(o) => o.id" label="Options">
+ *     <template #item="{ item, index }">…</template>
+ *   </VirtualList>
+ *
+ * The rows keep their place in the list for screen readers
+ * (`aria-setsize` / `aria-posinset`). `scrollToIndex(i)` brings a row into
+ * view, e.g. the one a keyboard user moved to.
+ */
+import { computed, onBeforeUnmount, onMounted, ref } from "vue";
+
+const props = withDefaults(defineProps<{
+  items: T[];
+  itemKey: (item: T, index: number) => string | number;
+  /** Every row's height in px. */
+  itemHeight: number;
+  /** CSS height of the scrolling box. */
+  height?: string | undefined;
+  /** Rows built above and below the view. */
+  overscan?: number | undefined;
+  label?: string | undefined;
+}>(), { height: "320px", overscan: 6, label: undefined });
+
+const boxEl = ref<HTMLElement | null>(null);
+const top = ref(0);
+const viewH = ref(320);
+
+const first = computed(() => Math.max(0, Math.floor(top.value / props.itemHeight) - props.overscan));
+const last = computed(() => Math.min(props.items.length, Math.ceil((top.value + viewH.value) / props.itemHeight) + props.overscan));
+const shown = computed(() => props.items.slice(first.value, last.value).map((item, k) => ({ item, index: first.value + k })));
+
+function onScroll(): void {
+  top.value = boxEl.value?.scrollTop ?? 0;
+}
+
+let ro: ResizeObserver | null = null;
+onMounted(() => {
+  viewH.value = boxEl.value?.clientHeight || viewH.value;
+  if (typeof ResizeObserver !== "undefined" && boxEl.value) {
+    ro = new ResizeObserver(() => { viewH.value = boxEl.value?.clientHeight || viewH.value; });
+    ro.observe(boxEl.value);
+  }
+});
+onBeforeUnmount(() => ro?.disconnect());
+
+/** Scroll so row `i` is in view (nearest edge). */
+function scrollToIndex(i: number): void {
+  const el = boxEl.value;
+  if (!el) return;
+  const y = i * props.itemHeight;
+  if (y < el.scrollTop) el.scrollTop = y;
+  else if (y + props.itemHeight > el.scrollTop + el.clientHeight) el.scrollTop = y + props.itemHeight - el.clientHeight;
+  onScroll();
+}
+
+defineExpose({ scrollToIndex });
+</script>
+
+<template>
+  <div ref="boxEl" class="wp-vlist" :style="{ height }" tabindex="0" role="list" :aria-label="label" @scroll.passive="onScroll">
+    <div class="wp-vlist__space" :style="{ height: `${items.length * itemHeight}px` }">
+      <div
+        v-for="row in shown"
+        :key="itemKey(row.item, row.index)"
+        class="wp-vlist__row"
+        role="listitem"
+        :aria-setsize="items.length"
+        :aria-posinset="row.index + 1"
+        :style="{ top: `${row.index * itemHeight}px`, height: `${itemHeight}px` }"
+      >
+        <slot name="item" :item="row.item" :index="row.index" />
+      </div>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+.wp-vlist { position: relative; overflow-y: auto; overscroll-behavior: contain; min-width: 0; outline: none; border-radius: var(--wp-radius); }
+.wp-vlist:focus-visible { box-shadow: inset 0 0 0 2px var(--wp-border-focus); }
+.wp-vlist__space { position: relative; width: 100%; }
+.wp-vlist__row { position: absolute; left: 0; right: 0; display: flex; align-items: center; min-width: 0; box-sizing: border-box; }
+</style>

package/src/VisuallyHidden.vue

@@ -1,29 +1,29 @@
-<script setup lang="ts">
-/**
- * Visually hidden: text for screen readers only (a table header with no
- * visible name, "(opens in a new tab)", a live status line). With
- * `focusable` it shows itself while it has focus, for a "Skip to the list"
- * link. Works on the canvas and in the manager.
- *
- *   <VisuallyHidden>Select</VisuallyHidden>
- *   <VisuallyHidden as="div" aria-live="polite">{{ status }}</VisuallyHidden>
- */
-withDefaults(defineProps<{
-  /** The element to draw. */
-  as?: string | undefined;
-  /** Show while focused (skip links). */
-  focusable?: boolean | undefined;
-}>(), { as: "span" });
-</script>
-
-<template>
-  <component :is="as" class="wp-visually-hidden" :data-focusable="focusable || undefined"><slot /></component>
-</template>
-
-<style scoped>
-.wp-visually-hidden:not([data-focusable]),
-.wp-visually-hidden[data-focusable]:not(:focus):not(:focus-within) {
-  position: absolute !important; width: 1px; height: 1px; margin: -1px; padding: 0; overflow: hidden;
-  clip: rect(0 0 0 0); clip-path: inset(50%); white-space: nowrap; border: 0;
-}
-</style>
+<script setup lang="ts">
+/**
+ * Visually hidden: text for screen readers only (a table header with no
+ * visible name, "(opens in a new tab)", a live status line). With
+ * `focusable` it shows itself while it has focus, for a "Skip to the list"
+ * link. Works on the canvas and in the manager.
+ *
+ *   <VisuallyHidden>Select</VisuallyHidden>
+ *   <VisuallyHidden as="div" aria-live="polite">{{ status }}</VisuallyHidden>
+ */
+withDefaults(defineProps<{
+  /** The element to draw. */
+  as?: string | undefined;
+  /** Show while focused (skip links). */
+  focusable?: boolean | undefined;
+}>(), { as: "span" });
+</script>
+
+<template>
+  <component :is="as" class="wp-visually-hidden" :data-focusable="focusable || undefined"><slot /></component>
+</template>
+
+<style scoped>
+.wp-visually-hidden:not([data-focusable]),
+.wp-visually-hidden[data-focusable]:not(:focus):not(:focus-within) {
+  position: absolute !important; width: 1px; height: 1px; margin: -1px; padding: 0; overflow: hidden;
+  clip: rect(0 0 0 0); clip-path: inset(50%); white-space: nowrap; border: 0;
+}
+</style>

package/src/WpButton.vue

@@ -1,75 +1,75 @@
-<script setup lang="ts">
-/**
- * The canvas twin of the manager Button (manager/components/ui/Button.vue).
- * Same variants, sizes and states, same stylesheet (`button.css`), but the
- * icon is a PrimeIcons class, as everywhere on the canvas, and the default
- * size is the canvas `sm`.
- *
- *   <WpButton variant="primary" icon="pi-plus">Add module</WpButton>
- *   <WpButton variant="ghost" icon="pi-download" aria-label="Download snapshot" />
- *   <WpButton variant="add" icon="pi-plus" block>Add rule</WpButton>
- *
- * With no slot content it is an icon button (`.wp-btn--icon`); its
- * `aria-label` is also its tooltip (`hint` sets another, `kbd` adds a key
- * chip). `pressed` turns it into a toggle (a "favourites only" star, a
- * filter panel trigger). Loading swaps the icon for the sparkle, sets
- * aria-busy and ignores clicks.
- *
- * The stylesheet is pulled in scoped, so the canvas never carries the
- * `.wp-btn` classes globally. Row icon buttons are WpIconButton.
- */
-import { computed, useSlots } from "vue";
-import LoadingMark from "./LoadingMark.vue";
-import { vTooltip } from "./tooltip";
-
-const props = withDefaults(defineProps<{
-  variant?: "primary" | "secondary" | "ghost" | "danger" | "link" | "outline" | "add" | undefined;
-  size?: "sm" | "md" | "lg" | undefined;
-  /** PrimeIcons class (e.g. `pi-plus`), drawn before the label. */
-  icon?: string | undefined;
-  loading?: boolean | undefined;
-  disabled?: boolean | undefined;
-  /** Stretch to the container's full width. */
-  block?: boolean | undefined;
-  /** Makes it a toggle (`aria-pressed`): on, it wears the accent tint. */
-  pressed?: boolean | undefined;
-  type?: "button" | "submit" | "reset" | undefined;
-  ariaLabel?: string | undefined;
-  /** Tooltip text; an icon button shows its aria-label when this is unset.
-   *  Use this, not `v-tooltip` on the component, which would fight the
-   *  button's own. */
-  hint?: string | undefined;
-  /** A shortcut shown in the tooltip's key chip, e.g. "P". */
-  kbd?: string | undefined;
-}>(), { variant: "secondary", size: "sm", icon: undefined, type: "button", ariaLabel: undefined, hint: undefined, kbd: undefined, pressed: undefined });
-
-const emit = defineEmits<{ click: [evt: MouseEvent] }>();
-
-const slots = useSlots();
-const iconOnly = computed(() => !slots.default);
-
-function onClick(e: MouseEvent): void {
-  if (props.disabled || props.loading) return;
-  emit("click", e);
-}
-</script>
-
-<template>
-  <button
-    v-tooltip="{ text: hint ?? (iconOnly ? ariaLabel : undefined), kbd }"
-    :type="type"
-    class="wp-btn"
-    :class="[`wp-btn--${variant}`, `wp-btn--${size}`, { 'wp-btn--icon': iconOnly, 'wp-btn--block': block }]"
-    :disabled="disabled || loading"
-    :aria-label="ariaLabel"
-    :aria-busy="loading || undefined"
-    :aria-pressed="pressed === undefined ? undefined : pressed"
-    @click="onClick"
-  >
-    <LoadingMark v-if="loading" variant="sparkle" mono :size="size === 'lg' ? 16 : size === 'md' ? 14 : 12" decorative />
-    <i v-else-if="icon" class="pi" :class="icon" aria-hidden="true" />
-    <slot />
-  </button>
-</template>
-
-<style scoped src="./button.css"></style>
+<script setup lang="ts">
+/**
+ * The canvas twin of the manager Button (manager/components/ui/Button.vue).
+ * Same variants, sizes and states, same stylesheet (`button.css`), but the
+ * icon is a PrimeIcons class, as everywhere on the canvas, and the default
+ * size is the canvas `sm`.
+ *
+ *   <WpButton variant="primary" icon="pi-plus">Add module</WpButton>
+ *   <WpButton variant="ghost" icon="pi-download" aria-label="Download snapshot" />
+ *   <WpButton variant="add" icon="pi-plus" block>Add rule</WpButton>
+ *
+ * With no slot content it is an icon button (`.wp-btn--icon`); its
+ * `aria-label` is also its tooltip (`hint` sets another, `kbd` adds a key
+ * chip). `pressed` turns it into a toggle (a "favourites only" star, a
+ * filter panel trigger). Loading swaps the icon for the sparkle, sets
+ * aria-busy and ignores clicks.
+ *
+ * The stylesheet is pulled in scoped, so the canvas never carries the
+ * `.wp-btn` classes globally. Row icon buttons are WpIconButton.
+ */
+import { computed, useSlots } from "vue";
+import LoadingMark from "./LoadingMark.vue";
+import { vTooltip } from "./tooltip";
+
+const props = withDefaults(defineProps<{
+  variant?: "primary" | "secondary" | "ghost" | "danger" | "link" | "outline" | "add" | undefined;
+  size?: "sm" | "md" | "lg" | undefined;
+  /** PrimeIcons class (e.g. `pi-plus`), drawn before the label. */
+  icon?: string | undefined;
+  loading?: boolean | undefined;
+  disabled?: boolean | undefined;
+  /** Stretch to the container's full width. */
+  block?: boolean | undefined;
+  /** Makes it a toggle (`aria-pressed`): on, it wears the accent tint. */
+  pressed?: boolean | undefined;
+  type?: "button" | "submit" | "reset" | undefined;
+  ariaLabel?: string | undefined;
+  /** Tooltip text; an icon button shows its aria-label when this is unset.
+   *  Use this, not `v-tooltip` on the component, which would fight the
+   *  button's own. */
+  hint?: string | undefined;
+  /** A shortcut shown in the tooltip's key chip, e.g. "P". */
+  kbd?: string | undefined;
+}>(), { variant: "secondary", size: "sm", icon: undefined, type: "button", ariaLabel: undefined, hint: undefined, kbd: undefined, pressed: undefined });
+
+const emit = defineEmits<{ click: [evt: MouseEvent] }>();
+
+const slots = useSlots();
+const iconOnly = computed(() => !slots.default);
+
+function onClick(e: MouseEvent): void {
+  if (props.disabled || props.loading) return;
+  emit("click", e);
+}
+</script>
+
+<template>
+  <button
+    v-tooltip="{ text: hint ?? (iconOnly ? ariaLabel : undefined), kbd }"
+    :type="type"
+    class="wp-btn"
+    :class="[`wp-btn--${variant}`, `wp-btn--${size}`, { 'wp-btn--icon': iconOnly, 'wp-btn--block': block }]"
+    :disabled="disabled || loading"
+    :aria-label="ariaLabel"
+    :aria-busy="loading || undefined"
+    :aria-pressed="pressed === undefined ? undefined : pressed"
+    @click="onClick"
+  >
+    <LoadingMark v-if="loading" variant="sparkle" mono :size="size === 'lg' ? 16 : size === 'md' ? 14 : 12" decorative />
+    <i v-else-if="icon" class="pi" :class="icon" aria-hidden="true" />
+    <slot />
+  </button>
+</template>
+
+<style scoped src="./button.css"></style>