aidos-ui 4.0.0 → 4.0.2

package/src/pages/usePromise.mdx

@@ -1,15 +1,280 @@
 # usePromise
 
-This hook can be used to unwrap a promsie value, with an initial value that can be assigned while the promise has not resolved.
+A React hook for unwrapping Promise values into React state. Handles loading, success, and error states automatically.
+
+---
+
+## Signature
+
+```ts
+function usePromise<T>(
+  promiseFactory: () => Promise<T>,
+  inputs: Array<any>,
+  initialValue: T
+): [T | null, any]
+```
+
+---
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `promiseFactory` | `() => Promise<T>` | Factory function that returns a Promise |
+| `inputs` | `Array<any>` | Dependency array (like useEffect deps) |
+| `initialValue` | `T` | Value to use before the Promise resolves |
+
+---
+
+## Returns
+
+A tuple with two elements:
+
+| Index | Type | Description |
+|-------|------|-------------|
+| `0` | `T \| null` | The resolved value, or `initialValue` while loading |
+| `1` | `any` | Error if the Promise rejected, otherwise `null` |
+
+---
+
+## Basic usage
+
+```js
+import { usePromise } from "aidos-ui";
+
+function UserProfile({ userId }) {
+  const [user, error] = usePromise(
+    () => fetchUser(userId),
+    [userId],
+    null
+  );
+
+  if (error) {
+    return <ErrorMessage error={error} />;
+  }
+
+  if (!user) {
+    return <LoadingSpinner />;
+  }
+
+  return <div>{user.name}</div>;
+}
+```
+
+---
+
+## With initial value
+
+Provide an initial value to show immediately while loading:
+
+```js
+function Counter() {
+  const [count, error] = usePromise(
+    () => fetchCurrentCount(),
+    [],
+    0  // Show 0 while loading
+  );
+
+  return <span>{count}</span>;
+}
+```
+
+---
+
+## Dependency-based refetching
+
+The Promise re-executes when dependencies change:
+
+```js
+function SearchResults({ query }) {
+  const [results, error] = usePromise(
+    () => searchAPI(query),
+    [query],  // Refetch when query changes
+    []
+  );
+
+  return (
+    <ul>
+      {results.map((result) => (
+        <li key={result.id}>{result.title}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+---
+
+## Error handling
+
+```js
+function DataDisplay() {
+  const [data, error] = usePromise(
+    () => fetchData(),
+    [],
+    null
+  );
+
+  if (error) {
+    return (
+      <Card>
+        <Span color="negative">Error: {error.message}</Span>
+        <Button onClick={() => window.location.reload()}>
+          Retry
+        </Button>
+      </Card>
+    );
+  }
+
+  if (!data) {
+    return <Spinner />;
+  }
+
+  return <DataTable data={data} />;
+}
+```
+
+---
+
+## Multiple async calls
+
+Use multiple `usePromise` hooks for parallel data fetching:
 
 ```js
