@nysds/components 1.16.1 → 1.18.0

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

@@ -0,0 +1,197 @@
+import { LitElement } from "lit";
+/**
+ * `<nys-tabgroup>` is the container for `<nys-tab>` and `<nys-tabpanel>`
+ * elements.
+ *
+ * Accepts tabs and panels as flat light-DOM children in any order (interleaved
+ * or grouped). On slot change, children are sorted into dedicated shadow-DOM
+ * containers, ARIA relationships are wired, and the first selected (or first)
+ * tab is activated.
+ *
+ * Scroll shadows are rendered on either side of the tab list and toggled via
+ * `ResizeObserver` and a `scroll` listener so they accurately reflect whether
+ * overflow content exists in each direction.
+ *
+ * Keyboard navigation follows the
+ * {@link https://www.w3.org/WAI/ARIA/apg/patterns/tabs/ ARIA Tabs Pattern}:
+ * - Arrow keys move focus without changing selection.
+ * - Enter / Space confirm selection on the focused tab.
+ *
+ * @element nys-tabgroup
+ *
+ * @slot - Accepts `<nys-tab>` and `<nys-tabpanel>` children. Elements are
+ *   moved into internal shadow-DOM containers on `slotchange`; the slot
+ *   itself is not rendered visibly.
+ *
+ * @example Disable a tab using the `disabled` attribute on `<nys-tab>`.
+ * ```html
+ * <nys-tabgroup name="Account Settings">
+ *   <nys-tab label="Profile"></nys-tab>
+ *   <nys-tab label="Security"></nys-tab>
+ *   <nys-tab label="Notifications" disabled></nys-tab>
+ *   <nys-tabpanel><p>Manage your profile information.</p></nys-tabpanel>
+ *   <nys-tabpanel><p>Update your password and 2FA settings.</p></nys-tabpanel>
+ *   <nys-tabpanel><p>Notification preferences (coming soon).</p></nys-tabpanel>
+ * </nys-tabgroup>
+ * ```
+ *
+ * @example Pre-select a tab using the `selected` attribute on `<nys-tab>`.
+ * ```html
+ * <nys-tabgroup name="Reports">
+ *   <nys-tab label="Summary"></nys-tab>
+ *   <nys-tab label="Details" selected></nys-tab>
+ *   <nys-tabpanel><p>Summary view</p></nys-tabpanel>
+ *   <nys-tabpanel><p>Detailed view (shown by default)</p></nys-tabpanel>
+ * </nys-tabgroup>
+ * ```
+ */
+export declare class NysTabgroup extends LitElement {
+    static styles: import("lit").CSSResult;
+    /**
+     * Unique identifier for the tabgroup element.
+     * If not provided, one is auto-generated in `connectedCallback`.
+     * Reflected to the DOM attribute.
+     *
+     * @attr id
+     */
+    id: string;
+    /**
+     * The name of the tab group.
+     * Used for form submission and accessibility purposes.
+     *
+     * @attr name
+     */
+    name: string;
+    /**
+     * Cached in `firstUpdated` and used by `_updateScrollShadows` to read
+     * scroll position and dimensions.
+     */
+    private _tabsEl;
+    /**
+     * Reference to the left scroll-shadow overlay element.
+     * Receives the `is-visible` class when the tab list is scrolled away from
+     * its leftmost position.
+     */
+    private _shadowLeft;
+    /**
+     * Reference to the right scroll-shadow overlay element.
+     * Receives the `is-visible` class when overflow content exists to the right
+     * of the current scroll position.
+     */
+    private _shadowRight;
+    /**
+     * `ResizeObserver` instance watching `_tabsEl` for size changes.
+     * Re-evaluates scroll shadow visibility whenever the tab list is resized
+     * (e.g. viewport resize, dynamic tab additions).
+     * Stored so it can be disconnected if needed.
+     */
+    private _resizeObserver?;
+    /**
+     * Called when the element is inserted into the document.
+     * Auto-generates a unique `id` if one was not provided.
+     */
+    connectedCallback(): void;
+    /**
+     * Called after the element's shadow DOM has been rendered for the first time.
+     *
+     * Caches references to the tab list and scroll-shadow elements, performs an
+     * initial scroll-shadow evaluation, and attaches:
+     * - A `scroll` event listener on `_tabsEl` to update shadows on scroll.
+     * - A `ResizeObserver` on `_tabsEl` to update shadows when the container
+     *   is resized.
+     */
+    firstUpdated(): void;
+    /**
+     * Reads the current scroll state of `_tabsEl` and toggles the `is-visible`
+     * class on the left and right shadow overlays accordingly.
+     *
+     * - Left shadow is visible when `scrollLeft > 0`.
+     * - Right shadow is visible when `scrollLeft + clientWidth < scrollWidth`
+     *   (i.e. content exists beyond the right edge).
+     *
+     * Defined as an arrow function so it can be passed directly as an event
+     * listener without losing `this` context.
+     *
+     * @returns void
+     */
+    private _updateScrollShadows;
+    /**
+     * Returns all `<nys-tab>` elements currently residing in the shadow-DOM
+     * tabs container, in DOM order.
+     *
+     * @returns An array of `HTMLElement` references to every `<nys-tab>` child.
+     */
+    private _getTabs;
+    /**
+     * Returns all `<nys-tabpanel>` elements currently residing in the
+     * shadow-DOM panels container, in DOM order.
+     *
+     * @returns An array of `HTMLElement` references to every `<nys-tabpanel>` child.
+     */
+    private _getPanels;
+    /**
+     * Single source of truth for ARIA wiring, `tabindex`, and panel visibility.
+     *
+     * For each index `i`:
+     * - Sets `selected` / removes `selected` attribute on `tabs[i]`.
+     * - Sets `aria-controls` on `tabs[i]` to the `id` of `panels[i]`.
+     * - Sets `aria-labelledby` on `panels[i]` to the `id` of `tabs[i]`.
+     * - Removes `hidden` from `panels[selectedIndex]`; adds it to all others.
+     *
+     * Must be called any time the selected tab changes (initial render and
+     * subsequent user interactions).
+     *
+     * @param tabs - Ordered array of `<nys-tab>` elements to update.
+     * @param panels - Ordered array of `<nys-tabpanel>` elements to update.
+     *   Must be the same length as `tabs` for correct pairing.
+     * @param selectedIndex - Zero-based index of the tab/panel pair to activate.
+     * @returns void
+     */
+    private _applySelection;
+    /**
+     * Handles `slotchange` on the default slot.
+     *
+     * Iterates over all assigned elements and moves each `<nys-tab>` into
+     * `.nys-tabgroup__tabs` and each `<nys-tabpanel>` into
+     * `.nys-tabgroup__panels`, preserving relative order. After sorting,
+     * calls `_applySelection` using the first element that already has a
+     * `selected` attribute, or index `0` if none is found.
+     *
+     * @param e - The `Event` fired by the `<slot>` element on slot change.
+     * @returns void
+     */
+    private _sortChildren;
+    /**
+     * Handles the `nys-tab-select` custom event bubbled up from a child
+     * `<nys-tab>`.
+     *
+     * Resolves the originating `<nys-tab>` via `composedPath()` (required
+     * because the event crosses shadow DOM boundaries), determines its index
+     * among the current tab list, and delegates to `_applySelection`.
+     *
+     * @param e - The `Event` (cast to `CustomEvent`) dispatched by `<nys-tab>`.
+     * @returns void
+     */
+    private _handleTabSelect;
+    /**
+     * Implements the ARIA radio-button keyboard pattern:
+     * - `ArrowRight` — moves focus to the next enabled tab (wraps).
+     * - `ArrowLeft` — moves focus to the previous enabled tab (wraps).
+     *
+     * Focus is moved without changing selection; Enter / Space on the newly
+     * focused tab (handled by `<nys-tab>._handleKeydown`) confirm selection.
+     *
+     * The currently focused tab is resolved via `composedPath()` because focus
+     * may sit on a shadow-DOM descendant of `<nys-tab>` rather than the host
+     * itself.
+     *
+     * Disabled tabs are excluded from navigation and will never receive focus
+     * via arrow keys.
+     *
+     * @param e - The `KeyboardEvent` from the tablist `keydown` listener.
+     * @returns void
+     */
+    private _handleKeydown;
+    private _handleWheel;
+    render(): import("lit-html").TemplateResult<1>;
+}

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

