srcdev-nuxt-components 9.4.6 → 9.4.8

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.

package/app/components/01.atoms/navigation/tabs/TabsCore.vue

@@ -0,0 +1,272 @@
+<template>
+  <div class="tabs-core" :class="[`axis-${axis}`]">
+    <ul
+      ref="tabsNavRef"
+      role="tablist"
+      :aria-label="ariaLabel"
+      class="tabs-list"
+      :class="[elementClasses]"
+      @mouseleave="resetHoverToActivePosition()"
+    >
+      <li v-for="(index, key) in itemCount" :key="key">
+        <button
+          :id="`tab-${key}-trigger`"
+          :data-tab-index="key"
+          data-nav-item
+          type="button"
+          role="tab"
+          aria-selected="false"
+          class="tabs-list-item"
+          @click.prevent="navItemClicked($event)"
+          @mouseenter="navItemHovered($event)"
+          @keydown="navItemKeydown($event)"
+        >
+          <slot :name="`tab-${key}-trigger`"></slot>
+        </button>
+      </li>
+    </ul>
+    <div class="tab-content-wrapper">
+      <div
+        v-for="(item, key) in itemCount"
+        :id="`tab-${key}-content`"
+        :key="key"
+        ref="tabsContentRefs"
+        class="tab-content"
+        :aria-labelledby="`tab-${key}-trigger`"
+        role="tabpanel"
+        tabindex="0"
+        aria-hidden="true"
+      >
+        <slot :name="`tab-${key}-content`"></slot>
+      </div>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+interface Props {
+  axis?: "x" | "y";
+  transitionDuration?: number;
+  /** Number of tabs to render — drives both the trigger and content indexed slots. */
+  itemCount: number;
+  /** Shows a moving highlight behind the hovered tab. */
+  trackHover?: boolean;
+  /** Shows a moving highlight behind the active tab. */
+  trackActive?: boolean;
+  /** Shows a moving underline/sideline indicator beneath the active tab. */
+  trackIndicator?: boolean;
+  /** aria-label on the tablist — override for localisation. */
+  ariaLabel?: string;
+  styleClassPassthrough?: string | string[];
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  axis: "x",
+  transitionDuration: 200,
+  trackHover: true,
+  trackActive: true,
+  trackIndicator: true,
+  ariaLabel: "Tabs",
+  styleClassPassthrough: () => [],
+});
+
+const { elementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
+
+const tabsNavRef = ref<HTMLElement | null>(null);
+const tabsContentRefs = ref<HTMLElement[] | null>(null);
+
+const { initNavDecorators, navItemClicked, navItemHovered, navItemKeydown, resetHoverToActivePosition } = useTabs(
+  props.axis,
+  tabsNavRef,
+  tabsContentRefs,
+  props.transitionDuration,
+  { trackHover: props.trackHover, trackActive: props.trackActive, trackIndicator: props.trackIndicator }
+);
+
+onMounted(() => {
+  initNavDecorators();
+});
+</script>
+
+<style lang="css">
+@layer components {
+  .tabs-core {
+    .tabs-list {
+      position: relative;
+      display: flex;
+      width: fit-content;
+      z-index: 1;
+
+      list-style-type: none;
+      margin: 0;
+      padding: 0;
+
+      border-bottom: var(--tabs-nav-border, 0.1rem solid var(--slate-06));
+
+      .nav__hovered {
+        content: "";
+        position: absolute;
+        left: 0;
+        right: 0;
+        bottom: 0;
+        top: 0;
+        scale: var(--_width-hovered, 0.125) 1;
+        translate: var(--_x-hovered, 0) 0;
+        transform-origin: left;
+        transition:
+          scale var(--_transition-duration),
+          translate var(--_transition-duration);
+        z-index: 1;
+        background: var(--tabs-hover-indicator-colour, var(--slate-07));
+      }
+
+      .nav__active {
+        content: "";
+        position: absolute;
+        left: 0;
+        right: 0;
+        bottom: 0;
+        top: 0;
+        scale: var(--_width-active, 0.125) 1;
+        translate: var(--_x-active, 0) 0;
+        transform-origin: left;
+        transition:
+          scale var(--_transition-duration),
+          translate var(--_transition-duration);
+        z-index: 2;
+        background: var(--tabs-active-indicator-colour, var(--slate-09));
+      }
+
+      .nav__active-indicator {
+        content: "";
+        position: absolute;
+        left: 0;
+        right: 0;
+        bottom: 0;
+        scale: var(--_width-active, 0.125) 1;
+        translate: var(--_x-active, 0) 0;
+        transform-origin: left;
+        transition:
+          scale var(--_transition-duration),
+          translate var(--_transition-duration);
+        z-index: 3;
+        background: var(--tabs-underline-indicator-colour, var(--slate-10));
+        height: var(--tabs-underline-indicator-height, 0.4rem);
+      }
+
+      .tabs-list-item {
+        opacity: var(--tabs-list-item-opacity, 0.7);
+        position: relative;
+        transition: color var(--tabs-list-item-colour-transition-duration, 100ms);
+        z-index: 4;
+        background: transparent;
+        border: 0;
+        color: var(--tabs-list-item-colour, var(--slate-10));
+        cursor: pointer;
+        font: inherit;
+        text-transform: var(--tabs-list-item-text-transform, uppercase);
+        font-weight: var(--tabs-list-item-font-weight, 500);
+        margin: 0;
+        padding: var(--tabs-list-item-padding-block, 1em) var(--tabs-list-item-padding-inline, 2em);
+
+        /* Text colour tracks the indicator actually behind it — hover and active can differ. */
+        &:hover {
+          opacity: 1;
+          color: var(--tabs-hover-indicator-text-colour, var(--slate-00));
+        }
+
+        &[aria-selected="true"] {
+          opacity: 1;
+          color: var(
+            --tabs-list-item-colour-selected,
+            var(--tabs-active-indicator-text-colour, var(--slate-00))
+          );
+        }
+
+        &:focus-visible {
+          outline: var(--tabs-list-item-focus-outline-width, 2px) solid var(--theme-ring);
+          outline-offset: var(--tabs-list-item-focus-outline-offset, -2px);
+        }
+      }
+    }
+
+    .tab-content-wrapper {
+      display: grid;
+      grid-template-areas: "element-stack";
+
+      background-color: var(--tabs-content-background-colour, var(--slate-09));
+      border: var(--tabs-content-border-width, 0.1rem) solid var(--tabs-content-border-colour, var(--slate-06));
+      border-radius: var(--tabs-content-border-radius, 0);
+      outline: var(--tabs-content-border-width, 0.1rem) solid var(--tabs-content-border-colour, var(--slate-06));
+
+      .tab-content {
+        grid-area: element-stack;
+        display: none;
+
+        &:focus-visible {
+          outline: var(--tabs-list-item-focus-outline-width, 2px) solid var(--theme-ring);
+          outline-offset: calc(-1 * var(--tabs-list-item-focus-outline-width, 2px));
+        }
+      }
+    }
+
+    /*
+    * Deal with axis-y
+    **/
+
+    &.axis-y {
+      display: flex;
+      flex-direction: row;
+      gap: var(--tabs-axis-y-gap, 2em);
+
+      .tabs-list {
+        flex-direction: column;
+
+        border-bottom: initial;
+        border-left: var(--tabs-nav-border, 0.1rem solid var(--slate-06));
+        position: relative;
+
+        .tabs-list-item {
+          text-align: left;
+          width: 100%;
+        }
+
+        .nav__hovered,
+        .nav__active {
+          left: 0;
+          right: initial;
+          bottom: initial;
+          top: 0;
+          height: var(--_y-height);
+          transform-origin: top;
+          width: var(--_y-width);
+        }
+
+        .nav__hovered {
+          translate: 0 var(--_y-hovered, 0);
+        }
+
+        .nav__active {
+          translate: 0 var(--_y-active, 0);
+        }
+
+        .nav__active-indicator {
+          left: 0;
+          right: initial;
+          bottom: initial;
+          top: 0;
+          height: var(--_y-height);
+          scale: var(--_width-active, 0.125) 1;
+          translate: 0 var(--_y-active, 0);
+          transform-origin: top;
+          width: var(--tabs-underline-indicator-height, 0.4em);
+        }
+      }
+
+      .tab-content-wrapper {
+        flex-grow: 1;
+      }
+    }
+  }
+}
+</style>

package/app/components/01.atoms/navigation/tabs/stories/TabsCore.stories.ts

@@ -0,0 +1,199 @@
+import TabsCore from "../TabsCore.vue";
+import type { Meta, StoryObj } from "@nuxtjs/storybook";
+
+const meta: Meta<typeof TabsCore> = {
+  title: "Atoms/Navigation/TabsCore",
+  component: TabsCore,
+  argTypes: {
+    axis: {
+      control: "radio",
+      options: ["x", "y"],
+      description: "Layout axis — horizontal tab row or vertical tab column",
+    },
+    itemCount: {
+      control: { type: "number", min: 1, max: 6, step: 1 },
+      description: "Number of tabs — drives the tab-{n}-trigger / tab-{n}-content indexed slots",
+    },
+    transitionDuration: {
+      control: { type: "range", min: 0, max: 600, step: 10 },
+      description: "Duration (ms) of the moving indicator's transition",
+    },
+    trackHover: {
+      control: "boolean",
+      description: "Shows a moving highlight behind the hovered tab",
+    },
+    trackActive: {
+      control: "boolean",
+      description: "Shows a moving highlight behind the active tab",
+    },
+    trackIndicator: {
+      control: "boolean",
+      description: "Shows a moving underline/sideline indicator beneath the active tab",
+    },
+    ariaLabel: {
+      control: "text",
+      description: "aria-label on the tablist — override for localisation",
+    },
+  },
+  args: {
+    axis: "x",
+    itemCount: 3,
+    transitionDuration: 200,
+    trackHover: true,
+    trackActive: true,
+    trackIndicator: true,
+    ariaLabel: "Tabs",
+  },
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "A tablist built from indexed slots (tab-{n}-trigger / tab-{n}-content, driven by itemCount) with moving hover/active/underline indicators. Supports arrow-key navigation (Left/Right or Up/Down depending on axis, plus Home/End) per the WAI-ARIA Tabs pattern.",
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof TabsCore>;
+
+// ─── Fixtures ─────────────────────────────────────────────────────────────────
+
+const panels = [
+  { label: "Overview", content: "A short summary of the product goes here." },
+  { label: "Specs", content: "Technical specifications and dimensions." },
+  { label: "Reviews", content: "Customer reviews and ratings." },
+];
+
+const tabSlots = panels
+  .map(
+    (panel, index) => `
+    <template #tab-${index}-trigger>${panel.label}</template>
+    <template #tab-${index}-content>
+      <div style="padding: 1.6rem;">${panel.content}</div>
+    </template>`
+  )
+  .join("\n");
+
+const fivePanels = [
+  { label: "Overview", content: "A short summary of the product goes here." },
+  { label: "Specs", content: "Technical specifications and dimensions." },
+  { label: "Reviews", content: "Customer reviews and ratings." },
+  { label: "Shipping", content: "Delivery estimates and carrier options." },
+  { label: "Returns", content: "Return window and refund policy." },
+];
+
+const fiveTabSlots = fivePanels
+  .map(
+    (panel, index) => `
+    <template #tab-${index}-trigger>${panel.label}</template>
+    <template #tab-${index}-content>
+      <div style="padding: 1.6rem;">${panel.content}</div>
+    </template>`
+  )
+  .join("\n");
+
+// ─── Stories ──────────────────────────────────────────────────────────────────
+
+export const Horizontal: Story = {
+  args: { itemCount: panels.length },
+  render: (args) => ({
+    components: { TabsCore },
+    setup() {
+      return { args };
+    },
+    template: `
+      <TabsCore v-bind="args">
+        ${tabSlots}
+      </TabsCore>
+    `,
+  }),
+};
+
+export const Vertical: Story = {
+  args: { itemCount: panels.length, axis: "y" },
+  render: (args) => ({
+    components: { TabsCore },
+    setup() {
+      return { args };
+    },
+    template: `
+      <TabsCore v-bind="args">
+        ${tabSlots}
+      </TabsCore>
+    `,
+  }),
+};
+
+export const IndicatorsOff: Story = {
+  name: "Indicators Off",
+  args: { itemCount: panels.length, trackHover: false, trackActive: false, trackIndicator: false },
+  render: (args) => ({
+    components: { TabsCore },
+    setup() {
+      return { args };
+    },
+    template: `
+      <TabsCore v-bind="args">
+        ${tabSlots}
+      </TabsCore>
+    `,
+  }),
+};
+
+export const FiveTabs: Story = {
+  name: "Five Tabs (regression check)",
+  args: { itemCount: fivePanels.length },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "itemCount raised to 5 as a regression check — the original hand-rolled version of this component had an indicator-positioning issue that only showed up with more than 3 tabs. Try hovering quickly across several tabs in a row, then clicking a tab several positions away from the active one (e.g. tab 1 → tab 5), to confirm the hover/active/underline indicators land in the right place without jumping or lagging behind.",
+      },
+    },
+  },
+  render: (args) => ({
+    components: { TabsCore },
+    setup() {
+      return { args };
+    },
+    template: `
+      <TabsCore v-bind="args">
+        ${fiveTabSlots}
+      </TabsCore>
+    `,
+  }),
+};
+
+export const IndicatorColours: Story = {
+  name: "Indicator Colours (demo)",
+  args: { itemCount: panels.length },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Each moving indicator given a distinct colour via its public CSS token, purely to make the three separate states (hover / active / underline) easy to tell apart. Hover a tab to see the green highlight move independently of the blue active highlight — the label text stays white against both backgrounds via the matching --tabs-hover-indicator-text-colour / --tabs-active-indicator-text-colour tokens (see CONSUMER-STYLING.md), which previously had no effect since they were wired to the wrong element.",
+      },
+    },
+  },
+  render: (args) => ({
+    components: { TabsCore },
+    setup() {
+      const indicatorColourVars = {
+        "--tabs-hover-indicator-colour": "seagreen",
+        "--tabs-hover-indicator-text-colour": "white",
+        "--tabs-active-indicator-colour": "steelblue",
+        "--tabs-active-indicator-text-colour": "white",
+        "--tabs-underline-indicator-colour": "darkorange",
+      };
+      return { args, indicatorColourVars };
+    },
+    template: `
+      <div :style="indicatorColourVars">
+        <TabsCore v-bind="args">
+          ${tabSlots}
+        </TabsCore>
+      </div>
+    `,
+  }),
+};