ng-hub-ui-forms 22.3.0 → 22.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ng-hub-ui-forms",
-  "version": "22.3.0",
+  "version": "22.4.0",
   "license": "MIT",
   "description": "Accessible, signal-based form fields for Angular (input, textarea, slider, select, datepicker) with automatic error display for controls, FormGroups and FormArrays. Reactive Forms today, Signal Forms ready. Part of the ng-hub-ui family.",
   "author": "Carlos Morcillo <carlos.morcillo@me.com> (https://www.carlosmorcillo.com)",

package/src/lib/styles/_tokens.scss

@@ -50,7 +50,7 @@
 	// ── Input ─────────────────────────────────────────────────────────────────
 	--hub-input-color: var(--hub-sys-text-primary, #212529);
 	--hub-input-bg: var(--hub-sys-surface-page, #fff);
-	--hub-input-font-family: var(--hub-ref-font-family-base, system-ui, sans-serif);
+	--hub-input-font-family: var(--hub-ref-font-family-base, system-ui, -apple-system, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif);
 	--hub-input-font-size: var(--hub-ref-font-size-base, 1rem);
 	--hub-input-font-weight: var(--hub-ref-font-weight-base, 400);
 	--hub-input-line-height: var(--hub-ref-line-height-base, 1.5);
@@ -122,6 +122,16 @@
 	--hub-slider-track-border-radius: var(--hub-ref-radius-pill, 50rem);
 	--hub-slider-track-bg: var(--hub-sys-border-color-default, #dee2e6);
 	--hub-slider-track-fill-bg: var(--hub-sys-color-primary, #0d6efd);
+	// Full background <image> for the filled portion of the track. The track layers
+	// this as a sized background over `--hub-slider-track-bg`, so it accepts a
+	// gradient (e.g. `linear-gradient(to right, …)`) that renders intact, clipped to
+	// the current percentage. The default wraps the solid `--hub-slider-track-fill-bg`
+	// in a flat gradient so it stays a valid, sizeable background layer while
+	// preserving the previous solid look (the colour token is kept for back-compat).
+	--hub-slider-track-fill: linear-gradient(var(--hub-slider-track-fill-bg), var(--hub-slider-track-fill-bg));
+	// Vertical room reserved above the rail for the value bubble. Set to 0 by the
+	// `--flush` modifier when the slider renders no value bubble.
+	--hub-slider-value-space: 1.75rem;
 	--hub-slider-thumb-width: 1.1rem;
 	--hub-slider-thumb-height: 1.1rem;
 	--hub-slider-thumb-border-radius: 50%;
@@ -162,7 +172,12 @@
 	--hub-select-dropdown-bg: var(--hub-sys-surface-page, #fff);
 	--hub-select-dropdown-border-color: var(--hub-sys-border-color-default, #dee2e6);
 	--hub-select-dropdown-border-radius: var(--hub-ref-radius-md, 0.375rem);
-	--hub-select-dropdown-box-shadow: var(--hub-sys-shadow, 0 0.5rem 1rem rgba(0, 0, 0, 0.12));
+	--hub-select-dropdown-box-shadow: var(--hub-sys-shadow, 0 0.5rem 1rem rgba(0, 0, 0, 0.15));
+	// Dropdown panel stacking. The vendored ng-select hard-codes `z-index: 1050` on
+	// `.ng-dropdown-panel` — one below HubModal (`--hub-sys-zindex-modal`, 1055) — so a
+	// select opened inside a modal was clipped underneath it. Sit a few layers above
+	// the modal instead.
+	--hub-select-dropdown-z-index: calc(var(--hub-sys-zindex-modal, 1055) + 5);
 
 	// ── Datepicker ──────────────────────────────────────────────────────────────
 	--hub-datepicker-icon: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Cpath fill='%236c757d' d='M3.5 0a.5.5 0 0 1 .5.5V1h8V.5a.5.5 0 0 1 1 0V1h1a2 2 0 0 1 2 2v11a2 2 0 0 1-2 2H2a2 2 0 0 1-2-2V3a2 2 0 0 1 2-2h1V.5a.5.5 0 0 1 .5-.5zM1 4v10a1 1 0 0 0 1 1h12a1 1 0 0 0 1-1V4H1z'/%3E%3C/svg%3E");
@@ -174,7 +189,7 @@
 	--hub-daterangepicker-color: var(--hub-sys-text-primary, #212529);
 	--hub-daterangepicker-border-color: var(--hub-sys-border-color-default, #dee2e6);
 	--hub-daterangepicker-border-radius: var(--hub-ref-radius-md, 0.375rem);
-	--hub-daterangepicker-box-shadow: var(--hub-sys-shadow, 0 0.5rem 1rem rgba(0, 0, 0, 0.12));
+	--hub-daterangepicker-box-shadow: var(--hub-sys-shadow, 0 0.5rem 1rem rgba(0, 0, 0, 0.15));
 	--hub-daterangepicker-padding-x: var(--hub-ref-space-3, 1rem);
 	--hub-daterangepicker-padding-y: var(--hub-ref-space-3, 1rem);
 	--hub-daterangepicker-cell-size: 2rem;
@@ -203,4 +218,20 @@
 	// Text on the selected button sits on the primary accent — derived contrast token.
 	--hub-select-button-selected-color: var(--hub-sys-color-primary-on, var(--hub-ref-color-white, #fff));
 	--hub-select-button-selected-border-color: var(--hub-sys-color-primary, #0d6efd);
+
+	// ── Segmented ───────────────────────────────────────────────────────────────
+	--hub-segmented-bg: var(--hub-sys-surface-elevated, #f8f9fa);
+	// Optional single-slot accent. Its default (transparent) contributes nothing, so the selected
+	// pill keeps the neutral white surface below; set it — or apply a `[color]` / `data-variant` —
+	// to tint the pill. A custom variant re-bases `--hub-segmented-selected-bg` (mirrors the
+	// `--hub-table-accent` model), which both the sliding indicator and the multiple-mode pill read.
+	--hub-segmented-accent: transparent;
+	--hub-segmented-selected-bg: var(--hub-sys-surface-page, #fff);
+	--hub-segmented-selected-color: var(--hub-sys-text-primary, #212529);
+	--hub-segmented-radius: var(--hub-ref-radius-md, 0.375rem);
+	--hub-segmented-gap: 0.25rem;
+	--hub-segmented-padding-x: var(--hub-ref-space-3, 1rem);
+	--hub-segmented-padding-y: var(--hub-ref-space-2, 0.5rem);
+	// Duration/easing of the single-mode sliding indicator as it moves between options.
+	--hub-segmented-indicator-transition: 0.2s ease;
 }

package/src/lib/styles/index.scss

@@ -11,3 +11,6 @@
 
 @use 'tokens';
 @use 'field';
+
+// One-call theming mixins (opt-in; forwarded so consumers can `@use` them from the package root).
+@forward 'mixins/segmented-theme';

package/src/lib/styles/mixins/_segmented-theme.scss

@@ -0,0 +1,66 @@
+// ─────────────────────────────────────────────────────────────────────────
+// hub-segmented-theme — one-call theming for `<hub-segmented>`
+// ─────────────────────────────────────────────────────────────────────────
+//
+// Override any of the `--hub-segmented-*` design tokens in a single include.
+// Every parameter is OPTIONAL and defaults to `null`: only the parameters you
+// pass are emitted, so the rest keep the component's defaults. Token-based and
+// self-contained (no Bootstrap dependencies).
+//
+// Apply it inside any selector that wraps the control — the host element, a
+// container, a route, or `:root` for a global theme.
+//
+// @example — a compact, brand-accented bar with a rounded frame:
+//
+//   @use 'ng-hub-ui-forms/styles/mixins/segmented-theme' as *;
+//
+//   .view-switch {
+//     @include hub-segmented-theme(
+//       $selected-bg: var(--hub-sys-color-brand),
+//       $selected-color: var(--hub-sys-color-brand-on, #fff),
+//       $radius: 0.75rem,
+//       $padding-y: 0.375rem
+//     );
+//   }
+//
+// scss-docs-start hub-segmented-theme
+@mixin hub-segmented-theme(
+	// ── Colour ──
+	$bg: null,                // the bar (track) surface
+	$selected-bg: null,       // selected pill / sliding-indicator fill
+	$selected-color: null,    // selected option text colour
+	// ── Shape ──
+	$radius: null,            // bar corner radius (pill radius derives from it)
+	// ── Density / spacing ──
+	$gap: null,               // padding around, and gutter between, the options
+	$padding-x: null,         // option horizontal padding
+	$padding-y: null          // option vertical padding
+) {
+	// Colour
+	@if $bg != null {
+		--hub-segmented-bg: #{$bg};
+	}
+	@if $selected-bg != null {
+		--hub-segmented-selected-bg: #{$selected-bg};
+	}
+	@if $selected-color != null {
+		--hub-segmented-selected-color: #{$selected-color};
+	}
+
+	// Shape
+	@if $radius != null {
+		--hub-segmented-radius: #{$radius};
+	}
+
+	// Density / spacing
+	@if $gap != null {
+		--hub-segmented-gap: #{$gap};
+	}
+	@if $padding-x != null {
+		--hub-segmented-padding-x: #{$padding-x};
+	}
+	@if $padding-y != null {
+		--hub-segmented-padding-y: #{$padding-y};
+	}
+}
+// scss-docs-end hub-segmented-theme

package/types/ng-hub-ui-forms.d.ts

@@ -771,6 +771,108 @@ declare class HubSliderComponent extends HubFieldControl {
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<HubSliderComponent, "hub-slider", never, { "label": { "alias": "label"; "required": false; "isSignal": true; }; "labelType": { "alias": "labelType"; "required": false; "isSignal": true; }; "range": { "alias": "range"; "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; }; "showValue": { "alias": "showValue"; "required": false; "isSignal": true; }; "formText": { "alias": "formText"; "required": false; "isSignal": true; }; "formTextType": { "alias": "formTextType"; "required": false; "isSignal": true; }; "classlist": { "alias": "classlist"; "required": false; "isSignal": true; }; }, { "valueChange": "valueChange"; }, never, never, true, never>;
 }
 
+/** A single choice rendered by {@link HubSegmentedComponent}. */
+interface HubSegmentedOption {
+    /** Value written to the form control when this option is selected. */
+    value: unknown;
+    /** Visible label for the segment. */
+    label: string;
+    /** When `true`, the segment is rendered but cannot be selected. */
+    disabled?: boolean;
+}
+/** Density of the segmented control. */
+type HubSegmentedSize = 'sm' | 'md' | 'lg';
+/**
+ * Segmented button bar (`hub-segmented`): a compact group of 2..n options rendered as an inline
+ * (or vertical) segmented control. A full `ng-hub-ui-forms` field — it extends
+ * {@link HubFieldControl}, so it binds with `formControlName` / `ngModel` and shares the label,
+ * helper text and validation chrome with every other field.
+ *
+ * Two selection modes:
+ * - **single** (default): exclusive choice following the WAI-ARIA radiogroup pattern
+ *   (`role="radiogroup"` wrapping `role="radio"` buttons). Arrow keys move focus **and** select.
+ *   The value is the scalar of the chosen option.
+ * - **multiple** (`[multiple]="true"`): a toggle group (`role="group"` wrapping
+ *   `aria-pressed` buttons). Clicking toggles membership; arrow keys only move focus.
+ *   The value is an array of the selected option values.
+ *
+ * ```html
+ * <hub-segmented
+ *   formControlName="view"
+ *   [options]="[{ value: 'list', label: 'List' }, { value: 'grid', label: 'Grid' }]"
+ * />
+ *
+ * <hub-segmented formControlName="tags" [multiple]="true" [vertical]="true" [options]="tags" />
+ * ```
+ */
+declare class HubSegmentedComponent extends HubFieldControl {
+    #private;
+    protected readonly _labelTypes: typeof HubLabelTypes;
+    /** The selectable options, in render order. */
+    readonly options: _angular_core.InputSignal<HubSegmentedOption[]>;
+    /** Visual density. */
+    readonly size: _angular_core.InputSignal<HubSegmentedSize>;
+    /**
+     * Semantic accent for the selected pill. Drives `data-variant` on the bar, which re-bases the
+     * `--hub-segmented-selected-*` tokens. Built-in values map to the design-system palette
+     * (`primary`, `secondary`, `success`, `danger`, `warning`, `info`, `neutral`), but the set is
+     * OPEN — any custom string works as long as the consumer supplies the matching
+     * `--hub-segmented-selected-bg` / `--hub-segmented-selected-color` (or `--hub-segmented-accent`)
+     * for that `data-variant`. Empty string (default) keeps the neutral white-pill look.
+     */
+    readonly color: _angular_core.InputSignal<string>;
+    /** Label text. */
+    readonly label: _angular_core.InputSignal<string>;
+    /** Label display type (`stacked`, `horizontal`). */
+    readonly labelType: _angular_core.InputSignal<HubLabelType>;
+    /** Helper text shown below the control. */
+    readonly formText: _angular_core.InputSignal<string>;
+    /** When `true`, options toggle independently and the value is an array. */
+    readonly multiple: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** When `true`, the segments stack vertically instead of sitting in a row. */
+    readonly vertical: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Currently selected value — a scalar in single mode, an array in multiple mode. */
+    readonly value: _angular_core.ModelSignal<unknown>;
+    /** The rendered option buttons, used to move focus during keyboard navigation. */
+    private readonly _buttons;
+    /** The segmented bar element — the positioning context for the sliding indicator. */
+    private readonly _bar;
+    private readonly _destroyRef;
+    private readonly _isBrowser;
+    constructor();
+    /**
+     * Index of the option that owns the group's tab stop (roving tabindex): the first selected
+     * option, or the first enabled option when nothing is selected yet.
+     */
+    readonly rovingIndex: _angular_core.Signal<number>;
+    /** Whether the given option is currently selected (mode-aware). */
+    isSelected(option: HubSegmentedOption): boolean;
+    /**
+     * Selects (single) or toggles (multiple) an option and notifies the form. No-op when the
+     * control or the option is disabled.
+     */
+    select(option: HubSegmentedOption): void;
+    /**
+     * Keyboard navigation. In single mode the arrow keys move to (and select) the next / previous
+     * enabled option (radiogroup pattern); in multiple mode they only move focus and selection is
+     * left to the native button click (`Space` / `Enter`). `Home` / `End` jump to the first / last
+     * enabled option.
+     */
+    onKeydown(event: KeyboardEvent): void;
+    /** Writes an incoming value from the form model (coerces to an array in multiple mode). */
+    writeValue(value: unknown): void;
+    /**
+     * Measures the selected option (single mode) and writes its position and size onto the bar as
+     * `--hub-segmented-indicator-{x,y,width,height}` px custom properties, which the sliding
+     * indicator reads. Collapses the indicator (width/height 0) in multiple mode or when nothing is
+     * selected. Browser-only — invoked from `afterRenderEffect` / `afterNextRender` / the
+     * `ResizeObserver`, so the DOM is always up to date when it runs.
+     */
+    private updateIndicator;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<HubSegmentedComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<HubSegmentedComponent, "hub-segmented", never, { "options": { "alias": "options"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "color": { "alias": "color"; "required": false; "isSignal": true; }; "label": { "alias": "label"; "required": false; "isSignal": true; }; "labelType": { "alias": "labelType"; "required": false; "isSignal": true; }; "formText": { "alias": "formText"; "required": false; "isSignal": true; }; "multiple": { "alias": "multiple"; "required": false; "isSignal": true; }; "vertical": { "alias": "vertical"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": false; "isSignal": true; }; }, { "value": "valueChange"; }, never, never, true, never>;
+}
+
 /**
  * Groups related fields under a `<fieldset>`/`<legend>` and **automatically displays the
  * group-level (cross-field) validation errors** of the bound `FormGroup`/`FormArray`.
@@ -899,9 +1001,22 @@ declare class HubSelectComponent extends HubFieldControl {
     protected readonly _headerTpl: _angular_core.Signal<TemplateRef<any> | undefined>;
     protected readonly _footerTpl: _angular_core.Signal<TemplateRef<any> | undefined>;
     protected readonly _notFoundTpl: _angular_core.Signal<TemplateRef<any> | undefined>;
-    /** Rendering format (`dropdown`, `buttons`, `checkbox`, `radio`). */
+    /**
+     * Rendering format (`dropdown`, `buttons`, `checkbox`, `radio`).
+     *
+     * @deprecated The non-dropdown values (`buttons` / `checkbox` / `radio`) are deprecated and
+     * will be removed in the next major — use `<hub-segmented>` instead, which is the dedicated,
+     * lightweight control for inline options as segments/buttons (single **and** multiple selection,
+     * horizontal **and** vertical, with label / helper text). Migration: `format="buttons"` →
+     * `<hub-segmented>`; `format="checkbox"` → `<hub-segmented [multiple]="true">`; `format="radio"`
+     * → `<hub-segmented [vertical]="true">`. Only `dropdown` (the default) will remain on `hub-select`.
+     */
     readonly format: _angular_core.InputSignal<HubSelectFormat>;
-    /** Lay out the `buttons`/`checkbox`/`radio` options vertically. */
+    /**
+     * Lay out the `buttons`/`checkbox`/`radio` options vertically.
+     *
+     * @deprecated Tied to the deprecated non-dropdown `format` values — use `<hub-segmented [vertical]="true">` instead.
+     */
     readonly vertical: _angular_core.InputSignalWithTransform<boolean, unknown>;
     /** Items to choose from. */
     readonly items: _angular_core.InputSignal<any[]>;
@@ -1594,5 +1709,5 @@ interface HubFormControlAdapter {
  */
 declare const hubFormControlAdapter: HubFormControlAdapter;
 
-export { FormTextTypes, HUB_FORMS_CONFIG, HubAutoresizeDirective, HubDatepickerComponent, HubFieldControl, HubFieldsetComponent, HubFormComponent, HubFormControl, HubFormTextDirective, HubGroupControl, HubInputComponent, HubInputFormats, HubInputPrefixDirective, HubInputSuffixDirective, HubInvertColorPipe, HubJoinButLastPipe, HubLabelTypes, HubLegendComponent, HubLegendDirective, HubMapPipe, HubOtpInputComponent, HubSafeUrlPipe, HubSelectComponent, HubSelectFormats, HubSliderComponent, HubSnakeUpperPipe, HubTextareaComponent, HubUcfirstPipe, HubValidationErrorDirective, NgClearButtonTemplateDirective, NgFooterTemplateDirective, NgHeaderTemplateDirective, NgLabelTemplateDirective, NgLoadingSpinnerTemplateDirective, NgLoadingTextTemplateDirective, NgMultiLabelTemplateDirective, NgNotFoundTemplateDirective, NgOptgroupTemplateDirective, NgOptionComponent, NgOptionTemplateDirective, NgSelectConfig, NgTagTemplateDirective, NgTypeToSearchTemplateDirective, applyMask, areEqual, camelToSnakeUpper, controlHasMinOrMaxValidator, defaultHubDatepickerConfig, defaultHubDatepickerLabels, defaultHubFormsConfig, defaultInvalidFeedback, get, getActiveElement, getMinOrMaxValueFromValidator, hubAreEqual, hubFormControlAdapter, isDefined, isMaskActive, isString, joinButLast, provideHubForms, runInZone, uuid };
-export type { FormTextType, HubDateRange, HubDateValue, HubDatepickerConfig, HubDatepickerLabels, HubDatepickerMode, HubFormControlAdapter, HubFormControlConfig, HubFormControlHandle, HubFormControlOption, HubFormsConfig, HubGroupErrorTrigger, HubInputFormat, HubLabelType, HubMaskResult, HubOtpMode, HubSelectFormat, HubSliderValue };
+export { FormTextTypes, HUB_FORMS_CONFIG, HubAutoresizeDirective, HubDatepickerComponent, HubFieldControl, HubFieldsetComponent, HubFormComponent, HubFormControl, HubFormTextDirective, HubGroupControl, HubInputComponent, HubInputFormats, HubInputPrefixDirective, HubInputSuffixDirective, HubInvertColorPipe, HubJoinButLastPipe, HubLabelTypes, HubLegendComponent, HubLegendDirective, HubMapPipe, HubOtpInputComponent, HubSafeUrlPipe, HubSegmentedComponent, HubSelectComponent, HubSelectFormats, HubSliderComponent, HubSnakeUpperPipe, HubTextareaComponent, HubUcfirstPipe, HubValidationErrorDirective, NgClearButtonTemplateDirective, NgFooterTemplateDirective, NgHeaderTemplateDirective, NgLabelTemplateDirective, NgLoadingSpinnerTemplateDirective, NgLoadingTextTemplateDirective, NgMultiLabelTemplateDirective, NgNotFoundTemplateDirective, NgOptgroupTemplateDirective, NgOptionComponent, NgOptionTemplateDirective, NgSelectConfig, NgTagTemplateDirective, NgTypeToSearchTemplateDirective, applyMask, areEqual, camelToSnakeUpper, controlHasMinOrMaxValidator, defaultHubDatepickerConfig, defaultHubDatepickerLabels, defaultHubFormsConfig, defaultInvalidFeedback, get, getActiveElement, getMinOrMaxValueFromValidator, hubAreEqual, hubFormControlAdapter, isDefined, isMaskActive, isString, joinButLast, provideHubForms, runInZone, uuid };
+export type { FormTextType, HubDateRange, HubDateValue, HubDatepickerConfig, HubDatepickerLabels, HubDatepickerMode, HubFormControlAdapter, HubFormControlConfig, HubFormControlHandle, HubFormControlOption, HubFormsConfig, HubGroupErrorTrigger, HubInputFormat, HubLabelType, HubMaskResult, HubOtpMode, HubSegmentedOption, HubSegmentedSize, HubSelectFormat, HubSliderValue };