@carissa-io/webkit-testimonials 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,144 @@
-# Temporary Holding Version
+# @carissa-io/webkit-testimonials
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+One large customer quote at a time, with who said it, and previous / next icon buttons. A React component, SCSS-themed, safe
+on the server; its only runtime dependency is `@carissa-io/components-icon` (the chevrons and the pause / play icons). It is not a grid of avatar cards and not a carousel pattern: it rotates only if the
+site opts in with `autoplay_interval` (and then offers a pause button), and there is no motion on mount, no gradient and no default shadow. The only motion is a soft fade of the new quote
+after a change.
+
+**The component has no strings of its own.** The site passes every quote, name and label. The look comes from the theme's
+second stylesheet, `@carissa-io/theme-default/webkit.css`, which apps do not load.
+
+```bash
+npm i @carissa-io/webkit-testimonials
+```
+
+## Use
+
+```jsx
+import { Testimonials } from '@carissa-io/webkit-testimonials'
+
+<Testimonials
+    title={t('quotes_title')}
+    label={t('quotes_region')}
+    previous_label={t('previous')}
+    next_label={t('next')}
+    counter_label={(current, total) => t('quote_counter', { current, total })}
+    items={[
+        { id: 'ada', quote: t('ada_quote'), name: 'Ada Example', role: t('ada_role'), source: 'Example Co' },
+        { id: 'ben', quote: t('ben_quote'), name: 'Ben Sample', role: t('ben_role'), avatar: <img src="/ben.png" alt="" /> },
+    ]}
+/>
+```
+
+| Prop | |
+|---|---|
+| `items` | `[{ id, quote, name, role?, source?, avatar? }]`. `quote` is a string or any node, `name` is required, `role` and `source` are optional text, `avatar` is an optional node the site supplies, `id` the React key (the index when missing). An item without a quote or a name is skipped; anything that is not an array renders no figure |
+| `index` | the current item, **controlled**: the parent decides and the buttons only report through `on_change` |
+| `default_index` | the first item when uncontrolled, `0` by default |
+| `on_change` | `(index) => void`, called with the new index on every button click, in both modes |
+| `autoplay_interval` | optional, milliseconds. Turns the automatic rotation on; off when missing, not a finite number, below `2000`, or with fewer than two items. See [Autoplay](#autoplay) |
+| `pause_label`, `play_label` | the accessible names (`aria-label`) of the pause / play toggle: `pause_label` while the rotation plays, `play_label` while it is paused. Only used when autoplay is on. **Required for accessibility** like `previous_label`: a missing or blank label leaves the toggle without a name; the piece invents no string |
+| `title` | optional heading text; no heading when empty |
+| `title_level` | 1 to 6, default `2`; anything else falls back to `2` |
+| `previous_label`, `next_label` | the accessible names (`aria-label`) of the two icon-only buttons. **Required for accessibility**; never built in. A missing or blank label leaves that button without an `aria-label` (and so without a name): the piece does not invent a string, so always pass both |
+| `counter_label` | optional: a string, or a function `(current, total) => string`. Without it the counter shows `1 / 3` |
+| `label` | optional `aria-label` of the region |
+| `className`, `id`, ... | `className` is appended; unknown props go to the root (a `section`) |
+
+An invalid `index` or `default_index` (not an integer inside the list) falls back to `0`; if the list shrinks, the position
+is clamped the same way. The buttons wrap around: next on the last quote shows the first. With a single item there are no
+controls, no counter and no live region.
+
+## Autoplay
+
+Opt in with `autoplay_interval={8000}` (milliseconds, at least `2000`). Every interval the current item advances to the next
+and wraps from the last to the first: uncontrolled, the piece sets its own index; controlled, it calls `on_change(next)` and
+the parent applies it (a parent that ignores it keeps being asked every interval). The new quote gets the same fade as after
+a button press, but the live region stays silent: only user-driven changes are announced.
+
+The rotation pauses, and starts a fresh full interval when it resumes, while:
+
+- the pointer is over the piece,
+- focus is inside the piece,
+- the page tab is hidden (`document.visibilityState`),
+- the user pressed the pause button (a **manual pause** lasts until the button is pressed again; leaving with the pointer or focus does not resume it).
+
+Pressing previous or next restarts the interval. A real `button type="button"` (`c-testimonials__button c-testimonials__button--toggle`) renders next to
+previous / next only while autoplay is on, icon-only, drawing the Lucide `PauseIcon` while playing and `PlayIcon` while paused
+(decorative `aria-hidden`); it has no `aria-pressed`, its name switches between `pause_label` and `play_label`. With
+`prefers-reduced-motion: reduce` the rotation does not start and the toggle is not rendered; the preference is followed
+live. All timers and listeners are removed on unmount and when the prop turns off. On the server nothing runs: the browser
+state (media query, visibility) is read only in the client, and a missing `matchMedia` means no preference.
+
+```jsx
+<Testimonials items={items} previous_label={t('previous')} next_label={t('next')}
+    autoplay_interval={8000} pause_label={t('pause')} play_label={t('play')} />
+```
+
+## Accessibility
+
+- **A `figure`, not a carousel.** The current quote is a `figure` with a `blockquote` and a `figcaption` (name, role and
+  source). The piece does not use `aria-roledescription="carousel"` or slide semantics; it shows one quote and swaps it.
+- **Buttons are the only tab stops.** Previous, next and, with autoplay, the pause / play toggle are real `button type="button"`, reachable in that order, activated
+  with Enter or Space, and styled by the theme's focus ring (the piece styles no `outline`). They are icon-only (a
+  decorative `aria-hidden` chevron, no visible text); their accessible name comes from `previous_label`, `next_label`, `pause_label` and `play_label`.
+- **The new position is announced, not the whole quote.** A visually hidden `aria-live="polite"` element stays empty on
+  mount and receives the counter text (`counter_label`, or `2 / 3`) only after the user presses a button. A change driven
+  by a controlled `index` from outside is not announced.
+- **Moving content can be stopped (WCAG 2.2.2 Pause, Stop, Hide).** Autoplay is off unless the site opts in; when on, it
+  pauses on hover, on focus inside and in a hidden tab, always offers the pause / play button, honours
+  `prefers-reduced-motion: reduce` (no rotation, no toggle), and never rotates a single item. Automatic changes are not
+  announced, so a screen reader is not interrupted; the visible counter still updates.
+- **One soft fade, after a change.** No transition and no motion on mount or on the server.
+  When the user presses previous / next (or autoplay advances) and the item changes, the new figure is re-keyed and gets
+  `c-testimonials__figure--enter`: an opacity-only CSS keyframe (0 to 1; no movement, no layout shift). A change driven by a
+  controlled `index` from outside, a single item and the first render never fade. Under `prefers-reduced-motion: reduce`
+  the piece's SCSS sets `animation: none`, so the change is instant. The default duration is `0s` (inert); the theme sets
+  one. The visible counter (`current / total`) is plain text.
+- The title is a real heading (`title_level`); `label` names the region for screen reader landmark lists.
+
+## Layout
+
+A single column (`$c-testimonials-align: center` centres the quote, attribution and controls; the 65ch measure box stays
+centred in its container): the quote, capped by `$c-testimonials-quote-max-width` (65ch, the text measure), then the attribution (avatar
+node, name, role, source), then the controls. Long quotes and long names wrap (`overflow-wrap`), nothing is truncated and
+there are no fixed widths. The avatar is a slot: the site supplies the node (usually an `img`) and the piece only limits
+its box to `$c-testimonials-avatar-size`.
+
+## Style
+
+```scss
+@use '@carissa-io/webkit-testimonials/scss' with (
+    $c-testimonials-quote-font-size: 2.5rem,
+    $c-testimonials-button-border-width: 1px
+);
+```
+
+Classes: `c-testimonials`, `c-testimonials__header`, `c-testimonials__title`, `c-testimonials__figure`,
+`c-testimonials__quote`, `c-testimonials__cite`, `c-testimonials__avatar`, `c-testimonials__person`, `c-testimonials__name`,
+`c-testimonials__role`, `c-testimonials__source`, `c-testimonials__controls`, `c-testimonials__figure--enter` (the fade, added only after a change),
+`c-testimonials__button` (with `c-testimonials__button--previous`, `--next` and `--toggle`, the autoplay pause / play button; each holds one `c-icon` svg), `c-testimonials__counter`, `c-testimonials__status` (the hidden live
+region). Every variable is `!default` (see [scss/_variables.scss](scss/_variables.scss)); the defaults are neutral
+(inherited colours, transparent background, no rules).
+
+| Variable | Default |
+|---|---|
+| `$c-testimonials-font-family`, `-color`, `-background` | `inherit`, `inherit`, `transparent` |
+| `$c-testimonials-align` | `start` (`start` or `center`: `text-align` and flex alignment of figure, attribution and controls) |
+| `$c-testimonials-max-width` | `80rem` (header, figure and controls, centred) |
+| `$c-testimonials-padding-block`, `-padding-inline` | `4rem`, `1rem` |
+| `$c-testimonials-header-margin-bottom` | `2rem` |
+| `$c-testimonials-title-font-size`, `-font-weight`, `-line-height`, `-color`, `-max-width` | `1.75rem`, `inherit`, `1.15`, `inherit`, `40ch` |
+| `$c-testimonials-gap` | `1.5rem` (quote to attribution) |
+| `$c-testimonials-quote-font-size`, `-font-weight`, `-line-height`, `-letter-spacing`, `-color`, `-max-width` | `2rem`, `inherit`, `1.3`, `normal`, `inherit`, `65ch` |
+| `$c-testimonials-cite-gap`, `-avatar-size`, `-person-gap` | `1rem`, `3rem`, `0.125rem` |
+| `$c-testimonials-name-font-size`, `-font-weight`, `-color` | `1rem`, `inherit`, `inherit` |
+| `$c-testimonials-role-font-size`, `-color` | `0.875rem`, `inherit` |
+| `$c-testimonials-source-font-size`, `-color` | `0.875rem`, `inherit` |
+| `$c-testimonials-fade-duration`, `-fade-easing` | `0s` (no fade), `ease` |
+| `$c-testimonials-controls-gap`, `-controls-margin-top` | `1rem`, `2rem` |
+| `$c-testimonials-button-padding-block`, `-padding-inline` | `0.5rem`, `1rem` |
+| `$c-testimonials-button-font-family`, `-font-size`, `-font-weight`, `-color`, `-background` | `inherit`, `0.875rem`, `inherit`, `inherit`, `transparent` |
+| `$c-testimonials-button-border-width`, `-border-style`, `-border-color`, `-radius`, `-cursor` | `0`, `solid`, `currentcolor`, `0`, `pointer` |
+| `$c-testimonials-counter-font-size`, `-counter-color` | `0.875rem`, `inherit` |
+| `$c-testimonials-link-color`, `-link-text-decoration` | `inherit`, `underline` |

