@x-wave/blog 2.0.0 → 2.1.0

package/README.md

@@ -1,54 +1,236 @@
-# Staking Docs
+# @x-wave/blog
 
-Multi-language documentation site built with Next.js App Router and MDX. This repo contains both the framework packages and a reference app used for local development and previews.
+A responsive, multi-language documentation framework for React + Vite applications. Ships with TypeScript, i18n (i18next), MDX support, dark mode, and built-in navigation.
 
-## Repository structure
+## Features
 
-```
-packages/
-├── app/            # Next.js reference app
-├── blog/           # Build orchestration package
-├── ui/             # UI components and client logic
-├── locales/        # i18n resources (i18next)
-├── consts/         # Navigation config + shared constants
-├── styles/         # SCSS + compiled CSS
-└── types/          # Shared TypeScript types
-```
+- **Multi-language support**: Ship 3+ languages with a single codebase (en, es, zh included)
+- **MDX content**: Write docs in Markdown with React components
+- **Dark mode**: Built-in light/dark/system theme toggle with localStorage persistence
+- **Advanced mode**: Optional Simple/Advanced content variants for the same page
+- **Mobile responsive**: Automatic sidebar → mobile menu on small screens
+- **Headless**: No styling opinions—includes SCSS variables for full customization
+- **HMR-friendly**: Vite development with Hot Module Replacement for instant feedback
 
-## Quick start
+## Installation
 
-### 1. Install dependencies
+### npm
 
 ```bash
-pnpm install
+npm install @x-wave/blog
 ```
 
-### 2. Run the Next.js app
+### pnpm
 
 ```bash
-pnpm dev
+pnpm add @x-wave/blog
 ```
 
-The app runs from [packages/app](packages/app). The default route is `/en/welcome`.
+### yarn
+
+```bash
+yarn add @x-wave/blog
+```
 
-## Content structure
+## Quick setup
 
-MDX files live under the app package:
+### 1. Create your app structure
 
 ```
-packages/app/docs/
-├── en/
-│   ├── welcome.mdx
-│   ├── glossary.mdx
-│   └── faq.mdx
-├── es/
-└── zh/
+src/
+├── App.tsx                      # Your app component
+├── main.tsx                     # Entry point
+├── navigation.ts                # Site navigation definition
+├── utils.ts                     # Content loaders
+├── logo.svg                     # Optional: your logo
+└── docs/
+    ├── en/
+    │   ├── welcome.mdx
+    │   ├── glossary.mdx
+    │   └── faq.mdx
+    ├── es/
+    │   ├── welcome.mdx
+    │   ├── glossary.mdx
+    │   └── faq.mdx
+    └── zh/
+        ├── welcome.mdx
+        ├── glossary.mdx
+        └── faq.mdx
+```
+
+### 2. Set up i18n and styles
+
+Import the i18n setup and framework styles in your app entry point:
+
+```ts
+// src/main.tsx
+import '@x-wave/blog/locales'   // Initialises i18next with en, es, zh
+import '@x-wave/blog/styles'    // Compiled CSS with variables and component styles (required)
+import { createRoot } from 'react-dom/client'
+import App from './App'
+
+createRoot(document.getElementById('root')!).render(<App />)
 ```
 
