@tekus/design-system 5.39.0 → 5.40.0

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

@@ -0,0 +1,286 @@
+import * as _angular_core from '@angular/core';
+import { OnInit } from '@angular/core';
+import { ControlValueAccessor, NgControl, FormControl } from '@angular/forms';
+
+/**
+ * @component CounterComponent
+ * @description
+ * Compact control for selecting an integer value within a bounded range using
+ * icon-only decrement and increment buttons, with an editable value in the center.
+ * It has its own distinct visual identity so it reads as a standalone element rather
+ * than blending into the standard input family.
+ *
+ * This component supports:
+ * - `value`: the current integer. Never null; always rendered clamped into `[min, max]`.
+ * - `min` / `max`: the inclusive bounds. Buttons **disable** at a limit, never hide,
+ *   and the value never wraps around.
+ * - `step`: the amount added or subtracted per action.
+ * - `disabled` / `readonly`: `disabled` blocks interaction and applies a distinct
+ *   treatment to the value; `readonly` looks normal but cannot change.
+ * - Holding a button auto-repeats the step.
+ *
+ * It implements `ControlValueAccessor`, so it works with `[(ngModel)]` and reactive forms.
+ *
+ * @usage
+ * ### Basic Usage
+ * ```html
+ * <tk-counter [(ngModel)]="quantity" />
+ * <tk-counter [min]="1" [max]="10" [step]="2" [(value)]="servings" />
+ * <tk-counter [control]="quantityControl" (valueChange)="onQuantityChange($event)" />
+ * ```
+ */
+declare class CounterComponent implements ControlValueAccessor, OnInit {
+    readonly ngControl: NgControl | null;
+    private readonly destroyRef;
+    constructor();
+    /**
+     * @property {ModelSignal<number>} value
+     * @description
+     * Current integer value. Never null; always rendered clamped into `[min, max]`.
+     * Supports two-way binding via `[(value)]` and emits `(valueChange)` after clamping.
+     *
+     * @default `0`
+     */
+    value: _angular_core.ModelSignal<number>;
+    /**
+     * @property {InputSignal<number>} min
+     * @description
+     * Lower bound, inclusive. The decrement button disables at this value.
+     *
+     * @default `0`
+     */
+    min: _angular_core.InputSignal<number>;
+    /**
+     * @property {InputSignal<number>} max
+     * @description
+     * Upper bound, inclusive. The increment button disables at this value.
+     *
+     * @default `99`
+     */
+    max: _angular_core.InputSignal<number>;
+    /**
+     * @property {InputSignal<number>} step
+     * @description
+     * Amount added or subtracted per action. `PageUp` / `PageDown` apply ten times this.
+     *
+     * @default `1`
+     */
+    step: _angular_core.InputSignal<number>;
+    /**
+     * @property {ModelSignal<boolean>} disabled
+     * @description
+     * Disables all interaction and applies the distinct disabled treatment to the value.
+     *
+     * @default `false`
+     */
+    disabled: _angular_core.ModelSignal<boolean>;
+    /**
+     * @property {InputSignal<boolean>} readonly
+     * @description
+     * The value is shown but cannot change. Visually normal, unlike `disabled`.
+     *
+     * @default `false`
+     */
+    readonly: _angular_core.InputSignal<boolean>;
+    /**
+     * @property {InputSignal<FormControl | undefined>} control
+     * @description
+     * External FormControl used to read/set the value. Optional: when omitted the
+     * counter keeps its value in the `value` model alone and creates no control.
+     * Not needed when using `formControlName` or `[(ngModel)]`.
+     *
+     * @default `undefined`
+     */
+    control: _angular_core.InputSignal<FormControl<any> | undefined>;
+    /**
+     * @property {InputSignal<string>} decreaseLabel
+     * @description
+     * Accessible label for the decrement button, which carries no visible text.
+     *
+     * @default `'Decrease'`
+     */
+    decreaseLabel: _angular_core.InputSignal<string>;
+    /**
+     * @property {InputSignal<string>} increaseLabel
+     * @description
+     * Accessible label for the increment button, which carries no visible text.
+     *
+     * @default `'Increase'`
+     */
+    increaseLabel: _angular_core.InputSignal<string>;
+    /**
+     * @property {InputSignal<string>} ariaLabel
+     * @description
+     * Accessible name for the value field. The counter renders no visible label, so
+     * either this or `ariaLabelledby` must be set unless surrounding text already
+     * names the control — otherwise the spinbutton is announced unnamed.
+     */
+    ariaLabel: _angular_core.InputSignal<string>;
+    /**
+     * @property {InputSignal<string>} ariaLabelledby
+     * @description
+     * Id of an existing element that names the value field. Use instead of
+     * `ariaLabel` when a visible label already exists elsewhere in the view.
+     */
+    ariaLabelledby: _angular_core.InputSignal<string>;
+    /** The value field, used to resync its text after the model clamps a typed entry. */
+    private readonly valueInput;
+    /**
+     * The effective upper bound. Guards against a `max` lower than `min` so the range
+     * is never inverted and `clamp` stays well defined.
+     */
+    readonly safeMax: _angular_core.Signal<number>;
+    /**
+     * The effective step. Guards against `0`, a negative, or a non-finite `step`, any
+     * of which would make stepping a no-op — and would let a held button repeat forever
+     * without ever reaching a limit.
+     */
+    readonly effectiveStep: _angular_core.Signal<number>;
+    /** The amount applied by `PageUp` / `PageDown`: ten times `step`. */
+    readonly pageStep: _angular_core.Signal<number>;
+    /**
+     * Character budget for the value field: the widest number the range can produce,
+     * never fewer than `MIN_VALUE_WIDTH_CH`.
+     *
+     * Derived from the **range**, not from the current value, so that every counter
+     * sharing a range renders exactly the same width. That is what keeps the buttons
+     * aligned down a column when one row shows `1` and the next shows `44` — sizing to
+     * the current value instead would make each row a different width.
+     */
+    readonly valueWidthCh: _angular_core.Signal<number>;
+    /**
+     * The rendered value: always a valid integer inside `[min, safeMax]`, even when a
+     * parent binds something out of range. Deliberately a `computed` rather than an
+     * `effect` writing back into `value`, which would fight a two-way `[(value)]`
+     * binding; the first interaction commits the clamped number and converges the two.
+     */
+    readonly displayValue: _angular_core.Signal<number>;
+    /** Whether the value sits at the lower bound, which disables the decrement button. */
+    readonly atMin: _angular_core.Signal<boolean>;
+    /** Whether the value sits at the upper bound, which disables the increment button. */
+    readonly atMax: _angular_core.Signal<boolean>;
+    /** Computed host class: the BEM block plus the disabled and readonly modifiers. */
+    readonly hostClass: _angular_core.Signal<string>;
+    get effectiveControl(): FormControl | null;
+    onChange: (value: number) => void;
+    onTouched: () => void;
+    private isWriting;
+    private holdTimeout;
+    private holdInterval;
+    ngOnInit(): void;
+    /**
+     * @method writeValue
+     * @description
+     * Writes a new value to the element, clamped into range.
+     * @param value The new value.
+     */
+    writeValue(value: number | null): void;
+    /**
+     * @method registerOnChange
+     * @description
+     * Registers a callback called when the value changes in the UI.
+     * @param fn The callback function.
+     */
+    registerOnChange(fn: (value: number) => void): void;
+    /**
+     * @method registerOnTouched
+     * @description
+     * Registers a callback called by the forms API to update the form model on blur.
+     * @param fn The callback function.
+     */
+    registerOnTouched(fn: () => void): void;
+    /**
+     * @method setDisabledState
+     * @description
+     * Called by the forms API when the control status changes to or from 'DISABLED'.
+     * @param isDisabled The disabled status to set on the element.
+     */
+    setDisabledState(isDisabled: boolean): void;
+    /**
+     * @method stepBy
+     * @description
+     * Moves the value by `step` in the given direction, clamped into range.
+     * @param direction `1` to increment, `-1` to decrement.
+     */
+    stepBy(direction: 1 | -1): void;
+    /**
+     * @method startHold
+     * @description
+     * Steps once immediately, then begins auto-repeating after `HOLD_DELAY_MS`.
+     * No-ops when the counter cannot change or is already at that limit.
+     * @param direction `1` to increment, `-1` to decrement.
+     */
+    startHold(direction: 1 | -1): void;
+    /**
+     * @method stopHold
+     * @description
+     * Cancels any pending or running auto-repeat. Safe to call when none is active.
+     */
+    stopHold(): void;
+    /**
+     * @method onButtonKeydown
+     * @description
+     * Handles keyboard activation of a stepper button. `Enter` and `Space` are handled
+     * here — and their default prevented — so the button steps exactly once per press
+     * and relies on native key auto-repeat while held.
+     * @param event The keyboard event.
+     * @param direction `1` to increment, `-1` to decrement.
+     */
+    onButtonKeydown(event: KeyboardEvent, direction: 1 | -1): void;
+    /**
+     * @method onValueKeydown
+     * @description
+     * Handles the spinbutton keyboard contract: arrows step by `step`, Home / End jump
+     * to the bounds, PageUp / PageDown apply a larger step, and Enter commits the
+     * currently typed text.
+     * @param event The keyboard event.
+     */
+    onValueKeydown(event: KeyboardEvent): void;
+    /**
+     * @method onInput
+     * @description
+     * Rejects non-numeric characters as they are typed, without clamping — clamping
+     * mid-keystroke would fight the user on the way to a valid number (typing `1`
+     * toward `12` when `min` is `5`). The value is committed on blur or Enter.
+     * @param event The input event.
+     */
+    onInput(event: Event): void;
+    /**
+     * @method onValueBlur
+     * @description
+     * Commits the typed text, marks the control touched, and resyncs the field so its
+     * text always matches the clamped value.
+     */
+    onValueBlur(): void;
+    /**
+     * Keeps digits only, plus a single leading `-` when the range includes negatives.
+     * Applied to whatever lands in the field, so it also covers paste and drop.
+     */
+    private sanitize;
+    /** Whether the counter currently accepts changes. */
+    private canInteract;
+    /** Whether stepping in `direction` would move past an already-reached bound. */
+    private isAtLimit;
+    /**
+     * Rounds and clamps an arbitrary value into `[min, safeMax]`. Non-finite input
+     * (an empty or unparseable field) falls back to `min`, so the value is never empty.
+     */
+    private clamp;
+    /**
+     * The single write path: clamps, updates the model, notifies the forms API, and
+     * emits `(valueChange)` — so clamping and emission happen in exactly one place.
+     */
+    private commit;
+    /** Parses the field's current text, commits it, and resyncs the displayed text. */
+    private commitTypedValue;
+    /**
+     * Rewrites the field's text from `displayValue`. Required because the `[value]`
+     * binding will not update the DOM when the model is unchanged — typing `150` with
+     * `max` `99` while the value is already `99` leaves stale text behind otherwise.
+     */
+    private syncInputText;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<CounterComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<CounterComponent, "tk-counter", never, { "value": { "alias": "value"; "required": false; "isSignal": true; }; "min": { "alias": "min"; "required": false; "isSignal": true; }; "max": { "alias": "max"; "required": false; "isSignal": true; }; "step": { "alias": "step"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "readonly": { "alias": "readonly"; "required": false; "isSignal": true; }; "control": { "alias": "control"; "required": false; "isSignal": true; }; "decreaseLabel": { "alias": "decreaseLabel"; "required": false; "isSignal": true; }; "increaseLabel": { "alias": "increaseLabel"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "ariaLabelledby": { "alias": "ariaLabelledby"; "required": false; "isSignal": true; }; }, { "value": "valueChange"; "disabled": "disabledChange"; }, never, never, true, never>;
+}
+
+export { CounterComponent };

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