@tuwaio/docs-ui 0.6.0 → 0.7.0

package/README.md

@@ -197,7 +197,7 @@ declare module '*.mdx' {
 }
 ```
 
-A translation keeps the structure of its English page: the same code blocks in the same order, the same heading levels with the English heading ids written as `## Встановлення [#-installation]` (so anchors work in every language) and the same links. `tuwa-docs-i18n-check`, run from the docs app, checks it and that every translated page exists in every language; add it to the build and to the pre-commit hook:
+A translation keeps the structure of its English page: the same code blocks in the same order, the same heading levels with the English heading ids written as `## Встановлення [#-installation]` (so anchors work in every language) and the same links. `tuwa-docs-i18n-check`, run from the docs app, checks it and that every translated page exists in every language (it gives headings their ids with the `github-slugger` of the site's `nextra` and fails when that cannot be loaded); add it to the build and to the pre-commit hook:
 
 ```json
 {
@@ -210,6 +210,8 @@ A translation keeps the structure of its English page: the same code blocks in t
 
 Client components inside `DocsLayout` read the language and the interface texts with `useDocsI18n()`.
 
+`NextraDocsLayout` is the same layout without state: the language, its texts (`docsLabels[locale]`) and the page map come from props. The docs hub renders it with its own dictionaries and translates its sidebar by route with `localizePageMap(pageMap, {}, { routes })`.
+
 ### Search index
 
 Run the command after `next build`. It uses the `pagefind` package of the site, so add it to the site's dependencies:

package/dist/components/DocsLayout.cjs

@@ -19,7 +19,8 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var DocsLayout_exports = {};
 __export(DocsLayout_exports, {
-  DocsLayout: () => DocsLayout
+  DocsLayout: () => DocsLayout,
+  NextraDocsLayout: () => NextraDocsLayout
 });
 module.exports = __toCommonJS(DocsLayout_exports);
 var import_jsx_runtime = require("react/jsx-runtime");
@@ -32,51 +33,73 @@ var import_pageMap = require("../pageMap");
 var import_Footer = require("./Footer");
 var import_LocaleSwitcher = require("./LocaleSwitcher");
 var import_NavBar = require("./NavBar");
-function LocalizedLayout({
+function NextraDocsLayout({
   logo,
   links,
   footerLinks,
   pageMap,
   docsRepositoryBase,
-  sidebarTitles,
+  locale,
+  onLocaleChange,
+  labels,
+  sidebar,
   children
 }) {
-  const { locale, setLocale, t } = (0, import_docsI18n.useDocsI18n)();
-  const siteTitles = locale === "en" ? void 0 : sidebarTitles?.[locale];
-  const localizedPageMap = (0, import_react.useMemo)(
-    () => (0, import_pageMap.localizePageMap)(pageMap, { ...t.sidebar, ...siteTitles }),
-    [pageMap, t.sidebar, siteTitles]
-  );
   return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
     import_nextra_theme_docs.Layout,
     {
-      navbar: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_NavBar.Navbar, { logo, links, children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_LocaleSwitcher.LocaleSwitcher, { locale, onSelect: setLocale, ariaLabel: t.selectLanguage }) }),
-      footer: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_Footer.Footer, { logo, links: footerLinks, labels: t.footer, policyLanguage: (0, import_locale.policyLanguageOf)(locale) }),
-      pageMap: localizedPageMap,
+      navbar: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_NavBar.Navbar, { logo, links, children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+        import_LocaleSwitcher.LocaleSwitcher,
+        {
+          locale,
+          onSelect: (code) => {
+            const picked = (0, import_locale.normalizeLocale)(code);
+            if (picked) onLocaleChange(picked);
+          },
+          ariaLabel: labels.selectLanguage
+        }
+      ) }),
+      footer: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_Footer.Footer, { logo, links: footerLinks, labels: labels.footer, policyLanguage: (0, import_locale.policyLanguageOf)(locale) }),
+      pageMap,
       docsRepositoryBase,
       navigation: { prev: true, next: true },
-      editLink: t.nextra.editThisPage,
-      feedback: { content: t.nextra.feedback },
-      lastUpdated: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_nextra_theme_docs.LastUpdated, { locale, children: t.nextra.lastUpdated }),
-      toc: { title: t.nextra.onThisPage, backToTop: t.nextra.scrollToTop },
-      themeSwitch: { light: t.nextra.themeLight, dark: t.nextra.themeDark, system: t.nextra.themeSystem },
+      ...sidebar && { sidebar },
+      editLink: labels.nextra.editThisPage,
+      feedback: { content: labels.nextra.feedback },
+      lastUpdated: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_nextra_theme_docs.LastUpdated, { locale, children: labels.nextra.lastUpdated }),
+      toc: { title: labels.nextra.onThisPage, backToTop: labels.nextra.scrollToTop },
+      themeSwitch: {
+        light: labels.nextra.themeLight,
+        dark: labels.nextra.themeDark,
+        system: labels.nextra.themeSystem
+      },
       search: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
         import_components.Search,
         {
-          placeholder: t.nextra.searchPlaceholder,
-          emptyResult: t.nextra.searchEmpty,
-          errorText: t.nextra.searchError,
-          loading: t.nextra.searchLoading
+          placeholder: labels.nextra.searchPlaceholder,
+          emptyResult: labels.nextra.searchEmpty,
+          errorText: labels.nextra.searchError,
+          loading: labels.nextra.searchLoading
         }
       ),
       children
     }
   );
 }
+function LocalizedLayout({ pageMap, sidebarTitles, ...props }) {
+  const { locale, setLocale, t } = (0, import_docsI18n.useDocsI18n)();
+  const siteTitles = locale === "en" ? void 0 : sidebarTitles?.[locale];
+  const localizedPageMap = (0, import_react.useMemo)(
+    () => (0, import_pageMap.localizePageMap)(pageMap, { ...t.sidebar, ...siteTitles }),
+    [pageMap, t.sidebar, siteTitles]
+  );
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(NextraDocsLayout, { ...props, pageMap: localizedPageMap, locale, onLocaleChange: setLocale, labels: t });
+}
 function DocsLayout({ initialLocale, ...props }) {
   return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_docsI18n.DocsI18nProvider, { initialLocale, children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(LocalizedLayout, { ...props }) });
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  DocsLayout
+  DocsLayout,
+  NextraDocsLayout
 });

package/dist/components/DocsLayout.d.cts

@@ -1,8 +1,11 @@
 import * as react from 'react';
-import { ReactNode } from 'react';
+import { ReactNode, ComponentProps } from 'react';
 import { PageMapItem } from 'nextra';
+import { Layout } from 'nextra-theme-docs';
+import { DocsLabels } from '../docsLabels.cjs';
 import { TuwaLocale } from '../locale.cjs';
 import { SocialLink } from './NavBar.cjs';
+import '../policies.cjs';
 
 /**
  * Props of {@link DocsLayout}.
@@ -29,12 +32,52 @@ interface DocsLayoutProps {
     children: ReactNode;
 }
 /**
- * The layout of a TUWA project documentation site in three languages (English, Ukrainian, Simplified Chinese): the
- * Nextra `Layout` with the docs-ui {@link Navbar} (the language switch after the links; the theme switch stays in the
- * Nextra sidebar and the mobile menu), the {@link Footer}, the search, the table of contents, the edit, feedback and
- * last-updated texts and the sidebar titles in the language of the reader. Render it in the `<body>` of the root
- * layout, around the page; pages rendered with `createDocsPage` (`@tuwaio/docs-ui/nextra/page`) switch to their
- * translation.
+ * Props of {@link NextraDocsLayout}.
+ */
+interface NextraDocsLayoutProps {
+    /** Logo of the site, for example `SiteLogo`; rendered in the navbar and the footer. */
+    logo: ReactNode;
+    /** External links of the navbar (default: `baseNavLinks`). */
+    links?: SocialLink[];
+    /** External links of the footer (default: `baseFooterLinks`). */
+    footerLinks?: SocialLink[];
+    /** The page map, already in the language of the reader (`localizePageMap`); passed to Nextra as it is. */
+    pageMap: PageMapItem[];
+    /** URL of the docs app in the repository, for the edit links. */
+    docsRepositoryBase: string;
+    /** The language of the reader, shown in the language switch and used for the dates and the policy links. */
+    locale: TuwaLocale;
+    /**
+     * Called with the language the reader picks in the switch.
+     *
+     * @param locale - The picked language.
+     */
+    onLocaleChange: (locale: TuwaLocale) => void;
+    /** The interface texts of that language, `docsLabels[locale]`. */
+    labels: DocsLabels;
+    /** Options of the Nextra sidebar (the `sidebar` prop of its `Layout`), for example `{ defaultMenuCollapseLevel: 1 }`. */
+    sidebar?: ComponentProps<typeof Layout>['sidebar'];
+    /** The page and anything rendered next to it. */
+    children: ReactNode;
+}
+/**
+ * The Nextra `Layout` of a TUWA documentation site in a given language: the docs-ui {@link Navbar} with the language
+ * switch after the links (the theme switch stays in the Nextra sidebar and the mobile menu), the {@link Footer}, the
+ * search, the table of contents, the edit, feedback and last-updated texts and the theme switch options from
+ * `labels`. It keeps no state: {@link DocsLayout} renders it with the language of its provider, and the docs hub with
+ * its own dictionaries, so every site words and wires its chrome the same way.
+ *
+ * @param props - See {@link NextraDocsLayoutProps}.
+ * @returns The layout.
+ */
+declare function NextraDocsLayout({ logo, links, footerLinks, pageMap, docsRepositoryBase, locale, onLocaleChange, labels, sidebar, children, }: NextraDocsLayoutProps): react.JSX.Element;
+/**
+ * The layout of a TUWA project documentation site in three languages (English, Ukrainian, Simplified Chinese):
+ * {@link NextraDocsLayout} (the Nextra `Layout` with the docs-ui {@link Navbar}, the language switch after the links,
+ * the theme switch in the Nextra sidebar and the mobile menu, the {@link Footer}, the search, the table of contents,
+ * the edit, feedback and last-updated texts) and the sidebar titles in the language of the reader. Render it in the
+ * `<body>` of the root layout, around the page; pages rendered with `createDocsPage` (`@tuwaio/docs-ui/nextra/page`)
+ * switch to their translation.
  *
  * The URL never changes with the language. The server renders English; after mount the language is read from
  * `tuwa-locale` in Local Storage, then the browser languages and the time zone (no cookie, no request), and a pick in
@@ -46,5 +89,5 @@ interface DocsLayoutProps {
  */
 declare function DocsLayout({ initialLocale, ...props }: DocsLayoutProps): react.JSX.Element;
 
-export { DocsLayout };
-export type { DocsLayoutProps };
+export { DocsLayout, NextraDocsLayout };
+export type { DocsLayoutProps, NextraDocsLayoutProps };

package/dist/components/DocsLayout.d.ts

@@ -1,8 +1,11 @@
 import * as react from 'react';
-import { ReactNode } from 'react';
+import { ReactNode, ComponentProps } from 'react';
 import { PageMapItem } from 'nextra';
+import { Layout } from 'nextra-theme-docs';
+import { DocsLabels } from '../docsLabels.js';
 import { TuwaLocale } from '../locale.js';
 import { SocialLink } from './NavBar.js';
+import '../policies.js';
 
 /**
  * Props of {@link DocsLayout}.
@@ -29,12 +32,52 @@ interface DocsLayoutProps {
     children: ReactNode;
 }
 /**
- * The layout of a TUWA project documentation site in three languages (English, Ukrainian, Simplified Chinese): the
- * Nextra `Layout` with the docs-ui {@link Navbar} (the language switch after the links; the theme switch stays in the
- * Nextra sidebar and the mobile menu), the {@link Footer}, the search, the table of contents, the edit, feedback and
- * last-updated texts and the sidebar titles in the language of the reader. Render it in the `<body>` of the root
- * layout, around the page; pages rendered with `createDocsPage` (`@tuwaio/docs-ui/nextra/page`) switch to their
- * translation.
+ * Props of {@link NextraDocsLayout}.
+ */
+interface NextraDocsLayoutProps {
+    /** Logo of the site, for example `SiteLogo`; rendered in the navbar and the footer. */
+    logo: ReactNode;
+    /** External links of the navbar (default: `baseNavLinks`). */
+    links?: SocialLink[];
+    /** External links of the footer (default: `baseFooterLinks`). */
+    footerLinks?: SocialLink[];
+    /** The page map, already in the language of the reader (`localizePageMap`); passed to Nextra as it is. */
+    pageMap: PageMapItem[];
+    /** URL of the docs app in the repository, for the edit links. */
+    docsRepositoryBase: string;
+    /** The language of the reader, shown in the language switch and used for the dates and the policy links. */
+    locale: TuwaLocale;
+    /**
+     * Called with the language the reader picks in the switch.
+     *
+     * @param locale - The picked language.
+     */
+    onLocaleChange: (locale: TuwaLocale) => void;
+    /** The interface texts of that language, `docsLabels[locale]`. */
+    labels: DocsLabels;
+    /** Options of the Nextra sidebar (the `sidebar` prop of its `Layout`), for example `{ defaultMenuCollapseLevel: 1 }`. */
+    sidebar?: ComponentProps<typeof Layout>['sidebar'];
+    /** The page and anything rendered next to it. */
+    children: ReactNode;
+}
+/**
+ * The Nextra `Layout` of a TUWA documentation site in a given language: the docs-ui {@link Navbar} with the language
+ * switch after the links (the theme switch stays in the Nextra sidebar and the mobile menu), the {@link Footer}, the
+ * search, the table of contents, the edit, feedback and last-updated texts and the theme switch options from
+ * `labels`. It keeps no state: {@link DocsLayout} renders it with the language of its provider, and the docs hub with
+ * its own dictionaries, so every site words and wires its chrome the same way.
+ *
+ * @param props - See {@link NextraDocsLayoutProps}.
+ * @returns The layout.
+ */
+declare function NextraDocsLayout({ logo, links, footerLinks, pageMap, docsRepositoryBase, locale, onLocaleChange, labels, sidebar, children, }: NextraDocsLayoutProps): react.JSX.Element;
+/**
+ * The layout of a TUWA project documentation site in three languages (English, Ukrainian, Simplified Chinese):
+ * {@link NextraDocsLayout} (the Nextra `Layout` with the docs-ui {@link Navbar}, the language switch after the links,
+ * the theme switch in the Nextra sidebar and the mobile menu, the {@link Footer}, the search, the table of contents,
+ * the edit, feedback and last-updated texts) and the sidebar titles in the language of the reader. Render it in the
+ * `<body>` of the root layout, around the page; pages rendered with `createDocsPage` (`@tuwaio/docs-ui/nextra/page`)
+ * switch to their translation.
  *
  * The URL never changes with the language. The server renders English; after mount the language is read from
  * `tuwa-locale` in Local Storage, then the browser languages and the time zone (no cookie, no request), and a pick in
@@ -46,5 +89,5 @@ interface DocsLayoutProps {
  */
 declare function DocsLayout({ initialLocale, ...props }: DocsLayoutProps): react.JSX.Element;
 
-export { DocsLayout };
-export type { DocsLayoutProps };
+export { DocsLayout, NextraDocsLayout };
+export type { DocsLayoutProps, NextraDocsLayoutProps };

package/dist/components/DocsLayout.js

@@ -4,55 +4,77 @@ import { Search } from "nextra/components";
 import { LastUpdated, Layout } from "nextra-theme-docs";
 import { useMemo } from "react";
 import { DocsI18nProvider, useDocsI18n } from "../docsI18n";
-import { policyLanguageOf } from "../locale";
+import { normalizeLocale, policyLanguageOf } from "../locale";
 import { localizePageMap } from "../pageMap";
 import { Footer } from "./Footer";
 import { LocaleSwitcher } from "./LocaleSwitcher";
 import { Navbar } from "./NavBar";
-function LocalizedLayout({
+function NextraDocsLayout({
   logo,
   links,
   footerLinks,
   pageMap,
   docsRepositoryBase,
-  sidebarTitles,
+  locale,
+  onLocaleChange,
+  labels,
+  sidebar,
   children
 }) {
-  const { locale, setLocale, t } = useDocsI18n();
-  const siteTitles = locale === "en" ? void 0 : sidebarTitles?.[locale];
-  const localizedPageMap = useMemo(
-    () => localizePageMap(pageMap, { ...t.sidebar, ...siteTitles }),
-    [pageMap, t.sidebar, siteTitles]
-  );
   return /* @__PURE__ */ jsx(
     Layout,
     {
-      navbar: /* @__PURE__ */ jsx(Navbar, { logo, links, children: /* @__PURE__ */ jsx(LocaleSwitcher, { locale, onSelect: setLocale, ariaLabel: t.selectLanguage }) }),
-      footer: /* @__PURE__ */ jsx(Footer, { logo, links: footerLinks, labels: t.footer, policyLanguage: policyLanguageOf(locale) }),
-      pageMap: localizedPageMap,
+      navbar: /* @__PURE__ */ jsx(Navbar, { logo, links, children: /* @__PURE__ */ jsx(
+        LocaleSwitcher,
+        {
+          locale,
+          onSelect: (code) => {
+            const picked = normalizeLocale(code);
+            if (picked) onLocaleChange(picked);
+          },
+          ariaLabel: labels.selectLanguage
+        }
+      ) }),
+      footer: /* @__PURE__ */ jsx(Footer, { logo, links: footerLinks, labels: labels.footer, policyLanguage: policyLanguageOf(locale) }),
+      pageMap,
       docsRepositoryBase,
       navigation: { prev: true, next: true },
-      editLink: t.nextra.editThisPage,
-      feedback: { content: t.nextra.feedback },
-      lastUpdated: /* @__PURE__ */ jsx(LastUpdated, { locale, children: t.nextra.lastUpdated }),
-      toc: { title: t.nextra.onThisPage, backToTop: t.nextra.scrollToTop },
-      themeSwitch: { light: t.nextra.themeLight, dark: t.nextra.themeDark, system: t.nextra.themeSystem },
+      ...sidebar && { sidebar },
+      editLink: labels.nextra.editThisPage,
+      feedback: { content: labels.nextra.feedback },
+      lastUpdated: /* @__PURE__ */ jsx(LastUpdated, { locale, children: labels.nextra.lastUpdated }),
+      toc: { title: labels.nextra.onThisPage, backToTop: labels.nextra.scrollToTop },
+      themeSwitch: {
+        light: labels.nextra.themeLight,
+        dark: labels.nextra.themeDark,
+        system: labels.nextra.themeSystem
+      },
       search: /* @__PURE__ */ jsx(
         Search,
         {
-          placeholder: t.nextra.searchPlaceholder,
-          emptyResult: t.nextra.searchEmpty,
-          errorText: t.nextra.searchError,
-          loading: t.nextra.searchLoading
+          placeholder: labels.nextra.searchPlaceholder,
+          emptyResult: labels.nextra.searchEmpty,
+          errorText: labels.nextra.searchError,
+          loading: labels.nextra.searchLoading
         }
       ),
       children
     }
   );
 }
+function LocalizedLayout({ pageMap, sidebarTitles, ...props }) {
+  const { locale, setLocale, t } = useDocsI18n();
+  const siteTitles = locale === "en" ? void 0 : sidebarTitles?.[locale];
+  const localizedPageMap = useMemo(
+    () => localizePageMap(pageMap, { ...t.sidebar, ...siteTitles }),
+    [pageMap, t.sidebar, siteTitles]
+  );
+  return /* @__PURE__ */ jsx(NextraDocsLayout, { ...props, pageMap: localizedPageMap, locale, onLocaleChange: setLocale, labels: t });
+}
 function DocsLayout({ initialLocale, ...props }) {
   return /* @__PURE__ */ jsx(DocsI18nProvider, { initialLocale, children: /* @__PURE__ */ jsx(LocalizedLayout, { ...props }) });
 }
 export {
-  DocsLayout
+  DocsLayout,
+  NextraDocsLayout
 };

package/dist/components/Footer.cjs

@@ -82,12 +82,7 @@ function Footer({ links, logo, labels, policyLanguage = "en" }) {
           }
         )
       ] }),
-      /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { className: "tuwadocs:flex tuwadocs:flex-wrap tuwadocs:items-center tuwadocs:justify-center tuwadocs:gap-3 tuwadocs:mt-4 tuwadocs:pt-4 tuwa-footer-border", children: /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { className: "tuwa-footer-copyright", children: [
-        "\xA9 2025 - ",
-        (/* @__PURE__ */ new Date()).getFullYear(),
-        " TUWA. ",
-        labels?.copyright ?? "All rights reserved."
-      ] }) })
+      /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { className: "tuwadocs:flex tuwadocs:flex-wrap tuwadocs:items-center tuwadocs:justify-center tuwadocs:gap-3 tuwadocs:mt-4 tuwadocs:pt-4 tuwa-footer-border", children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { className: "tuwa-footer-copyright", suppressHydrationWarning: true, children: `\xA9 2025 - ${(/* @__PURE__ */ new Date()).getFullYear()} TUWA. ${labels?.copyright ?? "All rights reserved."}` }) })
     ] })
   ] }) });
 }

package/dist/components/Footer.d.cts

@@ -31,8 +31,9 @@ interface FooterProps extends NavProps {
 /**
  * The footer of a TUWA documentation site: the `Footer` of `nextra-theme-docs` with the logo, external links, the
  * TUWA description and the license on the left, links to the policies in force on tuwa.io (`footerPolicies`) and to
- * the list of all policies on the docs hub on the right, and the copyright line (the current year is read on render)
- * centered below; on narrow screens everything is centered. Render it in the `footer` prop of the Nextra `Layout`.
+ * the list of all policies on the docs hub on the right, and the copyright line (the current year is read on render;
+ * while a prerendered page hydrates, the year of its HTML stays without a hydration error) centered below; on narrow
+ * screens everything is centered. Render it in the `footer` prop of the Nextra `Layout`.
  *
  * @param props - See {@link FooterProps}.
  * @returns The footer.

package/dist/components/Footer.d.ts

@@ -31,8 +31,9 @@ interface FooterProps extends NavProps {
 /**
  * The footer of a TUWA documentation site: the `Footer` of `nextra-theme-docs` with the logo, external links, the
  * TUWA description and the license on the left, links to the policies in force on tuwa.io (`footerPolicies`) and to
- * the list of all policies on the docs hub on the right, and the copyright line (the current year is read on render)
- * centered below; on narrow screens everything is centered. Render it in the `footer` prop of the Nextra `Layout`.
+ * the list of all policies on the docs hub on the right, and the copyright line (the current year is read on render;
+ * while a prerendered page hydrates, the year of its HTML stays without a hydration error) centered below; on narrow
+ * screens everything is centered. Render it in the `footer` prop of the Nextra `Layout`.
  *
  * @param props - See {@link FooterProps}.
  * @returns The footer.

package/dist/components/Footer.js

@@ -63,12 +63,7 @@ function Footer({ links, logo, labels, policyLanguage = "en" }) {
           }
         )
       ] }),
-      /* @__PURE__ */ jsx("div", { className: "tuwadocs:flex tuwadocs:flex-wrap tuwadocs:items-center tuwadocs:justify-center tuwadocs:gap-3 tuwadocs:mt-4 tuwadocs:pt-4 tuwa-footer-border", children: /* @__PURE__ */ jsxs("div", { className: "tuwa-footer-copyright", children: [
-        "\xA9 2025 - ",
-        (/* @__PURE__ */ new Date()).getFullYear(),
-        " TUWA. ",
-        labels?.copyright ?? "All rights reserved."
-      ] }) })
+      /* @__PURE__ */ jsx("div", { className: "tuwadocs:flex tuwadocs:flex-wrap tuwadocs:items-center tuwadocs:justify-center tuwadocs:gap-3 tuwadocs:mt-4 tuwadocs:pt-4 tuwa-footer-border", children: /* @__PURE__ */ jsx("div", { className: "tuwa-footer-copyright", suppressHydrationWarning: true, children: `\xA9 2025 - ${(/* @__PURE__ */ new Date()).getFullYear()} TUWA. ${labels?.copyright ?? "All rights reserved."}` }) })
     ] })
   ] }) });
 }

package/dist/index.d.cts

@@ -10,7 +10,7 @@ export { ThemeSwitcher, ThemeSwitcherProps } from './components/ThemeSwitcher.cj
 export { DocsLabels, docsLabels } from './docsLabels.cjs';
 export { I18nContextValue, I18nKit, I18nProviderProps, LocaleState, LocaleStateOptions, LocaleVariant, createI18n, useLocaleState } from './i18n.cjs';
 export { DEFAULT_LOCALE, LOCALE_STORAGE_KEY, LocaleSignals, TUWA_LOCALES, TuwaLocale, detectLocale, formatLabel, normalizeLocale, policyLanguageOf, resolveClientLocale } from './locale.cjs';
-export { localizePageMap } from './pageMap.cjs';
+export { LocalizePageMapOptions, localizePageMap } from './pageMap.cjs';
 export { POLICIES_INDEX_URL, POLICY_DOCUMENT_LABELS, POLICY_LANGUAGES, POLICY_LANGUAGE_NAMES, POLICY_SITE_URL, POLICY_SOURCE, Policy, PolicyContent, PolicyDocumentLabels, PolicyLanguage, PolicySection, PolicySlug, footerPolicies, formatPolicyDate, getPolicyFileUrl, getPolicyPageUrl, loadPolicy, policies, policyLanguageFrom, publishedPolicies } from './policies.cjs';
 export { PREFERENCE_DAYS, PreferenceExpiry, expireStoredPreferences } from './preferences.cjs';
 export { baseFooterLinks, baseNavLinks } from './utils.cjs';

package/dist/index.d.ts

@@ -10,7 +10,7 @@ export { ThemeSwitcher, ThemeSwitcherProps } from './components/ThemeSwitcher.js
 export { DocsLabels, docsLabels } from './docsLabels.js';
 export { I18nContextValue, I18nKit, I18nProviderProps, LocaleState, LocaleStateOptions, LocaleVariant, createI18n, useLocaleState } from './i18n.js';
 export { DEFAULT_LOCALE, LOCALE_STORAGE_KEY, LocaleSignals, TUWA_LOCALES, TuwaLocale, detectLocale, formatLabel, normalizeLocale, policyLanguageOf, resolveClientLocale } from './locale.js';
-export { localizePageMap } from './pageMap.js';
+export { LocalizePageMapOptions, localizePageMap } from './pageMap.js';
 export { POLICIES_INDEX_URL, POLICY_DOCUMENT_LABELS, POLICY_LANGUAGES, POLICY_LANGUAGE_NAMES, POLICY_SITE_URL, POLICY_SOURCE, Policy, PolicyContent, PolicyDocumentLabels, PolicyLanguage, PolicySection, PolicySlug, footerPolicies, formatPolicyDate, getPolicyFileUrl, getPolicyPageUrl, loadPolicy, policies, policyLanguageFrom, publishedPolicies } from './policies.js';
 export { PREFERENCE_DAYS, PreferenceExpiry, expireStoredPreferences } from './preferences.js';
 export { baseFooterLinks, baseNavLinks } from './utils.js';

package/dist/nextra.d.cts

@@ -1,10 +1,11 @@
-export { DocsLayout, DocsLayoutProps } from './components/DocsLayout.cjs';
+export { DocsLayout, DocsLayoutProps, NextraDocsLayout, NextraDocsLayoutProps } from './components/DocsLayout.cjs';
 export { LocalizedPage, LocalizedPageProps, LocalizedPageVariant } from './components/LocalizedPage.cjs';
 export { DocsI18nProvider, useDocsI18n } from './docsI18n.cjs';
 import 'react';
 import 'nextra';
-import './locale.cjs';
-import './components/NavBar.cjs';
+import 'nextra-theme-docs';
 import './docsLabels.cjs';
+import './locale.cjs';
 import './policies.cjs';
+import './components/NavBar.cjs';
 import './i18n.cjs';

package/dist/nextra.d.ts

@@ -1,10 +1,11 @@
-export { DocsLayout, DocsLayoutProps } from './components/DocsLayout.js';
+export { DocsLayout, DocsLayoutProps, NextraDocsLayout, NextraDocsLayoutProps } from './components/DocsLayout.js';
 export { LocalizedPage, LocalizedPageProps, LocalizedPageVariant } from './components/LocalizedPage.js';
 export { DocsI18nProvider, useDocsI18n } from './docsI18n.js';
 import 'react';
 import 'nextra';
-import './locale.js';
-import './components/NavBar.js';
+import 'nextra-theme-docs';
 import './docsLabels.js';
+import './locale.js';
 import './policies.js';
+import './components/NavBar.js';
 import './i18n.js';

package/dist/pageMap.cjs

@@ -21,34 +21,45 @@ __export(pageMap_exports, {
   localizePageMap: () => localizePageMap
 });
 module.exports = __toCommonJS(pageMap_exports);
-function localizeMetaValue(value, titles) {
-  if (typeof value === "string") return titles[value] ?? value;
-  if (value && typeof value === "object" && typeof value.title === "string") {
-    const translated = titles[value.title];
-    return translated ? { ...value, title: translated } : value;
-  }
-  return value;
+function localizeMetaValue(value, routeTitle, titles) {
+  if (typeof value === "string") return routeTitle ?? titles[value] ?? value;
+  if (!value || typeof value !== "object" || !("title" in value)) return value;
+  const title = value.title;
+  const translated = routeTitle ?? (typeof title === "string" ? titles[title] : void 0);
+  return translated ? { ...value, title: translated } : value;
 }
-function localizePageMap(pageMap, titles) {
-  if (Object.keys(titles).length === 0) return pageMap;
-  return pageMap.map((item) => {
+function localizeItems(items, titles, routes, parent) {
+  const routeTitle = (name) => routes[parent ? `${parent}/${name}` : name] ?? routes[name];
+  return items.map((item) => {
     if ("data" in item) {
       const data = Object.fromEntries(
-        Object.entries(item.data).map(([key, value]) => [key, localizeMetaValue(value, titles)])
+        Object.entries(item.data).map(([key, value]) => [key, localizeMetaValue(value, routeTitle(key), titles)])
       );
       return { ...item, data };
     }
     const copy = { ...item };
+    const name = item.name;
+    const route = typeof name === "string" ? parent ? `${parent}/${name}` : name : parent;
+    const byRoute = typeof name === "string" ? routeTitle(name) : void 0;
     const title = item.title;
-    if (typeof title === "string" && titles[title]) copy.title = titles[title];
-    if ("frontMatter" in item && item.frontMatter && typeof item.frontMatter.title === "string") {
-      const title2 = titles[item.frontMatter.title];
-      if (title2) copy.frontMatter = { ...item.frontMatter, title: title2 };
+    if (byRoute) copy.title = byRoute;
+    else if (typeof title === "string" && titles[title]) copy.title = titles[title];
+    if ("frontMatter" in item && item.frontMatter) {
+      const frontTitle = item.frontMatter.title;
+      const translated = byRoute ?? (typeof frontTitle === "string" ? titles[frontTitle] : void 0);
+      if (translated) copy.frontMatter = { ...item.frontMatter, title: translated };
+    }
+    if ("children" in item && Array.isArray(item.children)) {
+      copy.children = localizeItems(item.children, titles, routes, route);
     }
-    if ("children" in item && Array.isArray(item.children)) copy.children = localizePageMap(item.children, titles);
     return copy;
   });
 }
+function localizePageMap(pageMap, titles, options = {}) {
+  const routes = options.routes ?? {};
+  if (Object.keys(titles).length === 0 && Object.keys(routes).length === 0) return pageMap;
+  return localizeItems(pageMap, titles, routes);
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   localizePageMap

package/dist/pageMap.d.cts

@@ -1,20 +1,33 @@
 import { PageMapItem } from 'nextra';
 
+/** Options of {@link localizePageMap}. */
+interface LocalizePageMapOptions {
+    /**
+     * Translated titles by route instead of English title: `<folder>/<name>` (for example `guides/full-stack-react`),
+     * then the bare `<name>` (`guides`, `index`). A route title wins over an English title and also replaces the front
+     * matter `title`. The docs hub keys its sidebar this way.
+     */
+    routes?: Readonly<Record<string, string>>;
+}
 /**
  * Translates the titles of a Nextra page map: the sidebar, the top-level menu, the breadcrumbs and the previous / next
- * links all read them. Titles are matched by their English text (the `_meta` titles, the `title` of each item and the
- * front matter `title`), so a site lists each English title once, whatever the page; titles without a translation,
- * such as package names, stay as they are. The page map is not modified: changed items are copied.
+ * links all read them. The project sites match titles by their English text (the `_meta` titles, the `title` of each
+ * item and the front matter `title`), so a site lists each English title once, whatever the page; titles without a
+ * translation, such as package names, stay as they are. The docs hub matches them by route instead
+ * (`options.routes`). The page map is not modified: changed items are copied.
  *
  * @example
  * ```ts
  * localizePageMap(pageMap, { Introduction: 'Вступ', Packages: 'Пакети' });
+ * localizePageMap(pageMap, {}, { routes: { guides: 'Посібники', 'guides/starter-templates': 'Стартові шаблони' } });
  * ```
  *
  * @param pageMap - The page map of the site, the result of `getPageMap()` of `nextra/page-map`.
  * @param titles - Translated titles by English title.
- * @returns The page map with translated titles.
+ * @param options - See {@link LocalizePageMapOptions}.
+ * @returns The page map with translated titles, or `pageMap` itself when there is nothing to translate.
  */
-declare function localizePageMap(pageMap: PageMapItem[], titles: Readonly<Record<string, string>>): PageMapItem[];
+declare function localizePageMap(pageMap: PageMapItem[], titles: Readonly<Record<string, string>>, options?: LocalizePageMapOptions): PageMapItem[];
 
 export { localizePageMap };
+export type { LocalizePageMapOptions };

package/dist/pageMap.d.ts

@@ -1,20 +1,33 @@
 import { PageMapItem } from 'nextra';
 
+/** Options of {@link localizePageMap}. */
+interface LocalizePageMapOptions {
+    /**
+     * Translated titles by route instead of English title: `<folder>/<name>` (for example `guides/full-stack-react`),
+     * then the bare `<name>` (`guides`, `index`). A route title wins over an English title and also replaces the front
+     * matter `title`. The docs hub keys its sidebar this way.
+     */
+    routes?: Readonly<Record<string, string>>;
+}
 /**
  * Translates the titles of a Nextra page map: the sidebar, the top-level menu, the breadcrumbs and the previous / next
- * links all read them. Titles are matched by their English text (the `_meta` titles, the `title` of each item and the
- * front matter `title`), so a site lists each English title once, whatever the page; titles without a translation,
- * such as package names, stay as they are. The page map is not modified: changed items are copied.
+ * links all read them. The project sites match titles by their English text (the `_meta` titles, the `title` of each
+ * item and the front matter `title`), so a site lists each English title once, whatever the page; titles without a
+ * translation, such as package names, stay as they are. The docs hub matches them by route instead
+ * (`options.routes`). The page map is not modified: changed items are copied.
  *
  * @example
  * ```ts
  * localizePageMap(pageMap, { Introduction: 'Вступ', Packages: 'Пакети' });
+ * localizePageMap(pageMap, {}, { routes: { guides: 'Посібники', 'guides/starter-templates': 'Стартові шаблони' } });
  * ```
  *
  * @param pageMap - The page map of the site, the result of `getPageMap()` of `nextra/page-map`.
  * @param titles - Translated titles by English title.
- * @returns The page map with translated titles.
+ * @param options - See {@link LocalizePageMapOptions}.
+ * @returns The page map with translated titles, or `pageMap` itself when there is nothing to translate.
  */
-declare function localizePageMap(pageMap: PageMapItem[], titles: Readonly<Record<string, string>>): PageMapItem[];
+declare function localizePageMap(pageMap: PageMapItem[], titles: Readonly<Record<string, string>>, options?: LocalizePageMapOptions): PageMapItem[];
 
 export { localizePageMap };
+export type { LocalizePageMapOptions };

package/dist/pageMap.js

@@ -1,31 +1,42 @@
-function localizeMetaValue(value, titles) {
-  if (typeof value === "string") return titles[value] ?? value;
-  if (value && typeof value === "object" && typeof value.title === "string") {
-    const translated = titles[value.title];
-    return translated ? { ...value, title: translated } : value;
-  }
-  return value;
+function localizeMetaValue(value, routeTitle, titles) {
+  if (typeof value === "string") return routeTitle ?? titles[value] ?? value;
+  if (!value || typeof value !== "object" || !("title" in value)) return value;
+  const title = value.title;
+  const translated = routeTitle ?? (typeof title === "string" ? titles[title] : void 0);
+  return translated ? { ...value, title: translated } : value;
 }
-function localizePageMap(pageMap, titles) {
-  if (Object.keys(titles).length === 0) return pageMap;
-  return pageMap.map((item) => {
+function localizeItems(items, titles, routes, parent) {
+  const routeTitle = (name) => routes[parent ? `${parent}/${name}` : name] ?? routes[name];
+  return items.map((item) => {
     if ("data" in item) {
       const data = Object.fromEntries(
-        Object.entries(item.data).map(([key, value]) => [key, localizeMetaValue(value, titles)])
+        Object.entries(item.data).map(([key, value]) => [key, localizeMetaValue(value, routeTitle(key), titles)])
       );
       return { ...item, data };
     }
     const copy = { ...item };
+    const name = item.name;
+    const route = typeof name === "string" ? parent ? `${parent}/${name}` : name : parent;
+    const byRoute = typeof name === "string" ? routeTitle(name) : void 0;
     const title = item.title;
-    if (typeof title === "string" && titles[title]) copy.title = titles[title];
-    if ("frontMatter" in item && item.frontMatter && typeof item.frontMatter.title === "string") {
-      const title2 = titles[item.frontMatter.title];
-      if (title2) copy.frontMatter = { ...item.frontMatter, title: title2 };
+    if (byRoute) copy.title = byRoute;
+    else if (typeof title === "string" && titles[title]) copy.title = titles[title];
+    if ("frontMatter" in item && item.frontMatter) {
+      const frontTitle = item.frontMatter.title;
+      const translated = byRoute ?? (typeof frontTitle === "string" ? titles[frontTitle] : void 0);
+      if (translated) copy.frontMatter = { ...item.frontMatter, title: translated };
+    }
+    if ("children" in item && Array.isArray(item.children)) {
+      copy.children = localizeItems(item.children, titles, routes, route);
     }
-    if ("children" in item && Array.isArray(item.children)) copy.children = localizePageMap(item.children, titles);
     return copy;
   });
 }
+function localizePageMap(pageMap, titles, options = {}) {
+  const routes = options.routes ?? {};
+  if (Object.keys(titles).length === 0 && Object.keys(routes).length === 0) return pageMap;
+  return localizeItems(pageMap, titles, routes);
+}
 export {
   localizePageMap
 };

package/dist/translationCheck.cjs

@@ -149,6 +149,11 @@ async function checkSiteTranslations(options = {}) {
     throw new Error(`No ${contentDir} in ${cwd}: run the check from the docs app of the site`);
   }
   const createSlugger = options.createSlugger ?? await loadNextraSlugger(cwd);
+  if (!createSlugger) {
+    throw new Error(
+      `Cannot load github-slugger through nextra from ${cwd}: the heading ids of the translations cannot be checked`
+    );
+  }
   const locales = import_locale.TUWA_LOCALES.filter((locale) => locale !== import_locale.DEFAULT_LOCALE);
   const filesByLocale = new Map(locales.map((locale) => [locale, pageFiles((0, import_node_path.join)(cwd, i18nDir, locale))]));
   const pages = [...new Set([...filesByLocale.values()].flat().map(withoutExtension))].sort();

package/dist/translationCheck.d.cts

@@ -68,7 +68,7 @@ interface CheckSiteTranslationsOptions {
     contentDir?: string;
     /** The translations, one folder per language, relative to `cwd` (default: `src/i18n`). */
     i18nDir?: string;
-    /** The heading slugger (default: {@link loadNextraSlugger}). */
+    /** The heading slugger (default: {@link loadNextraSlugger}; the check fails when it cannot be loaded). */
     createSlugger?: HeadingSlugger;
 }
 /**
@@ -78,7 +78,8 @@ interface CheckSiteTranslationsOptions {
  *
  * @param options - See {@link CheckSiteTranslationsOptions}.
  * @returns The number of translated files and the issues found.
- * @throws When `contentDir` does not exist (the check runs from the wrong directory).
+ * @throws When `contentDir` does not exist (the check runs from the wrong directory), or when no `createSlugger` is
+ *   given and the slugger of Nextra cannot be loaded from `cwd` (the heading ids would go unchecked).
  */
 declare function checkSiteTranslations(options?: CheckSiteTranslationsOptions): Promise<{
     files: number;

package/dist/translationCheck.d.ts

@@ -68,7 +68,7 @@ interface CheckSiteTranslationsOptions {
     contentDir?: string;
     /** The translations, one folder per language, relative to `cwd` (default: `src/i18n`). */
     i18nDir?: string;
-    /** The heading slugger (default: {@link loadNextraSlugger}). */
+    /** The heading slugger (default: {@link loadNextraSlugger}; the check fails when it cannot be loaded). */
     createSlugger?: HeadingSlugger;
 }
 /**
@@ -78,7 +78,8 @@ interface CheckSiteTranslationsOptions {
  *
  * @param options - See {@link CheckSiteTranslationsOptions}.
  * @returns The number of translated files and the issues found.
- * @throws When `contentDir` does not exist (the check runs from the wrong directory).
+ * @throws When `contentDir` does not exist (the check runs from the wrong directory), or when no `createSlugger` is
+ *   given and the slugger of Nextra cannot be loaded from `cwd` (the heading ids would go unchecked).
  */
 declare function checkSiteTranslations(options?: CheckSiteTranslationsOptions): Promise<{
     files: number;

package/dist/translationCheck.js

@@ -121,6 +121,11 @@ async function checkSiteTranslations(options = {}) {
     throw new Error(`No ${contentDir} in ${cwd}: run the check from the docs app of the site`);
   }
   const createSlugger = options.createSlugger ?? await loadNextraSlugger(cwd);
+  if (!createSlugger) {
+    throw new Error(
+      `Cannot load github-slugger through nextra from ${cwd}: the heading ids of the translations cannot be checked`
+    );
+  }
   const locales = TUWA_LOCALES.filter((locale) => locale !== DEFAULT_LOCALE);
   const filesByLocale = new Map(locales.map((locale) => [locale, pageFiles(join(cwd, i18nDir, locale))]));
   const pages = [...new Set([...filesByLocale.values()].flat().map(withoutExtension))].sort();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tuwaio/docs-ui",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "private": false,
   "author": "Oleksandr Tkach",
   "license": "Apache-2.0",