srcdev-nuxt-components 9.4.7 → 9.4.8

package/app/components/01.atoms/animations/rotating-carousel-image/tests/__snapshots__/RotatingCarouselImage.spec.ts.snap

@@ -0,0 +1,19 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`RotatingCarouselImage > renders correct HTML structure (all props set) 1`] = `
+"<section class="rotating-carousel hover-pauses" style="--_rotate-x: 10deg; --_perspective: 1200px; --_translateZ: 1200px;" role="region" aria-label="Custom carousel" tabindex="0">
+  <div class="sr-only">Custom instructions</div><button class="control-btn" type="button" aria-label="Pause rotation"><span class="iconify i-mdi:pause" aria-hidden="true"></span></button>
+  <div class="slider" style="--_quantity: 2;">
+    <div class="item" style="--_position: 0;"><img data-nuxt-img="" srcset="/_ipx/_/a.jpg 1x, /_ipx/_/a.jpg 2x" alt="A" src="/_ipx/_/a.jpg"></div>
+    <div class="item" style="--_position: 1;"><img data-nuxt-img="" srcset="/_ipx/_/b.jpg 1x, /_ipx/_/b.jpg 2x" alt="B" src="/_ipx/_/b.jpg"></div>
+  </div>
+</section>"
+`;
+
+exports[`RotatingCarouselImage > renders correct HTML structure (default props) 1`] = `
+"<div class="rotating-carousel" style="--_rotate-x: 0deg; --_perspective: 1000px; --_translateZ: 1000px;" role="region" aria-label="Rotating image carousel" tabindex="0">
+  <div class="sr-only">Use spacebar to pause or play the rotation.</div>
+  <!--v-if-->
+  <div class="slider" style="--_quantity: 0;"></div>
+</div>"
+`;

package/app/components/01.atoms/navigation/skip-links/CONSUMER-STYLING.md

@@ -0,0 +1,31 @@
+# SkipLinks — Consumer Styling Guide
+
+## Public token API
+
+| Token | Default | Controls |
+|---|---|---|
+| `--skip-links-z-index` | `1000` | Stacking context of the revealed skip-nav panel |
+| `--skip-links-gap` | `0.2rem` | Gap between stacked skip links |
+| `--skip-links-background-colour` | `black` | Skip-nav panel background |
+| `--skip-links-border-colour` | `white` | Skip-nav panel border colour |
+| `--skip-links-border-width` | `1px` | Skip-nav panel border width |
+| `--skip-links-padding` | `0.2rem` | Skip-nav panel padding |
+| `--skip-links-text-colour` | `white` | Skip link text colour |
+| `--skip-links-link-padding-block` | `0.8rem` | Skip link vertical padding |
+| `--skip-links-link-padding-inline` | `1.2rem` | Skip link horizontal padding |
+| `--skip-links-transition-duration` | `0.3s` | Duration of the reveal transition when a link is focused |
+| `--skip-links-focus-outline-width` | `2px` | Focus outline width on a skip link |
+| `--skip-links-focus-outline-colour` | `white` | Focus outline colour on a skip link |
+
+```css
+.my-page {
+  --skip-links-background-colour: #111;
+  --skip-links-border-colour: #ffd700;
+  --skip-links-focus-outline-colour: #ffd700;
+}
+```
+
+## Links are prop-driven
+
+The set of skip links is provided via the `links` prop (`{ href, label }[]`), not slots — see the
+skill doc for the default value and localisation notes.

package/app/components/01.atoms/navigation/skip-links/SkipLinks.vue

