# `MishkaGervaz.Table.Dsl.Hooks`
[🔗](https://github.com/mishka-group/mishka_gervaz/blob/v0.0.1-alpha.3/lib/mishka_gervaz/table/dsl/hooks.ex#L1)

Hooks section DSL definition for table configuration.

Defines lifecycle callbacks for table events.

## Three layers

1. **Global lifecycle** — fires for every event of a kind (`before_delete`,
   `after_delete`, `on_realtime`, `on_filter`, …). These keep their existing
   behavior.

2. **Per-action observers** — fire alongside the built-in handler for a
   specific row or bulk action, keyed by the action's `name`. They cannot
   replace the handler; they observe and decorate it.

     - `before_row_action :name, fn record, state -> ... end`
     - `after_row_action  :name, fn result, state -> ... end`
     - `on_row_action_success :name, fn result, state[, socket] -> socket end`
     - `on_row_action_error   :name, fn reason, state[, socket] -> socket end`
     - `before_bulk_action :name, fn ids, state -> ... end`
     - `after_bulk_action  :name, fn result, state -> ... end`
     - `on_bulk_action_success :name, fn result, state[, socket] -> socket end`
     - `on_bulk_action_error   :name, fn errors, state[, socket] -> socket end`

   The `on_*_success` / `on_*_error` hooks accept arity 2 or 3. Use arity 3
   when you need the live socket for full manual control (e.g. to call
   `DataLoader.apply_archive_status/3`, `Phoenix.LiveView.push_navigate/2`,
   `put_flash/3`, etc). Arity 2 is fine for log-only side effects.

   A list of action names is also accepted to share one hook across actions:
   `before_row_action [:unarchive, :restore], fn ... end`.

3. **Full overrides** — replace the built-in handler entirely. These are the
   same runtime as the legacy `{:on_event, name}` / `{:on_bulk_action, name}`
   keys; the DSL aliases below are the documented form.

     - `override_row_action  :name, fn payload, state -> {:ok, state} end`
     - `override_bulk_action :name, fn ids, state -> {:ok, state} end`

4. **Built-in state-transition rules** — opt-in flags for common UX
   transitions, declared directly inside `hooks do … end`:

     hooks do
       switch_to_active_on_empty_archive true
       clear_selection_after_bulk true
       reset_page_on_empty_current_page true
       redirect_on_empty "/dashboard"
     end

## Return Values

Most hooks can return:
- `socket` - Continue with modified socket
- `{:cont, socket}` - Explicitly continue with modified socket
- `{:halt, socket}` - Stop the action (e.g., skip realtime update, cancel expand)

## Example

    hooks do
      on_realtime fn notification, socket ->
        if notification.data.created_by_id == socket.assigns.current_user.id do
          {:halt, socket}
        else
          {:cont, put_flash(socket, :info, "New record added!")}
        end
      end

      before_row_action :unarchive, fn record, state ->
        if record.locked?, do: {:halt, {:error, "locked"}}, else: :ok
      end

      after_bulk_action :unarchive, fn _result, _state -> :ok end

      switch_to_active_on_empty_archive true
    end

# `section`

Returns the hooks section definition.

---

*Consult [api-reference.md](api-reference.md) for complete listing*