-File names must match the `slug` in the navigation config.
+> **The styles import is required** for the UI components and layout to render correctly. This imports a single compiled CSS file (`index.css`) that contains all framework styles, CSS variables, and component styles.
+
+**Add custom translations:**
+
+```ts
+// src/main.tsx
+import '@x-wave/blog/locales'
+import i18next from 'i18next'
+
+// Add French translations
+i18next.addResourceBundle('fr', 'translation', {
+  language: 'Français',
+  'ui.simple': 'Simple',
+  'ui.advanced': 'Avancé',
+  // ... other keys
+})
+```
+
+### 3. Define your navigation
+
+```ts
+// src/navigation.ts
+import type { NavigationEntry } from '@x-wave/blog/types'
+
+export const NAVIGATION_DATA: NavigationEntry[] = [
+  {
+    title: 'docs.welcome',
+    slug: 'welcome',
+  },
+  {
+    title: 'Help',
+    defaultOpen: true,
+    items: [
+      {
+        title: 'docs.glossary',
+        slug: 'glossary',
+        showTableOfContents: true,
+      },
+      {
+        title: 'docs.faq',
+        slug: 'faq',
+      },
+    ],
+  },
+]
+```
+
+### 4. Create content loaders
+
+```ts
+// src/utils.ts
+import { createBlogUtils } from '@x-wave/blog'
+
+// Vite glob import – resolved relative to this file
+const mdxFiles = import.meta.glob('./docs/**/*.mdx', {
+  query: '?raw',
+  import: 'default',
+  eager: false,
+})
+
+// Export all blog utilities in a single object
+export const blog = createBlogUtils(mdxFiles)
+```
+
+### 5. Wrap your app with BlogProvider
+
+```tsx
+// src/App.tsx
+import { BlogProvider, DocumentationRoutes } from '@x-wave/blog'
+import { Navigate, Route, BrowserRouter as Router, Routes } from 'react-router-dom'
+import { blog } from './utils'
+import { NAVIGATION_DATA } from './navigation'
+
+const SUPPORTED_LANGUAGES = ['en', 'es', 'zh'] as const
+
+export default function App() {
+  return (
+    <BlogProvider
+      config={{
+        title: 'My Documentation',
+        supportedLanguages: SUPPORTED_LANGUAGES,
+        navigationData: NAVIGATION_DATA,
+        header: {
+          navLinks: [
+            {
+              label: 'Visit Site',
+              url: 'https://example.com',
+              target: '_blank',
+            },
+          ],
+        },
+      }}
+      blog={blog}
+    >
+      <Router>
+        <Routes>
+          <Route path="/:language/*" element={<DocumentationRoutes />} />
+          <Route path="/" element={<Navigate to="/en/welcome" replace />} />
+        </Routes>
+      </Router>
+    </BlogProvider>
+  )
+}
+```
+
+> **Note**: BrowserRouter requires server configuration to fallback to `index.html` for all routes.
+
+### Using a base path
+
+To mount documentation under a subpath (e.g., `/blog` or `/docs`), set the `basePath` config option:
+
+```tsx
+export default function App() {
+  return (
+    <BlogProvider
+      config={{
+        title: 'My Documentation',
+        basePath: '/blog',  // All routes will be prefixed with /blog
+        supportedLanguages: SUPPORTED_LANGUAGES,
+        navigationData: NAVIGATION_DATA,
+      }}
+      blog={blog}
+    >
+      <Router>
+        <Routes>
+          {/* Routes now mounted under /blog */}
+          <Route path="/blog/:language/*" element={<DocumentationRoutes />} />
+          <Route path="/blog" element={<Navigate to="/blog/en/welcome" replace />} />
+          
+          {/* Your other app routes */}
+          <Route path="/" element={<HomePage />} />
+        </Routes>
+      </Router>
+    </BlogProvider>
+  )
+}
+```
+
+This ensures internal navigation (search, tags, language switching) uses the correct base path.
+
+## Writing content
+
+### File naming
+
+Place your MDX files in language-specific directories:
+
+```
+src/docs/
+├── en/welcome.mdx
+├── es/welcome.mdx
+└── zh/welcome.mdx
+```
+
+File names must match the `slug` field in your navigation definition.
 
 ### Frontmatter
 
+Optional YAML at the top of your MDX file:
+
 ```mdx
 ---
 title: Getting Started
@@ -61,68 +243,319 @@ tags:
 ---
 
 # Welcome!
-```
 
-Supported fields:
+Regular content here.
+```
 
 | Field | Type | Description |
 |---|---|---|
-| `title` | `string` | Document title (informational, not displayed as the main heading) |
-| `description` | `string` | SEO description override (used for `<meta name="description">`) |
-| `author` | `string` | Author display under the title |
-| `date` | `string` | Date shown under the title (i18n-aware label) |
-| `keywords` | `string[] \| string` | Optional SEO keywords list |
-| `hasAdvanced` | `boolean` | Enables Simple/Advanced toggle and `-advanced.mdx` variant |
-| `tags` | `string[]` | Tag labels used by the tag index modal |
+| `title` | `string` | Document title (informational, not displayed by framework) |
+| `description` | `string` | Optional SEO description for the article. Used in the page `<meta name="description">` tag. Falls back to site-level description if not provided. |
+| `author` | `string` | Author name. Displayed below the page title with a user icon. |
+| `date` | `string` | Publication or update date. Displayed below the page title with "Last edited" label and calendar icon (i18n supported). |
+| `keywords` | `string[] \| string` | Optional array of keywords or comma-separated string for SEO. Inserted into the page `<meta name="keywords">` tag. |
+| `hasAdvanced` | `boolean` | Enables Simple/Advanced mode toggle. Requires a `-advanced.mdx` variant. |
+| `tags` | `string[]` | Array of tag strings for categorizing content. Tags are automatically indexed by the framework when you pass `mdxFiles` to BlogProvider. Tags are clickable and show search results. |
 
 ### Advanced mode variants
 
-Create a paired file that ends with `-advanced.mdx`:
+Create `welcome-advanced.mdx` alongside `welcome.mdx`:
 
 ```
