@ngbplatform/ui 1.3.0

package/src/ngb/command-palette/NgbCommandPaletteDialog.vue

@@ -0,0 +1,342 @@
+<template>
+  <Teleport to="body">
+    <TransitionRoot appear :show="store.isOpen" as="template" @after-leave="restoreLastFocus">
+      <Dialog as="div" class="relative z-[90]" :initialFocus="inputRef" @close="store.close()">
+        <TransitionChild
+          as="template"
+          enter="duration-150 ease-out"
+          enter-from="opacity-0"
+          enter-to="opacity-100"
+          leave="duration-120 ease-in"
+          leave-from="opacity-100"
+          leave-to="opacity-0"
+        >
+          <div class="fixed inset-0 bg-[rgba(7,12,20,.48)] backdrop-blur-[2px]" />
+        </TransitionChild>
+
+        <div class="fixed inset-0 overflow-y-auto">
+          <div class="flex min-h-full items-start justify-center px-4 pb-8 pt-[10vh]">
+            <TransitionChild
+              as="template"
+              enter="duration-150 ease-out"
+              enter-from="opacity-0 translate-y-3 scale-[0.985]"
+              enter-to="opacity-100 translate-y-0 scale-100"
+              leave="duration-120 ease-in"
+              leave-from="opacity-100 translate-y-0 scale-100"
+              leave-to="opacity-0 translate-y-3 scale-[0.985]"
+            >
+              <DialogPanel data-testid="command-palette-dialog" class="w-full max-w-[860px] overflow-hidden rounded-[var(--ngb-radius)] border border-ngb-border bg-ngb-card shadow-card">
+                <DialogTitle class="sr-only">Command palette</DialogTitle>
+
+                <div class="border-b border-ngb-border px-4 py-3">
+                  <div class="flex h-10 items-center gap-3 rounded-[var(--ngb-radius)] border border-ngb-border bg-ngb-card px-3">
+                    <span class="text-ngb-muted">
+                      <NgbIcon name="search" :size="18" />
+                    </span>
+
+                    <input
+                      ref="inputRef"
+                      data-testid="command-palette-input"
+                      :value="store.query"
+                      class="h-full flex-1 border-0 bg-transparent px-0 text-sm text-ngb-text outline-none placeholder:text-ngb-muted/70"
+                      :placeholder="placeholder"
+                      role="combobox"
+                      aria-autocomplete="list"
+                      :aria-expanded="store.hasResults"
+                      :aria-controls="listboxId"
+                      :aria-activedescendant="activeDescendantId"
+                      @input="store.setQuery(String(($event.target as HTMLInputElement)?.value ?? ''))"
+                      @keydown="onInputKeyDown"
+                    />
+
+                    <span class="hidden items-center gap-1 md:flex">
+                      <template v-if="isMac">
+                        <span class="ngb-kbd">⌘</span>
+                      </template>
+                      <template v-else>
+                        <span class="ngb-kbd">Ctrl</span>
+                      </template>
+                      <span class="ngb-kbd">K</span>
+                    </span>
+                  </div>
+
+                  <div v-if="scopeBadgeLabel || store.showRemoteLoading" class="mt-2 flex flex-wrap items-center gap-2 text-xs text-ngb-muted">
+                    <span v-if="scopeBadgeLabel" class="rounded-full border border-ngb-border bg-ngb-bg px-2.5 py-1">
+                      {{ scopeBadgeLabel }}
+                    </span>
+                    <span v-if="store.showRemoteLoading" class="rounded-full border border-ngb-border bg-ngb-bg px-2.5 py-1">
+                      Updating remote results…
+                    </span>
+                  </div>
+                </div>
+
+                <div class="sr-only" aria-live="polite">
+                  {{ liveRegionText }}
+                </div>
+
+                <div class="max-h-[560px] overflow-y-auto p-2" :id="listboxId" role="listbox">
+                  <div
+                    v-if="store.hasRemoteError && store.groups.length > 0"
+                    class="mx-2 mb-2 rounded-[var(--ngb-radius)] border border-[rgba(185,28,28,.16)] bg-[rgba(254,242,242,.92)] px-3 py-2 text-xs text-[#7f1d1d]"
+                  >
+                    {{ store.remoteError }}
+                  </div>
+
+                  <template v-if="store.groups.length > 0">
+                    <section v-for="group in store.groups" :key="group.code" class="py-1.5">
+                      <div class="px-3 pb-2 pt-1 text-[11px] font-semibold uppercase tracking-[0.14em] text-ngb-muted">
+                        {{ group.label }}
+                      </div>
+
+                      <div class="space-y-1">
+                        <button
+                          v-for="item in group.items"
+                          :id="optionId(item.key)"
+                          :key="item.key"
+                          :data-option-id="optionId(item.key)"
+                          :data-item-key="item.key"
+                          type="button"
+                          role="option"
+                          :aria-selected="isActive(item.key)"
+                          class="flex w-full items-start gap-3 rounded-[var(--ngb-radius)] border px-3 py-2.5 text-left transition-colors"
+                          :class="isActive(item.key)
+                            ? 'border-[rgba(11,60,93,.22)] bg-[rgba(11,60,93,.08)]'
+                            : 'border-transparent hover:border-ngb-border hover:bg-ngb-bg'"
+                          @mouseenter="setActive(item.key)"
+                          @click="onItemClick(item, $event)"
+                        >
+                          <span
+                            class="mt-0.5 flex h-8 w-8 shrink-0 items-center justify-center rounded-[var(--ngb-radius)]"
+                            :class="isActive(item.key) ? 'bg-transparent text-ngb-text' : 'bg-transparent text-ngb-muted'"
+                          >
+                            <NgbIcon :name="resolveCommandPaletteIcon(item.icon)" :size="17" />
+                          </span>
+
+                          <span class="min-w-0 flex-1">
+                            <span class="flex items-start justify-between gap-3">
+                              <span class="min-w-0">
+                                <span class="block truncate text-sm font-semibold text-ngb-text">{{ item.title }}</span>
+                                <span class="mt-0.5 block truncate text-xs leading-5 text-ngb-muted">{{ resolveCommandPaletteSubtitle(item) }}</span>
+                              </span>
+
+                              <span class="flex shrink-0 items-center gap-2">
+                                <NgbBadge
+                                  v-if="resolveCommandPaletteBadge(item)"
+                                  tone="neutral"
+                                >
+                                  {{ resolveCommandPaletteBadge(item) }}
+                                </NgbBadge>
+                                <span v-if="item.openInNewTabSupported" class="hidden text-[11px] text-ngb-muted lg:inline">
+                                  {{ primaryModifier }}+Enter
+                                </span>
+                              </span>
+                            </span>
+                          </span>
+                        </button>
+                      </div>
+                    </section>
+                  </template>
+
+                  <NgbCommandPaletteEmptyState
+                    v-else
+                    :query="store.cleanQuery"
+                    :loading="store.showRemoteLoading"
+                    :error="store.hasRemoteError ? store.remoteError : null"
+                  />
+                </div>
+
+                <NgbCommandPaletteFooterHints :primary-modifier="primaryModifier" />
+              </DialogPanel>
+            </TransitionChild>
+          </div>
+        </div>
+      </Dialog>
+    </TransitionRoot>
+  </Teleport>
+</template>
+
+<script setup lang="ts">
+import { computed, nextTick, onBeforeUnmount, onMounted, ref, watch } from 'vue'
+import { Dialog, DialogPanel, DialogTitle, TransitionChild, TransitionRoot } from '@headlessui/vue'
+import NgbBadge from '../primitives/NgbBadge.vue'
+import NgbIcon from '../primitives/NgbIcon.vue'
+import { useCommandPaletteStore } from './store'
+import type { CommandPaletteItem } from './types'
+import {
+  resolveCommandPaletteBadge,
+  resolveCommandPaletteIcon,
+  resolveCommandPaletteSubtitle,
+} from './presentation'
+import NgbCommandPaletteEmptyState from './NgbCommandPaletteEmptyState.vue'
+import NgbCommandPaletteFooterHints from './NgbCommandPaletteFooterHints.vue'
+
+const store = useCommandPaletteStore()
+const inputRef = ref<HTMLInputElement | null>(null)
+const lastFocusedElement = ref<HTMLElement | null>(null)
+let restoreFocusTimer: ReturnType<typeof window.setTimeout> | null = null
+
+const listboxId = 'ngb-command-palette-listbox'
+const placeholder = 'Search pages, records, reports, or run a command…'
+const isMac = /Mac|iPhone|iPad|iPod/i.test(String(globalThis.navigator?.platform ?? ''))
+const primaryModifier = computed(() => (isMac ? '⌘' : 'Ctrl'))
+
+function onDocumentFocusIn(event: FocusEvent): void {
+  if (store.isOpen) return
+  const target = event.target instanceof HTMLElement ? event.target : null
+  if (!target || target === document.body) return
+  lastFocusedElement.value = target
+}
+
+const flatItems = computed(() => store.flatItems)
+const indexByKey = computed(() => {
+  const map = new Map<string, number>()
+  flatItems.value.forEach((item, index) => map.set(item.key, index))
+  return map
+})
+
+const activeItem = computed(() => flatItems.value[store.activeIndex] ?? null)
+const activeDescendantId = computed(() => (activeItem.value ? optionId(activeItem.value.key) : undefined))
+const scopeBadgeLabel = computed<string | null>(() => {
+  switch (store.activeScope) {
+    case 'commands':
+      return 'Commands'
+    case 'pages':
+      return 'Pages'
+    case 'reports':
+      return 'Reports'
+    case 'documents':
+      return 'Documents'
+    case 'catalogs':
+      return 'Catalogs'
+    default:
+      return null
+  }
+})
+
+const liveRegionText = computed(() => {
+  if (store.hasRemoteError) return store.remoteError ?? 'Remote search is unavailable.'
+  if (store.showRemoteLoading) return 'Updating remote results.'
+  if (store.groups.length === 0) return store.cleanQuery ? `No results for ${store.cleanQuery}.` : 'Showing command palette shortcuts.'
+  return `${flatItems.value.length} results available.`
+})
+
+watch(
+  () => store.isOpen,
+  async (open) => {
+    if (open) {
+      if (restoreFocusTimer) {
+        window.clearTimeout(restoreFocusTimer)
+        restoreFocusTimer = null
+      }
+
+      const activeElement = document.activeElement
+      if (activeElement instanceof HTMLElement && activeElement !== document.body)
+        lastFocusedElement.value = activeElement
+      await nextTick()
+      focusInput(true)
+      return
+    }
+
+    const restoreTarget = lastFocusedElement.value
+    restoreFocusTimer = window.setTimeout(() => {
+      restoreFocusTimer = null
+      if (store.isOpen) return
+      restoreTarget?.focus?.()
+    }, 180)
+  },
+)
+
+watch(
+  () => store.focusRequestKey,
+  async () => {
+    if (!store.isOpen) return
+    await nextTick()
+    focusInput(true)
+  },
+)
+
+watch(
+  () => activeDescendantId.value,
+  async (id) => {
+    if (!id) return
+    await nextTick()
+    document.querySelector<HTMLElement>(`[data-option-id="${id}"]`)?.scrollIntoView({ block: 'nearest' })
+  },
+)
+
+function focusInput(selectAll = false, attempt = 0): void {
+  inputRef.value?.focus()
+  if (selectAll) inputRef.value?.select()
+  window.setTimeout(() => {
+    if (!store.isOpen) return
+    if (document.activeElement === inputRef.value) return
+    if (attempt >= 4) return
+    focusInput(selectAll, attempt + 1)
+  }, attempt === 0 ? 0 : 16)
+}
+
+function restoreLastFocus(): void {
+  if (store.isOpen) return
+  if (restoreFocusTimer) {
+    window.clearTimeout(restoreFocusTimer)
+    restoreFocusTimer = null
+  }
+  window.setTimeout(() => {
+    if (store.isOpen) return
+    lastFocusedElement.value?.focus?.()
+  }, 0)
+}
+
+onMounted(() => {
+  document.addEventListener('focusin', onDocumentFocusIn, true)
+})
+
+onBeforeUnmount(() => {
+  document.removeEventListener('focusin', onDocumentFocusIn, true)
+})
+
+function isActive(key: string): boolean {
+  return activeItem.value?.key === key
+}
+
+function setActive(key: string): void {
+  const index = indexByKey.value.get(key)
+  if (index == null) return
+  store.setActiveIndex(index)
+}
+
+function optionId(key: string): string {
+  return `ngb-command-palette-option-${key.replace(/[^a-z0-9_-]+/gi, '-')}`
+}
+
+function onInputKeyDown(event: KeyboardEvent): void {
+  if (event.key === 'ArrowDown') {
+    event.preventDefault()
+    store.moveActive(1)
+    return
+  }
+
+  if (event.key === 'ArrowUp') {
+    event.preventDefault()
+    store.moveActive(-1)
+    return
+  }
+
+  if (event.key === 'Escape') {
+    event.preventDefault()
+    event.stopPropagation()
+    store.close()
+    return
+  }
+
+  if (event.key === 'Enter') {
+    event.preventDefault()
+    void store.executeActive((event.metaKey || event.ctrlKey) ? 'new-tab' : 'default')
+  }
+}
+
+function onItemClick(item: CommandPaletteItem, event: MouseEvent): void {
+  const mode = (event.metaKey || event.ctrlKey) && item.openInNewTabSupported ? 'new-tab' : 'default'
+  void store.executeItem(item, mode)
+}
+</script>

