@windrun-huaiin/third-ui 14.4.0 → 14.4.2

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

@@ -1,3 +1,7 @@
+/**
+ * References most of its code and SVG animation design from
+ * https://github.com/fuma-nama/fumadocs/blob/dev/packages/radix-ui/src/components/toc/clerk.tsx
+ */
 import * as Primitive from 'fumadocs-core/toc';
 import { type ComponentProps, type ReactNode } from 'react';
 type TOCItemType = Primitive.TOCItemType;

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

@@ -37,6 +37,18 @@ const CLERK_TURN_CURVE_HEIGHT = 12;
 const CLERK_TURN_CONTROL_FACTOR = 0.68;
 // Safety margin that keeps turns away from the heading rows themselves.
 const CLERK_TURN_GAP_MARGIN = 7;
+// Shared duration for active rail fade transitions and endpoint dot movement.
+const CLERK_ACTIVE_ANIMATION_DURATION_MS = 300;
+// Easing curve for the active rail and dot; tuned for a slightly delayed, softer motion.
+const CLERK_ACTIVE_ANIMATION_EASING = 'cubic-bezier(0.22, 1, 0.36, 1)';
+// Horizontal gap between the path centerline and the heading text start.
+const CLERK_TEXT_GAP_FROM_PATH = 12;
+// Radius of numbered step badges rendered on top of the path centerline.
+const CLERK_STEP_BADGE_RADIUS = 7;
+// Visual line offsets by grouped heading depth: 1/2, 3, 4, >4.
+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 (jsxRuntime.jsxs(page.PageTOC, { className: className, children: [header, title !== null && title !== void 0 ? title : jsxRuntime.jsx(page.PageTOCTitle, {}), jsxRuntime.jsx(PortableClerkTOCScrollArea, { children: jsxRuntime.jsx(PortableClerkTOCItems, { toc: toc, emptyLabel: emptyLabel }) }), footer] }));
 }
