srcdev-nuxt-components 9.4.4 → 9.4.5

package/app/components/01.atoms/clipped-panel/stories/ClippedPanel.stories.ts

@@ -0,0 +1,105 @@
+import ClippedPanel from "../ClippedPanel.vue";
+import type { Meta, StoryObj } from "@nuxtjs/storybook";
+
+const meta: Meta<typeof ClippedPanel> = {
+  title: "Atoms/ClippedPanel",
+  component: ClippedPanel,
+  argTypes: {
+    tag: {
+      control: { type: "select" },
+      options: ["div", "p", "span", "section", "article", "aside", "header", "footer", "main", "nav", "ul", "ol"],
+      description: "Root element tag",
+      table: { category: "Basic" },
+    },
+    variant: {
+      control: { type: "select" },
+      options: ["square", "rectangle", "circle-cutout"],
+      description: "Which fixed-size notched shape to clip the panel to",
+      table: { category: "Basic" },
+    },
+    styleClassPassthrough: {
+      table: { disable: true },
+    },
+  },
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "A panel clipped to a fixed-size notched shape via `clip-path: path(...)`. Each variant is a specific pixel-size shape (see CONSUMER-STYLING.md) — colour and outline are the only overridable surface.",
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof ClippedPanel>;
+
+export const Square: Story = {
+  args: {
+    tag: "div",
+    variant: "square",
+  },
+  render: (args) => ({
+    components: { ClippedPanel },
+    setup() {
+      return { args };
+    },
+    template: `<ClippedPanel v-bind="args">Square</ClippedPanel>`,
+  }),
+};
+
+export const Rectangle: Story = {
+  args: {
+    tag: "div",
+    variant: "rectangle",
+  },
+  render: (args) => ({
+    components: { ClippedPanel },
+    setup() {
+      return { args };
+    },
+    template: `<ClippedPanel v-bind="args">Rectangle</ClippedPanel>`,
+  }),
+};
+
+export const CircleCutout: Story = {
+  args: {
+    tag: "div",
+    variant: "circle-cutout",
+  },
+  render: (args) => ({
+    components: { ClippedPanel },
+    setup() {
+      return { args };
+    },
+    template: `<ClippedPanel v-bind="args">Circle cutout</ClippedPanel>`,
+  }),
+};
+
+export const CustomColours: Story = {
+  args: {
+    tag: "div",
+    variant: "square",
+  },
+  render: (args) => ({
+    components: { ClippedPanel },
+    setup() {
+      return { args };
+    },
+    template: `
+      <ClippedPanel
+        v-bind="args"
+        style="--clipped-panel-background-colour: #fef3e7; --clipped-panel-outline-colour: #b5651d; --clipped-panel-outline-width: 2px;"
+      >
+        Custom colours
+      </ClippedPanel>
+    `,
+  }),
+  parameters: {
+    docs: {
+      description: {
+        story: "Overriding the public tokens via inline `--clipped-panel-*` custom properties.",
+      },
+    },
+  },
+};

package/app/components/01.atoms/clipped-panel/tests/ClippedPanel.spec.ts

@@ -0,0 +1,67 @@
+import { describe, it, expect } from "vitest";
+import { mountSuspended } from "@nuxt/test-utils/runtime";
+import ClippedPanel from "../ClippedPanel.vue";
+
+describe("ClippedPanel", () => {
+  it("mounts without error", async () => {
+    const wrapper = await mountSuspended(ClippedPanel);
+    expect(wrapper.vm).toBeTruthy();
+  });
+
+  it("renders correct HTML structure (default props)", async () => {
+    const wrapper = await mountSuspended(ClippedPanel);
+    expect(wrapper.html()).toMatchSnapshot();
+  });
+
+  it("renders a <div> by default", async () => {
+    const wrapper = await mountSuspended(ClippedPanel);
+    expect(wrapper.element.tagName).toBe("DIV");
+  });
+
+  it("renders the given tag", async () => {
+    const wrapper = await mountSuspended(ClippedPanel, { props: { tag: "section" } });
+    expect(wrapper.element.tagName).toBe("SECTION");
+  });
+
+  it("defaults to the square variant class", async () => {
+    const wrapper = await mountSuspended(ClippedPanel);
+    expect(wrapper.classes()).toContain("clipped-panel");
+    expect(wrapper.classes()).toContain("square");
+  });
+
+  it("applies the rectangle variant class", async () => {
+    const wrapper = await mountSuspended(ClippedPanel, { props: { variant: "rectangle" } });
+    expect(wrapper.classes()).toContain("rectangle");
+  });
+
+  it("applies the circle-cutout variant class", async () => {
+    const wrapper = await mountSuspended(ClippedPanel, { props: { variant: "circle-cutout" } });
+    expect(wrapper.classes()).toContain("circle-cutout");
+  });
+
+  it("renders slot content", async () => {
+    const wrapper = await mountSuspended(ClippedPanel, {
+      slots: { default: "<p class='slot-child'>Hello</p>" },
+    });
+    expect(wrapper.find(".slot-child").exists()).toBe(true);
+    expect(wrapper.find(".slot-child").text()).toBe("Hello");
+  });
+
+  it("applies styleClassPassthrough classes", async () => {
+    const wrapper = await mountSuspended(ClippedPanel, {
+      props: { styleClassPassthrough: ["custom-class"] },
+    });
+    expect(wrapper.classes()).toContain("custom-class");
+  });
+
+  it("resets classes when styleClassPassthrough prop changes", async () => {
+    const wrapper = await mountSuspended(ClippedPanel, {
+      props: { styleClassPassthrough: ["initial-class"] },
+    });
+    expect(wrapper.classes()).toContain("initial-class");
+
+    await wrapper.setProps({ styleClassPassthrough: ["updated-class"] });
+    expect(wrapper.classes()).not.toContain("initial-class");
+    expect(wrapper.classes()).toContain("updated-class");
+  });
+});

package/app/components/01.atoms/clipped-panel/tests/__snapshots__/ClippedPanel.spec.ts.snap

@@ -0,0 +1,3 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`ClippedPanel > renders correct HTML structure (default props) 1`] = `"<div class="clipped-panel square"></div>"`;

