srcdev-nuxt-components 9.5.3 → 9.5.4

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.",
+      },
+    },
+  },
+};

package/app/components/03.organisms/google-reviews/tests/GoogleReviewCard.spec.ts

@@ -0,0 +1,104 @@
+import { describe, it, expect } from "vitest";
+import { mountSuspended } from "@nuxt/test-utils/runtime";
+import GoogleReviewCard from "../GoogleReviewCard.vue";
+import type { GoogleReview } from "~/types/components";
+
+const review: GoogleReview = {
+  authorName: "Alex Doe",
+  authorUri: "https://maps.google.com/contrib/1",
+  authorPhotoUri: "https://lh3.googleusercontent.com/a",
+  rating: 4,
+  text: "Lovely visit, would come again.",
+  relativeTime: "2 weeks ago",
+  publishTime: "2026-09-18T10:00:00Z",
+  reviewUri: "https://maps.google.com/review/1",
+};
+
+const mountCard = (props: Partial<InstanceType<typeof GoogleReviewCard>["$props"]> = {}) =>
+  mountSuspended(GoogleReviewCard, { props: { review, ...props } });
+
+describe("GoogleReviewCard", () => {
+  it("mounts without error", async () => {
+    const wrapper = await mountCard();
+    expect(wrapper.vm).toBeTruthy();
+  });
+
+  it("renders correct HTML structure", async () => {
+    const wrapper = await mountCard();
+    expect(wrapper.html()).toMatchSnapshot();
+  });
+
+  it("renders as an article by default and a div when tag is div", async () => {
+    expect((await mountCard()).element.tagName).toBe("ARTICLE");
+    expect((await mountCard({ tag: "div" })).element.tagName).toBe("DIV");
+  });
+
+  it("links the author name to their profile", async () => {
+    const wrapper = await mountCard();
+    const author = wrapper.find(".google-review-card-author-name");
+    expect(author.element.tagName).toBe("A");
+    expect(author.attributes("href")).toBe(review.authorUri);
+    expect(author.text()).toBe("Alex Doe");
+  });
+
+  it("shows the author name as plain text when there is no profile link", async () => {
+    const wrapper = await mountCard({ review: { ...review, authorUri: undefined } });
+    expect(wrapper.find(".google-review-card-author-name").element.tagName).toBe("SPAN");
+  });
+
+  it("hides the avatar from screen readers, since the name is already read out", async () => {
+    const avatar = (await mountCard()).find(".display-avatar");
+    expect(avatar.attributes("aria-hidden")).toBe("true");
+    expect(avatar.find(".sr-only").exists()).toBe(false);
+  });
+
+  it("shows the author photo, or initials when there is no photo", async () => {
+    expect((await mountCard()).find(".display-avatar img").exists()).toBe(true);
+    const noPhoto = await mountCard({ review: { ...review, authorPhotoUri: undefined } });
+    expect(noPhoto.find(".display-avatar img").exists()).toBe(false);
+    expect(noPhoto.find(".display-avatar").text()).toContain("AD");
+  });
+
+  it("takes whole characters for initials when a name starts with an emoji", async () => {
+    const wrapper = await mountCard({ review: { ...review, authorName: "🌸 Rosa Lee", authorPhotoUri: undefined } });
+    expect(wrapper.find(".display-avatar").text()).toContain("🌸R");
+  });
+
+  it("hides the stars from screen readers and announces the rating as text", async () => {
+    const wrapper = await mountCard();
+    expect(wrapper.find(".google-review-card-stars").attributes("aria-hidden")).toBe("true");
+    expect(wrapper.find(".google-review-card-rating .sr-only").text()).toBe("Rated 4 out of 5");
+  });
+
+  it("shows the relative date with a machine-readable datetime", async () => {
+    const time = (await mountCard()).find("time");
+    expect(time.text()).toBe("2 weeks ago");
+    expect(time.attributes("datetime")).toBe(review.publishTime);
+  });
+
+  it("links to the full review on Google, described by the author name", async () => {
+    const wrapper = await mountCard();
+    const link = wrapper.find(".google-review-card-link");
+    expect(link.attributes("href")).toBe(review.reviewUri);
+    expect(link.text()).toBe("Read on Google");
+    const authorId = wrapper.find(".google-review-card-author-name").attributes("id");
+    expect(authorId).toBeTruthy();
+    expect(link.attributes("aria-describedby")).toBe(authorId);
+  });
+
+  it("omits the read link when there is no review link", async () => {
+    const wrapper = await mountCard({ review: { ...review, reviewUri: undefined } });
+    expect(wrapper.find(".google-review-card-link").exists()).toBe(false);
+  });
+
+  it("uses custom label text", async () => {
+    const wrapper = await mountCard({ ratingLabel: "{rating} étoiles sur 5", readMoreLabel: "Lire sur Google" });
+    expect(wrapper.find(".sr-only").text()).toBe("4 étoiles sur 5");
+    expect(wrapper.find(".google-review-card-link").text()).toBe("Lire sur Google");
+  });
+
+  it("applies styleClassPassthrough classes", async () => {
+    const wrapper = await mountCard({ styleClassPassthrough: ["custom-card"] });
+    expect(wrapper.classes()).toContain("custom-card");
+  });
+});

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

