@antelopejs/interface-dms 0.4.0 → 0.4.2

package/dist/layout-banners.d.ts

@@ -1,5 +1,7 @@
 import { RegisteringProxy } from "@antelopejs/interface-core";
 import type { User } from "./auth/db";
+import type { BlockLinkAction } from "./base/display";
+import type { BlockText } from "./base/types/composed-text";
 import type { MaybePromise } from "./types";
 /**
  * Semantic look of a layout banner. It also picks the banner's ARIA role:
@@ -13,8 +15,8 @@ export declare const LayoutBannerVariant: {
 };
 export type LayoutBannerVariant = (typeof LayoutBannerVariant)[keyof typeof LayoutBannerVariant];
 /**
- * What a banner's `visible` resolver decides on: the request the site layout
- * is being built for.
+ * What a banner's `visible` or `resolve` resolver decides on: the request the
+ * site layout is being built for.
  */
 export interface LayoutBannerContext {
     /** Undefined for an unauthenticated request. */
@@ -41,6 +43,31 @@ export interface LayoutBannerContext {
  * does not answer within two seconds, hides its banner for that request.
  */
 export type LayoutBannerVisibility = (context: LayoutBannerContext) => MaybePromise<boolean>;
+/**
+ * What a text banner shows: its message and, after it, link buttons.
+ */
+export interface LayoutBannerContent {
+    /**
+     * The message: a `$`-prefixed value resolves as an i18n key, and a
+     * `ComposedText` is composed in the reader's language from the raw values
+     * it carries — an amount, a date, a count.
+     */
+    text: BlockText;
+    /**
+     * Link buttons after the message; the last one is the main action. Their
+     * labels follow the `$` convention.
+     */
+    actions?: BlockLinkAction[];
+}
+/**
+ * Builds a banner's content per request, or answers `undefined` to hide it:
+ * the visibility and the message in one read, for a banner whose message
+ * names the state that makes it show (an invoice number, the amount due, the
+ * date the workspace is suspended). Runs where and when a
+ * {@link LayoutBannerVisibility} does, under the same two-second budget: a
+ * resolver that throws or does not answer hides its banner for that request.
+ */
+export type LayoutBannerResolver = (context: LayoutBannerContext) => MaybePromise<LayoutBannerContent | undefined>;
 interface LayoutBannerBase {
     /**
      * Unique key of the banner across the deployment: re-registering a key
@@ -62,18 +89,19 @@ interface LayoutBannerBase {
      * leaves the banner out. Defaults to `false`.
      */
     dismissible?: boolean;
+}
+interface LayoutBannerStaticBase extends LayoutBannerBase {
     /** Absent means the banner shows on every request. */
     visible?: LayoutBannerVisibility;
+    resolve?: never;
 }
-/** A banner showing a line of text. */
-export interface LayoutBannerTextInfo extends LayoutBannerBase {
-    /** The message. A `$`-prefixed value resolves as an i18n key. */
-    text: string;
+/** A banner showing a fixed message, and optionally link buttons. */
+export interface LayoutBannerTextInfo extends LayoutBannerStaticBase, LayoutBannerContent {
     component?: never;
     props?: never;
 }
 /** A banner mounting a component of a frontend layer as its content. */
-export interface LayoutBannerComponentInfo extends LayoutBannerBase {
+export interface LayoutBannerComponentInfo extends LayoutBannerStaticBase {
     /**
      * Name of a global component, provided by a frontend layer, rendered as the
      * banner's content. The DMS still draws the chrome: color, icon, dismiss
@@ -83,21 +111,56 @@ export interface LayoutBannerComponentInfo extends LayoutBannerBase {
     /** Props passed to the component. Must be serializable. */
     props?: Record<string, unknown>;
     text?: never;
+    actions?: never;
+}
+/**
+ * A banner whose message and buttons are built per request by `resolve`,
+ * which also decides whether it shows.
+ *
+ * @example
+ * ```typescript
+ * RegisterLayoutBanner({
+ *   key: "saas:past-due",
+ *   variant: LayoutBannerVariant.ERROR,
+ *   resolve: async ({ tenantId }) => {
+ *     const invoice = await openInvoice(tenantId);
+ *     if (!invoice) return undefined;
+ *     return {
+ *       text: {
+ *         key: "saas.banner.past_due",
+ *         params: {
+ *           amount: { type: "money", value: invoice.due, currency: invoice.currency },
+ *           date: { type: "date", value: invoice.retryAt, format: "day" },
+ *         },
+ *       },
+ *       actions: [{ label: "$saas.banner.pay", to: "/settings/workspace/billing" }],
+ *     };
+ *   },
+ * });
+ * ```
+ */
+export interface LayoutBannerResolvedInfo extends LayoutBannerBase {
+    resolve: LayoutBannerResolver;
+    visible?: never;
+    text?: never;
+    actions?: never;
+    component?: never;
+    props?: never;
 }
 /**
  * A global banner rendered under the header of the dashboard layout, on every
  * page — tenant pages and module back-office pages alike.
  */
-export type LayoutBannerInfo = LayoutBannerTextInfo | LayoutBannerComponentInfo;
+export type LayoutBannerInfo = LayoutBannerTextInfo | LayoutBannerComponentInfo | LayoutBannerResolvedInfo;
 /** @internal */
 export declare namespace internal {
     const RegisterLayoutBanner: RegisteringProxy<(info: LayoutBannerInfo) => void>;
 }
 /**
  * Register a global banner under the dashboard header. Banners stack by
- * `order`, and each one's `visible` resolver is evaluated server-side for every
- * site layout request, so the banner is in the server-rendered page. When the
- * state a resolver reads changes, call `NotifyMenuChanged(tenantId)` so the
+ * `order`, and each one's `visible` or `resolve` resolver is evaluated
+ * server-side for every site layout request, so the banner is in the
+ * server-rendered page. When the state a resolver reads changes, call `NotifyMenuChanged(tenantId)` so the
  * connected clients re-fetch their site layout.
  *
  * The registration is dropped automatically when the registering module stops.

package/dist/layout-banners.js

@@ -20,9 +20,9 @@ var internal;
 })(internal || (exports.internal = internal = {}));
 /**
  * Register a global banner under the dashboard header. Banners stack by
- * `order`, and each one's `visible` resolver is evaluated server-side for every
- * site layout request, so the banner is in the server-rendered page. When the
- * state a resolver reads changes, call `NotifyMenuChanged(tenantId)` so the
+ * `order`, and each one's `visible` or `resolve` resolver is evaluated
+ * server-side for every site layout request, so the banner is in the
+ * server-rendered page. When the state a resolver reads changes, call `NotifyMenuChanged(tenantId)` so the
  * connected clients re-fetch their site layout.
  *
  * The registration is dropped automatically when the registering module stops.

package/dist/layout-banners.js.map

@@ -1 +1 @@
-{"version":3,"file":"layout-banners.js","sourceRoot":"","sources":["../src/layout-banners.ts"],"names":[],"mappings":";;;AA0HA,oDAGC;AA7HD,+DAA8D;AAI9D;;;;GAIG;AACU,QAAA,mBAAmB,GAAG;IACjC,IAAI,EAAE,MAAM;IACZ,OAAO,EAAE,SAAS;IAClB,KAAK,EAAE,OAAO;CACN,CAAC;AA0FX,gBAAgB;AAChB,IAAiB,QAAQ,CAIxB;AAJD,WAAiB,QAAQ;IACV,6BAAoB,GAAG,IAAI,iCAAgB,EAErD,CAAC;AACN,CAAC,EAJgB,QAAQ,wBAAR,QAAQ,QAIxB;AAED;;;;;;;;;;;GAWG;AACH,SAAgB,oBAAoB,CAAC,IAAsB;IACzD,QAAQ,CAAC,oBAAoB,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC7C,OAAO,GAAG,EAAE,CAAC,QAAQ,CAAC,oBAAoB,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;AAC9D,CAAC"}
+{"version":3,"file":"layout-banners.js","sourceRoot":"","sources":["../src/layout-banners.ts"],"names":[],"mappings":";;;AAmMA,oDAGC;AAtMD,+DAA8D;AAM9D;;;;GAIG;AACU,QAAA,mBAAmB,GAAG;IACjC,IAAI,EAAE,MAAM;IACZ,OAAO,EAAE,SAAS;IAClB,KAAK,EAAE,OAAO;CACN,CAAC;AAiKX,gBAAgB;AAChB,IAAiB,QAAQ,CAIxB;AAJD,WAAiB,QAAQ;IACV,6BAAoB,GAAG,IAAI,iCAAgB,EAErD,CAAC;AACN,CAAC,EAJgB,QAAQ,wBAAR,QAAQ,QAIxB;AAED;;;;;;;;;;;GAWG;AACH,SAAgB,oBAAoB,CAAC,IAAsB;IACzD,QAAQ,CAAC,oBAAoB,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC7C,OAAO,GAAG,EAAE,CAAC,QAAQ,CAAC,oBAAoB,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;AAC9D,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antelopejs/interface-dms",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Public AntelopeJS interfaces of the DMS: pages, components, permissions, tenancy, auth, notifications and HTML rendering.",
   "keywords": [
     "antelopejs",