@umami/shiso 0.55.0 → 1.0.0

package/src/lib/search/provider.ts

@@ -0,0 +1,85 @@
+import type { SearchContext, SearchResult } from '@/lib/search';
+
+export interface SearchProvider {
+  /**
+   * `context` describes the active version/language scope. Providers may
+   * ignore it; the built-in local provider uses it to keep results inside
+   * the scope being browsed.
+   */
+  search(query: string, limit?: number, context?: SearchContext): Promise<SearchResult[]>;
+}
+
+export type SearchProviderFactory = (
+  options: Record<string, unknown>,
+) => SearchProvider | Promise<SearchProvider>;
+
+export interface ResolvedSearchProvider {
+  provider: SearchProvider;
+  providerId: string;
+  fellBack: boolean;
+}
+
+const factories = new Map<string, SearchProviderFactory>();
+
+function normalizeProviderId(id: string): string {
+  return id.trim().toLowerCase();
+}
+
+/**
+ * Registers a runtime search provider. Call this before rendering the app.
+ * The returned cleanup function only removes this exact registration.
+ */
+export function registerSearchProvider(id: string, factory: SearchProviderFactory): () => void {
+  const providerId = normalizeProviderId(id);
+
+  if (!providerId || providerId === 'local') {
+    throw new Error(
+      'Search provider ids must be non-empty and cannot replace the built-in "local" provider.',
+    );
+  }
+
+  factories.set(providerId, factory);
+
+  return () => {
+    if (factories.get(providerId) === factory) {
+      factories.delete(providerId);
+    }
+  };
+}
+
+async function createLocalProvider(options: Record<string, unknown>): Promise<SearchProvider> {
+  const { createLocalSearchProvider } = await import('@/lib/search/providers/local');
+  return createLocalSearchProvider(options);
+}
+
+/** Resolves a configured provider, falling back to local for unknown ids. */
+export async function resolveSearchProvider(
+  id: string,
+  options: Record<string, unknown> = {},
+): Promise<ResolvedSearchProvider> {
+  const requestedId = normalizeProviderId(id) || 'local';
+
+  if (requestedId === 'local') {
+    return {
+      provider: await createLocalProvider(options),
+      providerId: 'local',
+      fellBack: false,
+    };
+  }
+
+  const factory = factories.get(requestedId);
+
+  if (factory) {
+    return {
+      provider: await factory(options),
+      providerId: requestedId,
+      fellBack: false,
+    };
+  }
+
+  return {
+    provider: await createLocalProvider({}),
+    providerId: 'local',
+    fellBack: true,
+  };
+}

package/src/lib/search/providers/local.ts

@@ -0,0 +1,15 @@
+import type { SearchRecord } from '@/lib/search';
+import { filterRecordsByScope, searchIndex } from '@/lib/search';
+import type { SearchProvider } from '@/lib/search/provider';
+
+/** Built-in provider backed by the section index generated during the build. */
+export function createLocalSearchProvider(_options: Record<string, unknown> = {}): SearchProvider {
+  let records: Promise<SearchRecord[]> | null = null;
+
+  return {
+    async search(query, limit, context) {
+      records ||= import('@/lib/search-index.generated').then(module => module.SEARCH_INDEX);
+      return searchIndex(filterRecordsByScope(await records, context), query, limit);
+    },
+  };
+}

package/src/lib/search-index.generated.ts

@@ -0,0 +1,4 @@
+// Build-time alias target. Shiso replaces this module with the project's generated index.
+import type { SearchRecord } from '@/lib/search';
+
+export const SEARCH_INDEX: SearchRecord[] = [];

package/src/lib/search.ts