@@ -0,0 +1,46 @@
+import { LitElement } from "lit";
+/**
+ * `<nys-tabpanel>` is a content panel paired with a `<nys-tab>` inside a
+ * `<nys-tabgroup>`.
+ *
+ * Pairing is determined by render order: the Nth `<nys-tabpanel>` child of a
+ * `<nys-tabgroup>` corresponds to the Nth `<nys-tab>` child.
+ * `aria-labelledby` and the `hidden` attribute are managed externally by
+ * `<nys-tabgroup>` via `_applySelection`; do not set them directly.
+ *
+ * @element nys-tabpanel
+ *
+ * @slot - Default slot for panel content. Rendered inside a wrapper `<div>`
+ *   with the `.nys-tabpanel` class for styling.
+ *
+ * @example Panel content is wrapped by `<nys-tabpanel>`.
+ * ```html
+ * <!-- Panels are paired by position with <nys-tab> elements in the same <nys-tabgroup>. -->
+ * <nys-tabgroup name="Steps">
+ *   <nys-tab label="Step 1"></nys-tab>
+ *   <nys-tab label="Step 2"></nys-tab>
+ *   <nys-tabpanel>
+ *     <h2>Step 1: Enter your information</h2>
+ *     <p>Fill out the form below.</p>
+ *   </nys-tabpanel>
+ *   <nys-tabpanel>
+ *     <h2>Step 2: Review and submit</h2>
+ *     <p>Confirm your details before submitting.</p>
+ *   </nys-tabpanel>
+ * </nys-tabgroup>
+ * ```
+ */
+export declare class NysTabpanel extends LitElement {
+    static styles: import("lit").CSSResult;
+    /**
+     * Unique identifier for the panel element.
+     * If not provided, one is auto-generated in `connectedCallback`.
+     * Reflected to the DOM attribute so `aria-controls` references on sibling
+     * `<nys-tab>` elements resolve correctly.
+     *
+     * @attr id
+     */
+    id: string;
+    connectedCallback(): void;
+    render(): import("lit-html").TemplateResult<1>;
+}

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

