Merge pull request #28 from Enterwell/stage

Stage

apps/docs/components/docs/ComponentDocs.tsx

@@ -0,0 +1,72 @@
+import { parse as parseJsDoc } from 'comment-parser';
+import { Mdx } from './Mdx';
+import { Fragment } from 'react';
+import hooksApi from '@enterwell/hooks/dist/hooks.api.json';
+import uiApi from '@enterwell/ui/dist/ui.api.json';
+
+type ComponentDocsProps = {
+    component: React.FunctionComponent;
+};
+
+const api = [
+    ...hooksApi.members.find((m: any) => m.kind === "EntryPoint")?.members ?? [],
+    ...uiApi.members.find((m: any) => m.kind === "EntryPoint")?.members ?? []
+];
+
+function componentMember(component: React.FunctionComponent) {
+    return api?.find((m: any) => m.name === component.name);
+}
+
+function componentComment(component: React.FunctionComponent) {
+    const member = componentMember(component);
+    const comments = member ? parseJsDoc(member.docComment) : undefined;
+    return comments?.at(0);
+}
+
+export function ComponentDescription({ component }: ComponentDocsProps) {
+    const comment = componentComment(component);
+    const { description } = comment || {};
+
+    return (
+        <Mdx>{description}</Mdx>
+    )
+}
+
+export function ComponentParameters({ component }: ComponentDocsProps) {
+    const member = componentMember(component);
+    const comment = componentComment(component);
+    const params = member?.parameters?.map((param) => ({
+        name: param.parameterName,
+        description: comment?.tags?.find((tag) => tag.tag === 'param' && tag.name === param.parameterName)?.description,
+        optional: param.isOptional,
+        type: member.excerptTokens.slice(param.parameterTypeTokenRange.startIndex, param.parameterTypeTokenRange.endIndex).map(t => t.text).join(' '),
+    }));
+
+    if (!params?.length) {
+        return (
+            <div className="text-center text-gray-400">
+                <p>No parameters</p>
+            </div>
+        );
+    };
+
+    return (
+        <div className="grid grid-cols-1 sm:grid-cols-[auto_auto_1fr] gap-x-4 gap-y-1 items-center mt-2">
+            {params?.map((param: any) => (
+                <Fragment key={param.name}>
+                    <div>
+                        <span className="text-xl font-bold">{param.name}</span>
+                    </div>
+                    <div>
+                        {param.type && <span className="text-muted-foreground">{param.type}</span>}
+                        {param.optional && <span className="text-muted-foreground"> (optional)</span>}
+                    </div>
+                    <div>
+                        <Mdx>{param.description?.trim().slice(1)}</Mdx>
+                    </div>
+                    <hr className="sm:hidden" />
+                </Fragment>
+            ))}
+        </div>
+    )
+}

apps/docs/components/docs/Mdx.tsx

@@ -0,0 +1,20 @@
+import { evaluateSync } from "@mdx-js/mdx";
+import * as provider from "@mdx-js/react";
+import { useMDXComponents } from "nextra/mdx";
+import React from "react";
+import * as runtime from "react/jsx-runtime";
+
+export function Mdx({ children }: { children?: string }) {
+    if (!children) return null;
+
+    const { default: MDXContent } = evaluateSync(children, {
+        ...runtime,
+        ...provider,
+        useMDXComponents,
+        format: "mdx",
+        development: false,
+        Fragment: React.Fragment
+    });
+
+    return <MDXContent />;
+}

apps/docs/package.json

