@windrun-huaiin/third-ui 23.0.0 → 23.1.1

package/README.md

@@ -1,222 +1,185 @@
 # @windrun-huaiin/third-ui
 
-Third-party integrated UI components library, including Clerk authentication, Fumadocs documentation, and main application components.
+This README currently documents only the Fuma/MDX component design in `third-ui`.
 
-## Installation
+Other modules in this package, such as Clerk, main application UI, AI UI, fingerprint, SEO helpers, and shared layout utilities, are intentionally not covered here.
 
-```bash
-pnpm add @windrun-huaiin/third-ui
+## MDX Component Layer
+
+The Fuma/MDX part of `third-ui` provides the rendering component map used by application MDX pages.
+
+It is not responsible for reading files or compiling MDX. That belongs to `@windrun-huaiin/fumadocs-local-md`.
+
+The split is:
+
+- `local-md`: content source, frontmatter/meta parsing, Markdown/MDX compilation, render execution safety.
+- `third-ui`: React components used when MDX is rendered.
+- application: chooses which compiler features and renderer features are imported.
+
+## Design Goals
+
+- Keep the base MDX component map useful but small.
+- Make heavyweight rendering features explicit imports.
+- Avoid old aggregate component entries that import every renderer feature at module load time.
+- Let application code be the capability declaration.
+- Preserve a safe fallback path when disabled or unknown MDX components appear in content.
+- Keep renderer-only capabilities separate from compiler-only capabilities.
+
+## Current Entry Model
+
+New applications should use the base site MDX entry:
+
+```ts
+@windrun-huaiin/third-ui/fuma/server/site-mdx/base
 ```
 
-## TailwindCSS 4.x Config
-
-- Assume you have a project structure like this:
-
-```txt
-Your-project/
-├── src/
-│   └── app/
-│       └── globals.css
-├── node_modules/
-│   ├── @windrun-huaiin/
-│   │   ├── third-ui/
-│   │   │   └── src/        # This is third-ui src
-│   │   └── base-ui/
-│   │       └── src/        # This is base-ui src
-└── package.json
+Optional renderer features live behind physical subpath entries:
+
+```ts
+@windrun-huaiin/third-ui/fuma/server/site-mdx/features/code
+@windrun-huaiin/third-ui/fuma/server/site-mdx/features/math
+@windrun-huaiin/third-ui/fuma/server/site-mdx/features/mermaid
+@windrun-huaiin/third-ui/fuma/server/site-mdx/features/type-table
 ```
 
-- Then, in your `globals.css` file, you have to configure Tailwind CSS 4.x like this:
+The old aggregate entries have been removed. There is no supported `site-mdx-components` entry and no `optional-features` aggregate entry.
 
-```css
-@import 'tailwindcss';
+## Base Components
 
-@source "../node_modules/@windrun-huaiin/third-ui/src/**/*.{js,ts,jsx,tsx}";
-@source "../node_modules/@windrun-huaiin/base-ui/src/**/*.{js,ts,jsx,tsx}";
-@source "./src/**/*.{js,ts,jsx,tsx}";
+The base entry is the minimum component set for normal documentation content.
 
-/* Import styles */
-@import '@windrun-huaiin/third-ui/styles/third-ui.css';
-```
+It includes:
 
+- Fuma UI basics: `Card`, `Cards`, `Callout`, `File`, `Folder`, `Files`, `Accordion`, `Accordions`, `Tab`, `Tabs`.
+- Markdown element renderers: headings, links, blockquote, lists, table, inline code, pre, image, and related primitive tags.
+- Site-level lightweight components: `SiteX`, `TrophyCard`, `ZiaCard`, `GradientButton`, `ZiaFile`, `ZiaFolder`, `SunoEmbed`.
+- Image rendering integration with image fallback and CDN-related options.
+- Feature-specific fallback components for disabled math, Mermaid, type table, and code-tab style components.
 
-## Usage Example
+It intentionally does not include heavyweight renderer implementations such as Mermaid, KaTeX rendering, Fuma codeblock rendering, or type-table rendering.
 
-Root entry import is not supported. Always import from an explicit subpath such as `@windrun-huaiin/third-ui/clerk` or `@windrun-huaiin/third-ui/main`.
+## Renderer Feature Matrix
 