@@ -0,0 +1,92 @@
+<template>
+  <div class="skip-links" :class="[elementClasses]">
+    <div v-if="$slots.homeLink" class="skip-links__home">
+      <slot name="homeLink"></slot>
+    </div>
+    <nav class="skip-links__nav" :aria-label="ariaLabel">
+      <a v-for="link in links" :key="link.href" :href="link.href" class="skip-links__link">{{ link.label }}</a>
+    </nav>
+  </div>
+</template>
+
+<script lang="ts" setup>
+import type { SkipLink } from "~/types/components"
+
+interface Props {
+  links?: SkipLink[]
+  /** aria-label on the nav landmark — override for localisation. */
+  ariaLabel?: string
+  styleClassPassthrough?: string | string[]
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  links: () => [
+    { href: "#main-content", label: "Skip to main content" },
+    { href: "#footer-content", label: "Skip to footer" },
+  ],
+  ariaLabel: "Skip navigation",
+  styleClassPassthrough: () => [],
+})
+
+const { elementClasses, resetElementClasses } = useStyleClassPassthrough(props.styleClassPassthrough)
+
+watch(
+  () => props.styleClassPassthrough,
+  () => {
+    resetElementClasses(props.styleClassPassthrough)
+  }
+)
+</script>
+
+<style lang="css">
+@layer components {
+  .skip-links {
+    position: relative;
+
+    .skip-links__nav {
+      position: absolute;
+      top: 100%;
+      left: 0;
+      z-index: var(--skip-links-z-index, 1000);
+
+      display: flex;
+      flex-direction: column;
+      gap: var(--skip-links-gap, 0.2rem);
+      background-color: var(--skip-links-background-colour, black);
+      border: var(--skip-links-border-width, 1px) solid var(--skip-links-border-colour, white);
+      padding: var(--skip-links-padding, 0.2rem);
+      margin: 0;
+
+      /* Hidden off-screen via transform — does NOT break keyboard focusability */
+      opacity: 0;
+      transform: translateY(-100%);
+      transition:
+        transform var(--skip-links-transition-duration, 0.3s) ease-in-out,
+        opacity var(--skip-links-transition-duration, 0.3s) ease-in-out;
+
+      &:focus-within {
+        opacity: 1;
+        transform: translateY(0);
+      }
+    }
+
+    .skip-links__link {
+      display: block;
+      color: var(--skip-links-text-colour, white);
+      text-decoration: none;
+      padding: var(--skip-links-link-padding-block, 0.8rem) var(--skip-links-link-padding-inline, 1.2rem);
+      text-wrap: nowrap;
+
+      &:focus-visible {
+        outline: var(--skip-links-focus-outline-width, 2px) solid var(--skip-links-focus-outline-colour, white);
+      }
+    }
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .skip-links .skip-links__nav {
+      transition: none;
+    }
+  }
+}
+</style>

package/app/components/01.atoms/navigation/skip-links/stories/SkipLinks.stories.ts

