@forgeroute/ui 0.4.0 → 0.4.2

package/types/forgeroute-ui.d.ts

@@ -1,5 +1,6 @@
 import * as i0 from "@angular/core";
 import { ChangeDetectorRef, EnvironmentProviders, InjectionToken, OnDestroy, OnInit, Signal, TemplateRef, WritableSignal } from "@angular/core";
+import { UrlTree } from "@angular/router";
 import { AbstractControl, ControlValueAccessor, FormControl, ValidationErrors, Validator } from "@angular/forms";
 import { Observable, Subject } from "rxjs";
 import { HttpClient, HttpInterceptorFn } from "@angular/common/http";
@@ -99,7 +100,38 @@ export interface RowAction {
 /** Page-level permission passed to `<ui-data-table [permission]>`. Anything other than 'full' is read-only
  *  (apps use values like 'read-only' / 'hidden'). */
 export type TablePermission = 'full' | 'read' | 'read-only' | 'none' | 'hidden';
-export type CellType = 'text' | 'badge' | 'date' | 'phone' | 'number' | 'avatar-name' | 'days-ago' | 'progress' | 'tags' | 'image' | 'actions';
+export type CellType = 'text' | 'badge' | 'date' | 'phone' | 'number' | 'avatar-name' | 'days-ago' | 'progress' | 'tags' | 'image' | 'link' | 'actions';
+/**
+ * Where a `cellType: 'link'` cell points. Return a plain string from `linkFn` as shorthand for `{ href }`.
+ *
+ * - `routerLink` (+ `queryParams`) is an in-app route: the anchor gets the real URL as its `href` (so right-click,
+ *   middle-click, ctrl/cmd-click, "open in new tab" and "copy link address" all work) and a plain left click
+ *   navigates through the Angular `Router` without a page reload. `routerLink` wins when `href` is also set.
+ * - `href` accepts ONLY `mailto:`, `tel:`, `http:`, `https:` and root-relative paths (`/cases/12`). Anything else
+ *   (`javascript:`, `data:`, `//host`, empty, control characters) is never rendered as an href: the cell shows plain
+ *   text. A root-relative `href` is a normal link (full page load); use `routerLink` for in-app navigation.
+ * - `target: '_blank'` (default `'_self'`) adds `rel="noopener noreferrer"` and a "(opens in a new tab)" screen-reader
+ *   hint. `http(s):` hrefs always get the same `rel`.
+ * - `label` is the link text when the cell has no text of its own (`render` and `item[key]` are empty).
+ * - `ariaLabel` replaces the link's accessible name (default: its text).
+ * - `download` adds the `download` attribute.
+ */
+export interface LinkTarget {
+  href?: string;
+  routerLink?: string | readonly any[];
+  queryParams?: Record<string, any>;
+  target?: '_self' | '_blank';
+  label?: string;
+  ariaLabel?: string;
+  download?: boolean;
+}
+/** Payload of `(linkClick)`: a link cell's anchor was activated by a click (the row click is NOT also emitted). */
+export interface LinkClickEvent<T = any> {
+  item: T;
+  column: ColumnDef;
+  /** The anchor's href (null only for a routerLink that could not be resolved, which renders no anchor anyway). */
+  href: string | null;
+}
 export interface ColumnDef {
   key: string;
   label: string;
@@ -133,6 +165,13 @@ export interface ColumnDef {
    * Return null to render a plain '—' instead of a badge (e.g. for an empty value).
    */
   badgeFn?: (value: any, item?: any) => BadgeConfig | null;
+  /**
+   * Puts a gold `<ui-star>` to the LEFT of the cell's text when it returns a non-empty string; that string is the star's tooltip
+   * (hover / keyboard focus) and accessible name. Return null / undefined / '' for no star. The star is always gold.
+   * Applies to plain text cells (and the title of the phone card); the row's accessible name is unchanged (`nameFn` / `render`).
+   * Example: `{ key: 'name', label: 'Name', starFn: (doc) => doc.isAuthForm ? 'Authorization Form' : null }`
+   */
+  starFn?: (item: any) => string | null | undefined;
   /** Date format string. Default: 'MMM d, y' */
   dateFormat?: string;
   /** Returns the display name for the row. Default: item[col.key] */
@@ -158,6 +197,15 @@ export interface ColumnDef {
   /** Key in item holding the tags array. Defaults to col.key.
    *  Expected shape: { name: string; variant?: BadgeVariant }[] */
   tagsKey?: string;
+  /**
+   * `cellType: 'link'` — returns where the cell points for a row (`value` is `item[key]`), or null / undefined /
+   * '' for no link (the cell then shows plain text). A string is shorthand for `{ href }`. See {@link LinkTarget}
+   * for the contract and the allowed schemes. Text shown: `render(item)` if set, else `item[key]`, else the
+   * target's `label`, else '—'. The text is always escaped. A throwing `linkFn` renders plain text.
+   * Sorting, search, filters and export are independent of the link (export uses the host's `exportRow`).
+   * Clicking or keying the anchor never emits `rowClick`; it emits `(linkClick)`.
+   */
+  linkFn?: (item: any, value: any) => LinkTarget | string | null | undefined;
   /** Returns the image URL for the row. A falsy value (null / undefined / '') shows the placeholder icon. */
   imageFn?: (item: any) => string | null | undefined;
   /** Focal point (percent, 50/50 = centered) of the cropped image, applied as CSS object-position. */
@@ -887,6 +935,11 @@ export declare function formatTime(value: string | null | undefined): string;
 export interface SelectOption<V extends string | number = string> {
   value: V;
   label: string;
+  /**
+   * Optional longer explanation of this choice. The select shows the SELECTED option's description under the field (linked with
+   * `aria-describedby`) and sets it as the option's `title` tooltip where the browser shows one. Options without it are unchanged.
+   */
+  description?: string;
 }
 export declare class SelectComponent implements ControlValueAccessor, Validator, UiFieldValidity {
   readonly label: import("@angular/core").InputSignal<string>;
@@ -908,6 +961,10 @@ export declare class SelectComponent implements ControlValueAccessor, Validator,
   protected readonly _value: import("@angular/core").WritableSignal<string>;
   /** Index of the first option matching the written / chosen value, or -1 (so only ONE option is selected even with duplicate keys). */
   protected readonly _selectedIndex: import("@angular/core").Signal<number>;
+  /** The selected option's `description` ('' when none is selected or it has none); hidden while an error shows. */
+  protected readonly _selectedDescription: import("@angular/core").Signal<string>;
+  /** ids of the texts that describe the select: the error / hint, then the selected option's description. */
+  protected readonly _describedBy: import("@angular/core").Signal<string>;
   private readonly _reveal;
   private readonly _issue;
   /** True while the value breaks a built-in rule or the host passed an `[error]`. */
@@ -1114,6 +1171,15 @@ export declare class ImportExportComponent {
 }
 /** Simple English plural: "property" → "properties", "box" → "boxes", "contact" → "contacts". */
 export declare function pluralize(word: string): string;
+/** Resolved anchor data of a link cell (internal). */
+interface ResolvedLink {
+  href: string;
+  tree: UrlTree | null;
+  blank: boolean;
+  rel: string | null;
+  download: boolean;
+  ariaLabel: string | null;
+}
 export declare class DataTableComponent<T extends Record<string, any>> implements OnInit {
   readonly endpoint: import("@angular/core").InputSignal<string>;
   readonly columns: import("@angular/core").InputSignal<ColumnDef[]>;
@@ -1121,6 +1187,12 @@ export declare class DataTableComponent<T extends Record<string, any>> implement
   readonly pageSize: import("@angular/core").InputSignal<number>;
   readonly tableLabel: import("@angular/core").InputSignal<string>;
   readonly emptyMessage: import("@angular/core").InputSignal<string>;
+  /**
+   * Text of the retry button in the failed-load state (desktop table and phone cards). Plain text.
+   * Empty / blank keeps the error state's own default ("Try again").
+   */
+  readonly retryLabel: import("@angular/core").InputSignal<string>;
+  protected readonly _retryLabel: Signal<string>;
   readonly lockedColumn: import("@angular/core").InputSignal<string>;
   readonly savedViews: import("@angular/core").InputSignal<SavedView[]>;
   /**
@@ -1131,6 +1203,14 @@ export declare class DataTableComponent<T extends Record<string, any>> implement
   readonly page: import("@angular/core").InputSignal<string>;
   /** Show column config + saved views toolbar. Defaults true. Set false to hide both. */
   readonly showToolbar: import("@angular/core").InputSignal<boolean>;
+  /**
+   * Show the search box above the table. Defaults true. Set false for small fixed tables where searching is meaningless
+   * (a handful of summary rows). Quick-filter tabs and the toolbar are unaffected; when the search box, the tabs and the
+   * toolbar are all off, the header row above the table is not rendered at all.
+   */
+  readonly showSearch: import("@angular/core").InputSignal<boolean>;
+  /** False when the header row would be empty (no search box, no toolbar, no quick-filter tabs). */
+  protected readonly _showHeader: Signal<boolean>;
   /** Optional endpoint that returns Record<string,number> counts per quick-filter value. */
   readonly countsEndpoint: import("@angular/core").InputSignal<string>;
   /**
@@ -1179,6 +1259,12 @@ export declare class DataTableComponent<T extends Record<string, any>> implement
    */
   readonly bulkUpdateOptions: import("@angular/core").InputSignal<BulkUpdateOption<T>[]>;
   readonly rowClick: import("@angular/core").OutputEmitterRef<T>;
+  /**
+   * A `cellType: 'link'` anchor was clicked (plain or with ctrl/cmd/shift; a middle-button click is an `auxclick`, not emitted). Fires instead of
+   * `rowClick`: the anchor stops the click from reaching the row. For an in-app `routerLink` the table has already
+   * called `Router.navigateByUrl` on a plain left click (modifier / `_blank` clicks are left to the browser).
+   */
+  readonly linkClick: import("@angular/core").OutputEmitterRef<LinkClickEvent<T>>;
   /**
    * Optional per-row opt-out for (rowClick): rows where it returns false get no pointer cursor,
    * no tab stop and no click/keyboard activation (e.g. log rows with no linked record).
@@ -1447,6 +1533,13 @@ export declare class DataTableComponent<T extends Record<string, any>> implement
       activeValues: string[];
     };
   }[]>;
+  /**
+   * The sort buttons / icons and the column-filter icons only show while there is something to sort or filter: not after a failed
+   * load, and not when the table is empty because nothing exists or only a search / quick tab matched nothing (clear the search to
+   * get back). Once the user has used a column header control (a column filter or a sort is active) the controls stay, even with
+   * zero rows, so they can change or clear it. Headers are plain labels otherwise.
+   */
+  protected readonly _showColumnControls: Signal<boolean>;
   protected readonly _hasPhoneControls: Signal<boolean>;
   /** Phone sort select → sets the sort directly (same state, page reset and load as the header's onSort). */
   protected onPhoneSort(value: string): void;
@@ -1505,6 +1598,16 @@ export declare class DataTableComponent<T extends Record<string, any>> implement
   protected imageClass(col: ColumnDef, small: boolean): string;
   protected onImageError(url: string): void;
   protected phoneCell(value: any): string;
+  private readonly _injector;
+  /** Safe hrefs only: mailto:, tel:, http(s):// and root-relative paths. Everything else is refused (null). */
+  private _safeHref;
+  /** Text and (when there is a safe target) the anchor data of a `cellType: 'link'` cell. Never throws. */
+  protected linkView(col: ColumnDef, item: T): {
+    text: string;
+    link: ResolvedLink | null;
+  };
+  /** Anchor click: never reaches the row; a plain left click on an in-app route navigates via the Router (SPA, no reload). */
+  protected onLinkClick(e: MouseEvent, link: ResolvedLink, col: ColumnDef, item: T): void;
   protected getInitials(name: string): string;
   protected isCardOverdue(col: ColumnDef, item: T): boolean;
   /** Renders any non-badge column value as a plain string for the mobile card view. */
@@ -1561,6 +1664,11 @@ export declare class DataTableComponent<T extends Record<string, any>> implement
       "required": false;
       "isSignal": true;
     };
+    "retryLabel": {
+      "alias": "retryLabel";
+      "required": false;
+      "isSignal": true;
+    };
     "lockedColumn": {
       "alias": "lockedColumn";
       "required": false;
@@ -1581,6 +1689,11 @@ export declare class DataTableComponent<T extends Record<string, any>> implement
       "required": false;
       "isSignal": true;
     };
+    "showSearch": {
+      "alias": "showSearch";
+      "required": false;
+      "isSignal": true;
+    };
     "countsEndpoint": {
       "alias": "countsEndpoint";
       "required": false;
@@ -1648,6 +1761,7 @@ export declare class DataTableComponent<T extends Record<string, any>> implement
     };
   }, {
     "rowClick": "rowClick";
+    "linkClick": "linkClick";
     "tableButtonClick": "tableButtonClick";
     "panelActionClick": "panelActionClick";
     "saveViewClick": "saveViewClick";
@@ -2117,11 +2231,27 @@ export declare class AudioPlayerComponent {
     "playbackError": "playbackError";
   }, never, never, true, never>;
 }
+/**
+ * Shimmering placeholder for content that is loading.
+ *
+ * By default it is purely decorative (hidden from assistive tech), like before. Give ONE skeleton - or the wrapper of a group of them - an
+ * `ariaLabel` to announce the loading state: the host then becomes a polite live region (`role="status"`, `aria-live="polite"`,
+ * `aria-busy="true"`, named by the label) and is no longer hidden. Remove the skeleton (or the label) when the content has loaded.
+ *
+ *   <ui-skeleton [height]="44" ariaLabel="Loading submissions" />
+ *   <div role="status" aria-label="Loading report"> <ui-skeleton /> <ui-skeleton /> </div>   <!-- decorative skeletons inside a labelled wrapper -->
+ *
+ * Do not label every skeleton of a group: each labelled skeleton is its own live region and would be announced separately.
+ */
 export declare class SkeletonComponent {
   readonly height: import("@angular/core").InputSignal<number>;
   readonly width: import("@angular/core").InputSignal<string>;
   readonly radius: import("@angular/core").InputSignal<number>;
   readonly mb: import("@angular/core").InputSignal<number>;
+  /** Accessible name that turns the skeleton into a polite status region ("Loading ..."). Empty (default) = decorative, hidden from assistive tech. */
+  readonly ariaLabel: import("@angular/core").InputSignal<string>;
+  /** The trimmed label ('' = none). */
+  label(): string;
   static ɵfac: i0.ɵɵFactoryDeclaration<SkeletonComponent, never>;
   static ɵcmp: i0.ɵɵComponentDeclaration<SkeletonComponent, "ui-skeleton", never, {
     "height": {
@@ -2144,6 +2274,11 @@ export declare class SkeletonComponent {
       "required": false;
       "isSignal": true;
     };
+    "ariaLabel": {
+      "alias": "ariaLabel";
+      "required": false;
+      "isSignal": true;
+    };
   }, {}, never, never, true, never>;
 }
 /**
@@ -2177,6 +2312,33 @@ export declare class TooltipDirective {
     };
   }, {}, never, never, true, never>;
 }
+/**
+ * A small gold star with a hover / focus tooltip: `<ui-star tooltip="Authorization Form" />`.
+ *
+ * The star is always gold (there is no color input). `tooltip` is the text the user sees on hover or keyboard focus (library `uiTooltip`);
+ * it is also the star's accessible name, so a screen reader reads it too. Without a tooltip the star is decorative (hidden from assistive tech).
+ * In `<ui-data-table>` use `ColumnDef.starFn` to put one to the left of a text cell (e.g. the name column).
+ */
+export declare class StarComponent {
+  /** Tooltip text (also the accessible name). Empty = no tooltip and the star is decorative. */
+  readonly tooltip: import("@angular/core").InputSignal<string>;
+  /** Star size in px. Default 16. */
+  readonly size: import("@angular/core").InputSignal<number>;
+  protected readonly hasTooltip: import("@angular/core").Signal<boolean>;
+  static ɵfac: i0.ɵɵFactoryDeclaration<StarComponent, never>;
+  static ɵcmp: i0.ɵɵComponentDeclaration<StarComponent, "ui-star", never, {
+    "tooltip": {
+      "alias": "tooltip";
+      "required": false;
+      "isSignal": true;
+    };
+    "size": {
+      "alias": "size";
+      "required": false;
+      "isSignal": true;
+    };
+  }, {}, never, never, true, never>;
+}
 export type ImageRepositionShape = 'circle' | 'rounded';
 /**
  * Drag-to-center photo frame. The image fills the frame (`object-fit: cover`) and the user drags it, or uses the arrow
@@ -3073,7 +3235,7 @@ export declare class ButtonComponent {
    */
   readonly href: import("@angular/core").InputSignal<string | null>;
   /** Where to open the `href` (`_blank` = a new tab). */
-  readonly target: import("@angular/core").InputSignal<"_blank" | "_self" | "_parent" | "_top" | null>;
+  readonly target: import("@angular/core").InputSignal<"_self" | "_blank" | "_parent" | "_top" | null>;
   /** `rel` of the `href` link. A `_blank` target always gets `noopener noreferrer` added. */
   readonly rel: import("@angular/core").InputSignal<string | null>;
   /** The href when it is allowed (http, https, mailto, tel, sms or a relative URL), else null. */
@@ -6025,6 +6187,12 @@ export declare class TextInputComponent implements ControlValueAccessor, Validat
   readonly max: import("@angular/core").InputSignal<number | undefined>;
   /** `type="number"` only: most digits allowed after the decimal point. */
   readonly maxDecimals: import("@angular/core").InputSignal<number | undefined>;
+  /**
+   * `type="number"` only: how much the browser's spinner arrows and the Up / Down keys change the value (e.g. `0.01` for money).
+   * Leave it unset for the browser's default step of 1. A value that is not a number above 0 is ignored (also the default step).
+   * It only picks the increment; it does not restrict what can be typed (use `maxDecimals` for that).
+   */
+  readonly step: import("@angular/core").InputSignal<number | undefined>;
   /**
    * What the control value is. `'string'` (default) = the typed text. `'number'` = `number | null`; requires `type="number"`
    * (otherwise a dev-mode warning is logged once and string behaviour is used).
@@ -6043,6 +6211,8 @@ export declare class TextInputComponent implements ControlValueAccessor, Validat
   private readonly _reveal;
   /** True when the control value is a number: `valueType="number"` on a `type="number"` field. */
   private readonly _numeric;
+  /** The native `step` attribute: only for `type="number"` and only for a finite number above 0; otherwise none (the browser's step of 1). */
+  protected readonly _stepAttr: import("@angular/core").Signal<string | null>;
   private _warned;
   private readonly _formatting;
   private readonly _issue;
@@ -6152,6 +6322,11 @@ export declare class TextInputComponent implements ControlValueAccessor, Validat
       "required": false;
       "isSignal": true;
     };
+    "step": {
+      "alias": "step";
+      "required": false;
+      "isSignal": true;
+    };
     "valueType": {
       "alias": "valueType";
       "required": false;
@@ -6190,6 +6365,8 @@ export declare class TextareaInputComponent implements ControlValueAccessor, Val
    */
   readonly hintAsDescription: import("@angular/core").InputSignal<boolean>;
   readonly error: import("@angular/core").InputSignal<string>;
+  /** Opt-in. `true` shows the text in a monospace font (HTML / code / merge-tag fields). Default `false` = unchanged. */
+  readonly monospace: import("@angular/core").InputSignal<boolean>;
   /** 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>;
   protected readonly _disabledInput: import("@angular/core").InputSignal<boolean>;
@@ -6280,6 +6457,11 @@ export declare class TextareaInputComponent implements ControlValueAccessor, Val
       "required": false;
       "isSignal": true;
     };
+    "monospace": {
+      "alias": "monospace";
+      "required": false;
+      "isSignal": true;
+    };
     "showErrors": {
       "alias": "showErrors";
       "required": false;
@@ -7026,6 +7208,8 @@ export interface DropdownItem {
   label: string;
   value: string;
   count?: number;
+  /** Greyed-out, not selectable and skipped by keyboard navigation. */
+  disabled?: boolean;
 }
 export declare class DropdownComponent {
   readonly label: import("@angular/core").InputSignal<string>;
@@ -7036,16 +7220,54 @@ export declare class DropdownComponent {
   readonly activeValue: import("@angular/core").InputSignal<string>;
   readonly variant: import("@angular/core").InputSignal<"badge" | "button">;
   readonly menuWidth: import("@angular/core").InputSignal<string>;
+  /**
+   * Accessible name. Set it when the trigger has no meaningful visible text. Applied as `aria-label` on the
+   * trigger and on the menu; when empty (default) no `aria-label` is rendered, the trigger is named by its
+   * visible label and the menu by `aria-labelledby` pointing at the trigger. Surrounding whitespace is trimmed.
+   */
+  readonly ariaLabel: import("@angular/core").InputSignal<string>;
   readonly itemClick: import("@angular/core").OutputEmitterRef<DropdownItem>;
   protected readonly open: import("@angular/core").WritableSignal<boolean>;
   protected readonly loading: import("@angular/core").WritableSignal<boolean>;
   private readonly _loaded;
   private readonly _id;
+  private readonly _host;
+  private readonly _cdr;
+  private _pendingFocus;
+  private _typeahead;
+  private _typeaheadTimer;
+  private _destroyed;
+  protected readonly triggerId: string;
+  protected readonly menuId: string;
+  protected readonly _ariaLabel: import("@angular/core").Signal<string | null>;
   protected readonly displayItems: import("@angular/core").Signal<DropdownItem[]>;
   constructor();
   toggle(event: Event): void;
   select(item: DropdownItem): void;
   close(): void;
+  /**
+   * Keyboard contract (WAI-ARIA menu button).
+   * Trigger: Enter / Space toggle (opening focuses the first item), ArrowDown opens + first item,
+   * ArrowUp opens + last item, ArrowDown/ArrowUp while open move into the menu, Tab closes (focus moves on naturally).
+   */
+  protected onTriggerKeydown(event: KeyboardEvent): void;
+  /** Firefox fires the button click on Space keyup even when keydown was prevented. */
+  protected onTriggerKeyup(event: KeyboardEvent): void;
+  /**
+   * Menu keys (focus on an item): ArrowDown / ArrowUp move with wrap, Home / End jump to first / last,
+   * Enter / Space activate the focused item (native button click), Tab / Shift+Tab close and let focus move on from the trigger,
+   * printable characters jump to the next item whose label starts with the typed text (typeahead, reset after 500 ms).
+   * Disabled items are skipped. Other keys are ignored. Escape is handled on the host.
+   */
+  protected onMenuKeydown(event: KeyboardEvent): void;
+  protected onEscape(event: Event): void;
+  private _setOpen;
+  private _openAndFocus;
+  /** Renders the menu synchronously, then focuses the pending first / last enabled item. */
+  private _focusPending;
+  private _typeaheadFocus;
+  private _enabledItems;
+  private _focusTrigger;
   static ɵfac: i0.ɵɵFactoryDeclaration<DropdownComponent, never>;
   static ɵcmp: i0.ɵɵComponentDeclaration<DropdownComponent, "ui-dropdown", never, {
     "label": {
@@ -7083,6 +7305,11 @@ export declare class DropdownComponent {
       "required": false;
       "isSignal": true;
     };
+    "ariaLabel": {
+      "alias": "ariaLabel";
+      "required": false;
+      "isSignal": true;
+    };
   }, {
     "itemClick": "itemClick";
   }, never, never, true, never>;
@@ -7524,6 +7751,12 @@ export declare class ListComponent<T = unknown> {
  * The row has no list role of its own: put `role="list"` on the host container and `role="listitem"` on each `ui-bar-row`
  * (or wrap them in `ui-list`). The label names the inner progressbar (`aria-labelledby`) and `valueText`
  * (default: the count plus the share) is its `aria-valuetext`.
+ *
+ * Out-of-range input: only the BAR is clamped, never the text the user reads. The fill is always 0-100% of the track:
+ * `value` below 0, NaN, -Infinity or not a number (string, null, undefined) draws no fill; `value` above `max`
+ * (including +Infinity) fills 100%; `max` of 0, negative, NaN, +/-Infinity or not a number draws an empty bar. The progressbar's
+ * `aria-valuenow` is clamped to [0, max] and `aria-valuemax` is 0 for an invalid max. The count text keeps the real `value`
+ * (formatted; a non-finite or non-number value reads "0"), and `count` / `share` / `valueText` are shown and announced as given.
  * Layout: `minmax(0, 12rem) 1fr auto`; at 480px and below the label sits above the bar with the count at the end of the label line.
  */
 export declare class BarRowComponent {
@@ -7531,7 +7764,7 @@ export declare class BarRowComponent {
   readonly label: import("@angular/core").InputSignal<string>;
   /** This row's amount. */
   readonly value: import("@angular/core").InputSignal<number>;
-  /** The amount that fills the bar (e.g. the largest category's count). 0 / NaN / negative draws an empty bar. */
+  /** The amount that fills the bar (e.g. the largest category's count). 0 / NaN / negative / infinite / not a number draws an empty bar. */
   readonly max: import("@angular/core").InputSignal<number>;
   /** Fixed bar colour. Default blue; never follows completion. */
   readonly variant: import("@angular/core").InputSignal<ProgressBarVariant>;
@@ -7545,6 +7778,10 @@ export declare class BarRowComponent {
   readonly locale: import("@angular/core").InputSignal<string>;
   /** Unique id tying the label to the progressbar. */
   protected readonly labelId: string;
+  /** `value` made safe for the bar: anything that is not a real number becomes 0 (the bar clamps the rest to 0..max). */
+  protected readonly barValue: import("@angular/core").Signal<number>;
+  /** `max` made safe for the bar: only a finite number above 0 counts, everything else is 0 (empty bar). */
+  protected readonly barMax: import("@angular/core").Signal<number>;
   protected readonly countText: import("@angular/core").Signal<string>;
   protected readonly effectiveValueText: import("@angular/core").Signal<string>;
   static ɵfac: i0.ɵɵFactoryDeclaration<BarRowComponent, never>;
@@ -8289,13 +8526,17 @@ export declare class ErrorComponent {
   }, {}, never, never, true, never>;
 }
 export type KpiCardColor = 'green' | 'blue' | 'amber' | 'orange' | 'red' | 'slate';
-export type KpiCardValueColor = 'default' | 'green' | 'blue';
+/** Colour of the big value: `default` (dark slate), `green`, `blue`, or `red` (for figures that need attention: overdue, outstanding, failed). */
+export type KpiCardValueColor = 'default' | 'green' | 'blue' | 'red';
 /**
  * Compact KPI summary card: optional icon, uppercase label, large value, optional subtitle.
  * Set `clickable` to show a hover state + chevron (bind `(click)` on the host). A clickable card is a keyboard button:
  * role="button", focusable (tabindex 0, visible focus ring), and Enter / Space fire the host's (click). Give it an
  * accessible name with [attr.aria-label] when the label alone isn't enough (e.g. "Net Commission: $12.5K — show details").
  *
+ *   Optional background: `background="#fef2f2"` fills the card with any CSS colour (default white), e.g. a soft red for money going out; the
+ *   text keeps its own colours, so pick a light shade.
+ *
  *   Optional ring: `[progress]="67"` (+ `progressMax`, `progressVariant`, `progressSize`) draws a ui-progress-ring beside the label; extra lines
  *   (a pace badge, a projection…) go in an element with the `kpi-footer` attribute.
  *
@@ -8315,6 +8556,8 @@ export declare class KpiCardComponent {
   readonly highlight: import("@angular/core").InputSignal<boolean>;
   readonly clickable: import("@angular/core").InputSignal<boolean>;
   readonly valueColor: import("@angular/core").InputSignal<KpiCardValueColor>;
+  /** Card background as any CSS colour (`#fef2f2`, `var(--surface)` …). Empty (default) = white. The text colours do not change, so use a light shade. */
+  readonly background: import("@angular/core").InputSignal<string>;
   /** Completed amount shown as a `ui-progress-ring` beside the label. `null` (default) = no ring. */
   readonly progress: import("@angular/core").InputSignal<number | null>;
   /** Total for `progress` (default 100, so `progress` is a percentage). */
@@ -8374,6 +8617,11 @@ export declare class KpiCardComponent {
       "required": false;
       "isSignal": true;
     };
+    "background": {
+      "alias": "background";
+      "required": false;
+      "isSignal": true;
+    };
     "progress": {
       "alias": "progress";
       "required": false;
@@ -8411,6 +8659,167 @@ export declare class KpiCardComponent {
     };
   }, {}, never, ["[kpi-footer]"], true, never>;
 }
+interface StateView {
+  id: string;
+  name: string;
+  path: string;
+  value: number;
+  /** "12 pickups" (or just "12"). */
+  valueText: string;
+  /** "Texas, 12 pickups": the accessible name, the tooltip text and the hidden-list entry. */
+  label: string;
+  fill: string;
+}
+/**
+ * US choropleth map: the 50 states plus Washington, DC, each coloured from `colorLow` (value 0) to `colorHigh` (the largest
+ * value) by its number in `data`.
+ *
+ * Interaction and accessibility
+ * - Every state is a button (`role="button"`, name "Texas, 12 pickups", `aria-pressed` for the selected one). The group has a
+ *   single tab stop (roving tabindex: last focused state, else the selected one, else Alabama); arrow keys,
+ *   Home and End move between states in alphabetical order, Enter / Space emit `stateClick` with the abbreviation.
+ * - The tooltip (state name + value) shows on hover AND on keyboard focus; it is real text, `aria-hidden` because the
+ *   state's accessible name already says the same. Colour is never the only signal: values are in names, tooltip and the
+ *   visually hidden list of all states.
+ * - A selected state gets an orange outline and the others are dimmed; the focus ring is drawn as an overlay outline
+ *   (works the same in Chrome, Edge, Firefox and Safari) and only for keyboard focus.
+ * - `prefers-reduced-motion` turns the transitions off. Strokes use `vector-effect: non-scaling-stroke`, so outlines keep
+ *   their pixel width when `focusState` zooms in.
+ *
+ * Known limitation: the very small states (CT, DC, DE, HI, MA, MD, NH, NJ, RI, VT) are tiny touch targets on a phone. They
+ * are reachable by keyboard and screen reader like any other; set `showSmallStateButtons` for a row of 44px buttons for them.
+ * Territories are not on the map.
+ */
+export declare class UsStateMapComponent {
+  /** State abbreviation -> value. Keys are case-insensitive; unknown keys are ignored; numbers and numeric strings (`'5'`) are read as numbers, anything else (negative, NaN, Infinity, text, booleans, null) counts as 0; repeated keys (`tx` and `TX`) are added up. */
+  readonly data: import("@angular/core").InputSignal<Record<string, number>>;
+  /** Abbreviation of the selected state (orange outline, the others are dimmed). Unknown / null = none. */
+  readonly selectedState: import("@angular/core").InputSignal<string | null>;
+  /** Abbreviation of a state to zoom the map to (bounding box plus 15% padding). Unknown / null = the whole map. */
+  readonly focusState: import("@angular/core").InputSignal<string | null>;
+  /** Unit for one, e.g. "pickup": "Texas, 1 pickup". Empty = just the number. */
+  readonly unitSingular: import("@angular/core").InputSignal<string>;
+  /** Unit for other counts, e.g. "pickups". Empty = the singular text is used for every count. */
+  readonly unitPlural: import("@angular/core").InputSignal<string>;
+  /** Colour of a value of 0 (CSS hex or rgb()). Invalid values fall back to #e5e7eb. */
+  readonly colorLow: import("@angular/core").InputSignal<string>;
+  /** Colour of the largest value (CSS hex or rgb()). Invalid values fall back to #1e40af. */
+  readonly colorHigh: import("@angular/core").InputSignal<string>;
+  /** Shows the colour scale (0 to the largest value). */
+  readonly showLegend: import("@angular/core").InputSignal<boolean>;
+  /** Shows a row of buttons for the very small states (touch friendly, 44px). Off by default. */
+  readonly showSmallStateButtons: import("@angular/core").InputSignal<boolean>;
+  /** Accessible name of the whole map. */
+  readonly ariaLabel: import("@angular/core").InputSignal<string>;
+  /** CSS maximum width of the map (it always shrinks to its container). */
+  readonly maxWidth: import("@angular/core").InputSignal<string>;
+  /** Optional CSS height of the map, e.g. "420px". Empty = follows the width (aspect ratio of the map). */
+  readonly height: import("@angular/core").InputSignal<string>;
+  /** Emits the state's abbreviation (upper case) on click, tap, Enter or Space. */
+  readonly stateClick: import("@angular/core").OutputEmitterRef<string>;
+  private readonly host;
+  /** True between a pointer press and the click that follows: a mouse / touch focus must not draw the keyboard ring. */
+  protected pointerDown: boolean;
+  private readonly hoveredId;
+  private readonly focusedId;
+  private readonly lastFocusedId;
+  private readonly ringVisible;
+  protected readonly tipPos: import("@angular/core").WritableSignal<{
+    x: number;
+    y: number;
+  } | null>;
+  private readonly low;
+  private readonly high;
+  private readonly values;
+  private readonly max;
+  private unit;
+  private valueText;
+  protected readonly views: import("@angular/core").Signal<StateView[]>;
+  protected readonly smallViews: import("@angular/core").Signal<StateView[]>;
+  protected readonly selectedId: import("@angular/core").Signal<string | null>;
+  protected readonly selectedView: import("@angular/core").Signal<StateView | null>;
+  protected readonly focusRingView: import("@angular/core").Signal<StateView | null>;
+  protected readonly viewBox: import("@angular/core").Signal<string>;
+  /** The one state in the tab order: last focused, else selected, else the first. */
+  protected readonly tabStop: import("@angular/core").Signal<string>;
+  protected readonly tip: import("@angular/core").Signal<StateView | null>;
+  protected readonly gradient: import("@angular/core").Signal<string>;
+  protected readonly maxText: import("@angular/core").Signal<string>;
+  protected readonly legendLabel: import("@angular/core").Signal<string>;
+  protected opacityOf(id: string): string | null;
+  protected onHover(ev: PointerEvent, id: string): void;
+  protected onLeave(id: string): void;
+  protected clearHover(): void;
+  protected onClick(id: string): void;
+  protected onFocus(id: string): void;
+  protected onBlur(id: string): void;
+  protected onKey(ev: KeyboardEvent, id: string): void;
+  static ɵfac: i0.ɵɵFactoryDeclaration<UsStateMapComponent, never>;
+  static ɵcmp: i0.ɵɵComponentDeclaration<UsStateMapComponent, "ui-us-state-map", never, {
+    "data": {
+      "alias": "data";
+      "required": false;
+      "isSignal": true;
+    };
+    "selectedState": {
+      "alias": "selectedState";
+      "required": false;
+      "isSignal": true;
+    };
+    "focusState": {
+      "alias": "focusState";
+      "required": false;
+      "isSignal": true;
+    };
+    "unitSingular": {
+      "alias": "unitSingular";
+      "required": false;
+      "isSignal": true;
+    };
+    "unitPlural": {
+      "alias": "unitPlural";
+      "required": false;
+      "isSignal": true;
+    };
+    "colorLow": {
+      "alias": "colorLow";
+      "required": false;
+      "isSignal": true;
+    };
+    "colorHigh": {
+      "alias": "colorHigh";
+      "required": false;
+      "isSignal": true;
+    };
+    "showLegend": {
+      "alias": "showLegend";
+      "required": false;
+      "isSignal": true;
+    };
+    "showSmallStateButtons": {
+      "alias": "showSmallStateButtons";
+      "required": false;
+      "isSignal": true;
+    };
+    "ariaLabel": {
+      "alias": "ariaLabel";
+      "required": false;
+      "isSignal": true;
+    };
+    "maxWidth": {
+      "alias": "maxWidth";
+      "required": false;
+      "isSignal": true;
+    };
+    "height": {
+      "alias": "height";
+      "required": false;
+      "isSignal": true;
+    };
+  }, {
+    "stateClick": "stateClick";
+  }, never, never, true, never>;
+}
 export type DatePreset = 'today' | '7days' | '30days' | 'month' | 'quarter' | 'ytd' | 'all' | 'custom';
 export interface DateRange {
   preset: DatePreset;
@@ -8848,6 +9257,7 @@ export declare class RadioMatrixComponent implements ControlValueAccessor, Valid
  * Header (all optional - set `[showHeader]="false"` and the card is just the body):
  *  - `title` / `subtitle`: the bold uppercase title and the grey line under it.
  *  - `titleId`: an id for the title text, which also names the card for assistive tech (aria-labelledby).
+ *  - `ariaLabel`: the card's accessible name when the header does not provide one (`[showHeader]="false"`, or a header with no title). A visible title always wins; `titleId` still names the card by aria-labelledby.
  *  - `<div card-header-leading>`: something before the title block, such as a logo or an icon.
  *  - `<ng-container card-header>`: your own header content, shown under the title (or instead of it when no title is set).
  *  - `<ng-container card-header-action>`: buttons or links on the right side of the header.
@@ -8863,6 +9273,7 @@ export declare class RadioMatrixComponent implements ControlValueAccessor, Valid
  *   <ui-detail-card title="COMMUNICATIONS" subtitle="All calls, texts, and emails"> ...body... </ui-detail-card>
  *   <ui-detail-card title="CONTACT INFO" [showEdit]="true" (editClick)="openEdit()"> ... </ui-detail-card>
  *   <ui-detail-card [showHeader]="false"> ...body only... </ui-detail-card>
+ *   <ui-detail-card [showHeader]="false" ariaLabel="Report filters"> ...body only, but named for assistive tech... </ui-detail-card>
  *   <ui-detail-card [collapsible]="false">
  *     <div card-header>Any markup</div>
  *     <ui-button card-header-action size="xs" variant="secondary">Add</ui-button>
@@ -8876,6 +9287,8 @@ export declare class DetailCardComponent {
   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. */
+  readonly ariaLabel: import("@angular/core").InputSignal<string>;
   /** Grey line under the title. */
   readonly subtitle: import("@angular/core").InputSignal<string>;
   /** Card background as any CSS colour (`#f8fafc`, `var(--surface)` …). Empty = white. */
@@ -8892,6 +9305,8 @@ export declare class DetailCardComponent {
   readonly showEdit: import("@angular/core").InputSignal<boolean>;
   readonly editLabel: import("@angular/core").InputSignal<string>;
   readonly editClick: import("@angular/core").OutputEmitterRef<void>;
+  /** The group's aria-label: the visible title (unless `titleId` names the card instead), else `ariaLabel`, else none. */
+  groupLabel(): string | null;
   /** The body is open unless the card has a header that is collapsible and was collapsed. */
   isOpen(): boolean;
   toggle(): void;
@@ -8914,6 +9329,11 @@ export declare class DetailCardComponent {
       "required": false;
       "isSignal": true;
     };
+    "ariaLabel": {
+      "alias": "ariaLabel";
+      "required": false;
+      "isSignal": true;
+    };
     "subtitle": {
       "alias": "subtitle";
       "required": false;
@@ -9246,8 +9666,12 @@ export declare class ColorInputComponent implements ControlValueAccessor, Valida
  *  - `iconColor`: colour of the icon (default blue #2563eb).
  *  - `iconBackground`: colour of the tile behind the icon (default white when a `background` is set, otherwise light grey #f1f5f9).
  *  - `bordered`: 1px #e2e8f0 border and 10px radius (default false).
- *  - `size`: 'md' (default; 1rem title, 28px tile) or 'sm' (0.875rem title, 24px tile).
- *  Padding is built in (14px 18px; 12px 14px at 480px and narrower) - there is no padding input.
+ *  - `size`: the visual size only (the semantic heading `level` is independent of it). Anything else becomes 'md'.
+ *      'sm'  0.875rem (14px) title, 0.75rem description, 24px tile, 14px icon; padding 14px 18px (12px 14px at 480px and narrower)
+ *      'md'  (default) 1rem (16px) title, 0.8125rem description, 28px tile, 16px icon; padding 14px 18px (12px 14px at 480px and narrower)
+ *      'lg'  1.25rem (20px) title, 0.9375rem description, 36px tile, 20px icon; padding 18px 22px (14px 16px at 480px and narrower)
+ *      'xl'  1.5rem (24px) title (1.375rem at 480px and narrower), 1rem description, 44px tile, 24px icon; padding 22px 26px (16px 18px at 480px and narrower)
+ *  Padding is built in per size - there is no padding input.
  *
  * Content slots:
  *  - `[section-header-icon]`: your own icon (an `<svg>`, an `<img>` ...) shown in the tile instead of the `icon` input.
@@ -9278,8 +9702,8 @@ export declare class SectionHeaderComponent {
   readonly iconBackground: import("@angular/core").InputSignal<string>;
   /** 1px border and 10px corners. */
   readonly bordered: import("@angular/core").InputSignal<boolean>;
-  /** 'md' (default) or 'sm'. */
-  readonly size: import("@angular/core").InputSignal<"sm" | "md">;
+  /** Visual size: 'sm', 'md' (default), 'lg' or 'xl'. Independent of `level`; anything else renders as 'md'. */
+  readonly size: import("@angular/core").InputSignal<"sm" | "md" | "lg" | "xl">;
   protected readonly titleId: string;
   protected readonly descriptionId: string;
   protected readonly headingLevel: import("@angular/core").Signal<number>;