aidos-ui 4.0.0 → 4.0.2

package/src/pages/useCookie.mdx

@@ -1,15 +1,176 @@
 # useCookie
 
-`useCookie` is a hook that can be used to get acceess to cookies by name, and use them as if they were React component state.
+A React hook for reading and writing browser cookies with React state-like API. Handles SSR gracefully and persists values across page reloads.
+
+---
+
+## Signature
+
+```ts
+function useCookie<T, L>(
+  key: string,
+  options: {
+    initialValue: T;
+    loadingValue: L;
+    serialize?: (value: T) => string;
+    deserialize?: (value: string) => T;
+    maxAge?: number;
+  }
+): [T | L, (value: T | ((prev: T | L) => T)) => void]
+```
+
+---
+
+## Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `key` | `string` | Required | Cookie name |
+| `options.initialValue` | `T` | Required | Value to set if cookie doesn't exist |
+| `options.loadingValue` | `L` | Required | Value to use during SSR or initial load |
+| `options.serialize` | `(T) => string` | `JSON.stringify` | Custom serialization function |
+| `options.deserialize` | `(string) => T` | `JSON.parse` | Custom deserialization function |
+| `options.maxAge` | `number` | 1 year | Cookie expiration in seconds |
+
+---
+
+## Returns
+
+Returns a tuple similar to `useState`:
+
+1. **Current value** - The cookie value (or `loadingValue` during SSR)
+2. **Setter function** - Updates the cookie (accepts value or callback)
+
+---
+
+## Basic usage
+
+```js
+import { useCookie } from "aidos-ui";
+
+function Settings() {
+  const [theme, setTheme] = useCookie("theme", {
+    initialValue: "light",
+    loadingValue: "light",
+  });
+
+  return (
+    <Button onClick={() => setTheme(theme === "light" ? "dark" : "light")}>
+      Current: {theme}
+    </Button>
+  );
+}
+```
+
+---
+
+## With callback setter
+
+Like `useState`, the setter accepts a callback function:
+
+```js
+const [count, setCount] = useCookie("visit-count", {
+  initialValue: 0,
+  loadingValue: 0,
+});
+
+// Increment based on previous value
+setCount((prev) => prev + 1);
+```
+
+---
+
+## SSR handling
+
+The `loadingValue` is used during server-side rendering when cookies aren't available:
 
 ```js
-const [darkModeEnabled, setDarkModeEnabled] = useCookie("dark-mode", {
-  initialValue: false,
-  // loadingValue could be different to initial value for example if we are server rendering,
-  // in which case we do not have access to cookies and you may decide to assign another
-  // value, like "pending".
-  loadingValue: false,
+const [user, setUser] = useCookie("user-preferences", {
+  initialValue: { notifications: true },
+  loadingValue: null, // Renders nothing during SSR
+});
+
+if (user === null) {
+  return <Spinner />;
+}
+
+return <Settings preferences={user} />;
+```
+
+---
+
+## Custom serialization
+
+For complex data or non-JSON formats:
+
+```js
+const [date, setDate] = useCookie("last-visit", {
+  initialValue: new Date(),
+  loadingValue: null,
+  serialize: (d) => d.toISOString(),
+  deserialize: (s) => new Date(s),
 });
 ```
 
 ---
+
+## Custom expiration
+
+Set cookie expiration with `maxAge` (in seconds):
+
+```js
+// Expire in 1 hour
+const [session, setSession] = useCookie("session", {
+  initialValue: null,
+  loadingValue: null,
+  maxAge: 60 * 60, // 1 hour
+});
+
+// Expire in 30 days
+const [preferences, setPreferences] = useCookie("prefs", {
+  initialValue: {},
+  loadingValue: {},
+  maxAge: 60 * 60 * 24 * 30, // 30 days
+});
+```
+
+---
+
+## Helper functions
+
+The module also exports utility functions:
+
+```js
+import { hasCookie, getCookie } from "aidos-ui";
+
+// Check if cookie exists
+if (hasCookie("user-token")) {
+  // ...
+}
+
+// Get cookie value directly
+const token = getCookie("user-token");
+```
+
+---
+
+## Dark mode example
+
+```js
+function App() {
+  const [darkMode, setDarkMode] = useCookie("dark-mode", {
+    initialValue: false,
+    loadingValue: false,
+  });
+
+  useEffect(() => {
+    document.body.classList.toggle("dark-mode", darkMode);
+  }, [darkMode]);
+
+  return (
+    <Button onClick={() => setDarkMode(!darkMode)}>
+      {darkMode ? "Light mode" : "Dark mode"}
+    </Button>
+  );
+}
+```

