@forgeroute/ui 0.4.67 → 0.4.69

package/package.json

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

package/src/_detail-columns.scss

@@ -0,0 +1,32 @@
+// Independent column scrolling for detail pages (`<ui-sidebar-layout uiFillViewport>`): the viewport does not scroll; the two columns are capped
+// to the room under the page's top block (`--cols-h`, set by the `uiFillViewport` directive) and each scrolls inside its own box.
+//
+//   @use 'detail-columns' as dc;          // @forgeroute/ui/src is on the stylePreprocessorOptions includePaths
+//   @include dc.independent-columns;      // or (1200px) for collapseAt="lg"
+//
+// Markup: `.detail-page` wraps the page, `.col-main` is the `layout-main` element, `.col-side` is the `layout-side` element.
+// Only applies while the layout has two columns: `$collapse` = the sidebar-layout `collapseAt` width in px (900 = md, 1200 = lg); collapsed it is
+// one column and the page scrolls as usual. `$bleed` is the room inside the main column's scroll box so a focus ring or shadow at its edge is not clipped.
+@mixin independent-columns($collapse: 900px, $bleed: 4px) {
+  @media (min-width: #{$collapse + 1}) {
+    .detail-page { padding-bottom: 0; }   // the columns end at the bottom of the content area
+    .col-main {
+      position: relative;   // visually hidden / absolutely positioned content (sr-only text, menus) stays inside this scroll box; otherwise it is positioned against the page and stretches the document, which then scrolls
+      box-sizing: border-box;
+      padding: $bleed;
+      margin: -$bleed;
+      max-height: calc(var(--cols-h) + #{2 * $bleed});
+      overflow-y: auto;
+      overscroll-behavior: contain;
+      -webkit-overflow-scrolling: touch;
+    }
+    .col-side {
+      display: block;
+      position: relative;   // absolutely positioned content (visually hidden text, menus) stays inside this scroll box; otherwise it would stretch the library's outer side wrapper and give the column a second scrollbar
+      max-height: var(--cols-h);
+      overflow-y: auto;
+      overscroll-behavior: contain;
+      -webkit-overflow-scrolling: touch;
+    }
+  }
+}

package/types/forgeroute-ui-messaging.d.ts

@@ -115,7 +115,7 @@ export declare class TemplatePickerComponent {
   private readonly host;
   private readonly search$;
   /** Filter results to a specific channel: 'email', 'text', or omit for all. */
-  readonly channel: import("@angular/core").InputSignal<"" | "email" | "text">;
+  readonly channel: import("@angular/core").InputSignal<"" | "text" | "email">;
   readonly selectedId: import("@angular/core").InputSignal<string | null>;
   readonly label: import("@angular/core").InputSignal<string>;
   /** Shows the red required asterisk (same as the library inputs) — e.g. when a template must be picked to send. */
@@ -543,7 +543,7 @@ export declare class DocumentSendOptionsComponent implements UiFieldValidity {
   /** API root from FORGEROUTE_CONFIG (e.g. a cross-origin prod API); falls back to same-origin `/api`. */
   private readonly apiBase;
   /** `email` → purpose select + attachment allowed; `text` → link only (purpose fixed to e-signature). */
-  readonly channel: import("@angular/core").InputSignal<"email" | "text">;
+  readonly channel: import("@angular/core").InputSignal<"text" | "email">;
   readonly label: import("@angular/core").InputSignal<string>;
   /** When true, at least one document must be chosen. The message forms leave it false: documents are optional there. */
   readonly required: import("@angular/core").InputSignal<boolean>;
@@ -608,7 +608,7 @@ export declare class DocumentSendOptionsComponent implements UiFieldValidity {
   /** Roles of documents whose row had no `signerRoles` and that the host resolves (`signers().resolveRoles`). */
   readonly roleStates: import("@angular/core").WritableSignal<Record<string, RoleState>>;
   /** The envelope's documents: `loading` / `error` while the panel reads them (`loadDocuments`), `ready` once known. */
-  readonly envelopeStatus: import("@angular/core").WritableSignal<"idle" | "loading" | "ready" | "error">;
+  readonly envelopeStatus: import("@angular/core").WritableSignal<"error" | "loading" | "ready" | "idle">;
   private envelopeSub;
   private readonly roleSubs;
   /** The sender opened the collapsed "Signing options" line. */
@@ -1997,7 +1997,7 @@ export declare class SendMessagePanelComponent {
   readonly activeContact: import("@angular/core").WritableSignal<MessageContact | null>;
   /** What the sender should know about the picked contact before sending (why a channel is missing, what to add). */
   readonly contactNotices: import("@angular/core").Signal<string[]>;
-  readonly channel: import("@angular/core").WritableSignal<"email" | "text">;
+  readonly channel: import("@angular/core").WritableSignal<"text" | "email">;
   readonly valid: import("@angular/core").WritableSignal<boolean>;
   /** Bumped on every fresh open / new contact — re-creates the email and text forms so no draft carries over. */
   readonly formEpoch: import("@angular/core").WritableSignal<number>;

package/types/forgeroute-ui-stripe.d.ts

@@ -1300,7 +1300,7 @@ export declare class StripeConnectComponent {
   readonly navigateTab: import("@angular/core").InputSignal<((url: string) => void) | null>;
   protected readonly visible: import("@angular/core").Signal<boolean>;
   /** Which screen the card shows. */
-  protected readonly state: import("@angular/core").Signal<"none" | "complete" | "verifying" | "incomplete">;
+  protected readonly state: import("@angular/core").Signal<"complete" | "verifying" | "incomplete" | "none">;
   /** What the persistent status region says: the current state, plus "Loading." while a request runs. Empty while nothing is shown. */
   protected readonly liveText: import("@angular/core").Signal<string>;
   /** The user pressed a button that started a request: when the screen then changes, focus moves to the new screen (the pressed button is gone). */

package/types/forgeroute-ui.d.ts

@@ -2,7 +2,7 @@ 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 { AbstractControl, ControlValueAccessor, FormControl, ValidationErrors, Validator, ValidatorFn } from "@angular/forms";
 import { HttpInterceptorFn } from "@angular/common/http";
 import { SafeHtml } from "@angular/platform-browser";
 export interface ForgerouteConfig {
@@ -1095,7 +1095,7 @@ export declare class SelectComponent implements ControlValueAccessor, Validator,
   readonly error: import("@angular/core").InputSignal<string>;
   /** Reveal the built-in error messages now (e.g. after a failed Save click), without waiting for blur. */
   readonly showErrors: import("@angular/core").InputSignal<boolean>;
-  readonly size: import("@angular/core").InputSignal<"sm" | "default">;
+  readonly size: import("@angular/core").InputSignal<"default" | "sm">;
   readonly _disabledInput: import("@angular/core").InputSignal<boolean>;
   private readonly _cvaDisabled;
   protected readonly disabled: import("@angular/core").Signal<boolean>;
@@ -1591,6 +1591,8 @@ export declare class DataTableComponent<T extends Record<string, any>> implement
    */
   private _columnBadgeLabel;
   protected readonly _error: import("@angular/core").WritableSignal<string | null>;
+  /** Phone card list is only a role=list while it contains listitems: skeleton cards or real rows (not error / empty / no-match). */
+  protected readonly _cardListHasItems: Signal<boolean>;
   private readonly _loadFailed;
   /**
    * True from a failed load (the table shows its error state) until a later load SUCCEEDS. Unlike the error state itself it stays true while
@@ -2405,6 +2407,8 @@ export declare class ToastService implements OnDestroy {
   private _remaining;
   private _paused;
   show(msg: string, duration?: number): void;
+  /** Green success toast, the explicit name for `show()` (same type, same 3000ms default, same behaviour). */
+  success(msg: string, duration?: number): 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;
@@ -2682,7 +2686,7 @@ export declare class AudioPlayerComponent {
   /** Accessible name of the player. */
   readonly ariaLabel: import("@angular/core").InputSignal<string>;
   /** How much to load before play: 'metadata' (default), 'auto' or 'none'. */
-  readonly preload: import("@angular/core").InputSignal<"none" | "metadata" | "auto">;
+  readonly preload: import("@angular/core").InputSignal<"none" | "auto" | "metadata">;
   /** Fires when the browser can't load or decode the source. */
   readonly playbackError: import("@angular/core").OutputEmitterRef<void>;
   protected readonly failed: import("@angular/core").WritableSignal<boolean>;
@@ -2936,7 +2940,7 @@ export declare class CheckboxComponent implements ControlValueAccessor, Validato
    * clicking it still toggles the box - e.g. a product name that is both the heading of its card and the label of its checkbox.
    * Default null: plain label text, exactly as before. Single mode only.
    */
-  readonly headingLevel: import("@angular/core").InputSignal<1 | 2 | 5 | 3 | 6 | 4 | null>;
+  readonly headingLevel: import("@angular/core").InputSignal<1 | 2 | 3 | 4 | 5 | 6 | null>;
   readonly indeterminate: import("@angular/core").InputSignal<boolean>;
   readonly checked: import("@angular/core").ModelSignal<boolean>;
   /**
@@ -3963,7 +3967,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' }`). */
@@ -4009,7 +4013,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>;
@@ -4281,9 +4285,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). */
@@ -4948,7 +4952,7 @@ export declare class TextInputComponent implements ControlValueAccessor, Validat
   readonly passwordRequirements: import("@angular/core").InputSignal<boolean>;
   /** Rules for `passwordRequirements`; default = the library's five rules (8+ characters, upper, lower, digit, special). */
   readonly passwordRules: import("@angular/core").InputSignal<readonly PasswordRule[] | undefined>;
-  readonly type: import("@angular/core").InputSignal<"number" | "text" | "tel" | "email" | "password" | "url">;
+  readonly type: import("@angular/core").InputSignal<"number" | "text" | "email" | "tel" | "password" | "url">;
   readonly maxlength: import("@angular/core").InputSignal<number | undefined>;
   readonly required: import("@angular/core").InputSignal<boolean>;
   readonly autocomplete: import("@angular/core").InputSignal<string>;
@@ -4957,7 +4961,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<"" | "none" | "text" | "search" | "tel" | "email" | "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. */
@@ -5023,7 +5027,7 @@ export declare class TextInputComponent implements ControlValueAccessor, Validat
   protected readonly _stepAttr: import("@angular/core").Signal<string | null>;
   protected readonly _revealable: import("@angular/core").Signal<boolean>;
   protected readonly _shown: import("@angular/core").WritableSignal<boolean>;
-  protected readonly _inputType: import("@angular/core").Signal<"number" | "text" | "tel" | "email" | "password" | "url">;
+  protected readonly _inputType: import("@angular/core").Signal<"number" | "text" | "email" | "tel" | "password" | "url">;
   protected readonly _eyePath: string;
   protected readonly _eyeOffPath: string;
   protected readonly _showRequirements: import("@angular/core").Signal<boolean>;
@@ -5214,6 +5218,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`.
@@ -6823,7 +6847,7 @@ export declare class FormRowComponent {
  * child simply takes the full width. Keep a numeric span within the row's `cols` (use `all` for the whole row).
  */
 export declare class FormColSpanDirective {
-  readonly uiColSpan: import("@angular/core").InputSignal<"" | 2 | 3 | "2" | "3" | "all">;
+  readonly uiColSpan: import("@angular/core").InputSignal<"" | "2" | "3" | 2 | 3 | "all">;
   protected readonly _class: import("@angular/core").Signal<string>;
   static ɵfac: i0.ɵɵFactoryDeclaration<FormColSpanDirective, never>;
   static ɵdir: i0.ɵɵDirectiveDeclaration<FormColSpanDirective, "[uiColSpan]", never, {
@@ -8046,6 +8070,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;
@@ -8086,6 +8143,11 @@ export declare class AppShellComponent implements OnInit, OnDestroy {
    * when the title is not set.
    */
   readonly pageTitle: import("@angular/core").InputSignal<string>;
+  /**
+   * Show the app's toasts (renders one `<ui-toast />` for the whole shell). Default false so an app that already renders its own `<ui-toast />`
+   * is unchanged; an app that sets this removes its own.
+   */
+  readonly showToast: import("@angular/core").InputSignal<boolean>;
   readonly appName: import("@angular/core").InputSignal<string>;
   readonly user: import("@angular/core").InputSignal<ShellUser | null>;
   readonly readOnly: import("@angular/core").InputSignal<boolean>;
@@ -8103,6 +8165,10 @@ export declare class AppShellComponent implements OnInit, OnDestroy {
   readonly persistKey: import("@angular/core").InputSignal<string>;
   readonly logoutClick: import("@angular/core").OutputEmitterRef<void>;
   protected readonly _sidebarOpen: import("@angular/core").WritableSignal<boolean>;
+  /** `data.pageTitle` of the deepest activated route that sets one ('' when none does). Updated on every NavigationEnd. */
+  protected readonly _routeTitle: import("@angular/core").WritableSignal<string>;
+  /** The title shown in the top bar: the `pageTitle` input when the app sets one (it wins), else the route's `data.pageTitle`. */
+  protected readonly _title: import("@angular/core").Signal<string>;
   protected readonly _collapsed: import("@angular/core").WritableSignal<boolean>;
   /** The rail (icons-only sidebar) only exists on the desktop layout; on the drawer layout (≤1024px) a saved rail choice is ignored. */
   protected readonly _drawerLayout: import("@angular/core").WritableSignal<boolean>;
@@ -8144,6 +8210,8 @@ export declare class AppShellComponent implements OnInit, OnDestroy {
   ngOnInit(): void;
   private _drawerMq?;
   private readonly _onDrawerMqChange;
+  /** The `data.pageTitle` of the deepest activated route that has a non-empty string one (a child route's title wins over its parent's). */
+  private _titleOfRoute;
   ngOnDestroy(): void;
   private _expandActiveGroup;
   static ɵfac: i0.ɵɵFactoryDeclaration<AppShellComponent, never>;
@@ -8158,6 +8226,11 @@ export declare class AppShellComponent implements OnInit, OnDestroy {
       "required": false;
       "isSignal": true;
     };
+    "showToast": {
+      "alias": "showToast";
+      "required": false;
+      "isSignal": true;
+    };
     "appName": {
       "alias": "appName";
       "required": false;
@@ -9913,7 +9986,7 @@ export declare class DetailCardComponent {
   /** true (default) = the title is displayed in capitals (CSS only); false = shown as written. The text, aria-label and heading name are never changed. */
   readonly uppercaseTitle: import("@angular/core").InputSignal<boolean>;
   /** 1-6 makes the title a real heading for screen readers (role=heading, aria-level); null keeps it plain text. */
-  readonly headingLevel: import("@angular/core").InputSignal<1 | 2 | 5 | 3 | 6 | 4 | null>;
+  readonly headingLevel: import("@angular/core").InputSignal<1 | 2 | 3 | 4 | 5 | 6 | null>;
   /** Optional id for the title text; the card is then labelled by it. Without it the title is the card's aria-label. */
   readonly titleId: import("@angular/core").InputSignal<string>;
   /** Accessible name of the card when the header gives none (no header, or no title). A visible title wins; blank = no name. */
@@ -11197,6 +11270,28 @@ export declare class SidebarLayoutComponent {
     };
   }, {}, never, ["[layout-main]", "[layout-side]"], true, never>;
 }
+/**
+ * Independent column scrolling for a detail page's `<ui-sidebar-layout uiFillViewport>`.
+ *
+ * Sets `--cols-h` on the host: the room left between the top of the layout and the bottom of the shell's content area (the nearest
+ * `<main>`). Pair it with the `independent-columns` mixin (`@use 'detail-columns' as dc;` from `@forgeroute/ui/src/_detail-columns.scss`),
+ * which caps both columns to `--cols-h` so each scrolls on its own while the viewport does not scroll.
+ *
+ *   <ui-sidebar-layout uiFillViewport sideWidth="320px" collapseAt="md">
+ *     <div layout-main class="col-main"> ... </div>
+ *     <aside layout-side class="col-side"> ... </aside>
+ *   </ui-sidebar-layout>
+ *
+ * Re-measured when the content area or the element's parent changes size (window resize, tabs wrapping, a card loading). Pure layout maths
+ * on the element's position inside the scroller's content, so it does not depend on how far the page happens to be scrolled. The height is
+ * never below 240px. With no `<main>` ancestor nothing is set. Not related to `ui-page`'s `fillViewport` input (a page at least one viewport high).
+ */
+export declare class FillViewportDirective {
+  private readonly el;
+  constructor();
+  static ɵfac: i0.ɵɵFactoryDeclaration<FillViewportDirective, never>;
+  static ɵdir: i0.ɵɵDirectiveDeclaration<FillViewportDirective, "[uiFillViewport]", never, {}, {}, never, never, true, never>;
+}
 export type ActionBarAlign = 'start' | 'center' | 'end' | 'between';
 /**
  * Bar for page-level actions (Save / Cancel) that stays at the bottom of the scrolling area.
@@ -11334,6 +11429,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-…`). */
@@ -11388,6 +11503,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.
@@ -11467,8 +11605,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>;
@@ -11478,6 +11636,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[];
@@ -11526,6 +11686,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. */
@@ -11533,6 +11695,8 @@ export declare class CalendarComponent {
     day: import("@forgeroute/ui").CalendarDay;
     label: string;
     clickable: boolean;
+    level: CalendarDayLevel | null;
+    tooltip: string;
     allDay: CalendarItem[];
     timed: {
       lane: CalendarLane;
@@ -11565,6 +11729,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;
@@ -11684,6 +11871,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";
@@ -11693,6 +11895,7 @@ export declare class CalendarComponent {
     "dateClick": "dateClick";
     "slotClick": "slotClick";
     "moreClick": "moreClick";
+    "itemAction": "itemAction";
   }, never, ["[calendar-summary]", "[calendar-actions]", "[calendar-summary-mobile]"], true, never>;
 }
 /**
@@ -11887,7 +12090,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'`. */
@@ -11929,6 +12132,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
@@ -14057,4 +14291,4 @@ export declare class ConversationsComponent {
     "messagesRetry": "messagesRetry";
   }, never, ["[uiConversationsContext]"], true, never>;
 }
-export type { CalendarDay, CalendarRange, CalendarViewMode };
+export type { CalendarAgendaGroup, CalendarDay, CalendarDayLevel, CalendarRange, CalendarViewMode };