aidos-ui 4.0.3 → 4.0.5

package/src/pages/useKeyboard.mdx

@@ -1,257 +0,0 @@
-# useKeyboard
-
-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: "Z",
-    metaKey: true,
-    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: (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,258 +0,0 @@
-# useNavigation
-
-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.
-
----
-
-## 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
-import { useNavigation } from "aidos-ui";
-
-function NavigableList() {
-  const rootRef = useNavigation();
-
-  return (
-    <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>
-```