package/src/ngb/command-palette/NgbCommandPaletteEmptyState.vue

@@ -0,0 +1,55 @@
+<template>
+  <div class="px-5 py-8">
+    <template v-if="error">
+      <div
+        role="alert"
+        aria-live="assertive"
+        class="rounded-[var(--ngb-radius)] border border-[rgba(185,28,28,.18)] bg-[rgba(254,242,242,.9)] px-4 py-3"
+      >
+        <div class="text-sm font-semibold text-[#991b1b]">Remote search is temporarily unavailable</div>
+        <div class="mt-1 text-sm text-[#7f1d1d]">{{ error }}</div>
+      </div>
+    </template>
+
+    <template v-else-if="loading">
+      <div role="status" aria-live="polite">
+        <div class="text-sm font-semibold text-ngb-text">Searching records…</div>
+        <div class="mt-2 text-sm text-ngb-muted">Pages, commands, and cached reports stay available while remote results load.</div>
+      </div>
+    </template>
+
+    <template v-else-if="!query">
+      <div class="text-sm font-semibold text-ngb-text">Search pages, records, reports, or run a command</div>
+      <div class="mt-2 text-sm text-ngb-muted">
+        Try <span class="font-medium text-ngb-text">trial balance</span> or <span class="font-medium text-ngb-text">create journal entry</span>.
+      </div>
+      <div class="mt-4 flex flex-wrap gap-2 text-xs text-ngb-muted">
+        <span class="ngb-kbd">&gt;</span><span class="mr-3">Commands</span>
+        <span class="ngb-kbd">/</span><span class="mr-3">Pages</span>
+        <span class="ngb-kbd">#</span><span class="mr-3">Reports</span>
+        <span class="ngb-kbd">:</span><span class="mr-3">Documents</span>
+        <span class="ngb-kbd">@</span><span>Catalogs</span>
+      </div>
+    </template>
+
+    <template v-else>
+      <div class="text-sm font-semibold text-ngb-text">No results for “{{ query }}”</div>
+      <div class="mt-2 text-sm text-ngb-muted">Try a document number, a page name, or a scope prefix to narrow the search.</div>
+      <div class="mt-4 flex flex-wrap gap-2 text-xs text-ngb-muted">
+        <span class="ngb-kbd">&gt;</span><span class="mr-3">Commands</span>
+        <span class="ngb-kbd">/</span><span class="mr-3">Pages</span>
+        <span class="ngb-kbd">#</span><span class="mr-3">Reports</span>
+        <span class="ngb-kbd">:</span><span class="mr-3">Documents</span>
+        <span class="ngb-kbd">@</span><span>Catalogs</span>
+      </div>
+    </template>
+  </div>
+</template>
+
+<script setup lang="ts">
+defineProps<{
+  query: string
+  loading: boolean
+  error?: string | null
+}>()
+</script>

