@umami/shiso 0.61.0 → 1.0.0

package/src/lib/docs-config.ts

@@ -3,16 +3,19 @@ import { slugifyId } from '@/lib/slug';
 import type {
   AnchorItem,
   DocsConfig,
+  DocsScope,
   DropdownItem,
   GroupItem,
   LanguageItem,
   LinkTarget,
   NavGroupNode,
+  NavigationConfig,
   NavLinkNode,
   NavNode,
   NavPageNode,
   NormalizedDocsConfig,
   NormalizedDocsPage,
+  NormalizedDocsSite,
   NormalizeOptions,
   PageItem,
   TabItem,
@@ -34,24 +37,6 @@ function normalizeLinkTarget(href: string, target?: LinkTarget): LinkTarget {
   return target || (/^(?:#|\/|\.\.?\/)/.test(href) ? '_self' : '_blank');
 }
 
-/**
- * Recognized config keys that Shiso does not implement.
- * Policy: warn once and skip. Never fail a build over an unimplemented feature —
- * the same rule the schema validator applies to top-level keys.
- */
-const RESERVED_PAGE_KEYS = ['openapi', 'api', 'asyncapi', 'graphql', 'menu', 'product'];
-
-const warned = new Set<string>();
-
-function warnOnce(message: string) {
-  if (warned.has(message)) {
-    return;
-  }
-
-  warned.add(message);
-  console.warn(`[shiso] ${message}`);
-}
-
 export function assertDocsConfig(value: unknown, sourceName: string): asserts value is DocsConfig {
   if (!isRecord(value)) {
     throw new Error(`Invalid docs config in "${sourceName}": expected a JSON object.`);
@@ -108,10 +93,6 @@ function pageToUrl(slug: string, docsPrefix: string): string {
   return slug === 'index' ? base || '/' : `${base}/${slug}`;
 }
 
-function pickDefaultItem<T extends { default?: boolean }>(items: T[]): T {
-  return items.find(item => item.default) || items[0];
-}
-
 function dropdownsToTabs(dropdowns: DropdownItem[]): TabItem[] {
   return dropdowns.map((dropdown, index) => {
     const label = dropdown.dropdown?.trim();
@@ -141,18 +122,88 @@ interface NavContainer {
 }
 
 /**
- * Resolves a navigation container down to a flat list of tabs.
- *
- * Versions and languages collapse to their default entry for now. That is a
- * real limitation, so the skipped entries are reported rather than silently
- * dropped; Phases 6 and 7 replace this by normalizing once per version/locale.
+ * The mutually exclusive primary navigation modes a container may declare.
+ * `groups` and `pages` combine into one simple-navigation mode.
+ */
+function getNavigationModes(container: NavContainer): string[] {
+  const modes: string[] = [];
+
+  if (container.tabs !== undefined) {
+    modes.push('tabs');
+  }
+
+  if (container.dropdowns !== undefined) {
+    modes.push('dropdowns');
+  }
+
+  if (container.versions !== undefined) {
+    modes.push('versions');
+  }
+
+  if (container.languages !== undefined) {
+    modes.push('languages');
+  }
+
+  if (container.groups !== undefined || container.pages !== undefined) {
+    modes.push('groups/pages');
+  }
+
+  return modes;
+}
+
+/** Rejects a container that declares more than one primary navigation mode. */
+function assertSingleMode(container: NavContainer, where: string): void {
+  const modes = getNavigationModes(container);
+
+  if (modes.length > 1) {
+    throw new Error(
+      `Invalid docs config: ${where} must define exactly one of tabs, dropdowns, ` +
+        `versions, languages, or groups/pages — found ${modes.join(' and ')}.`,
+    );
+  }
+}
+
+/** Rejects arrays where more than one entry claims to be the default. */
+function assertSingleDefault<T extends { default?: boolean }>(
+  items: T[],
+  kind: string,
+  getLabel: (item: T) => string | undefined,
+) {
+  const defaults = items.filter(item => item.default === true);
+
+  if (defaults.length > 1) {
+    const labels = defaults.map(getLabel).filter(Boolean);
+
+    throw new Error(
+      `Invalid docs config: multiple ${kind} are marked "default": ${labels.join(', ')}. ` +
+        `Only one ${kind.replace(/s$/, '')} may be the default.`,
+    );
+  }
+}
+
+/** Explicit default first, then the first visible entry, then the first entry. */
+function pickDefaultEntry<T extends { default?: boolean; hidden?: boolean }>(items: T[]): T {
+  return items.find(item => item.default === true) || items.find(item => !item.hidden) || items[0];
+}
+
+/**
+ * Resolves a leaf navigation container (one that no longer carries versions or
+ * languages) down to a flat list of tabs.
  */
-function getTabsFromContainer(container: NavContainer, fallbackLabel = ''): TabItem[] {
-  if (Array.isArray(container.tabs) && container.tabs.length) {
+function getTabsFromLeafContainer(container: NavContainer, fallbackLabel = ''): TabItem[] {
+  if (Array.isArray(container.tabs)) {
+    if (!container.tabs.length) {
+      throw new Error('Invalid docs config: "tabs" must contain at least one tab.');
+    }
+
     return container.tabs;
   }
 
-  if (Array.isArray(container.dropdowns) && container.dropdowns.length) {
+  if (Array.isArray(container.dropdowns)) {
+    if (!container.dropdowns.length) {
+      throw new Error('Invalid docs config: "dropdowns" must contain at least one dropdown.');
+    }
+
     return dropdownsToTabs(container.dropdowns);
   }
 
@@ -166,58 +217,159 @@ function getTabsFromContainer(container: NavContainer, fallbackLabel = ''): TabI
     ];
   }
 
-  if (Array.isArray(container.versions) && container.versions.length) {
-    const version = pickDefaultItem(container.versions);
-    const skipped = container.versions.filter(item => item !== version).map(item => item.version);
-
-    if (skipped.length) {
-      warnOnce(
-        `Only the default version "${version.version}" is rendered; skipped: ${skipped.join(', ')}. ` +
-          'Multi-version output is not implemented yet.',
-      );
-    }
-
-    return getTabsFromContainer(version, version.version?.trim() || fallbackLabel);
-  }
-
-  if (Array.isArray(container.languages) && container.languages.length) {
-    const language = pickDefaultItem(container.languages);
-    const skipped = container.languages
-      .filter(item => item !== language)
-      .map(item => item.language);
-
-    if (skipped.length) {
-      warnOnce(
-        `Only the default language "${language.language}" is rendered; skipped: ${skipped.join(', ')}. ` +
-          'Multi-language output is not implemented yet.',
-      );
-    }
-
-    return getTabsFromContainer(language, language.language?.trim() || fallbackLabel);
-  }
-
   throw new Error(
     'Invalid docs config: navigation must define tabs, dropdowns, groups, pages, versions, or languages.',
   );
 }
 
 function hasExplicitTopNavigation(container: NavContainer): boolean {
-  if (
+  return (
     (Array.isArray(container.tabs) && container.tabs.length > 0) ||
     (Array.isArray(container.dropdowns) && container.dropdowns.length > 0)
-  ) {
-    return true;
+  );
+}
+
+/* ---------------------------------------------------------------------------
+ * Scope collection
+ *
+ * A docs site normalizes into one or more scopes: the ordinary navigation, one
+ * per version, one per language, or one per version nested inside a language.
+ * Page references alone determine URLs — scopes never add URL prefixes.
+ * ------------------------------------------------------------------------- */
+
+interface ScopeSource {
+  id: string;
+  language?: string;
+  version?: string;
+  hidden?: boolean;
+  isDefault: boolean;
+  /** Landing scope of its language: the language's default version. */
+  isLanguageDefault: boolean;
+  /** Leaf navigation container for this scope. */
+  container: NavContainer;
+  /** Label used for the synthetic tab in simple groups/pages navigation. */
+  fallbackLabel: string;
+}
+
+function makeVersionScopeSource(
+  version: VersionItem,
+  language: LanguageItem | undefined,
+  isDefault: boolean,
+  isLanguageDefault: boolean,
+): ScopeSource {
+  const versionLabel = version.version?.trim();
+
+  if (!versionLabel) {
+    throw new Error('Invalid docs config: version entry is missing "version".');
   }
 
-  if (Array.isArray(container.versions) && container.versions.length) {
-    return hasExplicitTopNavigation(pickDefaultItem(container.versions));
+  assertSingleMode(version, `version "${versionLabel}"`);
+
+  const languageLabel = language?.language?.trim();
+  const idBase = [languageLabel, versionLabel].filter(Boolean).join('-');
+
+  return {
+    id: slugifyId(idBase, 'scope'),
+    language: languageLabel || undefined,
+    version: versionLabel,
+    hidden: version.hidden || language?.hidden || undefined,
+    isDefault,
+    isLanguageDefault,
+    container: version,
+    fallbackLabel: versionLabel,
+  };
+}
+
+function collectScopeSources(navigation: NavigationConfig): ScopeSource[] {
+  assertSingleMode(navigation, 'navigation');
+
+  if (navigation.versions !== undefined) {
+    const versions = navigation.versions;
+
+    if (!Array.isArray(versions) || !versions.length) {
+      throw new Error('Invalid docs config: "versions" must contain at least one version.');
+    }
+
+    assertSingleDefault(versions, 'versions', item => item.version);
+
+    const defaultVersion = pickDefaultEntry(versions);
+
+    return versions.map(version =>
+      makeVersionScopeSource(
+        version,
+        undefined,
+        version === defaultVersion,
+        version === defaultVersion,
+      ),
+    );
   }
 
-  if (Array.isArray(container.languages) && container.languages.length) {
-    return hasExplicitTopNavigation(pickDefaultItem(container.languages));
+  if (navigation.languages !== undefined) {
+    const languages = navigation.languages;
+
+    if (!Array.isArray(languages) || !languages.length) {
+      throw new Error('Invalid docs config: "languages" must contain at least one language.');
+    }
+
+    assertSingleDefault(languages, 'languages', item => item.language);
+
+    const defaultLanguage = pickDefaultEntry(languages);
+
+    return languages.flatMap(language => {
+      const languageLabel = language.language?.trim();
+
+      if (!languageLabel) {
+        throw new Error('Invalid docs config: language entry is missing "language".');
+      }
+
+      assertSingleMode(language, `language "${languageLabel}"`);
+
+      if (language.versions !== undefined) {
+        const versions = language.versions;
+
+        if (!Array.isArray(versions) || !versions.length) {
+          throw new Error(
+            `Invalid docs config: language "${languageLabel}" "versions" must contain at least one version.`,
+          );
+        }
+
+        assertSingleDefault(versions, `language "${languageLabel}" versions`, item => item.version);
+
+        const defaultVersion = pickDefaultEntry(versions);
+
+        return versions.map(version =>
+          makeVersionScopeSource(
+            version,
+            language,
+            language === defaultLanguage && version === defaultVersion,
+            version === defaultVersion,
+          ),
+        );
+      }
+
+      return [
+        {
+          id: slugifyId(languageLabel, 'scope'),
+          language: languageLabel,
+          hidden: language.hidden || undefined,
+          isDefault: language === defaultLanguage,
+          isLanguageDefault: true,
+          container: language,
+          fallbackLabel: languageLabel,
+        },
+      ];
+    });
   }
 
-  return false;
+  return [
+    {
+      id: 'default',
+      isDefault: true,
+      isLanguageDefault: true,
+      container: navigation,
+      fallbackLabel: '',
+    },
+  ];
 }
 
 /* ---------------------------------------------------------------------------
@@ -377,16 +529,6 @@ function collectPages(items: PageItem[], context: WalkContext, state: WalkState)
       return;
     }
 
-    const reservedKey = Object.keys(item).find(key => RESERVED_PAGE_KEYS.includes(key));
-
-    if (reservedKey) {
-      warnOnce(
-        `Navigation item with "${reservedKey}" is recognized but is not ` +
-          'implemented yet — it will be skipped.',
-      );
-      return;
-    }
-
     throw new Error(
       `Invalid docs config: unrecognized page item with keys [${Object.keys(item).join(', ')}]. ` +
         'Supported items are strings, { page }, { href }, or { group, pages } blocks.',
@@ -401,30 +543,40 @@ function collectAnchors(anchors: AnchorItem[] | undefined): NavLinkNode[] {
     return [];
   }
 
-  return anchors
-    .filter(anchor => isRecord(anchor) && typeof anchor.href === 'string' && anchor.href)
-    .map(anchor => ({
+  return anchors.map((anchor, index) => {
+    const label = isRecord(anchor) && typeof anchor.anchor === 'string' ? anchor.anchor.trim() : '';
+    const href = isRecord(anchor) && typeof anchor.href === 'string' ? anchor.href : '';
+
+    if (!label || !href) {
+      throw new Error(
+        `Invalid docs config: anchor at index ${index} must define both "anchor" and "href".`,
+      );
+    }
+
+    return {
       kind: 'link' as const,
-      label: anchor.anchor?.trim() || (anchor.href as string),
-      href: anchor.href as string,
+      label,
+      href,
       icon: anchor.icon,
       hidden: anchor.hidden || undefined,
-      target: normalizeLinkTarget(anchor.href as string, anchor.target),
-    }));
+      target: normalizeLinkTarget(href, anchor.target),
+    };
+  });
 }
 
 /* ---------------------------------------------------------------------------
  * Normalization
  * ------------------------------------------------------------------------- */
 
-export function normalizeDocsConfig(
-  docsConfig: DocsConfig,
+function normalizeScope(
+  name: string | undefined,
+  source: ScopeSource,
+  anchors: AnchorItem[] | undefined,
   resolveDocFile: DocFileResolver,
-  options: NormalizeOptions = {},
+  docsPrefix: string,
 ): NormalizedDocsConfig {
-  const docsPrefix = options.docsPrefix ?? DOCS_PREFIX;
-  const tabs = getTabsFromContainer(docsConfig.navigation);
-  const showTabs = hasExplicitTopNavigation(docsConfig.navigation);
+  const tabs = getTabsFromLeafContainer(source.container, source.fallbackLabel);
+  const showTabs = hasExplicitTopNavigation(source.container);
   const state: WalkState = { pages: [], order: { value: 0 } };
   const treeByTab = new Map<string, PendingNode[]>();
   const seenTabIds = new Set<string>();
@@ -574,6 +726,9 @@ export function normalizeDocsConfig(
       ...page,
       url: pageToUrl(page.slug, docsPrefix),
       filePath,
+      scopeId: source.id,
+      language: source.language,
+      version: source.version,
     };
 
     pages.push(normalized);
@@ -638,17 +793,166 @@ export function normalizeDocsConfig(
   });
 
   return {
-    name: docsConfig.name,
+    name,
     tabs: normalizedTabs,
     showTabs,
     navigation,
-    anchors: collectAnchors(docsConfig.navigation.anchors),
+    anchors: collectAnchors(anchors),
     pages,
     pageBySlug,
     pageByLookupSlug,
   };
 }
 
+/**
+ * Normalizes the complete docs site: one scope for ordinary navigation, one per
+ * version, one per language, and one per version nested inside a language.
+ * Every scope builds, including hidden ones; hidden scopes are only omitted
+ * from switcher UI. Page references and route URLs are validated globally.
+ */
+export function normalizeDocsSite(
+  docsConfig: DocsConfig,
+  resolveDocFile: DocFileResolver,
+  options: NormalizeOptions = {},
+): NormalizedDocsSite {
+  const docsPrefix = options.docsPrefix ?? DOCS_PREFIX;
+  const sources = collectScopeSources(docsConfig.navigation);
+  const anchors = docsConfig.navigation.anchors;
+
+  const seenScopeIds = new Set<string>();
+
+  for (const source of sources) {
+    if (seenScopeIds.has(source.id)) {
+      throw new Error(
+        `Invalid docs config: duplicate version/language label resolves to duplicate scope id "${source.id}".`,
+      );
+    }
+
+    seenScopeIds.add(source.id);
+  }
+
+  const scopes: DocsScope[] = sources.map(source => {
+    const docs = normalizeScope(docsConfig.name, source, anchors, resolveDocFile, docsPrefix);
+    const firstPage = docs.pages.find(page => !page.hidden) || docs.pages[0];
+
+    return {
+      id: source.id,
+      language: source.language,
+      version: source.version,
+      hidden: source.hidden,
+      isDefault: source.isDefault,
+      isLanguageDefault: source.isLanguageDefault,
+      firstPageUrl: firstPage.url,
+      docs,
+    };
+  });
+
+  const pages: NormalizedDocsPage[] = [];
+  const pageByUrl: Record<string, NormalizedDocsPage> = {};
+  const fileOwners = new Map<string, string>();
+
+  for (const scope of scopes) {
+    for (const page of scope.docs.pages) {
+      const owner = fileOwners.get(page.fileSlug);
+
+      if (owner !== undefined) {
+        throw new Error(
+          `Invalid docs config: page "${page.fileSlug}" is referenced by multiple navigation ` +
+            'scopes. Each version/language must reference its own content files.',
+        );
+      }
+
+      fileOwners.set(page.fileSlug, scope.id);
+
+      if (pageByUrl[page.url]) {
+        throw new Error(
+          `Invalid docs config: duplicate route URL "${page.url}" across versions/languages.`,
+        );
+      }
+
+      pageByUrl[page.url] = page;
+      pages.push(page);
+    }
+  }
+
+  const defaultScope = scopes.find(scope => scope.isDefault) || scopes[0];
+
+  return { scopes, defaultScopeId: defaultScope.id, pages, pageByUrl };
+}
+
+/**
+ * Normalizes only the default scope of a site. Retained for callers that need
+ * a single navigation; multi-scope consumers use `normalizeDocsSite`.
+ */
+export function normalizeDocsConfig(
+  docsConfig: DocsConfig,
+  resolveDocFile: DocFileResolver,
+  options: NormalizeOptions = {},
+): NormalizedDocsConfig {
+  return getDefaultScope(normalizeDocsSite(docsConfig, resolveDocFile, options)).docs;
+}
+
+/* ---------------------------------------------------------------------------
+ * Site helpers
+ * ------------------------------------------------------------------------- */
+
+export function getDefaultScope(site: NormalizedDocsSite): DocsScope {
+  return site.scopes.find(scope => scope.id === site.defaultScopeId) || site.scopes[0];
+}
+
+export function getScopeById(site: NormalizedDocsSite, scopeId: string): DocsScope | null {
+  return site.scopes.find(scope => scope.id === scopeId) || null;
+}
+
+export function getScopeForPage(site: NormalizedDocsSite, page: NormalizedDocsPage): DocsScope {
+  return getScopeById(site, page.scopeId) || getDefaultScope(site);
+}
+
+/**
+ * One landing scope per language, for language switchers: the language's
+ * default-version scope, or its first visible scope when the default is
+ * hidden. Fully hidden languages are omitted.
+ */
+export function getLanguageScopes(site: NormalizedDocsSite): DocsScope[] {
+  const byLanguage = new Map<string, DocsScope[]>();
+
+  for (const scope of site.scopes) {
+    if (!scope.language) {
+      continue;
+    }
+
+    const list = byLanguage.get(scope.language) || [];
+    list.push(scope);
+    byLanguage.set(scope.language, list);
+  }
+
+  const landings: DocsScope[] = [];
+
+  for (const scopes of byLanguage.values()) {
+    const visible = scopes.filter(scope => !scope.hidden);
+
+    if (visible.length) {
+      landings.push(visible.find(scope => scope.isLanguageDefault) || visible[0]);
+    }
+  }
+
+  return landings;
+}
+
+/**
+ * Exact page lookup by pathname. Tolerates trailing slashes and explicit
+ * `/index` suffixes; everything else must match a page URL exactly.
+ */
+export function getPageByPathname(
+  site: NormalizedDocsSite,
+  pathname: string,
+): NormalizedDocsPage | null {
+  const trimmed = pathname.replace(/\/+$/, '') || '/';
+  const collapsed = trimmed === '/index' ? '/' : trimmed.replace(/\/index$/, '') || '/';
+
+  return site.pageByUrl[trimmed] || site.pageByUrl[collapsed] || null;
+}
+
 /** Flattens a navigation tree to the routed pages it contains, in document order. */
 export function flattenNav(nodes: NavNode[]): NormalizedDocsPage[] {
   const pages: NormalizedDocsPage[] = [];

package/src/lib/head.ts

@@ -1,12 +1,16 @@
 import { useEffect, useRef } from 'react';
 import { getDocModule, getLastModified } from '@/lib/content';
+import { resolveLocale } from '@/lib/locale';
 import { SITE_URL, toAbsoluteUrl } from '@/lib/paths';
 import {
+  getLocaleByPathname,
   getPageByPathname,
   getPageTitle,
+  getScopeByPathname,
   getSeo,
   showTimestamp,
   siteConfig,
+  siteModel,
   siteName,
 } from '@/lib/site-config';
 
@@ -53,10 +57,10 @@ export function buildHead(pathname: string): HeadTag[] {
   const title = getPageTitle(pageTitle);
   const description = frontmatter?.description || siteConfig.description;
   const canonical = page ? toAbsoluteUrl(page.url) : undefined;
-  // `seo.indexing: "all"` opts hidden pages into the index; explicit
-  // per-page `noindex` frontmatter always wins.
-  const noindex =
-    !page || frontmatter?.noindex === true || (!!page.hidden && seo.indexing !== 'all');
+  // `seo.indexing: "all"` opts hidden pages (and hidden versions/languages)
+  // into the index; explicit per-page `noindex` frontmatter always wins.
+  const hidden = !!page && (!!page.hidden || !!getScopeByPathname(pathname).hidden);
+  const noindex = !page || frontmatter?.noindex === true || (hidden && seo.indexing !== 'all');
 
   const tags: HeadTag[] = [{ tag: 'title', children: title }];
 
@@ -140,6 +144,7 @@ export function buildHead(pathname: string): HeadTag[] {
           headline: pageTitle || page.label,
           description,
           url: canonical,
+          inLanguage: resolveLocale(page.language, siteModel.locale),
           ...(siteName ? { isPartOf: { '@type': 'WebSite', name: siteName, url: SITE_URL } } : {}),
         },
         {
@@ -216,5 +221,11 @@ export function useHead(pathname: string) {
     }
 
     applyHead(buildHead(pathname));
+
+    // Keep the document language and direction in sync when navigating
+    // between language scopes.
+    const { lang, dir } = getLocaleByPathname(pathname);
+    document.documentElement.lang = lang;
+    document.documentElement.dir = dir;
   }, [pathname]);
 }

package/src/lib/locale.ts

@@ -0,0 +1,39 @@
+/** Primary language subtags written right-to-left. */
+const RTL_LANGUAGES = new Set(['ar', 'ckb', 'dv', 'fa', 'he', 'iw', 'ps', 'sd', 'ug', 'ur', 'yi']);
+
+/** BCP 47-shaped tags with a 2-3 letter primary subtag, e.g. "es" or "pt-BR". */
+const LOCALE_PATTERN = /^[a-z]{2,3}(-[a-z0-9]{2,8})*$/i;
+
+export function isValidLocale(value: string | undefined): value is string {
+  if (!value || !LOCALE_PATTERN.test(value)) {
+    return false;
+  }
+
+  try {
+    return Intl.getCanonicalLocales(value).length > 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Locale for a page: its scope's language code when valid, then the
+ * site-wide `$shiso.locale`, then en-US.
+ */
+export function resolveLocale(language: string | undefined, fallback: string | undefined): string {
+  if (isValidLocale(language)) {
+    return Intl.getCanonicalLocales(language)[0];
+  }
+
+  if (isValidLocale(fallback)) {
+    return Intl.getCanonicalLocales(fallback)[0];
+  }
+
+  return 'en-US';
+}
+
+/** Document direction for a locale, e.g. "ar" and "he" read right-to-left. */
+export function getTextDirection(locale: string): 'ltr' | 'rtl' {
+  const primary = locale.split('-')[0]?.toLowerCase() || '';
+  return RTL_LANGUAGES.has(primary) ? 'rtl' : 'ltr';
+}