@nysds/components 1.16.1 → 1.17.0

package/packages/react/NysLabel.d.ts

@@ -1,7 +1,10 @@
 import React from "react";
-import { NysLabel as NysLabelElement } from "../../dist/nysds.es.js";
+import {
+  NysLabel as NysLabelElement,
+  CustomEvent,
+} from "../../dist/nysds.es.js";
 
-export type { NysLabelElement };
+export type { NysLabelElement, CustomEvent };
 
 export interface NysLabelProps extends Pick<
   React.AllHTMLAttributes<HTMLElement>,
@@ -21,8 +24,8 @@ export interface NysLabelProps extends Pick<
   /** Adjusts colors for dark backgrounds. */
   inverted?: boolean;
 
-  /** ID of the form element this label is associated with. */
-  for?: NysLabelElement["for"];
+  /** The ID of the label. */
+  id?: NysLabelElement["id"];
 
   /** Label text displayed above the form field. */
   label?: NysLabelElement["label"];
@@ -42,6 +45,9 @@ export interface NysLabelProps extends Pick<
   /** 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;
 
@@ -53,6 +59,9 @@ export interface NysLabelProps extends Pick<
 
   /** 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 */
+  onNysLabelClick?: (event: CustomEvent) => void;
 }
 
 /**
@@ -60,6 +69,9 @@ export interface NysLabelProps extends Pick<
  * ---
  *
  *
+ * ### **Events:**
+ *  - **nys-label-click**
+ *
  * ### **Slots:**
  *  - **description** - Custom HTML description content below the label.
  */

package/packages/react/NysLabel.js

@@ -1,21 +1,35 @@
-import React, { forwardRef } from "react";
+import React, { forwardRef, useRef, useEffect } from "react";
 import "../../dist/nysds.es.js";
