@svgrid/grid 2.2.16 → 2.2.18

package/src/positioning.ts

@@ -0,0 +1,266 @@
+/**
+ * positioning - a small, dependency-free anchor-positioning engine for the
+ * overlay layer (popover, tooltip, menu, dropdowns). It replaces the vertical-
+ * flip-only `anchoredRect` for components that need the full placement matrix.
+ *
+ * Two halves:
+ *
+ * 1. `computePosition(reference, floating, options)` - PURE geometry. Given the
+ *    reference rect and the floating size (plus a viewport), it returns the
+ *    floating `x`/`y`, the resolved `placement` (after flip), the arrow offset,
+ *    and the available `maxWidth`/`maxHeight` on the chosen side. No DOM, so it
+ *    is fully unit-tested by feeding rects and asserting placement.
+ *
+ * 2. `autoUpdate(referenceEl, floatingEl, update)` - the browser half. Re-runs
+ *    `update` whenever the reference/floating resize, an ancestor scrolls, or the
+ *    window resizes (via `ResizeObserver` + scroll/resize listeners). SSR-safe
+ *    (a no-op without `window`).
+ *
+ * The middleware (flip / shift / size / arrow) is implemented inline - no
+ * Floating-UI dependency - matching the kit's zero-runtime-dep posture.
+ */
+
+/** A physical side the floating element is placed on, relative to the reference. */
+export type Side = 'top' | 'bottom' | 'left' | 'right'
+
+/** Cross-axis alignment. `center` is the bare side (e.g. `'bottom'`). */
+export type Align = 'start' | 'center' | 'end'
+
+/** `'bottom'` = bottom-center; `'bottom-start'` / `'bottom-end'` align the edges. */
+export type Placement = Side | `${Side}-start` | `${Side}-end`
+
+/** A viewport-relative rectangle (CSS `getBoundingClientRect` shape suffices). */
+export type Rect = { x: number; y: number; width: number; height: number }
+
+/** The available viewport (defaults to `window` in the browser). */
+export type Viewport = { width: number; height: number }
+
+export type ComputePositionOptions = {
+  /** Preferred placement. Default `'bottom-start'`. */
+  placement?: Placement
+  /** Main-axis gap between reference and floating. Default 6. */
+  offset?: number
+  /** Viewport edge kept clear on every side. Default 8. */
+  padding?: number
+  /** Flip to the opposite side when the preferred side overflows. Default true. */
+  flip?: boolean
+  /** Shift along the cross axis to stay in view (without flipping). Default true. */
+  shift?: boolean
+  /** Compute `maxWidth`/`maxHeight` for the chosen side. Default true. */
+  size?: boolean
+  /** When set, compute the arrow offset for an arrow element of this size (px). */
+  arrow?: { size: number }
+  /** Extra placements to try (after the automatic opposite) before giving up. */
+  fallbackPlacements?: Placement[]
+  /** Viewport to fit within. Defaults to the window; pure callers pass it. */
+  viewport?: Viewport
+  /** Floor for the available main-axis size returned by `size`. Default 0. */
+  minMainAxis?: number
+}
+
+export type ComputePositionResult = {
+  /** Floating left, in viewport (fixed-position) coordinates. */
+  x: number
+  /** Floating top, in viewport (fixed-position) coordinates. */
+  y: number
+  /** The resolved placement after flip. */
+  placement: Placement
+  /** The resolved side after flip. */
+  side: Side
+  /** The resolved cross-axis alignment. */
+  align: Align
+  /** Space available for the floating on the chosen side's main axis (+cross). */
+  maxWidth: number
+  maxHeight: number
+  /**
+   * Arrow offset within the floating box: `x` for top/bottom placements, `y` for
+   * left/right. Only present when `options.arrow` is set. Clamped so the arrow
+   * stays inside the floating (minus padding).
+   */
+  arrow?: { x?: number; y?: number }
+}
+
+const SIDES: Record<Side, Side> = { top: 'bottom', bottom: 'top', left: 'right', right: 'left' }
+
+/** Split a placement into its side + alignment (`center` when no suffix). */
+export function parsePlacement(p: Placement): { side: Side; align: Align } {
+  const [side, align] = p.split('-') as [Side, 'start' | 'end' | undefined]
+  return { side, align: align ?? 'center' }
+}
+
+function opposite(p: Placement): Placement {
+  const { side, align } = parsePlacement(p)
+  return (align === 'center' ? SIDES[side] : `${SIDES[side]}-${align}`) as Placement
+}
+
+function clamp(v: number, min: number, max: number): number {
+  if (max < min) return min
+  return v < min ? min : v > max ? max : v
+}
+
+/** Floating x/y for a given side+align (before flip/shift). */
+function coordsFor(side: Side, align: Align, r: Rect, f: Viewport, offset: number): { x: number; y: number } {
+  if (side === 'top' || side === 'bottom') {
+    const y = side === 'top' ? r.y - f.height - offset : r.y + r.height + offset
+    const x =
+      align === 'start' ? r.x : align === 'end' ? r.x + r.width - f.width : r.x + r.width / 2 - f.width / 2
+    return { x, y }
+  }
+  const x = side === 'left' ? r.x - f.width - offset : r.x + r.width + offset
+  const y =
+    align === 'start' ? r.y : align === 'end' ? r.y + r.height - f.height : r.y + r.height / 2 - f.height / 2
+  return { x, y }
+}
+
+/** How far the floating exceeds the viewport on the placement's MAIN axis. >0 = overflow. */
+function mainAxisOverflow(side: Side, x: number, y: number, f: Viewport, v: Viewport, pad: number): number {
+  switch (side) {
+    case 'top':
+      return pad - y
+    case 'bottom':
+      return y + f.height - (v.height - pad)
+    case 'left':
+      return pad - x
+    default:
+      return x + f.width - (v.width - pad)
+  }
+}
+
+function resolveViewport(v?: Viewport): Viewport {
+  if (v) return v
+  if (typeof window !== 'undefined') return { width: window.innerWidth, height: window.innerHeight }
+  return { width: 0, height: 0 }
+}
+
+/**
+ * Compute the floating position anchored to `reference`, applying flip (opposite
+ * side when the preferred side overflows), shift (cross-axis clamp to stay in
+ * view), size (available max width/height on the chosen side) and an optional
+ * arrow offset. Pure - pass an explicit `viewport` in tests.
+ */
+export function computePosition(
+  reference: Rect,
+  floating: Viewport,
+  options: ComputePositionOptions = {},
+): ComputePositionResult {
+  const offset = options.offset ?? 6
+  const pad = options.padding ?? 8
+  const doFlip = options.flip !== false
+  const doShift = options.shift !== false
+  const v = resolveViewport(options.viewport)
+  const preferred = options.placement ?? 'bottom-start'
+
+  // ---- flip: pick the placement whose main-axis overflow is smallest ----
+  const candidates: Placement[] = [preferred]
+  if (doFlip) {
+    candidates.push(opposite(preferred))
+    for (const fb of options.fallbackPlacements ?? []) candidates.push(fb)
+  }
+  let chosen = preferred
+  let best = Infinity
+  for (const cand of candidates) {
+    const { side, align } = parsePlacement(cand)
+    const { x, y } = coordsFor(side, align, reference, floating, offset)
+    const overflow = mainAxisOverflow(side, x, y, floating, v, pad)
+    if (overflow <= 0) {
+      chosen = cand
+      best = overflow
+      break
+    }
+    if (overflow < best) {
+      best = overflow
+      chosen = cand
+    }
+  }
+
+  const { side, align } = parsePlacement(chosen)
+  let { x, y } = coordsFor(side, align, reference, floating, offset)
+
+  // ---- shift: clamp along the CROSS axis so the floating stays in view ----
+  if (doShift) {
+    if (side === 'top' || side === 'bottom') {
+      x = clamp(x, pad, v.width - pad - floating.width)
+    } else {
+      y = clamp(y, pad, v.height - pad - floating.height)
+    }
+  }
+
+  // ---- size: available room on the chosen side ----
+  const minMain = options.minMainAxis ?? 0
+  let maxWidth: number
+  let maxHeight: number
+  if (side === 'top' || side === 'bottom') {
+    const avail = side === 'top' ? reference.y - offset - pad : v.height - pad - (reference.y + reference.height + offset)
+    maxHeight = Math.max(minMain, Math.floor(avail))
+    maxWidth = Math.max(0, v.width - 2 * pad)
+  } else {
+    const avail = side === 'left' ? reference.x - offset - pad : v.width - pad - (reference.x + reference.width + offset)
+    maxWidth = Math.max(minMain, Math.floor(avail))
+    maxHeight = Math.max(0, v.height - 2 * pad)
+  }
+
+  const result: ComputePositionResult = { x, y, placement: chosen, side, align, maxWidth, maxHeight }
+
+  // ---- arrow: point at the reference center, clamped inside the floating ----
+  if (options.arrow) {
+    const a = options.arrow.size
+    if (side === 'top' || side === 'bottom') {
+      const center = reference.x + reference.width / 2
+      const ax = clamp(center - x - a / 2, pad, floating.width - a - pad)
+      result.arrow = { x: ax }
+    } else {
+      const center = reference.y + reference.height / 2
+      const ay = clamp(center - y - a / 2, pad, floating.height - a - pad)
+      result.arrow = { y: ay }
+    }
+  }
+
+  return result
+}
+
+/** Collect scrollable ancestors so `autoUpdate` can listen to their scroll. */
+function scrollParents(node: Element): Element[] {
+  const out: Element[] = []
+  let el: Element | null = node.parentElement
+  while (el) {
+    const style = getComputedStyle(el)
+    if (/(auto|scroll|overlay|hidden)/.test(style.overflow + style.overflowY + style.overflowX)) out.push(el)
+    el = el.parentElement
+  }
+  return out
+}
+
+/**
+ * Re-run `update` whenever the anchored position could change: the reference or
+ * floating element resizes, an ancestor scrolls, or the window scrolls/resizes.
+ * Returns a cleanup function. SSR-safe (a no-op without `window`).
+ *
+ * ```ts
+ * const stop = autoUpdate(triggerEl, panelEl, () => reposition())
+ * // ...later
+ * stop()
+ * ```
+ */
+export function autoUpdate(reference: Element, floating: HTMLElement, update: () => void): () => void {
+  if (typeof window === 'undefined') return () => {}
+  const ancestors = scrollParents(reference)
+  for (const a of ancestors) a.addEventListener('scroll', update, { passive: true })
+  window.addEventListener('scroll', update, { passive: true })
+  window.addEventListener('resize', update)
+
+  let ro: ResizeObserver | undefined
+  if (typeof ResizeObserver === 'function') {
+    ro = new ResizeObserver(update)
+    ro.observe(reference)
+    ro.observe(floating)
+  }
+
+  update()
+
+  return () => {
+    for (const a of ancestors) a.removeEventListener('scroll', update)
+    window.removeEventListener('scroll', update)
+    window.removeEventListener('resize', update)
+    ro?.disconnect()
+  }
+}

