srcdev-nuxt-components 9.1.39 → 9.1.41

package/.claude/settings.local.json

@@ -24,7 +24,12 @@
       "Bash(git -C /Users/simoncornforth/websites/nuxt-components show 0f99d7a --stat)",
       "Bash(git -C /Users/simoncornforth/websites/nuxt-components diff app/components/parallax/SectionParallax.vue)",
       "Bash(git -C /Users/simoncornforth/websites/nuxt-components diff HEAD app/components/parallax/SectionParallax.vue)",
-      "Bash(git -C /Users/simoncornforth/websites/nuxt-components diff --cached)"
+      "Bash(git -C /Users/simoncornforth/websites/nuxt-components diff --cached)",
+      "Bash(SRCDEV_STANDALONE=true npx vitest --run app/components/02.molecules/samaritan-prompt)",
+      "Bash(SRCDEV_STANDALONE=true npx vitest --run app/composables/tests/useCancellableTimer app/components/02.molecules/samaritan-prompt/tests/SamaritanPromptMixed)",
+      "Bash(SRCDEV_STANDALONE=true npx vitest --run app/components/02.molecules/samaritan-prompt/tests/SamaritanPromptMixed)",
+      "Bash(SRCDEV_STANDALONE=true npx vitest --run app/composables/tests/useCancellableTimer)",
+      "Bash(SRCDEV_STANDALONE=true npm run test:run -- --reporter=verbose)"
     ],
     "additionalDirectories": [
       "/Users/simoncornforth/websites/nuxt-components/app/components/01.atoms/content-wrappers/content-width",

package/.claude/skills/testing-add-unit-test.md

@@ -182,6 +182,38 @@ await nextTick();
 vi.runAllTimers();
 ```
 
+## `mountSuspended` flushes component async setup — initial state may be past the first `await`
+
+`mountSuspended` calls `flushPromises()` internally, draining all pending microtasks including `await nextTick()` calls inside the component's async functions. If a component's async lifecycle starts with `await nextTick()` (e.g. to let a CSS `v-bind` update before beginning a transition), **the component will have already executed past it by the time `mountSuspended` returns**.
+
+Assert the post-flush state, not the state before the first await:
+
+```ts
+// Component's runEffect() starts with: await nextTick(); opacity.value = 0;
+// ❌ — by the time mountSuspended returns, opacity is already 0
+const wrapper = await mountSuspended(MyComponent, { props });
+expect(wrapper.find(".content").attributes("style")).toContain("opacity: 1");
+
+// ✅ — assert the state that exists after mountSuspended's flush
+const wrapper = await mountSuspended(MyComponent, { props });
+expect(wrapper.find(".content").attributes("style")).toContain("opacity: 0");
+```
+
+## `.then().catch()` requires two microtask hops; use `.then(onFulfilled, onRejected)` for one
+
+When asserting Promise settlement with a single `await Promise.resolve()`, put both handlers in the two-argument form of `.then()`. Chaining `.then().catch()` creates an intermediate Promise that adds a second hop, so `settled` won't be `true` after only one drain:
+
+```ts
+// ❌ needs two await Promise.resolve() to settle
+promise.then(() => { settled = true; }).catch(() => { settled = true; });
+
+// ✅ settles after one await Promise.resolve()
+promise.then(
+  () => { settled = true; },
+  () => { settled = true; },
+);
+```
+
 ## Hyphenated prop attributes in tests
 
 When a component uses a hyphenated Vue prop like `:tab-index` or `:aria-label`, Vue renders it as the literal hyphenated DOM attribute. Assert with the hyphenated form — not the camelCase equivalent:

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

@@ -0,0 +1,231 @@
+<template>
+  <div :class="['samaritan-prompt', elementClasses]">
+    <div class="samaritan-prompt__content" :style="effect === 'word-pulse' ? { opacity: textOpacity } : undefined">
+      <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>
+  </div>
+</template>
+
+<script setup lang="ts">
+interface Props {
+  messages: string[];
+  effect?: "typewriter" | "word-pulse";
+  typeSpeed?: number;
+  deleteSpeed?: number;
+  holdDuration?: number;
+  pauseDuration?: number;
+  wordDuration?: number;
+  fadeDuration?: number;
+  hideCursorInCycle?: boolean;
+  styleClassPassthrough?: string | string[];
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  effect: "typewriter",
+  typeSpeed: 80,
+  deleteSpeed: 40,
+  holdDuration: 2000,
+  pauseDuration: 500,
+  wordDuration: 1200,
+  fadeDuration: 400,
+  hideCursorInCycle: true,
+  styleClassPassthrough: () => [],
+});
+
+const { elementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
+
+const displayText = ref("");
+const textOpacity = ref(1);
+const cursorVisible = ref(true);
+const fadeDurationCss = computed(() => `${props.fadeDuration}ms`);
+const cursorOpacity = computed(() => (props.hideCursorInCycle && !cursorVisible.value ? 0 : 1));
+
+const { wait, schedule, stop, start } = useCancellableTimer();
+
+const startEffect = () => {
+  start();
+  displayText.value = "";
+  textOpacity.value = 1;
+  cursorVisible.value = true;
+  phase.value = "typing";
+  messageIndex.value = 0;
+  if (props.effect === "typewriter") {
+    schedule(typeTick, props.typeSpeed);
+  } else {
+    runWordPulse();
+  }
+};
+
+// --- Typewriter ---
+type Phase = "typing" | "holding" | "deleting" | "pausing";
+const phase = ref<Phase>("typing");
+const messageIndex = ref(0);
+
+const typeTick = () => {
+  const message = props.messages[messageIndex.value];
+  if (!message) return;
+
+  switch (phase.value) {
+    case "typing":
+      if (displayText.value.length === 0 && props.hideCursorInCycle) {
+        cursorVisible.value = false;
+      }
+      if (displayText.value.length < message.length) {
+        displayText.value = message.slice(0, displayText.value.length + 1);
+        schedule(typeTick, props.typeSpeed);
+      } else {
+        phase.value = "holding";
+        schedule(typeTick, props.holdDuration);
+      }
+      break;
+
+    case "holding":
+      phase.value = "deleting";
+      schedule(typeTick, props.deleteSpeed);
+      break;
+
+    case "deleting":
+      if (displayText.value.length > 0) {
+        displayText.value = displayText.value.slice(0, -1);
+        schedule(typeTick, props.deleteSpeed);
+      } else {
+        phase.value = "pausing";
+        if (props.hideCursorInCycle) cursorVisible.value = true;
+        schedule(typeTick, props.pauseDuration);
+      }
+      break;
+
+    case "pausing":
+      messageIndex.value = (messageIndex.value + 1) % props.messages.length;
+      phase.value = "typing";
+      schedule(typeTick, props.typeSpeed);
+      break;
+  }
+};
+
+// --- Word pulse ---
+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);
+
+      for (const message of props.messages) {
+        displayText.value = message;
+        await nextTick();
+        await wait(120);
+
+        textOpacity.value = 1;
+        await wait(props.wordDuration);
+
+        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;
+      await nextTick();
+    }
+  } catch {
+    // component unmounted — exit cleanly
+  }
+};
+
+watch(
+  () => props.effect,
+  () => {
+    stop();
+    startEffect();
+  }
+);
+
+onMounted(startEffect);
+
+onUnmounted(stop);
+</script>
+
+<style lang="css">
+@font-face {
+  font-family: "Mono MMM 5";
+  src: url("/fonts/monoMMM_5.ttf") format("truetype");
+  font-weight: normal;
+  font-style: normal;
+  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 {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    row-gap: 0.6rem;
+    width: 100%;
+    transition: opacity v-bind(fadeDurationCss) ease;
+
+    .samaritan-prompt__stage {
+      display: flex;
+      justify-content: center;
+      min-height: 1.2em;
+
+      .samaritan-prompt__text {
+        color: var(--_color-text);
+        white-space: nowrap;
+        text-transform: uppercase;
+      }
+    }
+
+    .samaritan-prompt__underline {
+      width: 100%;
+      min-width: 4ch;
+      height: 0.15rem;
+      background: var(--_color-underline);
+    }
+  }
+
+  .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;
+  }
+}
+
+@keyframes samaritan-pulse {
+  0%,
+  100% {
+    color: var(--_color-cursor);
+  }
+  50% {
+    color: var(--_color-cursor-off);
+  }
+}
+</style>

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

@@ -0,0 +1,235 @@
+<template>
+  <div :class="['samaritan-prompt', elementClasses]">
+    <div class="samaritan-prompt__content" :style="{ opacity: textOpacity }">
+      <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>
+  </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;
+}
+
+interface Props {
+  messageConfigs: MessageConfig[];
+  effect?: "typewriter" | "word-pulse";
+  typeSpeed?: number;
+  deleteSpeed?: number;
+  holdDuration?: number;
+  pauseDuration?: number;
+  wordDuration?: number;
+  fadeDuration?: number;
+  introDelay?: number;
+  hideCursorInCycle?: boolean;
+  styleClassPassthrough?: string | string[];
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  effect: "typewriter",
+  typeSpeed: 80,
+  deleteSpeed: 40,
+  holdDuration: 7000,
+  pauseDuration: 1000,
+  wordDuration: 1200,
+  fadeDuration: 400,
+  introDelay: 2000,
+  hideCursorInCycle: true,
+  styleClassPassthrough: () => [],
+});
+
+const { elementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
+
+const displayText = ref("");
+const textOpacity = ref(1);
+const cursorVisible = ref(true);
+const activeFadeDuration = ref(props.fadeDuration);
+const fadeDurationCss = computed(() => `${activeFadeDuration.value}ms`);
+const cursorOpacity = computed(() => (cursorVisible.value ? 1 : 0));
+
+const { wait, stop, start } = useCancellableTimer();
+
+type ResolvedConfig = Required<MessageConfig>;
+
+const resolveConfig = (msg: MessageConfig): ResolvedConfig => ({
+  text: msg.text,
+  effect: msg.effect ?? props.effect,
+  typeSpeed: msg.typeSpeed ?? props.typeSpeed,
+  deleteSpeed: msg.deleteSpeed ?? props.deleteSpeed,
+  holdDuration: msg.holdDuration ?? props.holdDuration,
+  pauseDuration: msg.pauseDuration ?? props.pauseDuration,
+  wordDuration: msg.wordDuration ?? props.wordDuration,
+  fadeDuration: msg.fadeDuration ?? props.fadeDuration,
+  hideCursorInCycle: msg.hideCursorInCycle ?? props.hideCursorInCycle,
+});
+
+const runTypewriter = async (config: ResolvedConfig) => {
+  const { text, typeSpeed, deleteSpeed, holdDuration, pauseDuration, hideCursorInCycle } = config;
+
+  if (hideCursorInCycle) cursorVisible.value = false;
+
+  for (let i = 1; i <= text.length; i++) {
+    displayText.value = text.slice(0, i);
+    await wait(typeSpeed);
+  }
+
+  await wait(holdDuration);
+
+  while (displayText.value.length > 0) {
+    displayText.value = displayText.value.slice(0, -1);
+    await wait(deleteSpeed);
+  }
+
+  if (hideCursorInCycle) cursorVisible.value = true;
+  await wait(pauseDuration);
+};
+
+const runWordPulse = async (config: ResolvedConfig) => {
+  const { text, fadeDuration, wordDuration, pauseDuration, hideCursorInCycle } = config;
+
+  activeFadeDuration.value = fadeDuration;
+  await nextTick();
+
+  if (hideCursorInCycle) cursorVisible.value = false;
+
+  textOpacity.value = 0;
+  await wait(fadeDuration);
+
+  displayText.value = text;
+  await nextTick();
+  await wait(120);
+
+  textOpacity.value = 1;
+  await wait(wordDuration);
+
+  textOpacity.value = 0;
+  await wait(fadeDuration);
+
+  displayText.value = "";
+  textOpacity.value = 1;
+  if (hideCursorInCycle) cursorVisible.value = true;
+  await nextTick();
+
+  await wait(pauseDuration);
+};
+
+const runLoop = async () => {
+  try {
+    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") {
+          await runTypewriter(config);
+        } else {
+          await runWordPulse(config);
+        }
+      }
+
+      // if (props.hideCursorInCycle) cursorVisible.value = true;
+    }
+  } catch {
+    // component unmounted — exit cleanly
+  }
+};
+
+const startLoop = () => {
+  start();
+  displayText.value = "";
+  textOpacity.value = 1;
+  cursorVisible.value = true;
+  runLoop();
+};
+
+onMounted(startLoop);
+onUnmounted(stop);
+</script>
+
+<style lang="css">
+@font-face {
+  font-family: "Mono MMM 5";
+  src: url("/fonts/monoMMM_5.ttf") format("truetype");
+  font-weight: normal;
+  font-style: normal;
+  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 {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    row-gap: 0.6rem;
+    width: 100%;
+    transition: opacity v-bind(fadeDurationCss) ease;
+
+    .samaritan-prompt__stage {
+      display: flex;
+      justify-content: center;
+      min-height: 1.2em;
+
+      .samaritan-prompt__text {
+        color: var(--_color-text);
+        white-space: nowrap;
+        text-transform: uppercase;
+      }
+    }
+
+    .samaritan-prompt__underline {
+      width: 100%;
+      min-width: 4ch;
+      height: 0.15rem;
+      background: var(--_color-underline);
+    }
+  }
+
+  .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;
+  }
+}
+
+@keyframes samaritan-pulse {
+  0%,
+  100% {
+    color: var(--_color-cursor);
+  }
+  50% {
+    color: var(--_color-cursor-off);
+  }
+}
+</style>