@@ -0,0 +1,128 @@
+/**
+ * Client-side search over the build-time index
+ * (see scripts/generate-search-index.mjs).
+ *
+ * Plain substring scoring, no dependencies: docs sites are small enough that
+ * scanning a few hundred sections per keystroke is cheap, and substring
+ * matches behave predictably for exact terms like config keys.
+ */
+
+export interface SearchRecord {
+  /** Base-relative route of the page. */
+  url: string;
+  /** Page title. */
+  page: string;
+  /** Section heading, absent for the page intro. */
+  heading?: string;
+  /** Heading anchor id, matching the rendered heading. */
+  id?: string;
+  /** Plain text of the section. */
+  text: string;
+  /** Navigation scope id, absent for single-scope sites. */
+  scopeId?: string;
+  /** Language label of the owning scope, when the site defines languages. */
+  language?: string;
+  /** Version label of the owning scope, when the site defines versions. */
+  version?: string;
+}
+
+/** Where a search originates, so providers can stay inside the active scope. */
+export interface SearchContext {
+  scopeId?: string;
+  language?: string;
+  version?: string;
+}
+
+/**
+ * Restricts records to the active scope. Records without a scope id (from
+ * single-scope indexes or older caches) always pass.
+ */
+export function filterRecordsByScope(
+  records: SearchRecord[],
+  context?: SearchContext,
+): SearchRecord[] {
+  if (!context?.scopeId) {
+    return records;
+  }
+
+  return records.filter(record => !record.scopeId || record.scopeId === context.scopeId);
+}
+
+export interface SearchResult {
+  /** Route including the section anchor. */
+  url: string;
+  /** Page title. */
+  page: string;
+  /** Section heading, absent for the page intro. */
+  heading?: string;
+  /** Snippet of section text around the first match, when the text matched. */
+  snippet?: string;
+  /** Provider-specific relevance score. Use 0 when a provider does not expose one. */
+  score: number;
+}
+
+const SNIPPET_RADIUS = 60;
+
+function makeSnippet(text: string, index: number, length: number): string {
+  const start = Math.max(0, index - SNIPPET_RADIUS);
+  const end = Math.min(text.length, index + length + SNIPPET_RADIUS);
+
+  return `${start > 0 ? '…' : ''}${text.slice(start, end).trim()}${end < text.length ? '…' : ''}`;
+}
+
+export function searchIndex(records: SearchRecord[], query: string, limit = 10): SearchResult[] {
+  const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
+
+  if (!terms.length) {
+    return [];
+  }
+
+  const results: SearchResult[] = [];
+
+  for (const record of records) {
+    const page = record.page.toLowerCase();
+    const heading = (record.heading || '').toLowerCase();
+    const text = record.text.toLowerCase();
+
+    let score = 0;
+    let snippetAt = -1;
+    let snippetLength = 0;
+    let matched = true;
+
+    for (const term of terms) {
+      if (page.includes(term)) {
+        score += page === term ? 40 : 20;
+      } else if (heading.includes(term)) {
+        score += heading === term ? 30 : 15;
+      } else {
+        const index = text.indexOf(term);
+
+        if (index === -1) {
+          matched = false;
+          break;
+        }
+
+        score += 5;
+
+        if (snippetAt === -1) {
+          snippetAt = index;
+          snippetLength = term.length;
+        }
+      }
+    }
+
+    if (!matched || !score) {
+      continue;
+    }
+
+    results.push({
+      url: record.id ? `${record.url}#${record.id}` : record.url,
+      page: record.page,
+      heading: record.heading,
+      snippet: snippetAt >= 0 ? makeSnippet(record.text, snippetAt, snippetLength) : undefined,
+      score,
+    });
+  }
+
+  return results.sort((a, b) => b.score - a.score).slice(0, limit);
+}

package/src/lib/site-config.ts

