Ui/Toast

/**
 * Handlers passed to `entryToView`. Spread `dismiss` onto a close
 *  button's attribute array (typically inside `h.button([...dismiss])`)
 *  to let users dismiss the entry manually. The attribute carries the
 *  Toast's dismiss handler bound to this entry's id; it routes through
 *  the Toast boundary's wrap chain at click time.
 */
type EntryHandlers = Readonly<{
  dismiss: ReadonlyArray<ChildAttribute>
}>

/**
 * Configuration for creating a toast container model. `defaultDuration` is
 *  applied to any `show()` call that doesn't provide its own `duration` or
 *  pass `sticky: true`. Accepts any Effect Duration input; a bare number is
 *  interpreted as milliseconds.
 */
type InitConfig = Readonly<{
  defaultDuration: Duration.Input
  id: string
}>

/**
 * Input for `show()`. `payload` is the consumer-defined content shape for an
 *  entry. Omit `duration` to use the container's `defaultDuration`; pass
 *  `sticky: true` to skip auto-dismiss entirely.
 */
type ShowInput = Readonly<{
  duration: Duration.Input
  payload: A
  sticky: boolean
  variant: Variant
}>

/**
 * Schedules an auto-dismiss timer for an entry. The result Message carries a
 *  version so stale timers (from hover or manual dismiss) are discarded in
 *  the update function. Static. The Command definition doesn't depend on
 *  payload.
 */
const DismissAfter: CommandDefinitionWithArgs<"DismissAfter", {
  duration: DurationFromMillis
  entryId: String
  version: Number
}, Effect<{
  _tag: "ElapsedDuration"
  entryId: string
  version: number
}, never, never>>

/**
 * Sent when an entry should begin dismissing. Starts the leave animation;
 *  the entry is removed from the stack when `TransitionedOut` fires.
 */
const Dismissed: CallableTaggedStruct<"Dismissed", {
  entryId: String
}>

/** Sent when every currently-visible entry should begin dismissing. */
const DismissedAll: CallableTaggedStruct<"DismissedAll", {}>

/**
 * Sent when an entry's auto-dismiss timer fires. Carries a version echoed
 *  from the scheduling moment so stale timers (from hover or manual dismiss)
 *  are discarded.
 */
const ElapsedDuration: CallableTaggedStruct<"ElapsedDuration", {
  entryId: String
  version: Number
}>

/** Wraps a single entry's Animation submodel message for delegation. */
const GotAnimationMessage: CallableTaggedStruct<"GotAnimationMessage", {
  entryId: String
  message: Union<[CallableTaggedStruct<"Showed", {}>, CallableTaggedStruct<"Hid", {}>, CallableTaggedStruct<"AdvancedAnimationFrame", {}>, CallableTaggedStruct<"EndedAnimation", {}>]>
}>

/**
 * Sent when the pointer enters an entry. Pauses the auto-dismiss timer by
 *  advancing the entry's version.
 */
const HoveredEntry: CallableTaggedStruct<"HoveredEntry", {
  entryId: String
}>

/**
 * Sent when the pointer leaves an entry. Restarts the auto-dismiss timer
 *  with the entry's full duration.
 */
const LeftEntry: CallableTaggedStruct<"LeftEntry", {
  entryId: String
}>

/** Where the toast viewport is anchored on the screen and how entries stack. */
const Position: Literals<readonly ["TopLeft", "TopCenter", "TopRight", "BottomLeft", "BottomCenter", "BottomRight"]>

/**
 * Semantic category of a toast. Drives the default ARIA role: `status` for
 *  `Info` / `Success`, `alert` for `Warning` / `Error`. Also surfaced as
 *  `data-variant` on each entry for per-variant CSS. This is the only
 *  content-adjacent field the component owns. The rest of the entry's
 *  content lives in the user-provided payload.
 */
const Variant: Literals<readonly ["Info", "Success", "Warning", "Error"]>