package/src/ngb/command-palette/NgbCommandPaletteFooterHints.vue

@@ -0,0 +1,29 @@
+<template>
+  <div class="flex flex-wrap items-center justify-between gap-3 border-t border-ngb-border px-4 py-3 text-xs text-ngb-muted">
+    <div class="flex flex-wrap items-center gap-2">
+      <span class="ngb-kbd">↑</span>
+      <span class="ngb-kbd">↓</span>
+      <span>Navigate</span>
+      <span class="ngb-kbd">Enter</span>
+      <span>Open</span>
+      <span class="ngb-kbd">{{ primaryModifier }}</span>
+      <span class="ngb-kbd">Enter</span>
+      <span>New tab</span>
+    </div>
+
+    <div class="flex flex-wrap items-center gap-2">
+      <span class="ngb-kbd">Esc</span>
+      <span>Close</span>
+      <span class="ngb-kbd">{{ primaryModifier }}</span>
+      <span class="ngb-kbd">K</span>
+      <span>Focus</span>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+defineProps<{
+  primaryModifier: string
+}>()
+</script>
+

package/src/ngb/command-palette/api.ts

@@ -0,0 +1,10 @@
+import { httpPost } from '../api/http'
+import type { CommandPaletteSearchRequestDto, CommandPaletteSearchResponseDto } from './types'
+
+export async function searchCommandPalette(
+  request: CommandPaletteSearchRequestDto,
+  signal?: AbortSignal,
+): Promise<CommandPaletteSearchResponseDto> {
+  return await httpPost<CommandPaletteSearchResponseDto>('/api/search/command-palette', request, { signal })
+}
+

