feat: update deprecation warnings

Author: YDX-2147483647

src/components/templates/FuncTemplate.tsx

@@ -42,11 +42,7 @@ export const FuncTemplate: FC<FuncTemplateProps> = ({
 				</small>
 			</h1>
 
-			{content.deprecation && (
-				<div className="mt-2">
-					<DeprecationWarning message={content.deprecation} />
-				</div>
-			)}
+			{<DeprecationWarning item={content} level="top" />}
 
 			<div class="my-4 text-gray-700">
 				<HtmlContent html={content.details} />
@@ -121,7 +117,7 @@ function ScopedDefinitions({
 							<code
 								class="text-base font-medium"
 								style={
-									method.deprecation
+									normalizeDeprecation(method) !== null
 										? { textDecoration: "line-through" }
 										: undefined
 								}
@@ -135,11 +131,7 @@ function ScopedDefinitions({
 							</small>
 						</h3>
 
-						{method.deprecation && (
-							<div className="mt-1">
-								<DeprecationWarning message={method.deprecation} />
-							</div>
-						)}
+						{<DeprecationWarning item={method} level="scoped" />}
 
 						<div class="pl-2">
 							<FunctionDisplay func={method} prefix={methodId} />

src/components/ui/DeprecationWarning.tsx

@@ -1,19 +1,44 @@
 import type { FC } from "hono/jsx";
+import { Translation } from "../../translation/";
+import type { WithDeprecation } from "../../types/model";
+import { normalizeDeprecation } from "../../utils/normalizeModel.js";
 import { AlertTriangleIcon } from "../icons";
 
 type DeprecationWarningProps = {
-	message: string;
+	item: WithDeprecation;
+	level: "top" | "scoped";
 };
 
+/**
+ * Generate a deprecation warning if the item deprecated; return null otherwise.
+ */
 export const DeprecationWarning: FC<DeprecationWarningProps> = ({
-	message,
+	item,
+	level,
 }) => {
-	return (
+	const deprecation = normalizeDeprecation(item);
+	if (!deprecation) {
+		return null;
+	}
+
+	const body = (
 		<small className="deprecation ml-2 flex items-center bg-yellow-50 px-2 py-1 rounded-md border border-yellow-200">
 			<div className="w-4 h-4 text-yellow-500 mr-1.5 flex-shrink-0">
 				<AlertTriangleIcon />
 			</div>
-			<span className="text-xs text-yellow-800">{message}</span>
+			<span className="text-xs text-yellow-800">
+				<Translation
+					translationKey="deprecationWarning"
+					message={deprecation.message}
+					until={deprecation.until}
+				/>
+			</span>
 		</small>
 	);
+
+	return level === "top" ? (
+		<div className="mt-1">{body}</div>
+	) : (
+		<div className="mt-2">{body}</div>
+	);
 };

src/translation/en-US.tsx

@@ -37,6 +37,14 @@ export const Translation: TranslationComponent = (props) => {
 			return <Fragment>Default value:</Fragment>;
 		case "stringValues":
 			return <Fragment>Available string values</Fragment>;
+		case "deprecationWarning":
+			return props.until ? (
+				<Fragment>
+					{props.message}; it will be removed in Typst {props.until}
+				</Fragment>
+			) : (
+				<Fragment>{props.message}</Fragment>
+			);
 		case "showExample":
 			return <Fragment>Show example</Fragment>;
 		case "tableOfContents":

src/translation/index.tsx

@@ -52,6 +52,7 @@ type TranslationComponentKey =
 	| "required"
 	| "requiredDescription"
 	// Other texts in documentation
+	// Don't forget `deprecationWarning` and `showExample` declared below.
 	| "tutorial"
 	| "tutorialDescription"
 	| "reference"
@@ -87,7 +88,13 @@ type TranslationComponentKey =
 
 export type TranslationComponentProps =
 	| { translationKey: TranslationComponentKey }
-	| { translationKey: "definitionsOf"; name: string };
+	| { translationKey: "definitionsOf"; name: string }
+	| {
+			translationKey: "deprecationWarning";
+			message: string;
+			/** A Typst version, e.g. "0.15.0". */
+			until: string | null;
+	  };
 
 /**
  * Translation component for UI text, descriptions, and other content to be embedded as JSX.

src/translation/ja-JP.tsx

@@ -42,6 +42,15 @@ export const Translation: TranslationComponent = (props) => {
 			return <Fragment>デフォルト値：</Fragment>;
 		case "stringValues":
 			return <Fragment>使用可能な文字列値</Fragment>;
+		case "deprecationWarning":
+			return props.until ? (
+				// TODO: Translate this. Don't forget to change `;` to `；`.
+				<Fragment>
+					{props.message}; it will be removed in Typst {props.until}
+				</Fragment>
+			) : (
+				<Fragment>{props.message}</Fragment>
+			);
 		case "showExample":
 			return <Fragment>例を表示</Fragment>;
 		case "tableOfContents":

src/types/model.ts

@@ -171,8 +171,13 @@ type Shorthands = {
 	math: Symbol[];
 };
 
-type WithDeprecation =
+export type WithDeprecation =
 	// Format since Typst v0.14.0-rc.1 (typst/typst#6617)
-	| { deprecation_message: string | null; deprecation_until: string | null }
+	| {
+			// TODO: This message contains markdown. Check if this is a bug of the official typst-docs.
+			deprecation_message: string | null;
+			/** A Typst version without leading `v`. */
+			deprecation_until: string | null;
+	  }
 	// Format for Typst v0.13.1
 	| { deprecation: string | null };

src/utils/normalizeModel.ts

@@ -0,0 +1,28 @@
+/**
+ * Normalize models to the latest format.
+ * @module
+ */
+
+import type { WithDeprecation } from "../types/model";
+
+/**
+ * Return deprecation info if deprecated, return null otherwise.
+ */
+export function normalizeDeprecation(item: WithDeprecation): {
+	message: string;
+	until: string | null;
+} | null {
+	if ("deprecation" in item) {
+		// For v0.13.1
+		return item.deprecation ? { message: item.deprecation, until: null } : null;
+	}
+
+	if (item.deprecation_message) {
+		return { message: item.deprecation_message, until: item.deprecation_until };
+	}
+	if (item.deprecation_until) {
+		// This will never reach for Typst v0.14.0-rc.1 documentation.
+		return { message: item.deprecation_until, until: null };
+	}
+	return null;
+}