@@ -22,19 +22,22 @@ export declare class NysTable extends LitElement {
     private _sortColumn;
     private _sortDirection;
     private _captionText;
+    private _observer;
     /**************** Lifecycle Methods ****************/
     constructor();
     connectedCallback(): void;
-    /******************** Functions ********************/
     firstUpdated(): void;
-    _handleSlotChange(): void;
-    _normalizeTableDOM(table: HTMLTableElement): void;
+    disconnectedCallback(): void;
     willUpdate(): void;
-    _addSortIcons(table: HTMLTableElement): void;
-    _updateSortIcons(table: HTMLTableElement): void;
+    /******************** Functions ********************/
+    private _handleSlotChange;
+    private _setupMutationObserver;
+    private _normalizeTableDOM;
+    private _addSortIcons;
+    private _updateSortIcons;
     private _onSortClick;
-    _sortTable(table: HTMLTableElement, columnIndex: number, direction: "asc" | "desc"): void;
-    _updateSortedColumnStyles(table: HTMLTableElement): void;
+    private _sortTable;
+    private _updateSortedColumnStyles;
     downloadFile(): void;
     /****************** Event Handlers ******************/
     /**

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

@@ -83,7 +83,6 @@ export declare class NysTextarea extends LitElement {
     showError: boolean;
     /** Error message text. Shown only when `showError` is true. */
     errorMessage: string;
-    updated(changedProperties: Map<string | number | symbol, unknown>): Promise<void>;
     private _hasUserInteracted;
     private _internals;
     /**
@@ -95,6 +94,7 @@ export declare class NysTextarea extends LitElement {
     connectedCallback(): void;
     disconnectedCallback(): void;
     firstUpdated(): void;
+    updated(changedProperties: Map<string | number | symbol, unknown>): Promise<void>;
     /**
      * Form Integration
      * --------------------------------------------------------------------------

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

@@ -101,6 +101,7 @@ export declare class NysTextinput extends LitElement {
     showError: boolean;
     /** Error message text. Shown only when `showError` is true. */
     errorMessage: string;
+    private _inputEl;
     private showPassword;
     private _originalErrorMessage;
     private _hasUserInteracted;
@@ -114,7 +115,7 @@ export declare class NysTextinput extends LitElement {
     constructor();
     connectedCallback(): void;
     disconnectedCallback(): void;
-    firstUpdated(): void;
+    firstUpdated(): Promise<void>;
     updated(changedProperties: Map<string | number | symbol, unknown>): Promise<void>;
     /**
      * Form Integration

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

@@ -5,6 +5,27 @@ declare global {
         onYouTubeIframeAPIReady: () => void;
     }
 }
+/**
+ * A YouTube video player with a thumbnail preview and play button.
+ * Loads the iframe only after the user clicks play, keeping initial page load light.
+ * Supports autoplay (muted), custom thumbnails, start time, lazy loading, and disabled state.
+ * Announces playback state and ad state to screen readers via a live region.
+ *
+ * For use with YouTube URLs only. Component renders nothing if the URL is invalid.
+ *
+ * @summary YouTube video player with thumbnail preview and accessibility announcements.
+ * @element nys-video
+ *
+ * @fires nys-video-play - Fired when the user clicks the thumbnail to load the player.
+ *
+ * @example Basic usage
+ * ```html
+ * <nys-video
+ *   videourl="https://www.youtube.com/watch?v=dQw4w9WgXcQ"
+ *   titleText="Video Title"
+ * ></nys-video>
+ * ```
+ */
 export declare class NysVideo extends LitElement {
     static styles: import("lit").CSSResult;
     /** Full YouTube URL — required. Component will not render if invalid. */
@@ -36,6 +57,10 @@ export declare class NysVideo extends LitElement {
     private _announcement;
     /** Tracks whether an ad is currently playing to suppress false "Video is playing" announcements */
     private _adPlaying;
+    /**
+     * Lifecycle methods
+     * --------------------------------------------------------------------------
+     */
     constructor();
     connectedCallback(): void;
     disconnectedCallback(): void;

package/dist/src/index.d.ts

@@ -2,6 +2,7 @@ export * from "../packages/nys-accordion/src/index";
 export * from "../packages/nys-alert/src/index";
 export * from "../packages/nys-avatar/src/index";
 export * from "../packages/nys-backtotop/src/index";
+export * from "../packages/nys-breadcrumbs/src/index";
 export * from "../packages/nys-button/src/index";
 export * from "../packages/nys-badge/src/index";
 export * from "../packages/nys-checkbox/src/index";
@@ -19,6 +20,7 @@ export * from "../packages/nys-radiobutton/src/index";
 export * from "../packages/nys-select/src/index";
 export * from "../packages/nys-skipnav/src/index";
 export * from "../packages/nys-stepper/src/index";
+export * from "../packages/nys-tab/src/index";
 export * from "../packages/nys-table/src/index";
 export * from "../packages/nys-textarea/src/index";
 export * from "../packages/nys-textinput/src/index";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nysds/components",
-  "version": "1.16.1",
+  "version": "1.18.0",
   "description": "New York State's design system and code component library.",
   "type": "module",
   "workspaces": [
@@ -53,7 +53,8 @@
     "mcp-server:build": "turbo run build --filter=@nysds/mcp-server",
     "clean:node": "rm -rf node_modules && rm -rf packages/*/node_modules && rm -rf packages/**/*/node_modules",
     "clean:dist": "rm -rf storybook-static && rm -rf coverage && rm -rf packages/*/coverage && rm -rf dist && find packages -type d -name dist ! -path '*/mcp-server/dist' -exec rm -rf {} + 2>/dev/null || true",
-    "clean:all": "npm run clean:dist && npm run clean:node && find packages -name '*.tsbuildinfo' -delete 2>/dev/null || true",
+    "clean:turbo": "find packages -type d -name '.turbo' -exec rm -rf {} + && rm -rf .turbo",
+    "clean:all": "npm run clean:dist && npm run clean:node && find packages -name '*.tsbuildinfo' -delete 2>/dev/null || true && npm run clean:turbo",
     "code-connect": "dotenv -- npx figma connect publish",
     "cem": "npx cem analyze --config ./custom-elements-manifest.config.mjs && cp ./custom-elements.json dist/ && node src/scripts/patch-react-utils.js"
   },

package/packages/react/NysBacktotop.d.ts

@@ -47,7 +47,7 @@ export interface NysBacktotopProps extends Pick<
 }
 
 /**
- * Floating back-to-top button with auto-show behavior and smooth scroll.
+ * Floating back-to-top button with auto-show behavior, smooth scroll, and focus management.
  * ---
  *
  */

package/packages/react/NysBadge.d.ts

@@ -42,6 +42,9 @@ export interface NysBadgeProps extends Pick<
   /** Primary label text displayed in the badge. */
   label?: NysBadgeElement["label"];
 
+  /** Screen reader text appended after the label for additional context. */
+  srText?: NysBadgeElement["srText"];
+
   /** undefined */
   variant?: NysBadgeElement["variant"];
 

package/packages/react/NysBadge.js

@@ -11,6 +11,7 @@ export const NysBadge = forwardRef((props, forwardedRef) => {
     intent,
     prefixLabel,
     label,
+    srText,
     variant,
     ...filteredProps
   } = props;
@@ -25,6 +26,7 @@ export const NysBadge = forwardRef((props, forwardedRef) => {
       intent: props.intent,
       prefixLabel: props.prefixLabel,
       label: props.label,
+      srText: props.srText,
       variant: props.variant,
       class: props.className,
       exportparts: props.exportparts,

package/packages/react/NysBreadcrumbItem.d.ts

@@ -0,0 +1,72 @@
+import React from "react";
+import {
+  NysBreadcrumbItem as NysBreadcrumbItemElement,
+  CustomEvent,
+} from "../../dist/nysds.es.js";
+
+export type { NysBreadcrumbItemElement, CustomEvent };
+
+export interface NysBreadcrumbItemProps extends Pick<
+  React.AllHTMLAttributes<HTMLElement>,
+  | "children"
+  | "dir"
+  | "hidden"
+  | "id"
+  | "lang"
+  | "slot"
+  | "style"
+  | "title"
+  | "translate"
+  | "onClick"
+  | "onFocus"
+  | "onBlur"
+> {
+  /** Private property used by nys-breadcrumbs to indicate this breadcrumb item is the last in the trail * */
+  isLast?: boolean;
+
+  /** undefined */
+  isBackToParent?: boolean;
+
+  /** undefined */
+  id?: NysBreadcrumbItemElement["id"];
+
+  /** undefined */
+  label?: NysBreadcrumbItemElement["label"];
+
+  /** undefined */
+  link?: NysBreadcrumbItemElement["link"];
+
+  /** A space-separated list of the classes of the element. Classes allows CSS and JavaScript to select and access specific elements via the class selectors or functions like the method `Document.getElementsByClassName()`. */
+  className?: string;
+
+  /** Contains a space-separated list of the part names of the element that should be exposed on the host element. */
+  exportparts?: string;
+
+  /** Used for labels to link them with their inputs (using input id). */
+  htmlFor?: string;
+
+  /** Used to help React identify which items have changed, are added, or are removed within a list. */
+  key?: number | string;
+
+  /** Contains a space-separated list of the part names of the element. Part names allows CSS to select and style specific elements in a shadow tree via the ::part pseudo-element. */
+  part?: string;
+
+  /** A mutable ref object whose `.current` property is initialized to the passed argument (`initialValue`). The returned object will persist for the full lifetime of the component. */
+  ref?: any;
+
+  /** Allows developers to make HTML elements focusable, allow or prevent them from being sequentially focusable (usually with the `Tab` key, hence the name) and determine their relative ordering for sequential focus navigation. */
+  tabIndex?: number;
+
+  /** Fired when the link is clicked. Detail: `{id, link}`. */
+  onNysBreadcrumbitemClick?: (event: CustomEvent) => void;
+}
+
+/**
+ * Single breadcrumb trail item with chevron separator and current page support.
+ * ---
+ *
+ *
+ * ### **Events:**
+ *  - **nys-breadcrumbitem-click** - Fired when the link is clicked. Detail: `{id, link}`.
+ */
+export const NysBreadcrumbItem: React.ForwardRefExoticComponent<NysBreadcrumbItemProps>;

package/packages/react/NysBreadcrumbItem.js

@@ -0,0 +1,42 @@
+import React, { forwardRef, useRef, useEffect } from "react";
+import "../../dist/nysds.es.js";
+import { useEventListener } from "./react-utils.js";
+
+export const NysBreadcrumbItem = forwardRef((props, forwardedRef) => {
+  const ref = useRef(null);
+  const { isLast, isBackToParent, id, label, link, ...filteredProps } = props;
+
+  /** Event listeners - run once */
+  useEventListener(
+    ref,
+    "nys-breadcrumbitem-click",
+    props.onNysBreadcrumbitemClick,
+  );
+
+  return React.createElement(
+    "nys-breadcrumbitem",
+    {
+      ref: (node) => {
+        ref.current = node;
+        if (typeof forwardedRef === "function") {
+          forwardedRef(node);
+        } else if (forwardedRef) {
+          forwardedRef.current = node;
+        }
+      },
+      ...filteredProps,
+      id: props.id,
+      label: props.label,
+      link: props.link,
+      class: props.className,
+      exportparts: props.exportparts,
+      for: props.htmlFor,
+      part: props.part,
+      tabindex: props.tabIndex,
+      isLast: props.isLast ? true : undefined,
+      isBackToParent: props.isBackToParent ? true : undefined,
+      style: { ...props.style },
+    },
+    props.children,
+  );
+});

package/packages/react/NysBreadcrumbs.d.ts

@@ -0,0 +1,89 @@
+import React from "react";
+import {
+  NysBreadcrumbs as NysBreadcrumbsElement,
+  CustomEvent,
+} from "../../dist/nysds.es.js";
+
+export type { NysBreadcrumbsElement, CustomEvent };
+
+export interface NysBreadcrumbsProps extends Pick<
+  React.AllHTMLAttributes<HTMLElement>,
+  | "children"
+  | "dir"
+  | "hidden"
+  | "id"
+  | "lang"
+  | "slot"
+  | "style"
+  | "title"
+  | "translate"
+  | "onClick"
+  | "onFocus"
+  | "onBlur"
+> {
+  /** 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). */
+  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. */
+  collapsed?: boolean;
+
+  /** Renders a filled light theme background bar behind the breadcrumb trail. */
+  backgroundBar?: boolean;
+
+  /** Prevents interaction. */
+  disabled?: boolean;
+
+  /** Unique identifier. Auto-generated if not provided. */
+  id?: NysBreadcrumbsElement["id"];
+
+  /** 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?: NysBreadcrumbsElement["ariaLabel"];
+
+  /** Controls the visual size of the breadcrumb text and spacing: `sm` for dense layouts, `md` (default) for standard use. */
+  size?: NysBreadcrumbsElement["size"];
+
+  /** A space-separated list of the classes of the element. Classes allows CSS and JavaScript to select and access specific elements via the class selectors or functions like the method `Document.getElementsByClassName()`. */
+  className?: string;
+
+  /** Contains a space-separated list of the part names of the element that should be exposed on the host element. */
+  exportparts?: string;
+
+  /** Used for labels to link them with their inputs (using input id). */
+  htmlFor?: string;
+
+  /** Used to help React identify which items have changed, are added, or are removed within a list. */
+  key?: number | string;
+
+  /** Contains a space-separated list of the part names of the element. Part names allows CSS to select and style specific elements in a shadow tree via the ::part pseudo-element. */
+  part?: string;
+
+  /** A mutable ref object whose `.current` property is initialized to the passed argument (`initialValue`). The returned object will persist for the full lifetime of the component. */
+  ref?: any;
+
+  /** Allows developers to make HTML elements focusable, allow or prevent them from being sequentially focusable (usually with the `Tab` key, hence the name) and determine their relative ordering for sequential focus navigation. */
+  tabIndex?: number;
+
+  /** undefined */
+  onNysExpand?: (event: CustomEvent) => void;
+
+  /** Fired when the user clicks the ellipsis to expand the trail. */
+  onNysBreadcrumbsExpand?: (event: CustomEvent) => void;
+}
+
+/**
+ * Breadcrumb navigation trail with responsive collapse support.
+ * ---
+ *
+ *
+ * ### **Events:**
+ *  - **nys-expand**
+ * - **nys-breadcrumbs-expand** - Fired when the user clicks the ellipsis to expand the trail.
+ *
+ * ### **Slots:**
+ *  - _default_ - One or more `nys-breadcrumbitem` elements defining the trail.
+ */
+export const NysBreadcrumbs: React.ForwardRefExoticComponent<NysBreadcrumbsProps>;

package/packages/react/NysBreadcrumbs.js

@@ -0,0 +1,50 @@
+import React, { forwardRef, useRef, useEffect } from "react";
+import "../../dist/nysds.es.js";
+import { useEventListener } from "./react-utils.js";
+
+export const NysBreadcrumbs = forwardRef((props, forwardedRef) => {
+  const ref = useRef(null);
+  const {
+    backToParent,
+    collapsed,
+    backgroundBar,
+    disabled,
+    id,
+    ariaLabel,
+    size,
+    ...filteredProps
+  } = props;
+
+  /** Event listeners - run once */
+  useEventListener(ref, "nys-expand", props.onNysExpand);
+  useEventListener(ref, "nys-breadcrumbs-expand", props.onNysBreadcrumbsExpand);
+
+  return React.createElement(
+    "nys-breadcrumbs",
+    {
+      ref: (node) => {
+        ref.current = node;
+        if (typeof forwardedRef === "function") {
+          forwardedRef(node);
+        } else if (forwardedRef) {
+          forwardedRef.current = node;
+        }
+      },
+      ...filteredProps,
+      id: props.id,
+      ariaLabel: props.ariaLabel,
+      size: props.size,
+      class: props.className,
+      exportparts: props.exportparts,
+      for: props.htmlFor,
+      part: props.part,
+      tabindex: props.tabIndex,
+      backToParent: props.backToParent ? true : undefined,
+      collapsed: props.collapsed ? true : undefined,
+      backgroundBar: props.backgroundBar ? true : undefined,
+      disabled: props.disabled ? true : undefined,
+      style: { ...props.style },
+    },
+    props.children,
+  );
+});