notificationModule

import { notificationModule } from '@atheory-ai/kitsune-ui'

shell.modules = [notificationModule(), /* others */]

What it does

Registers three command handlers:

notification.show — append a toast to <kit-toast-region>.
notification.dismiss — remove a specific toast by id.
notification.clear — remove all toasts.

Together with <kit-toast-region>, this turns user feedback into a one-liner from anywhere in your app.

Options

type NotificationModuleOptions = {
  target?: string                     // id or selector for the toast region
  fallback?: 'alert' | 'silent'       // what happens if no region is found
}

target — defaults to the first <kit-toast-region> on the page. Pass an id ('main-toasts') or any CSS selector (.toast-region).

fallback — defaults to 'alert'. If no toast region is found, show window.alert(message) for visibility. Set to 'silent' to do nothing.

Command shapes

`notification.show`

{
  type: 'notification.show',
  payload: {
    message: string,
    tone?: 'info' | 'success' | 'error',  // defaults to 'info'
  }
}

Returns:

{ ok: true, value: { delivered: boolean, id?: string, message, tone } }

If delivered: false, the message wasn’t shown (no region, no fallback).

`notification.dismiss`

{
  type: 'notification.dismiss',
  payload: { id: string }
}

Returns { ok: true, value: { dismissed: boolean, id } }.

`notification.clear`

{ type: 'notification.clear' }

Returns { ok: true, value: { cleared: boolean } }.

Triggering from metadata

<kit-button
  meta-command="notification.show"
  meta-prop-message="Saved"
  meta-prop-tone="success"
>
  Save
</kit-button>

Triggering from a module

A common pattern: another module observes a domain event and dispatches a notification:

defineKitModule({
  name: 'note-toasts',
  setup(runtime) {
    runtime.on('note.created', () => {
      runtime.command({
        type: 'notification.show',
        payload: { message: 'Note created', tone: 'success' },
      })
    })
  },
})

Custom toast UI

If you want a different toast UX (action buttons, longer-lived notifications, queueing), write a replacement module:

const myNotificationModule = defineKitModule({
  name: 'my-notifications',
  commands: {
    'notification.show': (cmd) => myToaster.show(cmd.payload),
    // ...
  },
})

shell.modules = [myNotificationModule, /* not the built-in */]

Or install both, with yours last — the last registered handler wins.