srcdev-nuxt-components 9.4.11 → 9.5.0

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

@@ -1,19 +1,34 @@
 <template>
-  <div :class="['samaritan-prompt', elementClasses]">
-    <div class="samaritan-prompt__content" :style="effect === 'word-pulse' ? { opacity: textOpacity } : undefined">
+  <div
+    :class="['samaritan-prompt', elementClasses]"
+    :style="{ '--_fade-duration': fadeDurationCss }"
+    :data-paused="isPaused || undefined"
+    @pointerenter="pause"
+    @pointerleave="resume"
+  >
+    <div
+      class="samaritan-prompt__content"
+      :style="effect === 'word-pulse' ? { opacity: textOpacity } : undefined"
+      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">
+import type { SamaritanPromptEffect } from "~/types/components/samaritan-prompt";
+
 interface Props {
   messages: string[];
-  effect?: "typewriter" | "word-pulse";
+  effect?: SamaritanPromptEffect;
   typeSpeed?: number;
   deleteSpeed?: number;
   holdDuration?: number;
@@ -36,19 +51,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 fadeDurationCss = computed(() => `${props.fadeDuration}ms`);
 const cursorOpacity = computed(() => (props.hideCursorInCycle && !cursorVisible.value ? 0 : 1));
 
-const { wait, schedule, stop, start } = useCancellableTimer();
+const timer = useCancellableTimer();
+const { wait, schedule, stop, start } = timer;
+
+const pause = () => {
+  isPaused.value = true;
+  timer.pause();
+};
+
+const resume = () => {
+  isPaused.value = false;
+  timer.resume();
+};
 
 const startEffect = () => {
   start();
   displayText.value = "";
+  announcedText.value = "";
   textOpacity.value = 1;
   cursorVisible.value = true;
   phase.value = "typing";
@@ -79,12 +113,14 @@ const typeTick = () => {
         schedule(typeTick, props.typeSpeed);
       } else {
         phase.value = "holding";
+        announcedText.value = message;
         schedule(typeTick, props.holdDuration);
       }
       break;
 
     case "holding":
       phase.value = "deleting";
+      announcedText.value = "";
       schedule(typeTick, props.deleteSpeed);
       break;
 
@@ -111,12 +147,10 @@ const typeTick = () => {
 const runWordPulse = async () => {
   try {
     while (true) {
-      // Underline and cursor visible during the pre-cycle pause
       await wait(props.pauseDuration);
 
       if (props.hideCursorInCycle) cursorVisible.value = false;
 
-      // Fade out the underline before the first word appears
       textOpacity.value = 0;
       await wait(props.fadeDuration);
 
@@ -126,13 +160,14 @@ const runWordPulse = async () => {
         await wait(120);
 
         textOpacity.value = 1;
+        announcedText.value = message;
         await wait(props.wordDuration);
 
+        announcedText.value = "";
         textOpacity.value = 0;
         await wait(props.fadeDuration);
       }
 
-      // Reset between cycles — underline and cursor visible again for next pause
       displayText.value = "";
       textOpacity.value = 1;
       if (props.hideCursorInCycle) cursorVisible.value = true;
@@ -165,67 +200,89 @@ onUnmounted(stop);
   font-display: swap;
 }
 
-.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);
-
-  .samaritan-prompt__content {
+@layer components {
+  .samaritan-prompt {
     display: flex;
     flex-direction: column;
     align-items: center;
-    row-gap: 0.6rem;
-    width: 100%;
-    transition: opacity v-bind(fadeDurationCss) ease;
+    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__stage {
+    .samaritan-prompt__content {
       display: flex;
-      justify-content: center;
-      min-height: 1.2em;
+      flex-direction: column;
+      align-items: center;
+      row-gap: var(--samaritan-prompt-underline-gap, 0.6rem);
+      width: 100%;
+      transition: opacity var(--_fade-duration, 400ms) ease;
 
-      .samaritan-prompt__text {
-        color: var(--_color-text);
-        white-space: nowrap;
-        text-transform: uppercase;
+      .samaritan-prompt__stage {
+        display: flex;
+        justify-content: center;
+        min-height: 1.2em;
+
+        .samaritan-prompt__text {
+          color: var(--samaritan-prompt-text-colour, #ffffff);
+          white-space: nowrap;
+          text-transform: var(--samaritan-prompt-text-transform, uppercase);
+        }
+      }
+
+      .samaritan-prompt__underline {
+        width: 100%;
+        min-width: 4ch;
+        height: var(--samaritan-prompt-underline-height, 0.15rem);
+        background: var(--samaritan-prompt-underline-colour, #ffffff);
       }
     }
 
-    .samaritan-prompt__underline {
-      width: 100%;
-      min-width: 4ch;
-      height: 0.15rem;
-      background: var(--_color-underline);
+    .samaritan-prompt__cursor {
+      color: var(--samaritan-prompt-cursor-colour, #cc0000);
+      font-size: var(--samaritan-prompt-cursor-size, 2.4rem);
+      line-height: 1;
+      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;
+      height: 1px;
+      padding: 0;
+      margin: -1px;
+      overflow: hidden;
+      clip: rect(0, 0, 0, 0);
+      white-space: nowrap;
+      border: 0;
     }
   }
 
-  .samaritan-prompt__cursor {
-    color: var(--_color-cursor);
-    font-size: 2.4rem;
-    line-height: 1;
-    animation: samaritan-pulse 2.5s ease-in-out infinite;
-    transition: opacity 400ms ease;
+  @media (prefers-reduced-motion: reduce) {
+    .samaritan-prompt {
+      .samaritan-prompt__content {
+        transition: 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/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>
+    `,
+  }),
+};