@object-ui/react 16.1.0 → 17.2.0

package/README.md

@@ -182,6 +182,47 @@ The `previewMode` object contains:
 | `expiresInSeconds` | `number` | `0` | Session duration (0 = no expiry) |
 | `bannerMessage` | `string` | — | UI banner message |
 
+### useNotifications / useNotificationsByPresentation
+
+`NotificationProvider` implements the spec `NotificationSchema`. A notification's
+`severity` picks its icon and tone; its `displayType` picks the **surface** that
+renders it — and each of the five spec types has a distinct one:
+
+| `displayType` | Presentation | Rendered by | Auto-dismiss |
+| --- | --- | --- | --- |
+| `toast` | transient overlay | the `onToast` delegate | yes |
+| `snackbar` | bottom-anchored bar, one at a time, one action | `<NotificationSnackbar />` | yes |
+| `banner` | page-width strip in the content flow | `<NotificationBanners />` | no |
+| `alert` | blocking acknowledgement dialog (FIFO) | `<NotificationAlerts />` | no |
+| `inline` | in place, at the raising surface | `<NotificationInline />` | no |
+
+The surface components ship in `@object-ui/components`; mount them where they
+belong (a banner is in flow, an inline notification sits next to its raiser).
+`onToast` receives **only** `toast` items — it used to receive all five, which is
+why every type looked like a toast.
+
+```tsx
+const { notify } = useNotifications()
+
+notify({ title: 'Saved', severity: 'success' })                     // toast (spec default)
+notify({ title: 'Viewing a draft', severity: 'warning', displayType: 'banner' })
+notify({ title: 'Fix 2 fields', severity: 'error', displayType: 'inline', scope: 'contact-form' })
+```
+
+A surface component subscribes with `useNotificationsByPresentation(type, scope?)`,
+which also registers the surface — raising a `banner` with no banner surface
+mounted warns in dev instead of vanishing.
+
+`config` is the spec `NotificationConfigSchema` (`defaultPosition`,
+`defaultDuration`, `maxVisible`, `stackDirection`, `pauseOnHover`); the legacy
+`position` / `stacking` spellings still resolve through
+`resolveNotificationConfig`. Three helpers apply it so every surface agrees:
+`resolveNotificationPosition` (a declared position always wins; nothing declared
+leaves the surface on its own anchor), `visibleNotificationStack` (`maxVisible` +
+`stackDirection`), and the context's `pauseAutoDismiss` / `resumeAutoDismiss`
+(`pauseOnHover`). See the
+[notifications guide](https://objectui.org/docs/guide/notifications).
+
 ## API Reference
 
 See [full documentation](https://objectui.org/api/react) for detailed API reference.

package/dist/SchemaRenderer.js

@@ -136,9 +136,19 @@ export class SchemaErrorBoundary extends Component {
         return this.props.children;
     }
 }
+/**
+ * Shared "no data source" fallback. MUST be a module constant: it feeds the
+ * `evaluatedSchema` memo below, and a fresh `{}` per render defeats that memo
+ * for every SchemaRenderer without a provider above it — re-cloning the schema
+ * and re-running the ExpressionEvaluator on each render, and handing a new
+ * schema identity to children that memoise on it. For a `kind:'react'` page
+ * that identity IS the compile key, so the page was silently remounted and its
+ * `useState` wiped (objectui#2954's latent hazard, made real by this line).
+ */
+const NO_DATA_SOURCE = {};
 export const SchemaRenderer = forwardRef(({ schema, ...props }, _ref) => {
     const context = useContext(SchemaRendererContext);
-    const dataSource = context?.dataSource || {};
+    const dataSource = context?.dataSource || NO_DATA_SOURCE;
     // Ambient host scope (user / app / features), fed by app-shell's
     // ExpressionProvider. Threaded into `visible`/expression evaluation so
     // component predicates can gate on the signed-in user & deployment flags.
@@ -233,7 +243,7 @@ export const SchemaRenderer = forwardRef(({ schema, ...props }, _ref) => {
             if (newSchema.visibleOn !== undefined) {
                 return !evaluator.evaluateCondition(newSchema.visibleOn);
             }
-            // @deprecated ADR-0089 → `visibleWhen` (was PageComponentSchema.visibility,
+            // @deprecated ADR-0089 → `visibleWhen` (was PageNodeSchema.visibility,
             // an ExpressionInput) — show-when-truthy, same semantics as `visibleOn`.
             if (newSchema.visibility !== undefined) {
                 return !evaluator.evaluateCondition(newSchema.visibility);

package/dist/context/AppShellContext.js

@@ -7,30 +7,50 @@ export function useAdapter() {
     return useContext(AdapterCtx);
 }
 export const MetadataCtx = createContext(null);
+/** Shared frozen empty list for the fallback below — see {@link NO_METADATA_PROVIDER}. */
+const NO_ITEMS = Object.freeze([]);
+/**
+ * The no-provider fallback, as a MODULE-LEVEL SINGLETON.
+ *
+ * Identity matters here, not just shape. `useMetadata()` used to build this
+ * object inline on every call, so outside a `<MetadataProvider>` every render
+ * produced a new `getItem` — and `useMetadataItem` lists `getItem` in its
+ * effect deps and calls `setState({...})` with a fresh object on every run. New
+ * identity → effect re-runs → new state object → re-render → new identity: an
+ * unbreakable render loop, synchronous enough to hang inside `render()`.
+ *
+ * So the fallback documented as the graceful path for consumers mounted outside
+ * a provider was the one thing that made those consumers impossible to mount —
+ * `record:alert` and `record:quick_actions` both call `useMetadataItem`
+ * unconditionally, and both spin. Found by
+ * `apps/console/src/__tests__/record-block-record-reach.test.tsx`
+ * (objectui#3149), which could not mount them at all until this was frozen.
+ *
+ * Frozen so a consumer cannot mutate the shared fallback out from under every
+ * other consumer of it.
+ */
+const NO_METADATA_PROVIDER = Object.freeze({
+    apps: NO_ITEMS,
+    objects: NO_ITEMS,
+    dashboards: NO_ITEMS,
+    reports: NO_ITEMS,
+    pages: NO_ITEMS,
+    loading: false,
+    error: null,
+    refresh: async () => { },
+    invalidate: () => { },
+    ensureType: async () => [],
+    getItem: async () => null,
+    getItemsByType: () => [],
+    getTypeStatus: () => 'ready',
+});
 export function useMetadata() {
     const ctx = useContext(MetadataCtx);
-    if (!ctx) {
-        // Graceful fallback: when a consumer is rendered outside a MetadataProvider
-        // (common in unit tests that only need to assert on rendering), return an
-        // empty no-op implementation rather than crash. Production code paths
-        // should always wrap in <MetadataProvider>.
-        return {
-            apps: [],
-            objects: [],
-            dashboards: [],
-            reports: [],
-            pages: [],
-            loading: false,
-            error: null,
-            refresh: async () => { },
-            invalidate: () => { },
-            ensureType: async () => [],
-            getItem: async () => null,
-            getItemsByType: () => [],
-            getTypeStatus: () => 'ready',
-        };
-    }
-    return ctx;
+    // Graceful fallback: a consumer rendered outside a MetadataProvider (unit
+    // tests that only assert on rendering, standalone previews) gets an empty
+    // no-op implementation rather than a crash. Production code paths should
+    // always wrap in <MetadataProvider>.
+    return ctx ?? NO_METADATA_PROVIDER;
 }
 export function useMetadataItem(type, name) {
     const { getItem } = useMetadata();
@@ -41,7 +61,15 @@ export function useMetadataItem(type, name) {
     });
     useEffect(() => {
         if (!name) {
-            setState({ item: null, loading: false, error: null });
+            // Bail out when already cleared instead of installing a fresh object.
+            // Belt-and-braces against the loop the frozen fallback above fixes at the
+            // source: `getItem` is an effect dep, so ANY caller whose context value
+            // is rebuilt per render — a hand-rolled one in a test, which this
+            // interface explicitly invites — would otherwise re-run this effect,
+            // re-set an equal-but-new state object, and re-render forever.
+            setState((s) => (s.item === null && !s.loading && s.error === null
+                ? s
+                : { item: null, loading: false, error: null }));
             return;
         }
         let cancelled = false;

package/dist/context/InlineEditContext.d.ts

@@ -22,6 +22,34 @@
  * context for the draft/editing flags and drives `saving`/`error`/`reset`.
  */
 import React from 'react';
+/**
+ * Server-computed decision aggregation of the record's pending approval node
+ * (framework#3266, `decision_progress` on `GET /approvals/requests/:id`).
+ *
+ * A multi-approver node does NOT finalize on the first decision: `unanimous`
+ * needs everyone, `quorum` needs `minApprovals` of the slate, `per_group` (会签)
+ * needs each named group to sign. Without the tally, an approver looking at the
+ * record cannot tell whether their own click completes the step or is one of
+ * three — the fact the whole node is about (objectstack#4478). The server does
+ * the counting so every client renders the same "2 of 3" the engine enforces.
+ *
+ * Absent for `first_response` nodes (one decision finalizes, so there is no
+ * progress to show) and for a backend that predates the enrichment.
+ */
+export interface ApprovalProgress {
+    behavior: 'unanimous' | 'quorum' | 'per_group';
+    /** Approvals recorded so far — satisfied GROUPS when `behavior` is `per_group`. */
+    got: number;
+    /** Approvals required to finalize — total GROUPS when `behavior` is `per_group`. */
+    need: number;
+    /** Per-group tally, `per_group` only. */
+    groups?: Array<{
+        group: string;
+        got: number;
+        need: number;
+        satisfied: boolean;
+    }>;
+}
 export interface InlineEditContextValue {
     /** True while the record is in inline-edit mode. */
     editing: boolean;
@@ -43,6 +71,30 @@ export interface InlineEditContextValue {
      * renderer DataSource-agnostic. Defaults to `false`.
      */
     locked: boolean;
+    /**
+     * Whether an approval is in flight on this record, INDEPENDENT of whether it
+     * locks the record (objectui#2902). An approval node may declare
+     * `lockRecord: false`, in which case the backend accepts edits while the node
+     * waits — `approvalPending` is true and `locked` is false.
+     *
+     * Kept separate because the two drive different affordances: the recall
+     * button and the "an approval is running" status belong to `approvalPending`,
+     * while only `locked` may suppress editing. Consumers that conflate them
+     * either hide recall on an editable record or claim a lock that isn't there.
+     *
+     * `locked` implies an approval is pending, so hosts that thread only `locked`
+     * still get a coherent band. Defaults to `false`.
+     */
+    approvalPending: boolean;
+    /**
+     * Quorum / per-group tally of the pending approval node, when it aggregates
+     * more than one decision (objectstack#4478). Threaded verbatim from the
+     * host's approvals read so the band renders the server's count instead of
+     * re-deriving the engine's tally rules. Undefined when no approval is
+     * running, when the node finalizes on the first response, or when the host
+     * doesn't resolve approvals at all.
+     */
+    approvalProgress?: ApprovalProgress;
     /**
      * Human-readable reason for the approval lock, surfaced as the band's
      * tooltip. Optional — consumers fall back to their own localized default
@@ -88,6 +140,18 @@ export interface InlineEditProviderProps {
      * from a record field the backend may not materialize. Defaults to `false`.
      */
     locked?: boolean;
+    /**
+     * Whether an approval is pending on the record, whether or not it locks it
+     * (objectui#2902). Omitted ⇒ falls back to `locked`, which keeps hosts that
+     * only know about the lock rendering exactly as before.
+     */
+    approvalPending?: boolean;
+    /**
+     * The pending node's server-computed decision tally (objectstack#4478).
+     * Surfaced verbatim so the band can show "2 of 3" / per-group ticks. Omitted
+     * for `first_response` nodes and for hosts that don't read approvals.
+     */
+    approvalProgress?: ApprovalProgress;
     /** Optional human-readable lock reason, surfaced as the band tooltip. */
     lockedReason?: string;
     children: React.ReactNode;

package/dist/context/InlineEditContext.js

@@ -24,7 +24,11 @@ import { jsx as _jsx } from "react/jsx-runtime";
  */
 import React from 'react';
 const InlineEditContext = React.createContext(null);
-export const InlineEditProvider = ({ canEdit = true, locked = false, lockedReason, children, }) => {
+export const InlineEditProvider = ({ canEdit = true, locked = false, approvalPending, approvalProgress, lockedReason, children, }) => {
+    // A locked record always has an approval running; the converse is what
+    // #2902 added. Defaulting this way means an un-migrated host keeps its
+    // previous behavior with no code change.
+    const pending = approvalPending ?? locked;
     const [editing, setEditing] = React.useState(false);
     const [draft, setDraft] = React.useState({});
     const [autoFocusField, setAutoFocusField] = React.useState(null);
@@ -57,6 +61,8 @@ export const InlineEditProvider = ({ canEdit = true, locked = false, lockedReaso
         editing,
         canEdit,
         locked,
+        approvalPending: pending,
+        approvalProgress,
         lockedReason,
         draft,
         autoFocusField,
@@ -68,7 +74,7 @@ export const InlineEditProvider = ({ canEdit = true, locked = false, lockedReaso
         reset: teardown,
         setSaving,
         setError,
-    }), [editing, canEdit, locked, lockedReason, draft, autoFocusField, saving, error, enter, setField, teardown]);
+    }), [editing, canEdit, locked, pending, approvalProgress, lockedReason, draft, autoFocusField, saving, error, enter, setField, teardown]);
     return _jsx(InlineEditContext.Provider, { value: value, children: children });
 };
 /**

package/dist/context/NotificationContext.d.ts

@@ -15,15 +15,100 @@
 import React from 'react';
 /** Notification severity levels aligned with NotificationSeveritySchema */
 export type NotificationSeverityLevel = 'info' | 'success' | 'warning' | 'error';
-/** Notification display type aligned with NotificationTypeSchema */
-export type NotificationDisplayType = 'toast' | 'banner' | 'snackbar' | 'modal';
-/** Notification position aligned with NotificationPositionSchema */
-export type NotificationPositionValue = 'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right';
+/**
+ * Notification presentation — the spec `NotificationTypeSchema`
+ * (`ui/notification.zod.ts`: toast / snackbar / banner / alert / inline).
+ * Every member has a DISTINCT presentation; see {@link NOTIFICATION_PRESENTATIONS}.
+ */
+export type NotificationPresentation = 'toast' | 'snackbar' | 'banner' | 'alert' | 'inline';
+/**
+ * Notification display type as AUTHORED. Identical to
+ * {@link NotificationPresentation} plus the deprecated renderer-local `modal`
+ * spelling, which stored items may still carry (#2942) and which resolves to
+ * `alert`. Use {@link resolveNotificationPresentation} to get the presentation.
+ */
+export type NotificationDisplayType = NotificationPresentation
+/** @deprecated renderer dialect — never in the spec; presented as `alert` */
+ | 'modal';
+/**
+ * Where a presentation is rendered.
+ *
+ * - `delegate` — handed to the provider's `onToast` callback; the host owns the
+ *   overlay (sonner in the console). Historically EVERY type took this path,
+ *   which is why a `banner` surfaced as a toast (#3014).
+ * - everything else names a surface component that subscribes to the context
+ *   and renders the items in place. `@object-ui/components` ships one per
+ *   surface (`NotificationSnackbar` / `NotificationBanners` /
+ *   `NotificationAlerts` / `NotificationInline`).
+ */
+export type NotificationSurface = 'delegate' | 'snackbar' | 'banner' | 'alert' | 'inline';
+export interface NotificationPresentationBehavior {
+    /** The surface responsible for rendering this presentation. */
+    surface: NotificationSurface;
+    /**
+     * Whether the presentation auto-dismisses when the raiser declares no
+     * `duration`. A toast/snackbar is transient by definition; a banner is a
+     * persistent strip and an alert is a blocking acknowledgement, so neither may
+     * evaporate on the shared 5s timer. An explicit `duration` always wins.
+     */
+    transient: boolean;
+}
+/**
+ * The presentation table — one entry per spec `NotificationTypeSchema` member.
+ *
+ * Typed as `Record<NotificationPresentation, …>`, so adding a member to the
+ * spec enum fails type-check here until its presentation is decided, rather
+ * than silently falling back to a toast.
+ */
+export declare const NOTIFICATION_PRESENTATIONS: Record<NotificationPresentation, NotificationPresentationBehavior>;
+/**
+ * Resolve an authored `displayType` to the presentation that renders it:
+ * the spec default (`toast`) when absent, and `alert` for the deprecated
+ * `modal` dialect.
+ */
+export declare function resolveNotificationPresentation(displayType?: NotificationDisplayType): NotificationPresentation;
+/**
+ * Notification position — the spec `NotificationPositionSchema`
+ * (underscore spellings). The hyphen forms are this context's historical
+ * dialect, kept accepted for stored items.
+ */
+export type NotificationPositionValue = 'top_left' | 'top_center' | 'top_right' | 'bottom_left' | 'bottom_center' | 'bottom_right'
+/** @deprecated legacy spelling — use `top_left` */
+ | 'top-left'
+/** @deprecated legacy spelling — use `top_center` */
+ | 'top-center'
+/** @deprecated legacy spelling — use `top_right` */
+ | 'top-right'
+/** @deprecated legacy spelling — use `bottom_left` */
+ | 'bottom-left'
+/** @deprecated legacy spelling — use `bottom_center` */
+ | 'bottom-center'
+/** @deprecated legacy spelling — use `bottom_right` */
+ | 'bottom-right';
+/**
+ * The spec vocabularies this context implements — exported for the parity
+ * tests (#2942), which fail the moment `NotificationTypeSchema` /
+ * `NotificationPositionSchema` and these sets drift in either direction.
+ */
+export declare const SUPPORTED_NOTIFICATION_DISPLAY_TYPES: ReadonlySet<string>;
+export declare const SUPPORTED_NOTIFICATION_POSITIONS: ReadonlySet<string>;
+/**
+ * Action button variant — the spec `NotificationActionSchema.variant`
+ * (`primary | secondary | link`, default `primary`).
+ *
+ * This used to be the shadcn Button vocabulary (`default | destructive |
+ * outline`) — a renderer-local fork of a spec enum, i.e. a second de-facto
+ * contract. Surfaces map these three onto their own button styling instead.
+ */
+export type NotificationActionVariant = 'primary' | 'secondary' | 'link';
+/** The spec vocabulary this context implements — exported for the parity test. */
+export declare const SUPPORTED_NOTIFICATION_ACTION_VARIANTS: ReadonlySet<string>;
 /** Action button on a notification */
 export interface NotificationActionButton {
     label: string;
     onClick: () => void;
-    variant?: 'default' | 'destructive' | 'outline';
+    /** Spec `NotificationActionSchema.variant`. Default: `primary`. */
+    variant?: NotificationActionVariant;
 }
 /** A single notification item */
 export interface NotificationItem {
@@ -31,10 +116,40 @@ export interface NotificationItem {
     title: string;
     message?: string;
     severity: NotificationSeverityLevel;
+    /**
+     * The presentation the raiser asked for. Materialized by `notify()` — stored
+     * items always carry a resolved {@link NotificationPresentation}, never
+     * `modal` and never `undefined`.
+     */
     displayType?: NotificationDisplayType;
     actions?: NotificationActionButton[];
-    /** Duration in ms (0 = persistent). Default: 5000 */
+    /**
+     * Duration in ms (0 = persistent). Defaults to the configured duration for
+     * TRANSIENT presentations (toast / snackbar) and to persistent for the rest —
+     * a banner that evaporates after 5s is not a banner.
+     */
     duration?: number;
+    /**
+     * Whether the surface offers a dismiss control (spec `dismissible`, default
+     * `true`). Only meaningful for the persistent presentations — a transient
+     * one dismisses itself.
+     */
+    dismissible?: boolean;
+    /**
+     * `inline` only — names the surface that raised it, so the matching
+     * `<NotificationInline scope="…" />` renders it in place instead of every
+     * inline outlet on the page showing every inline notification. Renderer-local
+     * routing metadata, not a spec field: the spec describes what a notification
+     * IS, not which React subtree hosts it.
+     */
+    scope?: string;
+    /**
+     * Spec `NotificationSchema.position` — "Override default position", falling
+     * back to `config.defaultPosition`. Honored by the FLOATING presentations
+     * (toast, snackbar); `banner` / `inline` / `alert` are anchored by what they
+     * are (content top / in place / centered modal) and ignore it.
+     */
+    position?: NotificationPositionValue;
     /** Whether the notification has been read */
     read?: boolean;
     /** Timestamp */
@@ -42,23 +157,75 @@ export interface NotificationItem {
     /** Optional icon name (lucide icon) */
     icon?: string;
 }
-/** Configuration for the notification system */
+/**
+ * Configuration for the notification system — the spec
+ * `NotificationConfigSchema` (`defaultPosition` / `defaultDuration` /
+ * `maxVisible` / `stackDirection` / `pauseOnHover`).
+ *
+ * The field names used to fork from it (`position`, and a renderer-local
+ * `stacking` boolean with no spec counterpart), and only `defaultDuration` was
+ * ever read — the other three were stored and ignored. The legacy names are
+ * still accepted; see {@link resolveNotificationConfig}.
+ */
 export interface NotificationSystemConfig {
-    /** Default position for toast notifications */
-    position?: NotificationPositionValue;
-    /** Default duration in ms */
+    /**
+     * Default screen position for the FLOATING presentations (toast, snackbar).
+     * A notification's own `position` overrides it.
+     *
+     * Deliberately undefined by default: "the host didn't say" has to be
+     * representable, otherwise a fabricated default silently competes with the
+     * host's own toast chrome (which also serves non-notification `toast.*`
+     * calls). Declared wins; undeclared defers to the surface's own anchor.
+     */
+    defaultPosition?: NotificationPositionValue;
+    /** Default duration in ms for the transient presentations. */
     defaultDuration?: number;
-    /** Maximum number of visible notifications */
+    /** Maximum number of notifications a stacking surface renders at once. */
     maxVisible?: number;
-    /** Whether to stack notifications */
+    /** Which way a stack grows: `down` puts the newest below (spec default). */
+    stackDirection?: 'up' | 'down';
+    /** Pause a transient notification's auto-dismiss timer while hovered. */
+    pauseOnHover?: boolean;
+    /** @deprecated renderer dialect — use `defaultPosition` */
+    position?: NotificationPositionValue;
+    /**
+     * @deprecated renderer dialect with no spec counterpart. Read as "show only
+     * the newest" (`maxVisible: 1`) when false, so it is honored rather than
+     * fossilized; declare `maxVisible` instead.
+     */
     stacking?: boolean;
 }
+/** Config with the legacy spellings folded in and the spec defaults applied. */
+export interface ResolvedNotificationConfig {
+    defaultPosition?: NotificationPositionValue;
+    defaultDuration: number;
+    maxVisible: number;
+    stackDirection: 'up' | 'down';
+    pauseOnHover: boolean;
+}
+/**
+ * Fold the deprecated spellings into the spec ones and apply the spec defaults
+ * (`NotificationConfigSchema`: 5000ms / 5 visible / stack down / pause on
+ * hover). `defaultPosition` gets no fabricated default — see the field docs.
+ */
+export declare function resolveNotificationConfig(config?: NotificationSystemConfig): ResolvedNotificationConfig;
 export interface NotificationProviderProps {
     children: React.ReactNode;
     /** System configuration */
     config?: NotificationSystemConfig;
-    /** External toast handler (e.g., Sonner) for rendering toasts */
-    onToast?: (notification: NotificationItem) => void;
+    /**
+     * External toast handler (e.g. Sonner) — the `toast` presentation's surface.
+     *
+     * Called ONLY for `displayType: 'toast'`. It used to receive every
+     * notification, which is why the other four spec types all surfaced as
+     * toasts (#3014); they now render through their own surface components,
+     * which subscribe via {@link useNotificationsByPresentation}.
+     *
+     * The resolved config comes with it so the delegate can honor the parts of
+     * the contract only it can apply — `defaultPosition` above all, since the
+     * toast overlay is the host's.
+     */
+    onToast?: (notification: NotificationItem, config: ResolvedNotificationConfig) => void;
 }
 interface NotificationContextValue {
     /** All notifications (including history) */
@@ -83,19 +250,44 @@ interface NotificationContextValue {
     dismiss: (id: string) => void;
     /** Clear all notifications */
     clearAll: () => void;
-    /** System configuration */
-    config: NotificationSystemConfig;
+    /** System configuration, spec-normalized (see {@link resolveNotificationConfig}). */
+    config: ResolvedNotificationConfig;
+    /**
+     * Hold a transient notification's auto-dismiss timer (spec `pauseOnHover`).
+     * A surface calls this on pointer-enter; no-op when the notification is
+     * persistent or the config opted out.
+     */
+    pauseAutoDismiss: (id: string) => void;
+    /** Resume a held timer with the time it had left. */
+    resumeAutoDismiss: (id: string) => void;
+    /**
+     * Announce that a surface is mounted and will render `surface` items.
+     * Returns the unregister callback. Surfaces call this from an effect; the
+     * provider uses it only to warn (dev builds) when a notification is raised
+     * with nothing on screen able to present it.
+     */
+    registerSurface: (surface: NotificationSurface) => () => void;
 }
 /**
  * NotificationProvider — Provides a spec-driven notification system.
  *
+ * Each spec display type is presented by its own surface. `toast` is delegated
+ * to the host (`onToast`); the other four are rendered by surface components
+ * that subscribe to this context — mount them where they belong:
+ * `NotificationSnackbar` / `NotificationAlerts` anywhere inside the provider,
+ * `NotificationBanners` at the top of the content area, and
+ * `NotificationInline` in the surface that raises the notification.
+ *
  * @example
  * ```tsx
  * <NotificationProvider
- *   config={{ position: 'top-right', defaultDuration: 5000, maxVisible: 5 }}
+ *   config={{ position: 'top_right', defaultDuration: 5000, maxVisible: 5 }}
  *   onToast={(n) => toast[n.severity](n.title, { description: n.message })}
  * >
+ *   <NotificationBanners />
  *   <App />
+ *   <NotificationSnackbar />
+ *   <NotificationAlerts />
  * </NotificationProvider>
  * ```
  */
@@ -110,4 +302,40 @@ export declare function useNotifications(): NotificationContextValue;
  * Hook to check if a NotificationProvider is available.
  */
 export declare function useHasNotificationProvider(): boolean;
+/**
+ * Apply the config's stack rules to a surface's items: keep the newest
+ * `maxVisible`, then order them so the stack GROWS in `stackDirection`
+ * (`down`, the spec default, puts the newest below the older ones).
+ *
+ * Shared by the stacking surfaces (banner, inline) so `maxVisible` means one
+ * thing. It used to mean nothing at all — the config carried it and no surface
+ * read it, while `NotificationBanners` capped at a hard-coded 3 of its own.
+ *
+ * @param items the surface's notifications, newest-first
+ */
+export declare function visibleNotificationStack(items: NotificationItem[], config: Pick<ResolvedNotificationConfig, 'maxVisible' | 'stackDirection'>): NotificationItem[];
+/**
+ * The screen position a FLOATING notification (toast, snackbar) should take:
+ * its own `position`, else the configured `defaultPosition`, else `undefined`.
+ *
+ * `undefined` is a meaningful answer, not a missing one — it means "nothing was
+ * declared", and the surface should keep its own anchor (a snackbar's bottom
+ * edge) or defer to the host's toast chrome, rather than being moved by a
+ * default nobody asked for. Always returns the spec (underscore) spelling.
+ */
+export declare function resolveNotificationPosition(notification: Pick<NotificationItem, 'position'>, config?: Pick<ResolvedNotificationConfig, 'defaultPosition'>): NotificationPositionValue | undefined;
+/**
+ * Subscribe to the live notifications for ONE presentation — the contract a
+ * surface component implements (`@object-ui/components` ships one per spec
+ * type). Registering also tells the provider the surface exists, so raising a
+ * `banner` with no banner surface mounted warns in dev instead of vanishing.
+ *
+ * Items come back newest-first, matching `notifications`. A surface that wants
+ * FIFO order (an `alert` queue) reverses them itself.
+ *
+ * @param presentation the spec display type this surface renders
+ * @param scope optional `inline` routing key — when set, only items raised with
+ *   the same `scope` are returned; when omitted, only unscoped items are.
+ */
+export declare function useNotificationsByPresentation(presentation: NotificationPresentation, scope?: string): NotificationItem[];
 export {};