package/dist/index.js

@@ -0,0 +1,155 @@
+// src/Testimonials.jsx
+import { useEffect, useRef, useState, useSyncExternalStore } from "react";
+import { ChevronLeftIcon, ChevronRightIcon, PauseIcon, PlayIcon } from "@carissa-io/components-icon";
+import { jsx, jsxs } from "react/jsx-runtime";
+var LEVELS = [1, 2, 3, 4, 5, 6];
+var join = (...parts) => parts.filter(Boolean).join(" ");
+var filled = (value) => value !== void 0 && value !== null && value !== false && value !== true && value !== "";
+var text = (value) => typeof value === "string" && value.trim() !== "";
+var valid_index = (value, total) => Number.isInteger(value) && value >= 0 && value < total;
+var MIN_AUTOPLAY_INTERVAL = 2e3;
+var REDUCED_MOTION = "(prefers-reduced-motion: reduce)";
+var media_query = () => typeof window !== "undefined" && typeof window.matchMedia === "function" ? window.matchMedia(REDUCED_MOTION) : null;
+var subscribe_reduced = (notify) => {
+  const query = media_query();
+  if (!query) return () => {
+  };
+  if (typeof query.addEventListener === "function") {
+    query.addEventListener("change", notify);
+    return () => query.removeEventListener("change", notify);
+  }
+  query.addListener?.(notify);
+  return () => query.removeListener?.(notify);
+};
+var read_reduced = () => media_query()?.matches === true;
+var subscribe_visibility = (notify) => {
+  document.addEventListener("visibilitychange", notify);
+  return () => document.removeEventListener("visibilitychange", notify);
+};
+var read_hidden = () => document.visibilityState === "hidden";
+var never = () => false;
+function Testimonials({
+  items,
+  index,
+  default_index = 0,
+  on_change,
+  title,
+  title_level = 2,
+  previous_label,
+  next_label,
+  pause_label,
+  play_label,
+  autoplay_interval,
+  counter_label,
+  label,
+  className = "",
+  onMouseEnter,
+  onMouseLeave,
+  onFocus,
+  onBlur,
+  ...rest
+}) {
+  const [inner, set_inner] = useState(default_index);
+  const [announced, set_announced] = useState(null);
+  const [changed, set_changed] = useState(null);
+  const [cycle, set_cycle] = useState(0);
+  const [hovered, set_hovered] = useState(false);
+  const [focused, set_focused] = useState(false);
+  const [manual_pause, set_manual_pause] = useState(false);
+  const reduced = useSyncExternalStore(subscribe_reduced, read_reduced, never);
+  const hidden = useSyncExternalStore(subscribe_visibility, read_hidden, never);
+  const level = Number(title_level);
+  const Heading = `h${LEVELS.includes(level) ? level : 2}`;
+  const list = Array.isArray(items) ? items.filter((item2) => item2 && typeof item2 === "object" && !Array.isArray(item2) && filled(item2.quote) && filled(item2.name)) : [];
+  const total = list.length;
+  const wanted = index === void 0 ? inner : index;
+  const current = valid_index(wanted, total) ? wanted : 0;
+  const item = list[current];
+  const has_title = text(title);
+  const counter_text = (position) => {
+    if (typeof counter_label === "function") return counter_label(position, total);
+    if (text(counter_label)) return counter_label;
+    return `${position} / ${total}`;
+  };
+  const autoplay = typeof autoplay_interval === "number" && Number.isFinite(autoplay_interval) && autoplay_interval >= MIN_AUTOPLAY_INTERVAL && total > 1 && !reduced;
+  const running = autoplay && !manual_pause && !hovered && !focused && !hidden;
+  const move = (next, by_user) => {
+    if (index === void 0) set_inner(next);
+    set_changed(next);
+    set_announced(by_user ? next : null);
+    set_cycle((value) => value + 1);
+    if (typeof on_change === "function") on_change(next);
+  };
+  const go = (step) => move((current + step + total) % total, true);
+  const advance = useRef(null);
+  useEffect(() => {
+    advance.current = () => move((current + 1) % total, false);
+  });
+  useEffect(() => {
+    if (!running) return void 0;
+    const timer = setTimeout(() => advance.current(), autoplay_interval);
+    return () => clearTimeout(timer);
+  }, [running, autoplay_interval, cycle]);
+  const leaving = (event) => !event.currentTarget.contains(event.relatedTarget);
+  const after_interaction = announced !== null && announced === current;
+  const fading = changed !== null && changed === current;
+  const status = after_interaction ? counter_text(current + 1) : "";
+  const button_label = (value) => text(value) ? value : void 0;
+  return /* @__PURE__ */ jsxs(
+    "section",
+    {
+      ...rest,
+      onMouseEnter: (event) => {
+        set_hovered(true);
+        if (typeof onMouseEnter === "function") onMouseEnter(event);
+      },
+      onMouseLeave: (event) => {
+        set_hovered(false);
+        if (typeof onMouseLeave === "function") onMouseLeave(event);
+      },
+      onFocus: (event) => {
+        set_focused(true);
+        if (typeof onFocus === "function") onFocus(event);
+      },
+      onBlur: (event) => {
+        if (leaving(event)) set_focused(false);
+        if (typeof onBlur === "function") onBlur(event);
+      },
+      "aria-label": text(label) ? label : void 0,
+      className: join("c-testimonials", className),
+      children: [
+        has_title ? /* @__PURE__ */ jsx("div", { className: "c-testimonials__header", children: /* @__PURE__ */ jsx(Heading, { className: "c-testimonials__title", children: title }) }) : null,
+        item ? /* @__PURE__ */ jsxs("figure", { className: join("c-testimonials__figure", fading && "c-testimonials__figure--enter"), children: [
+          /* @__PURE__ */ jsx("blockquote", { className: "c-testimonials__quote", children: item.quote }),
+          /* @__PURE__ */ jsxs("figcaption", { className: "c-testimonials__cite", children: [
+            filled(item.avatar) ? /* @__PURE__ */ jsx("span", { className: "c-testimonials__avatar", children: item.avatar }) : null,
+            /* @__PURE__ */ jsxs("span", { className: "c-testimonials__person", children: [
+              /* @__PURE__ */ jsx("span", { className: "c-testimonials__name", children: item.name }),
+              filled(item.role) ? /* @__PURE__ */ jsx("span", { className: "c-testimonials__role", children: item.role }) : null,
+              filled(item.source) ? /* @__PURE__ */ jsx("span", { className: "c-testimonials__source", children: item.source }) : null
+            ] })
+          ] })
+        ] }, current) : null,
+        total > 1 ? /* @__PURE__ */ jsxs("div", { className: "c-testimonials__controls", children: [
+          /* @__PURE__ */ jsx("button", { type: "button", className: "c-testimonials__button c-testimonials__button--previous", "aria-label": button_label(previous_label), onClick: () => go(-1), children: /* @__PURE__ */ jsx(ChevronLeftIcon, {}) }),
+          /* @__PURE__ */ jsx("span", { className: "c-testimonials__counter", children: counter_text(current + 1) }),
+          /* @__PURE__ */ jsx("button", { type: "button", className: "c-testimonials__button c-testimonials__button--next", "aria-label": button_label(next_label), onClick: () => go(1), children: /* @__PURE__ */ jsx(ChevronRightIcon, {}) }),
+          autoplay ? /* @__PURE__ */ jsx(
+            "button",
+            {
+              type: "button",
+              className: "c-testimonials__button c-testimonials__button--toggle",
+              "aria-label": button_label(manual_pause ? play_label : pause_label),
+              onClick: () => set_manual_pause((value) => !value),
+              children: manual_pause ? /* @__PURE__ */ jsx(PlayIcon, {}) : /* @__PURE__ */ jsx(PauseIcon, {})
+            }
+          ) : null,
+          /* @__PURE__ */ jsx("span", { className: "c-testimonials__status", "aria-live": "polite", "aria-atomic": "true", children: status })
+        ] }) : null
+      ]
+    }
+  );
+}
+export {
+  Testimonials
+};

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@carissa-io/webkit-testimonials",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Carissa web kit: testimonials, one quote at a time, as a React component with SCSS variables",
+  "type": "module",
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "scss",
+    "THIRD-PARTY-NOTICES"
+  ],
+  "exports": {
+    ".": "./dist/index.js",
+    "./scss": "./scss/index.scss",
+    "./scss/*": "./scss/*"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "esbuild src/index.js --bundle --packages=external --format=esm --jsx=automatic --outfile=dist/index.js",
+    "test": "vitest run",
+    "lint": "eslint .",
+    "prepublishOnly": "node -e \"if (!process.env.GITHUB_ACTIONS) { console.error('Refusing to publish outside GitHub Actions CI: commit and push to main instead.'); process.exit(1); }\" && npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/carissa-io/webkit-testimonials.git"
+  },
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=24"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@testing-library/jest-dom": "^7.0.1",
+    "@testing-library/react": "^16.3.3",
+    "@testing-library/user-event": "^14.6.7",
+    "@vitejs/plugin-react": "^6.1.1",
+    "esbuild": "^0.28.0",
+    "eslint": "^10.12.0",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "globals": "^17.13.0",
+    "jsdom": "^29.1.1",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
+    "sass-embedded": "^1.105.1",
+    "vite": "^8.3.2",
+    "vitest": "^4.1.11"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "dependencies": {
+    "@carissa-io/components-icon": "^0.1.2"
+  }
+}

