@x-wave/blog 2.2.7 → 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/consts/index.js

@@ -0,0 +1,24 @@
+const t = [
+  {
+    slug: "welcome"
+  },
+  {
+    title: "nav.helpResources",
+    defaultOpen: !0,
+    items: [
+      {
+        slug: "glossary"
+      },
+      {
+        slug: "faq"
+      }
+    ]
+  }
+], s = "Staking Docs", o = ["en", "zh", "es"], e = "https://github.com/polkadot-cloud", l = "https://staking.polkadot.cloud";
+export {
+  s as DOCS_TITLE,
+  e as GITHUB_REPO_URL,
+  t as NAVIGATION_DATA,
+  l as STAKING_DASHBOARD_URL,
+  o as SUPPORTED_LANGUAGES
+};

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/locales/index.js

@@ -0,0 +1,180 @@
+import e from "i18next";
+import { default as c } from "i18next";
+import a from "i18next-browser-languagedetector";
+import { initReactI18next as t } from "react-i18next";
+const s = {
+  en: {
+    translation: {
+      language: "English",
+      languageCode: "en",
+      nav: {
+        gettingStarted: "Getting Started",
+        helpResources: "Help Resources",
+        guides: "Guides",
+        reference: "Reference",
+        previous: "Previous",
+        next: "Next"
+      },
+      docs: {
+        helloWorld: "Welcome!",
+        gettingStarted: "Getting Started",
+        glossary: "Glossary",
+        faq: "FAQ"
+      },
+      ui: {
+        home: "Home",
+        simple: "Simple",
+        advanced: "Advanced",
+        switchLanguage: "Switch Language",
+        tableOfContents: "Table of Contents",
+        onThisPage: "On this page",
+        launchApp: "Launch App",
+        support: "Support",
+        discord: "Discord",
+        email: "Email",
+        theme: "Theme",
+        light: "Light",
+        dark: "Dark",
+        system: "System",
+        search: "Search",
+        searchPlaceholder: "Search documentation...",
+        searchNavigate: "to navigate",
+        searchSelect: "to select",
+        searchClose: "to close",
+        noSearchResults: "No results found",
+        tags: "Tags",
+        filterByTag: "Filter by tag",
+        tagResults: "Articles tagged with",
+        noTagResults: "No articles found with this tag",
+        lastEdited: "Last edited",
+        axes: "Articles",
+        latestPosts: "Latest Posts",
+        loadingArticles: "Loading articles...",
+        noArticlesFound: "No articles found",
+        by: "By",
+        connect: "Connect"
+      }
+    }
+  },
+  zh: {
+    translation: {
+      language: "中文",
+      languageCode: "zh",
+      nav: {
+        gettingStarted: "开始使用",
+        helpResources: "帮助资源",
+        guides: "指南",
+        reference: "参考",
+        previous: "上一篇",
+        next: "下一篇"
+      },
+      docs: {
+        helloWorld: "欢迎！",
+        gettingStarted: "开始使用",
+        glossary: "术语表",
+        faq: "常见问题"
+      },
+      ui: {
+        home: "首页",
+        simple: "简单",
+        advanced: "高级",
+        switchLanguage: "切换语言",
+        tableOfContents: "目录",
+        onThisPage: "本页内容",
+        launchApp: "启动应用",
+        support: "支持",
+        discord: "Discord",
+        email: "电子邮件",
+        theme: "主题",
+        light: "浅色",
+        dark: "深色",
+        system: "系统",
+        search: "搜索",
+        searchPlaceholder: "搜索文档...",
+        searchNavigate: "导航",
+        searchSelect: "选择",
+        searchClose: "关闭",
+        noSearchResults: "未找到结果",
+        tags: "标签",
+        filterByTag: "按标签筛选",
+        tagResults: "带有标签的文章",
+        noTagResults: "未找到带有此标签的文章",
+        lastEdited: "最后编辑",
+        articles: "文章",
+        loadingArticles: "正在加载文章...",
+        noArticlesFound: "未找到文章",
+        by: "作者",
+        connect: "连接"
+      }
+    }
+  },
+  es: {
+    translation: {
+      language: "Español",
+      languageCode: "es",
+      nav: {
+        gettingStarted: "Primeros Pasos",
+        helpResources: "Recursos de Ayuda",
+        guides: "Guías",
+        reference: "Referencia",
+        previous: "Anterior",
+        next: "Siguiente"
+      },
+      docs: {
+        helloWorld: "¡Bienvenido!",
+        gettingStarted: "Primeros Pasos",
+        glossary: "Glosario",
+        faq: "Preguntas Frecuentes"
+      },
+      ui: {
+        home: "Inicio",
+        simple: "Simple",
+        advanced: "Avanzado",
+        switchLanguage: "Cambiar Idioma",
+        tableOfContents: "Tabla de Contenidos",
+        onThisPage: "En esta página",
+        launchApp: "Iniciar App",
+        support: "Soporte",
+        discord: "Discord",
+        email: "Correo",
+        theme: "Tema",
+        light: "Claro",
+        dark: "Oscuro",
+        system: "Sistema",
+        search: "Buscar",
+        searchPlaceholder: "Buscar documentación...",
+        searchNavigate: "para navegar",
+        searchSelect: "para seleccionar",
+        searchClose: "para cerrar",
+        noSearchResults: "No se encontraron resultados",
+        tags: "Etiquetas",
+        filterByTag: "Filtrar por etiqueta",
+        tagResults: "Artículos etiquetados con",
+        noTagResults: "No se encontraron artículos con esta etiqueta",
+        lastEdited: "Última edición",
+        articles: "Artículos",
+        loadingArticles: "Cargando artículos...",
+        noArticlesFound: "No se encontraron artículos",
+        by: "Por",
+        connect: "Conectar"
+      }
+    }
+  }
+};
+e.use(a).use(t).init({
+  resources: s,
+  fallbackLng: "en",
+  lng: "en",
+  // Set 'en' as the initial language synchronously
+  debug: !1,
+  interpolation: {
+    escapeValue: !1
+  },
+  detection: {
+    order: ["path", "localStorage", "navigator"],
+    lookupFromPathIndex: 0
+  }
+});
+export {
+  c as default
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x-wave/blog",
-  "version": "2.2.7",
+  "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/types/index.d.ts

@@ -0,0 +1,31 @@
+export interface NavigationItem {
+    slug: string;
+    hasAdvanced?: boolean;
+}
+export interface NavigationItemWithTitle extends NavigationItem {
+    title: string;
+}
+export interface NavigationSection {
+    title: string;
+    items: NavigationItem[];
+    defaultOpen?: boolean;
+}
+export interface NavigationSectionWithTitles {
+    title: string;
+    items: NavigationItemWithTitle[];
+    defaultOpen?: boolean;
+}
+export type NavigationEntry = NavigationSection | NavigationItem;
+export type NavigationEntryWithTitles = NavigationSectionWithTitles | NavigationItemWithTitle;
+export interface LoadedContent {
+    content: string;
+    frontmatter: {
+        title?: string;
+        hasAdvanced?: boolean;
+        tags?: string[];
+        date?: string;
+        author?: string;
+        [key: string]: unknown;
+    };
+}
+export type SupportedLanguage = string;

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;
+    };
+};

