@nordhealth/components 4.26.2 → 5.0.0

package/lib/src/accordion/Accordion.d.ts

@@ -0,0 +1,121 @@
+import { LitElement } from 'lit';
+import { NordEvent } from '../common/events.js';
+/**
+ * Event dispatched when the set of open accordion items changes.
+ */
+export declare class AccordionChangeEvent extends NordEvent {
+    value: string[];
+    constructor(value: string[]);
+}
+declare const Accordion_base: typeof LitElement;
+/**
+ * Accordion is a set of collapsible sections, each with a header that toggles
+ * the visibility of its content. It coordinates a group of
+ * [Accordion Item](/components/accordion-item/) elements, keyboard focus
+ * movement between them, and which items are open.
+ *
+ * @status draft
+ * @category container
+ * @lightDom true
+ *
+ * @slot - Default slot for [Accordion Item](/components/accordion-item/) elements.
+ *
+ * @fires {AccordionChangeEvent} change - Dispatched when an item is expanded or collapsed. The event includes a `value` array of the currently open item values.
+ *
+ * @cssprop --n-accordion-item-gap - Spacing between accordion items.
+ *
+ * @remarks
+ * `value` is the source of truth as an array property. The `value` attribute is
+ * only read as a comma-separated seed: it is adopted on connect and again
+ * whenever the attribute is set (e.g. `el.setAttribute('value', 'a,b')`), but it
+ * is **not** reflected back to the DOM as the open set changes via interaction.
+ * Read `accordion.value` (the property) to get the current open set; do not rely
+ * on the `value` attribute staying in sync after the user interacts.
+ */
+export default class Accordion extends Accordion_base {
+    static get observedAttributes(): string[];
+    private accordionId;
+    private direction;
+    private rovingFocus;
+    private childObserver?;
+    private setupScheduled;
+    /**
+     * Whether multiple items can be open at the same time.
+     */
+    multiple: boolean;
+    /**
+     * Whether the component should ignore user interaction.
+     */
+    disabled: boolean;
+    /**
+     * The visual orientation of the accordion. Controls whether roving focus uses
+     * left/right or up/down arrow keys.
+     */
+    orientation: 'vertical' | 'horizontal';
+    /**
+     * Whether to loop keyboard focus back to the first item when the end of the
+     * list is reached while using the arrow keys.
+     */
+    loopFocus: boolean;
+    /**
+     * The value(s) of the item(s) that are open. Assign an array via the property,
+     * or provide an initial comma-separated `value="a,b"` attribute.
+     */
+    value: string[];
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
+    /**
+     * Seed the open set from a `value="a,b"` attribute the first time we connect.
+     * The property is the source of truth thereafter.
+     */
+    private adoptValueAttribute;
+    /**
+     * Watch for items being added, removed, or reordered so newly slotted items
+     * get wired up (ids / ARIA / open-state). Re-runs `setup()` deferred to a
+     * microtask to avoid measuring/reflecting mid-mutation (reflection race).
+     */
+    private observeChildren;
+    private scheduleSetup;
+    protected createRenderRoot(): this;
+    private get items();
+    /**
+     * If no `value` was provided but items declare `open`, adopt those as the
+     * initial open set (mirrors `defaultValue` from open items).
+     */
+    private seedDefaultValue;
+    /**
+     * Wire up ids and ARIA relationships, delegate trigger activation, and reflect
+     * the open state of every item.
+     */
+    private setup;
+    private itemIdCount;
+    protected handleValueChange(oldValue: string[] | undefined): void;
+    protected handleDisabledChange(): void;
+    /**
+     * Reflect the current open set onto every item.
+     */
+    private syncState;
+    /**
+     * Open or close a single item, respecting the `multiple` setting.
+     */
+    private setItemOpen;
+    /**
+     * Toggle an item when its trigger is activated. Called directly by the
+     * [Accordion Trigger](/components/accordion-trigger/).
+     * @internal
+     */
+    activateTrigger(trigger: HTMLElement): void;
+    /**
+     * Move keyboard focus between triggers. Called by triggers on arrow/Home/End.
+     * The focused trigger is the current item, so the shared roving controller
+     * resolves it from the active element.
+     */
+    handleTriggerKeydown(event: KeyboardEvent): void;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'nord-accordion': Accordion;
+    }
+}
+export {};

