srcdev-nuxt-components 9.4.6 → 9.4.8

package/app/components/01.atoms/navigation/tabs/tests/TabsCore.spec.ts

@@ -0,0 +1,274 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { mountSuspended } from "@nuxt/test-utils/runtime";
+import TabsCore from "../TabsCore.vue";
+
+class MockResizeObserver {
+  observe = vi.fn();
+  unobserve = vi.fn();
+  disconnect = vi.fn();
+}
+
+const slots = {
+  "tab-0-trigger": "Tab One",
+  "tab-0-content": "<p class='panel-0'>Content one</p>",
+  "tab-1-trigger": "Tab Two",
+  "tab-1-content": "<p class='panel-1'>Content two</p>",
+  "tab-2-trigger": "Tab Three",
+  "tab-2-content": "<p class='panel-2'>Content three</p>",
+};
+
+const fiveSlots = {
+  ...slots,
+  "tab-3-trigger": "Tab Four",
+  "tab-3-content": "<p class='panel-3'>Content four</p>",
+  "tab-4-trigger": "Tab Five",
+  "tab-4-content": "<p class='panel-4'>Content five</p>",
+};
+
+describe("TabsCore", () => {
+  beforeEach(() => {
+    vi.stubGlobal("ResizeObserver", MockResizeObserver);
+  });
+
+  // ─── Mount ───────────────────────────────────────────────────────────────
+
+  it("mounts without error", async () => {
+    const wrapper = await mountSuspended(TabsCore, { props: { itemCount: 3 }, slots });
+    expect(wrapper.vm).toBeTruthy();
+  });
+
+  it("renders one trigger and one panel per itemCount", async () => {
+    const wrapper = await mountSuspended(TabsCore, { props: { itemCount: 3 }, slots });
+    expect(wrapper.findAll(".tabs-list-item")).toHaveLength(3);
+    expect(wrapper.findAll(".tab-content")).toHaveLength(3);
+  });
+
+  // ─── Accessibility structure ─────────────────────────────────────────────
+
+  it("renders a tablist with the default aria-label", async () => {
+    const wrapper = await mountSuspended(TabsCore, { props: { itemCount: 3 }, slots });
+    const tablist = wrapper.find("[role='tablist']");
+    expect(tablist.exists()).toBe(true);
+    expect(tablist.attributes("aria-label")).toBe("Tabs");
+  });
+
+  it("uses a custom ariaLabel when provided", async () => {
+    const wrapper = await mountSuspended(TabsCore, { props: { itemCount: 3, ariaLabel: "Settings" }, slots });
+    expect(wrapper.find("[role='tablist']").attributes("aria-label")).toBe("Settings");
+  });
+
+  it("renders each trigger as a type=button with role=tab", async () => {
+    const wrapper = await mountSuspended(TabsCore, { props: { itemCount: 3 }, slots });
+    const triggers = wrapper.findAll(".tabs-list-item");
+    triggers.forEach((trigger) => {
+      expect(trigger.attributes("type")).toBe("button");
+      expect(trigger.attributes("role")).toBe("tab");
+    });
+  });
+
+  it("renders each panel as role=tabpanel labelled by its trigger", async () => {
+    const wrapper = await mountSuspended(TabsCore, { props: { itemCount: 3 }, slots });
+    const panels = wrapper.findAll(".tab-content");
+    panels.forEach((panel, index) => {
+      expect(panel.attributes("role")).toBe("tabpanel");
+      expect(panel.attributes("aria-labelledby")).toBe(`tab-${index}-trigger`);
+    });
+  });
+
+  // ─── Active tab state ────────────────────────────────────────────────────
+
+  it("marks the first tab active and its panel visible/unhidden on mount", async () => {
+    const wrapper = await mountSuspended(TabsCore, { props: { itemCount: 3 }, slots });
+    const triggers = wrapper.findAll(".tabs-list-item");
+    const panels = wrapper.findAll(".tab-content");
+
+    expect(triggers[0]!.attributes("aria-selected")).toBe("true");
+    expect(triggers[0]!.attributes("tabindex")).toBe("0");
+    expect(triggers[1]!.attributes("aria-selected")).toBe("false");
+    expect(triggers[1]!.attributes("tabindex")).toBe("-1");
+
+    expect(panels[0]!.attributes("aria-hidden")).toBe("false");
+    expect((panels[0]!.element as HTMLElement).style.display).toBe("block");
+    expect(panels[1]!.attributes("aria-hidden")).toBe("true");
+    expect((panels[1]!.element as HTMLElement).style.display).toBe("none");
+  });
+
+  it("activates a tab on click and updates aria-selected, tabindex, and panel visibility", async () => {
+    const wrapper = await mountSuspended(TabsCore, { props: { itemCount: 3 }, slots });
+    const triggers = wrapper.findAll(".tabs-list-item");
+    const panels = wrapper.findAll(".tab-content");
+
+    await triggers[1]!.trigger("click");
+
+    expect(triggers[0]!.attributes("aria-selected")).toBe("false");
+    expect(triggers[0]!.attributes("tabindex")).toBe("-1");
+    expect(triggers[1]!.attributes("aria-selected")).toBe("true");
+    expect(triggers[1]!.attributes("tabindex")).toBe("0");
+
+    expect(panels[0]!.attributes("aria-hidden")).toBe("true");
+    expect(panels[1]!.attributes("aria-hidden")).toBe("false");
+    expect((panels[1]!.element as HTMLElement).style.display).toBe("block");
+  });
+
+  // ─── Keyboard navigation ─────────────────────────────────────────────────
+
+  it("moves focus and activates the next tab on ArrowRight (axis x)", async () => {
+    const wrapper = await mountSuspended(TabsCore, { props: { itemCount: 3 }, slots });
+    const triggers = wrapper.findAll(".tabs-list-item");
+
+    await triggers[0]!.trigger("keydown", { key: "ArrowRight" });
+
+    expect(triggers[1]!.attributes("aria-selected")).toBe("true");
+    expect(triggers[1]!.attributes("tabindex")).toBe("0");
+  });
+
+  it("wraps to the first tab on ArrowRight from the last tab", async () => {
+    const wrapper = await mountSuspended(TabsCore, { props: { itemCount: 3 }, slots });
+    const triggers = wrapper.findAll(".tabs-list-item");
+
+    await triggers[2]!.trigger("click");
+    await triggers[2]!.trigger("keydown", { key: "ArrowRight" });
+
+    expect(triggers[0]!.attributes("aria-selected")).toBe("true");
+  });
+
+  it("moves focus to the previous tab on ArrowLeft (axis x)", async () => {
+    const wrapper = await mountSuspended(TabsCore, { props: { itemCount: 3 }, slots });
+    const triggers = wrapper.findAll(".tabs-list-item");
+
+    await triggers[1]!.trigger("click");
+    await triggers[1]!.trigger("keydown", { key: "ArrowLeft" });
+
+    expect(triggers[0]!.attributes("aria-selected")).toBe("true");
+  });
+
+  it("uses ArrowUp/ArrowDown instead of ArrowLeft/ArrowRight when axis is y", async () => {
+    const wrapper = await mountSuspended(TabsCore, { props: { itemCount: 3, axis: "y" }, slots });
+    const triggers = wrapper.findAll(".tabs-list-item");
+
+    await triggers[0]!.trigger("keydown", { key: "ArrowRight" });
+    expect(triggers[0]!.attributes("aria-selected")).toBe("true");
+
+    await triggers[0]!.trigger("keydown", { key: "ArrowDown" });
+    expect(triggers[1]!.attributes("aria-selected")).toBe("true");
+  });
+
+  it("jumps to the last tab on End and the first tab on Home", async () => {
+    const wrapper = await mountSuspended(TabsCore, { props: { itemCount: 3 }, slots });
+    const triggers = wrapper.findAll(".tabs-list-item");
+
+    await triggers[0]!.trigger("keydown", { key: "End" });
+    expect(triggers[2]!.attributes("aria-selected")).toBe("true");
+
+    await triggers[2]!.trigger("keydown", { key: "Home" });
+    expect(triggers[0]!.attributes("aria-selected")).toBe("true");
+  });
+
+  // ─── trackHover / trackActive / trackIndicator ──────────────────────────
+
+  it("renders all three indicator decorators by default", async () => {
+    const wrapper = await mountSuspended(TabsCore, { props: { itemCount: 3 }, slots });
+    expect(wrapper.find(".nav__hovered").exists()).toBe(true);
+    expect(wrapper.find(".nav__active").exists()).toBe(true);
+    expect(wrapper.find(".nav__active-indicator").exists()).toBe(true);
+  });
+
+  it("omits the hover decorator when trackHover is false", async () => {
+    const wrapper = await mountSuspended(TabsCore, { props: { itemCount: 3, trackHover: false }, slots });
+    expect(wrapper.find(".nav__hovered").exists()).toBe(false);
+  });
+
+  it("omits the active decorator when trackActive is false", async () => {
+    const wrapper = await mountSuspended(TabsCore, { props: { itemCount: 3, trackActive: false }, slots });
+    expect(wrapper.find(".nav__active").exists()).toBe(false);
+  });
+
+  it("omits the underline indicator when trackIndicator is false", async () => {
+    const wrapper = await mountSuspended(TabsCore, { props: { itemCount: 3, trackIndicator: false }, slots });
+    expect(wrapper.find(".nav__active-indicator").exists()).toBe(false);
+  });
+
+  // ─── Hover indicator movement ────────────────────────────────────────────
+
+  it("moves the hover indicator position on mouseenter", async () => {
+    const wrapper = await mountSuspended(TabsCore, { props: { itemCount: 3 }, slots });
+    const tabsList = wrapper.find(".tabs-list").element as HTMLElement;
+    const triggers = wrapper.findAll(".tabs-list-item");
+
+    expect(tabsList.style.getPropertyValue("--_width-hovered")).toBe("");
+
+    await triggers[1]!.trigger("mouseenter");
+
+    expect(tabsList.style.getPropertyValue("--_width-hovered")).not.toBe("");
+  });
+
+  it("resets the hover indicator to the active tab on mouseleave", async () => {
+    const wrapper = await mountSuspended(TabsCore, { props: { itemCount: 3 }, slots });
+    const tabsList = wrapper.find(".tabs-list");
+    const triggers = wrapper.findAll(".tabs-list-item");
+
+    await triggers[1]!.trigger("mouseenter");
+    await tabsList.trigger("mouseleave");
+
+    // Should not throw, and the hover indicator settles back onto the active (first) tab.
+    expect((tabsList.element as HTMLElement).style.getPropertyValue("--_x-hovered")).toBe("0px");
+  });
+
+  it("clears a pending settle timeout when hovering a second tab before the first settles", async () => {
+    const wrapper = await mountSuspended(TabsCore, { props: { itemCount: 3 }, slots });
+    const triggers = wrapper.findAll(".tabs-list-item");
+    const clearTimeoutSpy = vi.spyOn(global, "clearTimeout");
+
+    await triggers[1]!.trigger("mouseenter");
+    await triggers[2]!.trigger("mouseenter");
+
+    expect(clearTimeoutSpy).toHaveBeenCalled();
+  });
+
+  // ─── Regression: more than 3 tabs ────────────────────────────────────────
+  // The original hand-rolled version of this component had an indicator-positioning issue
+  // that only showed up with itemCount > 3 — these lock in correct behaviour at 5.
+
+  it("activates a distant tab (index 0 -> index 4) directly via click", async () => {
+    const wrapper = await mountSuspended(TabsCore, { props: { itemCount: 5 }, slots: fiveSlots });
+    const triggers = wrapper.findAll(".tabs-list-item");
+
+    await triggers[4]!.trigger("click");
+
+    expect(triggers[0]!.attributes("aria-selected")).toBe("false");
+    expect(triggers[4]!.attributes("aria-selected")).toBe("true");
+    expect(triggers[4]!.attributes("tabindex")).toBe("0");
+    expect(wrapper.findAll(".tab-content")[4]!.attributes("aria-hidden")).toBe("false");
+  });
+
+  it("does not recolour tabs spanned by a distant activation jump (regression: intermediate labels going invisible)", async () => {
+    // The old implementation force-applied a "transitioning" class to every tab spanned by a
+    // jump, forcing it to the active-indicator's text colour for the whole transition — even
+    // though the sliding indicator only visually reaches each spanned tab partway through, and
+    // for a forward jump doesn't reach the middle tabs until late in the transition. That made
+    // intermediate labels flash a colour matching neither their own background nor (yet) the
+    // indicator's, going invisible. Spanned tabs should only ever carry aria-selected/hover
+    // state of their own — never a class forcing them to look active.
+    const wrapper = await mountSuspended(TabsCore, { props: { itemCount: 5 }, slots: fiveSlots });
+    const triggers = wrapper.findAll(".tabs-list-item");
+
+    // Active tab starts at index 0, so activating index 4 spans every tab in between.
+    await triggers[4]!.trigger("click");
+
+    [1, 2, 3].forEach((index) => {
+      expect(triggers[index]!.attributes("aria-selected")).toBe("false");
+      expect(triggers[index]!.classes()).not.toContain("transitioning");
+    });
+  });
+
+  it("wraps correctly with End then ArrowRight across 5 tabs", async () => {
+    const wrapper = await mountSuspended(TabsCore, { props: { itemCount: 5 }, slots: fiveSlots });
+    const triggers = wrapper.findAll(".tabs-list-item");
+
+    await triggers[0]!.trigger("keydown", { key: "End" });
+    expect(triggers[4]!.attributes("aria-selected")).toBe("true");
+
+    await triggers[4]!.trigger("keydown", { key: "ArrowRight" });
+    expect(triggers[0]!.attributes("aria-selected")).toBe("true");
+  });
+});

