@x-wave/blog 1.0.4 → 1.0.6

package/README.md

@@ -65,14 +65,14 @@ 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 '@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 />)
 ```
 
-> **The styles import is required** for the UI components and layout to render correctly.
+> **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:**
 
@@ -348,34 +348,36 @@ import type { NavigationEntry, BlogConfig, HeaderLink } from '@x-wave/blog/types
 
 ### CSS variables
 
-The framework exports SCSS variable files. Import and override them in your own stylesheets:
+The framework uses CSS custom properties (`--xw-*` prefix) for theming. These are automatically injected when the framework initializes, but you can override them:
 
-```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
+```css
+/* In your app.css */
+.xw-blog-root {
+  --xw-primary: #007bff;
+  --xw-background: #fafafa;
+  --xw-foreground: #1a1a1a;
+  /* ... other variables */
+}
 ```
 
-Or import directly from the framework package:
+Or in JavaScript:
 
-```scss
-@import 'node_modules/@x-wave/blog/dist/styles/_variables.scss';
-
-$color-primary: #007bff;
-$color-background: #fafafa;
+```javascript
+const blogRoot = document.querySelector('.xw-blog-root')
+blogRoot.style.setProperty('--xw-primary', '#007bff')
+blogRoot.style.setProperty('--xw-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)
+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
 
@@ -388,7 +390,7 @@ interface BlogConfig {
   supportedLanguages: readonly string[]           // e.g. ['en', 'es', 'zh']
   navigationData: NavigationEntry[]               // Menu structure
   basePath?: string                               // Base path for all routes (default: '')
-  header?: {
+  header?: {                                       // Optional: omit to hide built-in header
     navLinks?: HeaderLink[]                       // Top-level nav links
     dropdownItems?: HeaderDropdownItem[]          // Support dropdown menu
   }
@@ -397,6 +399,68 @@ interface BlogConfig {
 
 **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.
+
+### 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>
+  )
+}
+```
+
+**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 |