aidos-ui 4.0.3 → 4.0.5

package/src/pages/usePromise.mdx

@@ -1,280 +0,0 @@
-# usePromise
-
-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 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 />;
-  }
-
-  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>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,251 +0,0 @@
-# useRefEffect
-
-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
-const ref = useRefEffect((element) => {
-  element.scrollIntoView({ behavior: "smooth" });
-  // No cleanup needed
-});
-```
-
----
-
-## 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) => {
-      // Handle shortcuts...
-    };
-
-    window.addEventListener("keydown", onKeyDown);
-
-    return () => {
-      window.removeEventListener("keydown", onKeyDown);
-    };
-  });
-}
-```
-
----
-
-## 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/src/stateMachineContextFactory.tsx

@@ -1,111 +0,0 @@
-import React, {
-  useContext,
-  useCallback,
-  ReactNode,
-  useMemo,
-  useRef,
-} from "react";
-import { Subscribe, createEmitter, Callback } from "./Emitter";
-
-export type Reducer<State, Context> = <Data extends any>({
-  state,
-  context,
-  data,
-}: {
-  state: State;
-  context: Context;
-  data: Data;
-}) => { state: State; context: Context };
-
-type StateMachineConfig<State, Transition, Context> = {
-  states: {
-    [state: string]: {
-      // @ts-ignore
-      on: { [transition: Transition]: Reducer<State, Context> };
-    };
-  };
-  context: Context;
-  state: State;
-};
-
-type Send = <Transition, Data>(transition: Transition, data: Data) => void;
-
-type StateMachineContextType<State, Context> = {
-  subscribe: Subscribe<{ state: State; context: Context }>;
-  send: Send;
-};
-
-export function stateMachineContextFactory<State, Transition, Context>(
-  stateMachineConfig: StateMachineConfig<State, Transition, Context>
-) {
-  const StateMachineContext = React.createContext<
-    StateMachineContextType<State, Context>
-  >({
-    subscribe: () => {
-      throw new Error("Not implemented");
-    },
-    send: (_) => {
-      throw new Error("Not implemented");
-    },
-  });
-
-  type StateMachineState = {
-    state: State;
-    context: Context;
-  };
-
-  function Provider({ children }: { children: ReactNode }) {
-    const stateMachineRef = useRef<StateMachineState>({
-      state: stateMachineConfig.state,
-      context: stateMachineConfig.context,
-    });
-
-    const emitterRef = useRef(
-      createEmitter<{ state: State; context: Context }>()
-    );
-
-    const subscribe = useCallback((callback: Callback<StateMachineState>) => {
-      const unsbuscribe = emitterRef.current.subscribe(callback);
-      callback(stateMachineRef.current);
-
-      return unsbuscribe;
-    }, []);
-
-    const send = useCallback(
-      <Transition, Data extends any>(transition: Transition, data: Data) => {
-        const state = stateMachineRef.current.state;
-        // @ts-ignore I don't know how to fix this
-        const transitions = stateMachineConfig.states[state].on;
-        const reducer: Reducer<State, Context> = transitions[transition];
-
-        if (!reducer) {
-          // No transition available in the current state, so no update needed
-          return;
-        }
-
-        const newState = reducer({
-          ...stateMachineRef.current,
-          data,
-        });
-
-        stateMachineRef.current = newState;
-        emitterRef.current.emit(newState);
-      },
-      []
-    );
-
-    const value = useMemo(() => ({ subscribe, send }), [subscribe, send]);
-
-    return (
-      <StateMachineContext.Provider value={value}>
-        {children}
-      </StateMachineContext.Provider>
-    );
-  }
-
-  function useStateMachine() {
-    return useContext(StateMachineContext);
-  }
-
-  return { Provider, useStateMachine };
-}