package/scss/_testimonials.scss

@@ -0,0 +1,185 @@
+@use 'variables' as *;
+
+// `center` centres; anything else is `start`.
+$_text-align: start;
+$_items: flex-start;
+
+@if $c-testimonials-align == center {
+    $_text-align: center;
+    $_items: center;
+}
+
+.c-testimonials {
+    box-sizing: border-box;
+    padding-block: $c-testimonials-padding-block;
+    padding-inline: $c-testimonials-padding-inline;
+    font-family: $c-testimonials-font-family;
+    color: $c-testimonials-color;
+    background: $c-testimonials-background;
+}
+
+.c-testimonials a {
+    color: $c-testimonials-link-color;
+    text-decoration: $c-testimonials-link-text-decoration;
+}
+
+.c-testimonials__header {
+    max-width: $c-testimonials-max-width;
+    margin-inline: auto;
+    margin-block-end: $c-testimonials-header-margin-bottom;
+    text-align: $_text-align;
+}
+
+.c-testimonials__title {
+    margin: 0;
+    max-width: $c-testimonials-title-max-width;
+    font-size: $c-testimonials-title-font-size;
+    font-weight: $c-testimonials-title-font-weight;
+    line-height: $c-testimonials-title-line-height;
+    color: $c-testimonials-title-color;
+    overflow-wrap: break-word;
+
+    // The title box has its own max-width, so a centred header centres the box as well as its text
+    @if $c-testimonials-align == center {
+        margin-inline: auto;
+    }
+}
+
+.c-testimonials__figure {
+    box-sizing: border-box;
+    display: flex;
+    flex-direction: column;
+    gap: $c-testimonials-gap;
+    max-width: $c-testimonials-max-width;
+    margin: 0;
+    margin-inline: auto;
+    align-items: $_items;
+    text-align: $_text-align;
+}
+
+@keyframes c-testimonials-fade {
+    from {
+        opacity: 0;
+    }
+
+    to {
+        opacity: 1;
+    }
+}
+
+// Opacity only: no movement and no layout shift. Added by the component only after the user changed the item.
+.c-testimonials__figure--enter {
+    animation: c-testimonials-fade $c-testimonials-fade-duration $c-testimonials-fade-easing;
+}
+
+@media (prefers-reduced-motion: reduce) {
+    .c-testimonials__figure--enter {
+        animation: none;
+    }
+}
+
+.c-testimonials__quote {
+    margin: 0;
+    max-width: $c-testimonials-quote-max-width;
+    font-size: $c-testimonials-quote-font-size;
+    font-weight: $c-testimonials-quote-font-weight;
+    line-height: $c-testimonials-quote-line-height;
+    letter-spacing: $c-testimonials-quote-letter-spacing;
+    color: $c-testimonials-quote-color;
+    overflow-wrap: break-word;
+}
+
+.c-testimonials__cite {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    justify-content: $_items;
+    gap: $c-testimonials-cite-gap;
+    min-width: 0;
+}
+
+.c-testimonials__avatar {
+    flex: none;
+    display: block;
+    max-width: $c-testimonials-avatar-size;
+    max-height: $c-testimonials-avatar-size;
+    overflow: visible;
+}
+
+.c-testimonials__avatar > * {
+    max-width: 100%;
+    height: auto;
+}
+
+.c-testimonials__person {
+    display: flex;
+    flex-direction: column;
+    align-items: $_items;
+    gap: $c-testimonials-person-gap;
+    min-width: 0;
+}
+
+.c-testimonials__name {
+    font-size: $c-testimonials-name-font-size;
+    font-weight: $c-testimonials-name-font-weight;
+    color: $c-testimonials-name-color;
+    overflow-wrap: break-word;
+}
+
+.c-testimonials__role {
+    font-size: $c-testimonials-role-font-size;
+    color: $c-testimonials-role-color;
+    overflow-wrap: break-word;
+}
+
+.c-testimonials__source {
+    font-size: $c-testimonials-source-font-size;
+    color: $c-testimonials-source-color;
+    overflow-wrap: break-word;
+}
+
+.c-testimonials__controls {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    justify-content: $_items;
+    gap: $c-testimonials-controls-gap;
+    max-width: $c-testimonials-max-width;
+    margin-block-start: $c-testimonials-controls-margin-top;
+    margin-inline: auto;
+}
+
+.c-testimonials__button {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    box-sizing: border-box;
+    padding-block: $c-testimonials-button-padding-block;
+    padding-inline: $c-testimonials-button-padding-inline;
+    font-family: $c-testimonials-button-font-family;
+    font-size: $c-testimonials-button-font-size;
+    font-weight: $c-testimonials-button-font-weight;
+    color: $c-testimonials-button-color;
+    background: $c-testimonials-button-background;
+    border: $c-testimonials-button-border-width $c-testimonials-button-border-style $c-testimonials-button-border-color;
+    border-radius: $c-testimonials-button-radius;
+    cursor: $c-testimonials-button-cursor;
+}
+
+.c-testimonials__counter {
+    font-size: $c-testimonials-counter-font-size;
+    color: $c-testimonials-counter-color;
+}
+
+// Visually hidden, still announced: the polite live region that receives the counter after the user moves.
+.c-testimonials__status {
+    position: absolute;
+    margin: -1px;
+    padding: 0;
+    border: 0;
+    width: 1px;
+    height: 1px;
+    clip-path: inset(50%);
+    white-space: normal;
+    overflow: hidden;
+}

