@nysds/components 1.16.1 → 1.18.0

package/dist/packages/nys-backtotop/src/nys-backtotop.d.ts

@@ -5,12 +5,23 @@ import { LitElement } from "lit";
  * Auto-shows after scrolling 1.5 viewports on pages 4+ screens tall. Set `visible` to force display.
  * Renders as circle button on mobile. Position with `position` prop (`left` or `right`).
  *
- * @summary Floating back-to-top button with auto-show behavior and smooth scroll.
+ * **Placement:** For best accessibility, place as the first focusable element in the page footer.
+ * If no footer exists, place at the bottom of the body tag (after main content). Floating
+ * positioning allows it to overlay content without taking up layout space.
+ *
+ * **Focus Management:** When clicked, after scrolling to the top, focus is automatically moved
+ * to the `<main>` element (if present), the first heading (`<h1>` or `<h2>`), or the document element.
+ * This ensures keyboard navigation continues naturally from the top of the page.
+ *
+ * @summary Floating back-to-top button with auto-show behavior, smooth scroll, and focus management.
  * @element nys-backtotop
  *
- * @example Auto-appearing button
+ * @example Auto-appearing button in footer
  * ```html
- * <nys-backtotop></nys-backtotop>
+ * <footer>
+ *   <nys-backtotop></nys-backtotop>
+ *   <!-- Other footer content -->
+ * </footer>
  * ```
  *
  * @example Always visible, left position
@@ -40,6 +51,7 @@ export declare class NysBacktotop extends LitElement {
      */
     private _handleScroll;
     private _scrollToTop;
+    private _moveFocusToTop;
     private _handleResize;
     render(): import("lit-html").TemplateResult<1>;
 }

package/dist/packages/nys-badge/src/nys-badge.d.ts

