From b32ecc3e53de3dbcc27964fc7a193cc35ef638c5 Mon Sep 17 00:00:00 2001 From: dks333 Date: Tue, 22 Apr 2025 18:00:45 -0700 Subject: [PATCH 1/5] add react hooks --- docs.json | 7 +- react-hooks.mdx | 210 +++++++++++++++++++++++++++++++++++ snippets/color-generator.mdx | 112 +++++++++++++++++++ snippets/counter.mdx | 32 ++++++ 4 files changed, 357 insertions(+), 4 deletions(-) create mode 100644 react-hooks.mdx create mode 100644 snippets/color-generator.mdx create mode 100644 snippets/counter.mdx diff --git a/docs.json b/docs.json index eb22219d4..0ae694caf 100644 --- a/docs.json +++ b/docs.json @@ -48,7 +48,8 @@ "image-embeds", "list-table", "code", - "reusable-snippets" + "reusable-snippets", + "react-hooks" ] }, { @@ -203,9 +204,7 @@ }, { "group": "Custom Components", - "pages": [ - "content/components/reusable-components" - ] + "pages": ["content/components/reusable-components"] }, { "group": "API Components", diff --git a/react-hooks.mdx b/react-hooks.mdx new file mode 100644 index 000000000..e98a5691c --- /dev/null +++ b/react-hooks.mdx @@ -0,0 +1,210 @@ +--- +title: "React Hooks" +description: "Learn how to use React hooks" +icon: "react" +--- + + +import { Counter } from "/snippets/counter.mdx"; +import { ColorGenerator } from "/snippets/color-generator.mdx"; + +Create interactive examples and dynamic content in your documentation using familiar [React hooks](https://react.dev/reference/react/hooks). + + + No imports needed! All standard React hooks are automatically available in your MDX files. + + +## Available Hooks + +You can use all standard [React hooks](https://react.dev/reference/react/hooks) in your documentation, such as `useState`, `useEffect`, etc. + +## Examples + +### 1. Directly in your MDX file +create a component directly in your MDX file. Use `useState` to create interactive components that respond to user actions: + + + +```jsx file.mdx +export const Counter = () => { + const [count, setCount] = useState(0); + + return ( +
+

Current count: {count}

+ +
+ ); +} + + +``` + + +### 2. Import from a snippet file + +Your snippets can be imported into your MDX files to create interactive components. Snippets should be stored in the `snippets` folder, check out the [snippets](/reusable-snippets) page for more information. + + +Here's an example of a snippet file that creates a color generator component: + + + + + + Create a snippet file in the `snippets` folder. + + ```jsx /snippets/color-generator.mdx [expandable] + export const ColorGenerator = () => { + const [hue, setHue] = useState(180) + const [saturation, setSaturation] = useState(50) + const [lightness, setLightness] = useState(50) + const [colors, setColors] = useState([]) + + useEffect(() => { + const newColors = [] + for (let i = 0; i < 5; i++) { + const l = Math.max(10, Math.min(90, lightness - 20 + i * 10)) + newColors.push(`hsl(${hue}, ${saturation}%, ${l}%)`) + } + setColors(newColors) + }, [hue, saturation, lightness]) + + const copyToClipboard = (color) => { + navigator.clipboard + .writeText(color) + .then(() => { + console.log(`Copied ${color} to clipboard!`) + }) + .catch((err) => { + console.error("Failed to copy: ", err) + }) + } + + return ( +
+ HSL Color Generator + +
+
+ + + + + +
+ +
+ {colors.map((color, idx) => ( +
copyToClipboard(color)} + /> + ))} +
+ +
+

+ Base color: hsl({hue}, {saturation}%, {lightness}%) +

+
+
+
+ ) + } + + ``` + + + On the top of your MDX file, import the snippet: + + ```jsx file.mdx + import { ColorGenerator } from "/snippets/color-generator.mdx" + ``` + + +

Use the component in your MDX file.

+ + ```jsx file.mdx + + ``` + + + + +## Important Considerations + + + + React hook components are client-side rendered, which has several implications: + + - **SEO**: Search engines might not index dynamic content properly + - **Initial Load**: Users might see a flash of loading content before the components render + + + + - **Optimize Dependency Arrays**: Include only necessary dependencies in your `useEffect` dependency arrays + - **Avoid Complex Calculations**: Move expensive operations to `useMemo` or `useCallback` + - **Control Re-renders**: Break large components into smaller ones to prevent unnecessary re-renders + + + + + diff --git a/snippets/color-generator.mdx b/snippets/color-generator.mdx new file mode 100644 index 000000000..6cad52444 --- /dev/null +++ b/snippets/color-generator.mdx @@ -0,0 +1,112 @@ +export const ColorGenerator = () => { + const [hue, setHue] = useState(165) + const [saturation, setSaturation] = useState(84) + const [lightness, setLightness] = useState(31) + const [colors, setColors] = useState([]) + + useEffect(() => { + const newColors = [] + for (let i = 0; i < 5; i++) { + const l = Math.max(10, Math.min(90, lightness - 20 + i * 10)) + newColors.push(`hsl(${hue}, ${saturation}%, ${l}%)`) + } + setColors(newColors) + }, [hue, saturation, lightness]) + + const copyToClipboard = (color) => { + navigator.clipboard + .writeText(color) + .then(() => { + console.log(`Copied ${color} to clipboard!`) + }) + .catch((err) => { + console.error("Failed to copy: ", err) + }) + } + + return ( +
+

HSL Color Generator

+ +
+
+ + + + + +
+ +
+ {colors.map((color, idx) => ( +
copyToClipboard(color)} + /> + ))} +
+ +
+

+ Base color: hsl({hue}, {saturation}%, {lightness}%) +

+
+
+
+ ) +} diff --git a/snippets/counter.mdx b/snippets/counter.mdx new file mode 100644 index 000000000..6e0e583fd --- /dev/null +++ b/snippets/counter.mdx @@ -0,0 +1,32 @@ +export const Counter = () => { + const [count, setCount] = useState(0) + + const increment = () => setCount(count + 1) + const decrement = () => setCount(count - 1) + + return ( +
+
+ + +
+ {count} +
+ + +
+
+ ) +} \ No newline at end of file From 39dee82eb61debc36194bd1255f57c9f17eb1332 Mon Sep 17 00:00:00 2001 From: dks333 Date: Tue, 22 Apr 2025 18:07:05 -0700 Subject: [PATCH 2/5] nits --- react-hooks.mdx | 46 +++++++++++++++++++----------------- snippets/color-generator.mdx | 2 +- snippets/counter.mdx | 4 ++-- 3 files changed, 27 insertions(+), 25 deletions(-) diff --git a/react-hooks.mdx b/react-hooks.mdx index e98a5691c..e9052dae4 100644 --- a/react-hooks.mdx +++ b/react-hooks.mdx @@ -4,7 +4,6 @@ description: "Learn how to use React hooks" icon: "react" --- - import { Counter } from "/snippets/counter.mdx"; import { ColorGenerator } from "/snippets/color-generator.mdx"; @@ -16,16 +15,17 @@ Create interactive examples and dynamic content in your documentation using fami ## Available Hooks -You can use all standard [React hooks](https://react.dev/reference/react/hooks) in your documentation, such as `useState`, `useEffect`, etc. +You can use all standard [React hooks](https://react.dev/reference/react/hooks) in your documentation, such as `useState`, `useEffect`, and other core React functionality. ## Examples -### 1. Directly in your MDX file -create a component directly in your MDX file. Use `useState` to create interactive components that respond to user actions: +### 1. Creating Components Directly in MDX + +Create a component directly in your MDX file using React hooks to build interactive elements that respond to user actions: -```jsx file.mdx +```jsx export const Counter = () => { const [count, setCount] = useState(0); @@ -42,19 +42,18 @@ export const Counter = () => { ``` +![A simple counter component with increment button](/images/counter-example.png) +*A basic counter component created with useState hook* -### 2. Import from a snippet file - -Your snippets can be imported into your MDX files to create interactive components. Snippets should be stored in the `snippets` folder, check out the [snippets](/reusable-snippets) page for more information. +### 2. Importing Components from Snippet Files - -Here's an example of a snippet file that creates a color generator component: +Import snippets into your MDX files to create reusable interactive components. Store snippets in the `snippets` folder for better organization. Learn more in the [reusable snippets documentation](/reusable-snippets). - Create a snippet file in the `snippets` folder. + Create a new file in the `snippets` folder with your component code. ```jsx /snippets/color-generator.mdx [expandable] export const ColorGenerator = () => { @@ -168,41 +167,44 @@ Here's an example of a snippet file that creates a color generator component:
) - } - + } ``` - On the top of your MDX file, import the snippet: + Add an import statement at the top of your MDX file: - ```jsx file.mdx + ```jsx import { ColorGenerator } from "/snippets/color-generator.mdx" ``` -

