@nordhealth/components 4.26.1 → 5.0.0-alpha.0

package/lib/src/filter-dropdown/FilterDropdown.d.ts

@@ -0,0 +1,247 @@
+import type { PropertyValues, TemplateResult } from 'lit';
+import { LitElement } from 'lit';
+import '../button/Button.js';
+import '../button-group/ButtonGroup.js';
+import '../input/Input.js';
+import '../popout/Popout.js';
+import '../spinner/Spinner.js';
+import '../visually-hidden/VisuallyHidden.js';
+export { FilterDropdownChangeEvent, FilterDropdownClearEvent, FilterDropdownLoadMoreEvent, FilterDropdownRemoveEvent, FilterDropdownSearchChangeEvent, } from './FilterDropdownEvents.js';
+/** The size of the trigger and popout. */
+export type FilterDropdownSize = 's' | 'm' | 'l';
+/**
+ * A flat, selectable option. With `children` it becomes a tree-style option: the
+ * parent stays selectable and the children render indented beneath it.
+ */
+export interface FilterDropdownSelectableOption {
+    /** The value submitted with `change` and tracked in `value`. */
+    value: string;
+    /** The human-readable text shown in the list. */
+    label: string;
+    /** When `true`, the option cannot be selected. */
+    disabled?: boolean;
+    /** Tree-style child options, rendered indented under this option. */
+    children?: FilterDropdownSelectableOption[];
+    /** Arbitrary data; lets `optionsValueKey`/`optionsLabelKey` overrides work. */
+    [key: string]: unknown;
+}
+/** A heading-labelled cluster of options, rendered with a divider. */
+export interface FilterDropdownGroupOption {
+    /** The heading shown above the group's options. */
+    heading: string;
+    /** The options within the group. */
+    children: FilterDropdownSelectableOption[];
+    /** When `true`, all options within the group cannot be selected. */
+    disabled?: boolean;
+}
+/** Any option shape accepted by the dropdown: flat, grouped, or tree. */
+export type FilterDropdownOption = FilterDropdownSelectableOption | FilterDropdownGroupOption;
+declare const FilterDropdown_base: typeof LitElement;
+/**
+ * Filter Dropdown is a full-featured filter control: a chip trigger that opens a
+ * popout list of options. It owns its selection and tracks `value`, unlike the
+ * composition-first [Filter Field](/components/filter-field/) — pass it `options`
+ * and listen for `change`. It ports the Provet Cloud filter dropdown.
+ *
+ * Options come in three shapes: a flat list (`{ value, label }`), groups
+ * (`{ heading, children }`) rendered with dividers, and tree-style options
+ * (a selectable option with `children`) where the parent stays selectable and the
+ * children render indented. Single mode tracks a string value and closes on
+ * select; `multiple` tracks an array, shows checkboxes and keeps the popout open.
+ *
+ * @status draft
+ * @category form
+ * @lightDom true
+ *
+ * @fires {FilterDropdownChangeEvent} change - Dispatched when the committed selection changes via user interaction.
+ * @fires {FilterDropdownSearchChangeEvent} search-change - Dispatched as the user types when `searchable` (use with `internal-search="false"` for async search).
+ * @fires {FilterDropdownClearEvent} clear - Dispatched when the selection is cleared, before `change`.
+ * @fires {FilterDropdownRemoveEvent} remove - Dispatched when the filter is removed (only when `removable`).
+ * @fires {FilterDropdownLoadMoreEvent} load-more - Dispatched when the list is scrolled near its end (infinite scroll).
+ * @fires {NordEvent} open - Dispatched when the popout is opened.
+ * @fires {NordEvent} close - Dispatched when the popout is closed.
+ *
+ * @localization filterIconLabel - Accessible label for the leading filter icon.
+ * @localization selectionLabel - The chip prefix shown before the highlighted value (e.g. "Status is").
+ * @localization searchLabel - Accessible label for the search input.
+ * @localization clearLabel - Accessible label for the clear button.
+ * @localization removeLabel - Accessible label for the remove button.
+ * @localization selectAll - Label for the select-all row.
+ * @localization deselectAll - Label for the select-all row when everything is selected.
+ * @localization noResults - Message shown when no options match the search.
+ * @localization unknown - Fallback label for a selected value with no matching option.
+ * @localization countSuffix - Suffix appended to the first label when several options are selected.
+ *
+ * @cssprop [--n-filter-dropdown-list-inline-size=250px] - Controls the inline size, or width, of the popout list. Defaults vary by `size`.
+ *
+ * @parent FilterBar
+ */
+export default class FilterDropdown extends FilterDropdown_base {
+    private filterDropdownId;
+    private localize;
+    private listRef;
+    private popout?;
+    private triggerButton?;
+    private dismiss;
+    private activeDescendant;
+    private openState;
+    /**
+     * The label naming what this filter targets, shown on the chip.
+     */
+    label: string;
+    /**
+     * A name identifying what this dropdown filters, for form/identification.
+     */
+    name: string;
+    /**
+     * The icon shown on the trigger.
+     */
+    icon: string;
+    /**
+     * The size of the trigger and popout. Defaults to `s` to match the other
+     * filter controls.
+     */
+    size: FilterDropdownSize;
+    /**
+     * The options to show. Either a flat list (`{ value, label }`), groups
+     * (`{ heading, children }`), or tree-style options (a selectable option with
+     * `children`).
+     */
+    options: FilterDropdownOption[];
+    /**
+     * The key on each option object to read the value from. Defaults to `value`.
+     */
+    optionsValueKey: string;
+    /**
+     * The key on each option object to read the label from. Defaults to `label`.
+     */
+    optionsLabelKey: string;
+    /**
+     * The committed value. A single string in single-select mode, or an array of
+     * strings when `multiple`.
+     */
+    value: string | string[];
+    /**
+     * Allows selecting more than one option. Selected options show a checkbox
+     * indicator and the popout stays open after each selection.
+     */
+    multiple: boolean;
+    /**
+     * Shows a search input at the top of the popout to filter the options.
+     */
+    searchable: boolean;
+    /**
+     * Whether options are filtered client-side by their label. Defaults to `true`.
+     * Set to `false` for async search: the component then emits `search-change` and
+     * leaves filtering to the consumer (who updates `options`).
+     */
+    internalSearch: boolean;
+    /**
+     * Shows a "Select all" control at the top of the popout. Only applies with
+     * `multiple`.
+     */
+    selectAll: boolean;
+    /**
+     * Shows a clear (✕) button while there is a selection. Pressing it clears the
+     * value (firing `clear` then `change`) without removing the dropdown.
+     */
+    clearable: boolean;
+    /**
+     * Whether the whole dropdown can be removed. When `true` the trailing
+     * affordance clears the value and fires `remove`; the consumer removes the
+     * dropdown from the DOM. Takes precedence over `clearable`.
+     */
+    removable: boolean;
+    /**
+     * Makes the component disabled. This prevents users from being able to
+     * interact with it and conveys its inactive state to assistive technologies.
+     */
+    disabled: boolean;
+    /**
+     * Shows a spinner in the popout while asynchronous results are loading. Pair
+     * with `internal-search="false"` for async search.
+     */
+    loading: boolean;
+    /**
+     * Whether the popout is open. Set it to open or close the popout
+     * programmatically.
+     */
+    open: boolean;
+    /**
+     * Message shown when no options match the search. Defaults to "No results.".
+     */
+    noResultsMessage: string;
+    /**
+     * Fallback label shown for a selected value that has no matching option.
+     */
+    labelForUnknown: string;
+    /** The current search text. */
+    private search;
+    /** Set after a keyboard move so the active row is scrolled into view. */
+    private scrollActivePending;
+    /**
+     * Set once a near-end scroll has emitted `load-more`; blocks further emits
+     * from the same gesture until the consumer responds (by toggling `loading` or
+     * appending to `options`). Cleared in `updated` when either changes.
+     */
+    private loadMoreRequested;
+    connectedCallback(): void;
+    protected createRenderRoot(): this;
+    /** Normalises `value` to an array regardless of single/multiple shape. */
+    private get valueAsArray();
+    /** Whether there is any committed selection. */
+    private get isInactive();
+    private getOptionValue;
+    private getOptionLabel;
+    /** Whether any option is a group (has a heading) or a tree (has children). */
+    private get hasGroupedOptions();
+    /** Lowercased search needle, or empty when not filtering internally. */
+    private get needle();
+    private matchesSearch;
+    /**
+     * Flattens grouped/tree options into render sections while preserving visual
+     * hierarchy: groups keep their heading; tree children are emitted right after
+     * their (still-selectable) parent and marked `indent`. Runs of standalone
+     * options are coalesced into one section so no divider appears between them.
+     * Applies the internal search filter as it goes.
+     */
+    private get sections();
+    /** The flat option list in render order, used for keyboard navigation. */
+    private get flatOptions();
+    /** Every selectable value (skipping disabled options), for select-all. */
+    private get allSelectableValues();
+    private get isAllSelected();
+    /** Resolves a value to its label across flat, grouped and tree options. */
+    private labelForValue;
+    /** The summary shown on the chip when there is a selection. */
+    private get selectionLabel();
+    private isSelected;
+    /** Open the popout. */
+    show(): void;
+    /** Close the popout. */
+    hide(): void;
+    /** Focus the trigger button. */
+    focus(options?: FocusOptions): void;
+    private handleTriggerClick;
+    protected updated(changed: PropertyValues): void;
+    private commit;
+    private toggle;
+    private toggleSelectAll;
+    private clear;
+    private handleClear;
+    private handleRemove;
+    private handleSearchInput;
+    private handleListScroll;
+    private handleKeydown;
+    private get listInlineSizeClass();
+    private renderIndicator;
+    private renderOption;
+    private optionId;
+    private renderList;
+    render(): TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'nord-filter-dropdown': FilterDropdown;
+    }
+}

