srcdev-nuxt-components 9.0.14 → 9.0.16

package/app/components/04.templates/page-hero-highlights/PageHeroHighlights.vue

@@ -0,0 +1,239 @@
+<template>
+  <component
+    :is="tag"
+    class="page-hero-highlights"
+    :class="[elementClasses, componentClasses]"
+    :aria-labelledby="ariaLabelledby"
+  >
+    <div class="header-row">
+      <div class="header-slot">
+        <slot name="header" :heading-id="headingId"></slot>
+      </div>
+    </div>
+    <div class="highlights-row" :class="highlightClasses">
+      <slot name="highlights"></slot>
+    </div>
+    <div class="content-row">
+      <div class="content-slot">
+        <slot name="content"></slot>
+      </div>
+    </div>
+  </component>
+</template>
+
+<script setup lang="ts">
+interface Props {
+  tag?: "div" | "section" | "main";
+  highlightsEqualWidths?: boolean;
+  highlightsJustify?: "start" | "center" | "end" | "space-between" | "space-around";
+  maxWidth?: string;
+  contentAlign?: "start" | "center";
+  highlightTitleBaseline?: boolean;
+  styleClassPassthrough?: string | string[];
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  tag: "div",
+  highlightsEqualWidths: false,
+  highlightsJustify: "start",
+  maxWidth: undefined,
+  contentAlign: "center",
+  highlightTitleBaseline: false,
+  styleClassPassthrough: () => [],
+});
+
+const gridColumns = computed(() => {
+  if (!props.maxWidth) return "16px 1fr 16px";
+  if (props.contentAlign === "start") return `16px minmax(0, ${props.maxWidth}) 1fr`;
+  return `max(16px, (100% - ${props.maxWidth}) / 2) 1fr max(16px, (100% - ${props.maxWidth}) / 2)`;
+});
+
+const { headingId, ariaLabelledby } = useAriaLabelledById(() => props.tag);
+const componentClasses = computed(() => ({
+  "highlight-title-baseline": props.highlightTitleBaseline,
+}));
+
+const highlightClasses = computed(() => ({
+  "equal-widths": props.highlightsEqualWidths,
+  "flexible-widths": !props.highlightsEqualWidths,
+  [`justify-${props.highlightsJustify}`]: true,
+}));
+
+const { elementClasses, resetElementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
+
+watch(
+  () => props.styleClassPassthrough,
+  () => {
+    resetElementClasses(props.styleClassPassthrough);
+  }
+);
+</script>
+
+<style lang="css">
+.page-hero-highlights {
+  /* User themable tokens */
+  --header-row-background-colour: darkblue;
+
+  --highlights-row-item-gap: 1rem;
+  --highlights-row-initial-item-offset: 1.2rem;
+
+  --highlight-rows-gap: 1.2rem;
+  --highlight-title-height: 1fr; /* see: highlight-title-baseline class below */
+  --highlight-padding-block-start: 1.2rem;
+  --highlight-padding: 1.2rem;
+
+  --highlight-background-color: white;
+  --highlight-border: 1px solid black;
+  --highlight-border-radius: 8px;
+  --highlight-color: black;
+
+  --content-row-background-color: var(--slate-01); /* transparent */
+  --content-row-start-gap: 1.2rem;
+  --content-row-end-gap: 1.2rem;
+
+  --content-slot-margin-block-start: 2.4rem;
+  --content-slot-margin: var(--highlights-row-initial-item-offset);
+  --content-slot-background-color: var(--slate-00);
+  --content-slot-border: 1px solid var(--slate-06);
+  --content-slot-border-radius: 0.8rem;
+  --content-slot-outline: 1px solid var(--slate-02);
+
+  &.highlight-title-baseline {
+    --highlight-title-height: 4rem; /* We need to manually tweak height, preferrably a proportional value as we're not setting an top padding when not prop.highlight-title-baseline */
+    --highlight-padding-block-start: 0; /* We're setting the title height via row height, so this should be exposed for override in consuming page */
+  }
+
+  display: grid;
+  grid-template-columns: v-bind(gridColumns);
+  grid-template-rows: auto var(--highlight-title-height) 1fr auto;
+  gap: 0;
+
+  .header-row {
+    /* Element geometry */
+    grid-column: 1 / -1;
+    grid-row: 1 / 3;
+    display: grid;
+    grid-template-columns: subgrid;
+    grid-template-rows: subgrid;
+
+    /* Element theme */
+    background-color: var(--header-row-background-colour);
+
+    .header-slot {
+      grid-column: 2;
+      grid-row: 1;
+    }
+  }
+
+  .highlights-row {
+    /* Element geometry */
+    grid-column: 2;
+    grid-row: 2 / 4; /* rows 2–3: straddles header/content boundary */
+
+    position: relative;
+    z-index: 1;
+
+    /* Element theme */
+    gap: var(--highlights-row-item-gap);
+    margin-inline-start: var(--highlights-row-initial-item-offset);
+
+    &.equal-widths {
+      display: grid;
+      grid-auto-columns: 1fr;
+      grid-auto-flow: column;
+    }
+
+    &.flexible-widths {
+      display: flex;
+      flex-wrap: wrap;
+      justify-content: center;
+    }
+
+    &.justify-start {
+      justify-content: start;
+    }
+    &.justify-center {
+      justify-content: center;
+    }
+    &.justify-end {
+      justify-content: end;
+    }
+    &.justify-space-between {
+      justify-content: space-between;
+    }
+    &.justify-space-around {
+      justify-content: space-around;
+    }
+
+    .highlight {
+      /* Element geometry */
+      display: grid;
+      grid-template-rows: subgrid;
+      grid-auto-flow: row;
+
+      /* Element theme */
+      padding-block: var(--highlight-padding-block-start) var(--highlight-padding);
+      padding-inline: var(--highlight-padding);
+
+      background-color: var(--highlight-background-color);
+      border: var(--highlight-border);
+      border-radius: var(--highlight-border-radius);
+      color: var(--highlight-color);
+
+      .title {
+        display: grid;
+        grid-row: 2;
+        align-items: end;
+        height: var(--highlight-title-height);
+      }
+      .body {
+        /* Element geometry */
+        grid-row: 3;
+        margin-block-start: var(--highlight-rows-gap);
+
+        /* Element theme */
+      }
+    }
+  }
+
+  .content-row {
+    /* Element geometry */
+    grid-column: 1 / span 3;
+    grid-row: 3 / span 2;
+    display: grid;
+    grid-template-columns: subgrid;
+    grid-template-rows: subgrid;
+
+    position: relative;
+    isolation: isolate;
+
+    /* Element theme */
+    background-color: var(--content-row-background-color);
+    padding-block-end: var(--content-row-end-gap);
+
+    &:before {
+      /* Element geometry */
+      content: "";
+      grid-template-columns: subgrid;
+      grid-template-rows: subgrid;
+      display: grid;
+      grid-column: 2;
+      grid-row: 1 / span 2;
+
+      /* Element theme */
+      margin-top: var(--content-row-start-gap);
+
+      background-color: var(--content-slot-background-color);
+      border: var(--content-slot-border);
+      outline: var(--content-slot-outline);
+      border-radius: var(--content-slot-border-radius);
+    }
+    .content-slot {
+      grid-column: 2;
+      grid-row: 2;
+      margin-block: var(--content-slot-margin-block-start) var(--content-slot-margin);
+      margin-inline: var(--content-slot-margin);
+    }
+  }
+}
+</style>

package/app/components/04.templates/page-hero-highlights/stories/PageHeroHighlights.stories.ts

@@ -0,0 +1,404 @@
+import { computed } from "vue";
+import PageHeroHighlights from "../PageHeroHighlights.vue";
+import type { Meta, StoryObj } from "@nuxtjs/storybook";
+
+type StoryArgs = {
+  tag?: "div" | "section" | "main";
+  highlightsEqualWidths?: boolean;
+  highlightsJustify?: "start" | "center" | "end" | "space-between" | "space-around";
+  maxWidth?: string;
+  contentAlign?: "start" | "center";
+  highlightTitleBaseline?: boolean;
+  headerBackground?: string;
+  contentBackground?: string;
+  highlightCount?: 1 | 2 | 3;
+  styleClassPassthrough?: string | string[];
+};
+
+const meta: Meta<StoryArgs> = {
+  title: "Templates/PageHeroHighlights",
+  component: PageHeroHighlights,
+  argTypes: {
+    tag: {
+      control: { type: "select" },
+      options: ["div", "section", "main"],
+      description: "HTML element to render as the root",
+    },
+    highlightsEqualWidths: {
+      control: "boolean",
+      description: "When true, highlight items share equal widths (grid). When false, items size to content (flex).",
+    },
+    highlightsJustify: {
+      control: { type: "select" },
+      options: ["start", "center", "end", "space-between", "space-around"],
+      description: "Justification of highlight items along the main axis",
+    },
+    maxWidth: {
+      control: { type: "select" },
+      options: ["", "600px", "800px", "1024px", "1200px", "1440px"],
+      description:
+        "Max width of the central content column. Gutters grow to enforce the constraint; below this width they hold at 16px.",
+    },
+    contentAlign: {
+      control: { type: "inline-radio" },
+      options: ["start", "center"],
+      description:
+        "Align the content column to the start (left gutter stays 16px, right takes remaining space) or center (equal gutters). Only meaningful when maxWidth is set.",
+    },
+    highlightTitleBaseline: {
+      control: "boolean",
+      description:
+        "When true, fixes the highlight title row to a set height so titles align to the header baseline. Override --highlight-title-height in the consuming page to tune the value.",
+    },
+    headerBackground: {
+      control: "color",
+      description: "Background colour of the header zone (sets --header-row-background-colour)",
+    },
+    contentBackground: {
+      control: "color",
+      description: "Background colour of the content zone (sets --content-row-background-color)",
+    },
+    highlightCount: {
+      control: { type: "select" },
+      options: [1, 2, 3],
+      description: "Number of highlight items to display in the highlights slot",
+    },
+    styleClassPassthrough: {
+      control: "object",
+      description: "Additional CSS classes applied to the root element",
+    },
+  },
+  args: {
+    tag: "div",
+    highlightsEqualWidths: false,
+    highlightsJustify: "start",
+    maxWidth: "",
+    contentAlign: "center",
+    highlightTitleBaseline: false,
+    headerBackground: "",
+    contentBackground: "",
+    highlightCount: 1,
+    styleClassPassthrough: [],
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof PageHeroHighlights>;
+
+// ─── Shared setup helper ──────────────────────────────────────────────────────
+
+function useStorySetup(args: StoryArgs) {
+  const bgStyles = computed(() => ({
+    ...(args.headerBackground ? { "--header-row-background-colour": args.headerBackground } : {}),
+    ...(args.contentBackground ? { "--content-row-background-color": args.contentBackground } : {}),
+  }));
+  const highlightCount = computed(() => args.highlightCount ?? 3);
+  const componentArgs = computed(() => {
+    const { headerBackground: _h, contentBackground: _c, highlightCount: _n, ...rest } = args;
+    return rest;
+  });
+  return { bgStyles, componentArgs, highlightCount };
+}
+
+// ─── Stories ─────────────────────────────────────────────────────────────────
+
+/** Default — header, highlights strip, and page content with all three slots filled. */
+export const Default: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: `
+All layout and visual properties are customisable via CSS custom properties. Set them on \`.page-hero-highlights\` (or a scoped class via \`styleClassPassthrough\`):
+
+\`\`\`css
+.page-hero-highlights {
+  /* Header zone */
+  --header-row-background-colour: darkblue;
+
+  /* Highlights strip */
+  --highlights-row-item-gap: 1rem;
+  --highlights-row-initial-item-offset: 1.2rem;
+
+  /* Highlight cards */
+  --highlight-rows-gap: 1.2rem;
+  --highlight-title-height: 1fr; /* see: highlight-title-baseline prop */
+  --highlight-padding-block-start: 1.2rem;
+  --highlight-padding: 1.2rem;
+  --highlight-background-color: white;
+  --highlight-border: 1px solid black;
+  --highlight-border-radius: 8px;
+  --highlight-color: black;
+
+  /* Content zone */
+  --content-row-background-color: var(--slate-01); /* transparent */
+  --content-row-start-gap: 1.2rem;
+  --content-row-end-gap: 1.2rem;
+
+  /* Content slot decorative border */
+  --content-slot-margin-block-start: 2.4rem;
+  --content-slot-margin: var(--highlights-row-initial-item-offset);
+  --content-slot-background-color: var(--slate-00);
+  --content-slot-border: 1px solid var(--slate-06);
+  --content-slot-border-radius: 0.8rem;
+  --content-slot-outline: 1px solid var(--slate-02);
+
+  /* When using :highlight-title-baseline="true" */
+  &.highlight-title-baseline {
+    --highlight-title-height: 4rem; /* proportional value preferred */
+    --highlight-padding-block-start: 0;
+  }
+}
+\`\`\`
+        `,
+      },
+    },
+  },
+  render: (args: StoryArgs) => ({
+    components: { PageHeroHighlights },
+    setup() {
+      return useStorySetup(args);
+    },
+    template: `
+      <PageHeroHighlights v-bind="componentArgs" :style="bgStyles">
+        <template #header>
+          <div style="color: white; padding-block: 1.6rem;">
+            <p class="page-heading-1">Dashboard</p>
+            <p class="page-body-normal">Overview of your account activity and key metrics.</p>
+          </div>
+        </template>
+
+        <template #highlights>
+          <div style="border-radius: 12px; background: #1a1a2e; color: white; padding: 1.6rem;">
+            <p class="page-heading-2">Total Revenue</p>
+            <p class="page-body-normal">£24,500</p>
+          </div>
+          <div v-if="highlightCount >= 2" style="border-radius: 12px; background: #1a1a2e; color: white; padding: 1.6rem;">
+            <p class="page-heading-2">Active Users</p>
+            <p class="page-body-normal">1,284</p>
+          </div>
+          <div v-if="highlightCount >= 3" style="border-radius: 12px; background: #1a1a2e; color: white; padding: 1.6rem;">
+            <p class="page-heading-2">Open Tasks</p>
+            <p class="page-body-normal">37</p>
+          </div>
+        </template>
+
+        <template #content>
+          <pre style="padding: 1.6rem; font-size: 1.2rem; line-height: 1.6; overflow-x: auto;">/* ─── PageHeroHighlights CSS tokens ─────────────────────────────────
+   Set on .page-hero-highlights (or a scoped styleClassPassthrough class).
+   Update values as needed. Delete tokens you are not overriding.
+   ─────────────────────────────────────────────────────────────────── */
+.page-hero-highlights {
+
+  /* Header zone */
+  --header-row-background-colour: darkblue;
+
+  /* Highlights strip */
+  --highlights-row-item-gap: 1rem;
+  --highlights-row-initial-item-offset: 1.2rem;
+
+  /* Highlight cards */
+  --highlight-rows-gap: 1.2rem;
+  --highlight-title-height: 1fr; /* see: highlight-title-baseline prop */
+  --highlight-padding-block-start: 1.2rem;
+  --highlight-padding: 1.2rem;
+  --highlight-background-color: white;
+  --highlight-border: 1px solid black;
+  --highlight-border-radius: 8px;
+  --highlight-color: black;
+
+  /* Content zone */
+  --content-row-background-color: var(--slate-01); /* transparent */
+  --content-row-start-gap: 1.2rem;
+  --content-row-end-gap: 1.2rem;
+
+  /* Content slot decorative border */
+  --content-slot-margin-block-start: 2.4rem;
+  --content-slot-margin: var(--highlights-row-initial-item-offset);
+  --content-slot-background-color: var(--slate-00);
+  --content-slot-border: 1px solid var(--slate-06);
+  --content-slot-border-radius: 0.8rem;
+  --content-slot-outline: 1px solid var(--slate-02);
+
+  /* When using :highlight-title-baseline="true" */
+  &.highlight-title-baseline {
+    --highlight-title-height: 4rem; /* proportional value preferred */
+    --highlight-padding-block-start: 0;
+  }
+}</pre>
+        </template>
+      </PageHeroHighlights>
+    `,
+  }),
+};
+
+/** As section tag — root renders as a semantic section with aria-labelledby wired to the heading. */
+export const AsSectionTag: Story = {
+  name: "As section Tag",
+  args: { tag: "section" },
+  render: (args: StoryArgs) => ({
+    components: { PageHeroHighlights },
+    setup() {
+      return useStorySetup(args);
+    },
+    template: `
+      <PageHeroHighlights v-bind="componentArgs" :style="bgStyles">
+        <template #header="{ headingId }">
+          <h1 :id="headingId" class="page-heading-1">Dashboard</h1>
+          <p class="page-body-normal">Overview of your account activity and key metrics.</p>
+        </template>
+
+        <template #highlights>
+          <div style="border-radius: 12px; background: #1a1a2e; color: white; padding: 1.6rem;">
+            <p class="page-heading-2">Total Revenue</p>
+            <p class="page-body-normal">£24,500</p>
+          </div>
+          <div v-if="highlightCount >= 2" style="border-radius: 12px; background: #1a1a2e; color: white; padding: 1.6rem;">
+            <p class="page-heading-2">Active Users</p>
+            <p class="page-body-normal">1,284</p>
+          </div>
+          <div v-if="highlightCount >= 3" style="border-radius: 12px; background: #1a1a2e; color: white; padding: 1.6rem;">
+            <p class="page-heading-2">Open Tasks</p>
+            <p class="page-body-normal">37</p>
+          </div>
+        </template>
+
+        <template #content>
+          <p class="page-heading-2">Recent Activity</p>
+          <p class="page-body-normal">Your most recent transactions and events will appear here.</p>
+        </template>
+      </PageHeroHighlights>
+    `,
+  }),
+};
+
+/** Equal widths — highlights items share equal column widths via grid. */
+export const EqualWidthHighlights: Story = {
+  name: "Equal Width Highlights",
+  args: { highlightsEqualWidths: true },
+  render: (args: StoryArgs) => ({
+    components: { PageHeroHighlights },
+    setup() {
+      return useStorySetup(args);
+    },
+    template: `
+      <PageHeroHighlights v-bind="componentArgs" :style="bgStyles">
+        <template #header>
+          <p class="page-heading-1">Dashboard</p>
+          <p class="page-body-normal">Overview of your account activity and key metrics.</p>
+        </template>
+
+        <template #highlights>
+          <div style="border-radius: 12px; background: #1a1a2e; color: white; padding: 1.6rem;">
+            <p class="page-heading-2">Total Revenue</p>
+            <p class="page-body-normal">£24,500</p>
+          </div>
+          <div v-if="highlightCount >= 2" style="border-radius: 12px; background: #1a1a2e; color: white; padding: 1.6rem;">
+            <p class="page-heading-2">Active Users</p>
+            <p class="page-body-normal">1,284</p>
+          </div>
+          <div v-if="highlightCount >= 3" style="border-radius: 12px; background: #1a1a2e; color: white; padding: 1.6rem;">
+            <p class="page-heading-2">Open Tasks</p>
+            <p class="page-body-normal">37</p>
+          </div>
+        </template>
+
+        <template #content>
+          <p class="page-heading-2">Recent Activity</p>
+          <p class="page-body-normal">Your most recent transactions and events will appear here.</p>
+        </template>
+      </PageHeroHighlights>
+    `,
+  }),
+};
+
+/** Minimal — renders with no slot content to show the bare grid structure. */
+export const NoSlotContent: Story = {
+  name: "No Slot Content",
+  render: (args: StoryArgs) => ({
+    components: { PageHeroHighlights },
+    setup() {
+      return useStorySetup(args);
+    },
+    template: `<PageHeroHighlights v-bind="componentArgs" :style="bgStyles" />`,
+  }),
+};
+
+/** Max width centered — content column capped at 800px with equal growing gutters either side. */
+export const MaxWidthCentered: Story = {
+  name: "Max Width — Centered",
+  args: { maxWidth: "800px", contentAlign: "center" },
+  render: (args: StoryArgs) => ({
+    components: { PageHeroHighlights },
+    setup() {
+      return useStorySetup(args);
+    },
+    template: `
+      <PageHeroHighlights v-bind="componentArgs" :style="bgStyles">
+        <template #header>
+          <p class="page-heading-1">Dashboard</p>
+          <p class="page-body-normal">Content column is capped at 800px — gutters grow equally on both sides.</p>
+        </template>
+
+        <template #highlights>
+          <div style="border-radius: 12px; background: #1a1a2e; color: white; padding: 1.6rem;">
+            <p class="page-heading-2">Total Revenue</p>
+            <p class="page-body-normal">£24,500</p>
+          </div>
+          <div style="border-radius: 12px; background: #1a1a2e; color: white; padding: 1.6rem;">
+            <p class="page-heading-2">Active Users</p>
+            <p class="page-body-normal">1,284</p>
+          </div>
+          <div style="border-radius: 12px; background: #1a1a2e; color: white; padding: 1.6rem;">
+            <p class="page-heading-2">Open Tasks</p>
+            <p class="page-body-normal">37</p>
+          </div>
+        </template>
+
+        <template #content>
+          <p class="page-heading-2">Recent Activity</p>
+          <p class="page-body-normal">Your most recent transactions and events will appear here.</p>
+        </template>
+      </PageHeroHighlights>
+    `,
+  }),
+};
+
+/** Max width start — content column capped at 800px, pinned to the left with a fixed 16px gutter. */
+export const MaxWidthStart: Story = {
+  name: "Max Width — Start",
+  args: { maxWidth: "800px", contentAlign: "start" },
+  render: (args: StoryArgs) => ({
+    components: { PageHeroHighlights },
+    setup() {
+      return useStorySetup(args);
+    },
+    template: `
+      <PageHeroHighlights v-bind="componentArgs" :style="bgStyles">
+        <template #header>
+          <p class="page-heading-1">Dashboard</p>
+          <p class="page-body-normal">Content column is capped at 800px, aligned to the start — right side takes the remaining space.</p>
+        </template>
+
+        <template #highlights>
+          <div style="border-radius: 12px; background: #1a1a2e; color: white; padding: 1.6rem;">
+            <p class="page-heading-2">Total Revenue</p>
+            <p class="page-body-normal">£24,500</p>
+          </div>
+          <div style="border-radius: 12px; background: #1a1a2e; color: white; padding: 1.6rem;">
+            <p class="page-heading-2">Active Users</p>
+            <p class="page-body-normal">1,284</p>
+          </div>
+          <div style="border-radius: 12px; background: #1a1a2e; color: white; padding: 1.6rem;">
+            <p class="page-heading-2">Open Tasks</p>
+            <p class="page-body-normal">37</p>
+          </div>
+        </template>
+
+        <template #content>
+          <p class="page-heading-2">Recent Activity</p>
+          <p class="page-body-normal">Your most recent transactions and events will appear here.</p>
+        </template>
+      </PageHeroHighlights>
+    `,
+  }),
+};