Use the component in your MDX file.

+

Add the component to your MDX content wherever needed:

- ```jsx file.mdx + ```jsx ``` +![HSL Color Generator component](/images/color-generator.png) +*Interactive HSL color generator created with multiple React hooks* ## Important Considerations - React hook components are client-side rendered, which has several implications: + React hook components render on the client-side, which has several implications: - - **SEO**: Search engines might not index dynamic content properly - - **Initial Load**: Users might see a flash of loading content before the components render + - **SEO**: Search engines might not fully index dynamic content + - **Initial Load**: Visitors may experience a flash of loading content before components render + - **Accessibility**: Ensure dynamic content changes are announced to screen readers - **Optimize Dependency Arrays**: Include only necessary dependencies in your `useEffect` dependency arrays - - **Avoid Complex Calculations**: Move expensive operations to `useMemo` or `useCallback` - - **Control Re-renders**: Break large components into smaller ones to prevent unnecessary re-renders + - **Memoize Complex Calculations**: Use `useMemo` or `useCallback` for expensive operations + - **Reduce Re-renders**: Break large components into smaller ones to prevent cascading re-renders + - **Lazy Loading**: Consider lazy loading complex components to improve initial page load time diff --git a/snippets/color-generator.mdx b/snippets/color-generator.mdx index 6cad52444..ef84154f1 100644 --- a/snippets/color-generator.mdx +++ b/snippets/color-generator.mdx @@ -25,7 +25,7 @@ export const ColorGenerator = () => { } return ( -
+

HSL Color Generator

diff --git a/snippets/counter.mdx b/snippets/counter.mdx index 6e0e583fd..50b526a94 100644 --- a/snippets/counter.mdx +++ b/snippets/counter.mdx @@ -9,7 +9,7 @@ export const Counter = () => {