@@ -0,0 +1,232 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { mountSuspended } from "@nuxt/test-utils/runtime";
+import { defineComponent, h, nextTick, ref } from "vue";
+import GoogleReviews from "../GoogleReviews.vue";
+import type { GoogleReviewsData } from "~/types/components";
+
+const makeReview = (n: number, rating: number) => ({
+  authorName: `Reviewer ${n}`,
+  authorUri: `https://maps.google.com/contrib/${n}`,
+  rating,
+  text: `Review text ${n}`,
+  relativeTime: `${n} weeks ago`,
+  publishTime: "2026-09-18T10:00:00Z",
+  reviewUri: `https://maps.google.com/review/${n}`,
+});
+
+const data: GoogleReviewsData = {
+  placeName: "Test Salon",
+  rating: 4.66,
+  totalReviews: 128,
+  mapsUri: "https://maps.google.com/?cid=1",
+  reviews: [makeReview(1, 5), makeReview(2, 4), makeReview(3, 3)],
+};
+
+const mountReviews = (props: Partial<InstanceType<typeof GoogleReviews>["$props"]> = {}, slots = {}) =>
+  mountSuspended(GoogleReviews, { props: { data, ...props }, slots });
+
+const setScrollMetrics = (el: Element, metrics: { scrollWidth: number; clientWidth: number; scrollLeft: number }) => {
+  for (const [key, value] of Object.entries(metrics)) {
+    Object.defineProperty(el, key, { configurable: true, value });
+  }
+};
+
+beforeEach(() => {
+  vi.stubGlobal(
+    "ResizeObserver",
+    vi.fn(function () {
+      return { observe: vi.fn(), unobserve: vi.fn(), disconnect: vi.fn() };
+    })
+  );
+});
+
+describe("GoogleReviews", () => {
+  it("mounts without error", async () => {
+    const wrapper = await mountReviews();
+    expect(wrapper.vm).toBeTruthy();
+  });
+
+  it("renders correct HTML structure", async () => {
+    const wrapper = await mountReviews();
+    expect(wrapper.html()).toMatchSnapshot();
+  });
+
+  // ─── Empty states ───────────────────────────────────────────────────────
+
+  it("renders nothing when data is null", async () => {
+    const wrapper = await mountReviews({ data: null });
+    expect(wrapper.find(".google-reviews").exists()).toBe(false);
+  });
+
+  it("renders nothing when every review is filtered out", async () => {
+    const wrapper = await mountReviews({ minRating: 5, data: { ...data, reviews: [makeReview(1, 4)] } });
+    expect(wrapper.find(".google-reviews").exists()).toBe(false);
+  });
+
+  // ─── Summary and attribution ───────────────────────────────────────────
+
+  it("shows the overall rating, total count and a link to the Google Maps listing", async () => {
+    const wrapper = await mountReviews();
+    expect(wrapper.find(".google-reviews-summary-rating").text()).toBe("4.7");
+    expect(wrapper.find(".google-reviews-summary .sr-only").text()).toBe("Rated 4.7 out of 5");
+    const link = wrapper.find("a.google-reviews-summary-link");
+    expect(link.attributes("href")).toBe(data.mapsUri);
+    expect(link.text()).toBe("128 reviews on Google");
+  });
+
+  it("hides the summary when showSummary is false", async () => {
+    const wrapper = await mountReviews({ showSummary: false });
+    expect(wrapper.find(".google-reviews-summary").exists()).toBe(false);
+  });
+
+  it("always renders the Google Maps attribution", async () => {
+    const wrapper = await mountReviews({ showSummary: false });
+    expect(wrapper.find(".google-reviews-attribution").text()).toBe("Reviews from Google Maps");
+  });
+
+  // ─── Semantics ─────────────────────────────────────────────────────────
+
+  it("is a labelled section containing a list of reviews", async () => {
+    const wrapper = await mountReviews();
+    expect(wrapper.element.tagName).toBe("SECTION");
+    expect(wrapper.attributes("aria-label")).toBe("Google reviews");
+    expect(wrapper.find("ul.google-reviews-list").exists()).toBe(true);
+    expect(wrapper.findAll("li.google-reviews-item")).toHaveLength(3);
+  });
+
+  it("labels the section by the heading slot when one is given", async () => {
+    const wrapper = await mountReviews(
+      {},
+      { heading: ({ headingId }: { headingId: string }) => h("h2", { id: headingId }, "What clients say") }
+    );
+    const heading = wrapper.find("h2");
+    expect(wrapper.attributes("aria-labelledby")).toBe(heading.attributes("id"));
+    expect(wrapper.attributes("aria-label")).toBeUndefined();
+  });
+
+  it("switches between aria-label and aria-labelledby when the heading slot is toggled after mount", async () => {
+    const showHeading = ref(false);
+    const Host = defineComponent({
+      setup() {
+        return () =>
+          h(GoogleReviews, { data }, showHeading.value
+            ? { heading: ({ headingId }: { headingId: string }) => h("h2", { id: headingId }, "Reviews") }
+            : {});
+      },
+    });
+    const wrapper = await mountSuspended(Host);
+    const root = () => wrapper.find(".google-reviews");
+    expect(root().attributes("aria-label")).toBe("Google reviews");
+
+    showHeading.value = true;
+    await nextTick();
+    expect(root().attributes("aria-labelledby")).toBe(wrapper.find("h2").attributes("id"));
+    expect(root().attributes("aria-label")).toBeUndefined();
+
+    showHeading.value = false;
+    await nextTick();
+    expect(root().attributes("aria-labelledby")).toBeUndefined();
+    expect(root().attributes("aria-label")).toBe("Google reviews");
+  });
+
+  it("makes the scroll area keyboard focusable", async () => {
+    const wrapper = await mountReviews();
+    expect(wrapper.find(".google-reviews-list").attributes("tabindex")).toBe("0");
+  });
+
+  // ─── Filtering ─────────────────────────────────────────────────────────
+
+  it("hides lower-rated reviews and shows the filter notice when minRating is set", async () => {
+    const wrapper = await mountReviews({ minRating: 4 });
+    expect(wrapper.findAll(".google-reviews-item")).toHaveLength(2);
+    expect(wrapper.find(".google-reviews-filter-notice").text()).toBe(
+      "Showing reviews rated 4 stars and above, in Google's order."
+    );
+  });
+
+  it("shows no filter notice when there is no filter", async () => {
+    const wrapper = await mountReviews();
+    expect(wrapper.find(".google-reviews-filter-notice").exists()).toBe(false);
+  });
+
+  // ─── Prev/next controls ────────────────────────────────────────────────
+
+  it("hides the prev/next buttons when every card fits", async () => {
+    const wrapper = await mountReviews();
+    expect(wrapper.find(".google-reviews-controls").exists()).toBe(false);
+  });
+
+  it("shows the prev/next buttons when cards overflow, disabling each at its end", async () => {
+    const wrapper = await mountReviews();
+    const list = wrapper.find(".google-reviews-list");
+
+    setScrollMetrics(list.element, { scrollWidth: 1000, clientWidth: 400, scrollLeft: 0 });
+    await list.trigger("scroll");
+    expect(wrapper.find(".google-reviews-prev").attributes("aria-disabled")).toBe("true");
+    expect(wrapper.find(".google-reviews-next").attributes("aria-disabled")).toBe("false");
+
+    setScrollMetrics(list.element, { scrollWidth: 1000, clientWidth: 400, scrollLeft: 600 });
+    await list.trigger("scroll");
+    expect(wrapper.find(".google-reviews-prev").attributes("aria-disabled")).toBe("false");
+    expect(wrapper.find(".google-reviews-next").attributes("aria-disabled")).toBe("true");
+  });
+
+  it("scrolls by one card when prev/next is pressed", async () => {
+    const wrapper = await mountReviews();
+    const list = wrapper.find(".google-reviews-list");
+    const scrollBy = vi.fn();
+    (list.element as HTMLElement).scrollBy = scrollBy;
+    Object.defineProperty(wrapper.find(".google-reviews-item").element, "offsetWidth", { configurable: true, value: 300 });
+
+    setScrollMetrics(list.element, { scrollWidth: 1000, clientWidth: 400, scrollLeft: 300 });
+    await list.trigger("scroll");
+
+    await wrapper.find(".google-reviews-next").trigger("click");
+    expect(scrollBy).toHaveBeenLastCalledWith({ left: 300 });
+    await wrapper.find(".google-reviews-prev").trigger("click");
+    expect(scrollBy).toHaveBeenLastCalledWith({ left: -300 });
+  });
+
+  it("gives the icon-only buttons accessible names", async () => {
+    const wrapper = await mountReviews();
+    const list = wrapper.find(".google-reviews-list");
+    setScrollMetrics(list.element, { scrollWidth: 1000, clientWidth: 400, scrollLeft: 0 });
+    await list.trigger("scroll");
+    expect(wrapper.find(".google-reviews-prev .button-text").text()).toBe("Previous reviews");
+    expect(wrapper.find(".google-reviews-next .button-text").text()).toBe("Next reviews");
+  });
+
+  // ─── Copy and slots ────────────────────────────────────────────────────
+
+  it("uses custom label text throughout", async () => {
+    const wrapper = await mountReviews({
+      minRating: 4,
+      ariaLabel: "Avis Google",
+      ratingLabel: "{rating} sur 5",
+      totalLabel: "{count} avis sur Google",
+      readMoreLabel: "Lire sur Google",
+      filterNotice: "Avis de {rating} étoiles et plus.",
+      attributionText: "Avis de Google Maps",
+    });
+    expect(wrapper.attributes("aria-label")).toBe("Avis Google");
+    expect(wrapper.find(".google-reviews-summary .sr-only").text()).toBe("4.7 sur 5");
+    expect(wrapper.find(".google-reviews-summary-link").text()).toBe("128 avis sur Google");
+    expect(wrapper.find(".google-review-card-link").text()).toBe("Lire sur Google");
+    expect(wrapper.find(".google-reviews-filter-notice").text()).toBe("Avis de 4 étoiles et plus.");
+    expect(wrapper.find(".google-reviews-attribution").text()).toBe("Avis de Google Maps");
+  });
+
+  it("replaces each card with the card slot", async () => {
+    const wrapper = await mountReviews(
+      {},
+      { card: ({ review }: { review: { authorName: string } }) => h("div", { class: "custom-card" }, review.authorName) }
+    );
+    expect(wrapper.findAll(".custom-card")).toHaveLength(3);
+    expect(wrapper.find(".google-review-card").exists()).toBe(false);
+  });
+
+  it("applies styleClassPassthrough classes", async () => {
+    const wrapper = await mountReviews({ styleClassPassthrough: ["custom-reviews"] });
+    expect(wrapper.classes()).toContain("custom-reviews");
+  });
+});

package/app/components/03.organisms/google-reviews/tests/__snapshots__/GoogleReviewCard.spec.ts.snap

@@ -0,0 +1,9 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`GoogleReviewCard > renders correct HTML structure 1`] = `
+"<article class="google-review-card">
+  <div class="google-review-card-author"><span class="display-avatar md" aria-hidden="true"><img data-nuxt-img="" srcset="/_ipx/_/https://lh3.googleusercontent.com/a 1x, /_ipx/_/https://lh3.googleusercontent.com/a 2x" alt="" class="display-avatar-image" src="/_ipx/_/https://lh3.googleusercontent.com/a"></span><a id="v-0-0" href="https://maps.google.com/contrib/1" class="google-review-card-author-name">Alex Doe</a><time datetime="2026-09-18T10:00:00Z" class="google-review-card-time">2 weeks ago</time></div>
+  <div class="google-review-card-rating"><span class="google-review-card-stars" style="--_rating: 4;" aria-hidden="true">★★★★★</span><span class="sr-only">Rated 4 out of 5</span></div>
+  <p class="google-review-card-text">Lovely visit, would come again.</p><a href="https://maps.google.com/review/1" aria-describedby="v-0-0" class="google-review-card-link">Read on Google</a>
+</article>"
+`;