@@ -21,11 +21,15 @@
   "dependencies": {
     "@emotion/react": "^11.11.1",
     "@emotion/styled": "^11.11.0",
+    "@enterwell/hooks": "workspace:*",
     "@enterwell/ui": "workspace:*",
+    "@mdx-js/mdx": "^2.3.0",
+    "@mdx-js/react": "^2.3.0",
     "@mui/icons-material": "5.14.8",
     "@mui/lab": "5.0.0-alpha.143",
     "@mui/material": "^5.14.8",
     "classix": "^2.1.34",
+    "comment-parser": "^1.4.0",
     "next": "13.4.19",
     "nextra": "latest",
     "nextra-theme-docs": "latest",

apps/docs/pages/hooks/hooks/use-debounce.mdx

@@ -1,8 +1,19 @@
+import { useDebounce } from '@enterwell/hooks';
+import { ComponentDescription, ComponentParameters } from '../../../components/docs/ComponentDocs';
+
 # useDebounce
 
-Use `useDebounce` to debounce a value.
+## Description
+
+<ComponentDescription component={useDebounce} />
+
+### Parameters
+
+<ComponentParameters component={useDebounce} />
+
+## Example
 
-```ts filename="demo.ts" {2}
+```ts filename="example.ts" {4}
 import { useDebounce } from '@enterwell/hooks';
 
 const [value, setValue] = useState(0);

apps/docs/pages/hooks/hooks/use-debounced-effect.mdx

@@ -0,0 +1,22 @@
+import { useDebouncedEffect } from '@enterwell/hooks';
+import { ComponentDescription, ComponentParameters } from '../../../components/docs/ComponentDocs';
+
+# useDebouncedEffect
+
+## Description
+
+<ComponentDescription component={useDebouncedEffect} />
+
+### Parameters
+
+<ComponentParameters component={useDebouncedEffect} />
+
+## Example
+
+```ts filename="example.ts" {3-5}
+import { useDebouncedEffect } from '@enterwell/hooks';
+
+useDebouncedEffect(() => {
+    // Do effect stuff here
+}, [], 500);
+```

apps/docs/pages/hooks/hooks/use-isomorphic-layout-effect.mdx

@@ -1,10 +1,19 @@
+import { useIsomorphicLayoutEffect } from '@enterwell/hooks';
+import { ComponentDescription, ComponentParameters } from '../../../components/docs/ComponentDocs';
+
 # useIsomorphicLayoutEffect
 
-Use `useIsomorphicLayoutEffect` to run layout effects in both the server and the client.
+## Description
+
+<ComponentDescription component={useIsomorphicLayoutEffect} />
+
+### Parameters
+
+<ComponentParameters component={useIsomorphicLayoutEffect} />
 
-This hook runs `useLayoutEffect` on the client and `useEffect` on the server.
+## Example
 
-```ts filename="demo.ts" {3-6}
+```ts filename="example.ts" {3-6}
 import { useIsomorphicLayoutEffect } from '@enterwell/hooks';
 
 useIsomorphicLayoutEffect(() => {

apps/docs/pages/hooks/hooks/use-resize-observer.mdx

@@ -1,6 +1,17 @@
-# useDebounce
+import { useResizeObserver } from '@enterwell/hooks';
+import { ComponentDescription, ComponentParameters } from '../../../components/docs/ComponentDocs';
+
+# useResizeObserver
+
+## Description
+
+<ComponentDescription component={useResizeObserver} />
+
+### Parameters
+
+<ComponentParameters component={useResizeObserver} />
 
-Use `useResizeObserver` to observe the size of an element. The hook returns a ref that you need to attach to the element you want to observe. The callback function is called with the element and the `ResizeObserverEntry` object.
+## Example
 
 ```tsx filename="demo.ts" {3-6,9-11}
 import { useResizeObserver } from '@enterwell/hooks';

apps/docs/pages/ui/components/dropdown-button.mdx

@@ -1,6 +1,18 @@
+import { DropdownButton } from '@enterwell/ui';
 import { ComponentWithSource } from '../../../components/docs/ComponentWithSource.tsx';
 import { ExampleDropdownButton } from '../../../components/ExampleDropdownButton.tsx';
+import { ComponentDescription, ComponentParameters } from '../../../components/docs/ComponentDocs';
 
 # DropdownButton
 
+## Description
+
+<ComponentDescription component={DropdownButton} />
+
+### Parameters
+
+<ComponentParameters component={DropdownButton} />
+
+## Example
+
 <ComponentWithSource component={ExampleDropdownButton} centered />

apps/docs/pages/ui/components/page-drawer.mdx

@@ -1,6 +1,18 @@
+import { PageDrawer } from '@enterwell/ui';
 import { ComponentWithSource } from '../../../components/docs/ComponentWithSource.tsx';
 import { ExamplePageDrawer } from '../../../components/ExamplePageDrawer.tsx';
+import { ComponentDescription, ComponentParameters } from '../../../components/docs/ComponentDocs';
 
-# PageDrawer
+# DropdownButton
+
+## Description
+
+<ComponentDescription component={PageDrawer} />
+
+### Parameters
+
+<ComponentParameters component={PageDrawer} />
+
+## Example
 
 <ComponentWithSource component={ExamplePageDrawer} />

apps/docs/theme.config.tsx

@@ -65,7 +65,6 @@ const config: DocsThemeConfig = {
         />
         <meta name="og:image" content={socialCard} />
         <meta name="apple-mobile-web-app-title" content="Enterwell UI" />
-        <link rel="icon" href="/ui/favicon.svg" type="image/svg+xml" />
         <link rel="icon" href="/ui/favicon.png" type="image/png" />
         <link
           rel="icon"

packages/hooks/hooks/useDebounce.ts

@@ -1,4 +1,5 @@
-import { useState, useEffect } from 'react';
+import { useState } from 'react';
+import { useDebouncedEffect } from './useDebouncedEffect';
 
 /**
  * Debounce hook.
@@ -9,16 +10,6 @@ import { useState, useEffect } from 'react';
  */
 export function useDebounce<T>(value: T, delay: number) {
     const [debouncedValue, setDebouncedValue] = useState(value);
-
-    useEffect(() => {
-        const handler = setTimeout(() => {
-            setDebouncedValue(value);
-        }, delay);
-
-        return () => {
-            clearTimeout(handler);
-        };
-    }, [value, delay]);
-
+    useDebouncedEffect(setDebouncedValue, [value, delay], delay);
     return debouncedValue;
 }

packages/hooks/hooks/useDebouncedEffect.ts

@@ -0,0 +1,18 @@
+import { useEffect } from "react";
+
+/**
+ * Hook that provides the debouncing functionality with a given callback.
+ *
+ * @param effect - Effect function to call on debounce
+ * @param deps - Effect dependencies
+ * @param delay - Debounce delay
+ * @public
+ */
+export function useDebouncedEffect(effect: Function, deps: unknown[], delay: number) {
+    useEffect(() => {
+        const handler = setTimeout(() => effect(), delay);
+
+        return () => clearTimeout(handler);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [...(deps || []), delay]);
+}

packages/hooks/hooks/useIsomorphicLayoutEffect.ts

@@ -1,7 +1,9 @@
 import { useEffect, useLayoutEffect } from 'react'
 
 /**
- * Isomorphic layout effect hook.
+ * Use `useIsomorphicLayoutEffect` to run layout effects in both the server and the client.
+ * 
+ * This hook runs `useLayoutEffect` on the client and `useEffect` on the server.
  * @public
  */
 export const useIsomorphicLayoutEffect = typeof window !== 'undefined' ? useLayoutEffect : useEffect

packages/hooks/hooks/useResizeObserver.ts

@@ -2,7 +2,7 @@ import { useRef } from 'react';
 import { useIsomorphicLayoutEffect } from './useIsomorphicLayoutEffect';
 
 /**
- * The resize observer hook.
+ * Use `useResizeObserver` to observe the size of an element. The hook returns a ref that you need to attach to the element you want to observe. The callback function is called with the element and the `ResizeObserverEntry` object.
  * @param callback - The callback.
  * @returns The ref.
  * @public

packages/hooks/index.ts

@@ -1,4 +1,5 @@
 // hook exports
+export * from "./hooks/useDebouncedEffect";
 export * from "./hooks/useDebounce";
 export * from "./hooks/useIsomorphicLayoutEffect";
 export * from "./hooks/useResizeObserver";

packages/hooks/temp/hooks.api.md

@@ -10,6 +10,9 @@ import { useEffect } from 'react';
 // @public
 export function useDebounce<T>(value: T, delay: number): T;
 
+// @public
+export function useDebouncedEffect(effect: Function, deps: unknown[], delay: number): void;
+
 // @public
 export const useIsomorphicLayoutEffect: typeof useEffect;
 

packages/ui/index.tsx

@@ -1,3 +1,5 @@
+'use client';
+
 // component exports
 export * from "./DropdownButton";
 export * from "./PageDrawer";