@@ -39,6 +39,8 @@ export declare class NysBadge extends LitElement {
     prefixLabel: string;
     /** Primary label text displayed in the badge. */
     label: string;
+    /** Screen reader text appended after the label for additional context. */
+    srText: string;
     variant: "strong" | "";
     private _prefixIcon;
     get prefixIcon(): string | boolean;

package/dist/packages/nys-breadcrumbs/src/index.d.ts

@@ -0,0 +1 @@
+export * from "./nys-breadcrumbs";

package/dist/packages/nys-breadcrumbs/src/nys-breadcrumbs.d.ts

@@ -0,0 +1,119 @@
+import { LitElement } from "lit";
+/**
+ * A breadcrumb navigation trail composed of `nys-breadcrumbitem` elements.
+ * Collapses when the trail exceeds 5 items on desktop or 3 items on mobile,
+ * showing the first, last, and item before the current page, with an ellipsis to expand.
+ * A single item renders as a back-to-parent link instead of a trail.
+ *
+ * @summary Breadcrumb navigation trail with responsive collapse support.
+ * @element nys-breadcrumbs
+ *
+ * @slot - One or more `nys-breadcrumbitem` elements defining the trail.
+ *
+ * @fires nys-breadcrumbs-expand - Fired when the user clicks the ellipsis to expand the trail.
+ *
+ * @example Full trail with current page
+ * ```html
+ * <nys-breadcrumbs>
+ *  <ol>
+ *   <li><a href="/">Home</a></li>
+ *   <li><a href="/services">Services</a></li>
+ *   <li>Current Page</li>
+ *  </ol>
+ * </nys-breadcrumbs>
+ * ```
+ *
+ * @example Trail without current page
+ * ```html
+ * <nys-breadcrumbs>
+ *  <ol>
+ *   <li><a href="/">Home</a></li>
+ *   <li><a href="/services">Services</a></li>
+ *  </ol>
+ * </nys-breadcrumbs>
+ * ```
+ *
+ * @example Single item renders as back-to-parent
+ * ```html
+ * <nys-breadcrumbs>
+ *  <ol>
+ *   <li><a href="/services">Services</a></li>
+ *  </ol>
+ * </nys-breadcrumbs>
+ * ```
+ */
+export declare class NysBreadcrumbs extends LitElement {
+    static styles: import("lit").CSSResult;
+    /**
+     * Unique identifier. Auto-generated if not provided.
+     */
+    id: string;
+    /**
+     * Accessible label for the `<nav>` landmark. Defaults to "path to this page" if not set.
+     * Override when multiple crumbs exist on the same page.
+     */
+    ariaLabel: string;
+    /**
+     * Controls the visual size of the breadcrumb text and spacing: `sm` for dense layouts, `md` (default) for standard use.
+     * @default "md"
+     */
+    size: "sm" | "md" | "";
+    /**
+     * On mobile, renders the trail as a single back-to-parent link pointing to the item before the current page.
+     * Has no effect on desktop or when only one item is present (which always renders as a back link).
+     * @default false
+     */
+    backToParent: boolean;
+    /**
+     * Forces the trail into its collapsed state.
+     * It shows only the first item, an ellipsis, and the last two items.
+     * The user can still expand the trail by clicking the ellipsis.
+     * @default false
+     */
+    collapsed: boolean;
+    /**
+     * Renders a filled light theme background bar behind the breadcrumb trail.
+     * @default false
+     */
+    backgroundBar: boolean;
+    /**
+     * Prevents interaction.
+     * @default false
+     */
+    disabled: boolean;
+    private _collapseThreshold;
+    private _manuallyExpanded;
+    private _mediaQuery;
+    /**
+     * Lifecycle methods
+     * --------------------------------------------------------------------------
+     */
+    constructor();
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    firstUpdated(): void;
+    updated(changedProperties: Map<string | number | symbol, unknown>): void;
+    /**
+     * Functions
+     * --------------------------------------------------------------------------
+     */
+    private _updateCollapseThreshold;
+    private _getSlottedOl;
+    private _getSlottedItems;
+    private _getAnchor;
+    private _isCurrentPage;
+    private _createBackToParentElement;
+    private _createCrumbElement;
+    /**
+     * Main logic for cloning and handling user slots.
+     * New <ol>, <li>, and <a> tags are created and rendered out as crumbs for the breadcrumbs trail.
+     */
+    private _handleSlotChange;
+    private _moveFocusToFirstExpandCrumb;
+    /**
+     * Event Handlers
+     * --------------------------------------------------------------------------
+     */
+    private _dispatchExpandEvent;
+    render(): import("lit-html").TemplateResult<1>;
+}

package/dist/packages/nys-breadcrumbs/src/nys-breadcrumbs.figma.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/packages/nys-button/src/nys-button.d.ts

@@ -108,11 +108,11 @@ export declare class NysButton extends LitElement {
      */
     ariaControls: string;
     /**
-     * Material Symbol icon before label. Not shown for `text` variant or `circle` mode.
+     * Material Symbol icon before label. Not shown for `circle` mode.
      */
     prefixIcon: string;
     /**
-     * Material Symbol icon after label. Use `chevron_down` for dropdowns, `open_in_new` for external links. Not shown for `text` variant or `circle` mode.
+     * Material Symbol icon after label. Use `chevron_down` for dropdowns, `open_in_new` for external links. Not shown for `circle` mode.
      */
     suffixIcon: string;
     /**

package/dist/packages/nys-checkbox/src/nys-checkbox.d.ts

@@ -66,8 +66,6 @@ export declare class NysCheckbox extends LitElement {
     groupExist: boolean;
     /** Renders as tile with larger clickable area. Apply to group for consistency. */
     tile: boolean;
-    /** Adjusts colors for dark backgrounds. */
-    inverted: boolean;
     /** Tooltip text shown on hover/focus of info icon. */
     tooltip: string;
     /**

package/dist/packages/nys-checkbox/src/nys-checkboxgroup.d.ts

@@ -3,7 +3,7 @@ import { LitElement } from "lit";
  * A container for grouping multiple `nys-checkbox` components as a single form control.
  * Handles validation, required constraints, and submits comma-separated values.
  *
- * Use to allow users to select multiple options from a list. Apply `tile`, `size`, and `inverted` to the group
+ * Use to allow users to select multiple options from a list. Apply `tile` and `size` to the group
  * and all children inherit these styles automatically.
  *
  * @summary Container for grouping checkboxes as a single form control.
@@ -50,8 +50,6 @@ export declare class NysCheckboxgroup extends LitElement {
     tile: boolean;
     /** Tooltip text shown on hover/focus of info icon. */
     tooltip: string;
-    /** Adjusts colors for dark backgrounds. Applied to all children. */
-    inverted: boolean;
     /** Form `id` to associate with. Applied to all children. */
     form: string | null;
     /**
@@ -84,7 +82,6 @@ export declare class NysCheckboxgroup extends LitElement {
     private _setCustomOtherError;
     private _updateCheckboxSize;
     private _updateCheckboxTile;
-    private _updateCheckboxInvert;
     private _updateCheckboxShowError;
     private _updateCheckboxForm;
     private _getSlotDescriptionForAria;

package/dist/packages/nys-combobox/src/nys-combobox.d.ts

@@ -22,6 +22,14 @@ import { LitElement } from "lit";
  */
 export declare class NysCombobox extends LitElement {
     static styles: import("lit").CSSResult;
+    static shadowRootOptions: {
+        delegatesFocus: boolean;
+        clonable?: boolean;
+        customElementRegistry?: CustomElementRegistry;
+        mode: ShadowRootMode;
+        serializable?: boolean;
+        slotAssignment?: SlotAssignmentMode;
+    };
     id: string;
     name: string;
     label: string;

package/dist/packages/nys-datepicker/src/nys-datepicker.d.ts

@@ -107,6 +107,7 @@ export declare class NysDatepicker extends LitElement {
     connectedCallback(): void;
     disconnectedCallback(): void;
     firstUpdated(): Promise<void>;
+    updated(changedProperties: Map<string | number | symbol, unknown>): void;
     private _whenWcDatepickerReady;
     /**
      * Form Integration

package/dist/packages/nys-dropdownmenu/src/nys-dropdownmenu.d.ts

@@ -38,6 +38,7 @@ export declare class NysDropdownMenu extends LitElement {
     private _trigger;
     private _menuElement;
     private _ariaTarget;
+    private _lastFocusedIndex;
     private readonly GAP;
     /**
      * Lifecycle Methods
@@ -57,7 +58,7 @@ export declare class NysDropdownMenu extends LitElement {
     private _closeDropdown;
     private _getMenuItems;
     private _handleDocumentClick;
-    private _focusOnFirstItem;
+    private _focusOnItem;
     private applyInverseTransform;
     /**
      * Position Logic
@@ -101,6 +102,7 @@ export declare class NysDropdownMenu extends LitElement {
      * Event Handlers
      * --------------------------------------------------------------------------
      */
+    private _handleMenuClick;
     private _handleTriggerKeydown;
     private _handleMenuKeydown;
     private _handleWindowResize;

package/dist/packages/nys-errormessage/src/nys-errormessage.d.ts

@@ -10,18 +10,18 @@ import { LitElement } from "lit";
  */
 export declare class NysErrorMessage extends LitElement {
     static styles: import("lit").CSSResult;
+    /** The "id" of the error message. */
+    id: string;
     /** Whether to display the error message. */
     showError: boolean;
     /** Error text to display. Falls back to native validation message if available. */
     errorMessage: string;
     /** Shows a divider line above the error message. */
     showDivider: boolean;
-    private _internals;
     /**
      * Lifecycle methods
      * --------------------------------------------------------------------------
      */
-    static formAssociated: boolean;
     constructor();
     render(): import("lit-html").TemplateResult<1>;
 }

package/dist/packages/nys-label/src/nys-label.d.ts

@@ -12,8 +12,8 @@ import { LitElement } from "lit";
  */
 export declare class NysLabel extends LitElement {
     static styles: import("lit").CSSResult;
-    /** ID of the form element this label is associated with. */
-    for: string;
+    /** The ID of the label. */
+    id: string;
     /** Label text displayed above the form field. */
     label: string;
     /** Helper text displayed below the label. */
@@ -23,13 +23,16 @@ export declare class NysLabel extends LitElement {
     /** Adjusts colors for dark backgrounds. */
     inverted: boolean;
     /** Tooltip text shown on hover/focus of info icon next to label. */
-    get tooltip(): string;
-    set tooltip(value: string);
-    private _tooltip;
+    tooltip: string;
+    connectedCallback(): void;
     /**
      * Event Handlers
      * --------------------------------------------------------------------------
      */
-    private _handleLabelClick;
+    /**
+     * While most components don't need to listen for this event.
+     * Special components like "nys-fileinput" and "nys-toggle" need to listen for label to execute their specific functionalities.
+     */
+    private _dispatchLabelClick;
     render(): import("lit-html").TemplateResult<1>;
 }

package/dist/packages/nys-radiobutton/src/nys-radiobutton.d.ts

@@ -50,8 +50,6 @@ export declare class NysRadiobutton extends LitElement {
     name: string;
     /** Value submitted when this radio is selected. */
     value: string;
-    /** Adjusts colors for dark backgrounds. */
-    inverted: boolean;
     /** Form `id` to associate with. */
     form: string | null;
     /**

package/dist/packages/nys-radiobutton/src/nys-radiogroup.d.ts

@@ -3,7 +3,7 @@ import { LitElement } from "lit";
  * A container for grouping `nys-radiobutton` elements as a single form control with enforced single selection.
  * Handles keyboard navigation (arrow keys), validation, required constraints, and form integration.
  *
- * Use to let users select exactly one option from 2-6 choices. Apply `tile`, `size`, and `inverted` to the group
+ * Use to let users select exactly one option from 2-6 choices. Apply `tile` and `size` to the group
  * and all children inherit these styles automatically. For 7+ options, use `nys-select`.
  *
  * @summary Container for grouping radio buttons as a single form control.
@@ -51,8 +51,6 @@ export declare class NysRadiogroup extends LitElement {
     tile: boolean;
     /** Tooltip text shown on hover/focus of info icon. */
     tooltip: string;
-    /** Adjusts colors for dark backgrounds. Applied to all children. */
-    inverted: boolean;
     /** Form `id` to associate with. Applied to all children. */
     form: string | null;
     /**
@@ -93,7 +91,6 @@ export declare class NysRadiogroup extends LitElement {
     private _initializeChildAttributes;
     private _updateRadioButtonsSize;
     private _updateRadioButtonsTile;
-    private _updateRadioButtonsInvert;
     private _updateRadioButtonsShowError;
     private _updateRadioButtonsForm;
     private _getSlotDescriptionForAria;

package/dist/packages/nys-tab/src/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./nys-tab";
+export * from "./nys-tabgroup";
+export * from "./nys-tabpanel";

package/dist/packages/nys-tab/src/nys-tab.d.ts

@@ -0,0 +1,116 @@
+import { LitElement } from "lit";
+/**
+ * `<nys-tab>` is a single tab within a `<nys-tabgroup>`.
+ *
+ * The host element carries `role="tab"`, `tabindex`, `aria-selected`,
+ * `aria-controls`, and `aria-disabled` so assistive technologies see the
+ * correct ARIA tab semantics on the element that is actually focused.
+ * `<nys-tabgroup>` manages `tabindex`, `aria-selected`, and `aria-controls`
+ * via `_applySelection`; do not set them directly on this element.
+ *
+ * @element nys-tab
+ *
+ * @fires nys-tab-select - Dispatched when the tab is activated via click or
+ *   Enter / Space. Bubbles and crosses shadow DOM boundaries.
+ *   `detail: { id: string, label: string }`
+ * @fires nys-tab-focus - Dispatched when the host receives focus. Bubbles and
+ *   crosses shadow DOM boundaries. `detail: { id: string }`
+ * @fires nys-tab-blur - Dispatched when the host loses focus. Bubbles and
+ *   crosses shadow DOM boundaries. `detail: { id: string }`
+ *
+ * @slot - No slots; content is derived from the `label` property.
+ *
+ * @example `<nys-tab>` and `<nys-tabpanel>` should always be wrapped by `<nys-tabgroup>`
+ * ```html
+ * <!-- Always place <nys-tab> elements inside a <nys-tabgroup>. -->
+ * <nys-tabgroup name="My Tabs">
+ *   <nys-tab label="Overview"></nys-tab>
+ *   <nys-tab label="Details" selected></nys-tab>
+ *   <nys-tab label="Archived" disabled></nys-tab>
+ *   <nys-tabpanel><p>Overview content</p></nys-tabpanel>
+ *   <nys-tabpanel><p>Details content (shown by default)</p></nys-tabpanel>
+ *   <nys-tabpanel><p>Archived content</p></nys-tabpanel>
+ * </nys-tabgroup>
+ * ```
+ */
+export declare class NysTab extends LitElement {
+    static styles: import("lit").CSSResult;
+    /**
+     * Unique identifier for the tab element.
+     * Reflected to the DOM attribute so `aria-controls` references resolve.
+     *
+     * @attr id
+     */
+    id: string;
+    /**
+     * Visible text label rendered inside the inner `<span>`.
+     *
+     * @attr label
+     */
+    label: string;
+    /**
+     * Whether this tab is the currently active tab.
+     * Managed by `<nys-tabgroup>`; reflected for CSS attribute selectors.
+     *
+     * @attr selected
+     */
+    selected: boolean;
+    /**
+     * Whether this tab is disabled.
+     * Reflected to the DOM attribute for CSS styling.
+     *
+     * @attr disabled
+     */
+    disabled: boolean;
+    /**
+     * Sets `role="tab"` and `tabindex="-1"` on the host (the element that AT
+     * will read and that receives keyboard focus). Attaches host-level listeners
+     * for keydown, focus, blur, and click so that interaction events work
+     * correctly on the host element itself.
+     *
+     * Click is handled at the host level so iOS VoiceOver double-tap (which
+     * dispatches `click` directly on the host because of `role="tab"`, bypassing
+     * shadow-DOM children) activates the tab. Normal taps land on the inner
+     * `<span>` and bubble up to this listener.
+     *
+     * `<nys-tabgroup>` overrides `tabindex` to `"0"` on the selected tab.
+     */
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    /**
+     * Keeps `aria-disabled` on the host in sync with the `disabled` property so
+     * AT perceives the disabled state on the element it actually focuses.
+     */
+    updated(changed: Map<string, unknown>): void;
+    /**
+     * Focuses the host element. The host carries `role="tab"` and `tabindex`,
+     * so it is the correct element for AT to land on.
+     */
+    focus(options?: FocusOptions): void;
+    /**
+     * Enter / Space on the focused host activate the tab.
+     * Arrow-key navigation is handled one level up by `<nys-tabgroup>`.
+     */
+    private _onKeydown;
+    /**
+     * Host focus → dispatch `nys-tab-focus` for external observers.
+     */
+    private _onFocus;
+    /**
+     * Host blur → dispatch `nys-tab-blur` for external observers.
+     */
+    private _onBlur;
+    /**
+     * Host-level click handler. Activates the tab regardless of whether the
+     * click landed on the inner element (normal pointer/keyboard tap, which
+     * bubbles up) or directly on the host (iOS VoiceOver double-tap dispatches
+     * `click` on the element with `role="tab"`, bypassing shadow-DOM children).
+     */
+    private _onClick;
+    /**
+     * Focuses the host then dispatches `nys-tab-select`. Called from both the
+     * click handler and the keydown handler.
+     */
+    private _handleClick;
+    render(): import("lit-html").TemplateResult<1>;
+}

package/dist/packages/nys-tab/src/nys-tab.figma.d.ts

@@ -0,0 +1 @@
+export {};