-packages/app/docs/en/
-├── welcome.mdx
-└── welcome-advanced.mdx
+src/docs/
+├── en/
+│   ├── welcome.mdx
+│   └── welcome-advanced.mdx
 ```
 
-Set `hasAdvanced: true` in the simple version frontmatter.
+Set `hasAdvanced: true` in the simple version's frontmatter, and the framework automatically shows a toggle.
+
+## API reference
 
-## Navigation configuration
+### Components
 
-Navigation lives in [packages/consts/src/navigation.ts](packages/consts/src/navigation.ts) and is passed into `BlogProvider` via the app config. Each entry can specify `showTableOfContents` per item.
+All components are exported from `@x-wave/blog`:
 
-## Next.js implementation notes
+```ts
+import { 
+  BlogProvider, 
+  DocumentationRoutes,
+  DocumentationLayout, 
+  ContentPage,
+  HomePage,
+  Header,
+  Sidebar,
+  TableOfContents,
+  AdvancedModeToggle,
+  Metadata
+} from '@x-wave/blog'
+```
 
-- **Static params**: `generateStaticParams()` in [packages/app/app/[language]/[slug]/page.tsx](packages/app/app/%5Blanguage%5D/%5Bslug%5D/page.tsx)
-- **Server-side content**: `readArticle()` and `readEnglishContent()` in [packages/app/lib/content.ts](packages/app/lib/content.ts)
-- **Client render**: `ContentPage` in [packages/ui/src/components/ContentPage/index.tsx](packages/ui/src/components/ContentPage/index.tsx)
+| Component | Purpose |
+|---|---|
+| `BlogProvider` | Root context wrapper (required) |
+| `DocumentationRoutes` | Pre-configured Routes for documentation pages (recommended) |
+| `DocumentationLayout` | Page layout: header + sidebar + content |
+| `ContentPage` | Loads and renders MDX pages |
+| `HomePage` | Lists latest articles with metadata (configurable via `defaultRoute`) |
+| `Header` | Top navigation bar |
+| `Sidebar` | Left navigation panel |
+| `TableOfContents` | "On this page" anchor panel |
+| `AdvancedModeToggle` | Simple/Advanced tab switch |
+| `Metadata` | Displays author and publication date with icons (used in HomePage and ContentPage) |
+
+### Hooks
+
+```ts
+import { useTheme } from '@x-wave/blog'
+
+const { theme, setTheme, effectiveTheme } = useTheme()
+```
+Manages light/dark/system theme preference.
+
+### Utilities
+
+```ts
+import { createBlogUtils } from '@x-wave/blog'
+
+const blog = createBlogUtils(mdxFiles)
+```
+Creates all blog utilities from a Vite glob import. This is the recommended approach as it bundles everything together.
+
+Returns an object with:
+- **`mdxFiles`**: The glob import (used internally for automatic tag indexing)
+- **`loadContent(language, slug, advanced?)`**: Loads MDX content for a specific language and slug
+- **`loadEnglishContent(slug, advanced?)`**: Loads English content for heading ID generation
+
+Pass the entire `blog` object to BlogProvider:
+
+```tsx
+<BlogProvider config={config} blog={blog}>
+```
+
+**Alternative: Advanced usage**
+
+```ts
+import { createContentLoaders } from '@x-wave/blog'
+
+const { loadMDXContent, loadEnglishContent, buildTagIndex } = createContentLoaders(mdxFiles)
+```
+For advanced use cases where you need more control over content loading and tag indexing.
+
+### Types
+
+All TypeScript types are exported from `@x-wave/blog/types`:
+
+```ts
+import type { NavigationEntry, BlogConfig, HeaderLink } from '@x-wave/blog/types'
+```
 
 ## Customization
 
-### Styles
+### CSS variables
+
+The framework uses CSS custom properties (`--xw-*` prefix) for theming. These are automatically injected when the framework initializes, but you can override them:
+
+```css
+/* In your app.css */
+.xw-blog-root {
+  --xw-primary: #007bff;
+  --xw-background: #fafafa;
+  --xw-foreground: #1a1a1a;
+  /* ... other variables */
+}
+```
+
+Or in JavaScript:
+
+```javascript
+const blogRoot = document.querySelector('.xw-blog-root')
+blogRoot.style.setProperty('--xw-primary', '#007bff')
+blogRoot.style.setProperty('--xw-background', '#fafafa')
+```
+
+Available CSS variables include:
+- `--xw-primary`, `--xw-secondary`
+- `--xw-background`, `--xw-foreground`
+- `--xw-card`, `--xw-card-foreground`
+- `--xw-muted`, `--xw-muted-foreground`
+- `--xw-accent`, `--xw-accent-foreground`
+- `--xw-border`, `--xw-ring`
+- And more—defined in `packages/styles/main.scss`
+
+All CSS variables are scoped to `.xw-blog-root` for isolation and to prevent conflicts with your application styles.
+
+### Config options
+
+**BlogConfig** properties:
+
+```ts
+interface BlogConfig {
+  title: string                                    // Site title
+  description?: string                            // Optional default description for SEO (used as fallback if article has no description)
+  logo?: React.ComponentType<{ className?: string }>  // Optional logo
+  supportedLanguages: readonly string[]           // e.g. ['en', 'es', 'zh']
+  navigationData: NavigationEntry[]               // Menu structure
+  basePath?: string                               // Base path for all routes (default: '')
+  contentMaxWidth?: string                        // Max width for content area (default: '80rem')
+  defaultRoute?: string                           // Default route: 'latest' (home page) or article slug (default: 'latest')
+  header?: {                                       // Optional: omit to hide built-in header
+    navLinks?: HeaderLink[]                       // Top-level nav links
+    dropdownItems?: HeaderDropdownItem[]          // Support dropdown menu
+  }
+}
+```
+
+**Key properties:**
+
+- **`header`**: Optional. If omitted entirely, the built-in header component will not be rendered. Use this when you want to implement a custom header.
+- **`description`**: Optional. Default SEO description used in the page `<meta name="description">` tag. Articles can override this with their own `description` in frontmatter.
+- **`contentMaxWidth`**: Optional. Set a custom maximum width for the main content area. Example: `'100rem'` or `'1400px'`. Default: `'80rem'`.
+- **`defaultRoute`**: Optional. Controls which page displays at the root path (`/`):
+  - Set to `'latest'` (default) to show the HomePage listing the latest articles
+  - Set to any article slug (e.g., `'welcome'`, `'getting-started'`) to redirect the root path to that article
+
+### Home page feature
 
-The compiled CSS is exported from `@x-wave/blog/styles`. In the Next.js app, it is imported once in [packages/app/app/globals.scss](packages/app/app/globals.scss). Override CSS variables on `.xw-blog-root` to theme the UI.
+The framework includes an optional home/latest posts page that lists articles sorted by publish date. Configure it with the `defaultRoute` option:
 
-### Base path
+```tsx
+// Show home page at root path (lists latest articles)
+config: {
+  defaultRoute: 'latest'  // or omit (defaults to 'latest')
+}
 