package/lib/src/accordion/AccordionHeader.d.ts

@@ -0,0 +1,28 @@
+import { LitElement } from 'lit';
+/**
+ * Accordion Header is the heading that labels an
+ * [Accordion Panel](/components/accordion-panel/). Following the WAI-ARIA
+ * accordion pattern, its [Accordion Trigger](/components/accordion-trigger/)
+ * button is wrapped in a heading element.
+ *
+ * @status draft
+ * @category container
+ * @lightDom true
+ *
+ * @slot - Default slot for an [Accordion Trigger](/components/accordion-trigger/).
+ */
+export default class AccordionHeader extends LitElement {
+    /**
+     * The heading level exposed to assistive technology, matching the surrounding
+     * document outline.
+     */
+    level: number;
+    connectedCallback(): void;
+    protected createRenderRoot(): this;
+    protected handleLevelChange(): void;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'nord-accordion-header': AccordionHeader;
+    }
+}

package/lib/src/accordion/AccordionItem.d.ts

@@ -0,0 +1,68 @@
+import { LitElement } from 'lit';
+/**
+ * Accordion Item groups an [Accordion Header](/components/accordion-header/) and
+ * its [Accordion Panel](/components/accordion-panel/) within an
+ * [Accordion](/components/accordion/).
+ *
+ * @status draft
+ * @category container
+ * @lightDom true
+ *
+ * @slot - Default slot for an [Accordion Header](/components/accordion-header/) and an [Accordion Panel](/components/accordion-panel/).
+ */
+export default class AccordionItem extends LitElement {
+    /**
+     * A unique value identifying this item within its
+     * [Accordion](/components/accordion/). Used to track which items are open.
+     */
+    value: string;
+    /**
+     * Whether this item is open. Coordinated by the parent
+     * [Accordion](/components/accordion/).
+     */
+    open: boolean;
+    /**
+     * Whether this item is disabled.
+     */
+    disabled: boolean;
+    /**
+     * Whether the parent [Accordion](/components/accordion/) is disabled. Combined
+     * with `disabled` to determine the effective disabled state. Reactive (and
+     * observed below) so toggling the parent's `disabled` after setup re-syncs the
+     * trigger's disabled/aria-disabled/tabindex.
+     * @internal
+     */
+    parentDisabled: boolean;
+    /**
+     * Stable id base assigned by the parent [Accordion](/components/accordion/).
+     * Persists across re-setup so ids are never reassigned to an item that
+     * already has them.
+     * @internal
+     */
+    partsId?: string;
+    connectedCallback(): void;
+    protected createRenderRoot(): this;
+    private get trigger();
+    private get panel();
+    private get isDisabled();
+    /**
+     * Wire up the ARIA relationship between the trigger and the panel. Called by
+     * the parent [Accordion](/components/accordion/).
+     * @internal
+     */
+    setupParts(id: string): void;
+    protected handleOpenChange(): void;
+    /**
+     * Synchronously push the open state (and ARIA) to the trigger and panel.
+     * Called by the parent [Accordion](/components/accordion/) and on local changes.
+     * @internal
+     */
+    propagate(): void;
+    protected handleDisabledChange(): void;
+    private updateTriggerDisabled;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'nord-accordion-item': AccordionItem;
+    }
+}

package/lib/src/accordion/AccordionPanel.d.ts