package/lib/src/filter-dropdown/FilterDropdownEvents.d.ts

@@ -0,0 +1,57 @@
+import { NordEvent } from '../common/events.js';
+/**
+ * Dispatched when the committed selection changes via user interaction (picking
+ * an option, toggling a checkbox, select-all, or clearing). Carries the new
+ * `value`: a single string in single-select mode, or an array of strings in
+ * `multiple` mode.
+ */
+export declare class FilterDropdownChangeEvent extends NordEvent {
+    /** The new committed value. */
+    readonly value: string | string[];
+    static eventName: string;
+    constructor(
+    /** The new committed value. */
+    value: string | string[]);
+    /** Convenience accessor mirroring `CustomEvent.detail`. */
+    get detail(): string | string[];
+}
+/**
+ * Dispatched as the user types into the search input. Carries the current search
+ * text so a consumer running external (async) search can update `options`. Only
+ * fired when `searchable` is set.
+ */
+export declare class FilterDropdownSearchChangeEvent extends NordEvent {
+    /** The current search text. */
+    readonly value: string;
+    static eventName: string;
+    constructor(
+    /** The current search text. */
+    value: string);
+    /** Convenience accessor mirroring `CustomEvent.detail`. */
+    get detail(): string;
+}
+/**
+ * Dispatched when the selection is cleared via the clear affordance or `clear()`,
+ * before the accompanying `change` event.
+ */
+export declare class FilterDropdownClearEvent extends NordEvent {
+    static eventName: string;
+    constructor();
+}
+/**
+ * Dispatched when the filter is removed via the remove affordance (only when
+ * `removable`). The consumer removes the dropdown from the DOM in the handler.
+ * The selection is cleared (firing `change`) before this event.
+ */
+export declare class FilterDropdownRemoveEvent extends NordEvent {
+    static eventName: string;
+    constructor();
+}
+/**
+ * Dispatched when the option list is scrolled near its end, so a consumer can
+ * load the next page of options (infinite scroll).
+ */
+export declare class FilterDropdownLoadMoreEvent extends NordEvent {
+    static eventName: string;
+    constructor();
+}