package/app/components/01.atoms/pop-over/CONSUMER-STYLING.md

@@ -0,0 +1,54 @@
+# PopOver — Consumer Styling Guide
+
+## Public token API
+
+| Token | Default | Controls |
+|---|---|---|
+| `--pop-over-gap` | `1rem` | Space between the trigger and the popover panel |
+| `--pop-over-trigger-outline-width` | `0.1rem` | Trigger focus outline width |
+| `--pop-over-trigger-outline-colour-hover` | `var(--theme-ring)` | Trigger outline colour on focus-visible |
+| `--pop-over-width` | `30rem` | Popover panel width |
+| `--pop-over-border-width` | `0.1rem` | Popover panel border width |
+| `--pop-over-border-colour` | `light-dark(var(--slate-02), var(--slate-06))` | Popover panel border colour |
+| `--pop-over-border-radius` | `0.8rem` | Popover panel corner radius |
+| `--pop-over-background-colour` | `light-dark(var(--slate-00), var(--slate-07))` | Popover panel background |
+| `--pop-over-text-colour` | `light-dark(var(--slate-09), var(--slate-01))` | Popover panel text colour |
+| `--pop-over-shadow` | `light-dark(0 0.4rem 1.6rem rgba(0,0,0,.12), 0 0.4rem 1.6rem rgba(0,0,0,.5))` | Popover panel elevation shadow |
+| `--pop-over-transition-duration` | `200ms` | Open/close fade duration |
+| `--pop-over-content-padding` | `1.6rem` | Padding around the `content` slot |
+| `--pop-over-content-padding-block-start` | `3.2rem` | Extra top padding so content clears the close button |
+| `--pop-over-close-button-offset` | `0.8rem` | Distance of the close button from the panel's top/right edges |
+| `--pop-over-close-button-size` | `2.4rem` | Close button box width/height |
+| `--pop-over-close-button-border-radius` | `50%` | Close button corner radius |
+| `--pop-over-close-button-colour` | `light-dark(var(--slate-06), var(--slate-03))` | Close button icon colour |
+| `--pop-over-close-button-icon-size` | `1.4rem` | Close button icon glyph size |
+| `--pop-over-close-button-outline-width` | `0.1rem` | Close button focus/hover outline width |
+| `--pop-over-close-button-surface-hover` | `light-dark(var(--slate-01), var(--slate-06))` | Close button background on hover/focus-visible |
+| `--pop-over-close-button-outline-colour-hover` | `var(--theme-ring)` | Close button outline colour on hover/focus-visible |
+
+```css
+.my-page {
+  --pop-over-background-colour: #1a1a1a;
+  --pop-over-text-colour: white;
+  --pop-over-width: 24rem;
+}
+```
+
+Or scope to a single instance via `styleClassPassthrough`:
+
+```vue
+<PopOver style-class-passthrough="promo-pop-over">...</PopOver>
+```
+
+## Notes
+
+- Built on the native Popover API (`popover`/`popovertarget`) and CSS anchor-positioning
+  (`anchor-name`/`position-anchor`/`anchor()`) — check current browser support before relying on
+  it where broad support is a hard requirement.
+- `placement` (`"top" | "right" | "bottom" | "left"`, default `"right"`) picks which side of the
+  trigger the panel opens on; each side gets a `position-try-fallbacks` so the browser flips it
+  automatically if it would overflow the viewport.
+- Unlike `DisplayTooltip` (a fixed icon trigger for inline help text) or `ActionMenu` (menu
+  semantics with arrow-key navigation), `PopOver` is a generic disclosure: both `trigger` and
+  `content` slots are entirely consumer-supplied, and it always renders its own visible close
+  button rather than relying on click-outside/Escape alone.

