@x-wave/blog 2.2.8 → 2.3.0

package/components/AdvancedModeToggle/index.d.ts

@@ -0,0 +1,5 @@
+interface AdvancedModeToggleProps {
+    hasAdvanced: boolean;
+}
+export declare function AdvancedModeToggle({ hasAdvanced }: AdvancedModeToggleProps): import("react/jsx-runtime").JSX.Element | null;
+export {};

package/components/ArticleNavigation/index.d.ts

@@ -0,0 +1,8 @@
+export interface ArticleNavigationProps {
+    prevSlug?: string;
+    prevTitle?: string;
+    nextSlug?: string;
+    nextTitle?: string;
+    language: string;
+}
+export declare function ArticleNavigation({ prevSlug, prevTitle, nextSlug, nextTitle, language, }: ArticleNavigationProps): import("react/jsx-runtime").JSX.Element | null;

package/components/BlogRoot/index.d.ts

@@ -0,0 +1,10 @@
+import { ReactNode } from 'react';
+interface BlogRootProps {
+    children: ReactNode;
+}
+/**
+ * BlogRoot component marks the entry point of the blog framework in the DOM.
+ * All blog-specific styles and functionality are scoped within this element.
+ */
+export declare function BlogRoot({ children }: BlogRootProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/components/BlogSidebar/index.d.ts

@@ -0,0 +1 @@
+export declare function BlogSidebar(): import("react/jsx-runtime").JSX.Element | null;

package/components/Breadcrumb/index.d.ts

@@ -0,0 +1,5 @@
+export interface BreadcrumbProps {
+    articleTitle: string;
+    language: string;
+}
+export declare function Breadcrumb({ articleTitle, language }: BreadcrumbProps): import("react/jsx-runtime").JSX.Element;

package/components/ContentPage/index.d.ts

@@ -0,0 +1,6 @@
+import { SupportedLanguage } from 'types';
+interface ContentPageProps {
+    language: SupportedLanguage;
+}
+export declare function ContentPage({ language }: ContentPageProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/components/DocumentationLayout/index.d.ts

@@ -0,0 +1,6 @@
+import { ReactNode } from 'react';
+interface DocumentationLayoutProps {
+    children: ReactNode;
+}
+export declare function DocumentationLayout({ children }: DocumentationLayoutProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/components/DocumentationRoutes/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Pre-configured Routes component for documentation pages.
+ * Use this inside your router to handle language-specific documentation routing.
+ *
+ * @example
+ * ```tsx
+ * import { BlogProvider, DocumentationRoutes } from '@x-wave/blog'
+ * import { BrowserRouter, Routes, Route, Navigate } from 'react-router-dom'
+ *
+ * function App() {
+ *   return (
+ *     <BlogProvider config={config} blog={blog}>
+ *       <BrowserRouter>
+ *         <Routes>
+ *           <Route path="/:language/*" element={<DocumentationRoutes />} />
+ *           <Route path="/" element={<Navigate to="/en/welcome" replace />} />
+ *         </Routes>
+ *       </BrowserRouter>
+ *     </BlogProvider>
+ *   )
+ * }
+ * ```
+ */
+export declare function DocumentationRoutes(): import("react/jsx-runtime").JSX.Element;

package/components/Header/index.d.ts

@@ -0,0 +1,5 @@
+interface HeaderProps {
+    onMobileMenuToggle?: () => void;
+}
+export declare function Header({ onMobileMenuToggle }: HeaderProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/components/HomePage/index.d.ts

@@ -0,0 +1,8 @@
+export interface BlogArticle {
+    slug: string;
+    title: string;
+    date?: string;
+    author?: string;
+    description?: string;
+}
+export declare function HomePage(): import("react/jsx-runtime").JSX.Element;

package/components/Metadata/index.d.ts

@@ -0,0 +1,5 @@
+export interface MetadataProps {
+    date?: string;
+    author?: string;
+}
+export declare function Metadata({ date, author }: MetadataProps): import("react/jsx-runtime").JSX.Element | null;

package/components/MobileMenu/index.d.ts

@@ -0,0 +1,6 @@
+interface MobileMenuProps {
+    isOpen: boolean;
+    onClose: () => void;
+}
+export declare function MobileMenu({ isOpen, onClose }: MobileMenuProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/components/NavigationContent/index.d.ts

@@ -0,0 +1,17 @@
+interface LanguageSelectorProps {
+    styles: Record<string, string>;
+    onLanguageChange?: () => void;
+}
+export declare function LanguageSelector({ styles, onLanguageChange, }: LanguageSelectorProps): import("react/jsx-runtime").JSX.Element;
+interface NavigationMenuProps {
+    styles: Record<string, string>;
+    onLinkClick?: () => void;
+}
+export declare function NavigationMenu({ styles, onLinkClick }: NavigationMenuProps): import("react/jsx-runtime").JSX.Element;
+interface NavigationContentProps {
+    styles: Record<string, string>;
+    onLinkClick?: () => void;
+    onLanguageChange?: () => void;
+}
+export declare function NavigationContent({ styles, onLinkClick, onLanguageChange, }: NavigationContentProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/components/SearchBar/index.d.ts

@@ -0,0 +1,5 @@
+interface SearchBarProps {
+    language: string;
+}
+export declare function SearchBar({ language }: SearchBarProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/components/Sidebar/index.d.ts

@@ -0,0 +1 @@
+export declare function Sidebar(): import("react/jsx-runtime").JSX.Element;

package/components/TableOfContents/index.d.ts

@@ -0,0 +1,6 @@
+interface TableOfContentsProps {
+    content: string;
+    englishContent: string;
+}
+export declare function TableOfContents({ content, englishContent, }: TableOfContentsProps): import("react/jsx-runtime").JSX.Element | null;
+export {};

package/components/TagResultsModal/index.d.ts

@@ -0,0 +1,12 @@
+interface TagResult {
+    title: string;
+    slug: string;
+}
+interface TagResultsModalProps {
+    tag: string;
+    results: TagResult[];
+    language: string;
+    onClose: () => void;
+}
+export declare function TagResultsModal({ tag, results, language, onClose, }: TagResultsModalProps): import('react').ReactPortal;
+export {};

package/components/Tags/index.d.ts

@@ -0,0 +1,7 @@
+interface TagsProps {
+    tags: string[];
+    variant?: 'default' | 'compact';
+    onTagClick?: (tag: string) => void;
+}
+export declare function Tags({ tags, variant, onTagClick }: TagsProps): import("react/jsx-runtime").JSX.Element | null;
+export {};

package/context.d.ts

@@ -0,0 +1,194 @@
+import { ReactNode } from 'react';
+import { LoadedContent, NavigationEntry } from 'types';
+/**
+ * Configuration for the blog framework, provided once via `BlogProvider`
+ * and accessible throughout the component tree via `useBlogConfig()`.
+ */
+export interface BlogConfig {
+    /** The blog/docs site title displayed in the sidebar and mobile menu. */
+    title: string;
+    /**
+     * Optional default description for SEO meta tags.
+     * Used as fallback description for articles that don't have their own description.
+     */
+    description?: string;
+    /**
+     * An optional SVG React component used as the site logo.
+     * Receives a `className` prop for styling.
+     * Example: `import CloudSvg from './cloud.svg?react'`
+     */
+    logo?: React.ComponentType<{
+        className?: string;
+    }>;
+    /**
+     * The list of supported locale codes (e.g. `['en', 'zh', 'es']`).
+     * These are used for language validation in routing and the language switcher.
+     */
+    supportedLanguages: readonly string[];
+    /**
+     * Optional base path for all documentation routes.
+     * Use this when mounting documentation under a subpath (e.g., '/blog' or '/docs').
+     * Default: '' (root path)
+     * Example: basePath: '/blog' → routes become /blog/en/welcome
+     */
+    basePath?: string;
+    /**
+     * Optional maximum width for the content area.
+     * Default: '80rem'
+     * Example: contentMaxWidth: '100rem' or contentMaxWidth: '1400px'
+     */
+    contentMaxWidth?: string;
+    /**
+     * The default route displayed at the root path (/).
+     * Use 'latest' to show the home page listing latest articles.
+     * Use any slug (e.g., 'welcome', 'getting-started') to display that article.
+     * Default: 'latest'
+     * Example: defaultRoute: 'welcome' or defaultRoute: 'latest'
+     */
+    defaultRoute?: string;
+    /**
+     * Whether to display the sidebar navigation menu.
+     * Default: true
+     * Note: This is independent of navigationData. You can have navigationData without showing a sidebar,
+     * or show a sidebar with empty navigationData.
+     */
+    showSideMenu?: boolean;
+    /**
+     * Whether to display next/previous article navigation at the bottom of content pages.
+     * Useful for guiding readers through sequential content.
+     * Default: false
+     */
+    showArticleNavigation?: boolean;
+    /**
+     * Optional default theme for the blog.
+     * If set, this will override the user's localStorage preference and system theme.
+     * Use this to ensure the blog matches your consuming app's theme.
+     * Options: 'light' | 'dark' | 'system' (default: uses localStorage or 'system')
+     */
+    defaultTheme?: 'light' | 'dark' | 'system';
+    /**
+     * Optional header configuration.
+     * If omitted entirely, the built-in header component will not be rendered.
+     * Use the exported `useTheme()` and `useSearchModal()` hooks to build custom headers.
+     */
+    header?: {
+        /**
+         * Custom navigation links displayed in the header.
+         * Example: "Launch App" button or external links.
+         */
+        navLinks?: HeaderLink[];
+        /**
+         * Custom dropdown menu items.
+         * If provided, displays a "Support" dropdown with these items.
+         */
+        dropdownItems?: HeaderDropdownItem[];
+    };
+    /**
+     * Optional social links displayed in the blog sidebar.
+     * These links appear in the "Connect" section on the home page.
+     * Example: Discord, GitHub, Email, etc.
+     */
+    socialLinks?: HeaderLink[];
+    /**
+     * Optional React node to render after article content as a Call-to-Action.
+     * Appears after the main content but before tags and article navigation.
+     * Example: Newsletter signup, related links, promotional content.
+     */
+    articleCTA?: React.ReactNode;
+    /**
+     * Optional custom font CSS property for article titles.
+     * Applied to h1 blog titles on ContentPage and title on HomePage.
+     * Example: 'Roboto, sans-serif' or '"Segoe UI", sans-serif'
+     */
+    articleTitleFont?: string;
+}
+/**
+ * A navigation link in the header.
+ */
+export interface HeaderLink {
+    /** Link text. Can be a string, i18n key, or React element. */
+    label: string | React.ReactNode;
+    /** Link URL (supports mailto: and other protocols). */
+    url: string;
+    /** Optional icon component (receives `className` prop for styling). */
+    icon?: React.ComponentType<{
+        className?: string;
+    }>;
+    /** Whether to open in new tab. Defaults to `true` for external URLs. */
+    target?: '_blank' | '_self';
+    /** rel attribute (e.g. 'noopener noreferrer'). Auto-set if target is '_blank'. */
+    rel?: string;
+    /** Optional CSS class name for custom styling. */
+    className?: string;
+}
+/**
+ * A dropdown menu item in the header support dropdown.
+ */
+export interface HeaderDropdownItem {
+    /** Item text. Can be a string, i18n key, or React element. */
+    label: string | React.ReactNode;
+    /** Item URL (supports mailto: and other protocols). */
+    url: string;
+    /** Optional icon component (receives `className` prop for styling). */
+    icon?: React.ComponentType<{
+        className?: string;
+    }>;
+    /** Whether to open in new tab. Defaults to `true` for external URLs. */
+    target?: '_blank' | '_self';
+    /** rel attribute (e.g. 'noopener noreferrer'). Auto-set if target is '_blank'. */
+    rel?: string;
+}
+export interface BlogContextValue {
+    config: BlogConfig & {
+        /** Dynamically built tag index from MDX frontmatter, per language */
+        tagIndex?: Record<string, Record<string, Array<{
+            slug: string;
+            title: string;
+        }>>>;
+        /** Optional navigation data passed to BlogProvider */
+        navigationData?: NavigationEntry[];
+    };
+    loadContent: (language: string, slug: string, advanced?: boolean) => Promise<LoadedContent>;
+    loadEnglishContent: (slug: string, advanced?: boolean) => Promise<string>;
+    discoverArticles: (language: string) => Promise<Array<{
+        slug: string;
+        title: string;
+        date?: string;
+        author?: string;
+        description?: string;
+    }>>;
+}
+/**
+ * Blog utilities object returned from createBlogUtils().
+ * Contains MDX files glob and content loaders.
+ */
+export interface BlogUtils {
+    mdxFiles: Record<string, () => Promise<unknown>>;
+    loadContent: (language: string, slug: string, advanced?: boolean) => Promise<LoadedContent>;
+    loadEnglishContent: (slug: string, advanced?: boolean) => Promise<string>;
+    discoverArticles: (language: string) => Promise<Array<{
+        slug: string;
+        title: string;
+        date?: string;
+        author?: string;
+        description?: string;
+    }>>;
+}
+export interface BlogProviderProps {
+    children: ReactNode;
+    config: BlogConfig;
+    /**
+     * Blog utilities object returned from createBlogUtils().
+     * Contains MDX files and content loaders.
+     */
+    blog: BlogUtils;
+    /**
+     * Optional navigation structure for the docs sidebar.
+     * If omitted, the sidebar will not be rendered.
+     * Entries may be individual items or grouped sections.
+     * Titles should be i18n keys resolved at runtime.
+     */
+    navigationData?: NavigationEntry[];
+}
+export declare function BlogProvider({ children, config, blog, navigationData, }: BlogProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare function useBlogConfig(): BlogContextValue;

package/hooks.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Hooks and utilities for custom header implementations.
+ * These are the same functions used by the built-in Header component.
+ */
+export type { Theme } from './theme';
+export { useTheme } from './theme';
+/**
+ * Hook to control the search modal.
+ * Returns functions to open/close the search modal programmatically.
+ */
+export declare function useSearchModal(): {
+    openSearchModal: () => void;
+    closeSearchModal: () => void;
+};
+/**
+ * Hook to change the language.
+ * Returns a function that changes the i18n language and navigates to the corresponding route.
+ * Preserves search params and hash, and handles basePath correctly.
+ *
+ * @example
+ * ```tsx
+ * const changeLanguage = useLanguageChange()
+ * <button onClick={() => changeLanguage('es')}>Español</button>
+ * ```
+ */
+export declare function useLanguageChange(): (newLanguage: string) => void;

package/index.d.ts

@@ -0,0 +1,28 @@
+export { AdvancedModeToggle } from './components/AdvancedModeToggle';
+export type { ArticleNavigationProps } from './components/ArticleNavigation';
+export { ArticleNavigation } from './components/ArticleNavigation';
+export { BlogRoot } from './components/BlogRoot';
+export { BlogSidebar } from './components/BlogSidebar';
+export type { BreadcrumbProps } from './components/Breadcrumb';
+export { Breadcrumb } from './components/Breadcrumb';
+export { ContentPage } from './components/ContentPage';
+export { DocumentationLayout } from './components/DocumentationLayout';
+export { DocumentationRoutes } from './components/DocumentationRoutes';
+export { Header } from './components/Header';
+export { HomePage } from './components/HomePage';
+export type { MetadataProps } from './components/Metadata';
+export { Metadata } from './components/Metadata';
+export { MobileMenu } from './components/MobileMenu';
+export { LanguageSelector, NavigationContent, NavigationMenu, } from './components/NavigationContent';
+export { SearchBar } from './components/SearchBar';
+export { Sidebar } from './components/Sidebar';
+export { TableOfContents } from './components/TableOfContents';
+export { TagResultsModal } from './components/TagResultsModal';
+export { Tags } from './components/Tags';
+export type { BlogConfig, BlogContextValue, BlogProviderProps, BlogUtils, HeaderDropdownItem, HeaderLink, } from './context';
+export { BlogProvider, useBlogConfig } from './context';
+export type { Theme } from './hooks';
+export { useLanguageChange, useSearchModal, useTheme } from './hooks';
+export { createBlogUtils, createContentLoaders } from './loaders';
+export { ThemeProvider } from './theme';
+export { generateHeadingId, getAdjacentArticles, getNavigationData, } from './utils';

package/loaders.d.ts

@@ -0,0 +1,92 @@
+import { LoadedContent } from 'types';
+/**
+ * Factory function to create content loader functions from a Vite glob import.
+ *
+ * The app must handle the `import.meta.glob` call because Vite resolves glob patterns
+ * relative to the file that calls them. This function handles all the generic logic:
+ * frontmatter parsing and content loading.
+ *
+ * @param mdxFiles - Object returned from `import.meta.glob('./docs/**\/*.mdx', { ... })`
+ * @returns Object with `loadMDXContent` and `loadEnglishContent` functions
+ *
+ * @example
+ * ```ts
+ * const mdxFiles = import.meta.glob('./docs/**\/*.mdx', {
+ *   query: '?raw',
+ *   import: 'default',
+ *   eager: false,
+ * })
+ *
+ * export const { loadMDXContent, loadEnglishContent } = createContentLoaders(mdxFiles)
+ * ```
+ */
+export declare function createContentLoaders(mdxFiles: Record<string, () => Promise<unknown>>): {
+    /**
+     * Load MDX content for a given language and slug.
+     * Automatically loads the advanced variant if `advanced` is true.
+     */
+    loadMDXContent(language: string, slug: string, advanced?: boolean): Promise<LoadedContent>;
+    /**
+     * Load English content for generating consistent heading IDs.
+     * All heading anchors are derived from English content for stability across translations.
+     */
+    loadEnglishContent(slug: string, advanced?: boolean): Promise<string>;
+    /**
+     * Build a tag index from all MDX files.
+     * Uses shared metadata cache to avoid duplicate file processing.
+     *
+     * @param language - Language code to scan (defaults to 'en')
+     * @returns Promise resolving to tag index mapping tag names to document info
+     */
+    buildTagIndex(language?: string): Promise<Record<string, Array<{
+        slug: string;
+        title: string;
+    }>>>;
+    /**
+     * Discover all articles from the file system by scanning MDX files.
+     * Uses shared metadata cache to avoid duplicate file processing with buildTagIndex.
+     *
+     * @param language - Language code to scan
+     * @returns Promise resolving to array of articles with metadata, sorted by date (newest first) then title
+     */
+    discoverArticles(language: string): Promise<Array<{
+        slug: string;
+        title: string;
+        date?: string;
+        author?: string;
+        description?: string;
+    }>>;
+};
+/**
+ * Convenience function to create all blog utilities from a Vite glob import.
+ * This bundles mdxFiles, content loaders, and tag indexing into a single export.
+ *
+ * @param mdxFiles - Object returned from `import.meta.glob('./docs/**\/*.mdx', { ... })`
+ * @returns Object with mdxFiles, loadContent, loadEnglishContent, and discoverArticles
+ *
+ * @example
+ * ```ts
+ * const mdxFiles = import.meta.glob('./docs/**\/*.mdx', {
+ *   query: '?raw',
+ *   import: 'default',
+ *   eager: false,
+ * })
+ *
+ * export const blog = createBlogUtils(mdxFiles)
+ *
+ * // In App.tsx:
+ * <BlogProvider config={config} blog={blog} />
+ * ```
+ */
+export declare function createBlogUtils(mdxFiles: Record<string, () => Promise<unknown>>): {
+    mdxFiles: Record<string, () => Promise<unknown>>;
+    loadContent: (language: string, slug: string, advanced?: boolean) => Promise<LoadedContent>;
+    loadEnglishContent: (slug: string, advanced?: boolean) => Promise<string>;
+    discoverArticles: (language: string) => Promise<Array<{
+        slug: string;
+        title: string;
+        date?: string;
+        author?: string;
+        description?: string;
+    }>>;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x-wave/blog",
-  "version": "2.2.8",
+  "version": "2.3.0",
   "type": "module",
   "exports": {
     ".": {
@@ -51,6 +51,7 @@
     "@vitejs/plugin-react-swc": "^3.10.1",
     "sass": "^1.97.3",
     "vite": "^6.3.5",
+    "vite-plugin-dts": "^4.5.4",
     "vite-tsconfig-paths": "^5.1.4"
   }
 }

package/theme.d.ts

@@ -0,0 +1,20 @@
+import { ReactNode } from 'react';
+/**
+ * Theme preference options:
+ * - `'light'` - always use light theme
+ * - `'dark'` - always use dark theme
+ * - `'system'` - automatically follow the OS/browser preference
+ */
+export type Theme = 'light' | 'dark' | 'system';
+interface ThemeContextValue {
+    theme: Theme;
+    setTheme: (theme: Theme) => void;
+    effectiveTheme: 'light' | 'dark';
+}
+interface ThemeProviderProps {
+    children: ReactNode;
+    defaultTheme?: Theme;
+}
+export declare function ThemeProvider({ children, defaultTheme }: ThemeProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare const useTheme: () => ThemeContextValue;
+export {};

package/utils/links.d.ts

@@ -0,0 +1,41 @@
+/**
+ * URL and link manipulation utilities for the blog framework
+ */
+/**
+ * Build an internal link with language prefix and optional basePath
+ *
+ * @param path - The relative path (e.g., 'welcome', 'glossary')
+ * @param language - The language code (e.g., 'en', 'es', 'zh')
+ * @param basePath - Optional base path prefix
+ * @returns The formatted link URL
+ */
+export declare function buildInternalLink(path: string, language: string, basePath?: string): string;
+/**
+ * Parse search/query parameters from a URL search string
+ *
+ * @param search - The search string (with or without leading ?)
+ * @returns Object with parsed advanced mode and anchor parameters
+ */
+export declare function parseSearchParams(search: string): {
+    advanced: boolean;
+    anchor: string;
+};
+/**
+ * Smooth scroll to an element by ID
+ *
+ * @param id - The element ID to scroll to
+ * @param headerOffset - Vertical offset to account for sticky header (default: 80px)
+ */
+export declare function scrollToElement(id: string, headerOffset?: number): void;
+/**
+ * Update the current URL with an anchor parameter and optional advanced mode flag
+ *
+ * @param anchorId - The anchor ID to link to
+ * @param isAdvancedMode - Whether advanced mode is enabled (default: false)
+ */
+export declare function updateUrlWithAnchor(anchorId: string, isAdvancedMode?: boolean): void;
+/**
+ * Scroll to the top of the window
+ * @param behavior - Scroll behavior: 'smooth' for animated scroll, 'auto' for instant
+ */
+export declare function scrollToTop(behavior?: 'smooth' | 'auto'): void;

package/utils.d.ts

@@ -0,0 +1,31 @@
+import { LoadedContent, NavigationEntry, NavigationEntryWithTitles, NavigationSection } from 'types';
+export type { Theme } from './theme';
+export { ThemeProvider, useTheme } from './theme';
+export declare const isNavigationSection: (entry: NavigationEntry) => entry is NavigationSection;
+export declare const isNavigationSectionWithTitles: (entry: NavigationEntryWithTitles) => entry is {
+    title: string;
+    items: Array<{
+        title: string;
+        slug: string;
+    }>;
+};
+export declare const getNavigationData: (navigationData: NavigationEntry[], language: string, loadContent: (language: string, slug: string, advanced?: boolean) => Promise<LoadedContent>) => Promise<NavigationEntryWithTitles[]>;
+export declare const generateHeadingId: (text: string) => string;
+/**
+ * Get the next and previous article based on chronological order.
+ * Articles are ordered by date (newest first), then alphabetically by title.
+ * Prev = newer article, Next = older article.
+ */
+export declare const getAdjacentArticles: (currentSlug: string, articles: Array<{
+    slug: string;
+    title: string;
+}>) => {
+    prev?: {
+        slug: string;
+        title: string;
+    };
+    next?: {
+        slug: string;
+        title: string;
+    };
+};