@@ -0,0 +1,113 @@
+import SkipLinks from "../SkipLinks.vue";
+import type { Meta, StoryObj } from "@nuxtjs/storybook";
+import type { SkipLink } from "~/types/components";
+
+const meta: Meta<typeof SkipLinks> = {
+  title: "Atoms/Navigation/SkipLinks",
+  component: SkipLinks,
+  argTypes: {
+    links: {
+      control: "object",
+      description: "Ordered list of { href, label } skip targets",
+    },
+    ariaLabel: {
+      control: "text",
+      description: "aria-label on the nav landmark — override for localisation",
+    },
+    styleClassPassthrough: {
+      control: "object",
+      description: "Additional CSS classes applied to the root element",
+    },
+  },
+  args: {
+    ariaLabel: "Skip navigation",
+    styleClassPassthrough: [],
+  },
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "An accessibility utility that renders a set of visually-hidden links revealed only on keyboard focus, letting keyboard/screen-reader users jump past repeated navigation straight to main content, the footer, or any other in-page target. The links are placed first in the DOM — consumers should place `<SkipLinks>` at the very top of their page layout.",
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof SkipLinks>;
+
+// ─── Stories ──────────────────────────────────────────────────────────────────
+
+export const Default: Story = {
+  render: (args) => ({
+    components: { SkipLinks },
+    setup() {
+      return { args };
+    },
+    template: `
+      <div>
+        <p style="padding: 2rem; text-align: center;">
+          The skip links below are visually hidden until focused. Click into this preview, then
+          press <kbd>Tab</kbd> to reveal them.
+        </p>
+        <SkipLinks v-bind="args" />
+      </div>
+    `,
+  }),
+};
+
+const customLinks: SkipLink[] = [
+  { href: "#site-navigation", label: "Skip to navigation" },
+  { href: "#main-content", label: "Skip to main content" },
+  { href: "#footer-content", label: "Skip to footer" },
+];
+
+export const CustomLinks: Story = {
+  name: "Custom Links",
+  args: { links: customLinks },
+  render: (args) => ({
+    components: { SkipLinks },
+    setup() {
+      return { args };
+    },
+    template: `
+      <div>
+        <p style="padding: 2rem; text-align: center;">
+          Press <kbd>Tab</kbd> after clicking into this preview to reveal three custom skip links.
+        </p>
+        <SkipLinks v-bind="args" />
+      </div>
+    `,
+  }),
+};
+
+export const AlwaysVisible: Story = {
+  name: "Always Visible (for review)",
+  parameters: {
+    docs: {
+      description: {
+        story: "Forces the skip-nav panel open via `:focus-within` emulation so it can be inspected without tabbing — for visual review only, not representative of real usage.",
+      },
+    },
+  },
+  render: (args) => ({
+    components: { SkipLinks },
+    setup() {
+      return { args };
+    },
+    template: `
+      <div>
+        <style>
+          .always-visible-demo .skip-links__nav {
+            opacity: 1 !important;
+            transform: translateY(0) !important;
+            position: static !important;
+          }
+        </style>
+        <div class="always-visible-demo">
+          <SkipLinks v-bind="args" />
+        </div>
+      </div>
+    `,
+  }),
+};

package/app/components/01.atoms/navigation/skip-links/tests/SkipLinks.spec.ts

@@ -0,0 +1,71 @@
+import { describe, it, expect } from "vitest";
+import { mountSuspended } from "@nuxt/test-utils/runtime";
+import SkipLinks from "../SkipLinks.vue";
+import type { SkipLink } from "~/types/components";
+
+describe("SkipLinks", () => {
+  it("mounts without error", async () => {
+    const wrapper = await mountSuspended(SkipLinks);
+    expect(wrapper.vm).toBeTruthy();
+  });
+
+  it("renders correct HTML structure (default props)", async () => {
+    const wrapper = await mountSuspended(SkipLinks);
+    expect(wrapper.html()).toMatchSnapshot();
+  });
+
+  it("renders correct HTML structure (all props set)", async () => {
+    const wrapper = await mountSuspended(SkipLinks, {
+      props: {
+        links: [{ href: "#content", label: "Skip to content" }],
+        ariaLabel: "Custom skip nav",
+      },
+    });
+    expect(wrapper.html()).toMatchSnapshot();
+  });
+
+  it("renders the default main-content and footer links", async () => {
+    const wrapper = await mountSuspended(SkipLinks);
+    const links = wrapper.findAll(".skip-links__link");
+    expect(links).toHaveLength(2);
+    expect(links[0]!.attributes("href")).toBe("#main-content");
+    expect(links[0]!.text()).toBe("Skip to main content");
+    expect(links[1]!.attributes("href")).toBe("#footer-content");
+    expect(links[1]!.text()).toBe("Skip to footer");
+  });
+
+  it("renders custom links when the links prop is provided", async () => {
+    const customLinks: SkipLink[] = [
+      { href: "#nav", label: "Skip to navigation" },
+      { href: "#search", label: "Skip to search" },
+      { href: "#content", label: "Skip to content" },
+    ];
+    const wrapper = await mountSuspended(SkipLinks, { props: { links: customLinks } });
+    const links = wrapper.findAll(".skip-links__link");
+    expect(links).toHaveLength(3);
+    expect(links.map((link) => link.text())).toEqual(["Skip to navigation", "Skip to search", "Skip to content"]);
+  });
+
+  it("defaults the nav aria-label to 'Skip navigation'", async () => {
+    const wrapper = await mountSuspended(SkipLinks);
+    expect(wrapper.find(".skip-links__nav").attributes("aria-label")).toBe("Skip navigation");
+  });
+
+  it("uses a custom ariaLabel when provided", async () => {
+    const wrapper = await mountSuspended(SkipLinks, { props: { ariaLabel: "Custom skip nav" } });
+    expect(wrapper.find(".skip-links__nav").attributes("aria-label")).toBe("Custom skip nav");
+  });
+
+  it("does not render the home-link slot wrapper when the slot is unused", async () => {
+    const wrapper = await mountSuspended(SkipLinks);
+    expect(wrapper.find(".skip-links__home").exists()).toBe(false);
+  });
+
+  it("renders the homeLink slot content when provided", async () => {
+    const wrapper = await mountSuspended(SkipLinks, {
+      slots: { homeLink: "<a href='/' class='logo-link'>Home</a>" },
+    });
+    expect(wrapper.find(".skip-links__home").exists()).toBe(true);
+    expect(wrapper.find(".logo-link").exists()).toBe(true);
+  });
+});

package/app/components/01.atoms/navigation/skip-links/tests/__snapshots__/SkipLinks.spec.ts.snap

@@ -0,0 +1,15 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`SkipLinks > renders correct HTML structure (all props set) 1`] = `
+"<div class="skip-links">
+  <!--v-if-->
+  <nav class="skip-links__nav" aria-label="Custom skip nav"><a href="#content" class="skip-links__link">Skip to content</a></nav>
+</div>"
+`;
+
+exports[`SkipLinks > renders correct HTML structure (default props) 1`] = `
+"<div class="skip-links">
+  <!--v-if-->
+  <nav class="skip-links__nav" aria-label="Skip navigation"><a href="#main-content" class="skip-links__link">Skip to main content</a><a href="#footer-content" class="skip-links__link">Skip to footer</a></nav>
+</div>"
+`;