package/lib/src/filter-dropdown/localization.d.ts

@@ -0,0 +1,14 @@
+declare const filterDropdownLocalization: {
+    filterIconLabel: string;
+    /** The chip prefix shown before the highlighted value, e.g. "Status is". */
+    selectionLabel: (label: string) => string;
+    searchLabel: string;
+    clearLabel: string;
+    removeLabel: string;
+    selectAll: string;
+    deselectAll: string;
+    noResults: string;
+    unknown: string;
+    countSuffix: (extra: number) => string;
+};
+export default filterDropdownLocalization;

package/lib/src/filter-field/FilterField.d.ts

@@ -0,0 +1,89 @@
+import { LitElement } from 'lit';
+import '../button/Button.js';
+import '../button-group/ButtonGroup.js';
+import '../visually-hidden/VisuallyHidden.js';
+export { FilterFieldClearEvent, FilterFieldRemoveEvent } from './FilterFieldEvents.js';
+declare const FilterField_base: typeof LitElement;
+/**
+ * Filter Field is the presentation-only filter **chip**: a joined pill showing a
+ * leading icon, the filter's `label`, the active selection summary (`value`) and
+ * a clear or remove affordance, dashed while inactive. It is the shared chip used
+ * across the filter family and the building block for custom filters.
+ *
+ * It owns no popout and tracks no value — drop it into a popout-owning control as
+ * its `slot="trigger"` (the host opens/positions the popout and sets
+ * `aria-controls`/`aria-haspopup`/`aria-expanded` on this element). Show the
+ * active selection with `value`, reset it in response to `clear`, and remove the
+ * whole field in response to `remove`. Your app owns the active filters and any
+ * URL/query state.
+ *
+ * @status draft
+ * @category form
+ * @lightDom true
+ *
+ * @fires {FilterFieldClearEvent} clear - Dispatched when the clear affordance is pressed.
+ * @fires {FilterFieldRemoveEvent} remove - Dispatched when the remove affordance is pressed.
+ *
+ * @localization filterIconLabel - Accessible label for the leading filter icon.
+ * @localization selectionLabel - The chip prefix shown before the highlighted value (e.g. "Status is").
+ * @localization clearLabel - Accessible label for the clear button.
+ * @localization removeLabel - Accessible label for the remove button.
+ *
+ * @parent FilterBar
+ */
+export default class FilterField extends FilterField_base {
+    private localize;
+    private triggerButton?;
+    private ariaObserver?;
+    /** The label naming what this filter targets, shown on the chip. */
+    label: string;
+    /**
+     * A short summary of the active selection (e.g. the selected option's label,
+     * or "3 selected"). When set the chip is shown as active and the clear button
+     * appears; leave it empty for an inactive filter. The chip does not derive this
+     * — set it from your app's state.
+     */
+    value: string;
+    /**
+     * Forces the active (solid) treatment without a `value` summary, for filters
+     * that are on but have nothing short to show.
+     */
+    active: boolean;
+    /**
+     * Shows a clear (✕) button while the chip is active. Defaults to `true`. Has no
+     * effect when `removable` is set.
+     */
+    clearable: boolean;
+    /** The leading icon shown on the chip. */
+    icon: string;
+    /** Identifies the filter (e.g. for your app's active-filter state). */
+    name: string;
+    /**
+     * Whether the whole field can be removed. When `true` the trailing affordance
+     * is a remove button that fires `remove`; otherwise it is a clear button (shown
+     * only when there is a value) that fires `clear`.
+     */
+    removable: boolean;
+    /**
+     * Makes the component disabled. This prevents users from being able to
+     * interact with it and conveys its inactive state to assistive technologies.
+     */
+    disabled: boolean;
+    /** The size of the chip controls. */
+    size: 's' | 'm' | 'l';
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    protected createRenderRoot(): this;
+    protected updated(): void;
+    private forwardAria;
+    /** Whether the filter currently has an active selection. */
+    private get isActive();
+    private handleClear;
+    private handleRemove;
+    render(): import("lit").TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'nord-filter-field': FilterField;
+    }
+}