package/src/pages/useKeyboard.mdx

@@ -1,20 +1,257 @@
 # useKeyboard
 
-This hook can be used to create keyboard shortcuts to make using a website easier and more accessible.
+A React hook for creating keyboard shortcuts. Useful for improving accessibility and power-user workflows.
+
+---
+
+## Signature
+
+```ts
+function useKeyboard<T extends HTMLElement>(
+  shortcuts: Array<KeyboardShortcut<T>>
+): (root: T) => void
+```
+
+---
+
+## KeyboardShortcut type
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `key` | `string` | Required | The key to listen for (case-insensitive) |
+| `metaKey` | `boolean` | - | Require Cmd/Meta key (macOS) |
+| `ctrlKey` | `boolean` | - | Require Ctrl key |
+| `action` | `(root: T) => void` | Required | Function to execute when shortcut triggers |
+| `onlyWhenFocused` | `boolean` | - | Only trigger when the element is focused |
+
+---
+
+## Basic usage
+
+```js
+import { useKeyboard } from "aidos-ui";
+
+function SearchInput() {
+  const [query, setQuery] = useState("");
+
+  const ref = useKeyboard([
+    {
+      key: "Escape",
+      onlyWhenFocused: true,
+      action: () => setQuery(""),
+    },
+  ]);
+
+  return (
+    <input
+      ref={ref}
+      value={query}
+      onChange={(e) => setQuery(e.target.value)}
+      placeholder="Search..."
+    />
+  );
+}
+```
+
+---
+
+## Global shortcuts
+
+Create app-wide keyboard shortcuts by attaching to a root element:
+
+```js
+function App() {
+  const searchRef = useRef(null);
+
+  const rootRef = useKeyboard([
+    {
+      key: "K",
+      metaKey: true,
+      action: () => searchRef.current?.focus(),
+    },
+    {
+      key: "/",
+      action: () => searchRef.current?.focus(),
+    },
+  ]);
+
+  return (
+    <div ref={rootRef}>
+      <SearchInput ref={searchRef} />
+      {/* Rest of app */}
+    </div>
+  );
+}
+```
+
+---
+
+## Focus management
+
+Combine with `onlyWhenFocused` to create context-aware shortcuts:
+
+```js
+function CommandPalette() {
+  const [open, setOpen] = useState(false);
+  const [query, setQuery] = useState("");
+
+  const ref = useKeyboard([
+    {
+      key: "K",
+      metaKey: true,
+      action: () => setOpen(true),
+    },
+    {
+      key: "Escape",
+      onlyWhenFocused: true,
+      action: () => {
+        if (query) {
+          setQuery("");
+        } else {
+          setOpen(false);
+        }
+      },
+    },
+  ]);
+
+  return (
+    <div ref={ref}>
+      {open && (
+        <Dialog>
+          <TextInput
+            value={query}
+            onValueChange={setQuery}
+            placeholder="Type a command..."
+          />
+        </Dialog>
+      )}
+    </div>
+  );
+}
+```
+
+---
+
+## Modifier keys
+
+Use `metaKey` and `ctrlKey` for modifier-based shortcuts:
 
 ```js
 const ref = useKeyboard([
+  // Cmd+S (macOS) / Ctrl+S (Windows/Linux)
+  {
+    key: "S",
+    metaKey: true,
+    action: () => saveDocument(),
+  },
+  // Ctrl+Enter
+  {
+    key: "Enter",
+    ctrlKey: true,
+    action: () => submitForm(),
+  },
+  // Cmd+Shift doesn't have a dedicated prop, but you can handle it:
   {
-    key: "K",
+    key: "Z",
     metaKey: true,
-    action: (root) => root.focus(),
+    action: (root) => {
+      // Check for Shift in the action if needed
+      if (window.event?.shiftKey) {
+        redo();
+      } else {
+        undo();
+      }
+    },
   },
+]);
+```
+
+---
+
+## Multiple shortcuts
+
+Register multiple shortcuts at once:
+
+```js
+const ref = useKeyboard([
+  { key: "ArrowUp", action: () => selectPrevious() },
+  { key: "ArrowDown", action: () => selectNext() },
+  { key: "Enter", action: () => confirm() },
+  { key: "Escape", action: () => cancel() },
+  { key: "Delete", action: () => remove() },
+  { key: "Backspace", action: () => remove() },
+]);
+```
+
+---
+
+## With TypeScript
+
+The hook is generic and preserves the element type:
+
+```ts
+// HTMLInputElement
+const inputRef = useKeyboard<HTMLInputElement>([
   {
     key: "Escape",
     onlyWhenFocused: true,
-    action: () => {
-      setQuery("");
+    action: (input) => {
+      input.value = "";  // TypeScript knows this is HTMLInputElement
+      input.blur();
     },
   },
 ]);
+
+// HTMLDivElement
+const divRef = useKeyboard<HTMLDivElement>([
+  {
+    key: "Space",
+    action: (div) => div.click(),
+  },
+]);
 ```
