srcdev-nuxt-components 9.5.3 → 9.5.5

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>"
+`;

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

@@ -0,0 +1,43 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`GoogleReviews > renders correct HTML structure 1`] = `
+"<section class="google-reviews" aria-label="Google reviews">
+  <div class="google-reviews-header">
+    <div class="google-reviews-summary"><span class="google-reviews-summary-rating" aria-hidden="true">4.7</span><span class="google-reviews-stars" style="--_rating: 4.66;" aria-hidden="true">★★★★★</span><span class="sr-only">Rated 4.7 out of 5</span><a href="https://maps.google.com/?cid=1" class="google-reviews-summary-link">128 reviews on Google</a></div>
+  </div>
+  <!--v-if-->
+  <ul class="google-reviews-list" tabindex="0">
+    <li class="google-reviews-item">
+      <article class="google-review-card">
+        <div class="google-review-card-author"><span class="display-avatar md" aria-hidden="true"><span>R1</span>
+          <!--v-if--></span><a id="v-0-0-0" href="https://maps.google.com/contrib/1" class="google-review-card-author-name">Reviewer 1</a><time datetime="2026-09-18T10:00:00Z" class="google-review-card-time">1 weeks ago</time>
+        </div>
+        <div class="google-review-card-rating"><span class="google-review-card-stars" style="--_rating: 5;" aria-hidden="true">★★★★★</span><span class="sr-only">Rated 5 out of 5</span></div>
+        <p class="google-review-card-text">Review text 1</p><a href="https://maps.google.com/review/1" aria-describedby="v-0-0-0" class="google-review-card-link">Read on Google</a>
+      </article>
+    </li>
+    <li class="google-reviews-item">
+      <article class="google-review-card">
+        <div class="google-review-card-author"><span class="display-avatar md" aria-hidden="true"><span>R2</span>
+          <!--v-if--></span><a id="v-0-0-1" href="https://maps.google.com/contrib/2" class="google-review-card-author-name">Reviewer 2</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">Review text 2</p><a href="https://maps.google.com/review/2" aria-describedby="v-0-0-1" class="google-review-card-link">Read on Google</a>
+      </article>
+    </li>
+    <li class="google-reviews-item">
+      <article class="google-review-card">
+        <div class="google-review-card-author"><span class="display-avatar md" aria-hidden="true"><span>R3</span>
+          <!--v-if--></span><a id="v-0-0-2" href="https://maps.google.com/contrib/3" class="google-review-card-author-name">Reviewer 3</a><time datetime="2026-09-18T10:00:00Z" class="google-review-card-time">3 weeks ago</time>
+        </div>
+        <div class="google-review-card-rating"><span class="google-review-card-stars" style="--_rating: 3;" aria-hidden="true">★★★★★</span><span class="sr-only">Rated 3 out of 5</span></div>
+        <p class="google-review-card-text">Review text 3</p><a href="https://maps.google.com/review/3" aria-describedby="v-0-0-2" class="google-review-card-link">Read on Google</a>
+      </article>
+    </li>
+  </ul>
+  <div class="google-reviews-footer">
+    <!--v-if-->
+    <p class="google-reviews-attribution">Reviews from Google Maps</p>
+  </div>
+</section>"
+`;

package/app/components/05.forms/input-number/CONSUMER-STYLING.md

@@ -18,7 +18,7 @@ token, same as `InputTextCore`.
 | `--input-number-surface` | `var(--theme-input-surface)` | Wrapper, input, and embedded-button background |
 | `--input-number-surface-hover` | `var(--theme-input-surface-hover)` | Embedded left/right button background on hover |
 | `--input-number-border` | `var(--theme-border)` | Border/divider colour (`normal`/`underlined` variant border, and the divider between the input and an embedded button) |
-| `--input-number-border-hover` | `var(--theme-border-focus)` | Wrapper outline colour on mouse hover (`normal` variant only) |
+| `--input-number-border-hover` | `var(--theme-border-focus)` | Wrapper outline colour on mouse hover over the input or either step button (`normal` variant only) |
 | `--input-number-border-focus` | `var(--theme-border-focus)` | Wrapper outline colour on `:focus-visible` (`normal` variant), and the embedded button's own `:focus-visible` outline |
 | `--input-number-text-color` | `var(--theme-input-text-color-normal)` | Input text colour |
 | `--input-number-placeholder-color` | `var(--theme-input-placeholder)` | Placeholder text colour |

package/app/components/05.forms/input-number/InputNumber.vue

@@ -104,13 +104,13 @@ const minLength = computed(() => `${props.max.toString().length + 1}em`);
       border-radius: var(--form-input-border-radius);
       outline: var(--form-element-outline-width) solid transparent;
 
-      &:has(input:hover) {
+      &:has(input:hover, button:hover) {
         outline: var(--form-element-outline-width-focus) solid
           var(--input-number-border-hover, var(--theme-border-focus));
         outline-offset: var(--form-element-outline-offset-focus);
       }
 
-      &:has(input:focus-visible) {
+      &:has(input:focus-visible, button:focus-visible) {
         outline: var(--form-element-outline-width-focus) solid var(--_border-focus);
         outline-offset: var(--form-element-outline-offset-focus);
       }

package/app/components/05.forms/input-otp/CONSUMER-STYLING.md

@@ -0,0 +1,59 @@
+# InputOtp — Consumer Styling Guide
+
+## Public token API
+
+Colour tokens fall back to the shared `--theme-*` tokens, so leaving them unset keeps the
+component in step with every other themed form control. See `theming-component-token-pattern.md`
+for the two-tier shape.
+
+### Boxes (`InputOtp`)
+
+| Token | Default | Controls |
+|---|---|---|
+| `--input-otp-gap` | `0.8rem` | Space between boxes |
+| `--input-otp-box-inline-size` | `4.4rem` | Preferred box width (boxes shrink below it when the row is too narrow) |
+| `--input-otp-box-block-size` | `5.2rem` | Box height |
+| `--input-otp-font-size` | `2rem` | Digit size |
+| `--input-otp-border-radius` | `var(--form-input-border-radius)` | Box corner radius (`normal` variant) |
+| `--input-otp-surface` | `var(--theme-input-surface)` | Box background |
+| `--input-otp-text-color` | `var(--theme-input-text-color-normal)` | Digit colour |
+| `--input-otp-border` | `var(--theme-border)` | Box border (`normal`) or bottom border (`underlined`) |
+| `--input-otp-border-hover` | `var(--input-otp-border-focus)` | Outline colour on hover (`normal` variant) |
+| `--input-otp-border-focus` | `var(--theme-border-focus)` | Outline colour on `:focus-visible`, and the bottom border colour on focus (`underlined`) |
+
+### Field (`InputOtpField`)
+
+| Token | Default | Controls |
+|---|---|---|
+| `--input-otp-field-gap` | `0.8rem` | Space between the boxes and the error strip |
+
+The legend uses `FormFieldset`'s `--form-fieldset-legend-*` tokens (see its CONSUMER-STYLING.md).
+Border/outline widths and transition duration are the shared form geometry tokens
+(`--form-element-border-width`, `--form-element-outline-width-focus`, etc.), see
+`theming-form-geometry-tokens.md`.
+
+Private tokens (not public API): `--_border` and `--_border-focus` on `.input-otp`, which only
+resolve the two public border tokens once for reuse across the variant rules.
+
+## State hooks
+
+| Hook | Where | Meaning |
+|---|---|---|
+| `[data-invalid]` | `.input-otp`, and the `.input-otp-field` fieldset | Error state. Switches the colour ramp to the error colours, so `--theme-border` (and everything defaulting from it) turns red without a separate error token. |
+| `[data-theme]` | `.input-otp`, `.input-otp-field` | The `theme` prop. |
+| `.normal` / `.underlined` | `.input-otp` | The `inputVariant` prop. |
+| `.input-otp-box` | each digit `<input>` | One box. |
+
+## 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`.
+
+## Class passthrough
+
+- `InputOtp`: `style-class-passthrough` classes land on the `.input-otp` root (the row of boxes).
+- `InputOtpField`: `style-class-passthrough` classes land on the `.input-otp-field` fieldset; the
+  inner `InputOtp` gets none.