package/app/components/01.atoms/display-banner/CONSUMER-STYLING.md

@@ -0,0 +1,35 @@
+# DisplayBanner — Consumer Styling Guide
+
+## Public token API
+
+| Token | Default | Controls |
+|---|---|---|
+| `--display-banner-min-height` | `auto` | Minimum height of the banner |
+
+```css
+.my-page {
+  --display-banner-min-height: 40rem;
+}
+```
+
+Or scope to a single instance via `styleClassPassthrough`:
+
+```vue
+<DisplayBanner style-class-passthrough="hero-banner">...</DisplayBanner>
+```
+
+```css
+.hero-banner {
+  --display-banner-min-height: 40rem;
+}
+```
+
+## Layout
+
+`DisplayBanner` stacks its `canvas` and `content` slots on top of each other in a single grid
+area (`grid-template-areas: "banner"`). Whichever slot is rendered later in the DOM sits visually
+on top — put background media (an image, video, `CanvasSwitcher`-style visual) in `canvas` and
+overlaid text/CTAs in `content`, since `content` follows `canvas` in the template.
+
+Both slots are conditionally rendered (`v-if="$slots.canvas"` / `v-if="$slots.content"`), so an
+unused slot contributes no empty wrapper `<div>` to the DOM.

package/app/components/{display-banner → 01.atoms/display-banner}/DisplayBanner.vue

@@ -10,41 +10,24 @@
 </template>
 
 <script setup lang="ts">
-const props = defineProps({
-  tag: {
-    type: String,
-    default: "div",
-    validator(value: string) {
-      return [
-        "div",
-        "p",
-        "span",
-        "section",
-        "article",
-        "aside",
-        "header",
-        "footer",
-        "main",
-        "nav",
-        "ul",
-        "ol",
-      ].includes(value)
-    },
-  },
-  styleClassPassthrough: {
-    type: [String, Array] as PropType<string | string[]>,
-    default: () => [],
-  },
-})
+interface Props {
+  tag?: "div" | "p" | "span" | "section" | "article" | "aside" | "header" | "footer" | "main" | "nav" | "ul" | "ol";
+  styleClassPassthrough?: string | string[];
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  tag: "div",
+  styleClassPassthrough: () => [],
+});
 