package/app/components/01.atoms/navigation/tabs/CONSUMER-STYLING.md

@@ -0,0 +1,99 @@
+# TabsCore — Consumer Styling Guide
+
+## Public token API
+
+| Token | Default | Controls |
+|---|---|---|
+| `--tabs-nav-border` | `0.1rem solid var(--slate-06)` | Border between the tab list and its content (bottom border on `axis="x"`, left border on `axis="y"`) |
+| `--tabs-hover-indicator-colour` | `var(--slate-07)` | Background of the moving hover highlight (`trackHover`) |
+| `--tabs-hover-indicator-text-colour` | `var(--slate-00)` | Text colour of a hovered tab trigger's label — keep this in contrast with `--tabs-hover-indicator-colour` |
+| `--tabs-active-indicator-colour` | `var(--slate-09)` | Background of the moving active-tab highlight (`trackActive`) |
+| `--tabs-active-indicator-text-colour` | `var(--slate-00)` | Fallback text colour of the active tab trigger's label — keep this in contrast with `--tabs-active-indicator-colour` |
+| `--tabs-underline-indicator-colour` | `var(--slate-10)` | Colour of the underline/sideline indicator (`trackIndicator`) |
+| `--tabs-underline-indicator-height` | `0.4rem` | Thickness of the underline indicator (`axis="x"`) — also used as its width on `axis="y"` |
+| `--tabs-list-item-opacity` | `0.7` | Opacity of an inactive tab trigger |
+| `--tabs-list-item-colour` | `var(--slate-10)` | Text colour of an inactive tab trigger |
+| `--tabs-list-item-colour-selected` | falls back to `--tabs-active-indicator-text-colour` | Text colour of the active tab trigger — set this directly to override without touching `--tabs-active-indicator-text-colour` |
+| `--tabs-list-item-text-transform` | `uppercase` | `text-transform` of tab trigger labels |
+| `--tabs-list-item-font-weight` | `500` | Font weight of tab trigger labels |
+| `--tabs-list-item-padding-block` | `1em` | Vertical padding of a tab trigger |
+| `--tabs-list-item-padding-inline` | `2em` | Horizontal padding of a tab trigger |
+| `--tabs-list-item-colour-transition-duration` | `100ms` | Transition duration of the trigger text-colour change |
+| `--tabs-list-item-focus-outline-width` | `2px` | Focus outline width on a tab trigger/panel (colour is `--theme-ring`) |
+| `--tabs-list-item-focus-outline-offset` | `-2px` | Focus outline offset on a tab trigger |
+| `--tabs-content-background-colour` | `var(--slate-09)` | Background of the content panel wrapper |
+| `--tabs-content-border-width` | `0.1rem` | Border/outline width of the content panel wrapper |
+| `--tabs-content-border-colour` | `var(--slate-06)` | Border/outline colour of the content panel wrapper |
+| `--tabs-content-border-radius` | `0` | Corner radius of the content panel wrapper |
+| `--tabs-axis-y-gap` | `2em` | Gap between the tab list and content when `axis="y"` |
+
+```css
+.my-page {
+  --tabs-active-indicator-colour: #1a1a1a;
+  --tabs-underline-indicator-colour: #b5651d;
+  --tabs-content-border-radius: 0.8rem;
+}
+```
+
+## Colour tokens are flat values, not light-dark() pairs
+
+Every colour token above defaults to a single flat `--slate-*` value rather than a
+`light-dark(lightValue, darkValue)` pair — this component doesn't bake in automatic light/dark
+scheme-switching for its own defaults. If you want a token to adapt to `color-scheme`, wrap your
+own override in `light-dark()`:
+
+```css
+.my-page {
+  --tabs-active-indicator-colour: light-dark(#1a1a1a, #f5f5f5);
+}
+```
+
+## Tab-label text colour tracks the indicator behind it
+
+Hover and active can have different background colours (`--tabs-hover-indicator-colour` vs.
+`--tabs-active-indicator-colour`), so the trigger label uses two separate text-colour tokens
+rather than one shared "selected" colour — otherwise overriding just one indicator's background
+risks making the label unreadable against it while leaving the other state fine. If you override
+either indicator background, override its matching text-colour token to keep contrast:
+
+```css
+.my-page {
+  --tabs-hover-indicator-colour: gold;
+  --tabs-hover-indicator-text-colour: black;
+  --tabs-active-indicator-colour: navy;
+  --tabs-active-indicator-text-colour: white;
+}
+```
+
+## Tabs spanned by a jump keep their normal styling
+
+When the active tab (or hover) jumps across several tabs at once (e.g. clicking tab 5 while tab 1
+is active), the sliding indicator animates across the tabs in between, but their own labels are
+**not** recoloured to the active/hover text colour during that transition — they keep their normal
+inactive styling throughout. An earlier version force-applied the active text colour to every
+spanned tab for the whole transition, on the assumption the sliding indicator visually covered them
+the entire time — it doesn't (a forward jump grows the indicator gradually from the old tab's
+position, so it only reaches later tabs partway through), so intermediate labels could end up a
+colour that matched neither their own background nor the indicator yet, making them briefly
+invisible. Fixed 2026-09-15.
+
+Since a non-active tab keeps its normal inactive text colour throughout, and the active indicator
+still visually passes under it while sliding, `--tabs-active-indicator-colour`'s default
+(`var(--slate-09)`) is deliberately *not* the same value as `--tabs-list-item-colour`'s default
+(`var(--slate-10)`) — they used to be identical, which meant a passed-over tab's text became
+literally the same colour as the indicator sliding beneath it (invisible). If you override
+`--tabs-active-indicator-colour`, check it still differs enough from `--tabs-list-item-colour` (or
+override that too) to avoid the same collision recurring.
+
+## Indicator visibility is prop-driven, not tokens
+
+Whether the hover highlight, active highlight, and underline indicator render at all is controlled
+by the `trackHover`/`trackActive`/`trackIndicator` boolean props (all default `true`), since they
+also gate whether the underlying DOM nodes are created — not just their styling.
+
+## Movement/position values are private
+
+`--_x-active`, `--_x-hovered`, `--_width-active`, `--_width-hovered`, `--_y-active`, `--_y-hovered`,
+`--_y-height`, `--_y-width`, and `--_transition-duration` are computed at runtime from the tab
+elements' measured layout (`offsetLeft`/`offsetWidth`/etc. in `useTabs`) and aren't meaningful to
+override directly — use `transitionDuration` (a prop, in ms) to control indicator movement speed.