srcdev-nuxt-components 9.5.3 → 9.5.4

package/app/components/03.organisms/google-reviews/CONSUMER-STYLING.md

@@ -0,0 +1,110 @@
+# GoogleReviews — Consumer Styling Guide
+
+`GoogleReviews` shows a place's Google reviews as a single horizontally scrolling row of
+`GoogleReviewCard`s, with a summary above and prev/next buttons plus the Google Maps attribution
+below. Both components read the same `--google-reviews-*` tokens, so setting them on an ancestor
+styles a standalone `GoogleReviewCard` too.
+
+## Public token API
+
+### Row (`GoogleReviews`)
+
+| Token | Default | Controls |
+|---|---|---|
+| `--google-reviews-gap` | `1.6rem` | Space between header, row and footer, and between cards |
+| `--google-reviews-card-width` | `min(32rem, 85%)` | Width of each card in the row |
+| `--google-reviews-scroll-padding` | `0` | Snap inset, e.g. to line cards up with a page gutter |
+| `--google-reviews-scrollbar-width` | `thin` | Row scrollbar: `auto`, `thin` or `none` (`none` hides it; the buttons and touch/keyboard scrolling still work) |
+| `--google-reviews-scrollbar-thumb-colour` | `var(--slate-04)` | Scrollbar thumb |
+| `--google-reviews-scrollbar-track-colour` | `transparent` | Scrollbar track |
+| `--google-reviews-summary-rating-font-size` | `2.4rem` | Overall rating number |
+| `--google-reviews-focus-outline-width` | `2px` | Focus ring on the scrollable row |
+| `--google-reviews-focus-outline-colour` | `var(--theme-border-focus)` | Focus ring colour |
+
+### Card (`GoogleReviewCard`)
+
+| Token | Default | Controls |
+|---|---|---|
+| `--google-reviews-card-gap` | `1.2rem` | Space between author, stars, text and link |
+| `--google-reviews-card-padding` | `2rem` | Card padding |
+| `--google-reviews-card-border-width` | `1px` | Card border width |
+| `--google-reviews-card-border-colour` | `transparent` | Card border colour |
+| `--google-reviews-card-border-radius` | `0.8rem` | Card corner radius |
+| `--google-reviews-card-surface` | `var(--theme-surface-subtle)` | Card background |
+| `--google-reviews-card-text-colour` | `var(--theme-text)` | Card text colour |
+| `--google-reviews-avatar-surface` | `var(--theme-surface)` | Initials avatar background (shown when a reviewer has no photo) |
+| `--google-reviews-avatar-text-colour` | `var(--theme-on-surface)` | Initials colour |
+| `--google-reviews-author-font-weight` | `600` | Reviewer name weight |
+| `--google-reviews-author-line-clamp` | `2` | Lines of reviewer name before it's cut off with an ellipsis (`1` for single-line ellipsis, `none` to show it all) |
+| `--google-reviews-text-line-height` | `1.5` | Review text line height |
+| `--google-reviews-text-line-clamp` | `5` | Lines of review text before it's cut off with an ellipsis (`none` to show it all) |
+| `--google-reviews-link-colour` | `inherit` | "Read on Google" link colour |
+
+### Shared
+
+| Token | Default | Controls |
+|---|---|---|
+| `--google-reviews-star-size` | `1.6rem` | Star font size (summary and cards) |
+| `--google-reviews-star-colour` | `var(--amber-05)` | Filled star colour |
+| `--google-reviews-star-empty-colour` | `var(--slate-03)` | Unfilled star colour |
+| `--google-reviews-meta-font-size` | `1.4rem` | Date, link, filter notice and attribution |
+| `--google-reviews-meta-text-colour` | `inherit` | Colour of the same |
+
+Private tokens (not public API): `--_rating` (set inline from the review's rating) and `--_fill`
+(the star fill percentage derived from it).
+
+## State hooks
+
+- No `data-*` state. The prev/next buttons are `InputButton`s with `readonly`/`aria-disabled` at
+  either end of the row, styled by `InputButton`'s own tokens.
+- Inner classes: `.google-reviews-header`, `.google-reviews-summary`,
+  `.google-reviews-summary-rating`, `.google-reviews-stars`, `.google-reviews-summary-link`,
+  `.google-reviews-filter-notice`, `.google-reviews-list`, `.google-reviews-item`,
+  `.google-reviews-footer`, `.google-reviews-controls`, `.google-reviews-prev`,
+  `.google-reviews-next`, `.google-reviews-attribution`.
+- Card classes: `.google-review-card`, `.google-review-card-author`,
+  `.google-review-card-author-name`,
+  `.google-review-card-time`, `.google-review-card-rating`, `.google-review-card-stars`,
+  `.google-review-card-text`, `.google-review-card-link`.
+
+## Row alignment
+
+Inside `GoogleReviews`, every card spans the list's five shared rows (name, date, rating, text,
+link) through `grid-template-rows: subgrid`, so each section lines up across the whole row
+however tall its neighbours are: a one-line name's date sits level with a two-line name's. The
+author block is itself a subgrid over the name and date rows, with the avatar spanning both.
+Sections sit in fixed rows, so a card with no date, text or link leaves the gap rather than
+shifting up. Spacing between sections is a top margin (`--google-reviews-card-gap`), not a grid
+gap, so the name and date stay close together. A standalone `GoogleReviewCard` uses
+`auto auto auto 1fr auto` instead (link pinned to the bottom). Content from the `card` slot
+spans all five rows as one block. Browsers
+without subgrid fall back to equal-height cards that aren't aligned section by section.
+
+## Stars
+
+Stars are the text `★★★★★` filled with a hard-stop gradient clipped to the text, so fractional
+ratings (4.6) show a partly filled star. They're `aria-hidden`; the rating is read out from
+visually hidden text (`ratingLabel`).
+
+## Local overrides
+
+Set the tokens above on an element you own (a page or section class, or a class added with
+`:style-class-passthrough`): they inherit down into the component. Keep the block **unlayered** (no
+`@layer` wrapper) so it beats the library's `@layer components`. If your own file uses
+`<style scoped>`, tokens set on your element still work, but selectors that reach inside the component need
+`:deep()`. Patterns and examples: `.claude/skills/component-local-style-override.md`.
+
+**Caveat:** the card re-declares `--display-avatar-background` and `--display-avatar-text-colour` on its
+avatar, so setting those `DisplayAvatar` tokens on an ancestor has no effect here. Use
+`--google-reviews-avatar-surface` and `--google-reviews-avatar-text-colour` instead.
+
+## Class passthrough
+
+`style-class-passthrough` adds classes to the root (`.google-reviews` or `.google-review-card`).
+`GoogleReviews` doesn't forward it to the cards it renders; set tokens on the root instead, or
+use the `card` slot to render `GoogleReviewCard` yourself with its own passthrough.
+
+## Notes
+
+Google's terms require the attribution text to stay visible and readable. Restyle it, but don't
+hide it, and keep the words "Google Maps" in `attributionText` when translating.

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

