srcdev-nuxt-components 9.6.3 → 9.6.5

package/app/components/02.molecules/input-copy/tests/InputCopy.spec.ts

@@ -1,222 +1,198 @@
-import { describe, it, expect, vi, beforeEach } from "vitest";
-import { mount } from "@vue/test-utils";
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { nextTick } from "vue";
+import { mountSuspended } from "@nuxt/test-utils/runtime";
+import type { VueWrapper } from "@vue/test-utils";
 import InputCopy from "../InputCopy.vue";
 
+let wrapper: VueWrapper | undefined;
+let writeText: ReturnType<typeof vi.fn>;
+
+async function mountCopy(props: Record<string, unknown> = {}) {
+  wrapper = await mountSuspended(InputCopy, { props: { value: "test-key-123", ...props } });
+  return wrapper;
+}
+
+async function clickCopy(w: VueWrapper) {
+  await w.find("button").trigger("click");
+  await nextTick();
+  await nextTick();
+}
+
 describe("InputCopy", () => {
   beforeEach(() => {
-    vi.clearAllMocks();
+    writeText = vi.fn(() => Promise.resolve());
+    Object.defineProperty(navigator, "clipboard", { value: { writeText }, configurable: true });
   });
 
-  it("renders readonly input with value", () => {
-    const wrapper = mount(InputCopy, {
-      props: {
-        value: "test-key-123",
-        label: "Test key",
-      },
-    });
-
-    const input = wrapper.find("input");
-    expect(input.element.value).toBe("test-key-123");
-    expect(input.element.readOnly).toBe(true);
+  afterEach(() => {
+    wrapper?.unmount();
+    wrapper = undefined;
+    vi.restoreAllMocks();
   });
 
-  it("displays description when provided", () => {
-    const wrapper = mount(InputCopy, {
-      props: {
-        value: "test-key",
-        description: "This is your license key.",
-      },
+  describe("rendering", () => {
+    it("renders a readonly input with the value", async () => {
+      const w = await mountCopy();
+      const input = w.find("input").element as HTMLInputElement;
+      expect(input.value).toBe("test-key-123");
+      expect(input.readOnly).toBe(true);
     });
 
-    expect(wrapper.text()).toContain("This is your license key.");
-  });
-
-  it("does not display description when not provided", () => {
-    const wrapper = mount(InputCopy, {
-      props: {
-        value: "test-key",
-        description: undefined,
-      },
+    it("renders the root class and styleClassPassthrough classes", async () => {
+      const w = await mountCopy({ styleClassPassthrough: ["custom-class", "another-class"] });
+      expect(w.classes()).toContain("input-copy");
+      expect(w.classes()).toContain("custom-class");
+      expect(w.classes()).toContain("another-class");
     });
 
-    const description = wrapper.find(".input-copy__description");
-    expect(description.exists()).toBe(false);
-  });
-
-  it("renders copy button with default text", () => {
-    const wrapper = mount(InputCopy, {
-      props: {
-        value: "test-key",
-        buttonText: "Copy",
-      },
+    it("updates passthrough classes when the prop changes", async () => {
+      const w = await mountCopy({ styleClassPassthrough: ["first"] });
+      await w.setProps({ styleClassPassthrough: ["second"] });
+      expect(w.classes()).toContain("second");
+      expect(w.classes()).not.toContain("first");
     });
 
-    const button = wrapper.find("button");
-    expect(button.text()).toContain("Copy");
-  });
-
-  it("renders copy button with custom text", () => {
-    const wrapper = mount(InputCopy, {
-      props: {
-        value: "test-key",
-        buttonText: "Copy to clipboard",
-      },
+    it("renders the copy button as an inline InputButton", async () => {
+      const w = await mountCopy();
+      const button = w.find("button");
+      expect(button.classes()).toContain("input-button");
+      expect(button.classes()).toContain("inline");
+      expect(button.classes()).toContain("input-copy__button");
+      expect(button.attributes("type")).toBe("button");
     });
 
-    const button = wrapper.find("button");
-    expect(button.text()).toContain("Copy to clipboard");
-  });
-
-  it("disables button when isDisabled is true", () => {
-    const wrapper = mount(InputCopy, {
-      props: {
-        value: "test-key",
-        isDisabled: true,
-      },
+    it("renders default and custom button text", async () => {
+      const w = await mountCopy();
+      expect(w.find("button").text()).toContain("Copy");
+      await w.setProps({ buttonText: "Copy to clipboard" });
+      expect(w.find("button").text()).toContain("Copy to clipboard");
     });
 
-    const button = wrapper.find("button");
-    expect(button.attributes("disabled")).toBeDefined();
-  });
-
-  it("button is not disabled when isDisabled is false", () => {
-    const wrapper = mount(InputCopy, {
-      props: {
-        value: "test-key",
-        isDisabled: false,
-      },
+    it("renders the description only when provided", async () => {
+      const w = await mountCopy();
+      expect(w.find(".input-copy__description").exists()).toBe(false);
+      await w.setProps({ description: "This is your license key." });
+      expect(w.find(".input-copy__description").text()).toBe("This is your license key.");
     });
 
-    const button = wrapper.find("button");
-    expect(button.attributes("disabled")).toBeUndefined();
-  });
-
-  it("has proper aria-label on input from label prop", () => {
-    const wrapper = mount(InputCopy, {
-      props: {
-        value: "test-key",
-        label: "License key",
-      },
+    it("renders the icon in the button", async () => {
+      const w = await mountCopy();
+      expect(w.find("button .input-copy__icon").exists()).toBe(true);
     });
-
-    const input = wrapper.find("input");
-    expect(input.attributes("aria-label")).toBe("License key");
   });
 
-  it("has proper aria-label on input from ariaLabel prop (takes precedence)", () => {
-    const wrapper = mount(InputCopy, {
-      props: {
-        value: "test-key",
-        label: "License key",
-        ariaLabel: "Unique license identifier",
-      },
+  describe("id and name", () => {
+    it("auto-generates an id and mirrors it as the name", async () => {
+      const w = await mountCopy();
+      const input = w.find("input");
+      expect(input.attributes("id")).toBeTruthy();
+      expect(input.attributes("name")).toBe(input.attributes("id"));
     });
 
-    const input = wrapper.find("input");
-    expect(input.attributes("aria-label")).toBe("Unique license identifier");
-  });
-
-  it("has proper aria-label on button", () => {
-    const wrapper = mount(InputCopy, {
-      props: {
-        value: "test-key",
-        label: "API token",
-      },
+    it("uses the provided id, and name over the id", async () => {
+      const w = await mountCopy({ id: "license-key-input" });
+      expect(w.find("input").attributes("id")).toBe("license-key-input");
+      expect(w.find("input").attributes("name")).toBe("license-key-input");
+      await w.setProps({ name: "licenseKey" });
+      expect(w.find("input").attributes("name")).toBe("licenseKey");
     });
-
-    const button = wrapper.find("button");
-    expect(button.attributes("aria-label")).toContain("Copy");
-    expect(button.attributes("aria-label")).toContain("API token");
   });
 
-  it("has icon element in button", () => {
-    const wrapper = mount(InputCopy, {
-      props: {
-        value: "test-key",
-      },
+  describe("accessibility", () => {
+    it("labels the input from label, with ariaLabel taking precedence", async () => {
+      const w = await mountCopy({ label: "License key" });
+      expect(w.find("input").attributes("aria-label")).toBe("License key");
+      await w.setProps({ ariaLabel: "Unique license identifier" });
+      expect(w.find("input").attributes("aria-label")).toBe("Unique license identifier");
     });
 
-    const icon = wrapper.find(".input-copy__icon");
-    expect(icon.exists()).toBe(true);
-  });
-
-  it("input wrapper contains both input and button", () => {
-    const wrapper = mount(InputCopy, {
-      props: {
-        value: "test-key",
-      },
+    it("builds a default button aria-label from the label", async () => {
+      const w = await mountCopy({ label: "API token" });
+      expect(w.find("button").attributes("aria-label")).toBe("Copy API token to clipboard");
     });
 
-    const wrapper_el = wrapper.find(".input-copy__wrapper");
-    expect(wrapper_el.exists()).toBe(true);
-
-    const input = wrapper_el.find("input");
-    const button = wrapper_el.find("button");
+    it("uses buttonAriaLabel when provided", async () => {
+      const w = await mountCopy({ label: "API token", buttonAriaLabel: "API-Token kopieren" });
+      expect(w.find("button").attributes("aria-label")).toBe("API-Token kopieren");
+    });
 
-    expect(input.exists()).toBe(true);
-    expect(button.exists()).toBe(true);
-  });
+    it("links the description to the input with aria-describedby", async () => {
+      const w = await mountCopy({ id: "key", description: "Keep it safe." });
+      expect(w.find("input").attributes("aria-describedby")).toBe("key-description");
+      expect(w.find("#key-description").text()).toBe("Keep it safe.");
+    });
 
-  it("renders with correct component classes", () => {
-    const wrapper = mount(InputCopy, {
-      props: {
-        value: "test-key",
-      },
+    it("has no aria-describedby without a description", async () => {
+      const w = await mountCopy();
+      expect(w.find("input").attributes("aria-describedby")).toBeUndefined();
     });
 
-    expect(wrapper.classes()).toContain("input-copy");
+    it("has an empty status region until a copy succeeds", async () => {
+      const w = await mountCopy();
+      expect(w.find("[role='status']").text()).toBe("");
+    });
   });
 
-  it("applies styleClassPassthrough classes", () => {
-    const wrapper = mount(InputCopy, {
-      props: {
-        value: "test-key",
-        styleClassPassthrough: ["custom-class", "another-class"],
-      },
+  describe("disabled", () => {
+    it("disables the button when isDisabled is true", async () => {
+      const w = await mountCopy({ isDisabled: true });
+      expect(w.find("button").attributes("disabled")).toBeDefined();
     });
 
-    expect(wrapper.classes()).toContain("custom-class");
-    expect(wrapper.classes()).toContain("another-class");
+    it("leaves the button enabled by default", async () => {
+      const w = await mountCopy();
+      expect(w.find("button").attributes("disabled")).toBeUndefined();
+    });
   });
 
-  it("auto-generates an id and mirrors it as the name when neither is provided", () => {
-    const wrapper = mount(InputCopy, {
-      props: {
-        value: "test-key",
-      },
+  describe("copying", () => {
+    it("writes the value to the clipboard and emits copy and copied", async () => {
+      const w = await mountCopy();
+      await clickCopy(w);
+      expect(writeText).toHaveBeenCalledWith("test-key-123");
+      expect(w.emitted("copy")).toEqual([["test-key-123"]]);
+      expect(w.emitted("copied")).toEqual([["test-key-123"]]);
     });
 
-    const input = wrapper.find("input");
-    const id = input.attributes("id");
-
-    expect(id).toBeTruthy();
-    expect(input.attributes("name")).toBe(id);
-  });
-
-  it("uses the provided id prop instead of auto-generating one", () => {
-    const wrapper = mount(InputCopy, {
-      props: {
-        value: "test-key",
-        id: "license-key-input",
-      },
+    it("shows copiedText, announces it and adds the copied class", async () => {
+      const w = await mountCopy({ copiedText: "Kopiert!" });
+      await clickCopy(w);
+      expect(w.find("button").text()).toContain("Kopiert!");
+      expect(w.find("[role='status']").text()).toBe("Kopiert!");
+      expect(w.classes()).toContain("input-copy-copied");
     });
 
-    const input = wrapper.find("input");
-    expect(input.attributes("id")).toBe("license-key-input");
-    expect(input.attributes("name")).toBe("license-key-input");
-  });
+    it("keeps the button focusable but aria-disabled while copied, ignoring repeat clicks", async () => {
+      const w = await mountCopy();
+      await clickCopy(w);
+      const button = w.find("button");
+      expect(button.attributes("disabled")).toBeUndefined();
+      expect(button.attributes("aria-disabled")).toBe("true");
+      await clickCopy(w);
+      expect(writeText).toHaveBeenCalledOnce();
+    });
 
-  it("uses the provided name prop instead of falling back to the id", () => {
-    const wrapper = mount(InputCopy, {
-      props: {
-        value: "test-key",
-        id: "license-key-input",
-        name: "licenseKey",
-      },
+    it("resets after copiedDuration", async () => {
+      const w = await mountCopy({ copiedDuration: 1000 });
+      await clickCopy(w);
+      vi.advanceTimersByTime(999);
+      await nextTick();
+      expect(w.classes()).toContain("input-copy-copied");
+      vi.advanceTimersByTime(1);
+      await nextTick();
+      expect(w.classes()).not.toContain("input-copy-copied");
+      expect(w.find("button").text()).toContain("Copy");
+      expect(w.find("button").attributes("aria-disabled")).toBe("false");
     });
 
-    const input = wrapper.find("input");
-    expect(input.attributes("id")).toBe("license-key-input");
-    expect(input.attributes("name")).toBe("licenseKey");
+    it("logs and stays in the resting state when the clipboard write fails", async () => {
+      const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+      writeText.mockImplementation(() => Promise.reject(new Error("denied")));
+      const w = await mountCopy();
+      await clickCopy(w);
+      expect(errorSpy).toHaveBeenCalled();
+      expect(w.emitted("copied")).toBeUndefined();
+      expect(w.classes()).not.toContain("input-copy-copied");
+    });
   });
 });

package/app/components/02.molecules/progress-tracker/CONSUMER-STYLING.md

@@ -0,0 +1,116 @@
+# ProgressTracker — Consumer Styling Guide
+
+## Public token API
+
+All `--progress-tracker-*` tokens are the stable override surface. Set them on an ancestor you
+own, or on a class added with `:style-class-passthrough`.
+
+### Colours
+
+| Token | Default | Controls |
+|---|---|---|
+| `--progress-tracker-accent` | `var(--theme-accent)` | Done indicator fill, current indicator outline and number, connectors below done steps, progress bar fill |
+| `--progress-tracker-on-accent` | `var(--theme-on-surface)` | Tick colour on the done indicator; keep it in contrast with the accent |
+| `--progress-tracker-track` | `--theme-text` mixed to 15% | Progress bar track, upcoming indicator outline, connectors below current and upcoming steps |
+| `--progress-tracker-ring-colour` | `--theme-accent` mixed to 20% | Halo around the current indicator |
+| `--progress-tracker-upcoming-text` | `--theme-text` mixed to 60% | Upcoming step numbers, titles and bodies |
+| `--progress-tracker-title-colour` | `var(--theme-text)` | Done and current step titles |
+| `--progress-tracker-body-colour` | `--theme-text` mixed to 80% | Done and current step bodies |
+| `--progress-tracker-label-colour` | `--theme-text` mixed to 70% | Header label |
+
+### Header
+
+| Token | Default | Controls |
+|---|---|---|
+| `--progress-tracker-header-gap` | `2.4rem` | Space between the header and the first step |
+| `--progress-tracker-label-font-family` | `inherit` | Header label font (e.g. a monospace stack) |
+| `--progress-tracker-label-font-size` | `var(--step-4)` | Header label size |
+| `--progress-tracker-label-font-weight` | `600` | Header label weight |
+| `--progress-tracker-label-letter-spacing` | `0.12em` | Header label tracking |
+| `--progress-tracker-label-text-transform` | `uppercase` | Header label case; `none` keeps the prop's casing |
+| `--progress-tracker-bar-inline-size` | `16rem` | Preferred bar width; it shrinks first and wraps below the label when space runs out |
+| `--progress-tracker-bar-height` | `0.6rem` | Bar thickness |
+| `--progress-tracker-bar-radius` | `99rem` | Bar corner rounding |
+
+### Steps and indicators
+
+| Token | Default | Controls |
+|---|---|---|
+| `--progress-tracker-gap` | `4rem` | Space between the indicator column and the step content |
+| `--progress-tracker-step-padding-block` | `1.2rem` | Vertical padding of each step row |
+| `--progress-tracker-connector-width` | `0.2rem` | Connector line thickness |
+| `--progress-tracker-indicator-size` | `4.4rem` | Indicator width and height; titles are centred against it |
+| `--progress-tracker-indicator-border-width` | `0.2rem` | Indicator outline width |
+| `--progress-tracker-indicator-radius` | `50%` | Indicator shape; `0.8rem` gives rounded squares |
+| `--progress-tracker-indicator-font-size` | `var(--step-4)` | Step number size |
+| `--progress-tracker-ring-width` | `0.6rem` | Halo width around the current indicator |
+| `--progress-tracker-content-gap` | `0.8rem` | Space between title, body and slot content in a step |
+| `--progress-tracker-slot-gap` | `0.8rem` | Extra space above the `#step-{n}` slot content |
+| `--progress-tracker-title-font-size` | `var(--step-5)` | Step title size |
+| `--progress-tracker-title-font-weight` | `600` | Step title weight |
+| `--progress-tracker-title-line-clamp` | `none` | Lines before a title is cut off with an ellipsis (`1` is single-line) |
+| `--progress-tracker-body-font-size` | `var(--step-4)` | Step body size |
+| `--progress-tracker-body-line-clamp` | `none` | Lines before a body is cut off with an ellipsis |
+
+### Focus card (current step)
+
+| Token | Default | Controls |
+|---|---|---|
+| `--progress-tracker-card-surface` | `var(--theme-surface-subtle)` | Card background; set `#ffffff` (or similar) to lift it off a grey panel |
+| `--progress-tracker-card-shadow` | soft two-layer shadow | Card shadow; `none` for a flat card |
+| `--progress-tracker-card-radius` | `1.6rem` | Card corner rounding |
+| `--progress-tracker-card-padding-block` | `1.6rem` | Card top and bottom padding; the current indicator moves down by the same amount to stay level with the title |
+| `--progress-tracker-card-padding-inline` | `2rem` | Card side padding; the card bleeds left by the same amount so its text lines up with the other steps. Clearance between the current ring and the card is `--progress-tracker-gap` minus this minus `--progress-tracker-ring-width` (1.4rem by default), so raise the gap with it |
+
+### Motion
+
+| Token | Default | Controls |
+|---|---|---|
+| `--progress-tracker-transition-duration` | `200ms` | Bar fill and state colour transitions. Off under `prefers-reduced-motion: reduce` |
+
+Private (not public API): `--_progress-tracker-progress`, the done fraction the component sets
+inline on the bar.
+
+---
+
+## State hooks
+
+| Hook | Element | When |
+|---|---|---|
+| `.is-complete` | root | The model equals `steps.length` |
+| `.is-done`, `.is-current`, `.is-upcoming` | `.progress-tracker-step` and `.progress-tracker-indicator` | That step's state |
+| `aria-current="step"` | `.progress-tracker-title` | The current step |
+
+Inner classes: `.progress-tracker-header`, `.progress-tracker-label`, `.progress-tracker-bar`,
+`.progress-tracker-bar-fill`, `.progress-tracker-list` (the StepperList root),
+`.progress-tracker-indicator`, `.progress-tracker-indicator-icon`, `.progress-tracker-step`,
+`.progress-tracker-title`, `.progress-tracker-body`, `.progress-tracker-slot`.
+
+---
+
+## 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: StepperList tokens.** The list is a `StepperList`, and ProgressTracker sets its
+`--stepper-list-*` tokens on `.progress-tracker-list` from its own tokens. A `--stepper-list-*`
+value set on an ancestor never reaches it; use the `--progress-tracker-*` equivalents
+(`-gap`, `-step-padding-block`, `-connector-width`, `-accent`, `-track`).
+
+---
+
+## Class passthrough
+
+`style-class-passthrough` adds classes to the root `div`. Tokens set on a passthrough class apply to
+the whole tracker. Reactive after mount.
+
+---
+
+## Notes
+
+- Title centring against the indicator uses the `lh` unit. Safari before 16.4 ignores it and the
+  title sits level with the top of the indicator instead.