@neuravision/ng-construct 0.5.0 → 0.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neuravision/ng-construct",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Angular components for the Construct Design System",
   "keywords": [
     "angular",

package/types/neuravision-ng-construct.d.ts

@@ -412,6 +412,12 @@ declare class AfAppShellV2Component {
 
 type AfAvatarSize = 'sm' | 'md' | 'lg' | 'xl';
 type AfAvatarStatus = 'online' | 'offline' | 'busy' | 'away';
+/**
+ * Number of distinct colors in the seeded avatar palette. Must match the
+ * `[data-seed-color="N"]` selectors shipped by `@neuravision/construct`
+ * (see `components/avatar.css`). Bump together when Construct adds slots.
+ */
+declare const AVATAR_SEED_PALETTE_SIZE = 8;
 /**
  * Avatar component displaying a user image with fallback to initials.
  *
@@ -419,9 +425,16 @@ type AfAvatarStatus = 'online' | 'offline' | 'busy' | 'away';
  * fails to load or no `src` is given, initials derived from `name` are
  * shown instead.
  *
+ * Set `colorSeed` to give each user a stable, deterministic background
+ * color picked from the Construct DS palette — useful in lists where the
+ * eye should recognize repeat individuals at a glance. The seed is hashed
+ * locally and bound to `data-seed-color`; an empty seed leaves the
+ * attribute off and the avatar keeps the default background.
+ *
  * @example
  * <af-avatar src="/photo.jpg" name="Jane Doe" alt="Jane Doe" size="lg" />
  * <af-avatar name="John Smith" status="online" />
+ * <af-avatar name="Jane Doe" colorSeed="user-uuid-7b3e2a4d" />
  */
 declare class AfAvatarComponent {
     /** Image URL. Falls back to initials when missing or on load error. */
@@ -434,6 +447,12 @@ declare class AfAvatarComponent {
     alt: _angular_core.InputSignal<string>;
     /** Online status indicator. */
     status: _angular_core.InputSignal<AfAvatarStatus | undefined>;
+    /**
+     * Stable identifier (e.g. userUUID, email, username) hashed into a
+     * deterministic palette index. The same seed always produces the same
+     * color. Leave empty to keep the default avatar background.
+     */
+    colorSeed: _angular_core.InputSignal<string>;
     /** Tracks whether the image failed to load. */
     imageError: _angular_core.WritableSignal<boolean>;
     /** Whether to render the `<img>` element. */
@@ -442,11 +461,23 @@ declare class AfAvatarComponent {
     initials: _angular_core.Signal<string>;
     /** Accessible label for the avatar. */
     ariaLabel: _angular_core.Signal<string>;
+    /**
+     * Palette index in `[1, AVATAR_SEED_PALETTE_SIZE]` derived from `colorSeed`,
+     * or `null` when no seed is set. Returning `null` causes Angular to omit
+     * the `data-seed-color` attribute, preserving the unseeded default.
+     */
+    seedColorIndex: _angular_core.Signal<number | null>;
     avatarClasses: _angular_core.Signal<string>;
     /** Handles image load failure by switching to initials fallback. */
     onImageError(): void;
+    /**
+     * Dependency-free 32-bit string hash (djb2-style). Pure and stable across
+     * runs and environments — same input always yields the same non-negative
+     * integer.
+     */
+    private hashSeed;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<AfAvatarComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<AfAvatarComponent, "af-avatar", never, { "src": { "alias": "src"; "required": false; "isSignal": true; }; "name": { "alias": "name"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "alt": { "alias": "alt"; "required": false; "isSignal": true; }; "status": { "alias": "status"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<AfAvatarComponent, "af-avatar", never, { "src": { "alias": "src"; "required": false; "isSignal": true; }; "name": { "alias": "name"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "alt": { "alias": "alt"; "required": false; "isSignal": true; }; "status": { "alias": "status"; "required": false; "isSignal": true; }; "colorSeed": { "alias": "colorSeed"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
 type AfButtonVariant = 'primary' | 'secondary' | 'ghost' | 'outline' | 'danger' | 'accent' | 'link';
@@ -690,54 +721,171 @@ interface AfSelectOption {
     disabled?: boolean;
 }
 /**
- * Select dropdown component with form control support
+ * Native select dropdown component with form control support.
+ * Wraps a native `<select>` element with design system styling,
+ * accessible labelling, and Angular forms integration.
  *
- * @example
+ * For a custom dropdown with keyboard-navigated listbox, see `af-select-menu`.
+ *
+ * @example Basic usage with ngModel
  * <af-select
  *   label="Role"
  *   [options]="roleOptions"
  *   [(ngModel)]="selectedRole"
  *   hint="Choose your primary role"
- * ></af-select>
+ * />
+ *
+ * @example Reactive forms with error state
+ * <af-select
+ *   label="Country"
+ *   [options]="countries"
+ *   [formControl]="countryControl"
+ *   [error]="countryControl.hasError('required') ? 'Required field' : ''"
+ * />
+ *
+ * @accessibility
+ * - Uses a native `<select>` element for built-in browser accessibility.
+ * - `aria-invalid` is set when an error message is provided.
+ * - `aria-describedby` links to hint or error text.
+ * - Falls back to `aria-label` via {@link AF_SELECT_I18N} when no `label` input is given.
+ * - Screen-reader announcements via {@link AriaLiveAnnouncer} on selection change.
+ * - All user-facing strings are configurable via {@link AF_SELECT_I18N} for i18n.
  */
 declare class AfSelectComponent implements ControlValueAccessor {
     private static nextId;
-    /** Select label */
+    protected readonly i18n: _neuravision_ng_construct.AfSelectI18n;
+    private readonly announcer;
+    /** Label shown above the select. */
     label: _angular_core.InputSignal<string>;
-    /** Placeholder option */
+    /** Placeholder option shown when no value is selected. */
     placeholder: _angular_core.InputSignal<string>;
-    /** Options array */
+    /** Available options. */
     options: _angular_core.InputSignal<AfSelectOption[]>;
-    /** Hint text shown below select */
+    /** Hint text shown below the select. */
     hint: _angular_core.InputSignal<string>;
-    /** Error message */
+    /** Error message — shows error state when non-empty. */
     error: _angular_core.InputSignal<string>;
-    /** Whether select is required */
+    /** Whether the field is required. */
     required: _angular_core.InputSignal<boolean>;
-    /** Whether select is disabled */
+    /** Whether the select is disabled. */
     disabled: _angular_core.ModelSignal<boolean>;
-    /** Value comparison function (for object values) */
+    /** Size variant. */
+    size: _angular_core.InputSignal<"sm" | "md" | "lg">;
+    /** Value comparison function for object values. */
     compareWith: _angular_core.InputSignal<(a: unknown, b: unknown) => boolean>;
-    /** Unique select ID */
+    /** Unique select ID. */
     selectId: _angular_core.InputSignal<string>;
-    value: unknown;
-    onChangeCallback: (value: unknown) => void;
+    /** Emits when the user changes the selected value. */
+    valueChange: _angular_core.OutputEmitterRef<unknown>;
+    private readonly value;
+    private onChange;
     onTouched: () => void;
+    labelId: _angular_core.Signal<string>;
     hintId: _angular_core.Signal<string>;
     errorId: _angular_core.Signal<string>;
-    getAriaDescribedBy(): string | null;
-    get isPlaceholderSelected(): boolean;
-    private hasMatchingOption;
+    selectClasses: _angular_core.Signal<string>;
+    ariaDescribedBy: _angular_core.Signal<string | null>;
+    isPlaceholderSelected: _angular_core.Signal<boolean>;
     isOptionSelected(option: AfSelectOption): boolean;
-    onChange(event: Event): void;
-    /** ControlValueAccessor implementation */
+    handleChange(event: Event): void;
+    /** @docs-private */
     writeValue(value: unknown): void;
+    /** @docs-private */
     registerOnChange(fn: (value: unknown) => void): void;
+    /** @docs-private */
     registerOnTouched(fn: () => void): void;
+    /** @docs-private */
     setDisabledState(isDisabled: boolean): void;
+    private hasMatchingOption;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<AfSelectComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<AfSelectComponent, "af-select", never, { "label": { "alias": "label"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "options": { "alias": "options"; "required": false; "isSignal": true; }; "hint": { "alias": "hint"; "required": false; "isSignal": true; }; "error": { "alias": "error"; "required": false; "isSignal": true; }; "required": { "alias": "required"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "compareWith": { "alias": "compareWith"; "required": false; "isSignal": true; }; "selectId": { "alias": "selectId"; "required": false; "isSignal": true; }; }, { "disabled": "disabledChange"; }, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<AfSelectComponent, "af-select", never, { "label": { "alias": "label"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "options": { "alias": "options"; "required": false; "isSignal": true; }; "hint": { "alias": "hint"; "required": false; "isSignal": true; }; "error": { "alias": "error"; "required": false; "isSignal": true; }; "required": { "alias": "required"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "compareWith": { "alias": "compareWith"; "required": false; "isSignal": true; }; "selectId": { "alias": "selectId"; "required": false; "isSignal": true; }; }, { "disabled": "disabledChange"; "valueChange": "valueChange"; }, never, never, true, never>;
+}
+
+/**
+ * Test harness for AfSelectComponent.
+ *
+ * Provides a semantic API for interacting with the native select in tests,
+ * abstracting DOM details behind readable method names.
+ *
+ * @example
+ * const harness = new AfSelectHarness(fixture.nativeElement);
+ * expect(harness.isDisabled()).toBe(false);
+ * harness.selectByIndex(1);
+ * expect(harness.getValue()).toBe('Banana');
+ */
+declare class AfSelectHarness {
+    private readonly hostEl;
+    constructor(container: HTMLElement);
+    /** Returns the native `<select>` element. */
+    getSelectElement(): HTMLSelectElement;
+    /** Returns the current display value of the select. */
+    getValue(): string;
+    /** Returns the current selected index. */
+    getSelectedIndex(): number;
+    /** Selects an option by index and dispatches a change event. */
+    selectByIndex(index: number): void;
+    /** Returns the trimmed label text, or null if no label. */
+    getLabel(): string | null;
+    /** Returns the trimmed hint text, or null if no hint. */
+    getHint(): string | null;
+    /** Returns the trimmed error text, or null if no error. */
+    getError(): string | null;
+    /** Returns whether the select is disabled. */
+    isDisabled(): boolean;
+    /** Returns whether the select is required. */
+    isRequired(): boolean;
+    /** Returns whether `aria-invalid="true"` is set. */
+    isInvalid(): boolean;
+    /** Returns the `aria-describedby` attribute value. */
+    getAriaDescribedBy(): string | null;
+    /** Returns the `aria-label` attribute value. */
+    getAriaLabel(): string | null;
+    /** Returns all `<option>` elements. */
+    getOptions(): HTMLOptionElement[];
+    /** Returns the number of options (including placeholder). */
+    getOptionCount(): number;
+    /** Returns the trimmed text of the option at the given index. */
+    getOptionText(index: number): string;
+    /** Returns whether the option at the given index is disabled. */
+    isOptionDisabled(index: number): boolean;
+    /** Returns whether the option at the given index is selected. */
+    isOptionSelected(index: number): boolean;
+    /** Returns the select element's ID. */
+    getId(): string;
+    /** Returns whether the field wrapper has the error class. */
+    hasFieldError(): boolean;
+    /** Returns whether the select has the given CSS class. */
+    hasClass(className: string): boolean;
+    /** Returns whether the `.ct-select-wrap` wrapper exists. */
+    hasSelectWrap(): boolean;
+    /** Dispatches a blur event on the select. */
+    blur(): void;
+}
+
+/** Translatable strings used by the select component. */
+interface AfSelectI18n {
+    /** Screen-reader label for the required asterisk. */
+    required: string;
+    /** Fallback `aria-label` when no `label` input is provided. */
+    selectOption: string;
+    /** Announcement when an option is selected. Use `{label}` as placeholder. */
+    selected: string;
 }
+/**
+ * Injection token to override select screen-reader announcements
+ * and the fallback `aria-label`.
+ *
+ * @example
+ * providers: [{
+ *   provide: AF_SELECT_I18N,
+ *   useValue: {
+ *     required: 'Pflichtfeld',
+ *     selectOption: 'Option auswählen',
+ *     selected: '{label} ausgewählt',
+ *   },
+ * }]
+ */
+declare const AF_SELECT_I18N: InjectionToken<AfSelectI18n>;
 
 /**
  * Textarea component with form control support
@@ -3082,5 +3230,5 @@ declare class AfFormatLabelPipe implements PipeTransform {
     static ɵpipe: _angular_core.ɵɵPipeDeclaration<AfFormatLabelPipe, "afFormatLabel", true>;
 }
 
-export { AF_ACCORDION_I18N, AF_ALERT_I18N, AF_INPUT_I18N, AF_SELECT_MENU_I18N, AfAccordionComponent, AfAccordionHarness, AfAccordionItemComponent, AfAccordionItemHarness, AfAlertComponent, AfAlertHarness, AfAppShellComponent, AfAppShellPageHeaderComponent, AfAppShellV2Component, AfAppShellV2ToolbarComponent, AfAvatarComponent, AfBadgeComponent, AfBadgeHarness, AfBannerComponent, AfBreadcrumbsComponent, AfButtonComponent, AfButtonHarness, AfCardComponent, AfCellDefDirective, AfCheckboxComponent, AfChipComponent, AfChipInputComponent, AfComboboxComponent, AfDataTableComponent, AfDatepickerComponent, AfDividerComponent, AfDrawerComponent, AfDropdownComponent, AfEmptyStateComponent, AfFieldComponent, AfFileUploadComponent, AfFormatLabelPipe, AfIconComponent, AfInputComponent, AfInputHarness, AfModalComponent, AfNavItemComponent, AfNavTabsComponent, AfNavbarComponent, AfPaginationComponent, AfPopoverComponent, AfPopoverTriggerDirective, AfProgressBarComponent, AfRadioComponent, AfRadioGroupComponent, AfSelectComponent, AfSelectMenuComponent, AfSelectMenuHarness, AfSidebarComponent, AfSkeletonComponent, AfSkipLinkComponent, AfSliderComponent, AfSpinnerComponent, AfSwitchComponent, AfTabPanelComponent, AfTableBodyComponent, AfTableCellComponent, AfTableComponent, AfTableHeaderCellComponent, AfTableHeaderComponent, AfTableRowComponent, AfTabsComponent, AfTextareaComponent, AfToastContainerComponent, AfToastService, AfToggleGroupComponent, AfToolbarComponent, AfTooltipDirective };
-export type { AfAccordionI18n, AfAlertI18n, AfAlertVariant, AfAvatarSize, AfAvatarStatus, AfBadgeVariant, AfBannerAppearance, AfBannerPosition, AfBannerVariant, AfBreadcrumb, AfButtonSize, AfButtonType, AfButtonVariant, AfCardElevation, AfCardPadding, AfChipAppearance, AfChipSize, AfChipVariant, AfColumn, AfComboboxOption, AfDataRow, AfDataTableConfig, AfDateRange, AfDatepickerMode, AfDatepickerValueFormat, AfDatepickerView, AfDividerColor, AfDividerOrientation, AfDividerSpacing, AfDrawerPosition, AfDrawerSize, AfDropdownItem, AfEmptyStateSize, AfEmptyStateVariant, AfFileEntry, AfFileValidationError, AfIconSize, AfInputI18n, AfInputType, AfNavTab, AfNavTabsSize, AfNavTabsVariant, AfNavbarSize, AfNavbarVariant, AfPopoverAlign, AfPopoverPosition, AfPopoverSize, AfProgressBarSize, AfProgressBarVariant, AfSelectMenuI18n, AfSelectMenuOption, AfSelectOption, AfShellPanelState, AfShellSidebarState, AfSidebarMode, AfSkeletonVariant, AfSliderSize, AfSortDirection, AfSortState, AfSpinnerSize, AfTab, AfTableCellType, AfTableVariant, AfToast, AfToastVariant, AfToggleGroupSize, AfToggleItem, AfTooltipPosition };
+export { AF_ACCORDION_I18N, AF_ALERT_I18N, AF_INPUT_I18N, AF_SELECT_I18N, AF_SELECT_MENU_I18N, AVATAR_SEED_PALETTE_SIZE, AfAccordionComponent, AfAccordionHarness, AfAccordionItemComponent, AfAccordionItemHarness, AfAlertComponent, AfAlertHarness, AfAppShellComponent, AfAppShellPageHeaderComponent, AfAppShellV2Component, AfAppShellV2ToolbarComponent, AfAvatarComponent, AfBadgeComponent, AfBadgeHarness, AfBannerComponent, AfBreadcrumbsComponent, AfButtonComponent, AfButtonHarness, AfCardComponent, AfCellDefDirective, AfCheckboxComponent, AfChipComponent, AfChipInputComponent, AfComboboxComponent, AfDataTableComponent, AfDatepickerComponent, AfDividerComponent, AfDrawerComponent, AfDropdownComponent, AfEmptyStateComponent, AfFieldComponent, AfFileUploadComponent, AfFormatLabelPipe, AfIconComponent, AfInputComponent, AfInputHarness, AfModalComponent, AfNavItemComponent, AfNavTabsComponent, AfNavbarComponent, AfPaginationComponent, AfPopoverComponent, AfPopoverTriggerDirective, AfProgressBarComponent, AfRadioComponent, AfRadioGroupComponent, AfSelectComponent, AfSelectHarness, AfSelectMenuComponent, AfSelectMenuHarness, AfSidebarComponent, AfSkeletonComponent, AfSkipLinkComponent, AfSliderComponent, AfSpinnerComponent, AfSwitchComponent, AfTabPanelComponent, AfTableBodyComponent, AfTableCellComponent, AfTableComponent, AfTableHeaderCellComponent, AfTableHeaderComponent, AfTableRowComponent, AfTabsComponent, AfTextareaComponent, AfToastContainerComponent, AfToastService, AfToggleGroupComponent, AfToolbarComponent, AfTooltipDirective };
+export type { AfAccordionI18n, AfAlertI18n, AfAlertVariant, AfAvatarSize, AfAvatarStatus, AfBadgeVariant, AfBannerAppearance, AfBannerPosition, AfBannerVariant, AfBreadcrumb, AfButtonSize, AfButtonType, AfButtonVariant, AfCardElevation, AfCardPadding, AfChipAppearance, AfChipSize, AfChipVariant, AfColumn, AfComboboxOption, AfDataRow, AfDataTableConfig, AfDateRange, AfDatepickerMode, AfDatepickerValueFormat, AfDatepickerView, AfDividerColor, AfDividerOrientation, AfDividerSpacing, AfDrawerPosition, AfDrawerSize, AfDropdownItem, AfEmptyStateSize, AfEmptyStateVariant, AfFileEntry, AfFileValidationError, AfIconSize, AfInputI18n, AfInputType, AfNavTab, AfNavTabsSize, AfNavTabsVariant, AfNavbarSize, AfNavbarVariant, AfPopoverAlign, AfPopoverPosition, AfPopoverSize, AfProgressBarSize, AfProgressBarVariant, AfSelectI18n, AfSelectMenuI18n, AfSelectMenuOption, AfSelectOption, AfShellPanelState, AfShellSidebarState, AfSidebarMode, AfSkeletonVariant, AfSliderSize, AfSortDirection, AfSortState, AfSpinnerSize, AfTab, AfTableCellType, AfTableVariant, AfToast, AfToastVariant, AfToggleGroupSize, AfToggleItem, AfTooltipPosition };