-### Import components by module
-```tsx
-// Only import Clerk related components
-import { ClerkUser, ClerkOrganization } from '@windrun-huaiin/third-ui/clerk';
+| Capability | Renderer Entry | Compiler Entry Required | Notes |
+| --- | --- | --- | --- |
+| `base` | `site-mdx/base` | `local-md/presets/fuma-docs/base` | Required for normal MDX rendering |
+| `code` | `site-mdx/features/code` | `local-md/presets/fuma-docs/features/code` | Enables Fuma codeblock UI and built-in language icon mapping |
+| `math` | `site-mdx/features/math` | `local-md/presets/fuma-docs/features/math` | Enables `MathBlock` and `InlineMath` rendering |
+| `mermaid` | `site-mdx/features/mermaid` | Not required | Renderer-only component capability |
+| `type-table` | `site-mdx/features/type-table` | Not required | Renderer-only component capability |
+| `npm` | Not required | `local-md/presets/fuma-docs/features/npm` | Compiler-only content transform |
 
-// Only import main application components
-import { CTA, Features } from '@windrun-huaiin/third-ui/main';
+This table is the main rule for application integration.
 
-// Only import Fumadocs components  
-import { FumaPageGenerator, FumaBannerSuit } from '@windrun-huaiin/third-ui/fuma/server';
+`code` and `math` need both compiler and renderer support. `npm` is compiler-only. `mermaid` and `type-table` are renderer-only.
 
-// Shared MDX building blocks
-import { TocFooterWrapper, PortableClerkTOC } from '@windrun-huaiin/third-ui/fuma/mdx';
-```
+## Bundle Cropping Rule
 
-### Use components
-```tsx
-// Clerk user component (need to pass in translations and configuration)
-<ClerkUser 
-  locale="zh"
-  clerkAuthInModal={true}
-  t={{ signIn: "Sign in" }}
-  t2={{ terms: "Terms of Service", privacy: "Privacy Policy" }}
-/>
-
-// Clerk organization component
-<ClerkOrganization locale="zh" className="custom-class" />
-
-// Main application components
-<CTA />
-<Features />
-```
+Renderer pruning is based on import boundaries.
 
-## Design Principles
-
-1. **Modularization**: Grouped by functional domain, support import on demand
-2. **Parameterization**: Remove hard-coded dependencies, pass configuration through props
-3. **Type safety**: Full TypeScript support
-4. **Path alias**: Use `@/` alias internally, keep code clean
-
-## Dependencies
-
-- `@windrun-huaiin/base-ui`: Base UI components
-- `@windrun-huaiin/lib`: General utility library
-- `@clerk/nextjs`: Clerk authentication
-- `fumadocs-core`, `fumadocs-ui`: Fumadocs documentation
-
-## Notes
-
-- Components have removed direct `appConfig` dependencies, and configuration is passed through props
-- Clerk components need to provide correct translations in the application layer
-- Some components may require specific CSS animation classes (e.g. `animate-cta-gradient-wave`) 
-
-## Component List
-
-### Clerk module
-- `ClerkProviderClient` - Clerk authentication provider
-- `ClerkUser` - User button component  
-- `ClerkOrganization` - Organization switcher component
-
-### Main module
-- `CTA` - Call-to-Action component
-- `Features` - Feature showcase component
-- `Footer` - Footer component
-- `Gallery` - Image gallery component
-- `GoToTop` - Go to top button
-- `SEOContent` - SEO content component
-- `Tips` - Tip component
-
-### Fuma module
-- `getMDXComponents` - MDX component configuration function
-- `createMDXComponents` - MDX component factory function
-- `TocFooter` - Table of contents footer component
-- `FumaBannerSuit` - Fumadocs banner component
-
-### Fuma MDX submodule
-- `Mermaid` - Flowchart component
-- `ImageZoom` - Image zoom component
-- `TrophyCard` - Trophy card component
-- `ImageGrid` - Image grid component
-- `ZiaCard` - Zia card component
-- `GradientButton` - Gradient button component 
-
-## Usage
-
-### Clerk components
-
-```tsx
-import { ClerkProviderClient, ClerkUser } from '@windrun-huaiin/third-ui/clerk';
-
-// Use in layout.tsx
-<ClerkProviderClient 
-  signInUrl="/sign-in"
-  signUpUrl="/sign-up"
-  waitlistUrl="/waitlist"
->
-  {children}
-</ClerkProviderClient>
-
-// Use in navigation bar
-<ClerkUser clerkAuthInModal={true} />
-```
+If an application does not import `site-mdx/features/mermaid`, Mermaid renderer code should not be pulled into the base renderer entry. The same rule applies to code, math, and type-table renderer features.
 
-### Main components
+Do not reintroduce a file that imports all renderer features and then chooses one at runtime. That pattern defeats bundle cropping because static imports run before configuration checks.
 
-```tsx
-import { CTA, Features, Footer } from '@windrun-huaiin/third-ui/main';
+Correct model:
 
-// Use various page components
-<Features />
-<CTA />
-<Footer />
-```
+- base entry imports only base renderers and lightweight fallback components.
+- each optional feature entry imports only its own renderer implementation.
+- application code imports the feature entries it wants.
 
