@terrafirmagreg-team/search 0.0.0-stage → 1.2.0

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@terrafirmagreg-team/search",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.2.0",
+  "type": "module",
+  "description": "Section-aware search",
+  "license": "LGPL-3.0-only",
+  "exports": {
+    "./lib": "./src/lib/index.ts",
+    "./lib/*": [
+      "./src/lib/*.ts",
+      "./src/lib/*/index.ts"
+    ],
+    "./components/*": [
+      "./src/components/*.tsx",
+      "./src/components/*/index.tsx",
+      "./src/components/*/index.ts"
+    ],
+    "./locales": "./src/locales.ts"
+  },
+  "dependencies": {
+    "@terrafirmagreg-team/kit": "1.2.0",
+    "@terrafirmagreg-team/sites": "1.2.0",
+    "@terrafirmagreg-team/translate": "1.2.0",
+    "@terrafirmagreg-team/ui": "1.2.0",
+    "fumadocs-core": "16.17.8",
+    "server-only": "^0.0.1"
+  },
+  "peerDependencies": {
+    "next": ">=15",
+    "react": ">=19"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.5",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TerraFirmaGreg-Team/Web-Foundation.git",
+    "directory": "packages/search"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src"
+  ]
 }

package/src/components/dialog.tsx

@@ -0,0 +1,231 @@
+'use client';
+import {
+  SearchDialog as SearchDialogRoot,
+  SearchDialogClose,
+  SearchDialogContent,
+  SearchDialogFooter,
+  SearchDialogHeader,
+  SearchDialogIcon,
+  SearchDialogInput,
+  SearchDialogList,
+  SearchDialogOverlay,
+  SearchDialogListItem,
+  type SharedProps,
+} from '@terrafirmagreg-team/ui/components/blocks/search/dialog';
+import {
+  useDocsSearch,
+  type SearchClient,
+} from 'fumadocs-core/search/client';
+import { staticClient } from 'fumadocs-core/search/client/orama-static';
+import { useResolvedLang } from '@terrafirmagreg-team/translate/hooks/use-resolved-lang';
+import { usePathname } from 'next/navigation';
+import { useLocationSearchParams } from '@terrafirmagreg-team/ui/hooks/page/use-location-search';
+import { useMemo, useState } from 'react';
+import { Skeleton } from '@terrafirmagreg-team/ui/components/ui/skeleton';
+import { cn } from '@terrafirmagreg-team/ui/lib/utils/cn';
+import { useTranslations } from '@terrafirmagreg-team/translate/hooks/use-translations';
+import { useSectionCatalog } from '@terrafirmagreg-team/kit/hooks/use-catalog';
+import { useSectionNames } from '@terrafirmagreg-team/kit/hooks/use-section-names';
+import {
+  dumpSectionKeys,
+  parseSectionLocation,
+} from '@terrafirmagreg-team/sites/location';
+import { searchHitFilter, mergeClients } from '../lib';
+import { getSearchClientSources } from '../lib/sources';
+
+const chip =
+  'rounded-md border px-2 py-0.5 text-xs font-medium transition-colors cursor-pointer';
+const chipOn = 'bg-accent text-accent-foreground border-transparent';
+const chipOff = 'text-muted-foreground hover:text-foreground';
+const chipMixed = cn(chipOff, 'border-dashed');
+
+export function SearchDialog(props: SharedProps & { api: string }) {
+  const locale = useResolvedLang();
+  const t = useTranslations();
+  const sectionNames = useSectionNames();
+  const catalog = useSectionCatalog();
+  const pathname = usePathname();
+  const version = useLocationSearchParams().get('version') ?? undefined;
+  const { section, dataset: locationDataset } =
+    parseSectionLocation(pathname);
+  const dataset = locationDataset;
+  const scopeKey = `${section ?? ''}/${locationDataset ?? ''}`;
+
+  const sections = useMemo(
+    () =>
+      Object.entries(catalog).filter(
+        ([, datasets]) => datasets.length > 0,
+      ),
+    [catalog],
+  );
+  const defaultSel = useMemo((): Set<string> => {
+    if (section && dataset) return new Set([`${section}:${dataset}`]);
+    if (section)
+      return new Set(
+        (catalog[section] ?? []).map(({ id }) => `${section}:${id}`),
+      );
+    return new Set();
+  }, [section, dataset, catalog]);
+  const [picked, setPicked] = useState<{ key: string; sel: Set<string> }>();
+  const sel = picked?.key === scopeKey ? picked.sel : defaultSel;
+  const setSel = (value: Set<string>) =>
+    setPicked({ key: scopeKey, sel: value });
+  const toggle = (ids: readonly string[]) => {
+    const next = new Set(sel);
+    const allOn = ids.every((id) => next.has(id));
+    for (const id of ids) {
+      if (allOn) next.delete(id);
+      else next.add(id);
+    }
+    setSel(next);
+  };
+
+  const client = useMemo((): SearchClient => {
+    const from = `${props.api}/${locale}.json`;
+    const content = staticClient({ locale, from });
+    const selSecs = new Set([...sel].map((entry) => entry.split(':')[0]!));
+    const scopedSections =
+      sel.size === 0
+        ? dumpSectionKeys()
+        : dumpSectionKeys().filter((sec) => selSecs.has(sec));
+    const refs = scopedSections.flatMap((sec) =>
+      (catalog[sec] ?? []).map(({ id }) =>
+        sec === section && id === dataset && locationDataset
+          ? { id, version }
+          : { id },
+      ),
+    );
+    const extra = getSearchClientSources().map((make) =>
+      make({ refs, locale, tag: undefined }),
+    );
+    return mergeClients(content, ...extra);
+  }, [locale, sel, section, dataset, locationDataset, version, catalog, props.api]);
+  const { search, setSearch, query } = useDocsSearch({ client });
+  const showBadges =
+    sel.size === 0 ||
+    new Set([...sel].map((entry) => entry.split(':')[0]!)).size > 1;
+  const items = useMemo(() => {
+    const list = query.data !== 'empty' ? (query.data ?? []) : [];
+    const inScope = (item: (typeof list)[number]) =>
+      sel.size === 0 ||
+      !('url' in item) ||
+      [...sel].some((entry) =>
+        item.url.startsWith(`/${entry.replace(':', '/')}`),
+      );
+    const hitFilter =
+      section && typeof window !== 'undefined'
+        ? searchHitFilter(
+            section,
+            new URLSearchParams(window.location.search),
+          )
+        : undefined;
+    return list.filter(
+      (item) => inScope(item) && (hitFilter?.(item) ?? true),
+    );
+  }, [query.data, section, sel]);
+
+  return (
+    <SearchDialogRoot search={search} onSearchChange={setSearch} isLoading={query.isLoading} {...props}>
+      <SearchDialogOverlay />
+      <SearchDialogContent>
+        <SearchDialogHeader>
+          <SearchDialogIcon />
+          <SearchDialogInput />
+          <SearchDialogClose />
+        </SearchDialogHeader>
+        {query.isLoading ? (
+          <div className="flex flex-col gap-1.5 p-3">
+            <Skeleton className="h-9 w-full" />
+            <Skeleton className="h-9 w-5/6" />
+            <Skeleton className="h-9 w-4/6" />
+          </div>
+        ) : (
+          <SearchDialogList
+            items={items.length ? items : null}
+            Item={(itemProps) => (
+              <SearchDialogListItem
+                {...itemProps}
+                badge={
+                  showBadges && 'url' in itemProps.item
+                    ? scopeBadge(itemProps.item.url)
+                    : undefined
+                }
+              />
+            )}
+          />
+        )}
+        <SearchDialogFooter>
+          <div className="flex flex-wrap items-center gap-1">
+            <button
+              type="button"
+              aria-pressed={sel.size === 0}
+              className={cn(chip, sel.size === 0 ? chipOn : chipOff)}
+              onClick={() => setSel(new Set())}
+            >
+              {t('Everywhere', { note: 'ui.search_everywhere' })}
+            </button>
+            <span aria-hidden className="mx-0.5 h-4 w-px bg-border" />
+            {sections.map(([sec, datasets]) => {
+              const ids = datasets.map(({ id }) => `${sec}:${id}`);
+              if (ids.length === 1) {
+                const id = ids[0]!;
+                const on = sel.has(id);
+                return (
+                  <button
+                    key={sec}
+                    type="button"
+                    aria-pressed={on}
+                    className={cn(chip, on ? chipOn : chipOff)}
+                    onClick={() => toggle(ids)}
+                  >
+                    {sectionNames[sec]?.title ?? sec}
+                  </button>
+                );
+              }
+              const onCount = ids.filter((id) => sel.has(id)).length;
+              return [
+                <button
+                  key={sec}
+                  type="button"
+                  aria-pressed={onCount > 0}
+                  className={cn(
+                    chip,
+                    onCount === ids.length
+                      ? chipOn
+                      : onCount > 0
+                        ? chipMixed
+                        : chipOff,
+                  )}
+                  onClick={() => toggle(ids)}
+                >
+                  {sectionNames[sec]?.title ?? sec}
+                </button>,
+                ...datasets.map(({ id, title }) => {
+                  const entry = `${sec}:${id}`;
+                  const on = sel.has(entry);
+                  return (
+                    <button
+                      key={entry}
+                      type="button"
+                      aria-pressed={on}
+                      className={cn(chip, on ? chipOn : chipOff)}
+                      onClick={() => toggle([entry])}
+                    >
+                      {title ?? id}
+                    </button>
+                  );
+                }),
+              ];
+            })}
+          </div>
+        </SearchDialogFooter>
+      </SearchDialogContent>
+    </SearchDialogRoot>
+  );
+
+  function scopeBadge(url: string) {
+    const sec = url.split('/')[1];
+    return sec && sec in catalog ? (sectionNames[sec]?.title ?? sec) : undefined;
+  }
+}
+

