@tekus/design-system 5.38.1 → 5.40.0

package/types/tekus-design-system-components-data-list.d.ts

@@ -0,0 +1,193 @@
+import * as _angular_cdk_layout from '@angular/cdk/layout';
+import * as _angular_core from '@angular/core';
+import { TagSeverity } from '@tekus/design-system/components/tag';
+
+/**
+ * How the pairs are arranged.
+ *
+ * - `'list'`: a single vertical column at 100% width. Each item lays out
+ *   horizontally — term on the left, value on the right — with a divider between items.
+ * - `'grid'`: a responsive multi-column grid with no dividers. Each item stacks
+ *   vertically — term above value. The column count is owned by the component
+ *   (see `DataListComponent.gridColumnCount`), not by the consumer.
+ */
+type TkDataListLayout = 'list' | 'grid';
+/**
+ * The closed set of value types a data list can render.
+ *
+ * This union is deliberately closed: a value is governed, typed data, not free-form
+ * content. Adding a type is a system-level change, never something a consumer does
+ * inline.
+ *
+ * It expresses the same idea as `tk-table`'s `TableColumnType` — typed values rather
+ * than free-form content — but the two unions are independent and only overlap on
+ * `'text'` and `'tag'`. Do not expect parity: `'link'` and `'number'` exist only here,
+ * and table's `'image'`, `'actions'`, `'checkbox'`, `'selection'`, `'action-group'` and
+ * `'connection-status'` exist only there. Unifying the vocabulary would be a
+ * system-level decision affecting both components.
+ */
+type TkDataListValueType = 'text' | 'link' | 'tag' | 'number';
+/**
+ * A single term→value pair rendered by `tk-data-list`.
+ */
+interface TkDataListItem {
+    /** The term naming the value. Required. */
+    label: string;
+    /**
+     * The value to render.
+     *
+     * `null`, `undefined` and blank strings all render as the `--` placeholder,
+     * uniformly across every `type`. Note that `0` is a real value, not an empty one.
+     */
+    value: string | number | null | undefined;
+    /**
+     * How the value is rendered.
+     * @default 'text'
+     */
+    type?: TkDataListValueType;
+    /** An optional secondary line beneath the label. */
+    description?: string;
+    /**
+     * An optional icon shown in a secondary icon avatar before the label.
+     * Forwarded to `tk-avatar` as `variant="icon"`; decorative and hidden from
+     * assistive technology.
+     */
+    leadingIcon?: string;
+    /**
+     * The colour scheme of the tag. Only used when `type` is `'tag'`.
+     * @default 'primary'
+     */
+    tagSeverity?: TagSeverity;
+    /**
+     * Invoked when the value is activated. Required in practice for `type: 'link'`.
+     *
+     * Link values render a `tk-button` in its link variant, so they are
+     * action-based rather than href-based: this callback is the navigation or
+     * action hook. Assistive technology announces them as buttons.
+     *
+     * A `'link'` without a handler would be a button that does nothing, so it is
+     * rendered as plain text instead — no dead control reaches the accessibility
+     * tree or the tab order.
+     */
+    handler?: () => void;
+}
+
+/** Rendered in place of a value that is `null`, `undefined` or a blank string. */
+declare const DATA_LIST_EMPTY_PLACEHOLDER = "--";
+/**
+ * @component DataListComponent
+ * @description
+ * Displays a collection of read-only term→value pairs, where each value is a typed
+ * piece of data (text, link, tag or number). It is the pair-oriented sibling of
+ * `tk-table`: both render governed, typed values, but the data list presents them as
+ * label→value pairs instead of rows and columns. Use it for detail panels, record
+ * summaries and entity overviews.
+ *
+ * This component supports:
+ * - `items`: the pairs to render. See {@link TkDataListItem}.
+ * - `layout`: `'list'` (one column, dividers, term left / value right) or `'grid'`
+ *   (responsive multi-column, no dividers, term above value).
+ * - `emptyPlaceholder`: the text rendered in place of an empty value.
+ *
+ * The consumer only chooses the layout. Everything that follows from it — item
+ * orientation, dividers and the responsive column count — is owned by the component.
+ * To vary the layout across breakpoints (e.g. list on mobile, grid on desktop), switch
+ * the `layout` input at your own breakpoint.
+ *
+ * Renders as a description list (`<dl>`) so assistive technology announces each entry
+ * as a term→value pair. Interactivity lives inside the value, never on the item — the
+ * item itself is neither focusable nor clickable.
+ *
+ * @usage
+ * ### Basic Usage
+ * ```html
+ * <tk-data-list [items]="details" layout="list"></tk-data-list>
+ * ```
+ * ```ts
+ * details: TkDataListItem[] = [
+ *   { label: 'Owner', value: 'Ana Bermúdez' },
+ *   { label: 'Status', value: 'Active', type: 'tag' },
+ *   { label: 'Devices', value: 2322, type: 'number' },
+ *   { label: 'Contract', value: 'Open', type: 'link', handler: () => this.openContract() },
+ * ];
+ * ```
+ */
+declare class DataListComponent {
+    /**
+     * The term→value pairs to render, in order.
+     * @default []
+     */
+    items: _angular_core.InputSignal<TkDataListItem[]>;
+    /**
+     * How the pairs are arranged.
+     * @default 'list'
+     */
+    layout: _angular_core.InputSignal<TkDataListLayout>;
+    /**
+     * The text rendered in place of a value that is `null`, `undefined` or blank.
+     *
+     * Exposed as an input so it can be localised (`'N/A'`, `'Sin dato'`, …). The
+     * default is the system-wide placeholder.
+     * @default '--'
+     */
+    emptyPlaceholder: _angular_core.InputSignal<string>;
+    private readonly breakpointObserver;
+    /**
+     * Reactive viewport state across every breakpoint the design system defines.
+     *
+     * Grid mode sizes off the viewport rather than the component's own width, matching
+     * `tk-grid-container`. A consequence worth knowing: a data list inside a narrow
+     * drawer still reports the viewport's column count.
+     */
+    readonly screenChanges: _angular_core.Signal<_angular_cdk_layout.BreakpointState | undefined>;
+    /** Whether the grid layout is active. */
+    readonly isGrid: _angular_core.Signal<boolean>;
+    /**
+     * The number of grid columns for the current viewport.
+     *
+     * Mobile 1 · Tablet 2 · Small 2 · Normal 3 · Extra large 5. Falls back to a single
+     * column when the observer has not reported yet, so the first paint is mobile-first
+     * rather than over-wide.
+     */
+    readonly gridColumnCount: _angular_core.Signal<1 | 5 | 3 | 2>;
+    /**
+     * The `grid-template-columns` value bound on the `<dl>`, or `null` in list layout
+     * so the property is left off the element entirely.
+     *
+     * The track count is capped at the number of items: a data list usually holds fewer
+     * pairs than the viewport allows columns, and emitting the full count would leave
+     * empty tracks that squeeze every value into a fraction of the available width
+     * (e.g. three items over five tracks). Never drops below one, so an empty list still
+     * produces a valid value.
+     */
+    readonly gridTemplateColumns: _angular_core.Signal<string | null>;
+    /**
+     * Whether a value should render as the `--` placeholder.
+     *
+     * Applied before the type is considered, so the rule holds uniformly across every
+     * type. `0` and `false`-ish numbers are real values and are not treated as empty.
+     */
+    isEmpty(value: TkDataListItem['value']): boolean;
+    /**
+     * The effective value type, defaulting to `'text'`.
+     *
+     * A `'link'` with no `handler` has nothing to invoke, so it resolves to `'text'`: it
+     * renders as plain data instead of as a button that does nothing. That keeps a dead
+     * control out of the accessibility tree and the tab order entirely, which `disabled`
+     * would not do — and `disabled` would also claim the action merely is unavailable
+     * right now, which is not the case.
+     */
+    resolveType(item: TkDataListItem): TkDataListValueType;
+    /** The effective tag severity, defaulting to the one used in the design. */
+    resolveTagSeverity(item: TkDataListItem): TagSeverity;
+    /**
+     * The value as a string, for the child components that require one
+     * (`tk-tag.value` and `tk-button.label` are both typed `string`).
+     */
+    asText(value: TkDataListItem['value']): string;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<DataListComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<DataListComponent, "tk-data-list", never, { "items": { "alias": "items"; "required": false; "isSignal": true; }; "layout": { "alias": "layout"; "required": false; "isSignal": true; }; "emptyPlaceholder": { "alias": "emptyPlaceholder"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+export { DATA_LIST_EMPTY_PLACEHOLDER, DataListComponent };
+export type { TkDataListItem, TkDataListLayout, TkDataListValueType };

package/types/tekus-design-system-components-stat.d.ts

@@ -0,0 +1,161 @@
+import * as _angular_core from '@angular/core';
+import { Signal, InjectionToken } from '@angular/core';
+import { TagSeverity } from '@tekus/design-system/components/tag';
+
+/**
+ * The feedback intent of a stat. It drives the color of the value — and only the
+ * value: the surface, the label, the description and the progress bar are
+ * identical across every severity.
+ */
+type StatSeverity = 'secondary' | 'primary' | 'success' | 'warn' | 'danger';
+/**
+ * How a `tk-stat-group` lays its children out.
+ * - `auto`: a row that collapses to a column on small screens.
+ * - `row`: always horizontal.
+ * - `column`: always vertical.
+ */
+type StatGroupOrientation = 'auto' | 'row' | 'column';
+/** The contract a `tk-stat-group` exposes to the `tk-stat` children it projects. */
+interface StatGroupContext {
+    readonly orientation: Signal<StatGroupOrientation>;
+}
+/**
+ * Provided by `tk-stat-group`, injected optionally by `tk-stat`.
+ *
+ * This is how a stat discovers that it lives inside a group and must drop its own
+ * surface — the group owns the background, so the children must not paint their
+ * own. A stat never sets its grouped appearance itself, and a consumer never has
+ * to hand it down.
+ */
+declare const TK_STAT_GROUP: InjectionToken<StatGroupContext>;
+
+/**
+ * @component StatComponent
+ * @description
+ * Displays a single highlighted metric: a large dominant value, a small label above
+ * it, and optionally a status tag, a description and a progress bar. Used at the top
+ * of listings, summaries and dashboards to surface a key figure at a glance.
+ *
+ * This component supports:
+ * - `label` / `value`: the two required parts. The value is the dominant figure.
+ * - `severity`: the feedback intent. Colors the value — and nothing else.
+ * - `prefix` / `suffix`: small muted affixes flanking the value (e.g. `'$'`, `'/200'`).
+ * - `description`: a secondary line below the value.
+ * - `tagValue` / `tagSeverity`: a trailing tag in the header, via `tk-tag`.
+ * - `progress`: shows a `tk-progress-bar` below the content when set.
+ * - `severityLabel`: screen-reader-only text so `severity` is not color-only.
+ *
+ * There is no `grouped` input: wrapping stats in `tk-stat-group` applies the grouped
+ * appearance automatically.
+ *
+ * @usage
+ * ### Basic Usage
+ * ```html
+ * <tk-stat label="Usuarios mensuales" [value]="500" description="Audiencia estimada" />
+ * <tk-stat label="Slots" [value]="25" suffix="/200" [progress]="12" tagValue="Disponible" tagSeverity="success" />
+ * ```
+ */
+declare class StatComponent {
+    /** The small title shown above the value. */
+    label: _angular_core.InputSignal<string>;
+    /**
+     * The dominant figure. Accepts a number or an already-formatted string
+     * (`'1.2K'`, `'99,9 %'`) so the consumer keeps control of formatting and locale.
+     */
+    value: _angular_core.InputSignal<string | number>;
+    /**
+     * The feedback intent of the stat, which colors the value.
+     * @default 'secondary'
+     */
+    severity: _angular_core.InputSignal<StatSeverity>;
+    /** Small muted text rendered immediately before the value (e.g. `'$'`). */
+    prefix: _angular_core.InputSignal<string>;
+    /** Small muted text rendered immediately after the value (e.g. `'/200'`, `'/GB'`). */
+    suffix: _angular_core.InputSignal<string>;
+    /** A secondary line below the value, giving context or the origin of the figure. */
+    description: _angular_core.InputSignal<string>;
+    /** The text of the trailing header tag. The tag is only rendered when this is set. */
+    tagValue: _angular_core.InputSignal<string>;
+    /**
+     * The severity of the trailing header tag.
+     * @default 'secondary'
+     */
+    tagSeverity: _angular_core.InputSignal<TagSeverity>;
+    /**
+     * The completion percentage (0-100) shown as a progress bar below the content.
+     * Leave `undefined` to omit the bar — `0` is a valid value and renders an empty bar.
+     */
+    progress: _angular_core.InputSignal<number | undefined>;
+    /**
+     * Screen-reader-only text describing what this stat's `severity` means (e.g.
+     * `'sobre la cuota'`). Set it whenever `severity` is not `'secondary'`, so the
+     * meaning is not carried by color alone. Saying it visibly through `tagValue` or
+     * `description` is usually better, since it serves sighted users too.
+     */
+    severityLabel: _angular_core.InputSignal<string>;
+    /**
+     * The group this stat is projected into, if any. Injected optionally: a standalone
+     * stat resolves `null` and keeps its own surface.
+     */
+    private readonly group;
+    /** Whether this stat is projected inside a `tk-stat-group`. */
+    readonly grouped: boolean;
+    /** Unique DOM id linking the rendered label to the host's `aria-labelledby`. */
+    readonly labelId: string;
+    /**
+     * Whether a progress bar should be rendered. Tests for `null`/`undefined` rather
+     * than truthiness so that `progress = 0` still renders an empty bar.
+     */
+    hasProgress: _angular_core.Signal<boolean>;
+    /** Computed host class: the BEM block plus the severity and grouped modifiers. */
+    hostClass: _angular_core.Signal<string>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<StatComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<StatComponent, "tk-stat", never, { "label": { "alias": "label"; "required": true; "isSignal": true; }; "value": { "alias": "value"; "required": true; "isSignal": true; }; "severity": { "alias": "severity"; "required": false; "isSignal": true; }; "prefix": { "alias": "prefix"; "required": false; "isSignal": true; }; "suffix": { "alias": "suffix"; "required": false; "isSignal": true; }; "description": { "alias": "description"; "required": false; "isSignal": true; }; "tagValue": { "alias": "tagValue"; "required": false; "isSignal": true; }; "tagSeverity": { "alias": "tagSeverity"; "required": false; "isSignal": true; }; "progress": { "alias": "progress"; "required": false; "isSignal": true; }; "severityLabel": { "alias": "severityLabel"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * @component StatGroupComponent
+ * @description
+ * Wraps a row of related `tk-stat` into a single shared surface, inserting a
+ * separator between each pair. The group owns the background and the radius; every
+ * stat projected into it drops its own surface automatically, through the
+ * {@link TK_STAT_GROUP} token this component provides.
+ *
+ * This component supports:
+ * - `orientation`: `'auto'` (a row that collapses to a column on small screens),
+ *   `'row'` or `'column'`.
+ * - `ariaLabel`: names the group for assistive tech. Only when set does the group
+ *   expose `role="group"` — an unnamed group is noise.
+ *
+ * @usage
+ * ### Basic Usage
+ * ```html
+ * <tk-stat-group ariaLabel="Resumen de la campaña">
+ *   <tk-stat label="Usuarios mensuales" [value]="500" description="Audiencia estimada" />
+ *   <tk-stat label="Estado de la pantalla" [value]="500" severity="success" description="12 de 12 días" />
+ *   <tk-stat label="Slots" [value]="25" suffix="/200" [progress]="12" />
+ * </tk-stat-group>
+ * ```
+ */
+declare class StatGroupComponent implements StatGroupContext {
+    /**
+     * How the stats are laid out.
+     * - `'auto'`: horizontal, collapsing to a column on viewports narrower than a
+     *   vertical tablet. This is the responsive default the design calls for.
+     * - `'row'` / `'column'`: force one direction — for a group inside a narrow
+     *   sidebar on a wide screen, or one that must stay horizontal on mobile.
+     * @default 'auto'
+     */
+    orientation: _angular_core.InputSignal<StatGroupOrientation>;
+    /**
+     * The accessible name of the group. When set, the group exposes itself as
+     * `role="group"` with this label; when omitted it stays structurally invisible to
+     * assistive tech, since an unnamed group adds nothing but noise.
+     */
+    ariaLabel: _angular_core.InputSignal<string>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<StatGroupComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<StatGroupComponent, "tk-stat-group", never, { "orientation": { "alias": "orientation"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; }, {}, never, ["*"], true, never>;
+}
+
+export { StatComponent, StatGroupComponent, TK_STAT_GROUP };
+export type { StatGroupContext, StatGroupOrientation, StatSeverity };

package/types/tekus-design-system-components-table.d.ts

@@ -4,7 +4,7 @@ import { TagSeverity } from '@tekus/design-system/components/tag';
 import { SortEvent } from 'primeng/api';
 import { TkAction } from '@tekus/design-system/components/action-group';
 
-type TableColumnType = 'text' | 'tag' | 'actions' | 'selection' | 'checkbox' | 'action-group' | 'connection-status' | 'image';
+type TableColumnType = 'text' | 'tag' | 'actions' | 'selection' | 'checkbox' | 'action-group' | 'connection-status' | 'image' | 'counter';
 interface TableColumn<T = unknown> {
     field?: string;
     header: string;
@@ -32,6 +32,19 @@ interface TableColumn<T = unknown> {
     imageHeight?: string;
     imageFallback?: string;
     imageAction?: (row: T) => void;
+    counterMin?: number;
+    counterMax?: number;
+    counterStep?: number;
+    counterDisabled?: boolean | ((row: T) => boolean);
+    /** Accessible name for the cell's counter. Falls back to the column `header`. */
+    counterAriaLabel?: (row: T) => string;
+    counterDecreaseLabel?: string;
+    counterIncreaseLabel?: string;
+    /**
+     * Called after the cell has written the clamped value into `row[field]`.
+     * The hook to persist a quantity change.
+     */
+    counterChange?: (row: T, value: number) => void;
 }
 
 declare class TableComponent<T = unknown> {
@@ -215,6 +228,27 @@ declare class TableComponent<T = unknown> {
      * @param row {T} - The data row associated with the clicked image.
      */
     handleImageClick(event: Event, col: TableColumn<T>, row: T): void;
+    /**
+     * @method isCounterDisabled
+     * @description
+     * Resolves a counter column's `counterDisabled`, which may be a boolean or a
+     * per-row predicate — the same shape `getActionGroup` already accepts.
+     * @param col {TableColumn<T>} - The counter column definition.
+     * @param row {T} - The data row being rendered.
+     * @returns Whether this row's counter should be disabled.
+     */
+    isCounterDisabled(col: TableColumn<T>, row: T): boolean;
+    /**
+     * @method onCounterChange
+     * @description
+     * Writes a counter cell's new value into the row and notifies the consumer.
+     * The value arrives already clamped into the column's range by `tk-counter`.
+     * Mutating the row in place matches how the `checkbox` column type behaves.
+     * @param col {TableColumn<T>} - The counter column definition.
+     * @param row {T} - The data row being edited.
+     * @param value {number} - The new, clamped value.
+     */
+    onCounterChange(col: TableColumn<T>, row: T, value: number): void;
     /**
      * @method onImageError
      * @description