-### Fumadocs components
-
-```tsx
-import { createMDXComponents, TocFooter } from '@windrun-huaiin/third-ui/fuma';
-
-// Create pre-configured MDX components
-const getMDXComponents = createMDXComponents({
-  watermark: {
-    enabled: true,
-    text: "Your Watermark"
-  },
-  githubBaseUrl: "https://github.com/your-org/your-repo/edit/main/"
-});
-
-// Use in page
-const MDX = page.data.body;
-<MDX components={getMDXComponents()} />
-
-// Use TocFooter
-<TocFooter 
-  lastModified={page.data.date}
-  showCopy={true}
-  editPath="src/docs/your-file.mdx"
-  githubBaseUrl="https://github.com/your-org/your-repo/edit/main/"
-/>
-```
+## Fallback Design
+
+There are two fallback layers.
+
+The first layer lives in `third-ui`.
+
+It provides feature-aware fallbacks for known but disabled MDX capabilities:
+
+- `MathBlock`
+- `InlineMath`
+- `Mermaid`
+- `TypeTable`
+- `CodeBlockTab`
+- `CodeBlockTabs`
+- `CodeBlockTabsList`
+- `CodeBlockTabsTrigger`
+
+These fallbacks render visible warning blocks instead of silently dropping content.
 
-#### MDX components global configuration
+The second layer lives in `local-md`.
 
-In MDX file:
+It is the final safety net for arbitrary unknown PascalCase components, such as:
 
 ```mdx
-<!-- Mermaid chart, watermark automatically applied -->
-<Mermaid
-  chart="graph TD; A-->B"
-  title="My Diagram"
-/>
-
-<!-- Image grid, CDN URL automatically applied -->
-<ImageGrid
-  type="url"
-  images={["image1.webp", "image2.webp"]}
-  altPrefix="example"
-/>
-
-<!-- Image zoom, placeholder image automatically applied -->
-<ImageZoom src="/some-image.jpg" alt="Example" />
+<CalloutXXX />
 ```
 
-All configuration parameters will be automatically obtained from the global configuration, and no need to specify them in each use.
+`local-md` detects missing component references from the compiled MDX output and injects generic fallback components before rendering. This prevents unknown MDX components from crashing the page.
+
+The priority order is:
+
+- application-provided MDX components
+- enabled `third-ui` renderer feature components
+- `third-ui` known disabled-feature fallbacks
+- `local-md` generic unknown-component fallback
+
+## Heavy Renderer Boundary
+
+Heavy renderers are isolated under dedicated feature paths or heavy modules.
+
+Examples:
+
+- Mermaid rendering is behind the Mermaid feature entry.
+- Math rendering uses the math feature entry and lazy heavy math renderer.
+- Type table rendering is behind the type-table feature entry.
+- Fuma codeblock rendering is behind the code feature entry.
+
+The code renderer owns its programming-language icon map internally. Applications should not pass a global icon map into `createCodeMdxComponents()`.
+
+This keeps `site-mdx/base` from becoming a hidden dependency sink.
+
+## Application Rules
+
+Applications should treat their MDX integration files as the capability declaration.
+
+For `apps/ddaas`, the important files are:
+
+- `src/lib/content-source.ts`: compiler/source capabilities.
+- `src/components/mdx-components.tsx`: renderer/component capabilities.
+
+When enabling a capability:
+
+- import the compiler feature only if the capability needs compiler support.
+- import the renderer feature only if the capability needs renderer support.
+- add the imported feature to the matching `features` list.
+- do not import unused feature entries “just in case”.
+
+If an application creates its own MDX component and that component imports a heavy package directly, the package can still enter the bundle. That is expected and belongs to the application layer.
+
+## Styling
+
+MDX components assume the application includes the package styles and Tailwind source scanning for `third-ui`.
+
+The exact global CSS setup is application-specific, but MDX pages need the same base styles used by the rest of the Fuma UI integration.
+
+## Export Map
+
+MDX-related exports currently relevant to this design:
 
+| Export | Purpose |
+| --- | --- |
+| `./fuma/server/site-mdx/base` | Recommended base MDX component factory |
+| `./fuma/server/site-mdx/features/code` | Optional code renderer components |
+| `./fuma/server/site-mdx/features/math` | Optional math renderer components |
+| `./fuma/server/site-mdx/features/mermaid` | Optional Mermaid renderer components |
+| `./fuma/server/site-mdx/features/type-table` | Optional type-table renderer components |
+| `./fuma/mdx` | Shared MDX building blocks used by pages and widgets |
+| `./fuma/heavy` | Heavy renderer exports; avoid importing from app base paths unless intentionally needed |
+| `./fuma/share` | Shared markdown component utilities |
 
-## Showcase
+## Non-Goals
 
