srcdev-nuxt-components 9.4.12 → 9.5.1

package/app/components/02.molecules/samaritan-prompt/SamaritanPromptMixed.vue

@@ -1,32 +1,30 @@
 <template>
-  <div :class="['samaritan-prompt', elementClasses]">
+  <div
+    :class="['samaritan-prompt', elementClasses]"
+    :style="{ '--_fade-duration': fadeDurationCss }"
+    :data-paused="isPaused || undefined"
+    @pointerenter="pause"
+    @pointerleave="resume"
+  >
     <div class="samaritan-prompt__content" :style="{ opacity: textOpacity }" aria-hidden="true">
       <div class="samaritan-prompt__stage">
         <span class="samaritan-prompt__text">{{ displayText }}</span>
       </div>
       <div class="samaritan-prompt__underline"></div>
     </div>
-    <span class="samaritan-prompt__cursor" :style="{ opacity: cursorOpacity }" aria-hidden="true">▲</span>
+    <span class="samaritan-prompt__cursor" :style="{ opacity: cursorOpacity }" aria-hidden="true">
+      <slot name="cursor">▲</slot>
+    </span>
     <span class="samaritan-prompt__sr-text" aria-live="polite" aria-atomic="true">{{ announcedText }}</span>
   </div>
 </template>
 
 <script setup lang="ts">
