srcdev-nuxt-components 9.5.3 → 9.5.5

package/app/components/03.organisms/google-reviews/GoogleReviews.vue

@@ -0,0 +1,275 @@
+<template>
+  <component
+    :is="tag"
+    v-if="filteredReviews.length"
+    class="google-reviews"
+    :class="elementClasses"
+    :aria-labelledby="hasHeading() ? headingId : undefined"
+    :aria-label="hasHeading() ? undefined : ariaLabel"
+  >
+    <div v-if="hasHeading() || showSummary" class="google-reviews-header">
+      <slot name="heading" :heading-id="headingId"></slot>
+      <div v-if="showSummary && data" class="google-reviews-summary">
+        <span class="google-reviews-summary-rating" aria-hidden="true">{{ data.rating.toFixed(1) }}</span>
+        <span class="google-reviews-stars" :style="{ '--_rating': data.rating }" aria-hidden="true">★★★★★</span>
+        <span class="sr-only">{{ formatLabel(ratingLabel, data.rating.toFixed(1)) }}</span>
+        <a v-if="data.mapsUri" :href="data.mapsUri" class="google-reviews-summary-link">
+          {{ formatLabel(totalLabel, data.totalReviews) }}
+        </a>
+        <span v-else class="google-reviews-summary-link">{{ formatLabel(totalLabel, data.totalReviews) }}</span>
+      </div>
+    </div>
+
+    <p v-if="minRating > 0" class="google-reviews-filter-notice">{{ formatLabel(filterNotice, minRating) }}</p>
+
+    <ul ref="listRef" class="google-reviews-list" tabindex="0" @scroll.passive="updateScrollState">
+      <li v-for="(review, index) in filteredReviews" :key="review.reviewUri ?? index" class="google-reviews-item">
+        <slot name="card" :review="review">
+          <GoogleReviewCard :review="review" :rating-label="ratingLabel" :read-more-label="readMoreLabel" />
+        </slot>
+      </li>
+    </ul>
+
+    <div class="google-reviews-footer">
+      <div v-if="isOverflowing" class="google-reviews-controls">
+        <InputButton
+          variant="secondary"
+          :button-text="prevLabel"
+          :readonly="atStart"
+          class="google-reviews-prev"
+          @click="scrollByCard(-1)"
+        >
+          <template #iconOnly>
+            <Icon :name="prevIcon" class="icon" />
+          </template>
+        </InputButton>
+        <InputButton
+          variant="secondary"
+          :button-text="nextLabel"
+          :readonly="atEnd"
+          class="google-reviews-next"
+          @click="scrollByCard(1)"
+        >
+          <template #iconOnly>
+            <Icon :name="nextIcon" class="icon" />
+          </template>
+        </InputButton>
+      </div>
+      <p class="google-reviews-attribution">{{ attributionText }}</p>
+    </div>
+  </component>
+</template>
+
+<script setup lang="ts">
+import type { GoogleReviewsData } from "~/types/components";
+
+interface Props {
+  data: GoogleReviewsData | null;
+  minRating?: number;
+  showSummary?: boolean;
+  tag?: "section" | "div";
+  ariaLabel?: string;
+  prevLabel?: string;
+  nextLabel?: string;
+  prevIcon?: string;
+  nextIcon?: string;
+  ratingLabel?: string;
+  totalLabel?: string;
+  readMoreLabel?: string;
+  filterNotice?: string;
+  attributionText?: string;
+  styleClassPassthrough?: string | string[];
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  minRating: 0,
+  showSummary: true,
+  tag: "section",
+  ariaLabel: "Google reviews",
+  prevLabel: "Previous reviews",
+  nextLabel: "Next reviews",
+  prevIcon: "ic:outline-keyboard-arrow-left",
+  nextIcon: "ic:outline-keyboard-arrow-right",
+  ratingLabel: "Rated {rating} out of 5",
+  totalLabel: "{count} reviews on Google",
+  readMoreLabel: "Read on Google",
+  filterNotice: "Showing reviews rated {rating} stars and above, in Google's order.",
+  attributionText: "Reviews from Google Maps",
+  styleClassPassthrough: () => [],
+});
+
+const slots = useSlots();
+const headingId = useId();
+const hasHeading = () => Boolean(slots.heading);
+
+const formatLabel = (label: string, value: string | number) =>
+  label.replace("{rating}", String(value)).replace("{count}", String(value));
+
+const filteredReviews = computed(() => (props.data?.reviews ?? []).filter((review) => review.rating >= props.minRating));
+
+const listRef = ref<HTMLUListElement | null>(null);
+const atStart = ref(true);
+const atEnd = ref(true);
+const isOverflowing = ref(false);
+
+const updateScrollState = () => {
+  const list = listRef.value;
+  if (!list) return;
+  const offset = Math.abs(list.scrollLeft);
+  isOverflowing.value = list.scrollWidth > list.clientWidth + 1;
+  atStart.value = offset <= 1;
+  atEnd.value = offset + list.clientWidth >= list.scrollWidth - 1;
+};
+
+const scrollByCard = (direction: 1 | -1) => {
+  const list = listRef.value;
+  const item = list?.querySelector<HTMLElement>(".google-reviews-item");
+  if (!list || !item) return;
+  const styles = getComputedStyle(list);
+  const step = item.offsetWidth + (parseFloat(styles.columnGap) || 0);
+  const sign = styles.direction === "rtl" ? -1 : 1;
+  list.scrollBy({ left: direction * step * sign });
+};
+
+let resizeObserver: ResizeObserver | null = null;
+
+onMounted(() => {
+  updateScrollState();
+  resizeObserver = new ResizeObserver(updateScrollState);
+  if (listRef.value) resizeObserver.observe(listRef.value);
+});
+
+onBeforeUnmount(() => resizeObserver?.disconnect());
+
+watch(filteredReviews, async () => {
+  await nextTick();
+  if (listRef.value) {
+    resizeObserver?.disconnect();
+    resizeObserver?.observe(listRef.value);
+  }
+  updateScrollState();
+});
+
+const { elementClasses, resetElementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
+
+watch(
+  () => props.styleClassPassthrough,
+  () => {
+    resetElementClasses(props.styleClassPassthrough);
+  }
+);
+</script>
+
+<style lang="css">
+@layer components {
+  .google-reviews {
+    display: grid;
+    gap: var(--google-reviews-gap, 1.6rem);
+    min-inline-size: 0;
+
+    .google-reviews-header {
+      display: grid;
+      gap: 0.8rem;
+    }
+
+    .google-reviews-summary {
+      display: flex;
+      flex-wrap: wrap;
+      align-items: center;
+      gap: 0.8rem;
+    }
+
+    .google-reviews-summary-rating {
+      font-size: var(--google-reviews-summary-rating-font-size, 2.4rem);
+      font-weight: 700;
+    }
+
+    .google-reviews-stars {
+      --_fill: clamp(0%, var(--_rating, 0) / 5 * 100%, 100%);
+
+      font-size: var(--google-reviews-star-size, 1.6rem);
+      letter-spacing: 0.1em;
+      background: linear-gradient(
+        90deg,
+        var(--google-reviews-star-colour, var(--amber-05)) var(--_fill),
+        var(--google-reviews-star-empty-colour, var(--slate-03)) var(--_fill)
+      );
+      -webkit-background-clip: text;
+      background-clip: text;
+      color: transparent;
+    }
+
+    .google-reviews-summary-link {
+      color: inherit;
+      overflow-wrap: anywhere;
+    }
+
+    .google-reviews-filter-notice,
+    .google-reviews-attribution {
+      margin: 0;
+      overflow-wrap: anywhere;
+      font-size: var(--google-reviews-meta-font-size, 1.4rem);
+      color: var(--google-reviews-meta-text-colour, inherit);
+    }
+
+    .google-reviews-list {
+      display: grid;
+      grid-auto-flow: column;
+      grid-auto-columns: var(--google-reviews-card-width, min(32rem, 85%));
+      grid-template-rows: repeat(5, auto);
+      column-gap: var(--google-reviews-gap, 1.6rem);
+      row-gap: 0;
+      margin: 0;
+      padding: 0 0 0.8rem;
+      list-style: none;
+      overflow-x: auto;
+      overscroll-behavior-inline: contain;
+      scrollbar-width: var(--google-reviews-scrollbar-width, thin);
+      scrollbar-color: var(--google-reviews-scrollbar-thumb-colour, var(--slate-04))
+        var(--google-reviews-scrollbar-track-colour, transparent);
+      scroll-snap-type: inline mandatory;
+      scroll-padding-inline: var(--google-reviews-scroll-padding, 0);
+      scroll-behavior: smooth;
+
+      &:focus-visible {
+        outline: var(--google-reviews-focus-outline-width, 2px) solid var(--google-reviews-focus-outline-colour, var(--theme-border-focus));
+        outline-offset: 2px;
+      }
+
+      @media (prefers-reduced-motion: reduce) {
+        scroll-behavior: auto;
+      }
+    }
+
+    /* Cards share the list's five rows (name, date, rating, text, link) so each section lines up across the row */
+    .google-reviews-item {
+      display: grid;
+      grid-row: span 5;
+      grid-template-rows: subgrid;
+      scroll-snap-align: start;
+      min-inline-size: 0;
+
+      > * {
+        grid-row: 1 / -1;
+      }
+
+      > .google-review-card {
+        grid-template-rows: subgrid;
+      }
+    }
+
+    .google-reviews-footer {
+      display: flex;
+      flex-wrap: wrap;
+      align-items: center;
+      justify-content: space-between;
+      gap: 1.2rem;
+    }
+
+    .google-reviews-controls {
+      display: flex;
+      gap: 0.8rem;
+    }
+  }
+}
+</style>

package/app/components/03.organisms/google-reviews/stories/GoogleReviews.stories.ts

@@ -0,0 +1,323 @@
+import { computed, ref } from "vue";
+import GoogleReviews from "../GoogleReviews.vue";
+import CanvasSwitcher from "../../../01.atoms/canvas-switcher/CanvasSwitcher.vue";
+import type { Meta, StoryObj } from "@nuxtjs/storybook";
+import type { GoogleReview, GoogleReviewsData, MediaCanvas } from "~/types/components";
+
+type LineClamp = "none" | "1" | "2" | "3" | "4" | "5" | "6" | "8";
+
+type StoryArgs = InstanceType<typeof GoogleReviews>["$props"] & {
+  authorLineClamp: LineClamp;
+  textLineClamp: LineClamp;
+};
+
+const lineClampOptions: LineClamp[] = ["none", "1", "2", "3", "4", "5", "6", "8"];
+
+// ─── Fixtures ─────────────────────────────────────────────────────────────────
+
+const review = (n: number, rating: number, text: string, photo = true): GoogleReview => ({
+  authorName: ["Priya Shah", "Tom Ellis", "Grace Okafor", "Liam Byrne", "Mei Chen"][n - 1] ?? `Reviewer ${n}`,
+  authorUri: `https://www.google.com/maps/contrib/${n}`,
+  authorPhotoUri: photo ? `https://picsum.photos/seed/reviewer-${n}/96/96` : undefined,
+  rating,
+  text,
+  relativeTime: `${n} weeks ago`,
+  publishTime: "2026-09-18T10:00:00Z",
+  reviewUri: `https://www.google.com/maps/review/${n}`,
+});
+
+const fiveReviews: GoogleReview[] = [
+  review(1, 5, "Friendly, professional and really listened to what I wanted. Couldn't be happier with the result."),
+  review(2, 5, "Booked last minute and they still fitted me in. Great atmosphere and a brilliant finish."),
+  review(3, 4, "Lovely salon and a great cut. Parking nearby is a bit tricky, but worth it."),
+  review(4, 5, "Third visit now and every one has been spot on. Highly recommend."),
+  review(5, 3, "Good service overall, though my appointment started twenty minutes late."),
+];
+
+const baseData: GoogleReviewsData = {
+  placeName: "Example Salon",
+  rating: 4.6,
+  totalReviews: 214,
+  mapsUri: "https://www.google.com/maps?cid=1",
+  reviews: fiveReviews,
+};
+
+const longText =
+  "I've been coming here for a couple of years now and wanted to finally write something.\n\nFrom the moment you walk in it's clear they care: the consultation is thorough, nobody rushes you, and they explain exactly what they're doing and why. My hair has never been in better condition, and the aftercare advice has made a real difference between visits. The team are warm and welcoming, the space is calm, and it genuinely feels like a treat rather than a chore. Can't recommend them highly enough.";
+
+// ─── Meta ─────────────────────────────────────────────────────────────────────
+
+const meta: Meta<StoryArgs> = {
+  title: "Organisms/Google Reviews",
+  component: GoogleReviews,
+  argTypes: {
+    authorLineClamp: {
+      control: "select",
+      options: lineClampOptions,
+      description: "Story control for --google-reviews-author-line-clamp (1 = single-line ellipsis)",
+      table: { category: "CSS tokens" },
+    },
+    textLineClamp: {
+      control: "select",
+      options: lineClampOptions,
+      description: "Story control for --google-reviews-text-line-clamp",
+      table: { category: "CSS tokens" },
+    },
+    data: { control: "object", description: "GoogleReviewsData, usually from useGoogleReviews()" },
+    minRating: { control: { type: "range", min: 0, max: 5, step: 1 }, description: "Hide reviews below this rating; shows the filter notice" },
+    showSummary: { control: "boolean", description: "Overall rating, stars and total count" },
+    tag: { control: "select", options: ["section", "div"] },
+    ariaLabel: { control: "text" },
+    prevLabel: { control: "text" },
+    nextLabel: { control: "text" },
+    ratingLabel: { control: "text", description: "{rating} is replaced" },
+    totalLabel: { control: "text", description: "{count} is replaced" },
+    readMoreLabel: { control: "text" },
+    filterNotice: { control: "text", description: "{rating} is replaced" },
+    attributionText: { control: "text", description: "Must keep the words \"Google Maps\"" },
+  },
+  args: {
+    data: baseData,
+    minRating: 0,
+    showSummary: true,
+    tag: "section",
+    authorLineClamp: "2",
+    textLineClamp: "5",
+  },
+  decorators: [
+    (story, context) => ({
+      components: { story, CanvasSwitcher },
+      setup() {
+        const canvasName = ref<MediaCanvas>(context.parameters.initialCanvas ?? "fullWidthCanvas");
+        return { canvasName };
+      },
+      template: `
+        <div style="padding: 1.2rem 1.6rem; border-block-end: 1px solid currentColor;">
+          <CanvasSwitcher v-model:canvas-name="canvasName" />
+        </div>
+        <div :class="canvasName" style="margin-inline: auto; padding: 2rem; outline: 1px dashed currentColor;">
+          <story />
+        </div>
+      `,
+    }),
+  ],
+  parameters: {
+    layout: "fullscreen",
+    docs: {
+      description: {
+        component:
+          "Google reviews for one place, shown as a single horizontally scrolling row with prev/next buttons. Data comes from the layer's `/api/google-reviews` route via `useGoogleReviews()`; these stories use mock data.",
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<StoryArgs>;
+
+function useStorySetup(args: StoryArgs) {
+  const componentArgs = computed(() => {
+    const { authorLineClamp: _authorLineClamp, textLineClamp: _textLineClamp, ...rest } = args;
+    return rest;
+  });
+  const tokenStyles = computed(() => ({
+    "--google-reviews-author-line-clamp": args.authorLineClamp,
+    "--google-reviews-text-line-clamp": args.textLineClamp,
+  }));
+  return { args, componentArgs, tokenStyles };
+}
+
+const render = (args: StoryArgs) => ({
+  components: { GoogleReviews },
+  setup() {
+    return useStorySetup(args);
+  },
+  template: `<div :style="tokenStyles"><GoogleReviews v-bind="componentArgs" /></div>`,
+});
+
+// ─── Stories ──────────────────────────────────────────────────────────────────
+
+export const Default: Story = {
+  render,
+  parameters: {
+    docs: { description: { story: "Five reviews (Google's maximum). Use the canvas switcher above to try narrower widths." } },
+  },
+};
+
+export const FewReviews: Story = {
+  name: "Few Reviews (All Fit)",
+  args: { data: { ...baseData, reviews: fiveReviews.slice(0, 2) } },
+  render,
+  parameters: {
+    docs: { description: { story: "When every card fits, the prev/next buttons are hidden." } },
+  },
+};
+
+export const NarrowContainer: Story = {
+  render,
+  parameters: {
+    initialCanvas: "mobileCanvas",
+    docs: {
+      description: {
+        story:
+          "Phone-width container: the row stays a single row and scrolls with snapping. Check keyboard scrolling (focus the row, use the arrow keys) and that the buttons disable at each end.",
+      },
+    },
+  },
+};
+
+export const LongText: Story = {
+  args: { data: { ...baseData, reviews: [review(1, 5, longText), ...fiveReviews.slice(1)] } },
+  render,
+  parameters: {
+    docs: { description: { story: "Long reviews are clamped (`--google-reviews-text-line-clamp`, default 5 lines) with a link to read the rest on Google." } },
+  },
+};
+
+export const NoAvatars: Story = {
+  args: { data: { ...baseData, reviews: fiveReviews.map((r) => ({ ...r, authorPhotoUri: undefined })) } },
+  render,
+  parameters: {
+    docs: { description: { story: "Reviewers without a photo show their initials." } },
+  },
+};
+
+export const Filtered: Story = {
+  args: { minRating: 4 },
+  render,
+  parameters: {
+    docs: { description: { story: "`minRating` hides lower-rated reviews and shows the filter notice Google's terms require." } },
+  },
+};
+
+export const WithHeading: Story = {
+  render: (args: StoryArgs) => ({
+    components: { GoogleReviews },
+    setup() {
+      return useStorySetup(args);
+    },
+    template: `
+      <div :style="tokenStyles">
+        <GoogleReviews v-bind="componentArgs">
+          <template #heading="{ headingId }">
+            <h2 :id="headingId" style="margin:0">What clients say</h2>
+          </template>
+        </GoogleReviews>
+      </div>
+    `,
+  }),
+  parameters: {
+    docs: { description: { story: "The `heading` slot receives `headingId`; binding it labels the section by the heading instead of `ariaLabel`." } },
+  },
+};
+
+export const Themed: Story = {
+  args: { textLineClamp: "3" },
+  render: (args: StoryArgs) => ({
+    components: { GoogleReviews },
+    setup() {
+      return useStorySetup(args);
+    },
+    template: `
+      <div
+        :style="[tokenStyles, {
+          '--google-reviews-card-width': 'min(26rem, 80%)',
+          '--google-reviews-card-surface': 'var(--amber-01)',
+          '--google-reviews-card-text-colour': 'var(--amber-10)',
+          '--google-reviews-card-border-colour': 'var(--amber-03)',
+          '--google-reviews-card-border-radius': '2rem',
+          '--google-reviews-star-colour': 'var(--amber-07)',
+        }]"
+      >
+        <GoogleReviews v-bind="componentArgs" />
+      </div>
+    `,
+  }),
+  parameters: {
+    docs: { description: { story: "Card width, colours, radius, star colour and line clamp set through public tokens on a wrapper." } },
+  },
+};
+
+// ─── Stress test ──────────────────────────────────────────────────────────────
+
+const stressReviews: GoogleReview[] = [
+  {
+    authorName: "Bartholomew Maximilian Montgomery-Fitzgerald-Worthington-Smythe the Third of Little Snoring",
+    authorUri: "https://www.google.com/maps/contrib/1",
+    authorPhotoUri: "https://picsum.photos/seed/reviewer-1/96/96",
+    rating: 5,
+    text: `${"Absolutely wonderful. ".repeat(60)}\n\n\n\nStill going after four blank lines.`,
+    relativeTime: "11 years, 4 months and 3 days ago (edited)",
+    publishTime: "2015-06-01T10:00:00Z",
+    reviewUri: "https://www.google.com/maps/review/1",
+  },
+  {
+    authorName: "Pneumonoultramicroscopicsilicovolcanoconiosisfanaccountnospaces",
+    rating: 1,
+    text: `Sooooooo${"o".repeat(200)} good. See https://example.com/a/very/long/path/that/never/breaks/${"segment".repeat(20)}`,
+    relativeTime: "a week ago",
+    publishTime: "",
+  },
+  {
+    authorName: "🌸✨ Rosa 🌸",
+    authorPhotoUri: "https://example.invalid/expired-photo.jpg",
+    rating: 4.95,
+    text: "Emoji everywhere 💇‍♀️💅🏽🔥🔥🔥 and <script>alert('xss')</script> rendered as text, plus &amp; entities.",
+    relativeTime: "yesterday",
+    publishTime: "2026-10-02T10:00:00Z",
+    reviewUri: "https://www.google.com/maps/review/3",
+  },
+  {
+    authorName: "مريم الحسيني",
+    rating: 3,
+    text: "خدمة رائعة وفريق ودود جداً. سأعود بالتأكيد! Mixed with English mid-sentence.",
+    relativeTime: "منذ أسبوعين",
+    publishTime: "2026-09-18T10:00:00Z",
+    reviewUri: "https://www.google.com/maps/review/4",
+  },
+  {
+    authorName: "X",
+    rating: 0,
+    text: "",
+    relativeTime: "",
+    publishTime: "",
+  },
+  {
+    authorName: "",
+    rating: 7,
+    text: ".",
+    relativeTime: "just now",
+    publishTime: "2026-10-03T10:00:00Z",
+    reviewUri: "https://www.google.com/maps/review/6",
+  },
+];
+
+export const StressTest: Story = {
+  name: "Stress Test (Worst-Case Data)",
+  args: {
+    data: {
+      placeName: "A Place Name That Goes On And On ".repeat(5),
+      rating: 4.95,
+      totalReviews: 123456789,
+      mapsUri: "https://www.google.com/maps?cid=1",
+      reviews: stressReviews,
+    },
+    ratingLabel: "Durchschnittliche Bewertung von {rating} von insgesamt fünf möglichen Sternen",
+    totalLabel: "{count} Rezensionen auf Google ansehen und weitere Bewertungen unserer Kundschaft lesen",
+    readMoreLabel: "Vollständige Rezension auf Google Maps weiterlesen",
+    attributionText: "Rezensionen bereitgestellt von Google Maps, Inhalte von Dritten, ohne Gewähr für Richtigkeit",
+  },
+  render,
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Deliberately hostile data to find breakage: very long and unbroken author names and text, " +
+          "blank lines, an unbroken URL (reviewer names are clamped to 2 lines, review text to 5), emoji (including in initials), HTML-like text (must render as text), " +
+          "right-to-left Arabic, empty name/text/date, a broken photo URL, out-of-range ratings (0, 4.95, 7), " +
+          "a nine-digit total and long German copy for every label. Check at every canvas width: nothing " +
+          "should overflow its card, cards stay one row, and the footer wraps cleanly.",
+      },
+    },
+  },
+};