@@ -0,0 +1,117 @@
+import rawConfig from 'virtual:shiso-docs-config';
+import { resolveDocFile } from '@/lib/content';
+import {
+  assertDocsConfig,
+  getDefaultScope,
+  getScopeForPage,
+  getPageByPathname as getSitePageByPathname,
+  normalizeDocsSite,
+} from '@/lib/docs-config';
+import { getTextDirection, resolveLocale } from '@/lib/locale';
+import { stripBase } from '@/lib/paths';
+import { resolveSiteModel } from '@/lib/site-model';
+import type {
+  DocsConfig,
+  DocsScope,
+  NormalizedDocsConfig,
+  NormalizedDocsPage,
+  NormalizedDocsSite,
+  RedirectRule,
+  SeoConfig,
+} from '@/lib/types';
+
+assertDocsConfig(rawConfig, 'docs.json');
+
+export const siteConfig: DocsConfig = rawConfig;
+
+/** The complete normalized site: every version/language scope. */
+export const docsSite: NormalizedDocsSite = normalizeDocsSite(siteConfig, resolveDocFile);
+
+/** The default scope's navigation, used where a single navigation is expected. */
+export const docsConfig: NormalizedDocsConfig = getDefaultScope(docsSite).docs;
+
+/** Landing page of the default scope: the site-wide "docs home" URL. */
+export const docsHomeUrl = getDefaultScope(docsSite).firstPageUrl;
+
+export const siteModel = resolveSiteModel(siteConfig, docsConfig);
+
+/** Scope that owns the current pathname; the default scope for unknown paths. */
+export function getScopeByPathname(pathname: string): DocsScope {
+  const page = getPageByPathname(pathname);
+  return page ? getScopeForPage(docsSite, page) : getDefaultScope(docsSite);
+}
+
+/** Document language and direction for a pathname, from its scope's language. */
+export function getLocaleByPathname(pathname: string): { lang: string; dir: 'ltr' | 'rtl' } {
+  const lang = resolveLocale(getScopeByPathname(pathname).language, siteModel.locale);
+  return { lang, dir: getTextDirection(lang) };
+}
+
+export const siteName = siteModel.name;
+
+/** Trailing-slash-insensitive route key for redirect matching. */
+function toRouteKey(routePath: string): string {
+  const trimmed = routePath.replace(/\/+$/, '');
+  return trimmed || '/';
+}
+
+/**
+ * Redirect rules with exact-match sources. Wildcard patterns are rejected by
+ * the schema; this guard covers configs that bypassed validation.
+ */
+export function getRedirects(): RedirectRule[] {
+  return (siteConfig.redirects || []).filter(rule => {
+    if (!rule?.source || !rule.destination) {
+      return false;
+    }
+
+    if (/[:*]/.test(rule.source)) {
+      console.warn(
+        `[shiso] Redirect source "${rule.source}" uses a wildcard pattern, which is not ` +
+          'supported — it will be skipped. Use an exact source path.',
+      );
+      return false;
+    }
+
+    return true;
+  });
+}
+
+const redirectBySource = new Map(
+  getRedirects().map(rule => [toRouteKey(rule.source), rule.destination]),
+);
+
+/** Destination for a base-relative route covered by a redirect rule, if any. */
+export function matchRedirect(routePath: string): string | null {
+  return redirectBySource.get(toRouteKey(routePath)) || null;
+}
+
+export function getSeo(): SeoConfig {
+  const seo = siteConfig.seo || {};
+
+  return {
+    metatags: seo.metatags || {},
+    indexing: seo.indexing === 'all' ? 'all' : 'navigable',
+  };
+}
+
+/** True when the last-modified timestamp should show for a page. */
+export function showTimestamp(frontmatterValue: unknown): boolean {
+  if (typeof frontmatterValue === 'boolean') {
+    return frontmatterValue;
+  }
+
+  return siteModel.showTimestamp;
+}
+
+export function getPageByPathname(pathname: string): NormalizedDocsPage | null {
+  return getSitePageByPathname(docsSite, stripBase(pathname));
+}
+
+export function getPageTitle(pageTitle?: string): string {
+  if (pageTitle && siteName) {
+    return `${pageTitle} – ${siteName}`;
+  }
+
+  return pageTitle || siteName || '';
+}

package/src/lib/site-model.ts