package/src/scheduler-model.test.ts

@@ -151,6 +151,22 @@ describe('resolveEvents', () => {
     expect(other.isException).toBeFalsy()
   })
 
+  it('applies per-occurrence `fields` overrides to one instance (merged row + resource)', () => {
+    const rows: Row[] = [
+      { ...weekly, who: 'room1', exceptions: [{ occurrenceStart: '2026-07-13T09:30', fields: { who: 'room9', title: 'Standup (offsite)' } }] },
+    ]
+    const out = resolveEvents(rows, spec(), at(2026, 7, 1), at(2026, 8, 1))
+    const overridden = out.find((e) => e.start.getDate() === 13)!
+    expect(overridden.resourceId).toBe('room9') // re-derived from the merged row
+    expect((overridden.row as Row).who).toBe('room9') // the instance row carries the override
+    expect(overridden.title).toBe('Standup (offsite)') // title from fields when not set explicitly
+    expect(overridden.isException).toBe(true)
+    // Siblings keep the base resource + row.
+    const sibling = out.find((e) => e.start.getDate() === 20)!
+    expect(sibling.resourceId).toBe('room1')
+    expect((sibling.row as Row).who).toBe('room1')
+  })
+
   it('sorts all-day before timed at the same start', () => {
     const rows: Row[] = [
       { id: 'timed', title: 't', start: '2026-07-15T00:00', end: '2026-07-15T01:00' },

package/src/scheduler-model.ts

@@ -65,6 +65,9 @@ export type RecurrenceException = {
   end?: DateLike | null
   title?: string
   allDay?: boolean
+  /** Per-occurrence overrides for any other field, merged over the row for just
+   *  this occurrence (attendees, calendar, color, resource, ...). */
+  fields?: Record<string, unknown>
 }
 
 /** Field accessors the model uses to read an event off a row. The component
@@ -251,6 +254,14 @@ export function resolveEvents<TData>(
         let iEnd = new Date(occStart.getTime() + durationMs)
         let iTitle = title
         let iAllDay = allDay
+        // Per-occurrence overrides of ANY other field: merge onto a copy of the
+        // row for this instance, then re-derive the surfaced props from it so a
+        // "This event" change to attendees / calendar / color / resource shows.
+        let iRow = row
+        let iColor = color
+        let iColor2 = color2
+        let iStatus = status
+        let iResource = resourceId
         if (ex) {
           const exS = toDate(ex.start)
           const exE = toDate(ex.end)
@@ -262,21 +273,29 @@ export function resolveEvents<TData>(
           }
           if (ex.title != null) iTitle = ex.title
           if (ex.allDay != null) iAllDay = ex.allDay
+          if (ex.fields) {
+            iRow = { ...(row as Record<string, unknown>), ...ex.fields } as TData
+            iColor = spec.getColor?.(iRow) ?? color
+            iColor2 = spec.getSecondaryColor?.(iRow) ?? color2
+            iStatus = spec.getStatus?.(iRow) ?? status
+            iResource = spec.getResource?.(iRow) ?? resourceId
+            if (ex.title == null) iTitle = spec.getTitle?.(iRow) ?? iTitle
+          }
         }
         if (!rangesOverlap(iStart, iEnd, rangeStart, rangeEnd)) continue
         out.push({
           // Key on the CANONICAL occurrence start so a moved occurrence keeps its identity.
           key: `${rowKey}#${occStart.getFullYear()}-${occStart.getMonth() + 1}-${occStart.getDate()}T${occStart.getHours()}:${occStart.getMinutes()}`,
           rowKey,
-          row,
+          row: iRow,
           title: iTitle,
           start: iStart,
           end: iEnd,
           allDay: iAllDay,
-          color,
-          color2,
-          status,
-          resourceId,
+          color: iColor,
+          color2: iColor2,
+          status: iStatus,
+          resourceId: iResource,
           recurring: true,
           occurrenceStart: occStart,
           isException: !!ex,

package/src/svgrid-wrapper.types.ts

@@ -1,4 +1,7 @@
 import type { CellFormatConfig, ColumnDef, RowData, SvGridOptions, TableFeatures } from './core'
+// Type-only import (the reverse of SvGrid.types importing SvGridApi); TS resolves the
+// type-level cycle. Backs the generic key/value typing of `setOption` / `getOption`.
+import type { Props } from './SvGrid.types'
 import type { GridExportOptions, GridClipboardOptions } from './export-format'
 import type { ChartSpec, ChartType } from './chart'
 
@@ -194,6 +197,26 @@ export type SvGridApi<
   setSort(columnId: string, direction: 'asc' | 'desc' | null): void
   clearSort(): void
   setGroupBy(columnIds: ReadonlyArray<string>): void
+
+  // ----- Options (runtime prop overrides) -----
+  /**
+   * Change a grid prop at runtime, e.g. `api.setOption('sortable', true)`. The
+   * override is merged over the incoming prop and the grid re-renders reactively -
+   * identical to the parent passing a new prop value. Pass `undefined` to clear the
+   * override and fall back to the prop.
+   *
+   * Note: seed-once props are NOT retroactive - `initialSorting`,
+   * `initialColumnPinning`, `initialHiddenColumns`, `columnOrder`, the initial
+   * `pageSize`, and the one-shot `externalSort` / `externalFilter` are read at mount,
+   * so overriding them later has no effect. Prefer the dedicated data path for
+   * `data` / `columns` (this works, but the sync effects are the idiomatic route).
+   */
+  setOption<K extends keyof Props<TFeatures, TData>>(key: K, value: Props<TFeatures, TData>[K] | undefined): void
+  /** Read a prop's effective value: the runtime override if set, else the incoming prop. */
+  getOption<K extends keyof Props<TFeatures, TData>>(key: K): Props<TFeatures, TData>[K]
+  /** Clear every runtime override set via `setOption`, reverting to the incoming props. */
+  resetOptions(): void
+
   /** Set the operator filter for a column. Pass `null` to clear. */
   setFilter(
     columnId: string,

package/src/svgrid.charting.test.ts

@@ -73,11 +73,15 @@ function mountGrid(overrides: Record<string, unknown> = {}): Promise<MountResult
   })
 }
 
-const tick = () => Promise.resolve()
+// A macrotask boundary: drains all pending microtasks (Svelte effects, the chart
+// panel's lazy import() + its .then, and the follow-up flush) so the docked panel
+// is mounted before assertions. The panel is loaded lazily as its own chunk.
+const tick = () => new Promise((r) => setTimeout(r))
 
 describe('SvGrid built-in charting', () => {
   it('derives a chart spec from all displayed rows (default dimension + measure)', async () => {
     const { api, destroy } = await mountGrid({ charting: true })
+    await tick() // the chart engine loads lazily; ready a tick after mount
     try {
       const spec = api.getChartSpec()
       expect(spec).not.toBeNull()
@@ -398,6 +402,7 @@ describe('SvGrid built-in charting', () => {
 
   it('splits into one series per distinct value of the `series` field', async () => {
     const { api, destroy } = await mountGrid({ charting: { dimension: 'team', series: 'name', measures: 'age' } })
+    await tick() // the chart engine loads lazily; ready a tick after mount
     try {
       const spec = api.getChartSpec()
       // categories = distinct teams (4); one series per distinct name (6).
@@ -409,6 +414,7 @@ describe('SvGrid built-in charting', () => {
 
   it('plots one series per measure with `measures[]`', async () => {
     const { api, destroy } = await mountGrid({ charting: { dimension: 'team', measures: ['age', 'salary'] } })
+    await tick() // the chart engine loads lazily; ready a tick after mount
     try {
       const spec = api.getChartSpec()
       expect(spec!.series.length).toBe(2)
@@ -419,6 +425,7 @@ describe('SvGrid built-in charting', () => {
 
   it('marks the spec stacked when config.stacked is set', async () => {
     const { api, destroy } = await mountGrid({ charting: { dimension: 'team', series: 'name', measures: 'age', stacked: true } })
+    await tick() // the chart engine loads lazily; ready a tick after mount
     try {
       expect(api.getChartSpec()!.stacked).toBe(true)
     } finally {

package/src/svgrid.comments-autocomplete.test.ts

@@ -1,7 +1,7 @@
 /**
  * Track C: free-text autocomplete cell type + editable cell comments.
  */
-import { describe, expect, it } from 'vitest'
+import { describe, expect, it, vi } from 'vitest'
 import { mount, unmount } from 'svelte'
 import SvGrid from './SvGrid.svelte'
 import { createCoreRowModel, tableFeatures } from './index'
@@ -13,7 +13,10 @@ const rows: Row[] = [
   { id: 1, name: 'Ann', city: 'Paris' },
   { id: 2, name: 'Bo', city: 'Berlin' },
 ]
-const tick = () => new Promise<void>((r) => queueMicrotask(r))
+// Macrotask boundary: drains pending microtasks incl. the menu overlay's lazy
+// import() + flush, so the context menu is mounted before assertions (GridMenus
+// loads lazily as its own chunk the first time a menu/tooltip opens).
+const tick = () => new Promise<void>((r) => setTimeout(r))
 
 function mountGrid(extraCols: ColumnDef<typeof features, Row>[], props: Record<string, unknown> = {}) {
   return new Promise<{ api: SvGridApi<typeof features, Row>; target: HTMLElement; destroy: () => void }>(
@@ -90,6 +93,8 @@ describe('editable comments', () => {
     await tick()
     const cell = dataCell(target, 0)
     cell.dispatchEvent(new MouseEvent('contextmenu', { bubbles: true, cancelable: true }))
+    // First menu-open triggers GridMenus' lazy import; poll until it mounts.
+    await vi.waitFor(() => expect(target.querySelector('.sv-grid-context-menu')).not.toBeNull())
     await tick()
     const editItem = [...target.querySelectorAll('.sv-grid-context-menu .sv-grid-menu-item')].find(
       (b) => b.textContent?.trim() === 'Edit comment',

package/src/svgrid.context-menu.test.ts

@@ -3,7 +3,7 @@
  * fires a synthetic `contextmenu` event on a cell, and asserts the menu
  * opens with the expected items and that actions/close work.
  */
-import { describe, expect, it } from 'vitest'
+import { describe, expect, it, vi } from 'vitest'
 import { mount, unmount } from 'svelte'
 import SvGrid from './SvGrid.svelte'
 import {
@@ -29,7 +29,10 @@ const cols: ColumnDef<typeof features, Row>[] = [
   { field: 'name', header: 'Name', width: 200, editorType: 'text' },
   { field: 'team', header: 'Team', width: 160, editorType: 'text' },
 ]
-const tick = () => new Promise<void>((r) => queueMicrotask(r))
+// Macrotask boundary: drains pending microtasks incl. the menu overlay's lazy
+// import() + flush, so the context menu is mounted before assertions (GridMenus
+// loads lazily as its own chunk the first time a menu/tooltip opens).
+const tick = () => new Promise<void>((r) => setTimeout(r))
 
 function mountGrid(contextMenu: unknown) {
   return new Promise<{ api: SvGridApi<typeof features, Row>; target: HTMLElement; destroy: () => void }>(
@@ -76,7 +79,9 @@ describe('SvGrid context menu', () => {
     const { target, destroy } = await mountGrid(true)
     await tick()
     rightClickFirstCell(target)
-    await tick()
+    // First menu-open triggers GridMenus' lazy import (transforming the module on
+    // first load can exceed a single tick); poll until the overlay mounts.
+    await vi.waitFor(() => expect(target.querySelector('.sv-grid-context-menu')).not.toBeNull())
     const menu = target.querySelector('.sv-grid-context-menu')
     expect(menu).not.toBeNull()
     const labels = [...menu!.querySelectorAll('.sv-grid-menu-item')].map((b) => b.textContent?.trim())

package/src/toast-store.svelte.ts

@@ -13,10 +13,20 @@
  *
  * Mount a single <SvToaster /> once near the app root to render the queue.
  */
+import type { Snippet } from 'svelte'
 import { announce } from './a11y/live-region'
 
 export type ToastVariant = 'info' | 'success' | 'warning' | 'error'
 
+/** A button rendered inside a toast (a primary `action` or a secondary `cancel`). */
+export type ToastAction = {
+  label: string
+  /** Invoked with the toast id when pressed. */
+  onClick?: (id: number) => void
+  /** Keep the toast open after the click (default: dismiss it). */
+  keepOpen?: boolean
+}
+
 export type ToastOptions = {
   variant?: ToastVariant
   /** Auto-dismiss after N ms. `0` = sticky (dismiss manually). Default 4000. */
@@ -25,6 +35,12 @@ export type ToastOptions = {
   dismissible?: boolean
   /** Optional bold title above the message. */
   title?: string
+  /** Primary action button. */
+  action?: ToastAction
+  /** Secondary (cancel) action button. */
+  cancel?: ToastAction
+  /** Render a fully custom toast body instead of the icon + title + message. */
+  render?: Snippet<[Toast]>
 }
 
 export type Toast = {
@@ -34,6 +50,19 @@ export type Toast = {
   duration: number
   dismissible: boolean
   title?: string
+  action?: ToastAction
+  cancel?: ToastAction
+  render?: Snippet<[Toast]>
+}
+
+/** Patch applied by `toast.update(id, patch)`; every field is optional. */
+export type UpdateToast = Partial<Omit<Toast, 'id'>>
+
+/** Messages for `toast.promise`; success/error may derive from the value/error. */
+export type PromiseMessages<T> = {
+  loading: string
+  success: string | ((value: T) => string)
+  error: string | ((error: unknown) => string)
 }
 
 type VariantOptions = Omit<ToastOptions, 'variant'>
@@ -44,6 +73,17 @@ export type ToastFn = {
   success: (message: string, options?: VariantOptions) => number
   warning: (message: string, options?: VariantOptions) => number
   error: (message: string, options?: VariantOptions) => number
+  /**
+   * Show a sticky loading toast, then update it IN PLACE to success/error when
+   * the promise settles. Returns the original promise so callers can await it.
+   */
+  promise: <T>(promise: Promise<T>, messages: PromiseMessages<T>, options?: ToastOptions) => Promise<T>
+  /** Patch an existing toast (message/variant/title/action/duration/render). */
+  update: (id: number, patch: UpdateToast) => void
+  /** Push a toast with a fully custom body snippet. Returns its id. */
+  custom: (render: Snippet<[Toast]>, options?: ToastOptions) => number
+  /** Dismiss a toast by id. */
+  dismiss: (id: number) => void
 }
 
 function createToastStore() {
@@ -104,6 +144,9 @@ function createToastStore() {
       duration,
       dismissible: options.dismissible ?? true,
       title: options.title,
+      action: options.action,
+      cancel: options.cancel,
+      render: options.render,
     }
     toasts.push(entry)
     // Errors/warnings interrupt (assertive); info/success are polite.
@@ -114,17 +157,70 @@ function createToastStore() {
     return id
   }
 
+  /** Patch an existing toast in place (used by `promise`, and callable directly). */
+  function update(id: number, patch: UpdateToast): void {
+    const t = toasts.find((x) => x.id === id)
+    if (!t) return
+    if (patch.message != null) t.message = patch.message
+    if (patch.title !== undefined) t.title = patch.title
+    if (patch.variant) t.variant = patch.variant
+    if (patch.dismissible !== undefined) t.dismissible = patch.dismissible
+    if (patch.action !== undefined) t.action = patch.action
+    if (patch.cancel !== undefined) t.cancel = patch.cancel
+    if (patch.render !== undefined) t.render = patch.render
+    // A new duration restarts the auto-dismiss timer (0 = make it sticky again).
+    if (patch.duration !== undefined) {
+      const timer = timers.get(id)
+      if (timer) { clearTimeout(timer); timers.delete(id) }
+      meta.delete(id)
+      t.duration = patch.duration
+      if (patch.duration > 0) schedule(id, patch.duration)
+    }
+    announce(t.title ? `${t.title}: ${t.message}` : t.message, {
+      assertive: t.variant === 'error' || t.variant === 'warning',
+    })
+  }
+
+  function promise<T>(p: Promise<T>, messages: PromiseMessages<T>, options: ToastOptions = {}): Promise<T> {
+    const id = push(messages.loading, {
+      ...options,
+      variant: 'info',
+      duration: 0,
+      dismissible: options.dismissible ?? false,
+    })
+    p.then(
+      (value) => update(id, {
+        message: typeof messages.success === 'function' ? messages.success(value) : messages.success,
+        variant: 'success',
+        duration: options.duration ?? 4000,
+        dismissible: true,
+      }),
+      (error) => update(id, {
+        message: typeof messages.error === 'function' ? messages.error(error) : messages.error,
+        variant: 'error',
+        duration: options.duration ?? 6000,
+        dismissible: true,
+      }),
+    )
+    return p
+  }
+
   const toast = push as ToastFn
   toast.info = (m, o = {}) => push(m, { ...o, variant: 'info' })
   toast.success = (m, o = {}) => push(m, { ...o, variant: 'success' })
   toast.warning = (m, o = {}) => push(m, { ...o, variant: 'warning' })
   toast.error = (m, o = {}) => push(m, { ...o, variant: 'error' })
+  toast.promise = promise
+  toast.update = update
+  toast.custom = (render, o = {}) => push('', { ...o, render })
+  toast.dismiss = dismiss
 
   return {
     get toasts() {
       return toasts
     },
     toast,
+    update,
     dismiss,
     clear,
     pause,
@@ -140,6 +236,8 @@ export const toastStore = { get toasts() { return store.toasts } }
 export const toast: ToastFn = store.toast
 /** Dismiss a toast by id. */
 export const dismissToast = (id: number): void => store.dismiss(id)
+/** Patch an existing toast in place (message/variant/title/action/duration/render). */
+export const updateToast = (id: number, patch: UpdateToast): void => store.update(id, patch)
 /** Remove every toast (and cancel their timers). */
 export const clearToasts = (): void => store.clear()
 /** Pause a toast's auto-dismiss countdown (e.g. while hovered). */