@@ -0,0 +1,35 @@
+import { LitElement } from 'lit';
+/**
+ * Accordion Panel holds the content revealed by its
+ * [Accordion Trigger](/components/accordion-trigger/). It must be placed inside
+ * an [Accordion Item](/components/accordion-item/) and animates its height as it
+ * opens and closes.
+ *
+ * @status draft
+ * @category container
+ * @lightDom true
+ *
+ * @slot - Default slot for the panel content.
+ *
+ * @attr {boolean} data-open - Present while the panel is open (or opening).
+ * @attr {boolean} data-closed - Present while the panel is closed.
+ * @attr {boolean} data-starting-style - Present for the first frame of the open transition.
+ * @attr {boolean} data-ending-style - Present while the close transition runs.
+ *
+ * @cssprop [--n-accordion-panel-height] - Set during the open/close animation to the measured content height. Read it to coordinate custom animations.
+ */
+export default class AccordionPanel extends LitElement {
+    /**
+     * Whether the panel is open. Set by the parent
+     * [Accordion Item](/components/accordion-item/).
+     */
+    open: boolean;
+    private collapse;
+    connectedCallback(): void;
+    protected createRenderRoot(): this;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'nord-accordion-panel': AccordionPanel;
+    }
+}

package/lib/src/accordion/AccordionTrigger.d.ts

@@ -0,0 +1,48 @@
+import { LitElement } from 'lit';
+/**
+ * Accordion Trigger is the button that opens and closes its
+ * [Accordion Panel](/components/accordion-panel/). It must be placed inside an
+ * [Accordion Header](/components/accordion-header/).
+ *
+ * @status draft
+ * @category container
+ * @lightDom true
+ *
+ * @slot - Default slot for the trigger label and an icon. The icon is the last
+ * child, so any element or web component can be used; set its size on the
+ * element itself (for example `<nord-icon size="xxs">`).
+ *
+ * @cssprop [--n-accordion-trigger-gap=var(--n-space-xs)] - The gap between the label and the icon, using our [spacing tokens](/tokens/#space).
+ */
+export default class AccordionTrigger extends LitElement {
+    /**
+     * Whether the associated panel is open. Set by the parent
+     * [Accordion Item](/components/accordion-item/); reflected so it can be styled.
+     */
+    open: boolean;
+    /**
+     * Whether the trigger is disabled. Set by the parent
+     * [Accordion Item](/components/accordion-item/).
+     */
+    disabled: boolean;
+    /**
+     * How to justify the label and icon along the trigger. Defaults to
+     * `space-between`, pushing the icon to the far end; set `start` to sit the
+     * label and icon next to each other.
+     */
+    justifyContent?: 'start' | 'center' | 'end' | 'space-between' | 'space-around' | 'space-evenly';
+    private focusable;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    protected createRenderRoot(): this;
+    private get accordion();
+    protected handleOpenChange(): void;
+    private activate;
+    private handleClick;
+    private handleKeydown;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'nord-accordion-trigger': AccordionTrigger;
+    }
+}

package/lib/src/aside/Aside.d.ts

