@forgeroute/ui 0.4.68 → 0.4.70

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgeroute/ui",
-  "version": "0.4.68",
+  "version": "0.4.70",
   "peerDependencies": {
     "@angular/common": ">=22.0.0",
     "@angular/core": ">=22.0.0",

package/types/forgeroute-ui.d.ts

@@ -1,8 +1,8 @@
 import * as i0 from "@angular/core";
 import { EnvironmentProviders, InjectionToken, OnDestroy, OnInit, Signal, TemplateRef, WritableSignal } from "@angular/core";
 import { UrlTree } from "@angular/router";
-import { Observable } from "rxjs";
-import { AbstractControl, ControlValueAccessor, FormControl, ValidationErrors, Validator } from "@angular/forms";
+import { Observable, Subject } from "rxjs";
+import { AbstractControl, ControlValueAccessor, FormControl, ValidationErrors, Validator, ValidatorFn } from "@angular/forms";
 import { HttpInterceptorFn } from "@angular/common/http";
 import { SafeHtml } from "@angular/platform-browser";
 export interface ForgerouteConfig {
@@ -2387,6 +2387,54 @@ export declare class ModalComponent implements OnInit, OnDestroy {
   }, never, ["[modal-header-end]", "*", "[modal-footer-left]", "[modal-footer-center]", "[modal-footer-right]"], true, never>;
 }
 export type ToastType = 'success' | 'error' | 'info';
+/** A button on a toast (e.g. "View Contact", "Call Back"). */
+export interface ToastAction {
+  /** Identifies the button in `onAction` and in the `(action)` output; also the test id suffix (`toast-action-<id>`). */
+  id: string;
+  label: string;
+  /** Look of the button. Default `secondary`. */
+  variant?: 'primary' | 'secondary' | 'danger';
+  disabled?: boolean;
+  /** Keep the toast open after this button is used. Default `false`: using a button closes the toast. */
+  keepOpen?: boolean;
+}
+/** What `(action)` / `ToastService.action$` emit when a toast button is used. */
+export interface ToastActionEvent {
+  /** The `id` of the button. */
+  id: string;
+  /** The `key` of the toast it belongs to, when the toast had one. */
+  key?: string;
+}
+/**
+ * Per-message options for `show()` / `success()` / `info()` / `error()` / `notify()`. Every field is optional; a call without any of them is a plain
+ * toast exactly as before.
+ */
+export interface ToastOptions {
+  /** Only `notify()` reads this (`show` / `success` / `info` / `error` fix their own type). Default `success`. */
+  type?: ToastType;
+  /** How long it stays, in ms. Default: 3000 (4000 for errors). */
+  duration?: number;
+  /** A bold first line above the message. */
+  title?: string;
+  /** Buttons under the message. */
+  actions?: readonly ToastAction[];
+  /** Show "Dismissing in Ns" and a shrinking bar for this toast. Default: the outlet's / app's `countdown` setting (off). */
+  countdown?: boolean;
+  /** When another toast is showing, wait for it to finish instead of replacing it. Default: the outlet's / app's `queue` setting (off). */
+  queue?: boolean;
+  /** Identifies the toast: while one with the same key is showing or waiting, another one with that key is not added again (e.g. one per call id). */
+  key?: string;
+  /** Called with the `id` of a button when it is used (before the toast closes). */
+  onAction?: (actionId: string) => void;
+}
+/** What is known about the toast on screen beyond its message and type; `null` for a plain toast. */
+export interface ToastDetails {
+  title?: string;
+  actions: readonly ToastAction[];
+  countdown: boolean;
+  key?: string;
+  onAction?: (actionId: string) => void;
+}
 export declare class ToastService implements OnDestroy {
   readonly message: import("@angular/core").WritableSignal<string | null>;
   readonly type: import("@angular/core").WritableSignal<ToastType>;
@@ -2402,16 +2450,42 @@ export declare class ToastService implements OnDestroy {
    * Set once per app with `provideForgerouteToast({ persistentLiveRegion: true })`, or per outlet with `<ui-toast [persistentLiveRegion]="true" />`.
    */
   readonly persistentLiveRegion: import("@angular/core").WritableSignal<boolean>;
+  /** The title, buttons, countdown flag, key and callback of the toast on screen; `null` for a plain toast or none. */
+  readonly details: import("@angular/core").WritableSignal<ToastDetails | null>;
+  /** How many toasts are waiting behind the one on screen (queue mode). */
+  readonly queuedCount: import("@angular/core").WritableSignal<number>;
+  /** Default for `ToastOptions.queue`: new toasts wait for the one on screen instead of replacing it. Set with `provideForgerouteToast({ queue: true })` or `<ui-toast [queue]="true" />`. */
+  readonly queueDefault: import("@angular/core").WritableSignal<boolean>;
+  /** Default for `ToastOptions.countdown`. Set with `provideForgerouteToast({ countdown: true })` or `<ui-toast [countdown]="true" />`. */
+  readonly countdownDefault: import("@angular/core").WritableSignal<boolean>;
+  /** Most toasts that may wait; further ones are dropped. Default 20. Set with `provideForgerouteToast({ maxQueued })` or `<ui-toast [maxQueued]="n" />`. */
+  readonly maxQueued: import("@angular/core").WritableSignal<number>;
+  /** Time left of the toast on screen, in ms; only kept up to date for a toast with a countdown. */
+  readonly remainingMs: import("@angular/core").WritableSignal<number>;
+  /** The full time the toast on screen was given, in ms (the denominator of the countdown bar). */
+  readonly totalMs: import("@angular/core").WritableSignal<number>;
+  /** Emits when a toast button is used. */
+  readonly action$: Subject<ToastActionEvent>;
   private _timer;
+  private _ticker;
+  private _advanceTimer;
   private _deadline;
   private _remaining;
   private _paused;
-  show(msg: string, duration?: number): void;
+  private _queue;
+  /** Green success toast. `durationOrOptions` is the time in ms (default 3000) or a {@link ToastOptions} object. */
+  show(msg: string, durationOrOptions?: number | ToastOptions): void;
+  /** Green success toast, the explicit name for `show()` (same type, same 3000ms default, same behaviour). */
+  success(msg: string, durationOrOptions?: number | ToastOptions): void;
   /** Neutral (blue) toast for a result that is neither a success nor a failure, e.g. "No changes to save.". */
-  info(msg: string, duration?: number): void;
-  error(msg: string, duration?: number): void;
-  /** Removes the current toast now (close button / Escape). Safe when nothing is showing. */
+  info(msg: string, durationOrOptions?: number | ToastOptions): void;
+  error(msg: string, durationOrOptions?: number | ToastOptions): void;
+  /** A toast whose type comes from `options.type` (default `success`); the same as the named methods otherwise. */
+  notify(msg: string, options?: ToastOptions): void;
+  /** Removes the current toast now (close button / Escape); the next waiting one, if any, follows. Safe when nothing is showing. */
   dismiss(): void;
+  /** Uses the button `id` of the toast on screen: calls its `onAction`, emits `action$`, and closes the toast unless the button has `keepOpen`. No-op for an unknown or disabled button. */
+  runAction(id: string): void;
   /** Holds the countdown while the pointer or keyboard focus is on the toast (WCAG 2.2.1). No-op when nothing is counting down. */
   pause(): void;
   /** Continues after `pause()`; the toast gets at least 1000ms more so it can be read. No-op when not paused. */
@@ -2419,8 +2493,14 @@ export declare class ToastService implements OnDestroy {
   /** The root injector is destroyed (app teardown, TestBed reset): no timer may outlive it. */
   ngOnDestroy(): void;
   private _clearTimer;
+  private _clearTicker;
+  private _clearAdvance;
+  /** Starts the expiry timer (and the countdown ticker for a toast with a countdown). `fresh` = a new toast, not a resume after a pause. */
   private _start;
-  private _display;
+  /** The toast on screen is over (expired, dismissed or its button used): clear it and bring in the next waiting one after a short gap. */
+  private _finish;
+  private _enter;
+  private _present;
   static ɵfac: i0.ɵɵFactoryDeclaration<ToastService, never>;
   static ɵprov: i0.ɵɵInjectableDeclaration<any>;
 }
@@ -2446,6 +2526,28 @@ export declare class ToastComponent {
    */
   readonly persistentLiveRegion: import("@angular/core").InputSignal<boolean | null>;
   protected readonly persistent: import("@angular/core").Signal<boolean>;
+  /**
+   * Outlet-wide defaults for the optional parts of a toast (a message's own options win). `null` (default) leaves the app / service setting alone
+   * (`provideForgerouteToast`, itself off); a value is applied while this is the live outlet.
+   *
+   * - `queue`: a toast that arrives while another is showing waits for it instead of replacing it.
+   * - `countdown`: show "Dismissing in Ns" and a shrinking bar on every toast.
+   * - `maxQueued`: how many may wait (default 20).
+   */
+  readonly queue: import("@angular/core").InputSignal<boolean | null>;
+  readonly countdown: import("@angular/core").InputSignal<boolean | null>;
+  readonly maxQueued: import("@angular/core").InputSignal<number | null>;
+  /** Wording of the countdown line; `{n}` is the seconds left. */
+  readonly countdownLabel: import("@angular/core").InputSignal<string>;
+  /** Wording of the chip that says how many toasts are waiting; `{n}` is the count. */
+  readonly queueLabel: import("@angular/core").InputSignal<string>;
+  /** A toast button was used (also after its own `onAction`). */
+  readonly action: import("@angular/core").OutputEmitterRef<ToastActionEvent>;
+  protected readonly isRich: import("@angular/core").Signal<boolean>;
+  protected readonly countdownPct: import("@angular/core").Signal<number>;
+  protected readonly countdownText: import("@angular/core").Signal<string>;
+  protected readonly queueText: import("@angular/core").Signal<string>;
+  protected onAction(id: string): void;
   /**
    * Message that was already on screen when this instance took over from a destroyed host. While it is
    * unchanged the toast renders without the entry animation and without live-region roles, so the
@@ -2476,7 +2578,34 @@ export declare class ToastComponent {
       "required": false;
       "isSignal": true;
     };
-  }, {}, never, never, true, never>;
+    "queue": {
+      "alias": "queue";
+      "required": false;
+      "isSignal": true;
+    };
+    "countdown": {
+      "alias": "countdown";
+      "required": false;
+      "isSignal": true;
+    };
+    "maxQueued": {
+      "alias": "maxQueued";
+      "required": false;
+      "isSignal": true;
+    };
+    "countdownLabel": {
+      "alias": "countdownLabel";
+      "required": false;
+      "isSignal": true;
+    };
+    "queueLabel": {
+      "alias": "queueLabel";
+      "required": false;
+      "isSignal": true;
+    };
+  }, {
+    "action": "action";
+  }, never, never, true, never>;
 }
 export type ProgressBarVariant = 'blue' | 'green' | 'amber' | 'red' | 'slate';
 /**
@@ -3965,7 +4094,7 @@ export declare class ButtonComponent {
    * `ghost-start`: a ghost button for list / section toggles - a full-width row with its content aligned to the start, transparent
    * background, hover tint and the normal focus ring. Pair it with `ariaExpanded` / `ariaPressed`; the label may contain a heading element.
    */
-  readonly variant: import("@angular/core").InputSignal<"link" | "primary" | "secondary" | "danger" | "warning" | "ghost" | "ghost-start" | "tab" | "icon" | "icon-danger">;
+  readonly variant: import("@angular/core").InputSignal<"primary" | "secondary" | "danger" | "warning" | "link" | "ghost" | "ghost-start" | "tab" | "icon" | "icon-danger">;
   /** Renders an anchor to this route instead of a button (use with `variant="link"` for an inline text link). `['/settings']` or `'/settings'`. While `disabled` or `loading` it renders a non-clickable `<span role="link" aria-disabled>` with no href (like `href`). */
   readonly routerLink: import("@angular/core").InputSignal<string | readonly unknown[] | null>;
   /** Query params of the `routerLink` (e.g. `{ section: 'deal-defaults' }`). */
@@ -4011,7 +4140,7 @@ export declare class ButtonComponent {
   readonly color: import("@angular/core").InputSignal<string | undefined>;
   readonly active: import("@angular/core").InputSignal<boolean>;
   readonly size: import("@angular/core").InputSignal<"sm" | "md" | "lg" | "xs">;
-  readonly type: import("@angular/core").InputSignal<"button" | "reset" | "submit">;
+  readonly type: import("@angular/core").InputSignal<"reset" | "submit" | "button">;
   readonly disabled: import("@angular/core").InputSignal<boolean>;
   readonly loading: import("@angular/core").InputSignal<boolean>;
   readonly fullWidth: import("@angular/core").InputSignal<boolean>;
@@ -4283,9 +4412,9 @@ export interface ContactLookup {
   email: string | null;
   smsOptedIn: boolean;
 }
-declare function formatPhone(raw: string | null | undefined): string;
+declare function formatPhone$1(raw: string | null | undefined): string;
 export declare class ContactPickerComponent {
-  readonly formatPhone: typeof formatPhone;
+  readonly formatPhone: typeof formatPhone$1;
   readonly label: import("@angular/core").InputSignal<string>;
   readonly placeholder: import("@angular/core").InputSignal<string>;
   /** Helper text under the picker (linked to the search input via aria-describedby). */
@@ -4959,7 +5088,7 @@ export declare class TextInputComponent implements ControlValueAccessor, Validat
    * `search`, `text`, `none`). Empty (default) = the browser's default for the field, except `type="tel"`, which keeps `tel`.
    * It only picks the keyboard; it does not restrict what can be typed or pasted.
    */
-  readonly inputmode: import("@angular/core").InputSignal<"" | "search" | "none" | "text" | "email" | "tel" | "url" | "decimal" | "numeric">;
+  readonly inputmode: import("@angular/core").InputSignal<"" | "none" | "text" | "search" | "email" | "tel" | "url" | "decimal" | "numeric">;
   readonly readonly: import("@angular/core").InputSignal<boolean>;
   readonly hint: import("@angular/core").InputSignal<string>;
   /** Id(s) of an external element that also describes this control (e.g. one shared error text for a group of fields). Space separated; MERGED after the control's own hint / error id in `aria-describedby`, never replacing it. Empty = unchanged. */
@@ -5216,6 +5345,26 @@ export declare class TextInputComponent implements ControlValueAccessor, Validat
     "invalidChange": "invalidChange";
   }, never, ["[uiLabelEnd]"], true, never>;
 }
+/** Longest password the apps' servers accept (128 characters); use it as the password input's `maxlength`. */
+export declare const PASSWORD_MAX_LENGTH = 128;
+/**
+ * Policy of servers that accept only these special characters: 8+ characters, an uppercase letter, a lowercase letter, a digit and one of
+ * `@ $ ! % * ? & #`. (Anything else, e.g. `^` or a space, does NOT count as the special character.)
+ */
+export declare const LISTED_SPECIAL_PASSWORD_RULES: readonly PasswordRule[];
+/**
+ * Policy of servers that accept any ASCII symbol as the special character (character codes 33-126 that are not letters or digits): 8+ characters,
+ * an uppercase letter, a lowercase letter, a digit and one ASCII symbol. A space and non-ASCII characters (e.g. `é`) do NOT count.
+ */
+export declare const ASCII_SPECIAL_PASSWORD_RULES: readonly PasswordRule[];
+/**
+ * A form validator for a sign-up / reset-password control: the value must satisfy every rule and be at most `maxLength` characters. The error key
+ * is `passwordRules` (value `true`). A null / undefined value counts as an empty string (so it fails the rules; combine with `Validators.required`
+ * when an empty field should show a different message).
+ *
+ *   password = new FormControl('', [createPasswordPolicyValidator(LISTED_SPECIAL_PASSWORD_RULES)]);
+ */
+export declare function createPasswordPolicyValidator(rules: readonly PasswordRule[], maxLength?: number): ValidatorFn;
 /**
  * Number pad for short numeric codes such as a PIN. Shows one dot per allowed digit (filled as digits are entered) above a 3x4 grid of
  * 44px+ touch targets. The value is the digit string (`''` = nothing entered); it works with `[(value)]` and with `ngModel` / `FormControl`.
@@ -6495,7 +6644,7 @@ export declare class DropdownComponent {
   readonly loader: import("@angular/core").InputSignal<(() => Promise<DropdownItem[]>) | null>;
   readonly active: import("@angular/core").InputSignal<boolean>;
   readonly activeValue: import("@angular/core").InputSignal<string>;
-  readonly variant: import("@angular/core").InputSignal<"button" | "badge">;
+  readonly variant: import("@angular/core").InputSignal<"badge" | "button">;
   /** Trigger size for `variant="button"`: `sm` (default, the compact toolbar look) or `md` (same padding and type as a medium `ui-button`). */
   readonly size: import("@angular/core").InputSignal<"sm" | "md">;
   readonly menuWidth: import("@angular/core").InputSignal<string>;
@@ -7322,6 +7471,7 @@ export declare class NotesComponent {
  *   providers: [provideForgerouteToast()]
  *   providers: [provideForgerouteToast({ dismissible: true })]   // every toast also gets a close button (default: none)
  *   providers: [provideForgerouteToast({ persistentLiveRegion: true })]   // always-present live regions: reliable announcements in VoiceOver / Safari
+ *   providers: [provideForgerouteToast({ queue: true, countdown: true, maxQueued: 10 })]   // toasts wait for each other and show a countdown (defaults; a message's own options win)
  *
  * It is created first, so it is the registry's host and any other `<ui-toast>` (a table's own, a shell's) stays silent: each
  * message renders and is announced once. Nothing happens on the server. The outlet is destroyed with the app.
@@ -7329,6 +7479,9 @@ export declare class NotesComponent {
 export declare function provideForgerouteToast(options?: {
   dismissible?: boolean;
   persistentLiveRegion?: boolean;
+  queue?: boolean;
+  countdown?: boolean;
+  maxQueued?: number;
 }): EnvironmentProviders;
 /** Payload of `(reorder)`. Apply it with `reorderItems(items, order)` or take the ready-made `items`. */
 export interface ListReorderEvent<T = unknown> {
@@ -8048,6 +8201,39 @@ export interface UsStateOption {
   label: string;
 }
 export declare const US_STATES: UsStateOption[];
+/**
+ * The 50 US states (no DC) with their major cities, keyed by two-letter state code: `US_LOCATIONS['TX']` -> `['Abilene', ...]`. Cities are unique and
+ * trimmed per state. Use it for a city picker that follows a state select (the state names are in `US_STATES`).
+ */
+export declare const US_LOCATIONS: Record<string, string[]>;
+/**
+ * Look of the record-card groups on detail pages (the section header's title, icon and tint), so groups that exist in several apps look identical.
+ * Icon names are from the library's icon list; `background` is the section header's own light tint.
+ *
+ *   const GROUPS = { ...COMMON_DETAIL_GROUP_STYLES, deals: { title: 'Deals & Money', icon: 'opportunity', background: '#ecfdf5' } };
+ */
+export interface DetailGroupStyle {
+  title: string;
+  icon: string;
+  background: string;
+}
+/** The groups every app's detail pages share (the same title, icon and tint everywhere). An app adds its own groups next to these. */
+export declare const COMMON_DETAIL_GROUP_STYLES: {
+  readonly activity: {
+    readonly title: "Activity";
+    readonly icon: "message";
+    readonly background: "#eff6ff";
+  };
+  readonly notes: {
+    readonly title: "Notes";
+    readonly icon: "add-note";
+    readonly background: "#f1f5f9";
+  };
+};
+/** Header background of every record card on the detail pages (bound as the library card's `headerBackground`). */
+export declare const DETAIL_CARD_HEADER_BG = "#f8fafc";
+/** Light blue behind every group section header on the detail pages (large header with an icon tile and a description). */
+export declare const DETAIL_GROUP_HEADER_BG = "#eaf3ff";
 export interface NavLink {
   label: string;
   route: string;
@@ -11374,6 +11560,26 @@ declare function layoutLanes(boxes: {
   top: number;
   height: number;
 }[]): Record<string, CalendarLane>;
+/** A heading shared by consecutive agenda days (`ui-calendar` `agendaGroupFn`). Days that return the same `key` one after another sit under one heading. */
+interface CalendarAgendaGroup {
+  key: string;
+  label: string;
+}
+/**
+ * Ready-made `agendaGroupFn` for `ui-calendar`: Overdue (before `todayStr`), Today, Tomorrow, This Week (the rest of the current Sunday-first
+ * week) and Later (everything after). Pure `YYYY-MM-DD` string math (a day is added with the local `Date(y, m, d + n)` constructor, so a daylight
+ * saving change never shifts it); nothing parses a non-ISO string. A `todayStr` that is not a real day, or a day that is not a real
+ * `YYYY-MM-DD`, gives `null` (no heading) instead of a wrong group.
+ *
+ *   readonly group = computed(() => periodGroup(this.todayIso()));   // <ui-calendar [agendaGroupFn]="group()" />
+ */
+export declare function periodGroup(todayStr: string): (dateStr: string) => CalendarAgendaGroup | null;
+/** Level of a day's decoration (`ui-calendar` `dayDecorationFn`), lowest to highest. */
+type CalendarDayLevel = 'low' | 'medium' | 'high' | 'critical';
+/** What a screen reader hears for a decorated day (added to the cell's label, and shown as hidden text in the week view header). */
+declare const DAY_LEVEL_TEXT: Record<CalendarDayLevel, string>;
+/** True for the four known levels (an unknown string from a loosely typed host is ignored, not drawn). */
+declare function isDayLevel(level: unknown): level is CalendarDayLevel;
 /** One thing on the calendar. The host maps its own records to this shape. */
 export interface CalendarItem {
   /** Unique across ALL items passed in (prefix ids by source when merging lists, e.g. `task-…`, `event-…`). */
@@ -11428,6 +11634,29 @@ export interface CalendarSlotClick {
   /** `HH:00` of the clicked hour row. */
   time: string;
 }
+/** What `dayDecorationFn` returns for one day: a tint level and/or a tooltip. */
+export interface CalendarDayDecoration {
+  /** Tints the day (month cell background + a coloured top bar; week view day header) and adds "<level> activity" to its screen-reader label. */
+  level?: CalendarDayLevel;
+  /** Hover / keyboard-focus tooltip of the day (library `uiTooltip`). Empty = none. */
+  tooltip?: string;
+}
+/** One quick action offered on an item (`itemActionsFn`). */
+export interface CalendarItemAction {
+  /** Unique per item; reported back in `itemAction`. */
+  id: string;
+  /** Visible text (or the hover title and accessible name when `icon` is set). */
+  label: string;
+  /** Icon key of `<ui-icon>` (e.g. `check`, `edit`, `delete`). With an icon the button shows only the icon; without one it shows the label. */
+  icon?: string;
+  disabled?: boolean;
+  /** `danger` draws it red (destructive actions). */
+  variant?: 'default' | 'danger';
+}
+export interface CalendarItemActionEvent {
+  item: CalendarItem;
+  actionId: string;
+}
 /**
  * Month / week / agenda calendar. The host owns the data: it listens to `(rangeChange)`, loads that range and passes
  * the result as `items`. The calendar owns navigation, the view switcher, type filters, layout and keyboard access.
@@ -11507,8 +11736,28 @@ export declare class CalendarComponent {
   readonly startHour: import("@angular/core").InputSignal<number>;
   readonly endHour: import("@angular/core").InputSignal<number>;
   readonly emptyMessage: import("@angular/core").InputSignal<string>;
-  /** Builds the screen-reader name of a month cell; default "<weekday, date>, N events". */
+  /** Builds the screen-reader name of a month cell; default "<weekday, date>, N events" (plus ", <level> activity" when `dayDecorationFn` gives a level). */
   readonly dayLabelFn: import("@angular/core").InputSignal<((dateStr: string, items: CalendarItem[]) => string) | null>;
+  /**
+   * Optional per-day decoration (e.g. a workload heat map): called for every visible day with its items after the active filters. A `level`
+   * (`low` / `medium` / `high` / `critical`) tints the month cell (background + a coloured bar on top, so the level is not colour alone) and the
+   * week view day header, and adds "<level> activity" to the cell's default screen-reader label (a custom `dayLabelFn` label is used as given)
+   * and as hidden text in the week header. A `tooltip` shows on hover and keyboard focus (library `uiTooltip`). Null / `null` result = no change.
+   */
+  readonly dayDecorationFn: import("@angular/core").InputSignal<((dateStr: string, items: CalendarItem[]) => CalendarDayDecoration | null) | null>;
+  /**
+   * Optional quick actions on items (e.g. Confirm / Complete): called once per item, return `[]` for none. The actions are real buttons next to the
+   * item (month chip, all-day chip, timed event, agenda row) that appear on hover AND when keyboard focus is inside the item; they emit `itemAction`
+   * and never `itemClick`. On touch screens the agenda view always shows them (month and week chips show them while tapped / focused). Escape inside the
+   * actions returns focus to the item. Null = no actions and no extra DOM.
+   */
+  readonly itemActionsFn: import("@angular/core").InputSignal<((item: CalendarItem) => CalendarItemAction[]) | null>;
+  /**
+   * Optional agenda headings: called with each agenda day; consecutive days that return the same `key` share one `<h3>` heading (a `<section>`
+   * labelled by it). A `null` result draws that day without a heading. `periodGroup(today)` is a ready-made Overdue / Today / Tomorrow / This Week /
+   * Later grouping. Null = one block per date, as before.
+   */
+  readonly agendaGroupFn: import("@angular/core").InputSignal<((dateStr: string) => CalendarAgendaGroup | null) | null>;
   /** Fires on first render and whenever the view or the visible range changes: load this range, then pass `items`. */
   readonly rangeChange: import("@angular/core").OutputEmitterRef<CalendarRange>;
   readonly itemClick: import("@angular/core").OutputEmitterRef<CalendarItem>;
@@ -11518,6 +11767,8 @@ export declare class CalendarComponent {
   readonly slotClick: import("@angular/core").OutputEmitterRef<CalendarSlotClick>;
   /** "+N more" clicked in a month cell. */
   readonly moreClick: import("@angular/core").OutputEmitterRef<CalendarMoreClick>;
+  /** A quick action of an item (`itemActionsFn`) was activated. Never accompanied by `itemClick`. */
+  readonly itemAction: import("@angular/core").OutputEmitterRef<CalendarItemActionEvent>;
   private readonly host;
   protected readonly weekDayLabels: string[];
   protected readonly weekDayNames: string[];
@@ -11566,6 +11817,8 @@ export declare class CalendarComponent {
       overflow: number;
       clickable: boolean;
       label: string;
+      level: CalendarDayLevel | null;
+      tooltip: string;
     }[];
   }[]>;
   /** The 7 week columns with all-day items and the timed items laid out side by side when they overlap. */
@@ -11573,6 +11826,8 @@ export declare class CalendarComponent {
     day: import("@forgeroute/ui").CalendarDay;
     label: string;
     clickable: boolean;
+    level: CalendarDayLevel | null;
+    tooltip: string;
     allDay: CalendarItem[];
     timed: {
       lane: CalendarLane;
@@ -11605,6 +11860,29 @@ export declare class CalendarComponent {
   protected itemLabel(e: CalendarItem): string;
   protected agendaMeta(e: CalendarItem): string[];
   private dayAriaLabel;
+  /** The decoration of one day: an unknown `level` (loosely typed host) is dropped, a missing tooltip is `''`. */
+  private decoration;
+  protected levelText(level: CalendarDayLevel): string;
+  /** Quick actions per item id, computed once per input change (nothing is computed while `itemActionsFn` is null). */
+  private readonly actionsById;
+  private static readonly NO_ACTIONS;
+  protected actionsFor(item: CalendarItem): CalendarItemAction[];
+  protected actionIconD(a: CalendarItemAction): string | null;
+  protected onActionClick(item: CalendarItem, action: CalendarItemAction, event: Event): void;
+  /** Escape inside an item's actions: focus goes back to the item's own button. */
+  protected onActionsEscape(event: Event): void;
+  /** Agenda days grouped under `agendaGroupFn` headings (consecutive days with the same key), or null when no function is set. */
+  private static nextUid;
+  private readonly uid;
+  protected readonly agendaSections: import("@angular/core").Signal<{
+    key: string;
+    label: string;
+    id: string;
+    groups: {
+      dateStr: string;
+      items: CalendarItem[];
+    }[];
+  }[] | null>;
   protected onDateClick(dateStr: string): void;
   /** Grid keys on a day cell: arrows / Home / End move the tab stop, Enter / Space create. Keys on the chips inside never reach here. */
   protected onCellKey(event: KeyboardEvent, dateStr: string): void;
@@ -11724,6 +12002,21 @@ export declare class CalendarComponent {
       "required": false;
       "isSignal": true;
     };
+    "dayDecorationFn": {
+      "alias": "dayDecorationFn";
+      "required": false;
+      "isSignal": true;
+    };
+    "itemActionsFn": {
+      "alias": "itemActionsFn";
+      "required": false;
+      "isSignal": true;
+    };
+    "agendaGroupFn": {
+      "alias": "agendaGroupFn";
+      "required": false;
+      "isSignal": true;
+    };
   }, {
     "view": "viewChange";
     "anchorDate": "anchorDateChange";
@@ -11733,6 +12026,7 @@ export declare class CalendarComponent {
     "dateClick": "dateClick";
     "slotClick": "slotClick";
     "moreClick": "moreClick";
+    "itemAction": "itemAction";
   }, never, ["[calendar-summary]", "[calendar-actions]", "[calendar-summary-mobile]"], true, never>;
 }
 /**
@@ -11927,7 +12221,7 @@ export declare class ShowComponent {
   }, {}, never, ["*"], true, never>;
 }
 /**
- * Small formatting helpers shared by apps (money and postal addresses).
+ * Small formatting helpers shared by apps (money, postal addresses, names, phone numbers, durations and dates).
  */
 export interface FormatCurrencyOptions {
   /** ISO 4217 code. Default `'USD'`. */
@@ -11969,6 +12263,37 @@ export interface FormatAddressOptions {
  * with `{ style: 'usa' }` -> `1 Main, Austin, TX 78701`.
  */
 export declare function formatAddress(parts: AddressParts, options?: FormatAddressOptions): string;
+/**
+ * The first letter of the first and last name: `getInitials('Sarah', 'Chen')` -> `SC`. A missing name contributes nothing (`getInitials('Sarah', '')` -> `S`).
+ * Letters are returned as written (not upper-cased).
+ */
+export declare function getInitials(firstName: string | null | undefined, lastName: string | null | undefined): string;
+/**
+ * A length of time in seconds as text: `formatDuration(90)` -> `1m 30s`, `formatDuration(45)` -> `45s`. `null`, `undefined` and 0 give `''`.
+ * Hours are not split out (`3700` -> `61m 40s`).
+ */
+export declare function formatDuration(seconds: number | null | undefined): string;
+/**
+ * A phone number as `(555) 555-5555` while it is typed or stored: `formatPhone('5125550001')` -> `(512) 555-0001`. A US `+1` / leading `1` is dropped,
+ * other international numbers (a `+` that is not `+1` plus 10 digits) are returned as given, fewer digits give the partial form
+ * (`'512555'` -> `(512) 555`, `'512'` -> `512`) and more than 10 digits are cut to 10. `null`, `undefined` and `''` give `''`.
+ */
+export declare function formatPhone(raw: string | null | undefined): string;
+/**
+ * A US / Canada E.164 number as `+1 512 555-0100` (for showing a stored number). Any other value is returned as given (trimmed values are
+ * still formatted: `'  +15125550100  '` -> `+1 512 555-0100`); `null` and `undefined` give `''`. Use `formatPhone` for the domestic `(512) 555-0100` form.
+ */
+export declare function formatPhoneDisplay(e164: string | null | undefined): string;
+/**
+ * A date as short text: `formatShortDate('2026-01-05')` -> `Jan 5, 2026`; `''` / `null` / `undefined` give `—`. A plain `YYYY-MM-DD` is read as a LOCAL
+ * date (so it never shifts a day with the time zone); any other string goes through `new Date(...)` and uses the same en-US format.
+ */
+export declare function formatShortDate(value: string | null | undefined): string;
+/**
+ * Today's date as `YYYY-MM-DD` in the given IANA time zone (e.g. the user's profile time zone): `todayInTimezone('America/Phoenix')` -> `2026-10-13`.
+ * No or an invalid time zone falls back to the browser's local date.
+ */
+export declare function todayInTimezone(timezone?: string | null): string;
 /**
  * Starts the browser download of a blob under `fileName`. The anchor is attached to the page while it is clicked (Firefox ignores a click on
  * a detached anchor) and the object URL is revoked 1000 ms later (Safari reads it asynchronously, so an immediate revoke can cancel the
@@ -14097,4 +14422,4 @@ export declare class ConversationsComponent {
     "messagesRetry": "messagesRetry";
   }, never, ["[uiConversationsContext]"], true, never>;
 }
-export type { CalendarDay, CalendarRange, CalendarViewMode };
+export type { CalendarAgendaGroup, CalendarDay, CalendarDayLevel, CalendarRange, CalendarViewMode };