# Hooks

In a widget built from the canonical template, hooks live in two places:

| Location | What goes there | Example in the template |
|----------|-----------------|-------------------------|
| `src/features/<name>/hooks/` | Hooks of one domain: query keys and TanStack Query hooks over the feature's `api/` (or `service/`) | `src/features/entities/hooks/useEntities.ts` (`entityKeys`, `useEntities`, `useCreateEntity`) |
| `src/shared/hooks/` | Generic hooks with no domain | `src/shared/hooks/useDebouncedValue.ts` |

Dynamic UI also exports hooks (for example `useDPortalContext`, `useDContext`, `useFormatCurrency`); use them directly from `@dynamic-framework/ui-react`. See `modyo://docs/widgets/components-hooks`.

---

## Feature hooks

A feature's hooks wrap its `api/` functions with TanStack Query and are exported through the feature's `index.ts`:

```ts
// src/features/entities/index.ts
export { entityKeys, useCreateEntity, useEntities } from './hooks/useEntities';
```

- Inside the feature, `ui/` imports them by relative path: `import { useCreateEntity, useEntities } from '../hooks/useEntities';`
- Outside the feature (`src/pages/`, another feature), they are imported through `@/features/<name>`.
- `hooks/` reaches the network only through `api/` (or `service/`) and never imports `ui/`.

Keys, queries and mutations: `modyo://docs/widgets/patterns-tanstack-query`.

---

## Shared hooks

Hooks without a domain go in `src/shared/hooks/`. They must not import features, `src/app/` or `src/pages/`. From `src/shared/hooks/useDebouncedValue.ts`:

```ts
import { useEffect, useState } from 'react';

export function useDebouncedValue<T>(value: T, delay = 300): T {
  const [debounced, setDebounced] = useState(value);

  useEffect(() => {
    const id = setTimeout(() => setDebounced(value), delay);
    return () => clearTimeout(id);
  }, [value, delay]);

  return debounced;
}
```

Used by the reference feature's list to search only after the user stops typing:

```tsx
import { useDebouncedValue } from '@/shared/hooks/useDebouncedValue';

  const [searchQuery, setSearchQuery] = useState('');
  const search = useDebouncedValue(searchQuery, SEARCH_DEBOUNCE);

  const { data, isLoading, isError, refetch } = useEntities({ search });
```

---

## UI state

The template has no global UI store. UI state (an input value, a pending flag, an error flag) lives in the component that owns it, with React's `useState` or `useReducer`. Remote data stays in TanStack Query; do not copy it into local state.

From `src/features/entities/ui/EntityCreateModal.tsx`:

```tsx
  const [name, setName] = useState('');
  const [isPending, setIsPending] = useState(false);
  const [isError, setIsError] = useState(false);
```

When two components need the same UI state, lift it to their closest common parent and pass it down through props. Which modal is open is handled by Dynamic UI's portal context (`openPortal` / `closePortal` from `useDPortalContext`), not by local state.

---

## Naming

The template uses these names; follow them in new features:

| Element | Pattern | Template example |
|---------|---------|------------------|
| Hook file of a feature | `use<Domains>.ts` | `useEntities.ts` |
| Query keys | `<domain>Keys` | `entityKeys` |
| List query hook | `use<Domains>` | `useEntities` |
| Mutation hook | `use<Action><Domain>` | `useCreateEntity` |
| Shared hook | `use<Purpose>` | `useDebouncedValue` |

---

## See also

- `modyo://docs/widgets/patterns-tanstack-query` — query keys, queries and mutations
- `modyo://docs/widgets/patterns-features` — feature layers and import graph
- `modyo://docs/widgets/components-hooks` — hooks exported by Dynamic UI