package/src/ngb/command-palette/config.ts

@@ -0,0 +1,16 @@
+import type { CommandPaletteStoreConfig } from './types'
+
+let commandPaletteConfig: CommandPaletteStoreConfig | null = null
+
+export function configureNgbCommandPalette(config: CommandPaletteStoreConfig): void {
+  commandPaletteConfig = config
+}
+
+export function getConfiguredNgbCommandPalette(): CommandPaletteStoreConfig {
+  if (!commandPaletteConfig) {
+    throw new Error('NGB command palette is not configured. Call configureNgbCommandPalette(...) during app bootstrap.')
+  }
+
+  return commandPaletteConfig
+}
+

package/src/ngb/command-palette/presentation.ts

@@ -0,0 +1,85 @@
+import { coerceNgbIconName, type NgbIconName } from '../primitives/iconNames'
+import type { CommandPaletteItem } from './types'
+
+const GENERIC_BADGES = new Set(['Favorite', 'Recent'])
+const GENERIC_SUBTITLES = new Set([
+  'Favorite',
+  'Favorite report',
+  'Recent',
+  'Report',
+  'Page',
+  'Document',
+  'Catalog',
+])
+
+function cleanMeta(value: string | null | undefined): string | null {
+  const next = String(value ?? '').trim()
+  return next.length > 0 ? next : null
+}
+
+export function resolveCommandPaletteIcon(icon: string | null | undefined): NgbIconName {
+  return coerceNgbIconName(icon, 'search')
+}
+
+export function resolveCommandPaletteBadge(item: CommandPaletteItem): string | null {
+  const badge = cleanMeta(item.badge)
+  if (badge && !GENERIC_BADGES.has(badge)) return badge
+
+  switch (item.kind) {
+    case 'page':
+      return 'Page'
+    case 'document':
+      return 'Document'
+    case 'catalog':
+      return 'Catalog'
+    case 'report':
+      return 'Report'
+    case 'command':
+      return 'Action'
+    case 'recent':
+      switch (item.scope) {
+        case 'reports':
+          return 'Report'
+        case 'documents':
+          return 'Document'
+        case 'catalogs':
+          return 'Catalog'
+        default:
+          return 'Page'
+      }
+    default:
+      return null
+  }
+}
+
+export function resolveCommandPaletteSubtitle(item: CommandPaletteItem): string {
+  const subtitle = cleanMeta(item.subtitle)
+  if (subtitle && !GENERIC_SUBTITLES.has(subtitle)) return subtitle
+
+  switch (item.kind) {
+    case 'page':
+      return 'Open this page'
+    case 'document':
+      return 'Open this document'
+    case 'catalog':
+      return 'Open this catalog record'
+    case 'report':
+      return 'Run this report'
+    case 'command':
+      return 'Run this command'
+    case 'recent':
+      switch (item.scope) {
+        case 'reports':
+          return 'Open this recent report'
+        case 'documents':
+          return 'Open this recent document'
+        case 'catalogs':
+          return 'Open this recent catalog record'
+        default:
+          return 'Open this recent page'
+      }
+    default:
+      return 'Open this item'
+  }
+}
+