@@ -0,0 +1,221 @@
+import { toAbsoluteUrl, toHref } from '@/lib/paths';
+import { resolveSearchConfig } from '@/lib/search/config';
+import type {
+  ConfigLink,
+  ContextualOption,
+  ContextualOptionObject,
+  DocsConfig,
+  LinkTarget,
+  NormalizedDocsConfig,
+  NormalizedDocsPage,
+  NormalizedFooter,
+  NormalizedLink,
+  NormalizedNavbar,
+  ResolvedContextualOption,
+  SiteModel,
+  ThemeLabels,
+} from '@/lib/types';
+
+const SHISO_THEME_LABELS: ThemeLabels = {
+  menu: 'Menu',
+  documentationNavigation: 'Documentation navigation',
+  sections: 'Sections',
+  tableOfContents: 'On this page',
+  tableOfContentsNavigation: 'Table of contents',
+  searchTitle: 'Search',
+  searching: 'Searching...',
+  searchUnavailable: 'Search unavailable',
+  noResults: 'No results',
+  lastUpdated: 'Last updated on',
+  notFound: 'Page not found',
+  dismissBanner: 'Dismiss banner',
+  toggleTheme: 'Toggle theme',
+  moreOptions: 'More options',
+  copied: 'Copied',
+  expand: 'Expand',
+  collapse: 'Collapse',
+  copyPage: 'Copy page',
+  copyPageDescription: 'Copy this page as Markdown',
+  viewMarkdown: 'View as Markdown',
+  viewMarkdownDescription: 'Open this page as plain Markdown',
+  openInChatGPT: 'Open in ChatGPT',
+  openInClaude: 'Open in Claude',
+  openInPerplexity: 'Open in Perplexity',
+  askQuestionsAboutPage: 'Ask questions about this page',
+};
+
+function isInternalHref(href: string): boolean {
+  return /^(?:#|\/|\.\.?\/)/.test(href);
+}
+
+export function resolveLinkTarget(href: string, target?: LinkTarget): LinkTarget {
+  return target || (isInternalHref(href) ? '_self' : '_blank');
+}
+
+function normalizeLink(link: ConfigLink): NormalizedLink {
+  return {
+    href: link.href,
+    label: link.label?.trim() || undefined,
+    ariaLabel: link.ariaLabel?.trim() || undefined,
+    icon: link.icon?.trim() || undefined,
+    target: resolveLinkTarget(link.href, link.target),
+  };
+}
+
+function normalizeNavbar(config: DocsConfig['navbar']): NormalizedNavbar | null {
+  if (!config) {
+    return null;
+  }
+
+  const links = (config.links || []).filter(link => !!link?.href).map(normalizeLink);
+  const primary = config.primary?.href ? normalizeLink(config.primary) : undefined;
+
+  return links.length || primary ? { links, primary } : null;
+}
+
+function normalizeFooter(config: DocsConfig['footer']): NormalizedFooter | null {
+  const socials = (config?.socials || []).filter(link => !!link?.href).map(normalizeLink);
+  const links = (config?.links || [])
+    .filter(column => column?.items?.length)
+    .map(column => ({
+      ...column,
+      items: column.items.map(item => ({
+        ...item,
+        target: resolveLinkTarget(item.href, item.target),
+      })),
+    }));
+  const attribution = config?.attribution !== false;
+
+  return socials.length || links.length || attribution ? { socials, links, attribution } : null;
+}
+
+export function resolveSiteModel(config: DocsConfig, docs: NormalizedDocsConfig): SiteModel {
+  const appearance = config.appearance || {};
+  const logo = config.logo
+    ? typeof config.logo === 'string'
+      ? { light: config.logo, dark: config.logo }
+      : {
+          light: config.logo.light || config.logo.dark,
+          dark: config.logo.dark || config.logo.light,
+          href: config.logo.href,
+          target: config.logo.href
+            ? resolveLinkTarget(config.logo.href, config.logo.target)
+            : undefined,
+        }
+    : null;
+
+  return {
+    name: config.name?.trim() || undefined,
+    logo,
+    navbar: normalizeNavbar(config.navbar),
+    footer: normalizeFooter(config.footer),
+    banner: config.banner?.content?.trim()
+      ? { content: config.banner.content.trim(), dismissible: config.banner.dismissible === true }
+      : null,
+    appearance: {
+      default:
+        appearance.default === 'light' || appearance.default === 'dark'
+          ? appearance.default
+          : 'system',
+      strict: appearance.strict === true,
+    },
+    styling: {
+      eyebrows: config.styling?.eyebrows === 'breadcrumbs' ? 'breadcrumbs' : 'section',
+    },
+    search: resolveSearchConfig(config.search),
+    contextualOptions: config.contextual?.options || [],
+    error404: { ...config.errors?.['404'], redirect: config.errors?.['404']?.redirect !== false },
+    showTimestamp: config.metadata?.timestamp === true,
+    drilldown: config.interaction?.drilldown,
+    locale: config.$shiso?.locale?.trim() || 'en-US',
+    labels: SHISO_THEME_LABELS,
+    docs,
+  };
+}
+
+function aiPrompt(mdUrl: string): string {
+  return `Read ${mdUrl} so I can ask questions about it.`;
+}
+
+export function resolveContextualOptions(
+  options: ContextualOption[],
+  page: NormalizedDocsPage,
+  labels: ThemeLabels = SHISO_THEME_LABELS,
+): ResolvedContextualOption[] {
+  const mdHref = `${toHref(page.url)}.md`;
+  const absolutePageUrl = toAbsoluteUrl(page.url);
+  const mdUrl = absolutePageUrl ? `${absolutePageUrl}.md` : undefined;
+  const resolved: ResolvedContextualOption[] = [];
+
+  for (const option of options) {
+    if (typeof option !== 'string') {
+      const custom = option as ContextualOptionObject;
+      const href = custom.href.replaceAll('$path', page.url).replaceAll('$page', mdUrl || mdHref);
+
+      resolved.push({
+        key: custom.title,
+        title: custom.title,
+        description: custom.description,
+        icon: custom.icon,
+        action: 'link',
+        href,
+        target: resolveLinkTarget(href, custom.target),
+      });
+      continue;
+    }
+
+    if (option === 'copy') {
+      resolved.push({
+        key: option,
+        title: labels.copyPage,
+        description: labels.copyPageDescription,
+        icon: 'copy',
+        action: 'copy',
+        href: mdHref,
+        target: '_self',
+      });
+    } else if (option === 'view') {
+      resolved.push({
+        key: option,
+        title: labels.viewMarkdown,
+        description: labels.viewMarkdownDescription,
+        icon: 'external-link',
+        action: 'link',
+        href: mdHref,
+        target: '_blank',
+      });
+    } else if (mdUrl && option === 'chatgpt') {
+      resolved.push({
+        key: option,
+        title: labels.openInChatGPT,
+        description: labels.askQuestionsAboutPage,
+        icon: 'external-link',
+        action: 'link',
+        href: `https://chatgpt.com/?q=${encodeURIComponent(aiPrompt(mdUrl))}`,
+        target: '_blank',
+      });
+    } else if (mdUrl && option === 'claude') {
+      resolved.push({
+        key: option,
+        title: labels.openInClaude,
+        description: labels.askQuestionsAboutPage,
+        icon: 'external-link',
+        action: 'link',
+        href: `https://claude.ai/new?q=${encodeURIComponent(aiPrompt(mdUrl))}`,
+        target: '_blank',
+      });
+    } else if (mdUrl && option === 'perplexity') {
+      resolved.push({
+        key: option,
+        title: labels.openInPerplexity,
+        description: labels.askQuestionsAboutPage,
+        icon: 'external-link',
+        action: 'link',
+        href: `https://www.perplexity.ai/search?q=${encodeURIComponent(aiPrompt(mdUrl))}`,
+        target: '_blank',
+      });
+    }
+  }
+
+  return resolved;
+}

package/src/lib/slug.ts

@@ -0,0 +1,38 @@
+import GithubSlugger, { slug as slugifyOnce } from 'github-slugger';
+
+/**
+ * The single slug algorithm in the repo.
+ *
+ * Heading anchors are produced in two independent places — `remarkToc` (which
+ * builds the on-page table of contents) and `rehype-slug` (which sets the `id`
+ * on the rendered heading). Both must agree or every TOC link breaks, so both
+ * go through github-slugger here rather than reimplementing it.
+ */
+
+/**
+ * Creates a stateful slugger. Call `.slug(text)` once per heading in document
+ * order; repeated headings get `-1`, `-2`, ... suffixes exactly as rehype-slug
+ * does, because it is the same implementation.
+ */
+export function createSlugger(): GithubSlugger {
+  return new GithubSlugger();
+}
+
+/**
+ * Stateless slugify for one-off ids that do not need de-duplication.
+ *
+ * github-slugger does not trim, so padded input would otherwise produce leading
+ * and trailing dashes. Heading text is trimmed upstream by `headingText`; this
+ * makes the guarantee hold for every other caller too.
+ */
+export function slugify(value: string): string {
+  return slugifyOnce(value.trim());
+}
+
+/**
+ * Slugifies a label into a config-level identifier (tab ids, section ids).
+ * Falls back when the value contains no slug-able characters.
+ */
+export function slugifyId(value: string, fallback: string): string {
+  return slugify(value) || fallback;
+}