package/src/lib/config.ts

@@ -0,0 +1,14 @@
+import type { LangConfig } from '@terrafirmagreg-team/translate/lang';
+import { createConfig } from '@terrafirmagreg-team/kit/lib/config';
+import type { LocalizedIndex } from './indexes';
+
+export interface SearchConfig {
+
+  indexes(): Promise<LocalizedIndex[]>;
+
+  i18n(): LangConfig;
+}
+
+export const { register: registerSearchConfig, get: searchConfig } =
+  createConfig<SearchConfig>('Search');
+

package/src/lib/filters.ts

@@ -0,0 +1,23 @@
+import type { SortedResult } from '@terrafirmagreg-team/ui/types/search';
+
+export type SearchHitFilter = (hit: SortedResult) => boolean;
+export type SearchHitFilterFactory = (
+  params: URLSearchParams,
+) => SearchHitFilter | undefined;
+
+const hitFilters = new Map<string, SearchHitFilterFactory>();
+
+export function registerSearchHitFilter(
+  section: string,
+  factory: SearchHitFilterFactory,
+): void {
+  hitFilters.set(section, factory);
+}
+
+export function searchHitFilter(
+  section: string,
+  params: URLSearchParams,
+): SearchHitFilter | undefined {
+  return hitFilters.get(section)?.(params);
+}
+