@@ -0,0 +1,161 @@
+<template>
+  <component :is="tag" class="google-review-card" :class="elementClasses">
+    <div class="google-review-card-author">
+      <DisplayAvatar :src="review.authorPhotoUri" :text="initials" size="md" aria-hidden="true" />
+      <a v-if="review.authorUri" :id="authorId" :href="review.authorUri" class="google-review-card-author-name">
+        {{ review.authorName }}
+      </a>
+      <span v-else :id="authorId" class="google-review-card-author-name">{{ review.authorName }}</span>
+      <time v-if="review.relativeTime" :datetime="review.publishTime || undefined" class="google-review-card-time">
+        {{ review.relativeTime }}
+      </time>
+    </div>
+
+    <div class="google-review-card-rating">
+      <span class="google-review-card-stars" :style="{ '--_rating': review.rating }" aria-hidden="true">★★★★★</span>
+      <span class="sr-only">{{ formattedRatingLabel }}</span>
+    </div>
+
+    <p v-if="review.text" class="google-review-card-text">{{ review.text }}</p>
+
+    <a v-if="review.reviewUri" :href="review.reviewUri" :aria-describedby="authorId" class="google-review-card-link">
+      {{ readMoreLabel }}
+    </a>
+  </component>
+</template>
+
+<script setup lang="ts">
+import type { GoogleReview } from "~/types/components";
+
+interface Props {
+  review: GoogleReview;
+  tag?: "article" | "div";
+  ratingLabel?: string;
+  readMoreLabel?: string;
+  styleClassPassthrough?: string | string[];
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  tag: "article",
+  ratingLabel: "Rated {rating} out of 5",
+  readMoreLabel: "Read on Google",
+  styleClassPassthrough: () => [],
+});
+
+const authorId = useId();
+const initials = computed(() =>
+  props.review.authorName
+    .split(/\s+/)
+    .filter(Boolean)
+    .slice(0, 2)
+    .map((word) => Array.from(word)[0]!.toUpperCase())
+    .join("")
+);
+const formattedRatingLabel = computed(() => props.ratingLabel.replace("{rating}", String(props.review.rating)));
+
+const { elementClasses, resetElementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
+
+watch(
+  () => props.styleClassPassthrough,
+  () => {
+    resetElementClasses(props.styleClassPassthrough);
+  }
+);
+</script>
+
+<style lang="css">
+@layer components {
+  .google-review-card {
+    display: grid;
+    grid-template-rows: auto auto auto 1fr auto;
+    align-items: start;
+    block-size: 100%;
+    padding: var(--google-reviews-card-padding, 2rem);
+    border: var(--google-reviews-card-border-width, 1px) solid var(--google-reviews-card-border-colour, transparent);
+    border-radius: var(--google-reviews-card-border-radius, 0.8rem);
+    background-color: var(--google-reviews-card-surface, var(--theme-surface-subtle));
+    color: var(--google-reviews-card-text-colour, var(--theme-text));
+
+    /* Name and date take a row each so both line up across a GoogleReviews row */
+    .google-review-card-author {
+      grid-row: 1 / span 2;
+      display: grid;
+      grid-template-columns: auto minmax(0, 1fr);
+      grid-template-rows: subgrid;
+      align-items: start;
+      column-gap: 1.2rem;
+    }
+
+    .google-review-card-author .display-avatar {
+      --display-avatar-background: var(--google-reviews-avatar-surface, var(--theme-surface));
+      --display-avatar-text-colour: var(--google-reviews-avatar-text-colour, var(--theme-on-surface));
+
+      grid-column: 1;
+      grid-row: 1 / -1;
+    }
+
+    .google-review-card-author-name {
+      grid-column: 2;
+      grid-row: 1;
+      display: -webkit-box;
+      -webkit-box-orient: vertical;
+      overflow: hidden;
+      -webkit-line-clamp: var(--google-reviews-author-line-clamp, 2);
+      line-clamp: var(--google-reviews-author-line-clamp, 2);
+      font-weight: var(--google-reviews-author-font-weight, 600);
+      color: inherit;
+      overflow-wrap: anywhere;
+    }
+
+    .google-review-card-time {
+      grid-column: 2;
+      grid-row: 2;
+      font-size: var(--google-reviews-meta-font-size, 1.4rem);
+      color: var(--google-reviews-meta-text-colour, inherit);
+    }
+
+    .google-review-card-rating {
+      grid-row: 3;
+      margin-block-start: var(--google-reviews-card-gap, 1.2rem);
+    }
+
+    .google-review-card-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-review-card-text {
+      grid-row: 4;
+      margin-block-start: var(--google-reviews-card-gap, 1.2rem);
+      margin-inline: 0;
+      margin-block-end: 0;
+      white-space: pre-line;
+      overflow-wrap: anywhere;
+      line-height: var(--google-reviews-text-line-height, 1.5);
+      display: -webkit-box;
+      -webkit-box-orient: vertical;
+      overflow: hidden;
+      -webkit-line-clamp: var(--google-reviews-text-line-clamp, 5);
+      line-clamp: var(--google-reviews-text-line-clamp, 5);
+    }
+
+    .google-review-card-link {
+      grid-row: 5;
+      margin-block-start: var(--google-reviews-card-gap, 1.2rem);
+      justify-self: start;
+      color: var(--google-reviews-link-colour, inherit);
+      font-size: var(--google-reviews-meta-font-size, 1.4rem);
+    }
+  }
+}
+</style>

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>