@nysds/components 1.16.1 → 1.18.0

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

@@ -163,6 +163,8 @@ export type NysBadgeProps = {
   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" | "";
   /**  */
@@ -171,6 +173,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 +218,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;
@@ -249,8 +277,6 @@ export type NysCheckboxProps = {
   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;
   /** Checkbox size: `sm` (24px) or `md` (32px, default). */
@@ -296,8 +322,6 @@ export type NysCheckboxgroupProps = {
   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;
   /** Checkbox size for all children: `sm` (24px) or `md` (32px, default). */
@@ -425,6 +449,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 +563,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 +575,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 = {
@@ -604,8 +633,6 @@ export type NysRadiobuttonProps = {
   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;
   /** Radio size: `sm` (24px) or `md` (32px, default). */
@@ -652,8 +679,6 @@ export type NysRadiogroupProps = {
   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;
   /** Radio size for all children: `sm` (24px) or `md` (32px, default). */
@@ -750,6 +775,45 @@ export type NysStepperProps = {
   isCompactExpanded?: boolean;
 };
 
+export type NysTabProps = {
+  /** Unique identifier for the tab element.
+Reflected to the DOM attribute so `aria-controls` references resolve. */
+  id?: string;
+  /** Visible text label rendered inside the inner `<span>`. */
+  label?: string;
+  /** Whether this tab is the currently active tab.
+Managed by `<nys-tabgroup>`; reflected for CSS attribute selectors. */
+  selected?: boolean;
+  /** Whether this tab is disabled.
+Reflected to the DOM attribute for CSS styling. */
+  disabled?: boolean;
+
+  /** Dispatched when the tab is activated via click or Enter / Space. Bubbles and crosses shadow DOM boundaries. `detail: { id: string, label: string }` */
+  "onnys-tab-select"?: (e: CustomEvent<CustomEvent>) => void;
+  /** Dispatched when the host receives focus. Bubbles and crosses shadow DOM boundaries. `detail: { id: string }` */
+  "onnys-tab-focus"?: (e: CustomEvent<never>) => void;
+  /** Dispatched when the host loses focus. Bubbles and crosses shadow DOM boundaries. `detail: { id: string }` */
+  "onnys-tab-blur"?: (e: CustomEvent<never>) => void;
+};
+
+export type NysTabgroupProps = {
+  /** Unique identifier for the tabgroup element.
+If not provided, one is auto-generated in `connectedCallback`.
+Reflected to the DOM attribute. */
+  id?: string;
+  /** The name of the tab group.
+Used for form submission and accessibility purposes. */
+  name?: string;
+};
+
+export type NysTabpanelProps = {
+  /** 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. */
+  id?: string;
+};
+
 export type NysTableProps = {
   /**  */
   id?: string;
@@ -965,6 +1029,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 = {
@@ -1020,7 +1087,7 @@ export type CustomElements = {
   "nys-avatar": Partial<NysAvatarProps & BaseProps & BaseEvents>;
 
   /**
-   * 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.
    * ---
    *
    */
@@ -1033,6 +1100,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 +1305,9 @@ export type CustomElements = {
    * ---
    *
    *
+   * ### **Events:**
+   *  - **nys-label-click**
+   *
    * ### **Slots:**
    *  - **description** - Custom HTML description content below the label.
    */
@@ -1345,6 +1429,72 @@ export type CustomElements = {
    */
   "nys-stepper": Partial<NysStepperProps & BaseProps & BaseEvents>;
 
+  /**
+   * `<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.
+   * ---
+   *
+   *
+   * ### **Events:**
+   *  - **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 }`
+   * - **nys-tab-focus** - Dispatched when the host receives focus. Bubbles and crosses shadow DOM boundaries. `detail: { id: string }`
+   * - **nys-tab-blur** - Dispatched when the host loses focus. Bubbles and crosses shadow DOM boundaries. `detail: { id: string }`
+   *
+   * ### **Methods:**
+   *  - **focus(options: _FocusOptions_): _void_** - Focuses the host element. The host carries `role="tab"` and `tabindex`,
+   * so it is the correct element for AT to land on.
+   *
+   * ### **Slots:**
+   *  - _default_ - No slots; content is derived from the `label` property.
+   */
+  "nys-tab": Partial<NysTabProps & BaseProps & BaseEvents>;
+
+  /**
+   * `<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
+   * 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.
+   * ---
+   *
+   *
+   * ### **Slots:**
+   *  - _default_ - Accepts `<nys-tab>` and `<nys-tabpanel>` children. Elements are moved into internal shadow-DOM containers on `slotchange`; the slot itself is not rendered visibly.
+   */
+  "nys-tabgroup": Partial<NysTabgroupProps & BaseProps & BaseEvents>;
+
+  /**
+   * `<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.
+   * ---
+   *
+   *
+   * ### **Slots:**
+   *  - _default_ - Default slot for panel content. Rendered inside a wrapper `<div>` with the `.nys-tabpanel` class for styling.
+   */
+  "nys-tabpanel": Partial<NysTabpanelProps & BaseProps & BaseEvents>;
+
   /**
    * `<nys-table>` is a responsive table component that can display native HTML tables,
    * supports striped and bordered styling, sortable columns, and CSV download.
@@ -1439,9 +1589,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>;
 };