@x-wave/blog 0.1.0 → 1.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x-wave/blog",
-  "version": "0.1.0",
+  "version": "1.0.0",
   "type": "module",
   "exports": {
     ".": {

package/README.md

@@ -1,387 +0,0 @@
-# @x-wave/blog
-
-A responsive, multi-language documentation framework for React + Vite applications. Ships with TypeScript, i18n (i18next), MDX support, dark mode, and built-in navigation.
-
-## Features
-
-- **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
-
-## Installation
-
-### npm
-
-```bash
-npm install @x-wave/blog
-```
-
-### pnpm
-
-```bash
-pnpm add @x-wave/blog
-```
-
-### yarn
-
-```bash
-yarn add @x-wave/blog
-```
-
-## Quick setup
-
-### 1. Create your app structure
-
-```
-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'    // Framework styles (required)
-import { createRoot } from 'react-dom/client'
-import App from './App'
-
-createRoot(document.getElementById('root')!).render(<App />)
-```
-
-> **The styles import is required** for the UI components and layout to render correctly.
-
-**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, ContentPage, DocumentationLayout } from '@x-wave/blog'
-import { Navigate, Route, HashRouter as Router, Routes, useParams } from 'react-router-dom'
-import { blog } from './utils'
-import { NAVIGATION_DATA } from './navigation'
-
-const SUPPORTED_LANGUAGES = ['en', 'es', 'zh'] as const
-
-function DocumentationWrapper() {
-  const { language } = useParams<{ language: string }>()
-  return (
-    <DocumentationLayout>
-      <Routes>
-        <Route path="/:slug" element={<ContentPage language={language!} />} />
-        <Route path="/" element={<Navigate to={`/${language}/welcome`} replace />} />
-      </Routes>
-    </DocumentationLayout>
-  )
-}
-
-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={<DocumentationWrapper />} />
-          <Route path="/" element={<Navigate to="/en/welcome" replace />} />
-        </Routes>
-      </Router>
-    </BlogProvider>
-  )
-}
-```
-
-## 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
-author: Jane Doe
-date: 2026-02-23
-hasAdvanced: true
-tags:
-  - tutorial
-  - beginner
----
-
-# Welcome!
-
-Regular content here.
-```
-
-| Field | Type | Description |
-|---|---|---|
-| `title` | `string` | Document title (informational, not displayed by framework) |
-| `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). |
-| `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 `welcome-advanced.mdx` alongside `welcome.mdx`:
-
-```
-src/docs/
-├── en/
-│   ├── welcome.mdx
-│   └── welcome-advanced.mdx
-```
-
-Set `hasAdvanced: true` in the simple version's frontmatter, and the framework automatically shows a toggle.
-
-## API reference
-
-### Components
-
-All components are exported from `@x-wave/blog`:
-
-```ts
-import { 
-  BlogProvider, 
-  DocumentationLayout, 
-  ContentPage,
-  Header,
-  Sidebar,
-  TableOfContents,
-  AdvancedModeToggle
-} from '@x-wave/blog'
-```
-
-| Component | Purpose |
-|---|---|
-| `BlogProvider` | Root context wrapper (required) |
-| `DocumentationLayout` | Page layout: header + sidebar + content |
-| `ContentPage` | Loads and renders MDX pages |
-| `Header` | Top navigation bar |
-| `Sidebar` | Left navigation panel |
-| `TableOfContents` | "On this page" anchor panel |
-| `AdvancedModeToggle` | Simple/Advanced tab switch |
-
-### 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
-
-### CSS variables
-
-The framework exports SCSS variable files. Import and override them in your own stylesheets:
-
-```scss
-// In your app.scss
-@use '~@x-wave/blog/styles/_variables' as vars;
-
-// Override the color palette
-$color-primary: #007bff;
-$color-background: #fafafa;
-
-// Your custom styles here
-```
-
-Or import directly from the framework package:
-
-```scss
-@import 'node_modules/@x-wave/blog/dist/styles/_variables.scss';
-
-$color-primary: #007bff;
-$color-background: #fafafa;
-```
-
-Available variables include:
-- `$color-primary`, `$color-secondary`
-- `$color-background`, `$color-text`
-- `$spacing-xs`, `$spacing-sm`, `$spacing-md`, `$spacing-lg`, `$spacing-xl`
-- `$font-family-sans`, `$font-family-mono`
-- And more—see [styles/_variables.scss](packages/styles/_variables.scss)
-
-### Config options
-
-**BlogConfig** properties:
-
-```ts
-interface BlogConfig {
-  title: string                                    // Site title
-  logo?: React.ComponentType<{ className?: string }>  // Optional logo
-  supportedLanguages: readonly string[]           // e.g. ['en', 'es', 'zh']
-  navigationData: NavigationEntry[]               // Menu structure
-  header?: {
-    navLinks?: HeaderLink[]                       // Top-level nav links
-    dropdownItems?: HeaderDropdownItem[]          // Support dropdown menu
-  }
-}
-```
-
-## Browser support
-
-- Chrome/Edge 90+
-- Firefox 88+
-- Safari 14+
-- Mobile browsers (iOS Safari 14.5+, Chrome Android 90+)
-
-## License
-
-See LICENSE file in this repository.
-
----
-
-## For framework maintainers
-
-Contributing or maintaining this framework? See [DEVELOPMENT.md](./DEVELOPMENT.md) for setup, architecture, and build system details.