@next-library/theme 1.0.3 → 1.0.5

package/README.md

@@ -2,7 +2,9 @@
 
 Complete UI theme package for Next.js documentation framework. This package provides ready-made React components built on top of [`@next-library/core`](../core/README.md).
 
-> **Looking for core utilities only?** Check out [`@next-library/core`](../core/README.md) which provides content management, i18n, and SEO utilities without UI components.
+> **Looking for core utilities only?** See [`@next-library/core`](../core/README.md).
+
+> **Content tree:** Layout and nav expect the same **`PageData`** from **`extractPageData(contentTree, locale, slug)`**. Import **`contentTree`** from your generated **`lib/tree.ts`** and pass **`contentTree`** into **`NavigationBar`** (and derive **`getSupportedLocales(contentTree)`** for **`LanguageSwitcher`**). The canonical wiring is **[`example/app/`](../../example/app/)** and **[`docs/getting-started.md`](../../docs/getting-started.md)**.
 
 ## Features
 
@@ -35,6 +37,12 @@ yarn add @next-library/theme @next-library/core
 pnpm add next-themes @tailwindcss/typography
 ```
 
+### Module format (ESM vs `@next-library/core`)
+
+`@next-library/theme` is published as **ESM-only** (`import` / `export` in `package.json` `exports`). Use it from **Next.js App Router** (or any bundler that resolves ESM) as in this repo’s [example app](../../example).
+
+[`@next-library/core`](../core/README.md) ships **both ESM and CommonJS** (`import` and `require` via `exports`), which helps generic Node tooling and older setups. You do **not** need CJS to use the theme with Next.js; if you rely on `require('@next-library/theme')` in plain Node without a bundler, prefer importing `@next-library/core` for config/tree utilities and keep UI imports inside the Next.js bundle.
+
 ## Quick Start
 
 ### 1. Set Up Tailwind CSS v4
@@ -115,10 +123,18 @@ Import server components from `@next-library/theme/server`:
 ```typescript
 // app/[locale]/layout.tsx
 import { DocumentationLayout } from '@next-library/theme/server';