-If you mount the docs under a subpath, set `basePath` in the BlogProvider config. This ensures internal links and language switching include the prefix.
+// Or redirect root path to a specific article
+config: {
+  defaultRoute: 'welcome'  // Root path goes to /welcome article
+}
+```
+
+The home page displays:
+- **Title**: "Latest Posts" (i18n translated)
+- **Header metadata**: Author and date from the most recent article
+- **Article cards**: Recent articles with title, description, author, and date
+- **Sorting**: Articles sorted by date (newest first), limited to 50 articles
+
+Article metadata comes from MDX frontmatter:
+```mdx
+---
+title: Getting Started
+author: Jane Doe
+date: 2026-02-23
+description: Learn the basics in 5 minutes
+keywords: [getting started, tutorial, basics]
+---
+```
 
-### Custom header
+### Custom headers
+
+If you need a custom header instead of the built-in one, simply omit the `header` config and use the provided hooks:
+
+```tsx
+import { useTheme, useSearchModal } from '@x-wave/blog'
+import { Moon, Sun, MagnifyingGlass } from '@phosphor-icons/react'
+
+function CustomHeader() {
+  const { theme, setTheme } = useTheme()
+  const { openSearchModal } = useSearchModal()
+
+  return (
+    <header>
+      <h1>My Custom Header</h1>
+      
+      {/* Theme toggle button */}
+      <button onClick={() => setTheme(theme === 'dark' ? 'light' : 'dark')}>
+        {theme === 'dark' ? <Sun /> : <Moon />}
+      </button>
+      
+      {/* Search button */}
+      <button onClick={openSearchModal}>
+        <MagnifyingGlass />
+      </button>
+    </header>
+  )
+}
+
+function App() {
+  return (
+    <BlogProvider
+      config={{
+        title: 'My Docs',
+        supportedLanguages: ['en'],
+        navigationData: NAVIGATION_DATA,
+        // No header config = no built-in header
+      }}
+      blog={blog}
+    >
+      <CustomHeader />
+      <Router>
+        <Routes>
+          <Route path="/:language/*" element={<DocumentationRoutes />} />
+        </Routes>
+      </Router>
+    </BlogProvider>
+  )
+}
+```
 
-Omit the `header` config to hide the built-in header and use the hooks provided by the UI package (`useTheme`, `useSearchModal`).
+### Reusable components
 
-## Scripts
+#### Metadata component
 
-From repo root:
+The `Metadata` component displays article metadata (author and publication date) with icons and i18n support. It's used throughout the framework (HomePage and ContentPage) but is also exported for your own use:
 
-- `pnpm dev`: Starts the Next.js app and blog watcher
-- `pnpm build`: Builds all packages and the app
-- `pnpm build:blog`: Builds the blog package output
+```tsx
+import { Metadata } from '@x-wave/blog'
+
+function MyComponent() {
+  return (
+    <Metadata 
+      author="Jane Doe"
+      date="2026-02-23"
+    />
+  )
+}
+```
+
+The component:
+- Displays author with a user icon
+- Displays date with a calendar icon and "Last edited" label
+- Automatically formats the date using the user's locale
+- Returns `null` if both author and date are missing
+- Uses i18n for the "Last edited" label and date formatting
+
+**Available hooks:**
+
+- **`useTheme()`**: Returns `{ theme, setTheme, effectiveTheme }` for managing light/dark/system theme
+- **`useSearchModal()`**: Returns `{ openSearchModal, closeSearchModal }` for controlling the search modal
+
+These are the exact functions used by the built-in header, so you get the same functionality with full customization.
+
+**Key properties (continued):**
+
+| Property | Type | Required | Description |
+|---|---|---|---|
+| `title` | `string` | Yes | Site title displayed in header and sidebar |
+| `supportedLanguages` | `string[]` | Yes | Array of language codes (e.g., `['en', 'es', 'zh']`) |
+| `navigationData` | `NavigationEntry[]` | Yes | Sidebar navigation structure |
+| `basePath` | `string` | No | Base path prefix for all routes. Use when mounting docs under a subpath like `/blog` or `/docs`. Default: `''` (root) |
+| `logo` | `React.ComponentType` | No | SVG component for site logo |
+| `header` | `object` | No | Header configuration with nav links and dropdown items |
+
+## Browser support
+
+- Chrome/Edge 90+
+- Firefox 88+
+- Safari 14+
+- Mobile browsers (iOS Safari 14.5+, Chrome Android 90+)
 
 ## License
 
-See [LICENSE](LICENSE).
+See LICENSE file in this repository.
+
+---
 
-## Maintainers
+## For framework maintainers
 
-See [DEVELOPMENT.md](DEVELOPMENT.md) for build system details and contributor notes.
+Contributing or maintaining this framework? See [DEVELOPMENT.md](./DEVELOPMENT.md) for setup, architecture, and build system details.