-- [Free Trivia Game](https://freetrivia.info/)
-- [Music Poster](https://musicposter.org/en)
-- [Image Narration](https://imagenarration.com/en)
-- [Describe Yourself](https://describeyourself.org/en)
-- [Newspaper Template](https://newspaper-template.org/en)
-- [breathing exercise](https://breathingexercise.net/en)
-- [ai directory list](https://aidirectorylist.com/en)
-- [reve image directory](https://reveimage.directory/en)
+- This README does not document Clerk, main UI, AI UI, fingerprint, or SEO helpers.
+- The base MDX entry should not become an all-features preset.
+- Runtime feature flags should not be used as the primary pruning mechanism.
+- Unknown MDX components should not crash the page.

package/dist/fuma/fuma-page-genarator.d.ts

@@ -1,5 +1,6 @@
 import { ReactNode, ReactElement } from 'react';
 import type { LLMCopyButtonProps, LLMCopyButton } from '@third-ui/fuma/mdx/toc-base';
+export type FumaPageTocRenderMode = 'portable-clerk' | 'fumadocs-clerk' | 'fumadocs-normal';
 interface FumaPageParams {
     sourceKey: string;
     mdxContentSource: any | (() => Promise<any>);
@@ -14,11 +15,12 @@ interface FumaPageParams {
     supportedLocales?: string[];
     showBreadcrumb?: boolean;
     showTableOfContent?: boolean;
+    tocRenderMode?: FumaPageTocRenderMode;
     showTableOfContentPopover?: boolean;
     localePrefixAsNeeded?: boolean;
     defaultLocale?: string;
 }
-export declare function createFumaPage({ sourceKey, mdxContentSource, getMDXComponents, mdxSourceDir, githubBaseUrl, copyButtonComponent, siteIcon, FallbackPage, supportedLocales, showBreadcrumb, showTableOfContent, showTableOfContentPopover, localePrefixAsNeeded, defaultLocale, }: FumaPageParams): {
+export declare function createFumaPage({ sourceKey, mdxContentSource, getMDXComponents, mdxSourceDir, githubBaseUrl, copyButtonComponent, siteIcon, FallbackPage, supportedLocales, showBreadcrumb, showTableOfContent, tocRenderMode, showTableOfContentPopover, localePrefixAsNeeded, defaultLocale, }: FumaPageParams): {
     Page: ({ params }: {
         params: Promise<{
             locale: string;

package/dist/fuma/fuma-page-genarator.js

@@ -7,8 +7,9 @@ var React = require('react');
 var tocFooterWrapper = require('./mdx/toc-footer-wrapper.js');
 var lib = require('@windrun-huaiin/lib');
 var tocClerkPortable = require('./mdx/toc-clerk-portable.js');
+var lib$1 = require('@windrun-huaiin/base-ui/lib');
 
-function createFumaPage({ sourceKey, mdxContentSource, getMDXComponents, mdxSourceDir, githubBaseUrl, copyButtonComponent, siteIcon, FallbackPage, supportedLocales = ['en'], showBreadcrumb = true, showTableOfContent = true, showTableOfContentPopover = false, localePrefixAsNeeded = true, defaultLocale = 'en', }) {
+function createFumaPage({ sourceKey, mdxContentSource, getMDXComponents, mdxSourceDir, githubBaseUrl, copyButtonComponent, siteIcon, FallbackPage, supportedLocales = ['en'], showBreadcrumb = true, showTableOfContent = true, tocRenderMode = 'portable-clerk', showTableOfContentPopover = false, localePrefixAsNeeded = true, defaultLocale = 'en', }) {
     const getSource = () => tslib.__awaiter(this, void 0, void 0, function* () {
         if (typeof mdxContentSource === 'function') {
             return yield mdxContentSource();
@@ -35,12 +36,14 @@ function createFumaPage({ sourceKey, mdxContentSource, getMDXComponents, mdxSour
                     body: yield page$1.data.body({ components: getMDXComponents() }),
                     toc: (_e = page$1.data.toc) !== null && _e !== void 0 ? _e : [],
                 };
-            return (jsxRuntime.jsxs(page.DocsPage, { breadcrumb: { enabled: showBreadcrumb }, tableOfContent: {
+            return (jsxRuntime.jsxs(page.DocsPage, { breadcrumb: { enabled: showBreadcrumb }, tableOfContent: resolveTableOfContentOptions({
                     enabled: showTableOfContent,
-                    single: false,
-                    component: (jsxRuntime.jsx(tocClerkPortable.PortableClerkTOC, { toc: content.toc, footer: tocFooterElement })),
-                }, tableOfContentPopover: {
-                    enabled: false,
+                    tocRenderMode,
+                    toc: content.toc,
+                    footer: tocFooterElement,
+                }), tableOfContentPopover: {
+                    enabled: showTableOfContentPopover && tocRenderMode !== 'portable-clerk',
+                    style: tocRenderMode === 'fumadocs-clerk' ? 'clerk' : 'normal',
                 }, toc: content.toc, className: "max-sm:pb-16", children: [jsxRuntime.jsx(page.DocsTitle, { children: page$1.data.title }), jsxRuntime.jsx(page.DocsDescription, { className: "mb-2", children: page$1.data.description }), jsxRuntime.jsx(page.DocsBody, { className: "text-fd-foreground/80", children: content.body })] }));
         });
     };
@@ -87,5 +90,29 @@ function createFumaPage({ sourceKey, mdxContentSource, getMDXComponents, mdxSour
         generateMetadata,
     };
 }
+function resolveTableOfContentOptions({ enabled, tocRenderMode, toc, footer, }) {
+    if (tocRenderMode === 'portable-clerk') {
+        return {
+            enabled,
+            single: false,
+            component: (jsxRuntime.jsx(tocClerkPortable.PortableClerkTOC, { toc: toc, footer: footer })),
+        };
+    }
+    const themedTocProps = {
+        container: {
+            className: '[--color-fd-primary:var(--third-ui-toc-primary)] [--color-fd-primary-foreground:var(--third-ui-toc-primary-foreground)] [&_#toc-title]:hidden',
+            style: {
+                '--third-ui-toc-primary': lib$1.themeSvgIconColor,
+                '--third-ui-toc-primary-foreground': '#ffffff',
+            },
+        },
+        header: jsxRuntime.jsx(tocClerkPortable.PortableClerkTOCTitle, {}),
+        footer,
+    };
+    if (tocRenderMode === 'fumadocs-clerk') {
+        return Object.assign({ enabled, single: false, style: 'clerk' }, themedTocProps);
+    }
+    return Object.assign({ enabled, single: false, style: 'normal' }, themedTocProps);
+}
 
 exports.createFumaPage = createFumaPage;

package/dist/fuma/fuma-page-genarator.mjs

@@ -4,9 +4,10 @@ import { DocsPage, DocsTitle, DocsDescription, DocsBody } from 'fumadocs-ui/page
 import { cloneElement } from 'react';
 import { TocFooterWrapper } from './mdx/toc-footer-wrapper.mjs';
 import { getAsNeededLocalizedUrl } from '@windrun-huaiin/lib';
-import { PortableClerkTOC } from './mdx/toc-clerk-portable.mjs';
+import { PortableClerkTOC, PortableClerkTOCTitle } from './mdx/toc-clerk-portable.mjs';
+import { themeSvgIconColor } from '@windrun-huaiin/base-ui/lib';
 
-function createFumaPage({ sourceKey, mdxContentSource, getMDXComponents, mdxSourceDir, githubBaseUrl, copyButtonComponent, siteIcon, FallbackPage, supportedLocales = ['en'], showBreadcrumb = true, showTableOfContent = true, showTableOfContentPopover = false, localePrefixAsNeeded = true, defaultLocale = 'en', }) {
+function createFumaPage({ sourceKey, mdxContentSource, getMDXComponents, mdxSourceDir, githubBaseUrl, copyButtonComponent, siteIcon, FallbackPage, supportedLocales = ['en'], showBreadcrumb = true, showTableOfContent = true, tocRenderMode = 'portable-clerk', showTableOfContentPopover = false, localePrefixAsNeeded = true, defaultLocale = 'en', }) {
     const getSource = () => __awaiter(this, void 0, void 0, function* () {
         if (typeof mdxContentSource === 'function') {
             return yield mdxContentSource();
@@ -33,12 +34,14 @@ function createFumaPage({ sourceKey, mdxContentSource, getMDXComponents, mdxSour
                     body: yield page.data.body({ components: getMDXComponents() }),
                     toc: (_e = page.data.toc) !== null && _e !== void 0 ? _e : [],
                 };
-            return (jsxs(DocsPage, { breadcrumb: { enabled: showBreadcrumb }, tableOfContent: {
+            return (jsxs(DocsPage, { breadcrumb: { enabled: showBreadcrumb }, tableOfContent: resolveTableOfContentOptions({
                     enabled: showTableOfContent,
-                    single: false,
-                    component: (jsx(PortableClerkTOC, { toc: content.toc, footer: tocFooterElement })),
-                }, tableOfContentPopover: {
-                    enabled: false,
+                    tocRenderMode,
+                    toc: content.toc,
+                    footer: tocFooterElement,
+                }), tableOfContentPopover: {
+                    enabled: showTableOfContentPopover && tocRenderMode !== 'portable-clerk',
+                    style: tocRenderMode === 'fumadocs-clerk' ? 'clerk' : 'normal',
                 }, toc: content.toc, className: "max-sm:pb-16", children: [jsx(DocsTitle, { children: page.data.title }), jsx(DocsDescription, { className: "mb-2", children: page.data.description }), jsx(DocsBody, { className: "text-fd-foreground/80", children: content.body })] }));
         });
     };
@@ -85,5 +88,29 @@ function createFumaPage({ sourceKey, mdxContentSource, getMDXComponents, mdxSour
         generateMetadata,
     };
 }
+function resolveTableOfContentOptions({ enabled, tocRenderMode, toc, footer, }) {
+    if (tocRenderMode === 'portable-clerk') {
+        return {
+            enabled,
+            single: false,
+            component: (jsx(PortableClerkTOC, { toc: toc, footer: footer })),
+        };
+    }
+    const themedTocProps = {
+        container: {
+            className: '[--color-fd-primary:var(--third-ui-toc-primary)] [--color-fd-primary-foreground:var(--third-ui-toc-primary-foreground)] [&_#toc-title]:hidden',
+            style: {
+                '--third-ui-toc-primary': themeSvgIconColor,
+                '--third-ui-toc-primary-foreground': '#ffffff',
+            },
+        },
+        header: jsx(PortableClerkTOCTitle, {}),
+        footer,
+    };
+    if (tocRenderMode === 'fumadocs-clerk') {
+        return Object.assign({ enabled, single: false, style: 'clerk' }, themedTocProps);
+    }
+    return Object.assign({ enabled, single: false, style: 'normal' }, themedTocProps);
+}
 
 export { createFumaPage };

package/dist/fuma/mdx/index.js

@@ -28,5 +28,6 @@ exports.PortableClerkTOC = tocClerkPortable.PortableClerkTOC;
 exports.PortableClerkTOCItems = tocClerkPortable.PortableClerkTOCItems;
 exports.PortableClerkTOCPopover = tocClerkPortable.PortableClerkTOCPopover;
 exports.PortableClerkTOCScrollArea = tocClerkPortable.PortableClerkTOCScrollArea;
+exports.PortableClerkTOCTitle = tocClerkPortable.PortableClerkTOCTitle;
 exports.Banner = banner.Banner;
 exports.SunoEmbed = sunoEmbed.SunoEmbed;

package/dist/fuma/mdx/index.mjs

@@ -6,6 +6,6 @@ export { EditOnGitHub, LLMCopyButton, LastUpdatedDate } from './toc-base.mjs';
 export { FumaGithubInfo } from './fuma-github-info.mjs';
 export { ZiaFile, ZiaFolder } from './zia-file.mjs';
 export { TocFooterWrapper } from './toc-footer-wrapper.mjs';
-export { PortableClerkTOC, PortableClerkTOCItems, PortableClerkTOCPopover, PortableClerkTOCScrollArea } from './toc-clerk-portable.mjs';
+export { PortableClerkTOC, PortableClerkTOCItems, PortableClerkTOCPopover, PortableClerkTOCScrollArea, PortableClerkTOCTitle } from './toc-clerk-portable.mjs';
 export { Banner } from './banner.mjs';
 export { SunoEmbed } from './suno-embed.mjs';

package/dist/fuma/mdx/toc-clerk-portable.d.ts

@@ -15,6 +15,7 @@ type PortableClerkTOCProps = {
 };
 export declare function PortableClerkTOC({ toc, header, footer, title, emptyLabel, className, }: PortableClerkTOCProps): import("react/jsx-runtime").JSX.Element;
 export declare function PortableClerkTOCPopover({ toc, header, footer, emptyLabel, }: Omit<PortableClerkTOCProps, 'title' | 'className'>): import("react/jsx-runtime").JSX.Element;
+export declare function PortableClerkTOCTitle({ className, ...props }: ComponentProps<'h3'>): import("react/jsx-runtime").JSX.Element;
 export declare function PortableClerkTOCScrollArea({ ref, className, ...props }: ComponentProps<'div'>): import("react/jsx-runtime").JSX.Element;
 export declare function PortableClerkTOCItems({ toc, emptyLabel, ref, className, ...props }: ComponentProps<'div'> & {
     toc: TOCItemType[];

package/dist/fuma/mdx/toc-clerk-portable.js

@@ -4,9 +4,11 @@
 var tslib = require('tslib');
 var jsxRuntime = require('react/jsx-runtime');
 var Primitive = require('fumadocs-core/toc');
-var toc = require('fumadocs-ui/layouts/docs/page/slots/toc');
+var i18n = require('fumadocs-ui/contexts/i18n');
+var collapsible = require('fumadocs-ui/components/ui/collapsible');
 var React = require('react');
 var lib = require('@windrun-huaiin/base-ui/lib');
+var icons = require('@windrun-huaiin/base-ui/icons');
 
 function _interopNamespaceDefault(e) {
     var n = Object.create(null);
@@ -49,15 +51,15 @@ const CLERK_STEP_BADGE_RADIUS = 7;
 const CLERK_DEPTH_GROUP_LINE_OFFSETS = [6, 18, 30, 42];
 // Max number of characters rendered for a TOC label before trimming with ellipsis.
 const CLERK_MAX_LABEL_LENGTH = 44;
-function PortableClerkTOC({ toc: toc$1, header, footer, title, emptyLabel = 'No headings', className, }) {
-    return (jsxRuntime.jsx(toc.TOC, { style: "clerk", container: { className }, header: jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [header, title !== null && title !== void 0 ? title : null] }), footer: footer, list: {
-            children: jsxRuntime.jsx(PortableClerkTOCItems, { toc: toc$1, emptyLabel: emptyLabel }),
-        } }));
+function PortableClerkTOC({ toc, header, footer, title, emptyLabel = 'No headings', className, }) {
+    return (jsxRuntime.jsxs("div", { id: "nd-toc", className: cn('sticky top-(--fd-docs-row-1) h-[calc(var(--fd-docs-height)-var(--fd-docs-row-1))] flex flex-col [grid-area:toc] w-(--fd-toc-width) pt-12 pe-4 pb-2 max-xl:hidden', className), children: [header, title !== null && title !== void 0 ? title : jsxRuntime.jsx(PortableClerkTOCTitle, {}), jsxRuntime.jsx(PortableClerkTOCScrollArea, { children: jsxRuntime.jsx(PortableClerkTOCItems, { toc: toc, emptyLabel: emptyLabel }) }), footer] }));
 }
-function PortableClerkTOCPopover({ toc: toc$1, header, footer, emptyLabel = 'No headings', }) {
-    return (jsxRuntime.jsx(toc.TOCPopover, { style: "clerk", header: header, footer: footer, list: {
-            children: jsxRuntime.jsx(PortableClerkTOCItems, { toc: toc$1, emptyLabel: emptyLabel }),
-        } }));
+function PortableClerkTOCPopover({ toc, header, footer, emptyLabel = 'No headings', }) {
+    return (jsxRuntime.jsx(collapsible.Collapsible, { "data-toc-popover": "", className: "sticky top-(--fd-docs-row-2) z-10 [grid-area:toc-popover] h-(--fd-toc-popover-height) xl:hidden max-xl:layout:[--fd-toc-popover-height:--spacing(10)]", children: jsxRuntime.jsxs("header", { className: "border-b bg-fd-background/80 backdrop-blur-sm transition-colors", children: [jsxRuntime.jsxs(collapsible.CollapsibleTrigger, { "data-toc-popover-trigger": "", className: "flex w-full h-10 items-center text-sm text-fd-muted-foreground gap-2.5 px-4 py-2.5 text-start focus-visible:outline-none [&_svg]:size-4 md:px-6", children: [jsxRuntime.jsx(icons.NotepadTextIcon, { className: "shrink-0" }), jsxRuntime.jsx("span", { className: "flex-1 truncate", children: jsxRuntime.jsx(i18n.I18nLabel, { label: "toc" }) }), jsxRuntime.jsx(icons.ChevronDownIcon, { className: "shrink-0 transition-transform mx-0.5" })] }), jsxRuntime.jsx(collapsible.CollapsibleContent, { "data-toc-popover-content": "", children: jsxRuntime.jsxs("div", { className: "flex max-h-[50vh] flex-col px-4 md:px-6", children: [header, jsxRuntime.jsx(PortableClerkTOCScrollArea, { children: jsxRuntime.jsx(PortableClerkTOCItems, { toc: toc, emptyLabel: emptyLabel }) }), footer] }) })] }) }));
+}
+function PortableClerkTOCTitle(_a) {
+    var { className } = _a, props = tslib.__rest(_a, ["className"]);
+    return (jsxRuntime.jsxs("h3", Object.assign({ id: "toc-title", className: cn('inline-flex items-center gap-1.5 text-sm text-fd-muted-foreground', className) }, props, { children: [jsxRuntime.jsx(icons.NotepadTextIcon, { className: cn('size-4', lib.themeIconColor) }), jsxRuntime.jsx(i18n.I18nLabel, { label: "toc" })] })));
 }
 function PortableClerkTOCScrollArea(_a) {
     var { ref, className } = _a, props = tslib.__rest(_a, ["ref", "className"]);
@@ -390,3 +392,4 @@ exports.PortableClerkTOC = PortableClerkTOC;
 exports.PortableClerkTOCItems = PortableClerkTOCItems;
 exports.PortableClerkTOCPopover = PortableClerkTOCPopover;
 exports.PortableClerkTOCScrollArea = PortableClerkTOCScrollArea;
+exports.PortableClerkTOCTitle = PortableClerkTOCTitle;

package/dist/fuma/mdx/toc-clerk-portable.mjs

@@ -1,10 +1,12 @@
 "use client";
 import { __rest } from 'tslib';
-import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
+import { jsxs, jsx, Fragment } from 'react/jsx-runtime';
 import * as Primitive from 'fumadocs-core/toc';
-import { TOC, TOCPopover } from 'fumadocs-ui/layouts/docs/page/slots/toc';
+import { I18nLabel } from 'fumadocs-ui/contexts/i18n';
+import { Collapsible, CollapsibleTrigger, CollapsibleContent } from 'fumadocs-ui/components/ui/collapsible';
 import { useRef, useState, useMemo, useLayoutEffect, useEffect } from 'react';
 import { themeSvgIconColor, themeIconColor } from '@windrun-huaiin/base-ui/lib';
+import { NotepadTextIcon, ChevronDownIcon } from '@windrun-huaiin/base-ui/icons';
 
 // Base stroke width for both the inactive rail and the active highlight path.
 const CLERK_PATH_STROKE_WIDTH = 1;
@@ -29,14 +31,14 @@ const CLERK_DEPTH_GROUP_LINE_OFFSETS = [6, 18, 30, 42];
 // Max number of characters rendered for a TOC label before trimming with ellipsis.
 const CLERK_MAX_LABEL_LENGTH = 44;
 function PortableClerkTOC({ toc, header, footer, title, emptyLabel = 'No headings', className, }) {
-    return (jsx(TOC, { style: "clerk", container: { className }, header: jsxs(Fragment, { children: [header, title !== null && title !== void 0 ? title : null] }), footer: footer, list: {
-            children: jsx(PortableClerkTOCItems, { toc: toc, emptyLabel: emptyLabel }),
-        } }));
+    return (jsxs("div", { id: "nd-toc", className: cn('sticky top-(--fd-docs-row-1) h-[calc(var(--fd-docs-height)-var(--fd-docs-row-1))] flex flex-col [grid-area:toc] w-(--fd-toc-width) pt-12 pe-4 pb-2 max-xl:hidden', className), children: [header, title !== null && title !== void 0 ? title : jsx(PortableClerkTOCTitle, {}), jsx(PortableClerkTOCScrollArea, { children: jsx(PortableClerkTOCItems, { toc: toc, emptyLabel: emptyLabel }) }), footer] }));
 }
 function PortableClerkTOCPopover({ toc, header, footer, emptyLabel = 'No headings', }) {
-    return (jsx(TOCPopover, { style: "clerk", header: header, footer: footer, list: {
-            children: jsx(PortableClerkTOCItems, { toc: toc, emptyLabel: emptyLabel }),
-        } }));
+    return (jsx(Collapsible, { "data-toc-popover": "", className: "sticky top-(--fd-docs-row-2) z-10 [grid-area:toc-popover] h-(--fd-toc-popover-height) xl:hidden max-xl:layout:[--fd-toc-popover-height:--spacing(10)]", children: jsxs("header", { className: "border-b bg-fd-background/80 backdrop-blur-sm transition-colors", children: [jsxs(CollapsibleTrigger, { "data-toc-popover-trigger": "", className: "flex w-full h-10 items-center text-sm text-fd-muted-foreground gap-2.5 px-4 py-2.5 text-start focus-visible:outline-none [&_svg]:size-4 md:px-6", children: [jsx(NotepadTextIcon, { className: "shrink-0" }), jsx("span", { className: "flex-1 truncate", children: jsx(I18nLabel, { label: "toc" }) }), jsx(ChevronDownIcon, { className: "shrink-0 transition-transform mx-0.5" })] }), jsx(CollapsibleContent, { "data-toc-popover-content": "", children: jsxs("div", { className: "flex max-h-[50vh] flex-col px-4 md:px-6", children: [header, jsx(PortableClerkTOCScrollArea, { children: jsx(PortableClerkTOCItems, { toc: toc, emptyLabel: emptyLabel }) }), footer] }) })] }) }));
+}
+function PortableClerkTOCTitle(_a) {
+    var { className } = _a, props = __rest(_a, ["className"]);
+    return (jsxs("h3", Object.assign({ id: "toc-title", className: cn('inline-flex items-center gap-1.5 text-sm text-fd-muted-foreground', className) }, props, { children: [jsx(NotepadTextIcon, { className: cn('size-4', themeIconColor) }), jsx(I18nLabel, { label: "toc" })] })));
 }
 function PortableClerkTOCScrollArea(_a) {
     var { ref, className } = _a, props = __rest(_a, ["ref", "className"]);
@@ -365,4 +367,4 @@ function mergeRefs(...refs) {
     };
 }
 
-export { PortableClerkTOC, PortableClerkTOCItems, PortableClerkTOCPopover, PortableClerkTOCScrollArea };
+export { PortableClerkTOC, PortableClerkTOCItems, PortableClerkTOCPopover, PortableClerkTOCScrollArea, PortableClerkTOCTitle };

package/dist/fuma/server/features/code.d.ts

@@ -1,3 +1,2 @@
 import type { MDXComponents } from 'mdx/types';
-import { type ReactNode } from 'react';
-export declare function createCodeMdxComponents(iconMap?: Record<string, ReactNode>): MDXComponents;
+export declare function createCodeMdxComponents(): MDXComponents;