package/app/components/01.atoms/pop-over/PopOver.vue

@@ -0,0 +1,201 @@
+<template>
+  <ClientOnly>
+    <div class="pop-over" :class="[elementClasses]" :style="{ '--_anchor-name': anchorName }" :data-placement="placement">
+      <button
+        ref="triggerRef"
+        :popovertarget="popoverId"
+        popovertargetaction="toggle"
+        type="button"
+        class="pop-over-trigger"
+        :aria-label="triggerAriaLabel || undefined"
+      >
+        <slot name="trigger"></slot>
+      </button>
+
+      <div :id="popoverId" ref="popoverRef" popover class="pop-over-popover" :aria-label="popoverAriaLabel || undefined" @toggle="handleToggle">
+        <button
+          ref="closeButtonRef"
+          :popovertarget="popoverId"
+          popovertargetaction="hide"
+          type="button"
+          class="pop-over-close-button"
+          :aria-label="closeButtonAriaLabel"
+        >
+          <Icon name="lucide:x" class="pop-over-close-button-icon" aria-hidden="true" />
+        </button>
+        <div class="pop-over-content">
+          <slot name="content"></slot>
+        </div>
+      </div>
+    </div>
+  </ClientOnly>
+</template>
+
+<script setup lang="ts">
+interface Props {
+  placement?: "top" | "right" | "bottom" | "left";
+  /** aria-label on the trigger button — set this when the trigger slot is icon-only. */
+  triggerAriaLabel?: string;
+  /** aria-label on the popover content region — set this when the content slot has no visible heading. */
+  popoverAriaLabel?: string;
+  /** aria-label on the close button — override for localisation. */
+  closeButtonAriaLabel?: string;
+  styleClassPassthrough?: string | string[];
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  placement: "right",
+  triggerAriaLabel: "",
+  popoverAriaLabel: "",
+  closeButtonAriaLabel: "Close",
+  styleClassPassthrough: () => [],
+});
+
+const id = useId();
+const popoverId = `pop-over-${id}`;
+const anchorName = `--pop-over-anchor-${id}`;
+
+const triggerRef = ref<HTMLButtonElement | null>(null);
+const popoverRef = ref<HTMLDivElement | null>(null);
+const closeButtonRef = ref<HTMLButtonElement | null>(null);
+
+/** Move focus into the popover on open; the Popover API restores focus to the trigger on close. */
+const handleToggle = (event: Event) => {
+  const toggleEvent = event as ToggleEvent;
+  if (toggleEvent.newState === "open") {
+    closeButtonRef.value?.focus();
+  }
+};
+
+const { elementClasses, resetElementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
+
+watch(
+  () => props.styleClassPassthrough,
+  () => {
+    resetElementClasses(props.styleClassPassthrough);
+  }
+);
+</script>
+
+<style lang="css">
+@layer components {
+  .pop-over {
+    display: inline-block;
+    position: relative;
+
+    .pop-over-trigger {
+      all: unset;
+      cursor: pointer;
+      anchor-name: var(--_anchor-name);
+      outline: var(--pop-over-trigger-outline-width, 0.1rem) solid transparent;
+
+      &:focus-visible {
+        outline-color: var(--pop-over-trigger-outline-colour-hover, var(--theme-ring));
+        outline-offset: 0.2rem;
+      }
+    }
+
+    .pop-over-popover {
+      display: none;
+      position: absolute;
+      position-anchor: var(--_anchor-name);
+      margin: 0;
+      inset: auto;
+      border: var(--pop-over-border-width, 0.1rem) solid
+        var(--pop-over-border-colour, light-dark(var(--slate-02), var(--slate-06)));
+      border-radius: var(--pop-over-border-radius, 0.8rem);
+      background-color: var(--pop-over-background-colour, light-dark(var(--slate-00), var(--slate-07)));
+      color: var(--pop-over-text-colour, light-dark(var(--slate-09), var(--slate-01)));
+      box-shadow: var(
+        --pop-over-shadow,
+        light-dark(0 0.4rem 1.6rem rgba(0, 0, 0, 0.12), 0 0.4rem 1.6rem rgba(0, 0, 0, 0.5))
+      );
+      width: var(--pop-over-width, 30rem);
+
+      opacity: 0;
+      transition:
+        opacity var(--pop-over-transition-duration, 200ms),
+        display var(--pop-over-transition-duration, 200ms),
+        overlay var(--pop-over-transition-duration, 200ms);
+      transition-behavior: allow-discrete;
+
+      &:popover-open {
+        display: block;
+        opacity: 1;
+
+        @starting-style {
+          opacity: 0;
+        }
+      }
+
+      .pop-over-close-button {
+        all: unset;
+        cursor: pointer;
+        position: absolute;
+        top: var(--pop-over-close-button-offset, 0.8rem);
+        right: var(--pop-over-close-button-offset, 0.8rem);
+        display: grid;
+        place-items: center;
+        width: var(--pop-over-close-button-size, 2.4rem);
+        height: var(--pop-over-close-button-size, 2.4rem);
+        border-radius: var(--pop-over-close-button-border-radius, 50%);
+        color: var(--pop-over-close-button-colour, light-dark(var(--slate-06), var(--slate-03)));
+        outline: var(--pop-over-close-button-outline-width, 0.1rem) solid transparent;
+
+        &:hover,
+        &:focus-visible {
+          background-color: var(--pop-over-close-button-surface-hover, light-dark(var(--slate-01), var(--slate-06)));
+          outline-color: var(--pop-over-close-button-outline-colour-hover, var(--theme-ring));
+          outline-offset: 0.1rem;
+        }
+
+        .pop-over-close-button-icon {
+          width: var(--pop-over-close-button-icon-size, 1.4rem);
+          height: var(--pop-over-close-button-icon-size, 1.4rem);
+        }
+      }
+
+      .pop-over-content {
+        padding: var(--pop-over-content-padding, 1.6rem);
+        padding-top: var(--pop-over-content-padding-block-start, 3.2rem);
+
+        /* Trim the slotted content's own default UA margins so this padding is the only
+           space above/below it — interior spacing between multiple children is untouched. */
+        > :first-child {
+          margin-block-start: 0;
+        }
+
+        > :last-child {
+          margin-block-end: 0;
+        }
+      }
+    }
+
+    &[data-placement="right"] .pop-over-popover {
+      top: anchor(top);
+      left: calc(anchor(right) + var(--pop-over-gap, 1rem));
+      position-try-fallbacks: flip-inline;
+    }
+
+    &[data-placement="left"] .pop-over-popover {
+      top: anchor(top);
+      right: calc(anchor(left) + var(--pop-over-gap, 1rem));
+      left: auto;
+      position-try-fallbacks: flip-inline;
+    }
+
+    &[data-placement="bottom"] .pop-over-popover {
+      top: calc(anchor(bottom) + var(--pop-over-gap, 1rem));
+      left: anchor(left);
+      position-try-fallbacks: flip-block;
+    }
+
+    &[data-placement="top"] .pop-over-popover {
+      bottom: calc(anchor(top) + var(--pop-over-gap, 1rem));
+      top: auto;
+      left: anchor(left);
+      position-try-fallbacks: flip-block;
+    }
+  }
+}
+</style>

package/app/components/01.atoms/pop-over/stories/PopOver.stories.ts

@@ -0,0 +1,141 @@
+import PopOver from "../PopOver.vue";
+import type { Meta, StoryObj } from "@nuxtjs/storybook";
+
+const meta: Meta<typeof PopOver> = {
+  title: "Atoms/PopOver",
+  component: PopOver,
+  argTypes: {
+    placement: {
+      control: "select",
+      options: ["top", "right", "bottom", "left"],
+      description: "Which side of the trigger the popover panel opens on.",
+      table: { category: "Basic" },
+    },
+    triggerAriaLabel: {
+      control: "text",
+      description: "aria-label on the trigger button — set this when the trigger slot is icon-only.",
+      table: { category: "Accessibility" },
+    },
+    popoverAriaLabel: {
+      control: "text",
+      description: "aria-label on the popover content region — set this when the content slot has no visible heading.",
+      table: { category: "Accessibility" },
+    },
+    closeButtonAriaLabel: {
+      control: "text",
+      description: "aria-label on the close button — override for localisation.",
+      table: { category: "Accessibility" },
+    },
+    styleClassPassthrough: { table: { disable: true } },
+  },
+  args: {
+    placement: "right",
+    closeButtonAriaLabel: "Close",
+  },
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "A generic anchor-positioned disclosure panel: fully consumer-supplied trigger and content slots, built on the native Popover API and CSS anchor-positioning. See DisplayTooltip for a fixed icon-trigger variant, or ActionMenu for one with menu semantics.",
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof PopOver>;
+
+export const Default: Story = {
+  render: (args) => ({
+    components: { PopOver },
+    setup() {
+      return { args };
+    },
+    template: `
+      <div style="padding: 8rem;">
+        <PopOver v-bind="args">
+          <template #trigger>
+            <span>Open popover</span>
+          </template>
+          <template #content>
+            <p>This is some popover content.</p>
+          </template>
+        </PopOver>
+      </div>
+    `,
+  }),
+};
+
+export const Placements: Story = {
+  render: (args) => ({
+    components: { PopOver },
+    setup() {
+      return { args };
+    },
+    template: `
+      <div style="display: flex; gap: 4rem; padding: 10rem;">
+        <PopOver v-bind="args" placement="top">
+          <template #trigger><span>Top</span></template>
+          <template #content><p>Opens above the trigger.</p></template>
+        </PopOver>
+        <PopOver v-bind="args" placement="right">
+          <template #trigger><span>Right</span></template>
+          <template #content><p>Opens to the right of the trigger.</p></template>
+        </PopOver>
+        <PopOver v-bind="args" placement="bottom">
+          <template #trigger><span>Bottom</span></template>
+          <template #content><p>Opens below the trigger.</p></template>
+        </PopOver>
+        <PopOver v-bind="args" placement="left">
+          <template #trigger><span>Left</span></template>
+          <template #content><p>Opens to the left of the trigger.</p></template>
+        </PopOver>
+      </div>
+    `,
+  }),
+};
+
+export const IconTrigger: Story = {
+  render: (args) => ({
+    components: { PopOver },
+    setup() {
+      return { args };
+    },
+    template: `
+      <div style="padding: 8rem;">
+        <PopOver v-bind="args" trigger-aria-label="Show filters" popover-aria-label="Filter options">
+          <template #trigger>
+            <Icon name="lucide:filter" aria-hidden="true" />
+          </template>
+          <template #content>
+            <p>Filter controls would go here.</p>
+          </template>
+        </PopOver>
+      </div>
+    `,
+  }),
+};
+
+export const CustomColours: Story = {
+  render: (args) => ({
+    components: { PopOver },
+    setup() {
+      return { args };
+    },
+    template: `
+      <div style="padding: 8rem;">
+        <PopOver
+          v-bind="args"
+          style="--pop-over-background-colour: #1a1a1a; --pop-over-text-colour: white; --pop-over-border-colour: transparent;"
+        >
+          <template #trigger>
+            <span>Open popover</span>
+          </template>
+          <template #content>
+            <p>Overriding the public tokens via inline custom properties.</p>
+          </template>
+        </PopOver>
+      </div>
+    `,
+  }),
+};