package/src/ngb/command-palette/search.ts

@@ -0,0 +1,130 @@
+import type { CommandPaletteGroupCode, CommandPaletteScope } from './types'
+
+type SearchField = {
+  value?: string | null
+  exact: number
+  prefix: number
+  wordPrefix: number
+  contains: number
+}
+
+export function normalizeSearchText(value: string | null | undefined): string {
+  const source = String(value ?? '').trim().toLowerCase()
+  if (!source) return ''
+
+  let out = ''
+  let lastWasSpace = false
+
+  for (const char of source) {
+    if (/[a-z0-9]/.test(char)) {
+      out += char
+      lastWasSpace = false
+      continue
+    }
+
+    if (lastWasSpace) continue
+    out += ' '
+    lastWasSpace = true
+  }
+
+  return out.trim()
+}
+
+export function parseCommandPaletteQuery(value: string): { rawQuery: string; query: string; scope: CommandPaletteScope | null } {
+  const rawQuery = String(value ?? '')
+  const trimmed = rawQuery.trimStart()
+  const prefix = trimmed.charAt(0)
+
+  const scope = prefixToScope(prefix)
+  if (!scope) {
+    return {
+      rawQuery,
+      query: rawQuery.trim(),
+      scope: null,
+    }
+  }
+
+  return {
+    rawQuery,
+    query: trimmed.slice(1).trim(),
+    scope,
+  }
+}
+
+export function prefixToScope(prefix: string): CommandPaletteScope | null {
+  switch (prefix) {
+    case '>':
+      return 'commands'
+    case '/':
+      return 'pages'
+    case '#':
+      return 'reports'
+    case ':':
+      return 'documents'
+    case '@':
+      return 'catalogs'
+    default:
+      return null
+  }
+}
+
+export function scoreSearchText(query: string, fields: SearchField[]): number {
+  const normalizedQuery = normalizeSearchText(query)
+  if (!normalizedQuery) return 0
+
+  let best = 0
+  for (const field of fields) {
+    best = Math.max(best, scoreField(normalizedQuery, field))
+  }
+
+  return best
+}
+
+export function groupOrder(code: CommandPaletteGroupCode): number {
+  switch (code) {
+    case 'actions':
+      return 0
+    case 'go-to':
+      return 1
+    case 'documents':
+      return 2
+    case 'catalogs':
+      return 3
+    case 'reports':
+      return 4
+    case 'recent':
+      return 5
+    default:
+      return 99
+  }
+}
+
+export function defaultSearchFields(...values: Array<string | null | undefined>): SearchField[] {
+  return values
+    .filter((value) => String(value ?? '').trim().length > 0)
+    .map((value, index) => ({
+      value,
+      exact: index === 0 ? 1 : 0.86,
+      prefix: index === 0 ? 0.92 : 0.8,
+      wordPrefix: index === 0 ? 0.88 : 0.76,
+      contains: index === 0 ? 0.76 : 0.68,
+    }))
+}
+
+function scoreField(normalizedQuery: string, field: SearchField): number {
+  const normalizedValue = normalizeSearchText(field.value)
+  if (!normalizedValue) return 0
+
+  if (normalizedValue === normalizedQuery) return field.exact
+  if (normalizedValue.startsWith(normalizedQuery)) return field.prefix
+  if (containsWordPrefix(normalizedValue, normalizedQuery)) return field.wordPrefix
+  if (normalizedValue.includes(normalizedQuery)) return field.contains
+
+  return 0
+}
+
+function containsWordPrefix(value: string, query: string): boolean {
+  const parts = value.split(' ')
+  return parts.some((part) => part.startsWith(query))
+}
+