+
+---
+
+## Common patterns
+
+### Text editor shortcuts
+
+```js
+const ref = useKeyboard([
+  { key: "B", metaKey: true, action: () => toggleBold() },
+  { key: "I", metaKey: true, action: () => toggleItalic() },
+  { key: "U", metaKey: true, action: () => toggleUnderline() },
+  { key: "Z", metaKey: true, action: () => undo() },
+]);
+```
+
+### Navigation shortcuts
+
+```js
+const ref = useKeyboard([
+  { key: "H", action: () => navigate("/") },
+  { key: "S", action: () => navigate("/settings") },
+  { key: "?", action: () => showHelp() },
+]);
+```
+
+### List navigation
+
+```js
+const ref = useKeyboard([
+  { key: "J", action: () => selectNext() },
+  { key: "K", action: () => selectPrevious() },
+  { key: "G", action: () => selectFirst() },
+  { key: "G", ctrlKey: true, action: () => selectLast() },
+]);
+```
+
+---
+
+## Implementation details
+
+- Shortcuts are registered globally via `window.addEventListener`
+- Key matching is case-insensitive
+- The hook cleans up listeners when the component unmounts
+- Built on top of `useRefEffect` for reliable effect management

package/src/pages/useNavigation.mdx

@@ -1,30 +1,258 @@
 # useNavigation
 
