@umami/shiso 0.61.0 → 1.0.0

package/src/lib/search/provider.ts

@@ -1,7 +1,12 @@
-import type { SearchResult } from '@/lib/search';
+import type { SearchContext, SearchResult } from '@/lib/search';
 
 export interface SearchProvider {
-  search(query: string, limit?: number): Promise<SearchResult[]>;
+  /**
+   * `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 = (

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

@@ -1,5 +1,5 @@
 import type { SearchRecord } from '@/lib/search';
-import { searchIndex } 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. */
@@ -7,9 +7,9 @@ export function createLocalSearchProvider(_options: Record<string, unknown> = {}
   let records: Promise<SearchRecord[]> | null = null;
 
   return {
-    async search(query, limit) {
+    async search(query, limit, context) {
       records ||= import('@/lib/search-index.generated').then(module => module.SEARCH_INDEX);
-      return searchIndex(await records, query, limit);
+      return searchIndex(filterRecordsByScope(await records, context), query, limit);
     },
   };
 }

package/src/lib/search.ts

@@ -18,6 +18,34 @@ export interface SearchRecord {
   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 {

package/src/lib/site-config.ts

@@ -1,12 +1,21 @@
 import rawConfig from 'virtual:shiso-docs-config';
 import { resolveDocFile } from '@/lib/content';
-import { assertDocsConfig, normalizeDocsConfig } from '@/lib/docs-config';
-import { stripBase, stripDocsPrefix } from '@/lib/paths';
+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';
@@ -15,10 +24,29 @@ assertDocsConfig(rawConfig, 'docs.json');
 
 export const siteConfig: DocsConfig = rawConfig;
 
-export const docsConfig: NormalizedDocsConfig = normalizeDocsConfig(siteConfig, resolveDocFile);
+/** 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. */
@@ -28,8 +56,8 @@ function toRouteKey(routePath: string): string {
 }
 
 /**
- * Redirect rules with exact-match sources. Wildcard patterns are part of the
- * standard but not implemented; they are skipped with a warning.
+ * 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 => {
@@ -40,7 +68,7 @@ export function getRedirects(): RedirectRule[] {
     if (/[:*]/.test(rule.source)) {
       console.warn(
         `[shiso] Redirect source "${rule.source}" uses a wildcard pattern, which is not ` +
-          'implemented yet — it will be skipped.',
+          'supported — it will be skipped. Use an exact source path.',
       );
       return false;
     }
@@ -76,23 +104,8 @@ export function showTimestamp(frontmatterValue: unknown): boolean {
   return siteModel.showTimestamp;
 }
 
-export function normalizeParamSlug(slug: string): string {
-  const cleaned = slug.replace(/^\/+|\/+$/g, '');
-
-  if (!cleaned) {
-    return 'index';
-  }
-
-  if (cleaned === 'index') {
-    return cleaned;
-  }
-
-  return cleaned.replace(/\/index$/, '') || 'index';
-}
-
 export function getPageByPathname(pathname: string): NormalizedDocsPage | null {
-  const slug = normalizeParamSlug(stripDocsPrefix(stripBase(pathname)));
-  return docsConfig.pageByLookupSlug[slug] || null;
+  return getSitePageByPathname(docsSite, stripBase(pathname));
 }
 
 export function getPageTitle(pageTitle?: string): string {

package/src/lib/types.ts

@@ -54,7 +54,7 @@ export interface TabItem {
 
 export interface AnchorItem {
   anchor: string;
-  href?: string;
+  href: string;
   icon?: string;
   hidden?: boolean;
   target?: LinkTarget;
@@ -318,6 +318,12 @@ export interface NormalizedDocsPage {
   tabId: string;
   tabLabel: string;
   order: number;
+  /** Id of the navigation scope (version/language) this page belongs to. */
+  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;
   /**
    * Hidden pages are still routed and prerendered, so they remain reachable by
    * URL, but are excluded from the sidebar, prev/next, the
@@ -377,10 +383,41 @@ export interface NormalizedDocsConfig {
 }
 
 export interface NormalizeOptions {
-  /** Route prefix for docs pages. Phases 6/7 pass "/v2/docs", "/es/docs", etc. */
+  /** Route prefix for docs pages. Default "/docs"; "" serves docs at the root. */
   docsPrefix?: string;
 }
 
+/**
+ * One navigation scope of a site: the ordinary navigation, a version, a
+ * language, or a version nested inside a language. Page references alone
+ * determine URLs; scopes never add their own URL prefixes.
+ */
+export interface DocsScope {
+  id: string;
+  /** Language label, when this scope belongs to a language. */
+  language?: string;
+  /** Version label, when this scope belongs to a version. */
+  version?: string;
+  /** Hidden scopes still build, but are omitted from switchers. */
+  hidden?: boolean;
+  isDefault: boolean;
+  /** Landing scope of its language: the language's default version. */
+  isLanguageDefault: boolean;
+  /** URL of the scope's first visible page — the landing page for switchers. */
+  firstPageUrl: string;
+  docs: NormalizedDocsConfig;
+}
+
+/** The complete normalized site: every scope, with global page lookups. */
+export interface NormalizedDocsSite {
+  scopes: DocsScope[];
+  defaultScopeId: string;
+  /** Every routed page across all scopes, in scope order. */
+  pages: NormalizedDocsPage[];
+  /** Exact canonical URL to page, across all scopes. */
+  pageByUrl: Record<string, NormalizedDocsPage>;
+}
+
 export interface NormalizedLink extends ConfigLink {
   target: LinkTarget;
 }

package/types/search.d.ts

@@ -6,8 +6,18 @@ export interface SearchResult {
   snippet?: string;
 }
 
+/**
+ * Where a search originates, so providers can keep results inside the
+ * version/language scope being browsed. Providers may ignore it.
+ */
+export interface SearchContext {
+  scopeId?: string;
+  language?: string;
+  version?: string;
+}
+
 export interface SearchProvider {
-  search(query: string, limit?: number): Promise<SearchResult[]>;
+  search(query: string, limit?: number, context?: SearchContext): Promise<SearchResult[]>;
 }
 
 export type SearchProviderFactory = (