@windrun-huaiin/third-ui 14.4.0 → 14.4.1

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,14 @@ 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;
 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] }));
 }
@@ -128,22 +136,44 @@ function PortableClerkTOCItem({ item, isActive, resolvedContent, itemPadding, co
         }, 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 }) }));
 }
 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;

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,14 @@ 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;
 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] }));
 }
@@ -107,22 +115,44 @@ function PortableClerkTOCItem({ item, isActive, resolvedContent, itemPadding, co
         }, 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 }) }));
 }
 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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@windrun-huaiin/third-ui",
-  "version": "14.4.0",
+  "version": "14.4.1",
   "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,
@@ -57,6 +62,14 @@ 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;
 
 export function PortableClerkTOC({
   toc,
@@ -298,9 +311,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 +368,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 +426,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,9 +447,9 @@ 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 {
@@ -614,7 +675,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
       }