@windrun-huaiin/third-ui 23.0.0 → 23.1.0

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/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;

package/dist/fuma/server/features/code.js

@@ -51,11 +51,10 @@ function tryToMatchIcon(props, iconMap) {
     }
     return undefined;
 }
-function createCodeMdxComponents(iconMap = {}) {
-    const mergedIconMap = Object.assign(Object.assign({}, defaultCodeLanguageIconMap), iconMap);
+function createCodeMdxComponents() {
     return {
         pre: (props) => {
-            const customIcon = tryToMatchIcon(props, mergedIconMap);
+            const customIcon = tryToMatchIcon(props, defaultCodeLanguageIconMap);
             return (jsxRuntime.jsx(CodeBlock, Object.assign({}, props, (customIcon && { icon: customIcon }), { children: jsxRuntime.jsx(Pre, { children: props.children }) })));
         },
         CodeBlock,

package/dist/fuma/server/features/code.mjs

@@ -49,11 +49,10 @@ function tryToMatchIcon(props, iconMap) {
     }
     return undefined;
 }
-function createCodeMdxComponents(iconMap = {}) {
-    const mergedIconMap = Object.assign(Object.assign({}, defaultCodeLanguageIconMap), iconMap);
+function createCodeMdxComponents() {
     return {
         pre: (props) => {
-            const customIcon = tryToMatchIcon(props, mergedIconMap);
+            const customIcon = tryToMatchIcon(props, defaultCodeLanguageIconMap);
             return (jsx(CodeBlock, Object.assign({}, props, (customIcon && { icon: customIcon }), { children: jsx(Pre, { children: props.children }) })));
         },
         CodeBlock,

package/dist/fuma/server/site-mdx-base.js

@@ -2,13 +2,17 @@
 
 var tabs = require('fumadocs-ui/components/tabs');
 var callout = require('fumadocs-ui/components/callout');
+var card = require('fumadocs-ui/components/card');
 var files = require('fumadocs-ui/components/files');
 var accordion = require('fumadocs-ui/components/accordion');
 var siteX = require('../site-x.js');
 var base = require('./features/base.js');
 var widgets = require('./features/widgets.js');
+var siteMdxFallbacks = require('./site-mdx-fallbacks.js');
 
 const defaultFumaUiComponents = {
+    Card: card.Card,
+    Cards: card.Cards,
     Callout: callout.Callout,
     File: files.File,
     Folder: files.Folder,
@@ -24,7 +28,7 @@ function createSiteMdxBaseComponents(options = {}) {
 function createSiteMdxComponents(options = {}) {
     const { additionalComponents, baseOptions, features = [], } = options;
     return function getMDXComponents(components) {
-        return Object.assign(Object.assign(Object.assign(Object.assign({}, createSiteMdxBaseComponents(baseOptions)), features.reduce((acc, feature) => (Object.assign(Object.assign({}, acc), feature)), {})), additionalComponents), components);
+        return siteMdxFallbacks.withMissingMdxComponentFallback(Object.assign(Object.assign(Object.assign(Object.assign({}, createSiteMdxBaseComponents(baseOptions)), features.reduce((acc, feature) => (Object.assign(Object.assign({}, acc), feature)), {})), additionalComponents), components));
     };
 }
 

package/dist/fuma/server/site-mdx-base.mjs

@@ -1,12 +1,16 @@
 import { Tabs, Tab } from 'fumadocs-ui/components/tabs';
 import { Callout } from 'fumadocs-ui/components/callout';
+import { Cards, Card } from 'fumadocs-ui/components/card';
 import { Files, Folder, File } from 'fumadocs-ui/components/files';
 import { Accordions, Accordion } from 'fumadocs-ui/components/accordion';
 import { SiteX } from '../site-x.mjs';
 import { createBaseMdxComponents } from './features/base.mjs';
 import { createWidgetMdxComponents } from './features/widgets.mjs';
+import { withMissingMdxComponentFallback } from './site-mdx-fallbacks.mjs';
 
 const defaultFumaUiComponents = {
+    Card,
+    Cards,
     Callout,
     File,
     Folder,
@@ -22,7 +26,7 @@ function createSiteMdxBaseComponents(options = {}) {
 function createSiteMdxComponents(options = {}) {
     const { additionalComponents, baseOptions, features = [], } = options;
     return function getMDXComponents(components) {
-        return Object.assign(Object.assign(Object.assign(Object.assign({}, createSiteMdxBaseComponents(baseOptions)), features.reduce((acc, feature) => (Object.assign(Object.assign({}, acc), feature)), {})), additionalComponents), components);
+        return withMissingMdxComponentFallback(Object.assign(Object.assign(Object.assign(Object.assign({}, createSiteMdxBaseComponents(baseOptions)), features.reduce((acc, feature) => (Object.assign(Object.assign({}, acc), feature)), {})), additionalComponents), components));
     };
 }
 

package/dist/fuma/server/site-mdx-fallbacks.d.ts

@@ -1,4 +1,5 @@
 import type { ComponentPropsWithoutRef } from 'react';
+import type { MDXComponents } from 'mdx/types';
 type MissingFeatureBlockProps = ComponentPropsWithoutRef<'div'> & {
     feature: string;
     component: string;
@@ -14,5 +15,11 @@ export declare function createMissingMdxFeatureComponents(): {
     InlineMath: (props: ComponentPropsWithoutRef<"span">) => import("react/jsx-runtime").JSX.Element;
     Mermaid: (props: ComponentPropsWithoutRef<"div">) => import("react/jsx-runtime").JSX.Element;
     TypeTable: (props: ComponentPropsWithoutRef<"div">) => import("react/jsx-runtime").JSX.Element;
+    CodeBlockTab: (props: ComponentPropsWithoutRef<"div">) => import("react/jsx-runtime").JSX.Element;
+    CodeBlockTabs: (props: ComponentPropsWithoutRef<"div">) => import("react/jsx-runtime").JSX.Element;
+    CodeBlockTabsList: (props: ComponentPropsWithoutRef<"div">) => import("react/jsx-runtime").JSX.Element;
+    CodeBlockTabsTrigger: (props: ComponentPropsWithoutRef<"div">) => import("react/jsx-runtime").JSX.Element;
 };
+export declare function createMissingMdxComponentFallback(component: string): (props: ComponentPropsWithoutRef<"div">) => import("react/jsx-runtime").JSX.Element;
+export declare function withMissingMdxComponentFallback(components: MDXComponents): MDXComponents;
 export {};

package/dist/fuma/server/site-mdx-fallbacks.js

@@ -41,9 +41,39 @@ function createMissingMdxFeatureComponents() {
         InlineMath: (props) => (jsxRuntime.jsx(MissingMdxFeatureInline, Object.assign({}, props, { feature: "math", component: "InlineMath" }))),
         Mermaid: (props) => (jsxRuntime.jsx(MissingMdxFeatureBlock, Object.assign({}, props, { feature: "diagram renderer", component: "Mermaid" }))),
         TypeTable: (props) => (jsxRuntime.jsx(MissingMdxFeatureBlock, Object.assign({}, props, { feature: "API table renderer", component: "TypeTable" }))),
+        CodeBlockTab: (props) => (jsxRuntime.jsx(MissingMdxFeatureBlock, Object.assign({}, props, { feature: "code", component: "CodeBlockTab" }))),
+        CodeBlockTabs: (props) => (jsxRuntime.jsx(MissingMdxFeatureBlock, Object.assign({}, props, { feature: "code", component: "CodeBlockTabs" }))),
+        CodeBlockTabsList: (props) => (jsxRuntime.jsx(MissingMdxFeatureBlock, Object.assign({}, props, { feature: "code", component: "CodeBlockTabsList" }))),
+        CodeBlockTabsTrigger: (props) => (jsxRuntime.jsx(MissingMdxFeatureBlock, Object.assign({}, props, { feature: "code", component: "CodeBlockTabsTrigger" }))),
     };
 }
+function createMissingMdxComponentFallback(component) {
+    return function MissingMdxComponent(props) {
+        return (jsxRuntime.jsx(MissingMdxFeatureBlock, Object.assign({}, props, { feature: "unknown MDX component", component: component })));
+    };
+}
+function withMissingMdxComponentFallback(components) {
+    return new Proxy(components, {
+        has(target, prop) {
+            if (typeof prop === 'string' && /^[A-Z]/.test(prop)) {
+                return true;
+            }
+            return prop in target;
+        },
+        get(target, prop, receiver) {
+            if (typeof prop !== 'string' || prop in target) {
+                return Reflect.get(target, prop, receiver);
+            }
+            if (/^[A-Z]/.test(prop)) {
+                return createMissingMdxComponentFallback(prop);
+            }
+            return Reflect.get(target, prop, receiver);
+        },
+    });
+}
 
 exports.MissingMdxFeatureBlock = MissingMdxFeatureBlock;
 exports.MissingMdxFeatureInline = MissingMdxFeatureInline;
+exports.createMissingMdxComponentFallback = createMissingMdxComponentFallback;
 exports.createMissingMdxFeatureComponents = createMissingMdxFeatureComponents;
+exports.withMissingMdxComponentFallback = withMissingMdxComponentFallback;

package/dist/fuma/server/site-mdx-fallbacks.mjs

@@ -39,7 +39,35 @@ function createMissingMdxFeatureComponents() {
         InlineMath: (props) => (jsx(MissingMdxFeatureInline, Object.assign({}, props, { feature: "math", component: "InlineMath" }))),
         Mermaid: (props) => (jsx(MissingMdxFeatureBlock, Object.assign({}, props, { feature: "diagram renderer", component: "Mermaid" }))),
         TypeTable: (props) => (jsx(MissingMdxFeatureBlock, Object.assign({}, props, { feature: "API table renderer", component: "TypeTable" }))),
+        CodeBlockTab: (props) => (jsx(MissingMdxFeatureBlock, Object.assign({}, props, { feature: "code", component: "CodeBlockTab" }))),
+        CodeBlockTabs: (props) => (jsx(MissingMdxFeatureBlock, Object.assign({}, props, { feature: "code", component: "CodeBlockTabs" }))),
+        CodeBlockTabsList: (props) => (jsx(MissingMdxFeatureBlock, Object.assign({}, props, { feature: "code", component: "CodeBlockTabsList" }))),
+        CodeBlockTabsTrigger: (props) => (jsx(MissingMdxFeatureBlock, Object.assign({}, props, { feature: "code", component: "CodeBlockTabsTrigger" }))),
     };
 }
+function createMissingMdxComponentFallback(component) {
+    return function MissingMdxComponent(props) {
+        return (jsx(MissingMdxFeatureBlock, Object.assign({}, props, { feature: "unknown MDX component", component: component })));
+    };
+}
+function withMissingMdxComponentFallback(components) {
+    return new Proxy(components, {
+        has(target, prop) {
+            if (typeof prop === 'string' && /^[A-Z]/.test(prop)) {
+                return true;
+            }
+            return prop in target;
+        },
+        get(target, prop, receiver) {
+            if (typeof prop !== 'string' || prop in target) {
+                return Reflect.get(target, prop, receiver);
+            }
+            if (/^[A-Z]/.test(prop)) {
+                return createMissingMdxComponentFallback(prop);
+            }
+            return Reflect.get(target, prop, receiver);
+        },
+    });
+}
 
-export { MissingMdxFeatureBlock, MissingMdxFeatureInline, createMissingMdxFeatureComponents };
+export { MissingMdxFeatureBlock, MissingMdxFeatureInline, createMissingMdxComponentFallback, createMissingMdxFeatureComponents, withMissingMdxComponentFallback };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@windrun-huaiin/third-ui",
-  "version": "23.0.0",
+  "version": "23.1.0",
   "description": "Third-party integrated UI components for windrun-huaiin projects",
   "exports": {
     "./clerk": {
@@ -48,11 +48,6 @@
       "import": "./dist/fuma/server.mjs",
       "require": "./dist/fuma/server.js"
     },
-    "./fuma/server/site-mdx-components": {
-      "types": "./dist/fuma/server/site-mdx-components.d.ts",
-      "import": "./dist/fuma/server/site-mdx-components.mjs",
-      "require": "./dist/fuma/server/site-mdx-components.js"
-    },
     "./fuma/server/site-mdx/base": {
       "types": "./dist/fuma/server/site-mdx-base.d.ts",
       "import": "./dist/fuma/server/site-mdx-base.mjs",
@@ -93,11 +88,6 @@
       "import": "./dist/fuma/mdx/index.mjs",
       "require": "./dist/fuma/mdx/index.js"
     },
-    "./fuma/server/optional-features": {
-      "types": "./dist/fuma/server/optional-features.d.ts",
-      "import": "./dist/fuma/server/optional-features.mjs",
-      "require": "./dist/fuma/server/optional-features.js"
-    },
     "./fuma/base": {
       "types": "./dist/fuma/base/index.d.ts",
       "import": "./dist/fuma/base/index.mjs",
@@ -147,9 +137,9 @@
     "tslib": "^2.8.1",
     "unified": "^11.0.5",
     "zod": "^4.3.6",
-    "@windrun-huaiin/base-ui": "^23.0.0",
-    "@windrun-huaiin/lib": "^23.0.0",
-    "@windrun-huaiin/contracts": "^23.0.0"
+    "@windrun-huaiin/base-ui": "^23.1.0",
+    "@windrun-huaiin/contracts": "^23.1.0",
+    "@windrun-huaiin/lib": "^23.1.0"
   },
   "peerDependencies": {
     "clsx": "^2.1.1",

package/src/fuma/server/features/code.tsx

@@ -78,17 +78,13 @@ function tryToMatchIcon(
   return undefined;
 }
 
-export function createCodeMdxComponents(
-  iconMap: Record<string, ReactNode> = {},
-): MDXComponents {
-  const mergedIconMap = {
-    ...defaultCodeLanguageIconMap,
-    ...iconMap,
-  };
-
+export function createCodeMdxComponents(): MDXComponents {
   return {
     pre: (props) => {
-      const customIcon = tryToMatchIcon(props as MDXProps & { 'data-language'?: string; title?: string }, mergedIconMap);
+      const customIcon = tryToMatchIcon(
+        props as MDXProps & { 'data-language'?: string; title?: string },
+        defaultCodeLanguageIconMap,
+      );
       return (
         <CodeBlock
           {...props}

package/src/fuma/server/site-mdx-base.tsx

@@ -1,11 +1,13 @@
 import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
 import { Callout } from 'fumadocs-ui/components/callout';
+import { Card, Cards } from 'fumadocs-ui/components/card';
 import { File, Folder, Files } from 'fumadocs-ui/components/files';
 import { Accordion, Accordions } from 'fumadocs-ui/components/accordion';
 import type { MDXComponents } from 'mdx/types';
 import { SiteX } from '../site-x';
 import { createBaseMdxComponents } from './features/base';
 import { createWidgetMdxComponents } from './features/widgets';
+import { withMissingMdxComponentFallback } from './site-mdx-fallbacks';
 
 export type SiteMdxFeatureComponents = MDXComponents;
 
@@ -21,6 +23,8 @@ export interface CreateSiteMdxComponentsOptions {
 }
 
 const defaultFumaUiComponents: MDXComponents = {
+  Card,
+  Cards,
   Callout,
   File,
   Folder,
@@ -52,11 +56,11 @@ export function createSiteMdxComponents(
   } = options;
 
   return function getMDXComponents(components?: MDXComponents): MDXComponents {
-    return {
+    return withMissingMdxComponentFallback({
       ...createSiteMdxBaseComponents(baseOptions),
       ...features.reduce<MDXComponents>((acc, feature) => ({ ...acc, ...feature }), {}),
       ...additionalComponents,
       ...components,
-    };
+    });
   };
 }

package/src/fuma/server/site-mdx-fallbacks.tsx

@@ -1,4 +1,5 @@
 import type { ComponentPropsWithoutRef, ReactNode } from 'react';
+import type { MDXComponents } from 'mdx/types';
 
 type MissingFeatureBlockProps = ComponentPropsWithoutRef<'div'> & {
   feature: string;
@@ -118,5 +119,54 @@ export function createMissingMdxFeatureComponents() {
     TypeTable: (props: ComponentPropsWithoutRef<'div'>) => (
       <MissingMdxFeatureBlock {...props} feature="API table renderer" component="TypeTable" />
     ),
+    CodeBlockTab: (props: ComponentPropsWithoutRef<'div'>) => (
+      <MissingMdxFeatureBlock {...props} feature="code" component="CodeBlockTab" />
+    ),
+    CodeBlockTabs: (props: ComponentPropsWithoutRef<'div'>) => (
+      <MissingMdxFeatureBlock {...props} feature="code" component="CodeBlockTabs" />
+    ),
+    CodeBlockTabsList: (props: ComponentPropsWithoutRef<'div'>) => (
+      <MissingMdxFeatureBlock {...props} feature="code" component="CodeBlockTabsList" />
+    ),
+    CodeBlockTabsTrigger: (props: ComponentPropsWithoutRef<'div'>) => (
+      <MissingMdxFeatureBlock {...props} feature="code" component="CodeBlockTabsTrigger" />
+    ),
+  };
+}
+
+export function createMissingMdxComponentFallback(component: string) {
+  return function MissingMdxComponent(props: ComponentPropsWithoutRef<'div'>) {
+    return (
+      <MissingMdxFeatureBlock
+        {...props}
+        feature="unknown MDX component"
+        component={component}
+      />
+    );
   };
 }
+
+export function withMissingMdxComponentFallback(
+  components: MDXComponents,
+): MDXComponents {
+  return new Proxy(components, {
+    has(target, prop) {
+      if (typeof prop === 'string' && /^[A-Z]/.test(prop)) {
+        return true;
+      }
+
+      return prop in target;
+    },
+    get(target, prop, receiver) {
+      if (typeof prop !== 'string' || prop in target) {
+        return Reflect.get(target, prop, receiver);
+      }
+
+      if (/^[A-Z]/.test(prop)) {
+        return createMissingMdxComponentFallback(prop);
+      }
+
+      return Reflect.get(target, prop, receiver);
+    },
+  });
+}

package/src/fuma/server/optional-features.tsx

@@ -1,6 +0,0 @@
-export { createBaseMdxComponents } from './features/base';
-export { createCodeMdxComponents } from './features/code';
-export { createMathMdxComponents } from './features/math';
-export { createMermaidMdxComponents } from './features/mermaid';
-export { createTypeTableMdxComponents } from './features/type-table';
-export { createWidgetMdxComponents } from './features/widgets';

package/src/fuma/server/site-mdx-components.tsx

@@ -1,46 +0,0 @@
-import type { MDXComponents } from 'mdx/types';
-import type { ReactNode } from 'react';
-import {
-  createComposedSiteMdxComponents,
-  DEFAULT_SITE_MDX_FEATURES,
-  type SiteMdxFeature,
-} from './site-mdx-presets';
-
-export interface SiteMdxComponentsOptions {
-  imageFallbackSrc?: string;
-  cdnBaseUrl?: string;
-  watermarkEnabled?: boolean;
-  watermarkText?: string;
-  additionalComponents?: MDXComponents;
-  iconMap?: Record<string, ReactNode>;
-  features?: SiteMdxFeature[];
-}
-
-export function createSiteMdxComponents(
-  options: SiteMdxComponentsOptions,
-) {
-  const {
-    additionalComponents,
-    cdnBaseUrl,
-    features = DEFAULT_SITE_MDX_FEATURES,
-    iconMap = {},
-    imageFallbackSrc,
-    watermarkEnabled,
-    watermarkText,
-  } = options;
-
-  return function getMDXComponents(components?: MDXComponents): MDXComponents {
-    return createComposedSiteMdxComponents(
-      features,
-      {
-        cdnBaseUrl,
-        iconMap,
-        imageFallbackSrc,
-        watermarkEnabled,
-        watermarkText,
-      },
-      additionalComponents,
-      components,
-    );
-  };
-}

package/src/fuma/server/site-mdx-presets.ts

@@ -1,131 +0,0 @@
-import defaultMdxComponents from 'fumadocs-ui/mdx';
-import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
-import { Callout } from 'fumadocs-ui/components/callout';
-import { File, Folder, Files } from 'fumadocs-ui/components/files';
-import { Accordion, Accordions } from 'fumadocs-ui/components/accordion';
-import type { MDXComponents } from 'mdx/types';
-import {
-  createBaseMdxComponents,
-  createCodeMdxComponents,
-  createMathMdxComponents,
-  createMermaidMdxComponents,
-  createTypeTableMdxComponents,
-  createWidgetMdxComponents,
-} from './optional-features';
-import { SiteX } from '../site-x';
-import type { SiteMdxComponentsOptions } from './site-mdx-components';
-
-export type SiteMdxFeature = 'base' | 'code' | 'math' | 'mermaid' | 'type-table';
-
-const defaultFumaUiComponents: MDXComponents = {
-  Callout,
-  File,
-  Folder,
-  Files,
-  Accordion,
-  Accordions,
-  Tab,
-  Tabs,
-};
-
-export const DEFAULT_SITE_MDX_FEATURES: SiteMdxFeature[] = [
-  'base',
-  'code',
-  'math',
-  'mermaid',
-  'type-table',
-];
-
-export function createSiteFeatureComponentMap(
-  options: SiteMdxComponentsOptions,
-) {
-  const {
-    cdnBaseUrl,
-    iconMap = {},
-    imageFallbackSrc,
-    watermarkEnabled,
-    watermarkText,
-  } = options;
-
-  return {
-    base: {
-      ...defaultFumaUiComponents,
-      SiteX,
-      ...createBaseMdxComponents(imageFallbackSrc),
-      ...createWidgetMdxComponents(cdnBaseUrl, imageFallbackSrc),
-    },
-    code: createCodeMdxComponents(iconMap),
-    math: createMathMdxComponents(),
-    mermaid: createMermaidMdxComponents(watermarkEnabled, watermarkText),
-    'type-table': createTypeTableMdxComponents(),
-  } satisfies Record<SiteMdxFeature, MDXComponents>;
-}
-
-function createSiteFeatureComponents(
-  feature: SiteMdxFeature,
-  options: SiteMdxComponentsOptions,
-): MDXComponents {
-  const {
-    cdnBaseUrl,
-    iconMap = {},
-    imageFallbackSrc,
-    watermarkEnabled,
-    watermarkText,
-  } = options;
-
-  switch (feature) {
-    case 'base':
-      return {
-        ...defaultFumaUiComponents,
-        SiteX,
-        ...createBaseMdxComponents(imageFallbackSrc),
-        ...createWidgetMdxComponents(cdnBaseUrl, imageFallbackSrc),
-      };
-    case 'code':
-      return createCodeMdxComponents(iconMap);
-    case 'math':
-      return createMathMdxComponents();
-    case 'mermaid':
-      return createMermaidMdxComponents(watermarkEnabled, watermarkText);
-    case 'type-table':
-      return createTypeTableMdxComponents();
-  }
-}
-
-export function composeSiteMdxComponents(
-  features: readonly SiteMdxFeature[],
-  featureMap: Record<SiteMdxFeature, MDXComponents>,
-  additionalComponents?: MDXComponents,
-  components?: MDXComponents,
-): MDXComponents {
-  return {
-    ...defaultMdxComponents,
-    ...features.reduce<MDXComponents>((acc, feature) => {
-      return {
-        ...acc,
-        ...featureMap[feature],
-      };
-    }, {}),
-    ...additionalComponents,
-    ...components,
-  };
-}
-
-export function createComposedSiteMdxComponents(
-  features: readonly SiteMdxFeature[],
-  options: SiteMdxComponentsOptions,
-  additionalComponents?: MDXComponents,
-  components?: MDXComponents,
-): MDXComponents {
-  return {
-    ...defaultMdxComponents,
-    ...features.reduce<MDXComponents>((acc, feature) => {
-      return {
-        ...acc,
-        ...createSiteFeatureComponents(feature, options),
-      };
-    }, {}),
-    ...additionalComponents,
-    ...components,
-  };
-}