+import { isValidLocale, type Locale } from '@next-library/core';
+
+export default async function LocaleLayout({
+  children,
+  params,
+}: {
+  children: React.ReactNode;
+  params: Promise<{ locale: string }>;
+}) {
+  const { locale: raw } = await params;
+  const locale = (isValidLocale(raw) ? raw : 'en') as Locale;
 
-export default function LocaleLayout({ children, params }) {
-  const { locale } = await params;
-  
   return (
     <DocumentationLayout language={locale}>
       {children}
@@ -131,22 +147,38 @@ export default function LocaleLayout({ children, params }) {
 
 Import client components from `@next-library/theme/client`:
 
+Server parent (derive locales from the generated tree):
+
+```typescript
+import { getSupportedLocales } from '@next-library/core';
+import contentTree from '@/lib/tree';
+import { LocaleTools } from './locale-tools';
+
+const availableLocales = getSupportedLocales(contentTree);
+// …
+<LocaleTools availableLocales={availableLocales} />;
+```
+
+Client component:
+
 ```typescript
-// components/my-component.tsx
+// app/locale-tools.tsx
 'use client';
 
 import { LanguageSwitcher, ThemeSwitcher } from '@next-library/theme/client';
 
-export function MyComponent() {
+export function LocaleTools({ availableLocales }: { availableLocales: string[] }) {
   return (
     <div>
-      <LanguageSwitcher availableLocales={['en', 'fr', 'de']} />
+      <LanguageSwitcher availableLocales={availableLocales} />
       <ThemeSwitcher />
     </div>
   );
 }
 ```
 
+`NavigationBar` computes locales from **`contentTree`** when you pass **`contentTree`** (see complete example below).
+
 ## Component Exports
 
 ### Server Components (`@next-library/theme/server`)
@@ -204,16 +236,18 @@ export function MyComponent() {
 ```typescript
 // app/[locale]/layout.tsx
 import { DocumentationLayout } from '@next-library/theme/server';
+import { isValidLocale, type Locale } from '@next-library/core';
 
-export default async function LocaleLayout({ 
-  children, 
-  params 
-}: { 
+export default async function LocaleLayout({
+  children,
+  params,
+}: {
   children: React.ReactNode;
   params: Promise<{ locale: string }>;
 }) {
-  const { locale } = await params;
-  
+  const { locale: rawLocale } = await params;
+  const locale = (isValidLocale(rawLocale) ? rawLocale : 'en') as Locale;
+
   return (
     <DocumentationLayout language={locale}>
       {children}
@@ -228,52 +262,50 @@ export default async function LocaleLayout({
 // app/[locale]/docs/[[...slug]]/layout.tsx
 import { NavigationBar, LeftSidebar, RightSidebar } from '@next-library/theme/server';
 import { Breadcrumbs, AnchorLinkHandler } from '@next-library/theme/client';
-import { extractPageData, getSupportedLocales, type Locale } from '@next-library/core';
-
-export default async function DocsLayout({ 
-  children, 
-  params 
-}: { 
+import { extractPageData, isValidLocale, createConfig, type Locale } from '@next-library/core';
+import { libraryConfig } from '@/library.config';
+import contentTree from '@/lib/tree';
+
+export default async function DocsLayout({
+  children,
+  params,
+}: {
   children: React.ReactNode;
   params: Promise<{ locale: string; slug?: string[] }>;
 }) {
   const { locale: rawLocale, slug } = await params;
-  const supportedLocales = getSupportedLocales();
-  const locale = (supportedLocales.includes(rawLocale) ? rawLocale : 'en') as Locale;
+  const locale = (isValidLocale(rawLocale) ? rawLocale : 'en') as Locale;
   const safeSlug = Array.isArray(slug) ? slug : [];
-
-  const pageData = extractPageData(locale, safeSlug);
+  const fullConfig = createConfig(libraryConfig);
+  const pageData = extractPageData(contentTree, locale, safeSlug);
+  const repoUrl =
+    fullConfig.github?.user && fullConfig.github?.repo
+      ? `https://github.com/${fullConfig.github.user}/${fullConfig.github.repo}`
+      : undefined;
 
   return (
     <div>
-      {/* Mobile Navigation */}
       <NavigationBar
         language={locale}
         className="block lg:hidden"
         pageData={pageData}
+        websiteTitle={fullConfig.website?.title || 'Documentation'}
+        contentTree={contentTree}
+        repoUrl={repoUrl}
       />
-
-      {/* Main Content Layout */}
       <div className="flex flex-row gap-12 w-full lg:w-[95vw] mx-auto pt-10">
-        {/* Left Sidebar */}
         <LeftSidebar
           data={pageData}
           className="sticky top-28 hidden lg:flex lg:flex-[2] max-w-xs"
         />
-
-        {/* Main Content */}
         <main className="flex flex-col lg:gap-8 gap-4 flex-1 w-full lg:flex-[6] px-4 lg:px-0">
           <Breadcrumbs data={pageData} locale={locale} />
           {children}
         </main>
-
-        {/* Right Sidebar */}
         <RightSidebar
           data={pageData}
           className="sticky top-28 hidden lg:flex lg:flex-[1.5] max-w-xs"
         />
-
-        {/* Anchor Link Handler */}
         <AnchorLinkHandler locale={locale} />
       </div>
     </div>
@@ -284,73 +316,69 @@ export default async function DocsLayout({
 ### Documentation Page
 
 ```typescript
-// app/[locale]/docs/[[...slug]]/page.tsx
-import { PageHeader, MarkdownRenderer, FallbackLocaleWarning } from '@next-library/theme';
-import { extractPageData, generateArticleSchema, generateBreadcrumbSchema, generateCollectionPageSchema, getSupportedLocales, fetchRawFileContent } from '@next-library/core';
-import { StructuredData } from '@next-library/theme/server';
+// app/[locale]/docs/[[...slug]]/page.tsx (leaf page — folder views need FolderCards; see example app)
+import {
+  extractPageData,
+  isValidLocale,
+  createConfig,
+  type Locale,
+} from '@next-library/core';
+import { loadDocumentationMarkdown } from '@next-library/core/server';
+import { PageHeader, FallbackLocaleWarning } from '@next-library/theme/server';
+import { MarkdownRenderer } from '@next-library/theme/client';
+import { libraryConfig } from '@/library.config';
+import contentTree from '@/lib/tree';
 import { notFound } from 'next/navigation';
 
-export default async function DocPage({ 
-  params 
-}: { 
+export default async function DocPage({
+  params,
+}: {
   params: Promise<{ locale: string; slug?: string[] }>;
 }) {
   const { locale: rawLocale, slug } = await params;
-  const supportedLocales = getSupportedLocales();
-  const locale = supportedLocales.includes(rawLocale) ? rawLocale : 'en';
+  const locale = (isValidLocale(rawLocale) ? rawLocale : 'en') as Locale;
   const safeSlug = Array.isArray(slug) ? slug : [];
-
-  const pageData = extractPageData(locale, safeSlug);
+  const fullConfig = createConfig(libraryConfig);
+  const pageData = extractPageData(contentTree, locale, safeSlug);
   const { node } = pageData;
 
-  if (!node) {
+  if (!node?.githubPath || !fullConfig.github?.user || !fullConfig.github?.repo) {
     notFound();
   }
 
-  // Fetch markdown content from GitHub
-  const rawMarkdown = await fetchRawFileContent(node.githubPath!);
-
-  // Generate structured data
-  const articleSchema = generateArticleSchema({ /* ... */ });
-  const breadcrumbSchema = generateBreadcrumbSchema(pageData.navigation.breadcrumbs);
-  const collectionPageSchema = generateCollectionPageSchema({ /* ... */ });
-
-  const schemas = [articleSchema, breadcrumbSchema, collectionPageSchema]
-    .filter(Boolean)
-    .map(schema => JSON.stringify(schema, null, 0).replace(/</g, '\\u003c'))
-    .join('\n');
+  const githubConfig = {
+    user: fullConfig.github.user,
+    repo: fullConfig.github.repo,
+    branch: fullConfig.github.branch || 'main',
+    token: fullConfig.github.token,
+    app: fullConfig.github.app,
+  };
+  const rawMarkdown = await loadDocumentationMarkdown(node.githubPath, {
+    contentDir: fullConfig.tree?.contentBodiesDir,
+    github: githubConfig,
+  });
+  const baseUrl = fullConfig.website?.siteUrl || 'http://localhost:3000';
+  const pageUrl = `${baseUrl.replace(/\/$/, '')}/${locale}/docs/${safeSlug.join('/')}`;
+  const websiteTitle = fullConfig.website?.title || fullConfig.website?.organizationName || 'Documentation';
 
   return (
     <div>
-      {/* Structured Data */}
-      {schemas && (
-        <script
-          type="application/ld+json"
-          dangerouslySetInnerHTML={{ __html: schemas }}
-        />
-      )}
-
-      {/* Page Header with Copy Button */}
       <PageHeader
         title={node.title}
         markdown={rawMarkdown}
-        pageUrl={`https://example.com/${locale}/docs/${safeSlug.join('/')}`}
-        websiteTitle="My Documentation"
+        pageUrl={pageUrl}
+        websiteTitle={websiteTitle}
         locale={locale}
       />
-
-      {/* Fallback Warning */}
-      {node.fallback && (
-        <FallbackLocaleWarning locale={locale} />
-      )}
-
-      {/* Markdown Content */}
+      {node.fallback && <FallbackLocaleWarning locale={locale} />}
       <MarkdownRenderer markdown={rawMarkdown} />
     </div>
   );
 }
 ```
 
+For **JSON-LD**, **`generateMetadata`**, **folder `index` views** (`FolderCards`), and error handling, copy from **`example/app/[locale]/docs/[[...slug]]/page.tsx`** in the monorepo.
+
 ## Internationalization
 
 The theme package includes translations for 20+ languages. Components automatically use translations based on the `locale` prop:
@@ -467,10 +495,12 @@ interface DocumentationLayoutProps {
 
 ```typescript
 interface NavigationBarProps {
-  language: Locale;
+  language?: Locale;
   className?: string;
   pageData?: PageData;
   websiteTitle?: string;
+  contentTree?: ContentTree;
+  repoUrl?: string;
 }
 ```
 

package/dist/client.d.ts

@@ -41,4 +41,5 @@ export { BreadcrumbToggle } from './components/ui/breadcrumb-toggle';
 export * from './components/ui/sidebar';
 export { useMediaQuery } from './hooks/use-media-query';
 export { useIsMobile } from './hooks/use-mobile';
+export { ReadingProgress } from './components/layout/reading-progress';
 //# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AAGH,OAAO,EAAE,OAAO,IAAI,MAAM,EAAE,MAAM,uCAAuC,CAAC;AAC1E,OAAO,EAAE,IAAI,EAAE,MAAM,qCAAqC,CAAC;AAC3D,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,+CAA+C,CAAC;AACnG,OAAO,EAAE,SAAS,EAAE,MAAM,2CAA2C,CAAC;AACtE,OAAO,EAAE,aAAa,EAAE,MAAM,+CAA+C,CAAC;AAC9E,OAAO,EAAE,gBAAgB,EAAE,MAAM,kDAAkD,CAAC;AACpF,OAAO,EAAE,UAAU,EAAE,MAAM,4CAA4C,CAAC;AACxE,OAAO,EAAE,UAAU,EAAE,MAAM,4CAA4C,CAAC;AACxE,OAAO,EAAE,UAAU,EAAE,MAAM,4CAA4C,CAAC;AAGxE,OAAO,EAAE,iBAAiB,EAAE,MAAM,8CAA8C,CAAC;AACjF,OAAO,EAAE,aAAa,EAAE,MAAM,qDAAqD,CAAC;AACpF,OAAO,EAAE,eAAe,EAAE,MAAM,yDAAyD,CAAC;AAC1F,OAAO,EAAE,kBAAkB,EAAE,MAAM,2DAA2D,CAAC;AAG/F,OAAO,EAAE,WAAW,EAAE,MAAM,0CAA0C,CAAC;AACvE,OAAO,EAAE,WAAW,EAAE,MAAM,2CAA2C,CAAC;AAGxE,OAAO,EAAE,gBAAgB,EAAE,MAAM,yCAAyC,CAAC;AAC3E,OAAO,EAAE,cAAc,EAAE,MAAM,wCAAwC,CAAC;AAYxE,OAAO,EAAE,YAAY,EAAE,MAAM,qCAAqC,CAAC;AAKnE,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,wBAAwB,CAAC;AACvC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,wBAAwB,CAAC;AACvC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAC7D,OAAO,EAAE,iBAAiB,EAAE,MAAM,qCAAqC,CAAC;AACxE,cAAc,4BAA4B,CAAC;AAC3C,OAAO,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AACrE,cAAc,yBAAyB,CAAC;AAGxC,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AAGH,OAAO,EAAE,OAAO,IAAI,MAAM,EAAE,MAAM,uCAAuC,CAAC;AAC1E,OAAO,EAAE,IAAI,EAAE,MAAM,qCAAqC,CAAC;AAC3D,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,+CAA+C,CAAC;AACnG,OAAO,EAAE,SAAS,EAAE,MAAM,2CAA2C,CAAC;AACtE,OAAO,EAAE,aAAa,EAAE,MAAM,+CAA+C,CAAC;AAC9E,OAAO,EAAE,gBAAgB,EAAE,MAAM,kDAAkD,CAAC;AACpF,OAAO,EAAE,UAAU,EAAE,MAAM,4CAA4C,CAAC;AACxE,OAAO,EAAE,UAAU,EAAE,MAAM,4CAA4C,CAAC;AACxE,OAAO,EAAE,UAAU,EAAE,MAAM,4CAA4C,CAAC;AAGxE,OAAO,EAAE,iBAAiB,EAAE,MAAM,8CAA8C,CAAC;AACjF,OAAO,EAAE,aAAa,EAAE,MAAM,qDAAqD,CAAC;AACpF,OAAO,EAAE,eAAe,EAAE,MAAM,yDAAyD,CAAC;AAC1F,OAAO,EAAE,kBAAkB,EAAE,MAAM,2DAA2D,CAAC;AAG/F,OAAO,EAAE,WAAW,EAAE,MAAM,0CAA0C,CAAC;AACvE,OAAO,EAAE,WAAW,EAAE,MAAM,2CAA2C,CAAC;AAGxE,OAAO,EAAE,gBAAgB,EAAE,MAAM,yCAAyC,CAAC;AAC3E,OAAO,EAAE,cAAc,EAAE,MAAM,wCAAwC,CAAC;AAYxE,OAAO,EAAE,YAAY,EAAE,MAAM,qCAAqC,CAAC;AAKnE,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,wBAAwB,CAAC;AACvC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,wBAAwB,CAAC;AACvC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAC7D,OAAO,EAAE,iBAAiB,EAAE,MAAM,qCAAqC,CAAC;AACxE,cAAc,4BAA4B,CAAC;AAC3C,OAAO,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AACrE,cAAc,yBAAyB,CAAC;AAGxC,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAIjD,OAAO,EAAE,eAAe,EAAE,MAAM,sCAAsC,CAAC"}