fix: Correct anchor IDs of functions and their parameters (#232)

Co-authored-by: Copilot <[email protected]>

Author: YDX-2147483647

website/src/components/templates/FuncTemplate.tsx

@@ -57,7 +57,7 @@ export const FuncTemplate: FC<FuncTemplateProps> = ({
 			</h2>
 
 			<div class="mb-6">
-				<FunctionDefinition func={content} prefix={content.name} />
+				<FunctionDefinition func={content} />
 			</div>
 
 			{content.example && (
@@ -67,7 +67,7 @@ export const FuncTemplate: FC<FuncTemplateProps> = ({
 			)}
 
 			<div class="my-6">
-				<FunctionParameters func={content} prefix={content.name} />
+				<FunctionParameters func={content} />
 			</div>
 
 			{content.scope.length > 0 && (

website/src/components/templates/GroupTemplate.tsx

@@ -41,7 +41,7 @@ export const GroupTemplate: FC<GroupTemplateProps> = ({
 
 					{content.functions.map((method, index) => (
 						<div key={method.name}>
-							<h3 id={`definitions-${method.name}`} class="method-head">
+							<h3 id={`functions-${method.name}`} class="method-head">
 								<code class="text-base font-medium">{method.name}</code>
 								<div class="flex flex-wrap items-center gap-2 text-sm">
 									{method.element && <Tooltip kind="element" />}
@@ -50,7 +50,7 @@ export const GroupTemplate: FC<GroupTemplateProps> = ({
 							</h3>
 							<FunctionDisplay
 								func={method}
-								prefix={`definitions-${method.name}`}
+								prefix={`functions-${method.name}`}
 								isExampleFolding={false}
 							/>
 						</div>

website/src/components/ui/FunctionDefinition.tsx

@@ -2,16 +2,21 @@ import type { FC } from "hono/jsx";
 import type { Func } from "../../types/model";
 import { TypeIcon } from "./TypeIcon";
 import { genPath } from "./genPath";
-import { type2href } from "./type2href";
+import { buildParamId, type2href } from "./type2href";
 
 type FunctionDefinitionProps = {
 	func: Func;
-	prefix?: string;
+	/**
+	 * The prefix for parameter IDs
+	 *
+	 * See `buildParamId`.
+	 */
+	prefix?: string | undefined;
 };
 
 export const FunctionDefinition: FC<FunctionDefinitionProps> = ({
 	func,
-	prefix = "",
+	prefix = undefined,
 }) => {
 	return (
 		<div class="bg-gray-50 p-4 rounded-md border border-gray-100 overflow-x-auto">
@@ -28,7 +33,7 @@ export const FunctionDefinition: FC<FunctionDefinitionProps> = ({
 							{!param.positional && (
 								<div class="flex-shrink-0">
 									<a
-										href={`#${prefix}-${func.name}-parameters-${param.name}`}
+										href={`#${buildParamId(param.name, prefix)}`}
 										class="text-gray-800 hover:text-blue-500 transition-colors mr-1"
 									>
 										<span class="font-medium">{param.name}</span>

website/src/components/ui/FunctionDisplay.tsx

@@ -7,13 +7,18 @@ import { HtmlContent } from "./HtmlContent";
 
 type FunctionDisplayProps = {
 	func: Func;
-	prefix?: string;
+	/**
+	 * The prefix for IDs of function parameters
+	 *
+	 * See `buildParamId`.
+	 */
+	prefix?: string | undefined;
 	isExampleFolding?: boolean;
 };
 
 export const FunctionDisplay: FC<FunctionDisplayProps> = ({
 	func,
-	prefix = "",
+	prefix = undefined,
 	isExampleFolding = true,
 }) => {
 	return (

website/src/components/ui/FunctionParameters.tsx

@@ -4,16 +4,21 @@ import { ChevronRightIcon } from "../icons";
 import { HtmlContent } from "./HtmlContent";
 import { Tooltip } from "./Tooltip";
 import { TypeIcon } from "./TypeIcon";
-import { type2href } from "./type2href";
+import { buildParamId, type2href } from "./type2href";
 
 type FunctionParametersProps = {
 	func: Func;
-	prefix?: string;
+	/**
+	 * The prefix for IDs
+	 *
+	 * See `buildParamId`.
+	 */
+	prefix?: string | undefined;
 };
 
 export const FunctionParameters: FC<FunctionParametersProps> = ({
 	func,
-	prefix = "",
+	prefix = undefined,
 }) => {
 	return (
 		<div class="space-y-6">
@@ -23,7 +28,7 @@ export const FunctionParameters: FC<FunctionParametersProps> = ({
 					class="bg-gray-50 rounded-md p-4 border border-gray-100"
 				>
 					<h4
-						id={`${prefix}-${func.name}-parameters-${param.name}`}
+						id={buildParamId(param.name, prefix)}
 						class="flex flex-wrap items-center gap-2 mb-3"
 					>
 						<code class="text-base font-medium">{param.name}</code>

website/src/components/ui/common/TableOfContents.tsx

@@ -4,6 +4,30 @@ export type TableOfContentsProps = {
 	outline: OutlineItem[];
 };
 
+const PlainTableOfContents = ({
+	outline,
+	topLevel = false,
+}: TableOfContentsProps & { topLevel?: boolean }) => {
+	return (
+		// Indent for succeeding levels
+		<ol class={`space-y-1 ${!topLevel && "pl-4"} text-sm text-neutral-700`}>
+			{outline.map((item) => (
+				<li key={item.id} data-assoc={item.id}>
+					<a
+						href={`#${item.id}`}
+						class="block px-2 py-1 rounded hover:bg-neutral-100 transition-colors"
+					>
+						{item.name}
+					</a>
+					{item.children.length > 0 && (
+						<PlainTableOfContents outline={item.children} />
+					)}
+				</li>
+			))}
+		</ol>
+	);
+};
+
 export const TableOfContents = ({ outline }: TableOfContentsProps) => {
 	if (outline.length === 0) {
 		return null;
@@ -17,18 +41,7 @@ export const TableOfContents = ({ outline }: TableOfContentsProps) => {
 			<strong class="block mb-2 text-sm text-neutral-500 font-semibold tracking-wide">
 				目次
 			</strong>
-			<ol class="space-y-1 text-sm text-neutral-700">
-				{outline.map((item) => (
-					<li key={item.id} data-assoc={item.id}>
-						<a
-							href={`#${item.id}`}
-							class="block px-2 py-1 rounded hover:bg-neutral-100 transition-colors"
-						>
-							{item.name}
-						</a>
-					</li>
-				))}
-			</ol>
+			<PlainTableOfContents outline={outline} topLevel={true} />
 		</nav>
 	);
 };

website/src/components/ui/type2href.ts

@@ -58,3 +58,28 @@ export const type2href = (parameterType: string): string | null => {
 	}
 	return null;
 };
+
+/**
+ * Build the ID of a parameter with prefix
+ *
+ * If the parameter belongs to a top-level function on a page, leave `prefix` empty;
+ * Otherwise, set it to an appropriate prefix.
+ *
+ * ## Example values of `prefix`
+ *
+ * | Page (kind)         | Function         | Parameter  | `prefix`                |
+ * | ------------------- | ---------------- | ---------- | ----------------------- |
+ * | `figure` (function) | `figure`         | `body`     | `undefined`             |
+ * | `figure` (function) | `figure.caption` | `body`     | `"definitions-caption"` |
+ * | `calc` (group)      | `calc.abs`       | `value`    | `"functions-abs"`       |
+ * | `array` (type)      | `array.at`       | `index`    | `"definitions-at"`      |
+ * | `array` (type)      | Constructor      | `value`    | `"constructor"`      |
+ */
+export function buildParamId(
+	parameterName: string,
+	prefix: string | undefined,
+): string {
+	return prefix === undefined
+		? `parameters-${parameterName}`
+		: `${prefix}-${parameterName}`;
+}