feat(toHighlight): add new utility (#222)

Co-authored-by: John Leider <john@vuetifyjs.com>

Author: J-Sek

apps/docs/src/examples/composables/create-filter/live-search.vue

@@ -1,5 +1,5 @@
 <script setup lang="ts">
-  import { createFilter } from '@vuetify/v0'
+  import { createFilter, toHighlight } from '@vuetify/v0'
   import { computed, shallowRef } from 'vue'
 
   const cities = [
@@ -21,11 +21,7 @@
   const filter = createFilter({ keys: ['name', 'country'] })
   const { items } = filter.apply(query, cities)
 
-  function highlight (text: string) {
-    if (!query.value) return text
-    const regex = new RegExp(`(${query.value})`, 'gi')
-    return text.replace(regex, '<mark class="bg-warning text-on-warning rounded px-0.5">$1</mark>')
-  }
+  const highlightOptions = { ignoreCase: true, matchAll: true }
 
   const hasResults = computed(() => items.value.length > 0)
 </script>
@@ -62,9 +58,21 @@
         class="px-4 py-3 flex items-center justify-between hover:bg-surface-tint transition-colors"
       >
         <div>
-          <span class="font-medium" v-html="highlight(city.name)" />
+          <span class="font-medium">
+            <template v-for="(chunk, i) in toHighlight(city.name, query, highlightOptions)" :key="i">
+              <mark v-if="chunk.match" class="bg-warning text-on-warning rounded px-0.5">{{ chunk.text }}</mark>
+              <template v-else>{{ chunk.text }}</template>
+            </template>
+          </span>
+
           <span class="mx-2 opacity-30">/</span>
-          <span class="text-sm opacity-70" v-html="highlight(city.country)" />
+
+          <span class="text-sm opacity-70">
+            <template v-for="(chunk, i) in toHighlight(city.country, query, highlightOptions)" :key="i">
+              <mark v-if="chunk.match" class="bg-warning text-on-warning rounded px-0.5">{{ chunk.text }}</mark>
+              <template v-else>{{ chunk.text }}</template>
+            </template>
+          </span>
         </div>
 
         <span class="text-sm font-mono opacity-50">{{ city.population }}</span>

apps/docs/src/examples/composables/to-highlight/MessageRow.vue

@@ -0,0 +1,72 @@
+<script setup lang="ts">
+  import { toHighlight } from '@vuetify/v0'
+  import { computed, toRef } from 'vue'
+  import { snippets } from './messages'
+  import type { Message } from './messages'
+
+  const props = defineProps<{
+    message: Message
+    terms: string[]
+    serverMode: boolean
+  }>()
+
+  const message = toRef(() => props.message)
+  const options = { ignoreCase: true, matchAll: true } as const
+
+  const subject = computed(() => toHighlight(message.value.subject, () => props.terms, options))
+
+  const body = computed(() => {
+    if (props.serverMode) {
+      return toHighlight(message.value.body, undefined, {
+        matches: snippets(message.value.body, props.terms),
+      })
+    }
+    return toHighlight(message.value.body, () => props.terms, options)
+  })
+
+  const hits = computed(() =>
+    subject.value.filter(c => c.match).length + body.value.filter(c => c.match).length,
+  )
+</script>
+
+<template>
+  <article
+    class="flex gap-3 p-3 rounded transition-colors hover:bg-surface-tint data-[hit=false]:opacity-50"
+    :data-hit="hits > 0"
+  >
+    <div class="size-9 shrink-0 rounded-full bg-primary/15 text-primary text-sm font-semibold grid place-items-center">
+      {{ message.from.split(' ').map(p => p[0]).join('').slice(0, 2) }}
+    </div>
+
+    <div class="min-w-0 flex-1">
+      <header class="flex items-baseline gap-2">
+        <span class="font-semibold text-on-surface truncate">{{ message.from }}</span>
+        <span class="ml-auto shrink-0 text-xs text-on-surface/50">{{ message.time }}</span>
+      </header>
+
+      <p class="text-sm font-medium text-on-surface truncate">
+        <template v-for="(chunk, i) in subject" :key="i">
+          <mark
+            v-if="chunk.match"
+            class="bg-primary/25 text-on-surface rounded px-0.5 not-italic"
+          >{{ chunk.text }}</mark>
+
+          <template v-else>{{ chunk.text }}</template>
+        </template>
+      </p>
+
+      <p class="text-sm text-on-surface/70 line-clamp-2">
+        <template v-for="(chunk, i) in body" :key="i">
+          <mark
+            v-if="chunk.match"
+            :class="serverMode
+              ? 'bg-success/25 text-on-surface rounded px-0.5 not-italic decoration-2 underline decoration-success/60'
+              : 'bg-primary/20 text-on-surface rounded px-0.5 not-italic'"
+          >{{ chunk.text }}</mark>
+
+          <template v-else>{{ chunk.text }}</template>
+        </template>
+      </p>
+    </div>
+  </article>
+</template>

apps/docs/src/examples/composables/to-highlight/inbox.vue

@@ -0,0 +1,88 @@
+<script setup lang="ts">
+  import { Input, Switch, Toggle } from '@vuetify/v0'
+  import { computed, ref, shallowRef } from 'vue'
+  import MessageRow from './MessageRow.vue'
+  import { messages } from './messages'
+
+  const query = shallowRef('search')
+  const serverMode = shallowRef(false)
+
+  const filters = ['budget', 'review', 'urgent'] as const
+  const active = ref<Record<string, boolean>>({})
+
+  const terms = computed(() => {
+    const out: string[] = []
+    if (query.value.trim()) out.push(query.value.trim())
+    for (const f of filters) {
+      if (active.value[f] && !out.some(t => t.toLowerCase() === f)) out.push(f)
+    }
+    return out
+  })
+
+  const matching = computed(() => {
+    if (terms.value.length === 0) return messages
+    return messages.filter(m => {
+      const haystack = (m.subject + ' ' + m.body).toLowerCase()
+      return terms.value.some(t => haystack.includes(t.toLowerCase()))
+    })
+  })
+</script>
+
+<template>
+  <div class="flex flex-col gap-3 p-4 max-w-2xl mx-auto">
+    <Input.Root id="inbox-search" v-model="query" label="Search inbox">
+      <Input.Control
+        class="w-full px-3 py-2 rounded-lg border border-divider bg-surface text-on-surface placeholder:text-on-surface/40 outline-none data-[focused]:border-primary transition-colors"
+        placeholder="Search by sender, subject, or body…"
+      />
+    </Input.Root>
+
+    <div class="flex flex-wrap items-center gap-2">
+      <span class="text-xs font-medium text-on-surface/60">Saved filters:</span>
+
+      <Toggle.Root
+        v-for="f in filters"
+        :key="f"
+        v-model="active[f]"
+        class="px-2.5 py-1 rounded-full border border-divider text-xs font-medium text-on-surface/70 transition-colors data-[state=on]:border-primary data-[state=on]:bg-primary/15 data-[state=on]:text-on-surface hover:bg-surface-tint"
+      >
+        {{ f }}
+      </Toggle.Root>
+
+      <label class="ml-auto inline-flex items-center gap-2 text-xs text-on-surface/70 cursor-pointer">
+        <Switch.Root
+          v-model="serverMode"
+          class="inline-flex items-center border-none bg-transparent p-0 outline-none"
+        >
+          <Switch.Track class="relative inline-flex items-center w-9 h-5 rounded-full bg-surface-variant transition-colors data-[state=checked]:bg-success">
+            <Switch.Thumb class="![visibility:visible] block size-3.5 rounded-full bg-white shadow-sm transition-transform translate-x-0.5 data-[state=checked]:translate-x-5" />
+          </Switch.Track>
+        </Switch.Root>
+        Server snippets
+      </label>
+    </div>
+
+    <div class="flex items-baseline justify-between text-xs text-on-surface/60 px-1">
+      <span>{{ matching.length }} of {{ messages.length }} threads</span>
+
+      <span v-if="terms.length > 0">
+        Highlighting
+        <span class="font-mono">{{ JSON.stringify(terms.length === 1 ? terms[0] : terms) }}</span>
+      </span>
+    </div>
+
+    <div class="flex flex-col rounded-lg border border-divider bg-surface divide-y divide-divider">
+      <MessageRow
+        v-for="message in matching"
+        :key="message.id"
+        :message
+        :server-mode
+        :terms
+      />
+
+      <p v-if="matching.length === 0" class="p-6 text-center text-sm text-on-surface/60">
+        No threads match the active filters.
+      </p>
+    </div>
+  </div>
+</template>

apps/docs/src/examples/composables/to-highlight/messages.ts

@@ -0,0 +1,55 @@
+import type { MatchRange } from '@vuetify/v0'
+
+export interface Message {
+  id: number
+  from: string
+  subject: string
+  body: string
+  time: string
+}
+
+export const messages: Message[] = [
+  {
+    id: 1,
+    from: 'Lina Park',
+    subject: 'Q3 budget review',
+    body: 'The marketing line item is 18% over forecast. Can we walk through the spend before Friday? I have a draft proposal that trims paid ads without touching the events budget.',
+    time: '9:42 AM',
+  },
+  {
+    id: 2,
+    from: 'Marcus Chen',
+    subject: 'Re: design review for the search experience',
+    body: 'Loved the new typeahead — the highlight on each result row reads much faster than the underlined variant. One nit: the empty-state copy still says "no matches" instead of "no results".',
+    time: '8:15 AM',
+  },
+  {
+    id: 3,
+    from: 'Priya Shah',
+    subject: 'Weekly product sync notes',
+    body: 'Recap: launched the new search bar, started the onboarding redesign, paused the budget dashboard work pending review. Open questions on the search ranking tweak are tracked in the planning doc.',
+    time: 'Yesterday',
+  },
+  {
+    id: 4,
+    from: 'GitHub',
+    subject: 'New review request on vuetifyjs/0#222',
+    body: 'J-Sek requested your review on the toHighlight transformer PR. The branch adds a pure splitter and updates the create-filter live-search example to drop the v-html highlight path.',
+    time: 'Yesterday',
+  },
+]
+
+function escape (term: string) {
+  return term.replace(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`)
+}
+
+export function snippets (body: string, terms: string[]): MatchRange[] {
+  const safe = terms.filter(Boolean)
+  if (safe.length === 0) return []
+  const pattern = safe.map(t => String.raw`\b${escape(t)}\w*`).join('|')
+  const ranges: MatchRange[] = []
+  for (const m of body.matchAll(new RegExp(pattern, 'gi'))) {
+    ranges.push([m.index, m.index + m[0].length])
+  }
+  return ranges
+}

apps/docs/src/pages/composables/index.md

@@ -334,5 +334,6 @@ Value transformation utilities.
 | - | - |
 | [toArray](/composables/transformers/to-array) | Convert any value to an array |
 | [toElement](/composables/transformers/to-element) | Resolve refs, getters, or component instances to a plain DOM element |
+| [toHighlight](/composables/transformers/to-highlight) | Split text into matched and unmatched chunks for query highlighting |
 | [toReactive](/composables/transformers/to-reactive) | Convert MaybeRef objects to reactive proxies |