-function Foo() {
-  const [result, error] = usePromise(Promise.resolve(10));
+function Dashboard() {
+  const [stats, statsError] = usePromise(
+    () => fetchStats(),
+    [],
+    null
+  );
+
+  const [notifications, notifError] = usePromise(
+    () => fetchNotifications(),
+    [],
+    []
+  );
+
+  const [user, userError] = usePromise(
+    () => fetchCurrentUser(),
+    [],
+    null
+  );
+
+  const isLoading = !stats || !user;
+  const hasError = statsError || notifError || userError;
+
+  if (hasError) {
+    return <ErrorPage />;
+  }
+
+  if (isLoading) {
+    return <LoadingSkeleton />;
+  }
 
-  if (error != null) {
-    return <p>{error}</p>;
+  return (
+    <Column gap="large">
+      <StatsWidget stats={stats} />
+      <NotificationList notifications={notifications} />
+      <UserGreeting user={user} />
+    </Column>
+  );
+}
+```
+
+---
+
+## With typed responses
+
+```ts
+interface User {
+  id: string;
+  name: string;
+  email: string;
+}
+
+function UserCard({ userId }: { userId: string }) {
+  const [user, error] = usePromise<User | null>(
+    () => fetchUser(userId),
+    [userId],
+    null
+  );
+
+  // user is typed as User | null
+  if (user) {
+    return <span>{user.name}</span>;
   }
 
-  return <span>{result}</span>;
+  return <span>Loading...</span>;
+}
+```
+
+---
+
+## Conditional fetching
+
+Use dependencies to control when fetching occurs:
+
+```js
+function OptionalData({ shouldFetch, id }) {
+  const [data, error] = usePromise(
+    () => shouldFetch ? fetchData(id) : Promise.resolve(null),
+    [shouldFetch, id],
+    null
+  );
+
+  // ...
 }
 ```
+
+---
+
+## Comparison with other approaches
+
+### vs. plain useEffect
+
+```js
+// ❌ Manual state management
+const [data, setData] = useState(null);
+const [error, setError] = useState(null);
+
+useEffect(() => {
+  fetchData()
+    .then(setData)
+    .catch(setError);
+}, []);
+
+// ✅ usePromise - cleaner
+const [data, error] = usePromise(() => fetchData(), [], null);
+```
+
+### vs. React Query / SWR
+
+`usePromise` is simpler but lacks:
+- Caching
+- Background refetching
+- Stale-while-revalidate
+- Automatic retries
+
+Use `usePromise` for simple cases; consider React Query or SWR for complex data fetching needs.
+
+---
+
+## Best practices
+
+1. **Use meaningful initial values** - Choose values that make sense for your UI (empty array for lists, null for objects)
+
+2. **Handle all states** - Always check for error and loading states
+
+3. **Keep factories stable** - Avoid creating new functions on each render:
+
+```js
+// ❌ Creates new function each render
+const [data] = usePromise(() => fetch(`/api/${id}`), [id], null);
+
+// ✅ Factory only changes when id changes
+const [data] = usePromise(
+  () => fetchById(id),
+  [id],
+  null
+);
+```

package/src/pages/useRefEffect.mdx

@@ -1,42 +1,192 @@
 # useRefEffect
 
-This effect is useful when you want to run an effect for a component once only (`useEffect` does not reliably do this). This implies that this component cannot have dependencies in the way other hooks do. Other hooks in this library are implemented using this.
+A React hook that reliably runs an effect once when an element is mounted. Unlike `useEffect`, this hook guarantees single execution and proper cleanup, making it ideal for setting up event listeners and DOM manipulations.
+
+---
+
+## Signature
+
+```ts
+function useRefEffect<T>(
+  callback: (root: T) => (() => void) | void
+): (root: T) => void
+```
+
+---
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `callback` | `(root: T) => (() => void) \| void` | Function called when the element mounts. Can return a cleanup function. |
+
+---
+
+## Returns
+
+A ref callback function that should be passed to the element's `ref` prop.
+
+---
+
+## Why use this?
+
+React's `useEffect` with an empty dependency array doesn't reliably run only once due to:
+- Strict Mode double-invocation in development
+- Concurrent rendering behaviors
+- Fast refresh during development
+
+`useRefEffect` solves this by using a ref callback pattern that guarantees:
+- The effect runs exactly once when the element mounts
+- Cleanup runs exactly once when the element unmounts
+- No dependency array needed
+
+---
+
+## Basic usage
+
+```js
+import { useRefEffect } from "aidos-ui";
+
+function ResizeObserverComponent() {
+  const ref = useRefEffect((element) => {
+    const observer = new ResizeObserver((entries) => {
+      console.log("Size changed:", entries[0].contentRect);
+    });
+
+    observer.observe(element);
+
+    // Return cleanup function
+    return () => observer.disconnect();
+  });
+
+  return <div ref={ref}>Resize me!</div>;
+}
+```
+
+---
+
+## Event listeners
+
+Perfect for attaching event listeners to elements:
+
+```js
+function DraggableElement() {
+  const ref = useRefEffect((element) => {
+    let isDragging = false;
+    let startX = 0;
+    let startY = 0;
+
+    const onMouseDown = (e) => {
+      isDragging = true;
+      startX = e.clientX;
+      startY = e.clientY;
+    };
+
+    const onMouseMove = (e) => {
+      if (!isDragging) return;
+      const dx = e.clientX - startX;
+      const dy = e.clientY - startY;
+      element.style.transform = `translate(${dx}px, ${dy}px)`;
+    };
+
+    const onMouseUp = () => {
+      isDragging = false;
+    };
+
+    element.addEventListener("mousedown", onMouseDown);
+    window.addEventListener("mousemove", onMouseMove);
+    window.addEventListener("mouseup", onMouseUp);
+
+    return () => {
+      element.removeEventListener("mousedown", onMouseDown);
+      window.removeEventListener("mousemove", onMouseMove);
+      window.removeEventListener("mouseup", onMouseUp);
+    };
+  });
+
+  return <div ref={ref}>Drag me</div>;
+}
+```
+
+---
+
+## DOM measurements
+
+Use for operations that need the actual DOM element:
+
+```js
+function MeasuredElement() {
+  const [dimensions, setDimensions] = useState(null);
+
+  const ref = useRefEffect((element) => {
+    const rect = element.getBoundingClientRect();
+    setDimensions({
+      width: rect.width,
+      height: rect.height,
+    });
+  });
+
+  return (
+    <div ref={ref}>
+      {dimensions && (
+        <span>
+          {dimensions.width}x{dimensions.height}
+        </span>
+      )}
+    </div>
+  );
+}
+```
+
+---
+
+## Third-party library integration
+
+Initialize libraries that need a DOM element:
+
+```js
+function ChartComponent({ data }) {
+  const ref = useRefEffect((element) => {
+    const chart = new SomeChartLibrary(element, {
+      data,
+      width: 400,
+      height: 300,
+    });
+
+    return () => chart.destroy();
+  });
+
+  return <div ref={ref} />;
+}
+```
+
+---
+
+## Without cleanup
+
+If no cleanup is needed, simply don't return anything:
 
 ```js
-import { useRefEffect } from "./useRefEffect";
+const ref = useRefEffect((element) => {
+  element.scrollIntoView({ behavior: "smooth" });
+  // No cleanup needed
+});
+```
+
+---
 
-export type KeyboardShortcut<T> = {
-  key: string;
-  metaKey?: boolean;
-  ctrlKey?: boolean;
-  action: (root: T) => void;
-  onlyWhenFocused?: boolean;
-};
+## Building other hooks
 
+`useRefEffect` is the foundation for other hooks in this library:
+
+```js
+// useKeyboard is built on useRefEffect
 export function useKeyboard<T extends HTMLElement>(
   shortcuts: Array<KeyboardShortcut<T>>
 ) {
   return useRefEffect<T>((root: T) => {
     const onKeyDown = (e: KeyboardEvent) => {
-      for (const {
-        metaKey,
-        key,
-        action,
-        ctrlKey,
-        onlyWhenFocused,
-      } of shortcuts) {
-        if (metaKey && e.metaKey !== true) {
-          continue;
-        } else if (ctrlKey && e.ctrlKey !== true) {
-          continue;
-        } else if (onlyWhenFocused && document.activeElement !== root) {
-          continue;
-        }
-
-        if (e.key.toLowerCase() === key.toLowerCase()) {
-          action(root);
-        }
-      }
+      // Handle shortcuts...
     };
 
     window.addEventListener("keydown", onKeyDown);
@@ -47,3 +197,55 @@ export function useKeyboard<T extends HTMLElement>(
   });
 }
 ```
+
+---
+
+## TypeScript usage
+
+The hook is generic and preserves element types:
+
+```ts
+// Typed as HTMLInputElement
+const inputRef = useRefEffect<HTMLInputElement>((input) => {
+  input.focus();
+  input.select();
+});
+
+// Typed as HTMLCanvasElement
+const canvasRef = useRefEffect<HTMLCanvasElement>((canvas) => {
+  const ctx = canvas.getContext("2d");
+  // ctx is properly typed
+});
+```
+
+---
+
+## Comparison with useEffect
+
+```js
+// ❌ useEffect - may run multiple times in dev/strict mode
+useEffect(() => {
+  const element = ref.current;
+  if (!element) return;
+
+  element.addEventListener("click", handler);
+  return () => element.removeEventListener("click", handler);
+}, []);
+
+// ✅ useRefEffect - runs exactly once
+const ref = useRefEffect((element) => {
+  element.addEventListener("click", handler);
+  return () => element.removeEventListener("click", handler);
+});
+```
+
+---
+
+## How it works
+
+The hook uses a ref callback combined with a cleanup ref:
+
+1. When the element mounts, the callback receives the element
+2. The callback's return value (cleanup function) is stored
+3. When the element unmounts (ref receives `null`), cleanup runs
+4. The callback is memoized with `useCallback` to prevent re-runs

package/tsconfig.json

@@ -1,11 +1,16 @@
 {
   "compilerOptions": {
-    "lib": ["dom", "dom.iterable", "es2020", "es2020.string"],
+    "lib": [
+      "dom",
+      "dom.iterable",
+      "es2020",
+      "es2020.string"
+    ],
     "target": "ES2020",
     "module": "esnext",
     "sourceMap": true,
     "outDir": "dist/",
-    "jsx": "preserve",
+    "jsx": "react-jsx",
     "moduleResolution": "node",
     "esModuleInterop": true,
     "declaration": true,
@@ -18,6 +23,10 @@
     "resolveJsonModule": true,
     "isolatedModules": true
   },
-  "include": ["src/*"],
-  "exclude": ["node_modules"]
+  "include": [
+    "src/*"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
 }