@forgeroute/ui 0.4.1 → 0.4.2

package/package.json

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

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. */
@@ -906,7 +954,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>;
@@ -1123,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[]>;
@@ -1202,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).
@@ -1535,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. */
@@ -1688,6 +1761,7 @@ export declare class DataTableComponent<T extends Record<string, any>> implement
     };
   }, {
     "rowClick": "rowClick";
+    "linkClick": "linkClick";
     "tableButtonClick": "tableButtonClick";
     "panelActionClick": "panelActionClick";
     "saveViewClick": "saveViewClick";
@@ -2130,7 +2204,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>;
@@ -2238,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
@@ -3011,7 +3112,7 @@ export declare class PhoneNumberPickerComponent {
   protected readonly modeCtl: FormControl<string>;
   protected readonly zipCtl: FormControl<string>;
   protected readonly areaCtl: FormControl<string>;
-  protected readonly step: import("@angular/core").WritableSignal<2 | 1 | 3>;
+  protected readonly step: import("@angular/core").WritableSignal<1 | 2 | 3>;
   protected readonly mode: import("@angular/core").WritableSignal<PhoneNumberSearchMode>;
   private readonly _zip;
   private readonly _area;
@@ -3134,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. */
@@ -3142,8 +3243,8 @@ export declare class ButtonComponent {
   protected readonly _rel: import("@angular/core").Signal<string | null>;
   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" | "submit" | "reset">;
+  readonly size: import("@angular/core").InputSignal<"sm" | "md" | "xs" | "lg">;
+  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>;
@@ -6074,7 +6175,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" | "email" | "tel" | "search" | "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>;
   readonly error: import("@angular/core").InputSignal<string>;
@@ -6086,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).
@@ -6104,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;
@@ -6213,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;
@@ -6251,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>;
@@ -6341,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;
@@ -7211,7 +7332,7 @@ export declare class FormSectionComponent {
   }, {}, never, ["*"], true, never>;
 }
 export declare class FormRowComponent {
-  readonly cols: import("@angular/core").InputSignal<2 | 1 | 3>;
+  readonly cols: import("@angular/core").InputSignal<1 | 2 | 3>;
   static ɵfac: i0.ɵɵFactoryDeclaration<FormRowComponent, never>;
   static ɵcmp: i0.ɵɵComponentDeclaration<FormRowComponent, "ui-form-row", never, {
     "cols": {
@@ -8405,7 +8526,8 @@ 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:
@@ -9162,7 +9284,7 @@ export declare class DetailCardComponent {
   /** Bold uppercase title. Empty = no title text. */
   readonly title: import("@angular/core").InputSignal<string>;
   /** 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<2 | 1 | 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. */