@@ -116,49 +128,85 @@ function PortableClerkTOCItems(_a) {
     if (toc.length === 0) {
         return (jsxRuntime.jsx("div", { className: "rounded-lg border bg-fd-card p-3 text-xs text-fd-muted-foreground", children: emptyLabel }));
     }
-    return (jsxRuntime.jsxs("div", Object.assign({ ref: mergeRefs(containerRef, ref), className: cn('relative flex flex-col', className) }, props, { children: [jsxRuntime.jsx(ClerkOutline, { path: outlinePath, items: layout.items, activePath: activePath, activeAnchors: activeAnchors, activeEndpoint: activeEndpoint }), metas.map((meta, i) => (jsxRuntime.jsx(PortableClerkTOCItem, { item: meta.item, isActive: activeAnchors.includes(meta.item.url.slice(1)), resolvedContent: meta.resolvedContent, itemPadding: meta.itemPadding, contentRef: (node) => {
+    return (jsxRuntime.jsxs("div", Object.assign({ ref: mergeRefs(containerRef, ref), className: cn('relative flex flex-col', className) }, props, { children: [jsxRuntime.jsx(ClerkOutline, { path: outlinePath, items: layout.items, activePath: activePath, activeAnchors: activeAnchors, activeEndpoint: activeEndpoint }), metas.map((meta, i) => (jsxRuntime.jsx(PortableClerkTOCItem, { item: meta.item, isActive: activeAnchors.includes(meta.item.url.slice(1)), resolvedContent: meta.resolvedContent, fullTitle: meta.fullTitle, itemPadding: meta.itemPadding, contentRef: (node) => {
                     contentRefs.current[i] = node;
                 }, ref: (node) => {
                     itemRefs.current[i] = node;
                 } }, meta.item.url)))] })));
 }
-function PortableClerkTOCItem({ item, isActive, resolvedContent, itemPadding, contentRef, ref, }) {
-    return (jsxRuntime.jsx(Primitive__namespace.TOCItem, { ref: ref, href: item.url, "data-clerk-item": "", style: {
+function PortableClerkTOCItem({ item, isActive, resolvedContent, fullTitle, itemPadding, contentRef, ref, }) {
+    return (jsxRuntime.jsx(Primitive__namespace.TOCItem, { ref: ref, href: item.url, "data-clerk-item": "", title: fullTitle !== null && fullTitle !== void 0 ? fullTitle : undefined, style: {
             paddingInlineStart: itemPadding,
-        }, className: cn('prose group relative py-1.5 text-sm transition-colors wrap-anywhere first:pt-0 last:pb-0 hover:text-fd-accent-foreground', isActive ? lib.themeIconColor : 'text-fd-muted-foreground'), children: jsxRuntime.jsx("span", { ref: contentRef, className: "relative z-10", children: resolvedContent }) }));
+        }, className: cn('prose group relative py-1.5 text-sm transition-colors first:pt-0 last:pb-0 hover:text-fd-accent-foreground', isActive ? lib.themeIconColor : 'text-fd-muted-foreground'), children: jsxRuntime.jsx("span", { ref: contentRef, className: "relative z-10 block overflow-hidden text-ellipsis whitespace-nowrap", children: resolvedContent }) }));
 }
 function ClerkOutline({ path, items, activePath, activeAnchors, activeEndpoint, }) {
+    const activeSet = new Set(activeAnchors);
+    const [displayPath, setDisplayPath] = React.useState(activePath);
+    const [fadingPath, setFadingPath] = React.useState(null);
+    React.useEffect(() => {
+        if (activePath === displayPath)
+            return;
+        if (!displayPath) {
+            setDisplayPath(activePath);
+            setFadingPath(null);
+            return;
+        }
+        setFadingPath(displayPath);
+        setDisplayPath(activePath);
+        const timeout = window.setTimeout(() => {
+            setFadingPath(null);
+        }, CLERK_ACTIVE_ANIMATION_DURATION_MS);
+        return () => window.clearTimeout(timeout);
+    }, [activePath, displayPath]);
+    const dotTranslate = activeEndpoint
+        ? `translate(${activeEndpoint.x - CLERK_ACTIVE_DOT_RADIUS}px, ${activeEndpoint.y - CLERK_ACTIVE_DOT_RADIUS}px)`
+        : undefined;
+    const transitionStyle = {
+        transitionDuration: `${CLERK_ACTIVE_ANIMATION_DURATION_MS}ms`,
+        transitionTimingFunction: CLERK_ACTIVE_ANIMATION_EASING,
+    };
     if (!path)
         return null;
-    const activeSet = new Set(activeAnchors);
-    return (jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [jsxRuntime.jsx("svg", { "aria-hidden": "true", className: "pointer-events-none absolute inset-0 z-0 overflow-visible", width: "100%", height: "100%", children: jsxRuntime.jsx("path", { d: path, className: "stroke-fd-foreground/15", fill: "none", strokeWidth: CLERK_PATH_STROKE_WIDTH, strokeLinecap: "round", strokeLinejoin: "round" }) }), jsxRuntime.jsx("svg", { "aria-hidden": "true", className: "pointer-events-none absolute inset-0 z-0 overflow-visible", width: "100%", height: "100%", children: activePath ? (jsxRuntime.jsx("path", { d: activePath, fill: "none", strokeWidth: CLERK_PATH_STROKE_WIDTH, strokeLinecap: "round", strokeLinejoin: "round", stroke: lib.themeSvgIconColor })) : null }), jsxRuntime.jsx("svg", { "aria-hidden": "true", className: "pointer-events-none absolute inset-0 z-0 overflow-visible", width: "100%", height: "100%", children: activeEndpoint ? (jsxRuntime.jsx("circle", { cx: activeEndpoint.x, cy: activeEndpoint.y, r: CLERK_ACTIVE_DOT_RADIUS, fill: lib.themeSvgIconColor })) : null }), jsxRuntime.jsx("svg", { "aria-hidden": "true", className: "pointer-events-none absolute inset-0 z-1 overflow-visible", width: "100%", height: "100%", children: items.map((item) => {
+    return (jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [jsxRuntime.jsx("svg", { "aria-hidden": "true", className: "pointer-events-none absolute inset-0 z-0 overflow-visible", width: "100%", height: "100%", children: jsxRuntime.jsx("path", { d: path, className: "stroke-fd-foreground/15", fill: "none", strokeWidth: CLERK_PATH_STROKE_WIDTH, strokeLinecap: "round", strokeLinejoin: "round" }) }), jsxRuntime.jsxs("svg", { "aria-hidden": "true", className: "pointer-events-none absolute inset-0 z-0 overflow-visible", width: "100%", height: "100%", children: [fadingPath ? (jsxRuntime.jsx("path", { d: fadingPath, fill: "none", strokeWidth: CLERK_PATH_STROKE_WIDTH, strokeLinecap: "round", strokeLinejoin: "round", stroke: lib.themeSvgIconColor, className: "transition-opacity", style: Object.assign({ opacity: 0 }, transitionStyle) })) : null, displayPath ? (jsxRuntime.jsx("path", { d: displayPath, fill: "none", strokeWidth: CLERK_PATH_STROKE_WIDTH, strokeLinecap: "round", strokeLinejoin: "round", stroke: lib.themeSvgIconColor, className: "transition-opacity", style: Object.assign({ opacity: 1 }, transitionStyle) })) : null] }), jsxRuntime.jsx("div", { "aria-hidden": "true", className: "pointer-events-none absolute inset-0 z-0", children: jsxRuntime.jsx("div", { className: "absolute rounded-full transition-transform", style: Object.assign({ width: CLERK_ACTIVE_DOT_RADIUS * 2, height: CLERK_ACTIVE_DOT_RADIUS * 2, backgroundColor: lib.themeSvgIconColor, transform: dotTranslate, opacity: activeEndpoint ? 1 : 0 }, transitionStyle) }) }), jsxRuntime.jsx("svg", { "aria-hidden": "true", className: "pointer-events-none absolute inset-0 z-1 overflow-visible", width: "100%", height: "100%", children: items.map((item) => {
                     if (!item.stepNumber)
                         return null;
                     const isActive = activeSet.has(item.url.slice(1));
-                    return (jsxRuntime.jsxs("g", { transform: `translate(${item.x}, ${item.y})`, children: [jsxRuntime.jsx("circle", { r: "7", fill: isActive ? lib.themeSvgIconColor : undefined, className: cn(!isActive && 'fill-black dark:fill-white') }), jsxRuntime.jsx("text", { y: "0.5", textAnchor: "middle", dominantBaseline: "middle", className: "fill-white text-[9px] font-medium dark:fill-black", children: item.stepNumber })] }, item.url));
+                    return (jsxRuntime.jsxs("g", { transform: `translate(${item.x}, ${item.y})`, children: [jsxRuntime.jsx("circle", { r: CLERK_STEP_BADGE_RADIUS, fill: isActive ? lib.themeSvgIconColor : undefined, className: cn(!isActive && 'fill-black dark:fill-white') }), jsxRuntime.jsx("text", { y: "0.5", textAnchor: "middle", dominantBaseline: "middle", className: "fill-white text-[9px] font-medium dark:fill-black", children: item.stepNumber })] }, item.url));
                 }) })] }));
 }
 function getItemOffset(depth) {
-    if (depth <= 2)
-        return 14;
-    if (depth === 3)
-        return 26;
-    return 36;
+    const lineOffset = getLineOffset(depth);
+    const badgeRadius = depth === 3 ? CLERK_STEP_BADGE_RADIUS : 0;
+    return lineOffset + badgeRadius + CLERK_TEXT_GAP_FROM_PATH;
 }
 function getLineOffset(depth) {
-    return depth >= 3 ? 18 : 6;
+    const group = getDepthGroup(depth);
+    return CLERK_DEPTH_GROUP_LINE_OFFSETS[group];
 }
 function getVisualLinePosition(depth) {
     return getLineOffset(depth);
 }
+function getDepthGroup(depth) {
+    if (depth <= 2)
+        return 0;
+    if (depth === 3)
+        return 1;
+    if (depth === 4)
+        return 2;
+    return 3;
+}
 function resolveClerkItem(item) {
     const isH3 = item.depth === 3;
     const rawTitle = typeof item.title === 'string' ? item.title : '';
     const { isStep, displayStep, content } = getStepInfoFromTitle(rawTitle);
     let stepNumber = isH3 && isStep ? String(displayStep) : null;
     let resolvedContent = item.title;
+    let fullTitle = rawTitle || null;
     if (isH3 && isStep) {
         resolvedContent = content !== null && content !== void 0 ? content : item.title;
+        if (typeof content === 'string') {
+            fullTitle = content;
+        }
     }
     if (isH3 && !stepNumber) {
         const urlNum = getDigitsFromUrl(item.url);
@@ -169,18 +217,30 @@ function resolveClerkItem(item) {
                 const match = rawTitle.match(/^(\d+(?:\.\d+)*\.?)\s+(.+)$/);
                 if (match === null || match === void 0 ? void 0 : match[2]) {
                     resolvedContent = match[2];
+                    fullTitle = match[2];
                 }
             }
         }
     }
+    if (typeof resolvedContent === 'string') {
+        fullTitle = resolvedContent;
+        resolvedContent = truncateClerkLabel(resolvedContent);
+    }
     return {
         item,
         resolvedContent,
+        fullTitle,
         stepNumber,
         itemPadding: getItemOffset(item.depth),
         lineOffset: getVisualLinePosition(item.depth),
     };
 }
+function truncateClerkLabel(value) {
+    const normalized = value.trim();
+    if (normalized.length <= CLERK_MAX_LABEL_LENGTH)
+        return normalized;
+    return `${normalized.slice(0, CLERK_MAX_LABEL_LENGTH).trimEnd()}...`;
+}
 function buildOutlinePath(items) {
     if (items.length === 0)
         return '';

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

@@ -3,7 +3,7 @@ import { __rest } from '../../node_modules/.pnpm/@rollup_plugin-typescript@12.1.
 import { jsxs, jsx, Fragment } from 'react/jsx-runtime';
 import * as Primitive from 'fumadocs-core/toc';
 import { PageTOC, PageTOCTitle, PageTOCPopover, PageTOCPopoverTrigger, PageTOCPopoverContent } from 'fumadocs-ui/layouts/docs/page';
-import { useRef, useState, useMemo, useLayoutEffect } from 'react';
+import { useRef, useState, useMemo, useLayoutEffect, useEffect } from 'react';
 import { themeSvgIconColor, themeIconColor } from '@windrun-huaiin/base-ui/lib';
 
 // Base stroke width for both the inactive rail and the active highlight path.
@@ -16,6 +16,18 @@ const CLERK_TURN_CURVE_HEIGHT = 12;
 const CLERK_TURN_CONTROL_FACTOR = 0.68;
 // Safety margin that keeps turns away from the heading rows themselves.
 const CLERK_TURN_GAP_MARGIN = 7;
+// Shared duration for active rail fade transitions and endpoint dot movement.
+const CLERK_ACTIVE_ANIMATION_DURATION_MS = 300;
+// Easing curve for the active rail and dot; tuned for a slightly delayed, softer motion.
+const CLERK_ACTIVE_ANIMATION_EASING = 'cubic-bezier(0.22, 1, 0.36, 1)';
+// Horizontal gap between the path centerline and the heading text start.
+const CLERK_TEXT_GAP_FROM_PATH = 12;
+// Radius of numbered step badges rendered on top of the path centerline.
+const CLERK_STEP_BADGE_RADIUS = 7;
+// Visual line offsets by grouped heading depth: 1/2, 3, 4, >4.
+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 (jsxs(PageTOC, { className: className, children: [header, title !== null && title !== void 0 ? title : jsx(PageTOCTitle, {}), jsx(PortableClerkTOCScrollArea, { children: jsx(PortableClerkTOCItems, { toc: toc, emptyLabel: emptyLabel }) }), footer] }));
 }
@@ -95,49 +107,85 @@ function PortableClerkTOCItems(_a) {
     if (toc.length === 0) {
         return (jsx("div", { className: "rounded-lg border bg-fd-card p-3 text-xs text-fd-muted-foreground", children: emptyLabel }));
     }
-    return (jsxs("div", Object.assign({ ref: mergeRefs(containerRef, ref), className: cn('relative flex flex-col', className) }, props, { children: [jsx(ClerkOutline, { path: outlinePath, items: layout.items, activePath: activePath, activeAnchors: activeAnchors, activeEndpoint: activeEndpoint }), metas.map((meta, i) => (jsx(PortableClerkTOCItem, { item: meta.item, isActive: activeAnchors.includes(meta.item.url.slice(1)), resolvedContent: meta.resolvedContent, itemPadding: meta.itemPadding, contentRef: (node) => {
+    return (jsxs("div", Object.assign({ ref: mergeRefs(containerRef, ref), className: cn('relative flex flex-col', className) }, props, { children: [jsx(ClerkOutline, { path: outlinePath, items: layout.items, activePath: activePath, activeAnchors: activeAnchors, activeEndpoint: activeEndpoint }), metas.map((meta, i) => (jsx(PortableClerkTOCItem, { item: meta.item, isActive: activeAnchors.includes(meta.item.url.slice(1)), resolvedContent: meta.resolvedContent, fullTitle: meta.fullTitle, itemPadding: meta.itemPadding, contentRef: (node) => {
                     contentRefs.current[i] = node;
                 }, ref: (node) => {
                     itemRefs.current[i] = node;
                 } }, meta.item.url)))] })));
 }
-function PortableClerkTOCItem({ item, isActive, resolvedContent, itemPadding, contentRef, ref, }) {
-    return (jsx(Primitive.TOCItem, { ref: ref, href: item.url, "data-clerk-item": "", style: {
+function PortableClerkTOCItem({ item, isActive, resolvedContent, fullTitle, itemPadding, contentRef, ref, }) {
+    return (jsx(Primitive.TOCItem, { ref: ref, href: item.url, "data-clerk-item": "", title: fullTitle !== null && fullTitle !== void 0 ? fullTitle : undefined, style: {
             paddingInlineStart: itemPadding,
-        }, className: cn('prose group relative py-1.5 text-sm transition-colors wrap-anywhere first:pt-0 last:pb-0 hover:text-fd-accent-foreground', isActive ? themeIconColor : 'text-fd-muted-foreground'), children: jsx("span", { ref: contentRef, className: "relative z-10", children: resolvedContent }) }));
+        }, className: cn('prose group relative py-1.5 text-sm transition-colors first:pt-0 last:pb-0 hover:text-fd-accent-foreground', isActive ? themeIconColor : 'text-fd-muted-foreground'), children: jsx("span", { ref: contentRef, className: "relative z-10 block overflow-hidden text-ellipsis whitespace-nowrap", children: resolvedContent }) }));
 }
 function ClerkOutline({ path, items, activePath, activeAnchors, activeEndpoint, }) {
+    const activeSet = new Set(activeAnchors);
+    const [displayPath, setDisplayPath] = useState(activePath);
+    const [fadingPath, setFadingPath] = useState(null);
+    useEffect(() => {
+        if (activePath === displayPath)
+            return;
+        if (!displayPath) {
+            setDisplayPath(activePath);
+            setFadingPath(null);
+            return;
+        }
+        setFadingPath(displayPath);
+        setDisplayPath(activePath);
+        const timeout = window.setTimeout(() => {
+            setFadingPath(null);
+        }, CLERK_ACTIVE_ANIMATION_DURATION_MS);
+        return () => window.clearTimeout(timeout);
+    }, [activePath, displayPath]);
+    const dotTranslate = activeEndpoint
+        ? `translate(${activeEndpoint.x - CLERK_ACTIVE_DOT_RADIUS}px, ${activeEndpoint.y - CLERK_ACTIVE_DOT_RADIUS}px)`
+        : undefined;
+    const transitionStyle = {
+        transitionDuration: `${CLERK_ACTIVE_ANIMATION_DURATION_MS}ms`,
+        transitionTimingFunction: CLERK_ACTIVE_ANIMATION_EASING,
+    };
     if (!path)
         return null;
-    const activeSet = new Set(activeAnchors);
-    return (jsxs(Fragment, { children: [jsx("svg", { "aria-hidden": "true", className: "pointer-events-none absolute inset-0 z-0 overflow-visible", width: "100%", height: "100%", children: jsx("path", { d: path, className: "stroke-fd-foreground/15", fill: "none", strokeWidth: CLERK_PATH_STROKE_WIDTH, strokeLinecap: "round", strokeLinejoin: "round" }) }), jsx("svg", { "aria-hidden": "true", className: "pointer-events-none absolute inset-0 z-0 overflow-visible", width: "100%", height: "100%", children: activePath ? (jsx("path", { d: activePath, fill: "none", strokeWidth: CLERK_PATH_STROKE_WIDTH, strokeLinecap: "round", strokeLinejoin: "round", stroke: themeSvgIconColor })) : null }), jsx("svg", { "aria-hidden": "true", className: "pointer-events-none absolute inset-0 z-0 overflow-visible", width: "100%", height: "100%", children: activeEndpoint ? (jsx("circle", { cx: activeEndpoint.x, cy: activeEndpoint.y, r: CLERK_ACTIVE_DOT_RADIUS, fill: themeSvgIconColor })) : null }), jsx("svg", { "aria-hidden": "true", className: "pointer-events-none absolute inset-0 z-1 overflow-visible", width: "100%", height: "100%", children: items.map((item) => {
+    return (jsxs(Fragment, { children: [jsx("svg", { "aria-hidden": "true", className: "pointer-events-none absolute inset-0 z-0 overflow-visible", width: "100%", height: "100%", children: jsx("path", { d: path, className: "stroke-fd-foreground/15", fill: "none", strokeWidth: CLERK_PATH_STROKE_WIDTH, strokeLinecap: "round", strokeLinejoin: "round" }) }), jsxs("svg", { "aria-hidden": "true", className: "pointer-events-none absolute inset-0 z-0 overflow-visible", width: "100%", height: "100%", children: [fadingPath ? (jsx("path", { d: fadingPath, fill: "none", strokeWidth: CLERK_PATH_STROKE_WIDTH, strokeLinecap: "round", strokeLinejoin: "round", stroke: themeSvgIconColor, className: "transition-opacity", style: Object.assign({ opacity: 0 }, transitionStyle) })) : null, displayPath ? (jsx("path", { d: displayPath, fill: "none", strokeWidth: CLERK_PATH_STROKE_WIDTH, strokeLinecap: "round", strokeLinejoin: "round", stroke: themeSvgIconColor, className: "transition-opacity", style: Object.assign({ opacity: 1 }, transitionStyle) })) : null] }), jsx("div", { "aria-hidden": "true", className: "pointer-events-none absolute inset-0 z-0", children: jsx("div", { className: "absolute rounded-full transition-transform", style: Object.assign({ width: CLERK_ACTIVE_DOT_RADIUS * 2, height: CLERK_ACTIVE_DOT_RADIUS * 2, backgroundColor: themeSvgIconColor, transform: dotTranslate, opacity: activeEndpoint ? 1 : 0 }, transitionStyle) }) }), jsx("svg", { "aria-hidden": "true", className: "pointer-events-none absolute inset-0 z-1 overflow-visible", width: "100%", height: "100%", children: items.map((item) => {
                     if (!item.stepNumber)
                         return null;
                     const isActive = activeSet.has(item.url.slice(1));
-                    return (jsxs("g", { transform: `translate(${item.x}, ${item.y})`, children: [jsx("circle", { r: "7", fill: isActive ? themeSvgIconColor : undefined, className: cn(!isActive && 'fill-black dark:fill-white') }), jsx("text", { y: "0.5", textAnchor: "middle", dominantBaseline: "middle", className: "fill-white text-[9px] font-medium dark:fill-black", children: item.stepNumber })] }, item.url));
+                    return (jsxs("g", { transform: `translate(${item.x}, ${item.y})`, children: [jsx("circle", { r: CLERK_STEP_BADGE_RADIUS, fill: isActive ? themeSvgIconColor : undefined, className: cn(!isActive && 'fill-black dark:fill-white') }), jsx("text", { y: "0.5", textAnchor: "middle", dominantBaseline: "middle", className: "fill-white text-[9px] font-medium dark:fill-black", children: item.stepNumber })] }, item.url));
                 }) })] }));
 }
 function getItemOffset(depth) {
-    if (depth <= 2)
-        return 14;
-    if (depth === 3)
-        return 26;
-    return 36;
+    const lineOffset = getLineOffset(depth);
+    const badgeRadius = depth === 3 ? CLERK_STEP_BADGE_RADIUS : 0;
+    return lineOffset + badgeRadius + CLERK_TEXT_GAP_FROM_PATH;
 }
 function getLineOffset(depth) {
-    return depth >= 3 ? 18 : 6;
+    const group = getDepthGroup(depth);
+    return CLERK_DEPTH_GROUP_LINE_OFFSETS[group];
 }
 function getVisualLinePosition(depth) {
     return getLineOffset(depth);
 }
+function getDepthGroup(depth) {
+    if (depth <= 2)
+        return 0;
+    if (depth === 3)
+        return 1;
+    if (depth === 4)
+        return 2;
+    return 3;
+}
 function resolveClerkItem(item) {
     const isH3 = item.depth === 3;
     const rawTitle = typeof item.title === 'string' ? item.title : '';
     const { isStep, displayStep, content } = getStepInfoFromTitle(rawTitle);
     let stepNumber = isH3 && isStep ? String(displayStep) : null;
     let resolvedContent = item.title;
+    let fullTitle = rawTitle || null;
     if (isH3 && isStep) {
         resolvedContent = content !== null && content !== void 0 ? content : item.title;
+        if (typeof content === 'string') {
+            fullTitle = content;
+        }
     }
     if (isH3 && !stepNumber) {
         const urlNum = getDigitsFromUrl(item.url);
@@ -148,18 +196,30 @@ function resolveClerkItem(item) {
                 const match = rawTitle.match(/^(\d+(?:\.\d+)*\.?)\s+(.+)$/);
                 if (match === null || match === void 0 ? void 0 : match[2]) {
                     resolvedContent = match[2];
+                    fullTitle = match[2];
                 }
             }
         }
     }
+    if (typeof resolvedContent === 'string') {
+        fullTitle = resolvedContent;
+        resolvedContent = truncateClerkLabel(resolvedContent);
+    }
     return {
         item,
         resolvedContent,
+        fullTitle,
         stepNumber,
         itemPadding: getItemOffset(item.depth),
         lineOffset: getVisualLinePosition(item.depth),
     };
 }
+function truncateClerkLabel(value) {
+    const normalized = value.trim();
+    if (normalized.length <= CLERK_MAX_LABEL_LENGTH)
+        return normalized;
+    return `${normalized.slice(0, CLERK_MAX_LABEL_LENGTH).trimEnd()}...`;
+}
 function buildOutlinePath(items) {
     if (items.length === 0)
         return '';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@windrun-huaiin/third-ui",
-  "version": "14.4.0",
+  "version": "14.4.2",
   "description": "Third-party integrated UI components for windrun-huaiin projects",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",

package/src/fuma/mdx/toc-clerk-portable.tsx

@@ -1,5 +1,9 @@
 'use client';
 
+/**
+ * References most of its code and SVG animation design from
+ * https://github.com/fuma-nama/fumadocs/blob/dev/packages/radix-ui/src/components/toc/clerk.tsx
+ */
 import * as Primitive from 'fumadocs-core/toc';
 import {
   PageTOC,
@@ -11,6 +15,7 @@ import {
 import {
   type ComponentProps,
   type ReactNode,
+  useEffect,
   useLayoutEffect,
   useMemo,
   useRef,
@@ -35,6 +40,7 @@ type PortableClerkTOCProps = {
 type ClerkItemMeta = {
   item: TOCItemType;
   resolvedContent: ReactNode;
+  fullTitle: string | null;
   stepNumber: string | null;
   itemPadding: number;
   lineOffset: number;
@@ -57,6 +63,18 @@ const CLERK_TURN_CURVE_HEIGHT = 12;
 const CLERK_TURN_CONTROL_FACTOR = 0.68;
 // Safety margin that keeps turns away from the heading rows themselves.
 const CLERK_TURN_GAP_MARGIN = 7;
+// Shared duration for active rail fade transitions and endpoint dot movement.
+const CLERK_ACTIVE_ANIMATION_DURATION_MS = 300;
+// Easing curve for the active rail and dot; tuned for a slightly delayed, softer motion.
+const CLERK_ACTIVE_ANIMATION_EASING = 'cubic-bezier(0.22, 1, 0.36, 1)';
+// Horizontal gap between the path centerline and the heading text start.
+const CLERK_TEXT_GAP_FROM_PATH = 12;
+// Radius of numbered step badges rendered on top of the path centerline.
+const CLERK_STEP_BADGE_RADIUS = 7;
+// Visual line offsets by grouped heading depth: 1/2, 3, 4, >4.
+const CLERK_DEPTH_GROUP_LINE_OFFSETS = [6, 18, 30, 42] as const;
+// Max number of characters rendered for a TOC label before trimming with ellipsis.
+const CLERK_MAX_LABEL_LENGTH = 44;
 
 export function PortableClerkTOC({
   toc,
@@ -237,6 +255,7 @@ export function PortableClerkTOCItems({
           item={meta.item}
           isActive={activeAnchors.includes(meta.item.url.slice(1))}
           resolvedContent={meta.resolvedContent}
+          fullTitle={meta.fullTitle}
           itemPadding={meta.itemPadding}
           contentRef={(node: HTMLSpanElement | null) => {
             contentRefs.current[i] = node;
@@ -254,6 +273,7 @@ function PortableClerkTOCItem({
   item,
   isActive,
   resolvedContent,
+  fullTitle,
   itemPadding,
   contentRef,
   ref,
@@ -261,6 +281,7 @@ function PortableClerkTOCItem({
   item: TOCItemType;
   isActive: boolean;
   resolvedContent: ReactNode;
+  fullTitle: string | null;
   itemPadding: number;
   contentRef?: ((node: HTMLSpanElement | null) => void) | null;
   ref?: ((node: HTMLAnchorElement | null) => void) | null;
@@ -270,15 +291,19 @@ function PortableClerkTOCItem({
       ref={ref}
       href={item.url}
       data-clerk-item=""
+      title={fullTitle ?? undefined}
       style={{
         paddingInlineStart: itemPadding,
       }}
       className={cn(
-        'prose group relative py-1.5 text-sm transition-colors wrap-anywhere first:pt-0 last:pb-0 hover:text-fd-accent-foreground',
+        'prose group relative py-1.5 text-sm transition-colors first:pt-0 last:pb-0 hover:text-fd-accent-foreground',
         isActive ? themeIconColor : 'text-fd-muted-foreground',
       )}
     >
-      <span ref={contentRef} className="relative z-10">
+      <span
+        ref={contentRef}
+        className="relative z-10 block overflow-hidden text-ellipsis whitespace-nowrap"
+      >
         {resolvedContent}
       </span>
     </Primitive.TOCItem>
@@ -298,9 +323,39 @@ function ClerkOutline({
   activeAnchors: string[];
   activeEndpoint: { x: number; y: number } | null;
 }) {
-  if (!path) return null;
-
   const activeSet = new Set(activeAnchors);
+  const [displayPath, setDisplayPath] = useState(activePath);
+  const [fadingPath, setFadingPath] = useState<string | null>(null);
+
+  useEffect(() => {
+    if (activePath === displayPath) return;
+    if (!displayPath) {
+      setDisplayPath(activePath);
+      setFadingPath(null);
+      return;
+    }
+
+    setFadingPath(displayPath);
+    setDisplayPath(activePath);
+
+    const timeout = window.setTimeout(() => {
+      setFadingPath(null);
+    }, CLERK_ACTIVE_ANIMATION_DURATION_MS);
+
+    return () => window.clearTimeout(timeout);
+  }, [activePath, displayPath]);
+
+  const dotTranslate = activeEndpoint
+    ? `translate(${activeEndpoint.x - CLERK_ACTIVE_DOT_RADIUS}px, ${
+        activeEndpoint.y - CLERK_ACTIVE_DOT_RADIUS
+      }px)`
+    : undefined;
+  const transitionStyle = {
+    transitionDuration: `${CLERK_ACTIVE_ANIMATION_DURATION_MS}ms`,
+    transitionTimingFunction: CLERK_ACTIVE_ANIMATION_EASING,
+  };
+
+  if (!path) return null;
 
   return (
     <>
@@ -325,32 +380,50 @@ function ClerkOutline({
         width="100%"
         height="100%"
       >
-        {activePath ? (
+        {fadingPath ? (
           <path
-            d={activePath}
+            d={fadingPath}
             fill="none"
             strokeWidth={CLERK_PATH_STROKE_WIDTH}
             strokeLinecap="round"
             strokeLinejoin="round"
             stroke={themeSvgIconColor}
+            className="transition-opacity"
+            style={{
+              opacity: 0,
+              ...transitionStyle,
+            }}
           />
         ) : null}
-      </svg>
-      <svg
-        aria-hidden="true"
-        className="pointer-events-none absolute inset-0 z-0 overflow-visible"
-        width="100%"
-        height="100%"
-      >
-        {activeEndpoint ? (
-          <circle
-            cx={activeEndpoint.x}
-            cy={activeEndpoint.y}
-            r={CLERK_ACTIVE_DOT_RADIUS}
-            fill={themeSvgIconColor}
+        {displayPath ? (
+          <path
+            d={displayPath}
+            fill="none"
+            strokeWidth={CLERK_PATH_STROKE_WIDTH}
+            strokeLinecap="round"
+            strokeLinejoin="round"
+            stroke={themeSvgIconColor}
+            className="transition-opacity"
+            style={{
+              opacity: 1,
+              ...transitionStyle,
+            }}
           />
         ) : null}
       </svg>
+      <div aria-hidden="true" className="pointer-events-none absolute inset-0 z-0">
+        <div
+          className="absolute rounded-full transition-transform"
+          style={{
+            width: CLERK_ACTIVE_DOT_RADIUS * 2,
+            height: CLERK_ACTIVE_DOT_RADIUS * 2,
+            backgroundColor: themeSvgIconColor,
+            transform: dotTranslate,
+            opacity: activeEndpoint ? 1 : 0,
+            ...transitionStyle,
+          }}
+        />
+      </div>
       <svg
         aria-hidden="true"
         className="pointer-events-none absolute inset-0 z-1 overflow-visible"
@@ -365,7 +438,7 @@ function ClerkOutline({
           return (
             <g key={item.url} transform={`translate(${item.x}, ${item.y})`}>
               <circle
-                r="7"
+                r={CLERK_STEP_BADGE_RADIUS}
                 fill={isActive ? themeSvgIconColor : undefined}
                 className={cn(!isActive && 'fill-black dark:fill-white')}
               />
@@ -386,28 +459,40 @@ function ClerkOutline({
 }
 
 function getItemOffset(depth: number): number {
-  if (depth <= 2) return 14;
-  if (depth === 3) return 26;
-  return 36;
+  const lineOffset = getLineOffset(depth);
+  const badgeRadius = depth === 3 ? CLERK_STEP_BADGE_RADIUS : 0;
+  return lineOffset + badgeRadius + CLERK_TEXT_GAP_FROM_PATH;
 }
 
 function getLineOffset(depth: number): number {
-  return depth >= 3 ? 18 : 6;
+  const group = getDepthGroup(depth);
+  return CLERK_DEPTH_GROUP_LINE_OFFSETS[group];
 }
 
 function getVisualLinePosition(depth: number): number {
   return getLineOffset(depth);
 }
 
+function getDepthGroup(depth: number): number {
+  if (depth <= 2) return 0;
+  if (depth === 3) return 1;
+  if (depth === 4) return 2;
+  return 3;
+}
+
 function resolveClerkItem(item: TOCItemType): ClerkItemMeta {
   const isH3 = item.depth === 3;
   const rawTitle = typeof item.title === 'string' ? item.title : '';
   const { isStep, displayStep, content } = getStepInfoFromTitle(rawTitle);
   let stepNumber: string | null = isH3 && isStep ? String(displayStep) : null;
   let resolvedContent: ReactNode = item.title;
+  let fullTitle: string | null = rawTitle || null;
 
   if (isH3 && isStep) {
     resolvedContent = content ?? item.title;
+    if (typeof content === 'string') {
+      fullTitle = content;
+    }
   }
 
   if (isH3 && !stepNumber) {
@@ -419,20 +504,34 @@ function resolveClerkItem(item: TOCItemType): ClerkItemMeta {
         const match = rawTitle.match(/^(\d+(?:\.\d+)*\.?)\s+(.+)$/);
         if (match?.[2]) {
           resolvedContent = match[2];
+          fullTitle = match[2];
         }
       }
     }
   }
 
+  if (typeof resolvedContent === 'string') {
+    fullTitle = resolvedContent;
+    resolvedContent = truncateClerkLabel(resolvedContent);
+  }
+
   return {
     item,
     resolvedContent,
+    fullTitle,
     stepNumber,
     itemPadding: getItemOffset(item.depth),
     lineOffset: getVisualLinePosition(item.depth),
   };
 }
 
+function truncateClerkLabel(value: string): string {
+  const normalized = value.trim();
+  if (normalized.length <= CLERK_MAX_LABEL_LENGTH) return normalized;
+
+  return `${normalized.slice(0, CLERK_MAX_LABEL_LENGTH).trimEnd()}...`;
+}
+
 function buildOutlinePath(items: ClerkItemMeasure[]): string {
   if (items.length === 0) return '';
 
@@ -614,7 +713,7 @@ function mergeRefs<T>(
       }
 
       try {
-        (ref as React.MutableRefObject<T | null>).current = node;
+        (ref as React.RefObject<T | null>).current = node;
       } catch {
         // ignore readonly refs
       }

package/src/styles/fuma.css

@@ -3,6 +3,19 @@
   @apply top-20!;
 }
 
+@media (min-width: 1280px) {
+  /* 给桌面端固定 TOC 留一点底部呼吸感，避免视觉上直接压到 footer */
+  #nd-toc {
+    bottom: 1.25rem !important;
+  }
+
+  /* 文档主区域补一小段底部缓冲，减少 footer 刚进入视口就与 TOC 相撞 */
+  #nd-page {
+    padding-bottom: 5rem !important;
+    min-height: calc(100dvh - 5rem) !important;
+  }
+}
+
 /* 移动端文章目录下拉框的边距，建议移动端不要目录导航 96px */
 #nd-tocnav {
   @apply top-24!;
@@ -35,7 +48,7 @@ button[aria-label="Open Search"][data-search=""] {
 
 /* Custome Fuma Steps */
 .fd-step::before {
-  @apply size-5 -start-2.5 rounded-full;
+  @apply size-5 -inset-s-2.5 rounded-full;
   background-color: #000; 
   color: #fff;
   font-size: 0.75rem; 
@@ -128,4 +141,4 @@ button[aria-label="Open Search"][data-search=""] {
   [data-rmiz-modal-img] {
     transition-duration: 0.01ms !important;
   }
-} 
+}