+import { useEventListener } from "./react-utils.js";
 
 export const NysLabel = forwardRef((props, forwardedRef) => {
-  const { inverted, label, description, flag, tooltip, ...filteredProps } =
+  const ref = useRef(null);
+  const { inverted, id, label, description, flag, tooltip, ...filteredProps } =
     props;
 
+  /** Event listeners - run once */
+  useEventListener(ref, "nys-label-click", props.onNysLabelClick);
+
   return React.createElement(
     "nys-label",
     {
+      ref: (node) => {
+        ref.current = node;
+        if (typeof forwardedRef === "function") {
+          forwardedRef(node);
+        } else if (forwardedRef) {
+          forwardedRef.current = node;
+        }
+      },
       ...filteredProps,
-      for: props.for,
+      id: props.id,
       label: props.label,
       description: props.description,
       flag: props.flag,
       tooltip: props.tooltip,
       class: props.className,
       exportparts: props.exportparts,
+      for: props.htmlFor,
       part: props.part,
       tabindex: props.tabIndex,
       inverted: props.inverted ? true : undefined,

package/packages/react/NysVideo.d.ts

@@ -67,11 +67,17 @@ Falls back to YouTube's auto-generated thumbnail if not provided. */
 
   /** 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 user clicks the thumbnail to load the player. */
+  onNysVideoPlay?: (event: CustomEvent) => void;
 }
 
 /**
- *
+ * YouTube video player with thumbnail preview and accessibility announcements.
  * ---
  *
+ *
+ * ### **Events:**
+ *  - **nys-video-play** - Fired when the user clicks the thumbnail to load the player.
  */
 export const NysVideo: React.ForwardRefExoticComponent<NysVideoProps>;

package/packages/react/NysVideo.js

@@ -1,7 +1,9 @@
-import React, { forwardRef } from "react";
+import React, { forwardRef, useRef, useEffect } from "react";
 import "../../dist/nysds.es.js";
+import { useEventListener } from "./react-utils.js";
 
 export const NysVideo = forwardRef((props, forwardedRef) => {
+  const ref = useRef(null);
   const {
     autoplay,
     disabled,
@@ -15,9 +17,20 @@ export const NysVideo = forwardRef((props, forwardedRef) => {
     ...filteredProps
   } = props;
 
+  /** Event listeners - run once */
+  useEventListener(ref, "nys-video-play", props.onNysVideoPlay);
+
   return React.createElement(
     "nys-video",
     {
+      ref: (node) => {
+        ref.current = node;
+        if (typeof forwardedRef === "function") {
+          forwardedRef(node);
+        } else if (forwardedRef) {
+          forwardedRef.current = node;
+        }
+      },
       ...filteredProps,
       id: props.id,
       titleText: props.titleText,

package/packages/react/index.d.ts

@@ -4,6 +4,7 @@ export * from "./NysAlert.js";
 export * from "./NysAvatar.js";
 export * from "./NysBacktotop.js";
 export * from "./NysBadge.js";
+export * from "./NysBreadcrumbs.js";
 export * from "./NysButton.js";
 export * from "./NysCheckbox.js";
 export * from "./NysCheckboxgroup.js";

package/packages/react/index.js

@@ -4,6 +4,7 @@ export * from "./NysAlert.js";
 export * from "./NysAvatar.js";
 export * from "./NysBacktotop.js";
 export * from "./NysBadge.js";
+export * from "./NysBreadcrumbs.js";
 export * from "./NysButton.js";
 export * from "./NysCheckbox.js";
 export * from "./NysCheckboxgroup.js";

package/packages/react/nysds-jsx.d.ts

@@ -171,6 +171,32 @@ export type NysBadgeProps = {
   suffixicon?: string | boolean;
 };
 
+export type NysBreadcrumbsProps = {
+  /** 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. */
+  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). */
+  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;
+
+  /**  */
+  "onnys-expand"?: (e: CustomEvent<CustomEvent>) => void;
+  /** Fired when the user clicks the ellipsis to expand the trail. */
+  "onnys-breadcrumbs-expand"?: (e: CustomEvent<never>) => void;
+};
+
 export type NysButtonProps = {
   /** Unique identifier. Auto-generated if not provided. */
   id?: string;
@@ -190,9 +216,9 @@ export type NysButtonProps = {
   ariaLabel?: string;
   /** ID of controlled element (e.g., dropdown or modal). Sets `aria-controls`. */
   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;
   /** Renders circular icon-only button. Requires `icon` prop. `label` becomes aria-label. */
   circle?: boolean;
@@ -425,6 +451,8 @@ export type NysDropdownMenuItemProps = {
 };
 
 export type NysErrorMessageProps = {
+  /** 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. */
@@ -537,8 +565,8 @@ export type NysIconProps = {
 };
 
 export type NysLabelProps = {
-  /** 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. */
@@ -549,6 +577,9 @@ export type NysLabelProps = {
   inverted?: boolean;
   /** Tooltip text shown on hover/focus of info icon next to label. */
   tooltip?: string;
+
+  /**  */
+  "onnys-label-click"?: (e: CustomEvent<CustomEvent>) => void;
 };
 
 export type NysModalProps = {
@@ -965,6 +996,9 @@ Falls back to YouTube's auto-generated thumbnail if not provided. */
   autoplay?: boolean;
   /** Prevents the video from being played */
   disabled?: boolean;
+
+  /** Fired when the user clicks the thumbnail to load the player. */
+  "onnys-video-play"?: (e: CustomEvent<never>) => void;
 };
 
 export type CustomElements = {
@@ -1033,6 +1067,20 @@ export type CustomElements = {
    */
   "nys-badge": Partial<NysBadgeProps & BaseProps & BaseEvents>;
 
+  /**
+   * 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.
+   */
+  "nys-breadcrumbs": Partial<NysBreadcrumbsProps & BaseProps & BaseEvents>;
+
   /**
    * Button for actions and CTAs with variants, sizes, and icon support.
    * ---
@@ -1224,6 +1272,9 @@ export type CustomElements = {
    * ---
    *
    *
+   * ### **Events:**
+   *  - **nys-label-click**
+   *
    * ### **Slots:**
    *  - **description** - Custom HTML description content below the label.
    */
@@ -1439,9 +1490,12 @@ export type CustomElements = {
   "nys-unavheader": Partial<NysUnavHeaderProps & BaseProps & BaseEvents>;
 
   /**
-   *
+   * YouTube video player with thumbnail preview and accessibility announcements.
    * ---
    *
+   *
+   * ### **Events:**
+   *  - **nys-video-play** - Fired when the user clicks the thumbnail to load the player.
    */
   "nys-video": Partial<NysVideoProps & BaseProps & BaseEvents>;
 };