Handle deprecation notes in reference items

Author: davepagurek

src/components/ReferenceDirectoryWithFilter/index.tsx

@@ -3,6 +3,7 @@ import { useMemo, useRef, useState } from "preact/hooks";
 import { type JSX } from "preact";
 import { Icon } from "../Icon";
 import flask from "@src/content/ui/images/icons/flask.svg?raw"; 
+import warning from "@src/content/ui/images/icons/warning.svg?raw"; 
 
 type ReferenceDirectoryEntry = ReferenceDocContentItem & {
   data: {
@@ -43,6 +44,10 @@ const getOneLineDescription = (description: string): string => {
   let [oneLineDescription] = description.replace(/\n/g, " ").trim()
     .match(firstParagraphRegex) ?? [];
 
+  if (!oneLineDescription && description) {
+    oneLineDescription = description;
+  }
+
   if(oneLineDescription){
     oneLineDescription = oneLineDescription
       .replace(/^<p>|<\/p>$/g, "")
@@ -108,6 +113,12 @@ export const ReferenceDirectoryWithFilter = ({
                     dangerouslySetInnerHTML={{ __html: flask }}
                   />
                 )}
+                {entry.data.deprecated && (
+                  <div
+                    className="inline-block mr-2 w-[16px] h-[16px] mb-[-2px]"
+                    dangerouslySetInnerHTML={{ __html: warning }}
+                  />
+                )}
                 <span dangerouslySetInnerHTML={{ __html: entry.data.title }} />
               </span>
               <p

src/content/reference/config.ts

@@ -64,6 +64,7 @@ export const referenceSchema = z.object({
   submodule: z.string().optional(),
   file: z.string(),
   description: z.string().optional(),
+  deprecated: z.string().optional(),
   line: z.number().or(z.string().transform((v) => parseInt(v, 10))),
   params: z.array(paramSchema).optional(),
   overloads: z.array(z.object({ params: z.array(paramSchema) })).optional(),

src/content/ui/en.yaml

@@ -186,6 +186,7 @@ calloutTitles:
   "Try this!": "Try this!"
   Tip: Tip
   Note: Note
+  Warning: Warning
 LibrariesLayout:
   View All: View All
   Featured: Featured

src/content/ui/images/icons/warning.svg

@@ -20,6 +20,7 @@ import type {
 import { setJumpToState } from "../globals/state";
 import { p5Version } from "../globals/p5-version";
 import flask from "@src/content/ui/images/icons/flask.svg?raw"; 
+import warning from "@src/content/ui/images/icons/warning.svg?raw"; 
 
 const { entry, relatedEntries } = Astro.props;
 const currentLocale = getCurrentLocale(Astro.url.pathname);
@@ -106,6 +107,18 @@ const descriptionParts = description.split(
           <p>{t('experimentalApi', 'description')}</p>
         </div>
       )}
+      {entry.data.deprecated && (
+        <div class="deprecated">
+          <h5>
+            <div
+              class="inline-block mr-2 w-[20px] h-[20px] mb-[-2px]"
+              set:html={warning}
+            />
+            {t('calloutTitles', 'Warning')}
+          </h5>
+          <p set:html={entry.data.deprecated} />
+        </div>
+      )}
       {descriptionParts.map((part) => {
         if (part.startsWith('<pre')) {
           const exampleCode = part

src/layouts/ReferenceItemLayout.astro

@@ -255,6 +255,7 @@ const convertToMDX = async (
     file: doc.file.replace(/.*p5\.js\/(.*)/, "$1"),
     description: doc.description ?? "",
     line: doc.line,
+    deprecated: doc.deprecated,
   } as Record<string, unknown>;
 
   // Add specific frontmatter based on the type of doc

src/scripts/builders/reference.ts

@@ -291,7 +291,7 @@ pre.code-box,
   white-space: break-spaces;
 }
 
-.callout, .experimental {
+.callout, .experimental, .deprecated {
   padding: var(--spacing-sm);
   border-radius: 20px;
   background-color: var(--bg-magenta-20);
@@ -308,7 +308,7 @@ pre.code-box,
   }
 }
 
-.experimental {
+.experimental, .deprecated {
   background-color: var(--bg-yellow);
 }
 

styles/global.scss

@@ -49,7 +49,7 @@ export type ReferenceOverload = {
 export type ReferenceOverloads = ReferenceOverload[];
 
 /* Represents the definition of a class within the project, including its properties, methods, and inheritance information. */
-export interface ReferenceClassDefinition extends Chainable {
+export interface ReferenceClassDefinition extends Chainable, Deprecatable, MaybeBeta {
   name: string; // The name of the class.
   shortname: string; // A shorter or abbreviated name for the class.
   classitems: ReferenceParam[]; // Parameters or properties of the class.
@@ -92,6 +92,10 @@ interface Chainable {
   chainable: number;
 }
 
+interface Deprecatable {
+  deprecated?: string; // If this item is deprecated, a description of why.
+}
+
 /* Represents the return value of a method or constructor */
 interface Return {
   description: string;
@@ -103,7 +107,7 @@ interface MaybeBeta {
 }
 
 /* Represents a method within a class */
-export interface ReferenceClassItemMethod extends BaseClassItem, Chainable, MaybeBeta {
+export interface ReferenceClassItemMethod extends BaseClassItem, Chainable, MaybeBeta, Deprecatable {
   params?: ReferenceParam[];
   return?: Return;
   example?: string[];
@@ -119,7 +123,7 @@ interface MethodOverload {
 }
 
 /* Represents a property within a class */
-export interface ReferenceClassItemProperty extends BaseClassItem {
+export interface ReferenceClassItemProperty extends BaseClassItem, Deprecatable {
   type: string;
 }