-export interface MessageConfig {
-  text: string;
-  effect?: "typewriter" | "word-pulse";
-  typeSpeed?: number;
-  deleteSpeed?: number;
-  holdDuration?: number;
-  pauseDuration?: number;
-  wordDuration?: number;
-  fadeDuration?: number;
-  hideCursorInCycle?: boolean;
-}
+import type { SamaritanPromptEffect, SamaritanPromptMessageConfig } from "~/types/components/samaritan-prompt";
 
 interface Props {
-  messageConfigs: MessageConfig[];
-  effect?: "typewriter" | "word-pulse";
+  messageConfigs: SamaritanPromptMessageConfig[];
+  effect?: SamaritanPromptEffect;
   typeSpeed?: number;
   deleteSpeed?: number;
   holdDuration?: number;
@@ -51,21 +49,38 @@ const props = withDefaults(defineProps<Props>(), {
   styleClassPassthrough: () => [],
 });
 
-const { elementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
+const { elementClasses, resetElementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
+
+watch(
+  () => props.styleClassPassthrough,
+  () => resetElementClasses(props.styleClassPassthrough)
+);
 
 const displayText = ref("");
 const announcedText = ref("");
 const textOpacity = ref(1);
 const cursorVisible = ref(true);
+const isPaused = ref(false);
 const activeFadeDuration = ref(props.fadeDuration);
 const fadeDurationCss = computed(() => `${activeFadeDuration.value}ms`);
 const cursorOpacity = computed(() => (cursorVisible.value ? 1 : 0));
 
-const { wait, stop, start } = useCancellableTimer();
+const timer = useCancellableTimer();
+const { wait, stop, start } = timer;
+
+const pause = () => {
+  isPaused.value = true;
+  timer.pause();
+};
+
+const resume = () => {
+  isPaused.value = false;
+  timer.resume();
+};
 
-type ResolvedConfig = Required<MessageConfig>;
+type ResolvedConfig = Required<SamaritanPromptMessageConfig>;
 
-const resolveConfig = (msg: MessageConfig): ResolvedConfig => ({
+const resolveConfig = (msg: SamaritanPromptMessageConfig): ResolvedConfig => ({
   text: msg.text,
   effect: msg.effect ?? props.effect,
   typeSpeed: msg.typeSpeed ?? props.typeSpeed,
@@ -136,8 +151,6 @@ const runLoop = async () => {
     while (true) {
       if (props.introDelay > 0) await wait(props.introDelay);
 
-      // if (props.hideCursorInCycle) cursorVisible.value = false;
-
       for (const msg of props.messageConfigs) {
         const config = resolveConfig(msg);
         if (config.effect === "typewriter") {
@@ -146,8 +159,6 @@ const runLoop = async () => {
           await runWordPulse(config);
         }
       }
-
-      // if (props.hideCursorInCycle) cursorVisible.value = true;
     }
   } catch {
     // component unmounted — exit cleanly
@@ -175,37 +186,23 @@ onUnmounted(stop);
   font-display: optional;
 }
 
-.samaritan-stage {
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  min-block-size: 100dvh;
-  width: 100%;
-
+@layer components {
   .samaritan-prompt {
-    --_font-size: var(--samaritan-font-size, 2rem);
-    --_color-text: var(--samaritan-color-text, #ffffff);
-    --_color-underline: var(--samaritan-color-underline, #ffffff);
-    --_color-cursor: var(--samaritan-color-cursor, #cc0000);
-    --_color-cursor-off: var(--samaritan-color-cursor-off, transparent);
-    --_font-family: var(--samaritan-font-family, "Mono MMM 5", "Nova Mono", "Courier New", monospace);
-    --_letter-spacing: var(--samaritan-letter-spacing, 0.08em);
-
     display: flex;
     flex-direction: column;
     align-items: center;
-    row-gap: 0.6rem;
-    font-family: var(--_font-family);
-    font-size: var(--_font-size);
-    letter-spacing: var(--_letter-spacing);
+    row-gap: var(--samaritan-prompt-cursor-gap, 0.6rem);
+    font-family: var(--samaritan-prompt-font-family, "Mono MMM 5", "Nova Mono", "Courier New", monospace);
+    font-size: var(--samaritan-prompt-font-size, 2rem);
+    letter-spacing: var(--samaritan-prompt-letter-spacing, 0.08em);
 
     .samaritan-prompt__content {
       display: flex;
       flex-direction: column;
       align-items: center;
-      row-gap: 0.6rem;
+      row-gap: var(--samaritan-prompt-underline-gap, 0.6rem);
       width: 100%;
-      transition: opacity v-bind(fadeDurationCss) ease;
+      transition: opacity var(--_fade-duration, 400ms) ease;
 
       .samaritan-prompt__stage {
         display: flex;
@@ -213,28 +210,32 @@ onUnmounted(stop);
         min-height: 1.2em;
 
         .samaritan-prompt__text {
-          color: var(--_color-text);
+          color: var(--samaritan-prompt-text-colour, #ffffff);
           white-space: nowrap;
-          text-transform: uppercase;
+          text-transform: var(--samaritan-prompt-text-transform, uppercase);
         }
       }
 
       .samaritan-prompt__underline {
         width: 100%;
         min-width: 4ch;
-        height: 0.15rem;
-        background: var(--_color-underline);
+        height: var(--samaritan-prompt-underline-height, 0.15rem);
+        background: var(--samaritan-prompt-underline-colour, #ffffff);
       }
     }
 
     .samaritan-prompt__cursor {
-      color: var(--_color-cursor);
-      font-size: 2.4rem;
+      color: var(--samaritan-prompt-cursor-colour, #cc0000);
+      font-size: var(--samaritan-prompt-cursor-size, 2.4rem);
       line-height: 1;
-      animation: samaritan-pulse 2.5s ease-in-out infinite;
+      animation: samaritan-prompt-pulse var(--samaritan-prompt-cursor-pulse-duration, 2.5s) ease-in-out infinite;
       transition: opacity 400ms ease;
     }
 
+    &[data-paused] .samaritan-prompt__cursor {
+      animation-play-state: paused;
+    }
+
     .samaritan-prompt__sr-text {
       position: absolute;
       width: 1px;
@@ -247,27 +248,27 @@ onUnmounted(stop);
       border: 0;
     }
   }
-}
 
-@media (prefers-reduced-motion: reduce) {
-  .samaritan-prompt {
-    .samaritan-prompt__content {
-      transition: none;
-    }
+  @media (prefers-reduced-motion: reduce) {
+    .samaritan-prompt {
+      .samaritan-prompt__content {
+        transition: none;
+      }
 
-    .samaritan-prompt__cursor {
-      animation: none;
+      .samaritan-prompt__cursor {
+        animation: none;
+      }
     }
   }
 }
 
-@keyframes samaritan-pulse {
+@keyframes samaritan-prompt-pulse {
   0%,
   100% {
-    color: var(--_color-cursor);
+    color: var(--samaritan-prompt-cursor-colour, #cc0000);
   }
   50% {
-    color: var(--_color-cursor-off);
+    color: var(--samaritan-prompt-cursor-colour-off, transparent);
   }
 }
 </style>

package/app/components/02.molecules/samaritan-prompt/stories/SamaritanPrompt.stories.ts

@@ -0,0 +1,129 @@
+import { computed } from "vue";
+import SamaritanPrompt from "../SamaritanPrompt.vue";
+import type { Meta, StoryObj } from "@nuxtjs/storybook";
+
+// The default colours are white on the assumption of a dark page, so every story renders on a dark
+// stage. Keying on the serialised args restarts the loop when a timing control changes, so the
+// new value is visible straight away instead of after the current cycle.
+const stageStyle =
+  "display: grid; place-items: center; min-block-size: 32rem; padding: 3.2rem; background: #000; color: #fff;";
+
+const timingArgTypes = {
+  typeSpeed: {
+    control: { type: "range", min: 10, max: 400, step: 10 },
+    description: "ms per character typed",
+    table: { category: "Typewriter", defaultValue: { summary: "80" } },
+  },
+  deleteSpeed: {
+    control: { type: "range", min: 10, max: 400, step: 10 },
+    description: "ms per character deleted",
+    table: { category: "Typewriter", defaultValue: { summary: "40" } },
+  },
+  holdDuration: {
+    control: { type: "range", min: 0, max: 10000, step: 100 },
+    description: "ms the fully typed text holds before deleting",
+    table: { category: "Typewriter", defaultValue: { summary: "2000" } },
+  },
+  pauseDuration: {
+    control: { type: "range", min: 0, max: 5000, step: 100 },
+    description: "ms pause between messages (typewriter) or cycles (word-pulse)",
+    table: { category: "Timing", defaultValue: { summary: "500" } },
+  },
+  wordDuration: {
+    control: { type: "range", min: 200, max: 5000, step: 100 },
+    description: "ms each word-pulse message stays fully visible",
+    table: { category: "Word pulse", defaultValue: { summary: "1200" } },
+  },
+  fadeDuration: {
+    control: { type: "range", min: 0, max: 2000, step: 50 },
+    description: "ms for the word-pulse fade in and out",
+    table: { category: "Word pulse", defaultValue: { summary: "400" } },
+  },
+  hideCursorInCycle: {
+    control: "boolean",
+    description: "Hide the cursor while text animates, show it during pauses",
+    table: { category: "Cursor", defaultValue: { summary: "true" } },
+  },
+} as const;
+
+const meta: Meta<typeof SamaritanPrompt> = {
+  title: "Molecules/SamaritanPrompt",
+  component: SamaritanPrompt,
+  argTypes: {
+    messages: {
+      control: "object",
+      description: "Messages to cycle through",
+      table: { category: "Content" },
+    },
+    effect: {
+      control: "inline-radio",
+      options: ["typewriter", "word-pulse"],
+      description: "Animation effect for every message",
+      table: { category: "Content", defaultValue: { summary: "typewriter" } },
+    },
+    ...timingArgTypes,
+    styleClassPassthrough: {
+      control: "object",
+      description: "Additional CSS classes applied to the root element",
+      table: { category: "Styling" },
+    },
+  },
+  args: {
+    messages: ["Can you hear me?", "Surveillance active", "Threat detected"],
+    effect: "typewriter",
+    typeSpeed: 80,
+    deleteSpeed: 40,
+    holdDuration: 2000,
+    pauseDuration: 500,
+    wordDuration: 1200,
+    fadeDuration: 400,
+    hideCursorInCycle: true,
+    styleClassPassthrough: [],
+  },
+  render: (args) => ({
+    components: { SamaritanPrompt },
+    setup() {
+      const restartKey = computed(() => JSON.stringify(args));
+      return { args, restartKey, stageStyle };
+    },
+    template: `
+      <div :style="stageStyle">
+        <SamaritanPrompt :key="restartKey" v-bind="args" />
+      </div>
+    `,
+  }),
+};
+
+export default meta;
+type Story = StoryObj<typeof SamaritanPrompt>;
+
+export const Typewriter: Story = {};
+
+export const WordPulse: Story = {
+  name: "Word Pulse",
+  args: {
+    effect: "word-pulse",
+  },
+};
+
+export const CustomCursorAndTokens: Story = {
+  name: "Custom Cursor and Tokens",
+  render: (args) => ({
+    components: { SamaritanPrompt },
+    setup() {
+      const restartKey = computed(() => JSON.stringify(args));
+      return { args, restartKey, stageStyle };
+    },
+    template: `
+      <div :style="stageStyle">
+        <SamaritanPrompt
+          :key="restartKey"
+          v-bind="args"
+          style="--samaritan-prompt-text-colour: #00ff88; --samaritan-prompt-underline-colour: #00ff88; --samaritan-prompt-cursor-colour: #ffcc00; --samaritan-prompt-font-size: 3.2rem;"
+        >
+          <template #cursor>&#9679;</template>
+        </SamaritanPrompt>
+      </div>
+    `,
+  }),
+};

package/app/components/02.molecules/samaritan-prompt/stories/SamaritanPromptMixed.stories.ts

@@ -0,0 +1,124 @@
+import { computed } from "vue";
+import SamaritanPromptMixed from "../SamaritanPromptMixed.vue";
+import type { Meta, StoryObj } from "@nuxtjs/storybook";
+import type { SamaritanPromptMessageConfig } from "~/types/components";
+
+// Dark stage because the default colours are white. Keying on the serialised args restarts the
+// loop when a control changes, so the new value is visible straight away.
+const stageStyle =
+  "display: grid; place-items: center; min-block-size: 32rem; padding: 3.2rem; background: #000; color: #fff;";
+
+const messageConfigs: SamaritanPromptMessageConfig[] = [
+  { text: "Good evening", effect: "typewriter", holdDuration: 2500 },
+  { text: "Stand by", effect: "word-pulse", wordDuration: 2000, fadeDuration: 800 },
+  { text: "Connection established", effect: "typewriter", typeSpeed: 50, holdDuration: 2500 },
+];
+
+const meta: Meta<typeof SamaritanPromptMixed> = {
+  title: "Molecules/SamaritanPromptMixed",
+  component: SamaritanPromptMixed,
+  argTypes: {
+    messageConfigs: {
+      control: "object",
+      description: "Messages, each optionally overriding the effect and timing props below",
+      table: { category: "Content" },
+    },
+    effect: {
+      control: "inline-radio",
+      options: ["typewriter", "word-pulse"],
+      description: "Default effect for messages that don't set their own",
+      table: { category: "Content", defaultValue: { summary: "typewriter" } },
+    },
+    introDelay: {
+      control: { type: "range", min: 0, max: 5000, step: 100 },
+      description: "ms before the first message of each loop",
+      table: { category: "Timing", defaultValue: { summary: "2000" } },
+    },
+    typeSpeed: {
+      control: { type: "range", min: 10, max: 400, step: 10 },
+      description: "ms per character typed",
+      table: { category: "Typewriter", defaultValue: { summary: "80" } },
+    },
+    deleteSpeed: {
+      control: { type: "range", min: 10, max: 400, step: 10 },
+      description: "ms per character deleted",
+      table: { category: "Typewriter", defaultValue: { summary: "40" } },
+    },
+    holdDuration: {
+      control: { type: "range", min: 0, max: 10000, step: 100 },
+      description: "ms the fully typed text holds before deleting",
+      table: { category: "Typewriter", defaultValue: { summary: "7000" } },
+    },
+    pauseDuration: {
+      control: { type: "range", min: 0, max: 5000, step: 100 },
+      description: "ms pause after each message",
+      table: { category: "Timing", defaultValue: { summary: "1000" } },
+    },
+    wordDuration: {
+      control: { type: "range", min: 200, max: 5000, step: 100 },
+      description: "ms a word-pulse message stays fully visible",
+      table: { category: "Word pulse", defaultValue: { summary: "1200" } },
+    },
+    fadeDuration: {
+      control: { type: "range", min: 0, max: 2000, step: 50 },
+      description: "ms for the word-pulse fade in and out",
+      table: { category: "Word pulse", defaultValue: { summary: "400" } },
+    },
+    hideCursorInCycle: {
+      control: "boolean",
+      description: "Hide the cursor while text animates, show it during pauses",
+      table: { category: "Cursor", defaultValue: { summary: "true" } },
+    },
+    styleClassPassthrough: {
+      control: "object",
+      description: "Additional CSS classes applied to the root element",
+      table: { category: "Styling" },
+    },
+  },
+  args: {
+    messageConfigs,
+    effect: "typewriter",
+    introDelay: 500,
+    typeSpeed: 80,
+    deleteSpeed: 40,
+    holdDuration: 7000,
+    pauseDuration: 1000,
+    wordDuration: 1200,
+    fadeDuration: 400,
+    hideCursorInCycle: true,
+    styleClassPassthrough: [],
+  },
+  render: (args) => ({
+    components: { SamaritanPromptMixed },
+    setup() {
+      const restartKey = computed(() => JSON.stringify(args));
+      return { args, restartKey, stageStyle };
+    },
+    template: `
+      <div :style="stageStyle">
+        <SamaritanPromptMixed :key="restartKey" v-bind="args" />
+      </div>
+    `,
+  }),
+};
+
+export default meta;
+type Story = StoryObj<typeof SamaritanPromptMixed>;
+
+export const Default: Story = {};
+
+export const LightPage: Story = {
+  name: "Light Page (token override)",
+  render: (args) => ({
+    components: { SamaritanPromptMixed },
+    setup() {
+      const restartKey = computed(() => JSON.stringify(args));
+      return { args, restartKey };
+    },
+    template: `
+      <div style="display: grid; place-items: center; min-block-size: 32rem; padding: 3.2rem; background: #fff; --samaritan-prompt-text-colour: #000; --samaritan-prompt-underline-colour: #000;">
+        <SamaritanPromptMixed :key="restartKey" v-bind="args" />
+      </div>
+    `,
+  }),
+};

package/app/components/02.molecules/samaritan-prompt/tests/SamaritanPrompt.spec.ts

@@ -366,3 +366,69 @@ describe("SamaritanPrompt — word-pulse", () => {
     expect(wrapper.find(".samaritan-prompt__cursor").attributes("style")).toContain("opacity: 1");
   });
 });
+
+// ─── Accessibility, pause and slots ─────────────────────────────────────────
+
+describe("SamaritanPrompt — accessibility and pause", () => {
+  it("hides the animated content from assistive tech and exposes a polite live region", async () => {
+    const wrapper = await mountSuspended(SamaritanPrompt, { props: { messages } });
+    expect(wrapper.find(".samaritan-prompt__content").attributes("aria-hidden")).toBe("true");
+    const live = wrapper.find(".samaritan-prompt__sr-text");
+    expect(live.attributes("aria-live")).toBe("polite");
+    expect(live.attributes("aria-atomic")).toBe("true");
+    expect(live.text()).toBe("");
+  });
+
+  it("announces the full message once typed, and clears it when deleting starts", async () => {
+    const wrapper = await mountSuspended(SamaritanPrompt, {
+      props: { messages, typeSpeed: 10, holdDuration: 500, deleteSpeed: 10 },
+    });
+
+    vi.advanceTimersByTime(10 * (firstMessage.length + 1));
+    await nextTick();
+    expect(wrapper.find(".samaritan-prompt__sr-text").text()).toBe(firstMessage);
+
+    vi.advanceTimersByTime(500);
+    await nextTick();
+    expect(wrapper.find(".samaritan-prompt__sr-text").text()).toBe("");
+  });
+
+  it("stops typing while hovered and resumes on leave", async () => {
+    const wrapper = await mountSuspended(SamaritanPrompt, { props: { messages, typeSpeed: 100 } });
+    const root = wrapper.find(".samaritan-prompt");
+
+    vi.advanceTimersByTime(200);
+    await nextTick();
+    expect(wrapper.find(".samaritan-prompt__text").text()).toBe("He");
+
+    await root.trigger("pointerenter");
+    expect(root.attributes("data-paused")).toBeDefined();
+    vi.advanceTimersByTime(1000);
+    await nextTick();
+    expect(wrapper.find(".samaritan-prompt__text").text()).toBe("He");
+
+    await root.trigger("pointerleave");
+    expect(root.attributes("data-paused")).toBeUndefined();
+    vi.advanceTimersByTime(100);
+    await nextTick();
+    expect(wrapper.find(".samaritan-prompt__text").text()).toBe("Hel");
+  });
+
+  it("renders a custom cursor from the cursor slot", async () => {
+    const wrapper = await mountSuspended(SamaritanPrompt, {
+      props: { messages },
+      slots: { cursor: () => "_" },
+    });
+    expect(wrapper.find(".samaritan-prompt__cursor").text()).toBe("_");
+  });
+
+  it("updates passthrough classes when the prop changes", async () => {
+    const wrapper = await mountSuspended(SamaritanPrompt, {
+      props: { messages, styleClassPassthrough: "first-class" },
+    });
+    await wrapper.setProps({ styleClassPassthrough: "second-class" });
+    const classes = wrapper.find(".samaritan-prompt").classes();
+    expect(classes).toContain("second-class");
+    expect(classes).not.toContain("first-class");
+  });
+});