package/src/lib/index.ts

@@ -0,0 +1,20 @@
+export { mergeClients } from './merge';
+export { pageStructuredData } from './structured';
+export {
+  buildSearchIndexes,
+  type LocalizedIndex,
+  type SearchIndexPage,
+  type SearchPageSource,
+} from './indexes';
+export {
+  registerSearchConfig,
+  searchConfig,
+  type SearchConfig,
+} from './config';
+export {
+  registerSearchHitFilter,
+  searchHitFilter,
+  type SearchHitFilter,
+  type SearchHitFilterFactory,
+} from './filters';
+

package/src/lib/indexes.ts

@@ -0,0 +1,48 @@
+import type { AdvancedIndex } from 'fumadocs-core/search/server';
+import { stripLangFromUrl } from '@terrafirmagreg-team/translate/lib/slug';
+import { pageStructuredData } from './structured';
+
+export type LocalizedIndex = AdvancedIndex & { locale: string };
+
+export interface SearchIndexPage {
+  slugs: string[];
+  url: string;
+  data: { title?: string; description?: string };
+}
+
+export interface SearchPageSource {
+  getSource(): Promise<{ getPages(): SearchIndexPage[] }>;
+}
+
+export async function buildSearchIndexes(
+  sources: Record<string, SearchPageSource | undefined>,
+  languages: readonly string[],
+): Promise<LocalizedIndex[]> {
+  const pages: { section: string; page: SearchIndexPage }[] = [];
+  for (const [section, entry] of Object.entries(sources)) {
+    if (!entry) continue;
+    for (const page of (await entry.getSource()).getPages()) {
+      pages.push({ section, page });
+    }
+  }
+  return (
+    await Promise.all(
+      pages.map(async ({ section, page }) => {
+        const [dataset, lang] = page.slugs;
+        if (!dataset || !lang) return null;
+        return {
+          title: page.data.title ?? page.url,
+          description: page.data.description,
+          url: stripLangFromUrl(page.url, [...languages]),
+          id: page.url,
+          tag: `${section}:${dataset}`,
+          locale: lang,
+          structuredData: await pageStructuredData(
+            page.data as Record<string, unknown>,
+          ),
+        } satisfies LocalizedIndex;
+      }),
+    )
+  ).filter((index) => index !== null);
+}
+

package/src/lib/merge.ts