package/consts/index.ts

@@ -1,9 +0,0 @@
-export const DOCS_TITLE = 'Staking Docs'
-
-export const SUPPORTED_LANGUAGES = ['en', 'zh', 'es'] as const
-
-export const GITHUB_REPO_URL = 'https://github.com/polkadot-cloud'
-
-export const STAKING_DASHBOARD_URL = 'https://staking.polkadot.cloud'
-
-export { NAVIGATION_DATA } from './navigation'

package/consts/navigation.ts

@@ -1,26 +0,0 @@
-import type { NavigationEntry } from 'types'
-
-// Navigation structure - defines the sidebar menu order and grouping
-// - Individual item titles are loaded from their MDX frontmatter
-// - Section titles are i18n keys (e.g., 'nav.helpResources') and will be translated
-// Optional properties:
-// - hasAdvanced: boolean - indicates if the page has an advanced version
-// - defaultOpen: boolean - for sections, set to true to have them open by default
-// Note: showTableOfContents is configured in each article's frontmatter, not here
-export const NAVIGATION_DATA: NavigationEntry[] = [
-	{
-		slug: 'welcome',
-	},
-	{
-		title: 'nav.helpResources',
-		defaultOpen: true,
-		items: [
-			{
-				slug: 'glossary',
-			},
-			{
-				slug: 'faq',
-			},
-		],
-	},
-]

package/locales/index.ts