-The `useNavigation` hook is easy to use but complicated under the hood, so I expect there will be situations in which it will break, especially if the HTML markup is not perfectly correct. The gist of it is that it enables keyboard navigation by manipulating the `tabInde` property for all the elements under a certain element (the root). To the 'active' element we assign the `tabIndex` 0, while every other elements gets assigned `tabIndex` -1. This means that the whole area will be a single tab stop. Then, when we detect the arrow down or right we push change the active element by changing the `tabInde` and calling `element.focus()`.
+A React hook that enables keyboard navigation within a container element. Implements the [WAI-ARIA grid pattern](https://www.w3.org/WAI/ARIA/apg/patterns/grid/examples/layout-grids/) for accessible keyboard navigation.
 
-This is following the [grid layout pattern](https://www.w3.org/WAI/ARIA/apg/patterns/grid/examples/layout-grids/).
+---
+
+## Signature
+
+```ts
+function useNavigation(options?: {
+  autofocus?: boolean;
+  rowLength?: number;
+  enabled?: boolean;
+}): (root: HTMLElement) => void
+```
+
+---
+
+## Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `autofocus` | `boolean` | `false` | Automatically focus the first item on mount |
+| `rowLength` | `number` | `1` | Number of items per row (for grid layouts) |
+| `enabled` | `boolean` | `true` | Enable/disable navigation |
+
+---
+
+## Basic usage
 
 ```js
-export function List() {
+import { useNavigation } from "aidos-ui";
+
+function NavigableList() {
   const rootRef = useNavigation();
 
   return (
-    <ul aria-label={ariaLabel} ref={rootRef}>
-      <li>
-        <button>Button 1</button>
-      </li>
-      <li>
-        <button>Button 2</button>
-      </li>
-      <li>
-        <button>Button 3</button>
-      </li>
-      <li>
-        <button>Button 4</button>
-      </li>
+    <ul ref={rootRef} aria-label="Options">
+      <li><button>Option 1</button></li>
+      <li><button>Option 2</button></li>
+      <li><button>Option 3</button></li>
     </ul>
   );
 }
 ```
 
 ---
+
+## How it works
+
+The hook manages `tabIndex` on focusable elements within the container:
+
+1. The "active" element gets `tabIndex="0"`
+2. All other elements get `tabIndex="-1"`
+3. This makes the entire area a single Tab stop
+4. Arrow keys move focus between elements
+
+**Keyboard controls:**
+- **Arrow Down / Arrow Right**: Move to next item
+- **Arrow Up / Arrow Left**: Move to previous item
+- Navigation wraps around at the ends
+
+---
+
+## List navigation
+
+import { List } from "../List";
+import { ListButtonItem } from "../ListButtonItem";
+
+<List ariaLabel="example" navigation={true}>
+  <ListButtonItem color="secondary" headline="Headline 1" onClick={() => {}} />
+  <ListButtonItem color="secondary" headline="Headline 2" onClick={() => {}} />
+  <ListButtonItem
+    withDivider={false}
+    color="secondary"
+    headline="Headline 3"
+    onClick={() => {}}
+  />
+</List>
+
+```js
+<List ariaLabel="example" navigation={true}>
+  <ListButtonItem headline="Headline 1" onClick={() => {}} />
+  <ListButtonItem headline="Headline 2" onClick={() => {}} />
+  <ListButtonItem headline="Headline 3" onClick={() => {}} />
+</List>
+```
+
+---
+
+## Disabled navigation
+
+<List ariaLabel="example" navigation={false}>
+  <ListButtonItem color="secondary" headline="Headline 1" onClick={() => {}} />
+  <ListButtonItem color="secondary" headline="Headline 2" onClick={() => {}} />
+  <ListButtonItem
+    withDivider={false}
+    color="secondary"
+    headline="Headline 3"
+    onClick={() => {}}
+  />
+</List>
+
+```js
+<List ariaLabel="example" navigation={false}>
+  <ListButtonItem headline="Headline 1" onClick={() => {}} />
+  <ListButtonItem headline="Headline 2" onClick={() => {}} />
+  <ListButtonItem headline="Headline 3" onClick={() => {}} />
+</List>
+```
+
+---
+
+## Grid navigation
+
+For grid layouts, set `rowLength` to enable proper up/down navigation:
+
+```js
+function IconGrid() {
+  const rootRef = useNavigation({ rowLength: 4 });
+
+  return (
+    <div
+      ref={rootRef}
+      style={{
+        display: "grid",
+        gridTemplateColumns: "repeat(4, 1fr)",
+      }}
+    >
+      {icons.map((icon) => (
+        <button key={icon.name} onClick={() => selectIcon(icon)}>
+          <Icon icon={icon.name} />
+        </button>
+      ))}
+    </div>
+  );
+}
+```
+
+With `rowLength: 4`:
+- Arrow Left/Right moves horizontally
+- Arrow Up/Down moves vertically (jumps 4 items)
+
+---
+
+## Autofocus
+
+Focus the first item automatically when the component mounts:
+
+```js
+function DropdownMenu({ items }) {
+  const rootRef = useNavigation({ autofocus: true });
+
+  return (
+    <ul ref={rootRef} role="menu">
+      {items.map((item) => (
+        <li key={item.id} role="menuitem">
+          <button onClick={item.action}>{item.label}</button>
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
+---
+
+## Conditional navigation
+
+Enable or disable navigation dynamically:
+
+```js
+function EditableList({ isEditing }) {
+  const rootRef = useNavigation({
+    enabled: !isEditing,  // Disable during edit mode
+  });
+
+  return (
+    <ul ref={rootRef}>
+      {items.map((item) => (
+        <li key={item.id}>
+          {isEditing ? (
+            <TextInput value={item.name} />
+          ) : (
+            <button>{item.name}</button>
+          )}
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
+---
+
+## Dynamic lists
+
+The hook uses a MutationObserver to handle items being added or removed:
+
+```js
+function DynamicList() {
+  const [items, setItems] = useState(initialItems);
+  const rootRef = useNavigation();
+
+  const addItem = () => {
+    setItems([...items, { id: Date.now(), name: "New Item" }]);
+  };
+
+  return (
+    <div>
+      <button onClick={addItem}>Add Item</button>
+      <ul ref={rootRef}>
+        {items.map((item) => (
+          <li key={item.id}>
+            <button>{item.name}</button>
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+```
+
+---
+
+## Implementation notes
+
+- Uses `queryFocusables()` to find focusable elements (buttons, links, inputs, etc.)
+- Manages focus state via `tabIndex` manipulation
+- Handles wrap-around navigation at list boundaries
+- Observes DOM mutations to handle dynamic content
+- Built on `useRefEffect` for cleanup management
+
+---
+
+## Accessibility
+
+This hook helps implement accessible keyboard navigation:
+
+- Makes complex widgets keyboard-accessible
+- Follows WAI-ARIA grid pattern recommendations
+- Reduces Tab stops for better keyboard efficiency
+- Works with screen readers
+
+For best results, combine with proper ARIA attributes:
+
+```js
+<ul
+  ref={rootRef}
+  role="listbox"
+  aria-label="Select an option"
+>
+  <li role="option" aria-selected={selected === 1}>
+    <button>Option 1</button>
+  </li>
+  {/* ... */}
+</ul>
+```