From 9ba03850e96f42dc73f15312cf7d11fd44059531 Mon Sep 17 00:00:00 2001
From: Jian Qi <e.jianqi@gmail.com>
Date: Wed, 25 Feb 2026 16:56:37 +0800
Subject: [PATCH] feat(TrueFocus): add syncGroup and index props for
 multi-instance sync

---
 .../TextAnimations/TrueFocus/TrueFocus.vue    | 118 ++++++++++++------
 src/demo/TextAnimations/TrueFocusDemo.vue     |  26 +++-
 2 files changed, 107 insertions(+), 37 deletions(-)

diff --git a/src/content/TextAnimations/TrueFocus/TrueFocus.vue b/src/content/TextAnimations/TrueFocus/TrueFocus.vue
index 68bdfd7..46e737f 100644
--- a/src/content/TextAnimations/TrueFocus/TrueFocus.vue
+++ b/src/content/TextAnimations/TrueFocus/TrueFocus.vue
@@ -1,6 +1,6 @@
 <script setup lang="ts">
 import { motion } from 'motion-v';
-import { computed, nextTick, onMounted, onUnmounted, ref, watch, useTemplateRef } from 'vue';
+import { computed, nextTick, onMounted, onUnmounted, ref, watch, useTemplateRef, type Ref } from 'vue';
 
 interface TrueFocusProps {
   sentence?: string;
@@ -10,6 +10,8 @@ interface TrueFocusProps {
   glowColor?: string;
   animationDuration?: number;
   pauseBetweenAnimations?: number;
+  index?: Array<number>;
+  syncGroup?: string;
 }
 
 const props = withDefaults(defineProps<TrueFocusProps>(), {
@@ -23,7 +25,8 @@ const props = withDefaults(defineProps<TrueFocusProps>(), {
 });
 
 const words = computed(() => props.sentence.split(' '));
-const currentIndex = ref(0);
+
+const currentIndex = props.syncGroup ? getSyncGroupIndex(props.syncGroup) : ref(-1);
 const lastActiveIndex = ref<number | null>(null);
 const containerRef = useTemplateRef<HTMLDivElement>('containerRef');
 const wordRefs = ref<HTMLSpanElement[]>([]);
@@ -35,12 +38,19 @@ watch(
   [currentIndex, () => words.value.length],
   async () => {
     if (currentIndex.value === null || currentIndex.value === -1) return;
-    if (!wordRefs.value[currentIndex.value] || !containerRef.value) return;
+
+    let actualWordIndex = currentIndex.value;
+    if (props.index) {
+      actualWordIndex = props.index.findIndex(val => val === currentIndex.value);
+      if (actualWordIndex === -1) return;
+    }
+
+    if (!wordRefs.value[actualWordIndex] || !containerRef.value) return;
 
     await nextTick();
 
     const parentRect = containerRef.value.getBoundingClientRect();
-    const activeRect = wordRefs.value[currentIndex.value].getBoundingClientRect();
+    const activeRect = wordRefs.value[actualWordIndex].getBoundingClientRect();
 
     focusRect.value = {
       x: activeRect.left - parentRect.left,
@@ -54,8 +64,9 @@ watch(
 
 const handleMouseEnter = (index: number) => {
   if (props.manualMode) {
-    lastActiveIndex.value = index;
-    currentIndex.value = index;
+    const mappedIndex = props.index ? props.index[index] : index;
+    lastActiveIndex.value = mappedIndex;
+    currentIndex.value = mappedIndex;
   }
 };
 
@@ -66,18 +77,35 @@ const handleMouseLeave = () => {
 };
 
 const setWordRef = (el: HTMLSpanElement | null, index: number) => {
-  if (el) {
-    wordRefs.value[index] = el;
+  if (el) wordRefs.value[index] = el;
+};
+
+const startInterval = () => {
+  if (interval) clearInterval(interval);
+  if (!props.manualMode) {
+    interval = setInterval(
+      () => {
+        currentIndex.value = (currentIndex.value + 1) % words.value.length;
+      },
+      (props.animationDuration + props.pauseBetweenAnimations) * 1000
+    );
   }
 };
 
 onMounted(async () => {
   await nextTick();
 
-  if (wordRefs.value[0] && containerRef.value) {
-    const parentRect = containerRef.value.getBoundingClientRect();
-    const activeRect = wordRefs.value[0].getBoundingClientRect();
+  const isOwner = props.syncGroup ? registerSyncGroup(props.syncGroup) : true;
 
+  let initialWordIndex = 0;
+  if (props.index && currentIndex.value !== null && currentIndex.value !== undefined) {
+    const foundIndex = props.index.findIndex(val => val === currentIndex.value);
+    if (foundIndex !== -1) initialWordIndex = foundIndex;
+  }
+
+  if (wordRefs.value[initialWordIndex] && containerRef.value) {
+    const parentRect = containerRef.value.getBoundingClientRect();
+    const activeRect = wordRefs.value[initialWordIndex].getBoundingClientRect();
     focusRect.value = {
       x: activeRect.left - parentRect.left,
       y: activeRect.top - parentRect.top,
@@ -86,43 +114,63 @@ onMounted(async () => {
     };
   }
 
-  watch(
-    [() => props.manualMode, () => props.animationDuration, () => props.pauseBetweenAnimations, () => words.value],
-    () => {
-      if (interval) {
-        clearInterval(interval);
-        interval = null;
-      }
-
-      if (!props.manualMode) {
-        interval = setInterval(
-          () => {
-            currentIndex.value = (currentIndex.value + 1) % words.value.length;
-          },
-          (props.animationDuration + props.pauseBetweenAnimations) * 1000
-        );
-      }
-    },
-    { immediate: true }
-  );
+  if (isOwner) {
+    watch(
+      [() => props.manualMode, () => props.animationDuration, () => props.pauseBetweenAnimations, () => words.value],
+      () => startInterval(),
+      { immediate: true }
+    );
+  }
 });
 
 onUnmounted(() => {
-  if (interval) {
-    clearInterval(interval);
-  }
+  if (interval) clearInterval(interval);
+  if (props.syncGroup) unregisterSyncGroup(props.syncGroup);
 });
 </script>
+<script lang="ts">
+interface SyncGroupState {
+  index: Ref<number>;
+  count: number;
+}
+
+export const syncGroupMap = new Map<string, SyncGroupState>();
+
+export function getSyncGroupIndex(group: string): Ref<number> {
+  if (!syncGroupMap.has(group)) {
+    syncGroupMap.set(group, { index: ref(-1), count: 0 });
+  }
+  return syncGroupMap.get(group)!.index;
+}
+
+export function registerSyncGroup(group: string): boolean {
+  const state = syncGroupMap.get(group)!;
+  state.count += 1;
+  return state.count === 1;
+}
+
+export function unregisterSyncGroup(group: string): void {
+  if (!syncGroupMap.has(group)) return;
+  const state = syncGroupMap.get(group)!;
+  state.count -= 1;
+  if (state.count <= 0) {
+    syncGroupMap.delete(group);
+  }
+}
+</script>
 
 <template>
   <div class="relative flex flex-wrap justify-center items-center gap-[1em]" ref="containerRef">
     <span
       v-for="(word, index) in words"
-      :key="index"
+      :key="props.index ? props.index[index] : index"
       :ref="el => setWordRef(el as HTMLSpanElement, index)"
       class="relative font-black text-7xl transition-[filter,color] duration-300 ease-in-out cursor-pointer"
       :style="{
-        filter: index === currentIndex ? 'blur(0px)' : `blur(${blurAmount}px)`,
+        filter:
+          currentIndex === -1 || (props.index ? props.index[index] : index) === currentIndex
+            ? 'blur(0px)'
+            : `blur(${blurAmount}px)`,
         '--border-color': borderColor,
         '--glow-color': glowColor,
         transition: `filter ${animationDuration}s ease`
diff --git a/src/demo/TextAnimations/TrueFocusDemo.vue b/src/demo/TextAnimations/TrueFocusDemo.vue
index 9a8924d..da527c7 100644
--- a/src/demo/TextAnimations/TrueFocusDemo.vue
+++ b/src/demo/TextAnimations/TrueFocusDemo.vue
@@ -3,7 +3,9 @@
     <template #preview>
       <div class="demo-container h-[400px]">
         <div :key="key" class="flex flex-col justify-center items-center m-8 pl-6 w-full">
-          <TrueFocus :key="key" v-bind="config" />
+          <TrueFocus :key="`${key}-${syncMode}-1`" v-bind="config" />
+          <br />
+          <TrueFocus :key="`${key}-${syncMode}-2`" v-bind="config" />
         </div>
       </div>
 
@@ -12,6 +14,8 @@
 
         <PreviewSwitch title="Hover Mode" v-model="manualMode" />
 
+        <PreviewSwitch title="Apply Sync Group" v-model="syncMode" />
+
         <PreviewSlider title="Blur Amount" v-model="blurAmount" :min="0" :max="15" :step="0.5" value-unit="px" />
 
         <PreviewSlider
@@ -72,6 +76,8 @@ const blurAmount = ref(5);
 const animationDuration = ref(0.5);
 const pauseBetweenAnimations = ref(1);
 const borderColor = ref('#27FF64');
+const syncMode = ref(false);
+const defaultBlur = ref(true);
 
 const config = computed(() => ({
   sentence: 'True Focus',
@@ -79,7 +85,9 @@ const config = computed(() => ({
   blurAmount: blurAmount.value,
   borderColor: borderColor.value,
   animationDuration: animationDuration.value,
-  pauseBetweenAnimations: pauseBetweenAnimations.value
+  pauseBetweenAnimations: pauseBetweenAnimations.value,
+  syncGroup: syncMode.value ? 'sync-group-demo' : undefined,
+  defaultBlur: defaultBlur.value
 }));
 
 const propData = [
@@ -124,6 +132,20 @@ const propData = [
     type: 'number',
     default: '1',
     description: 'Time to pause between focusing on each word (in auto mode).'
+  },
+  {
+    name: 'index',
+    type: 'Array<number>',
+    default: 'undefined',
+    description:
+      'Maps each word to a shared index value, used to coordinate focus position across multiple instances in the same syncGroup.'
+  },
+  {
+    name: 'syncGroup',
+    type: 'string',
+    default: 'undefined',
+    description:
+      'A group identifier. All instances sharing the same syncGroup will stay in sync, hovering or animating one will reflect on all others.'
   }
 ];
 </script>