package/lib/src/filter-field/FilterFieldEvents.d.ts

@@ -0,0 +1,18 @@
+import { NordEvent } from '../common/events.js';
+/**
+ * Dispatched when the filter's value is cleared via the clear affordance. The
+ * field holds no value itself, so the consumer resets the composed control (and
+ * any active-filter/URL state) in the handler.
+ */
+export declare class FilterFieldClearEvent extends NordEvent {
+    static eventName: string;
+    constructor();
+}
+/**
+ * Dispatched when the filter is removed via the remove affordance. The consumer
+ * removes the field from the bar (and clears its filter) in the handler.
+ */
+export declare class FilterFieldRemoveEvent extends NordEvent {
+    static eventName: string;
+    constructor();
+}

package/lib/src/filter-field/localization.d.ts

@@ -0,0 +1,8 @@
+declare const filterFieldLocalization: {
+    filterIconLabel: string;
+    /** The chip prefix shown before the highlighted value, e.g. "Status is". */
+    selectionLabel: (label: string) => string;
+    clearLabel: string;
+    removeLabel: string;
+};
+export default filterFieldLocalization;

package/lib/src/filter-input/FilterInput.d.ts

@@ -0,0 +1,102 @@
+import type { PropertyValues } from 'lit';
+import { LitElement } from 'lit';
+import '../button/Button.js';
+import '../popout/Popout.js';
+declare const FilterInput_base: (new (...args: any[]) => import("../common/mixins/SizeMixin.js").SizeMixinInterface) & (new (...args: any[]) => import("../common/mixins/FormAssociatedMixin.js").FormAssociatedMixinInterface) & (new (...args: any[]) => import("../common/mixins/ReadonlyMixin.js").ReadonlyMixinInterface) & (new (...args: any[]) => import("../common/mixins/InputMixin.js").InputMixinInterface) & (new (...args: any[]) => import("../common/mixins/FocusableMixin.js").FocusableMixinInterface) & typeof LitElement;
+/**
+ * Filter Input is a compact search/text field for filtering a collection. It
+ * replaces the small ad-hoc search inputs that sit in toolbars and table
+ * headers. By default it renders inline as a small search field with a leading
+ * search icon; set `mode="chip"` to collapse it behind a chip button that opens
+ * the input in a popout, which is handy in a crowded [Filter Bar](/components/filter-bar/).
+ *
+ * It emits intent only: `input` as the user types and `change` when the value is
+ * committed. Your app owns the active filters and any URL/query state — read the
+ * value from the event target (or bind `value`) and filter accordingly.
+ *
+ * It is a control only, like [Combobox](/components/combobox/): compose it inside
+ * a [Field](/components/field/) for a visible label, or set `label` for an
+ * accessible name when used standalone.
+ *
+ * @status draft
+ * @category form
+ * @lightDom true
+ *
+ * @fires {NordEvent} input - Dispatched as the user types into the input.
+ * @fires {NordEvent} change - Dispatched when the value is committed.
+ * @fires {NordEvent} open - Dispatched when the chip-mode popout is opened.
+ * @fires {NordEvent} close - Dispatched when the chip-mode popout is closed.
+ *
+ * @slot start - Leading icon/content; defaults to a search icon.
+ * @slot end - Trailing icon/content before the clear button.
+ *
+ * @localization searchLabel - Default accessible label for the input when no `label` is set.
+ * @localization clearLabel - Accessible label for the clear button.
+ *
+ * @cssprop [--n-filter-input-inline-size] - Controls the inline size, or width, of the inline input.
+ *
+ * @parent FilterBar
+ */
+export default class FilterInput extends FilterInput_base {
+    private filterInputId;
+    private localize;
+    private popout?;
+    private startZone?;
+    private endZone?;
+    private slotObserver?;
+    private dismiss;
+    private openState;
+    /**
+     * How the input is presented.
+     *
+     * - `inline` (default) renders the search field directly.
+     * - `chip` collapses the field behind a chip button that opens a popout
+     *   containing the input.
+     */
+    mode: 'inline' | 'chip';
+    /**
+     * Whether the chip-mode popout is open. Only meaningful with `mode="chip"`.
+     */
+    open: boolean;
+    /**
+     * The size of the search control. Defaults to `s` to match the other filter
+     * controls in a compact filter bar; set `m` or `l` to enlarge it.
+     */
+    size: 's' | 'm' | 'l';
+    /**
+     * Whether to show a clear (✕) button while there is a value. Clearing resets
+     * the value to `''`, then fires `input` and `change`.
+     */
+    clearable: boolean;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    protected createRenderRoot(): HTMLDivElement | this;
+    /**
+     * Relocates the host's `slot="start"`/`slot="end"` children into the matching
+     * landing zone inside the control. Only direct host children are considered,
+     * and a child already sitting in its zone is left untouched, so repeated
+     * updates are idempotent and don't disturb focus or pointer state.
+     */
+    private relocateSlots;
+    protected updated(changed: PropertyValues): void;
+    /**
+     * The accessible name for the input: the enclosing Field's label, the host
+     * `aria-label`, the `label` prop, or the default term.
+     */
+    private get inputAccessibleName();
+    /** Open the chip popout. */
+    show(): void;
+    /** Close the chip popout. */
+    hide(): void;
+    private handleTriggerClick;
+    private handleClear;
+    /** The search field itself, shared by both modes. */
+    private renderInput;
+    render(): import("lit").TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'nord-filter-input': FilterInput;
+    }
+}
+export {};