@@ -0,0 +1,23 @@
+import type { SearchClient } from 'fumadocs-core/search/client';
+
+export function mergeClients(...clients: SearchClient[]): SearchClient {
+  return {
+    deps: clients.flatMap((client) => client.deps ?? []),
+    async search(query) {
+      const lists = await Promise.all(
+        clients.map((client) => client.search(query)),
+      );
+      const seen = new Set<string>();
+      const out = [];
+      for (const list of lists) {
+        for (const hit of list) {
+          if (seen.has(hit.id)) continue;
+          seen.add(hit.id);
+          out.push(hit);
+        }
+      }
+      return out;
+    },
+  };
+}
+

package/src/lib/server.ts

@@ -0,0 +1,56 @@
+import 'server-only';
+import { initAdvancedSearch } from 'fumadocs-core/search/server';
+import { searchConfig } from './config';
+import type { LocalizedIndex } from './indexes';
+
+type LangServer = { export(): Promise<unknown> };
+
+async function createLangServers() {
+  const config = searchConfig();
+  const indexes = await config.indexes();
+  const byLang = new Map<string, LocalizedIndex[]>();
+  for (const index of indexes) {
+    const list = byLang.get(index.locale) ?? [];
+    if (!list.length) byLang.set(index.locale, list);
+    list.push(index);
+  }
+  const servers = new Map<string, LangServer>();
+  for (const [lang, langIndexes] of byLang) {
+    servers.set(
+      lang,
+      initAdvancedSearch({ indexes: langIndexes, localeFilter: true }),
+    );
+  }
+  return servers;
+}
+
+let cached: Promise<Map<string, LangServer>> | undefined;
+
+function langServers() {
+  const p = (cached ??= createLangServers());
+  p.catch(() => {
+    if (cached === p) cached = undefined;
+  });
+  return p;
+}
+
+async function exportFor(langs: Iterable<string>) {
+  const servers = await langServers();
+  const data: Record<string, unknown> = {};
+  await Promise.all(
+    [...langs].map(async (lang) => {
+      const server = servers.get(lang);
+      if (server) data[lang] = await server.export();
+    }),
+  );
+  return { type: 'i18n' as const, data };
+}
+
+export function searchExport() {
+  return langServers().then((servers) => exportFor(servers.keys()));
+}
+
+export function searchExportLang(lang: string) {
+  return exportFor([lang]);
+}
+

package/src/lib/sources.ts

@@ -0,0 +1,21 @@
+import type { DatasetRef } from '@terrafirmagreg-team/sites/location';
+import type { SearchClient } from 'fumadocs-core/search/client';
+
+export type SearchClientSourceCtx = {
+  refs: DatasetRef[];
+  locale: string;
+  tag?: string | string[];
+};
+
+export type SearchClientSource = (ctx: SearchClientSourceCtx) => SearchClient;
+
+const sources: SearchClientSource[] = [];
+
+export function registerSearchClientSource(source: SearchClientSource): void {
+  sources.push(source);
+}
+
+export function getSearchClientSources(): readonly SearchClientSource[] {
+  return sources;
+}
+

package/src/lib/structured.ts

@@ -0,0 +1,26 @@
+import type { StructuredData } from 'fumadocs-core/mdx-plugins';
+
+type StructuredPageData = Record<string, unknown>;
+
+export async function pageStructuredData(
+  data: StructuredPageData,
+): Promise<StructuredData> {
+  const raw = data.structuredData;
+  if (typeof raw === 'function') {
+    const result = await (raw as () => Promise<StructuredData> | StructuredData)();
+    if (!result) throw new Error('Cannot find structured data from page');
+    return result;
+  }
+  if (typeof data.load === 'function') {
+    const loaded = await (
+      data.load as () => Promise<{ structuredData?: StructuredData }>
+    )();
+    if (!loaded.structuredData) {
+      throw new Error('Cannot find structured data from page');
+    }
+    return loaded.structuredData;
+  }
+  if (!raw) throw new Error('Cannot find structured data from page');
+  return raw as StructuredData;
+}
+

package/src/locales/en_us.json

@@ -0,0 +1,3 @@
+{
+  "Everywhere(ui.search_everywhere)": "Everywhere"
+}

package/src/locales/ru_ru.json

@@ -0,0 +1,3 @@
+{
+  "Everywhere(ui.search_everywhere)": "Везде"
+}

package/src/locales.ts

@@ -0,0 +1,6 @@
+import { createLocaleCatalog } from '@terrafirmagreg-team/translate/lib/locales';
+
+export const locales = createLocaleCatalog(
+  import.meta.glob('./locales/*.json', { eager: true, import: 'default' }),
+);
+

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.