@@ -53,7 +53,7 @@ export declare class AsideHandleModeChangeEvent extends NordEvent {
  * Container for the right-side rail + drawer pattern in the app shell.
  *
  * @status new
- * @category structure
+ * @category layout
  * @slot rail - Free-form content placed in the rail column.
  * @slot tooltip-divider - Tooltip anchored to the resize handle on hover.
  * @slot - Default slot for `<nord-aside-drawer>` panels.

package/lib/src/aside-drawer/AsideDrawer.d.ts

@@ -14,12 +14,14 @@ export declare class AsideDrawerWidthChangeEvent extends NordEvent {
  * A drawer panel inside `<nord-aside>`.
  *
  * @status new
- * @category structure
+ * @category layout
  * @slot - Default slot. Place arbitrary drawer content here.
  *
  * @fires {AsideDrawerWidthChangeEvent} width-change - Dispatched when the
  * drawer's width changes. The event exposes `width` (the new applied
  * inline-size in px) and `source` (`'drag' | 'keyboard' | 'attribute' | 'storage'`).
+ *
+ * @parent Aside
  */
 export default class AsideDrawer extends LitElement {
     static styles: import("lit").CSSResult[];

package/lib/src/aside-trigger/AsideTrigger.d.ts

@@ -11,6 +11,8 @@ import '../tooltip/Tooltip.js';
  * @slot tooltip - Overrides the tooltip body (falls back to `label`).
  *   Lets consumers add icons, shortcut hints, etc. — anything beyond the
  *   plain string label.
+ *
+ * @parent Aside
  */
 export default class AsideTrigger extends LitElement {
     static styles: import("lit").CSSResult[];

package/lib/src/autocomplete/Autocomplete.d.ts

@@ -0,0 +1,190 @@
+import type { ComboboxOption } from '../combobox/ComboboxBase.js';
+import { nothing } from 'lit';
+import ComboboxBase from '../combobox/ComboboxBase.js';
+import { LocalizeController } from '../localization/LocalizeController.js';
+export type { ComboboxOption } from '../combobox/ComboboxBase.js';
+export { ComboboxClearEvent } from '../combobox/ComboboxEvents.js';
+/**
+ * Autocomplete is a free-text input with suggestions: the text the user types
+ * is itself the committed `value` (a string), and the options are completion
+ * aids. Picking a suggestion fills the input with the option's `label` and commits
+ * that label. Use it when the answer is open-ended text but you can offer
+ * helpful completions (a city, a tag, a username); reach for
+ * [Combobox](/components/combobox/) instead when the value must be one of a
+ * fixed set of options.
+ *
+ * Autocomplete is a control only — it has no built-in label, hint or error.
+ * Compose it inside a [Field](/components/field/) to give it a label, hint and
+ * error message, the same way you would a native input.
+ *
+ * Base UI parity: Autocomplete is the Combobox primitive with
+ * `selectionMode="none"` + `fillInputOnItemPress`.
+ *
+ * @status draft
+ * @category form
+ * @lightDom true
+ *
+ * @slot start - Optional slot used to place an icon or prefix at the start of the control.
+ * @slot end - Optional slot used to place an icon or suffix at the end of the control.
+ *
+ * @fires {NordEvent} change - Dispatched when the committed value changes via user interaction.
+ * @fires {NordEvent} input - Dispatched as the user types into the input.
+ * @fires {NordEvent} open - Dispatched when the listbox is opened.
+ * @fires {NordEvent} close - Dispatched when the listbox is closed.
+ * @fires {ComboboxClearEvent} clear - Dispatched when the value is cleared via the clear button or `clear()`.
+ *
+ * @localization clearLabel - Accessible label for the clear button.
+ * @localization noResults - Message shown when no options match the query.
+ *
+ * @cssprop [--n-combobox-list-inline-size] - Controls the inline size, or width, of the dropdown list. Defaults to the width of the control.
+ * @cssprop [--n-combobox-block-size] - Controls the block size, or height, of the control. The medium default is `var(--n-space-xl)`; the s and l sizes scale from it.
+ *
+ * @attr {boolean} data-invalid - Present while the control is invalid (mirrors the `invalid` property). Style hook for the whole control.
+ * @attr {boolean} data-focused - Present while the control has focus. Style hook for focus-within treatments.
+ */
+export default class Autocomplete extends ComboboxBase {
+    /**
+     * The value of the autocomplete. This is the free text the user has typed (or
+     * the `label` of a picked suggestion) — always a single string.
+     */
+    value: string;
+    /**
+     * Enables inline ghost-text completion. While an option is highlighted with
+     * the keyboard, the input shows the typed query followed by the remainder of
+     * the highlighted option's label, with that remainder text-selected so
+     * continued typing overwrites it. Accepting (Enter, ArrowRight/End at the end
+     * of the text, or an option click) commits the full label.
+     */
+    inline: boolean;
+    /**
+     * Shows a clear (✕) button while there is text. Pressing it resets the value
+     * to `''`, then fires `clear` and `change`.
+     */
+    clearable: boolean;
+    /**
+     * Whether clicking the input opens the suggestion list. Defaults to `false`
+     * for autocomplete — matching Base UI's `openOnInputClick={false}`, the list
+     * appears as the user types rather than on click. Set to `true` to also open
+     * on click.
+     */
+    openOnInputClick: boolean;
+    protected localize: LocalizeController<"nord-autocomplete">;
+    /**
+     * Whether the active option last changed via the keyboard (arrows/Home/End)
+     * rather than pointer hover. Inline ghost completion only fills on keyboard
+     * navigation, mirroring Base UI's `keyboardActiveRef`. Reactive so toggling it
+     * (even when `activeIndex` is unchanged, e.g. a single filtered option)
+     * re-renders the ghost.
+     */
+    private keyboardActive;
+    connectedCallback(): void;
+    /**
+     * The committed free-text `value` *is* the query, so a programmatically-set
+     * `value` (e.g. `el.value = 'fea'`) filters the open list without the user
+     * having typed, matching the text the input already displays.
+     */
+    protected get filterQuery(): string;
+    /** The typed query an inline ghost is composed against (the committed value). */
+    private get inlineQuery();
+    /**
+     * Whether an inline ghost suffix is currently showing: only in `inline` mode,
+     * when the active option (reached via the keyboard) has a label that starts
+     * with the typed query and extends it.
+     */
+    private get hasInlineGhost();
+    /** The text shown in the input. */
+    protected get displayValue(): string;
+    /** Free text is always present once non-empty (drives the clear affordance). */
+    protected get hasValue(): boolean;
+    protected get formValue(): string | undefined;
+    protected get showClear(): boolean;
+    /**
+     * Autocomplete is a search input with suggestions, not a picker — like Base
+     * UI's autocomplete it renders no dropdown chevron (its `AriaCombobox` has no
+     * `Trigger`). The list appears as you type, not on a toggle click.
+     */
+    protected get showToggle(): boolean;
+    /**
+     * The `aria-autocomplete` value for the inner input, mapping the `inline` +
+     * `external-filtering` axes onto the four ARIA values:
+     * - inline + internal filter → `both`
+     * - inline + external-filtering → `inline` (static list + ghost)
+     * - external-filtering (no inline) → `none` (static list, no ghost)
+     * - otherwise → `list` (internal filter, no ghost)
+     */
+    protected get ariaAutocomplete(): 'list' | 'both' | 'inline' | 'none';
+    /**
+     * Autocomplete renders no selection state — `aria-selected` is omitted
+     * (`optionAriaSelected` → nothing) and the check is never shown
+     * (`showCheck` → false) — so nothing is ever "selected".
+     */
+    protected isSelected(): boolean;
+    /**
+     * Autocomplete has no selection model, so the listbox does not advertise
+     * `aria-multiselectable` at all (the base's `'false'` would imply a single-
+     * select semantic it doesn't have).
+     */
+    protected get ariaMultiselectable(): undefined;
+    /** Autocomplete never shows the selected-check icon (it is not a select). */
+    protected showCheck(): boolean;
+    /** No selection model, so no leading check gutter (avoids indenting suggestions). */
+    protected get rendersCheck(): boolean;
+    /** Autocomplete options are completion aids, not selectable values — omit aria-selected. */
+    protected optionAriaSelected(): typeof nothing;
+    /** Autocomplete keeps its committed free-text query when the listbox closes. */
+    protected onHide(): void;
+    /** Typing commits the typed text as the live value. */
+    protected onInput(input: HTMLInputElement): void;
+    /**
+     * Runs before the base's own key switch. Marks keyboard navigation (so the
+     * inline ghost may compose) and owns the ArrowRight/End inline-accept. After
+     * an accept the listbox is closed, so the base's own `End` branch (gated on
+     * `this.open`) is skipped; the base still performs the moves for the arrows
+     * and Home.
+     */
+    protected onKeydown(e: KeyboardEvent): void;
+    protected onMove(): void;
+    /**
+     * Fully owns Enter when the listbox is open. An inline ghost or any
+     * highlighted option fills+commits its label; otherwise the typed text is
+     * already committed, so Enter just closes and does NOT preventDefault (the
+     * owning form may submit). Returns `true` so the base does no further handling.
+     */
+    protected handleEnter(e: KeyboardEvent): boolean;
+    /** Whether the user has typed/committed any free text to complete against. */
+    private get hasQuery();
+    /** Pointer hover never composes an inline ghost (mirrors keyboard-vs-pointer). */
+    protected onOptionHover(): void;
+    /**
+     * Never silently commit an un-accepted inline suggestion: on blur drop the
+     * ghost suffix and restore the input to the typed query (the actual value).
+     */
+    protected onBlur(): void;
+    /**
+     * Lit binds the inner input's `.value` to the ghost-composed string, but the
+     * suffix selection has to be applied imperatively after the DOM update so
+     * continued typing overwrites it.
+     */
+    protected afterUpdate(): void;
+    /**
+     * Picking a suggestion is a completion aid: fill the input with its label and
+     * commit that label as the free-text value. No chips, no array, no toggle.
+     */
+    protected selectOption(option: ComboboxOption): void;
+    /** Commit the currently ghost-highlighted option's full label (inline mode). */
+    private acceptInline;
+    /**
+     * Drop the transient inline ghost suffix, restoring the input to the typed
+     * query (the actual committed `value`). Does not change `value`.
+     */
+    private revertInline;
+    /** A new query supersedes any inline ghost from the previous one. */
+    protected resetActiveIndex(): void;
+    /** Clear the current value, firing `clear` then `change`. */
+    clear(): void;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'nord-autocomplete': Autocomplete;
+    }
+}

package/lib/src/autocomplete/localization.d.ts

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

package/lib/src/avatar/Avatar.d.ts

@@ -6,7 +6,7 @@ import '../icon/Icon.js';
  * Default avatar illustration is displayed when no src is specified.
  *
  * @status ready
- * @category image
+ * @category content
  *
  * @cssprop [--n-avatar-color=var(--n-color-status-highlight)] - Controls the color of the avatar fallback, using [color tokens](/tokens/#color).
  * @cssprop [--n-avatar-size=var(--n-size-icon-l)] - Controls the size of the avatar, using [icon sizing tokens](/tokens/#size).

package/lib/src/badge/Badge.d.ts

@@ -5,7 +5,7 @@ import { LitElement } from 'lit';
  * data to indicate status.
  *
  * @status ready
- * @category text
+ * @category feedback
  * @slot - The badge content.
  * @slot icon - Used to place an icon at the start of badge.
  */

package/lib/src/banner/Banner.d.ts

@@ -1,4 +1,5 @@
 import { LitElement } from 'lit';
+import '../stack/Stack.js';
 /**
  * Banner informs users about important changes or conditions in the
  * interface. Use this component if you need to communicate to users
@@ -7,6 +8,7 @@ import { LitElement } from 'lit';
  * @status ready
  * @category feedback
  * @slot - default slot
+ * @slot actions - Optional slot for action buttons (a call to action and/or a dismiss button), shown at the trailing end of the banner.
  *
  * @cssprop [--n-banner-border-radius=var(--n-border-radius)] - Controls how rounded the corners are, using [border radius tokens](/tokens/#border-radius).
  * @cssprop [--n-banner-box-shadow=var(--n-box-shadow-card)] - Controls the surrounding shadow, using [box shadow tokens](/tokens/#box-shadow).
@@ -17,6 +19,7 @@ export default class Banner extends LitElement {
      * The style variant of the banner.
      */
     variant: 'info' | 'danger' | 'success' | 'warning';
+    private actionsSlot;
     render(): import("lit").TemplateResult<1>;
 }
 declare global {

package/lib/src/button-group/ButtonGroup.d.ts

@@ -3,7 +3,7 @@ import { LitElement } from 'lit';
  * Button groups are designed to bring together button controls that are of a similar nature. For example text formatting controls.
  *
  * @status ready
- * @category structure
+ * @category action
  * @slot - The button group content
  *
  * @cssprop [--n-button-group-border-radius=var(--n-border-radius-s)] - Controls the rounded corners of the button group, using [border radius tokens](/tokens/#border-radius). Only relevant for the default variant.

package/lib/src/calendar/Calendar.d.ts

@@ -9,8 +9,9 @@ export type DatePredicate = (date: Date) => boolean;
  * Please note that the date must be passed in ISO-8601 format.
  *
  * @status ready
- * @category list
+ * @category form
  * @fires {DateSelectEvent} change - Dispatched when a date is selected and the value changes.
+ * @fires {DateRangeSelectEvent} range-change - Dispatched in `range` mode when a complete range (start and end) has been selected.
  * @fires {DateSelectEvent} nord-focus-date - Dispatched when the calendar's focused date changes.
  *
  * @cssprop [--n-calendar-border-radius=var(--n-border-radius)] - Controls how rounded the corners are, using [border radius tokens](/tokens/#border-radius).
@@ -98,8 +99,43 @@ export default class Calendar extends LitElement {
      * It is recommended to return a string rather than a truthy value whenever possible.
      */
     isDateHighlighted: (date: Date) => string | boolean;
+    /**
+     * Opt into range selection. When `true`, clicking selects a range start, and
+     * the next click selects the end (the two clicks are swapped if the second is
+     * earlier than the first). The in-range days are styled, and a hover preview
+     * shows the range that would result. A completed range fires `range-change`.
+     *
+     * This is off by default, so the calendar keeps its single-date behaviour
+     * (the `value`/`change` API) unless `range` is set.
+     */
+    range: boolean;
+    /**
+     * The start of the selected range, in ISO-8601 format: YYYY-MM-DD. Only used
+     * when `range` is set. Pair with `rangeEnd` to control the selection.
+     */
+    rangeStart?: string;
+    /**
+     * The end of the selected range, in ISO-8601 format: YYYY-MM-DD. Only used
+     * when `range` is set. Pair with `rangeStart` to control the selection.
+     */
+    rangeEnd?: string;
+    /**
+     * The number of consecutive months to display side by side, starting from the
+     * focused month. Defaults to `1`. Useful with `range` for picking a span that
+     * crosses months without paging — the range and its hover preview span every
+     * visible month, and the navigation arrows slide the whole window. With more
+     * than one month the month/year dropdowns are replaced by static titles.
+     */
+    months: number;
     private activeFocus;
     private focusedDay;
+    /**
+     * While picking a range, the first click is held here until the second click
+     * completes the range. `undefined` means no in-progress pick.
+     */
+    private pendingRangeStart?;
+    /** The day currently hovered while a range pick is in progress (preview). */
+    private hoveredDay?;
     /**
      * Programmatically move focus to the calendar.
      * @param options An object which controls aspects of the focusing process.
@@ -109,9 +145,17 @@ export default class Calendar extends LitElement {
     }): void;
     render(): import("lit").TemplateResult<1>;
     protected handleValueChange(): void;
+    protected handleRangeChange(): void;
     protected handleFocusedDayChange(): void;
     private handleLangChange;
     private handleDaySelect;
+    /**
+     * Two-click range selection: the first click starts a pending range, the
+     * second completes it. The two ends are swapped if the second click is before
+     * the first, so the committed range is always ordered `start <= end`.
+     */
+    private selectRangeDay;
+    private handleDayHover;
     private getToday;
     private addDays;
     private addMonths;