package/lib/src/filter-input/localization.d.ts

@@ -0,0 +1,5 @@
+declare const filterInputLocalization: {
+    searchLabel: string;
+    clearLabel: string;
+};
+export default filterInputLocalization;

package/lib/src/filter-reset-button/FilterResetButton.d.ts

@@ -0,0 +1,50 @@
+import { LitElement } from 'lit';
+import '../button/Button.js';
+declare const FilterResetButton_base: typeof LitElement;
+/**
+ * Filter Reset Button clears every active filter at once. It is a thin,
+ * intent-only control: it renders a plain button and dispatches a `reset` event
+ * when pressed. Your app owns the active filters and is responsible for clearing
+ * them (and any URL/query state) in the handler — the button holds no state of
+ * its own.
+ *
+ * Disable it while there is nothing to reset by binding `disabled` to whether any
+ * filter is active (e.g. `?disabled=${!hasFilters}`). Mirrors the Provet Cloud
+ * filter reset button.
+ *
+ * @status draft
+ * @category form
+ * @lightDom true
+ *
+ * @fires {NordEvent} reset - Dispatched when the button is pressed to clear all active filters.
+ *
+ * @localization label - The text label for the reset button.
+ *
+ * @cssprop [--n-filter-reset-button-color=var(--n-color-text-highlight)] - Controls the text and icon color while the button is enabled.
+ *
+ * @parent FilterBar
+ */
+export default class FilterResetButton extends FilterResetButton_base {
+    private localize;
+    /**
+     * Makes the component disabled. This prevents users from being able to
+     * interact with it and conveys its inactive state to assistive technologies.
+     * Bind it to whether any filter is active so the control is only enabled when
+     * there is something to reset.
+     */
+    disabled: boolean;
+    /**
+     * The size of the button.
+     */
+    size: 's' | 'm' | 'l';
+    connectedCallback(): void;
+    protected createRenderRoot(): this;
+    private handleClick;
+    render(): import("lit").TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'nord-filter-reset-button': FilterResetButton;
+    }
+}
+export {};

package/lib/src/filter-reset-button/localization.d.ts

@@ -0,0 +1,4 @@
+declare const filterResetButtonLocalization: {
+    label: string;
+};
+export default filterResetButtonLocalization;