package/scss/_variables.scss

@@ -0,0 +1,73 @@
+// Every value is `!default`: set it before the first @use / through `with (...)` and it wins.
+//
+//   @use '@carissa-io/webkit-testimonials/scss' with ($c-testimonials-quote-font-size: 2.5rem, $c-testimonials-button-border-width: 1px);
+//
+// The defaults are neutral: inherited colours, a transparent background, no card, no shadow, no gradient, no icon and no
+// motion (the fade of the quote has a 0s duration until a theme sets one). A theme gives the look (sizes from its type scale, `var(--c-*)` colours, the 1px rules).
+
+// Root and container
+$c-testimonials-font-family: inherit !default;
+$c-testimonials-color: inherit !default;
+$c-testimonials-background: transparent !default;
+$c-testimonials-max-width: 80rem !default; // the inner block, centred
+$c-testimonials-padding-block: 4rem !default;
+$c-testimonials-padding-inline: 1rem !default;
+
+// Alignment: `start` or `center`. It sets text-align and the flex alignment of the figure, the attribution and the controls.
+$c-testimonials-align: start !default;
+
+// Header (title)
+$c-testimonials-header-margin-bottom: 2rem !default;
+$c-testimonials-title-font-size: 1.75rem !default;
+$c-testimonials-title-font-weight: inherit !default;
+$c-testimonials-title-line-height: 1.15 !default;
+$c-testimonials-title-color: inherit !default;
+$c-testimonials-title-max-width: 40ch !default;
+
+// The figure: the quote and its attribution
+$c-testimonials-gap: 1.5rem !default; // between the quote and the attribution
+$c-testimonials-quote-font-size: 2rem !default; // the theme ties it to its heading size
+$c-testimonials-quote-font-weight: inherit !default;
+$c-testimonials-quote-line-height: 1.3 !default;
+$c-testimonials-quote-letter-spacing: normal !default;
+$c-testimonials-quote-color: inherit !default;
+$c-testimonials-quote-max-width: 65ch !default; // the text measure
+
+// Fade of the new quote after the user pressed previous / next (never on mount; cancelled under prefers-reduced-motion).
+// 0s keeps the piece inert; a theme sets a duration.
+$c-testimonials-fade-duration: 0s !default;
+$c-testimonials-fade-easing: ease !default;
+
+// Attribution (figcaption)
+$c-testimonials-cite-gap: 1rem !default; // between the avatar and the person
+$c-testimonials-avatar-size: 3rem !default; // the box the site's avatar node sits in
+$c-testimonials-person-gap: 0.125rem !default;
+$c-testimonials-name-font-size: 1rem !default;
+$c-testimonials-name-font-weight: inherit !default;
+$c-testimonials-name-color: inherit !default;
+$c-testimonials-role-font-size: 0.875rem !default;
+$c-testimonials-role-color: inherit !default;
+$c-testimonials-source-font-size: 0.875rem !default;
+$c-testimonials-source-color: inherit !default;
+
+// Controls: previous button, counter, next button
+$c-testimonials-controls-gap: 1rem !default;
+$c-testimonials-controls-margin-top: 2rem !default;
+$c-testimonials-button-padding-block: 0.5rem !default;
+$c-testimonials-button-padding-inline: 1rem !default;
+$c-testimonials-button-font-family: inherit !default;
+$c-testimonials-button-font-size: 0.875rem !default;
+$c-testimonials-button-font-weight: inherit !default;
+$c-testimonials-button-color: inherit !default;
+$c-testimonials-button-background: transparent !default;
+$c-testimonials-button-border-width: 0 !default; // the theme sets 1px
+$c-testimonials-button-border-style: solid !default;
+$c-testimonials-button-border-color: currentcolor !default;
+$c-testimonials-button-radius: 0 !default;
+$c-testimonials-button-cursor: pointer !default;
+$c-testimonials-counter-font-size: 0.875rem !default;
+$c-testimonials-counter-color: inherit !default;
+
+// Links the site puts in a slot (quote, role, source): they follow the piece colours, never the browser blue
+$c-testimonials-link-color: inherit !default;
+$c-testimonials-link-text-decoration: underline !default;

package/scss/index.scss

@@ -0,0 +1,2 @@
+@forward 'variables';
+@use 'testimonials';