From a6fc12ef9425587877006e8fe562bce45075ad18 Mon Sep 17 00:00:00 2001 From: Robbie Averill Date: Wed, 18 Sep 2024 16:01:43 +1200 Subject: [PATCH 1/4] Children interface is now ReactNode, theme utility methods are deprecated in favour of plugin methods This fixes a type incompatibility where using `guard()` and returning a React or DOM element would not pass type checking. The Children interface now extends ReactNode for backwards compatibility and is marked as depreacated. Use ReactNode directly in future. Duplicated markdown utility functions in the theme are now deprecated in favour of their equivalents in the plugin package. --- .../src/markdown/utils.ts | 13 ++++++++----- .../src/markdown/utils.ts | 14 +++++++++----- 2 files changed, 17 insertions(+), 10 deletions(-) diff --git a/packages/docusaurus-plugin-openapi-docs/src/markdown/utils.ts b/packages/docusaurus-plugin-openapi-docs/src/markdown/utils.ts index f0ffb83b3..1662fc7c7 100644 --- a/packages/docusaurus-plugin-openapi-docs/src/markdown/utils.ts +++ b/packages/docusaurus-plugin-openapi-docs/src/markdown/utils.ts @@ -5,9 +5,12 @@ * LICENSE file in the root directory of this source tree. * ========================================================================== */ -export type Children = string | undefined | (string | string[] | undefined)[]; +import { type ReactNode } from "react"; -export type Props = Record & { children?: Children }; +/** @deprecated use ReactNode from React instead */ +export type Children = ReactNode; + +export type Props = Record & { children?: ReactNode }; export type Options = { inline?: boolean }; @@ -36,7 +39,7 @@ export function create( export function guard( value: T | undefined, - cb: (value: T) => Children + cb: (value: T) => ReactNode ): string { if (!!value || value === 0) { const children = cb(value); @@ -45,14 +48,14 @@ export function guard( return ""; } -export function render(children: Children): string { +export function render(children: ReactNode): string { if (Array.isArray(children)) { const filteredChildren = children.filter((c) => c !== undefined); return filteredChildren .map((i: any) => (Array.isArray(i) ? i.join("") : i)) .join(""); } - return children ?? ""; + return `${children ?? ""}`; } // Regex to selectively URL-encode '>' and '<' chars diff --git a/packages/docusaurus-theme-openapi-docs/src/markdown/utils.ts b/packages/docusaurus-theme-openapi-docs/src/markdown/utils.ts index 1c9539170..c3d6251b6 100644 --- a/packages/docusaurus-theme-openapi-docs/src/markdown/utils.ts +++ b/packages/docusaurus-theme-openapi-docs/src/markdown/utils.ts @@ -7,10 +7,13 @@ import { ReactNode } from "react"; -export type Children = ReactNode | string | undefined | (string | undefined)[]; +/** @deprecated use ReactNode from React instead */ +export type Children = ReactNode; -export type Props = Record & { children?: Children }; +/** @deprecated use Props from docusaurus-plugin-openapi-docs/src/markdown/utils instead */ +export type Props = Record & { children?: ReactNode }; +/** @deprecated use create() from docusaurus-plugin-openapi-docs/src/markdown/utils instead */ export function create(tag: string, props: Props): string { const { children, ...rest } = props; @@ -22,9 +25,10 @@ export function create(tag: string, props: Props): string { return `<${tag}${propString}>${render(children)}`; } +/** @deprecated use guard() from docusaurus-plugin-openapi-docs/src/markdown/utils instead */ export function guard( value: T | undefined | string, - cb: (value: T) => Children + cb: (value: T) => ReactNode ): string { if (!!value || value === 0) { const children = cb(value as T); @@ -33,11 +37,11 @@ export function guard( return ""; } -export function render(children: Children): string { +export function render(children: ReactNode): string { if (Array.isArray(children)) { return children.filter((c) => c !== undefined).join(""); } - return (children as string) ?? ""; + return `${children ?? ""}`; } export function toString(value: any): string | undefined { From 3aa807ae59d920f8883a1173c6ad96b2d5d52095 Mon Sep 17 00:00:00 2001 From: Robbie Averill Date: Tue, 24 Sep 2024 09:19:07 +1200 Subject: [PATCH 2/4] Revert changes to plugin guard() and render() methods, they will not accept ReactNode --- .../src/markdown/utils.ts | 15 ++++++++------- .../src/markdown/utils.ts | 9 +++------ 2 files changed, 11 insertions(+), 13 deletions(-) diff --git a/packages/docusaurus-plugin-openapi-docs/src/markdown/utils.ts b/packages/docusaurus-plugin-openapi-docs/src/markdown/utils.ts index 1662fc7c7..0a09b3310 100644 --- a/packages/docusaurus-plugin-openapi-docs/src/markdown/utils.ts +++ b/packages/docusaurus-plugin-openapi-docs/src/markdown/utils.ts @@ -5,12 +5,13 @@ * LICENSE file in the root directory of this source tree. * ========================================================================== */ -import { type ReactNode } from "react"; +/** + * Children in the plugin does not accept DOM elements, when compared with Children in the theme. + * It is designed for rendering HTML a strings. + */ +export type Children = string | undefined | (string | string[] | undefined)[]; -/** @deprecated use ReactNode from React instead */ -export type Children = ReactNode; - -export type Props = Record & { children?: ReactNode }; +export type Props = Record & { children?: Children }; export type Options = { inline?: boolean }; @@ -39,7 +40,7 @@ export function create( export function guard( value: T | undefined, - cb: (value: T) => ReactNode + cb: (value: T) => Children ): string { if (!!value || value === 0) { const children = cb(value); @@ -48,7 +49,7 @@ export function guard( return ""; } -export function render(children: ReactNode): string { +export function render(children: Children): string { if (Array.isArray(children)) { const filteredChildren = children.filter((c) => c !== undefined); return filteredChildren diff --git a/packages/docusaurus-theme-openapi-docs/src/markdown/utils.ts b/packages/docusaurus-theme-openapi-docs/src/markdown/utils.ts index c3d6251b6..66feab5c0 100644 --- a/packages/docusaurus-theme-openapi-docs/src/markdown/utils.ts +++ b/packages/docusaurus-theme-openapi-docs/src/markdown/utils.ts @@ -10,10 +10,8 @@ import { ReactNode } from "react"; /** @deprecated use ReactNode from React instead */ export type Children = ReactNode; -/** @deprecated use Props from docusaurus-plugin-openapi-docs/src/markdown/utils instead */ export type Props = Record & { children?: ReactNode }; -/** @deprecated use create() from docusaurus-plugin-openapi-docs/src/markdown/utils instead */ export function create(tag: string, props: Props): string { const { children, ...rest } = props; @@ -25,11 +23,10 @@ export function create(tag: string, props: Props): string { return `<${tag}${propString}>${render(children)}`; } -/** @deprecated use guard() from docusaurus-plugin-openapi-docs/src/markdown/utils instead */ export function guard( value: T | undefined | string, cb: (value: T) => ReactNode -): string { +) { if (!!value || value === 0) { const children = cb(value as T); return render(children); @@ -37,11 +34,11 @@ export function guard( return ""; } -export function render(children: ReactNode): string { +export function render(children: ReactNode) { if (Array.isArray(children)) { return children.filter((c) => c !== undefined).join(""); } - return `${children ?? ""}`; + return children; } export function toString(value: any): string | undefined { From 4a81586d29d5ff1ce713d32dca203c886bda99fc Mon Sep 17 00:00:00 2001 From: Robbie Averill Date: Tue, 24 Sep 2024 09:20:55 +1200 Subject: [PATCH 3/4] Revert string casting in plugin utils --- packages/docusaurus-plugin-openapi-docs/src/markdown/utils.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/docusaurus-plugin-openapi-docs/src/markdown/utils.ts b/packages/docusaurus-plugin-openapi-docs/src/markdown/utils.ts index 0a09b3310..c4dfe1663 100644 --- a/packages/docusaurus-plugin-openapi-docs/src/markdown/utils.ts +++ b/packages/docusaurus-plugin-openapi-docs/src/markdown/utils.ts @@ -56,7 +56,7 @@ export function render(children: Children): string { .map((i: any) => (Array.isArray(i) ? i.join("") : i)) .join(""); } - return `${children ?? ""}`; + return children ?? ""; } // Regex to selectively URL-encode '>' and '<' chars From 2fcfe32f377fa3f2fa297fb4229bd59fd60ed7f4 Mon Sep 17 00:00:00 2001 From: Robbie Averill Date: Tue, 24 Sep 2024 09:21:38 +1200 Subject: [PATCH 4/4] Restore fallback to empty string when children is falsy --- packages/docusaurus-theme-openapi-docs/src/markdown/utils.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/docusaurus-theme-openapi-docs/src/markdown/utils.ts b/packages/docusaurus-theme-openapi-docs/src/markdown/utils.ts index 66feab5c0..b3b53872a 100644 --- a/packages/docusaurus-theme-openapi-docs/src/markdown/utils.ts +++ b/packages/docusaurus-theme-openapi-docs/src/markdown/utils.ts @@ -38,7 +38,7 @@ export function render(children: ReactNode) { if (Array.isArray(children)) { return children.filter((c) => c !== undefined).join(""); } - return children; + return children ?? ""; } export function toString(value: any): string | undefined {