-const { elementClasses, resetElementClasses } = useStyleClassPassthrough(props.styleClassPassthrough)
+const { elementClasses, resetElementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
 
 watch(
   () => props.styleClassPassthrough,
   () => {
-    resetElementClasses(props.styleClassPassthrough)
+    resetElementClasses(props.styleClassPassthrough);
   }
-)
+);
 </script>
 
 <style lang="css">
@@ -53,16 +36,11 @@ watch(
   display: grid;
   grid-template-areas: "banner";
   container-type: inline-size;
+  min-height: var(--display-banner-min-height, auto);
   overflow: hidden;
 
   .canvas {
     grid-area: banner;
-
-    .image {
-      object-fit: cover;
-      width: 100%;
-      height: 100%;
-    }
   }
 
   .content {

package/app/components/01.atoms/display-banner/stories/DisplayBanner.stories.ts

@@ -0,0 +1,100 @@
+import DisplayBanner from "../DisplayBanner.vue";
+import type { Meta, StoryObj } from "@nuxtjs/storybook";
+
+const meta: Meta<typeof DisplayBanner> = {
+  title: "Atoms/DisplayBanner",
+  component: DisplayBanner,
+  argTypes: {
+    tag: {
+      control: { type: "select" },
+      options: ["div", "p", "span", "section", "article", "aside", "header", "footer", "main", "nav", "ul", "ol"],
+      description: "Root element tag",
+      table: { category: "Basic" },
+    },
+    styleClassPassthrough: {
+      table: { disable: true },
+    },
+  },
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Stacks a `canvas` slot (background media) and a `content` slot (overlaid text/CTAs) in a single grid area. Either slot may be omitted.",
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof DisplayBanner>;
+
+export const Default: Story = {
+  args: {
+    tag: "div",
+  },
+  render: (args) => ({
+    components: { DisplayBanner },
+    setup() {
+      return { args };
+    },
+    template: `
+      <DisplayBanner v-bind="args" style="--display-banner-min-height: 24rem;">
+        <template #canvas>
+          <div style="width: 100%; height: 100%; background: linear-gradient(135deg, #5b8def, #8f5be9);"></div>
+        </template>
+        <template #content>
+          <div style="display: grid; place-items: center; height: 100%; color: white;">
+            <h2 style="margin: 0;">Banner content</h2>
+          </div>
+        </template>
+      </DisplayBanner>
+    `,
+  }),
+};
+
+export const CanvasOnly: Story = {
+  args: {
+    tag: "div",
+  },
+  render: (args) => ({
+    components: { DisplayBanner },
+    setup() {
+      return { args };
+    },
+    template: `
+      <DisplayBanner v-bind="args" style="--display-banner-min-height: 16rem;">
+        <template #canvas>
+          <div style="width: 100%; height: 100%; background: linear-gradient(135deg, #5b8def, #8f5be9);"></div>
+        </template>
+      </DisplayBanner>
+    `,
+  }),
+  parameters: {
+    docs: {
+      description: {
+        story: "With no `content` slot, no empty `.content` wrapper is rendered.",
+      },
+    },
+  },
+};
+
+export const ContentOnly: Story = {
+  args: {
+    tag: "div",
+  },
+  render: (args) => ({
+    components: { DisplayBanner },
+    setup() {
+      return { args };
+    },
+    template: `
+      <DisplayBanner v-bind="args" style="--display-banner-min-height: 16rem; background: #1a1a1a;">
+        <template #content>
+          <div style="display: grid; place-items: center; height: 100%; color: white;">
+            <h2 style="margin: 0;">Content, no canvas</h2>
+          </div>
+        </template>
+      </DisplayBanner>
+    `,
+  }),
+};

package/app/components/01.atoms/display-banner/tests/DisplayBanner.spec.ts

@@ -0,0 +1,78 @@
+import { describe, it, expect } from "vitest";
+import { mountSuspended } from "@nuxt/test-utils/runtime";
+import DisplayBanner from "../DisplayBanner.vue";
+
+describe("DisplayBanner", () => {
+  it("mounts without error", async () => {
+    const wrapper = await mountSuspended(DisplayBanner);
+    expect(wrapper.vm).toBeTruthy();
+  });
+
+  it("renders correct HTML structure (default props)", async () => {
+    const wrapper = await mountSuspended(DisplayBanner);
+    expect(wrapper.html()).toMatchSnapshot();
+  });
+
+  it("renders a <div> by default", async () => {
+    const wrapper = await mountSuspended(DisplayBanner);
+    expect(wrapper.element.tagName).toBe("DIV");
+  });
+
+  it("renders the given tag", async () => {
+    const wrapper = await mountSuspended(DisplayBanner, { props: { tag: "section" } });
+    expect(wrapper.element.tagName).toBe("SECTION");
+  });
+
+  it("does not render a .canvas wrapper when the canvas slot is empty", async () => {
+    const wrapper = await mountSuspended(DisplayBanner);
+    expect(wrapper.find(".canvas").exists()).toBe(false);
+  });
+
+  it("does not render a .content wrapper when the content slot is empty", async () => {
+    const wrapper = await mountSuspended(DisplayBanner);
+    expect(wrapper.find(".content").exists()).toBe(false);
+  });
+
+  it("renders the canvas slot", async () => {
+    const wrapper = await mountSuspended(DisplayBanner, {
+      slots: { canvas: "<img class='slot-canvas' />" },
+    });
+    expect(wrapper.find(".canvas .slot-canvas").exists()).toBe(true);
+  });
+
+  it("renders the content slot", async () => {
+    const wrapper = await mountSuspended(DisplayBanner, {
+      slots: { content: "<p class='slot-content'>Hello</p>" },
+    });
+    expect(wrapper.find(".content .slot-content").text()).toBe("Hello");
+  });
+
+  it("renders both slots together", async () => {
+    const wrapper = await mountSuspended(DisplayBanner, {
+      slots: {
+        canvas: "<img class='slot-canvas' />",
+        content: "<p class='slot-content'>Hello</p>",
+      },
+    });
+    expect(wrapper.find(".canvas .slot-canvas").exists()).toBe(true);
+    expect(wrapper.find(".content .slot-content").exists()).toBe(true);
+  });
+
+  it("applies styleClassPassthrough classes", async () => {
+    const wrapper = await mountSuspended(DisplayBanner, {
+      props: { styleClassPassthrough: ["custom-class"] },
+    });
+    expect(wrapper.classes()).toContain("custom-class");
+  });
+
+  it("resets classes when styleClassPassthrough prop changes", async () => {
+    const wrapper = await mountSuspended(DisplayBanner, {
+      props: { styleClassPassthrough: ["initial-class"] },
+    });
+    expect(wrapper.classes()).toContain("initial-class");
+
+    await wrapper.setProps({ styleClassPassthrough: ["updated-class"] });
+    expect(wrapper.classes()).not.toContain("initial-class");
+    expect(wrapper.classes()).toContain("updated-class");
+  });
+});

package/app/components/01.atoms/display-banner/tests/__snapshots__/DisplayBanner.spec.ts.snap

@@ -0,0 +1,8 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`DisplayBanner > renders correct HTML structure (default props) 1`] = `
+"<div class="display-banner">
+  <!--v-if-->
+  <!--v-if-->
+</div>"
+`;

package/app/components/01.atoms/display-tooltip/CONSUMER-STYLING.md

@@ -0,0 +1,62 @@
+# DisplayTooltip — Consumer Styling Guide
+
+## Public token API
+
+| Token | Default | Controls |
+|---|---|---|
+| `--display-tooltip-padding-block` | `0.8rem` | Vertical padding around the trigger row |
+| `--display-tooltip-trigger-gap` | `0.8rem` | Space between `triggerContent` slot and the trigger button |
+| `--display-tooltip-trigger-icon-box-size` | `2rem` | Trigger icon's box width/height |
+| `--display-tooltip-trigger-icon-font-size` | `1.8rem` | Trigger icon glyph size |
+| `--display-tooltip-trigger-icon-colour` | `var(--theme-text)` | Trigger icon colour |
+| `--display-tooltip-trigger-outline-width` | `0.1rem` | Trigger button focus/hover outline width |
+| `--display-tooltip-trigger-outline-colour-hover` | `var(--theme-ring)` | Trigger button outline colour on hover/focus-visible |
+| `--display-tooltip-popover-width` | `30rem` | Popover panel width |
+| `--display-tooltip-popover-padding` | `1.2rem` | Popover panel content padding |
+| `--display-tooltip-popover-content-gap` | `1.2rem` | Gap between stacked children in the `tooltipContent` slot |
+| `--display-tooltip-popover-outline-width` | `0.1rem` | Popover panel outline (border) width |
+| `--display-tooltip-popover-outline-colour` | `light-dark(var(--slate-02), var(--slate-06))` | Popover panel outline (border) colour |
+| `--display-tooltip-popover-text-colour` | `light-dark(var(--slate-09), var(--slate-01))` | Popover panel text colour |
+| `--display-tooltip-popover-background-colour` | `light-dark(var(--slate-00), var(--slate-07))` | Popover panel background |
+| `--display-tooltip-popover-border-radius` | `0.8rem` | Popover panel corner radius |
+| `--display-tooltip-popover-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 |
+| `--display-tooltip-popover-offset` | `0.1rem` | Gap between the trigger and the popover panel |
+| `--display-tooltip-close-button-colour` | `light-dark(var(--slate-09), var(--slate-01))` | Close button text colour (used by `DisplayTooltipDefined`) |
+| `--display-tooltip-close-button-border-width` | `0.1rem` | Close button border width |
+| `--display-tooltip-close-button-border-colour` | `light-dark(var(--slate-03), var(--slate-06))` | Close button border colour |
+| `--display-tooltip-close-button-outline-width` | `0.1rem` | Close button outline width |
+| `--display-tooltip-close-button-outline-colour` | `transparent` | Close button outline colour at rest (no permanent ring) |
+| `--display-tooltip-close-button-border-colour-hover` | `light-dark(var(--slate-06), var(--slate-03))` | Close button border colour on hover/focus |
+| `--display-tooltip-close-button-outline-colour-hover` | `light-dark(var(--slate-06), var(--slate-03))` | Close button outline colour on hover/focus |
+| `--display-tooltip-close-button-padding` | `0.4rem 1rem` | Close button padding |
+
+```css
+.my-page {
+  --display-tooltip-popover-background-colour: #1a1a1a;
+  --display-tooltip-popover-text-colour: white;
+  --display-tooltip-popover-outline-colour: transparent;
+}
+```
+
+Or scope to a single instance via `styleClassPassthrough`:
+
+```vue
+<DisplayTooltip style-class-passthrough="promo-tooltip">...</DisplayTooltip>
+```
+
+## 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.
+- The `.display-tooltip-close-button` styled here is rendered by `DisplayTooltipDefined`, not this
+  component directly — `DisplayTooltip` only provides the `tooltipContent` slot, so a plain
+  `DisplayTooltip` usage supplies its own close affordance if it wants one (give it
+  `style="align-self: flex-end;"` or a class to right-align it within the content's flex column,
+  same as `DisplayTooltipDefined` does internally).
+- 2026-09-07: default colours switched from raw `light-dark(black, white)` to the library's
+  neutral `--slate-*` scale, and `.display-tooltip-popover-content` gained default `padding`,
+  `display: flex; flex-direction: column;`, and `gap` (previously unstyled, meaning content sat
+  flush against the panel edges) plus the popover gained a default elevation `box-shadow`
+  (previously none) — the out-of-the-box look was flat and under-styled before this. All of these
+  remain overridable via the tokens above.