srcdev-nuxt-components 9.4.6 → 9.4.7

package/app/components/01.atoms/grids/masonry-grid/tests/MasonryGrid.spec.ts

@@ -0,0 +1,158 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { mountSuspended } from "@nuxt/test-utils/runtime";
+import { nextTick } from "vue";
+import MasonryGrid from "../MasonryGrid.vue";
+
+// useElementSize/useResizeObserver (from @vueuse/core) require ResizeObserver, which jsdom
+// doesn't implement. Mock it and capture the callback so tests can simulate a real resize event —
+// jsdom also never actually measures layout (offsetWidth/offsetHeight stay 0), so this is the only
+// way to feed the component a non-zero measured width.
+// Vitest 4: a mock's implementation must be a regular function (not an arrow function)
+// to remain constructible via `new`.
+let resizeCallback: ResizeObserverCallback | undefined;
+const mockResizeObserver = vi.fn(function (callback: ResizeObserverCallback) {
+  resizeCallback = callback;
+  return {
+    observe: vi.fn(),
+    unobserve: vi.fn(),
+    disconnect: vi.fn(),
+  };
+});
+
+beforeEach(() => {
+  resizeCallback = undefined;
+  vi.stubGlobal("ResizeObserver", mockResizeObserver);
+  // ⚠️ Do NOT call vi.unstubAllGlobals() in afterEach — it removes global stubs from
+  // vitest.setup.ts ($fetch, etc.)
+});
+
+function simulateResizeTo(width: number) {
+  resizeCallback?.(
+    [{ contentBoxSize: [{ inlineSize: width, blockSize: 0 }], contentRect: { width } } as unknown as ResizeObserverEntry],
+    {} as ResizeObserver
+  );
+}
+
+function stubOffsetHeight(el: Element, height: number) {
+  Object.defineProperty(el, "offsetHeight", { value: height, configurable: true });
+}
+
+describe("MasonryGrid", () => {
+  it("mounts without error", async () => {
+    const wrapper = await mountSuspended(MasonryGrid);
+    expect(wrapper.vm).toBeTruthy();
+  });
+
+  it("renders as div by default", async () => {
+    const wrapper = await mountSuspended(MasonryGrid);
+    expect(wrapper.element.tagName).toBe("DIV");
+  });
+
+  it("renders a different tag when provided", async () => {
+    const wrapper = await mountSuspended(MasonryGrid, {
+      props: { tag: "section" },
+    });
+    expect(wrapper.element.tagName).toBe("SECTION");
+  });
+
+  it("renders slot content in natural authoring order", async () => {
+    const wrapper = await mountSuspended(MasonryGrid, {
+      slots: {
+        "item-1": "<div>Item 1</div>",
+        "item-2": "<div>Item 2</div>",
+      },
+    });
+    const items = wrapper.findAll(".masonry-grid-item");
+    expect(items.map((item) => item.text())).toEqual(["Item 1", "Item 2"]);
+  });
+
+  it("renders no items when no slots are provided", async () => {
+    const wrapper = await mountSuspended(MasonryGrid);
+    expect(wrapper.findAll(".masonry-grid-item")).toHaveLength(0);
+  });
+
+  it("does not absolutely position items when only one column fits (single-column fallback)", async () => {
+    const wrapper = await mountSuspended(MasonryGrid, {
+      slots: { "item-1": "<div>Item 1</div>", "item-2": "<div>Item 2</div>" },
+    });
+    await nextTick();
+    await nextTick();
+    expect(wrapper.find(".masonry-grid-wrapper").classes()).not.toContain("multiple-cols");
+    const item = wrapper.find(".masonry-grid-item").element as HTMLElement;
+    expect(item.style.getPropertyValue("--_position")).toBe("");
+  });
+
+  it("packs items into whichever column is currently shortest", async () => {
+    const wrapper = await mountSuspended(MasonryGrid, {
+      // itemMinWidth (300, default) + gap (12, default) = 312 -> floor(700/312) = 2 columns
+      slots: {
+        "item-1": "<div>Item 1</div>",
+        "item-2": "<div>Item 2</div>",
+        "item-3": "<div>Item 3</div>",
+      },
+    });
+    const items = wrapper.findAll(".masonry-grid-item");
+    stubOffsetHeight(items[0]!.element, 100);
+    stubOffsetHeight(items[1]!.element, 50);
+    stubOffsetHeight(items[2]!.element, 80);
+
+    simulateResizeTo(700);
+    await nextTick();
+    await nextTick(); // updateGrid is itself wrapped in an extra nextTick()
+
+    // col heights start [0, 0]. item-1 (h=100) -> shortest is col 0 -> col becomes 112.
+    // item-2 (h=50) -> shortest is now col 1 (0 < 112) -> col becomes 62.
+    // item-3 (h=80) -> shortest is still col 1 (62 < 112) -> placed below item-2.
+    // itemWidth (stretch) = floor((700 - 1*12) / 2) = 344; column steps are itemWidth+gap = 356px.
+    const el1 = items[0]!.element as HTMLElement;
+    const el2 = items[1]!.element as HTMLElement;
+    const el3 = items[2]!.element as HTMLElement;
+    expect(el1.style.getPropertyValue("--_position-top")).toBe("0px");
+    expect(el1.style.getPropertyValue("--_position-left")).toBe("0px");
+    expect(el2.style.getPropertyValue("--_position-top")).toBe("0px");
+    expect(el2.style.getPropertyValue("--_position-left")).toBe("356px");
+    expect(el3.style.getPropertyValue("--_position-top")).toBe("62px");
+    expect(el3.style.getPropertyValue("--_position-left")).toBe("356px");
+  });
+
+  it("uses a fixed item width when fixedWidth is set, ignoring stretch sizing", async () => {
+    const wrapper = await mountSuspended(MasonryGrid, {
+      props: { fixedWidth: true, itemMinWidth: 200 },
+      slots: { "item-1": "<div>Item 1</div>", "item-2": "<div>Item 2</div>" },
+    });
+    simulateResizeTo(700); // (200 + 12) -> floor(700/212) = 3 columns
+    await nextTick();
+    await nextTick();
+    const item = wrapper.find(".masonry-grid-item").element as HTMLElement;
+    expect(item.style.getPropertyValue("--_element-width")).toBe("200px");
+  });
+
+  it("spaces fixed-width columns by exactly itemWidth + gap, and centers the block via justify", async () => {
+    const wrapper = await mountSuspended(MasonryGrid, {
+      props: { fixedWidth: true, itemMinWidth: 200, gap: 20, justify: "center" },
+      slots: {
+        "item-1": "<div>Item 1</div>",
+        "item-2": "<div>Item 2</div>",
+        "item-3": "<div>Item 3</div>",
+      },
+    });
+    simulateResizeTo(700); // (200 + 20) -> floor(700/220) = 3 columns
+    await nextTick();
+    await nextTick();
+
+    // 3 columns * 200px + 2 gaps * 20px = 640px total content width, centered in 700px
+    // available -> 30px leftover on each side.
+    const items = wrapper.findAll(".masonry-grid-item");
+    const [el1, el2, el3] = items.map((item) => item.element as HTMLElement);
+    expect(el1!.style.getPropertyValue("--_position-left")).toBe("30px");
+    expect(el2!.style.getPropertyValue("--_position-left")).toBe("250px");
+    expect(el3!.style.getPropertyValue("--_position-left")).toBe("470px");
+  });
+
+  it("applies styleClassPassthrough", async () => {
+    const wrapper = await mountSuspended(MasonryGrid, {
+      props: { styleClassPassthrough: "custom-class" },
+    });
+    expect(wrapper.classes()).toContain("custom-class");
+  });
+});

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>
+    `,
+  }),
+};