@@ -1,182 +0,0 @@
-import i18n from 'i18next'
-import LanguageDetector from 'i18next-browser-languagedetector'
-import { initReactI18next } from 'react-i18next'
-
-const resources = {
-	en: {
-		translation: {
-			language: 'English',
-			languageCode: 'en',
-			nav: {
-				gettingStarted: 'Getting Started',
-				helpResources: 'Help Resources',
-				guides: 'Guides',
-				reference: 'Reference',
-				previous: 'Previous',
-				next: 'Next',
-			},
-			docs: {
-				helloWorld: 'Welcome!',
-				gettingStarted: 'Getting Started',
-				glossary: 'Glossary',
-				faq: 'FAQ',
-			},
-			ui: {
-				home: 'Home',
-				simple: 'Simple',
-				advanced: 'Advanced',
-				switchLanguage: 'Switch Language',
-				tableOfContents: 'Table of Contents',
-				onThisPage: 'On this page',
-				launchApp: 'Launch App',
-				support: 'Support',
-				discord: 'Discord',
-				email: 'Email',
-				theme: 'Theme',
-				light: 'Light',
-				dark: 'Dark',
-				system: 'System',
-				search: 'Search',
-				searchPlaceholder: 'Search documentation...',
-				searchNavigate: 'to navigate',
-				searchSelect: 'to select',
-				searchClose: 'to close',
-				noSearchResults: 'No results found',
-				tags: 'Tags',
-				filterByTag: 'Filter by tag',
-				tagResults: 'Articles tagged with',
-				noTagResults: 'No articles found with this tag',
-				lastEdited: 'Last edited',
-				axes: 'Articles',
-				latestPosts: 'Latest Posts',
-				loadingArticles: 'Loading articles...',
-				noArticlesFound: 'No articles found',
-				by: 'By',
-				connect: 'Connect',
-			},
-		},
-	},
-	zh: {
-		translation: {
-			language: '中文',
-			languageCode: 'zh',
-			nav: {
-				gettingStarted: '开始使用',
-				helpResources: '帮助资源',
-				guides: '指南',
-				reference: '参考',
-				previous: '上一篇',
-				next: '下一篇',
-			},
-			docs: {
-				helloWorld: '欢迎！',
-				gettingStarted: '开始使用',
-				glossary: '术语表',
-				faq: '常见问题',
-			},
-			ui: {
-				home: '首页',
-				simple: '简单',
-				advanced: '高级',
-				switchLanguage: '切换语言',
-				tableOfContents: '目录',
-				onThisPage: '本页内容',
-				launchApp: '启动应用',
-				support: '支持',
-				discord: 'Discord',
-				email: '电子邮件',
-				theme: '主题',
-				light: '浅色',
-				dark: '深色',
-				system: '系统',
-				search: '搜索',
-				searchPlaceholder: '搜索文档...',
-				searchNavigate: '导航',
-				searchSelect: '选择',
-				searchClose: '关闭',
-				noSearchResults: '未找到结果',
-				tags: '标签',
-				filterByTag: '按标签筛选',
-				tagResults: '带有标签的文章',
-				noTagResults: '未找到带有此标签的文章',
-				lastEdited: '最后编辑',
-				articles: '文章',
-				loadingArticles: '正在加载文章...',
-				noArticlesFound: '未找到文章',
-				by: '作者',
-				connect: '连接',
-			},
-		},
-	},
-	es: {
-		translation: {
-			language: 'Español',
-			languageCode: 'es',
-			nav: {
-				gettingStarted: 'Primeros Pasos',
-				helpResources: 'Recursos de Ayuda',
-				guides: 'Guías',
-				reference: 'Referencia',
-				previous: 'Anterior',
-				next: 'Siguiente',
-			},
-			docs: {
-				helloWorld: '¡Bienvenido!',
-				gettingStarted: 'Primeros Pasos',
-				glossary: 'Glosario',
-				faq: 'Preguntas Frecuentes',
-			},
-			ui: {
-				home: 'Inicio',
-				simple: 'Simple',
-				advanced: 'Avanzado',
-				switchLanguage: 'Cambiar Idioma',
-				tableOfContents: 'Tabla de Contenidos',
-				onThisPage: 'En esta página',
-				launchApp: 'Iniciar App',
-				support: 'Soporte',
-				discord: 'Discord',
-				email: 'Correo',
-				theme: 'Tema',
-				light: 'Claro',
-				dark: 'Oscuro',
-				system: 'Sistema',
-				search: 'Buscar',
-				searchPlaceholder: 'Buscar documentación...',
-				searchNavigate: 'para navegar',
-				searchSelect: 'para seleccionar',
-				searchClose: 'para cerrar',
-				noSearchResults: 'No se encontraron resultados',
-				tags: 'Etiquetas',
-				filterByTag: 'Filtrar por etiqueta',
-				tagResults: 'Artículos etiquetados con',
-				noTagResults: 'No se encontraron artículos con esta etiqueta',
-				lastEdited: 'Última edición',
-				articles: 'Artículos',
-				loadingArticles: 'Cargando artículos...',
-				noArticlesFound: 'No se encontraron artículos',
-				by: 'Por',
-				connect: 'Conectar',
-			},
-		},
-	},
-}
-
-i18n
-	.use(LanguageDetector)
-	.use(initReactI18next)
-	.init({
-		resources,
-		fallbackLng: 'en',
-		lng: 'en', // Set 'en' as the initial language synchronously
-		debug: false,
-		interpolation: {
-			escapeValue: false,
-		},
-		detection: {
-			order: ['path', 'localStorage', 'navigator'],
-			lookupFromPathIndex: 0,
-		},
-	})
-
-export default i18n

package/types/index.ts

@@ -1,40 +0,0 @@
-export interface NavigationItem {
-	slug: string
-	hasAdvanced?: boolean
-}
-
-export interface NavigationItemWithTitle extends NavigationItem {
-	title: string
-}
-
-export interface NavigationSection {
-	title: string
-	items: NavigationItem[]
-	defaultOpen?: boolean
-}
-
-export interface NavigationSectionWithTitles {
-	title: string
-	items: NavigationItemWithTitle[]
-	defaultOpen?: boolean
-}
-
-export type NavigationEntry = NavigationSection | NavigationItem
-
-export type NavigationEntryWithTitles =
-	| NavigationSectionWithTitles
-	| NavigationItemWithTitle
-
-export interface LoadedContent {
-	content: string
-	frontmatter: {
-		title?: string
-		hasAdvanced?: boolean
-		tags?: string[]
-		date?: string
-		author?: string
-		[key: string]: unknown
-	}
-}
-
-export type SupportedLanguage = string