@nysds/components 1.17.0 → 1.18.0

package/packages/react/NysRadiogroup.js

@@ -7,7 +7,6 @@ export const NysRadiogroup = forwardRef((props, forwardedRef) => {
     optional,
     showError,
     tile,
-    inverted,
     id,
     name,
     errorMessage,
@@ -40,7 +39,6 @@ export const NysRadiogroup = forwardRef((props, forwardedRef) => {
       optional: props.optional ? true : undefined,
       showError: props.showError ? true : undefined,
       tile: props.tile ? true : undefined,
-      inverted: props.inverted ? true : undefined,
       style: { ...props.style },
     },
     props.children,

package/packages/react/NysTab.d.ts

@@ -0,0 +1,90 @@
+import React from "react";
+import { NysTab as NysTabElement, CustomEvent } from "../../dist/nysds.es.js";
+
+export type { NysTabElement, CustomEvent };
+
+export interface NysTabProps extends Pick<
+  React.AllHTMLAttributes<HTMLElement>,
+  | "children"
+  | "dir"
+  | "hidden"
+  | "id"
+  | "lang"
+  | "slot"
+  | "style"
+  | "title"
+  | "translate"
+  | "onClick"
+  | "onFocus"
+  | "onBlur"
+> {
+  /** 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;
+
+  /** Unique identifier for the tab element.
+Reflected to the DOM attribute so `aria-controls` references resolve. */
+  id?: NysTabElement["id"];
+
+  /** Visible text label rendered inside the inner `<span>`. */
+  label?: NysTabElement["label"];
+
+  /** 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;
+
+  /** Dispatched when the tab is activated via click or Enter / Space. Bubbles and crosses shadow DOM boundaries. `detail: { id: string, label: string }` */
+  onNysTabSelect?: (event: CustomEvent) => void;
+
+  /** Dispatched when the host receives focus. Bubbles and crosses shadow DOM boundaries. `detail: { id: string }` */
+  onNysTabFocus?: (event: CustomEvent) => void;
+
+  /** Dispatched when the host loses focus. Bubbles and crosses shadow DOM boundaries. `detail: { id: string }` */
+  onNysTabBlur?: (event: CustomEvent) => void;
+}
+
+/**
+ * `<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.
+ */
+export const NysTab: React.ForwardRefExoticComponent<NysTabProps>;

package/packages/react/NysTab.js

@@ -0,0 +1,39 @@
+import React, { forwardRef, useRef, useEffect } from "react";
+import "../../dist/nysds.es.js";
+import { useEventListener } from "./react-utils.js";
+
+export const NysTab = forwardRef((props, forwardedRef) => {
+  const ref = useRef(null);
+  const { selected, disabled, id, label, ...filteredProps } = props;
+
+  /** Event listeners - run once */
+  useEventListener(ref, "nys-tab-select", props.onNysTabSelect);
+  useEventListener(ref, "nys-tab-focus", props.onNysTabFocus);
+  useEventListener(ref, "nys-tab-blur", props.onNysTabBlur);
+
+  return React.createElement(
+    "nys-tab",
+    {
+      ref: (node) => {
+        ref.current = node;
+        if (typeof forwardedRef === "function") {
+          forwardedRef(node);
+        } else if (forwardedRef) {
+          forwardedRef.current = node;
+        }
+      },
+      ...filteredProps,
+      id: props.id,
+      label: props.label,
+      class: props.className,
+      exportparts: props.exportparts,
+      for: props.htmlFor,
+      part: props.part,
+      tabindex: props.tabIndex,
+      selected: props.selected ? true : undefined,
+      disabled: props.disabled ? true : undefined,
+      style: { ...props.style },
+    },
+    props.children,
+  );
+});

package/packages/react/NysTabgroup.d.ts

@@ -0,0 +1,75 @@
+import React from "react";
+import { NysTabgroup as NysTabgroupElement } from "../../dist/nysds.es.js";
+
+export type { NysTabgroupElement };
+
+export interface NysTabgroupProps extends Pick<
+  React.AllHTMLAttributes<HTMLElement>,
+  | "children"
+  | "dir"
+  | "hidden"
+  | "id"
+  | "lang"
+  | "slot"
+  | "style"
+  | "title"
+  | "translate"
+  | "onClick"
+  | "onFocus"
+  | "onBlur"
+> {
+  /** Unique identifier for the tabgroup element.
+If not provided, one is auto-generated in `connectedCallback`.
+Reflected to the DOM attribute. */
+  id?: NysTabgroupElement["id"];
+
+  /** The name of the tab group.
+Used for form submission and accessibility purposes. */
+  name?: NysTabgroupElement["name"];
+
+  /** 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;
+}
+
+/**
+ * `<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.
+ */
+export const NysTabgroup: React.ForwardRefExoticComponent<NysTabgroupProps>;

package/packages/react/NysTabgroup.js

@@ -0,0 +1,22 @@
+import React, { forwardRef } from "react";
+import "../../dist/nysds.es.js";
+
+export const NysTabgroup = forwardRef((props, forwardedRef) => {
+  const { id, name, ...filteredProps } = props;
+
+  return React.createElement(
+    "nys-tabgroup",
+    {
+      ...filteredProps,
+      id: props.id,
+      name: props.name,
+      class: props.className,
+      exportparts: props.exportparts,
+      for: props.htmlFor,
+      part: props.part,
+      tabindex: props.tabIndex,
+      style: { ...props.style },
+    },
+    props.children,
+  );
+});

package/packages/react/NysTabpanel.d.ts

@@ -0,0 +1,63 @@
+import React from "react";
+import { NysTabpanel as NysTabpanelElement } from "../../dist/nysds.es.js";
+
+export type { NysTabpanelElement };
+
+export interface NysTabpanelProps extends Pick<
+  React.AllHTMLAttributes<HTMLElement>,
+  | "children"
+  | "dir"
+  | "hidden"
+  | "id"
+  | "lang"
+  | "slot"
+  | "style"
+  | "title"
+  | "translate"
+  | "onClick"
+  | "onFocus"
+  | "onBlur"
+> {
+  /** 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?: NysTabpanelElement["id"];
+
+  /** 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;
+}
+
+/**
+ * `<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.
+ */
+export const NysTabpanel: React.ForwardRefExoticComponent<NysTabpanelProps>;

package/packages/react/NysTabpanel.js

@@ -0,0 +1,21 @@
+import React, { forwardRef } from "react";
+import "../../dist/nysds.es.js";
+
+export const NysTabpanel = forwardRef((props, forwardedRef) => {
+  const { id, ...filteredProps } = props;
+
+  return React.createElement(
+    "nys-tabpanel",
+    {
+      ...filteredProps,
+      id: props.id,
+      class: props.className,
+      exportparts: props.exportparts,
+      for: props.htmlFor,
+      part: props.part,
+      tabindex: props.tabIndex,
+      style: { ...props.style },
+    },
+    props.children,
+  );
+});

package/packages/react/index.d.ts

@@ -29,6 +29,9 @@ export * from "./NysSelect.js";
 export * from "./NysSkipnav.js";
 export * from "./NysStep.js";
 export * from "./NysStepper.js";
+export * from "./NysTab.js";
+export * from "./NysTabgroup.js";
+export * from "./NysTabpanel.js";
 export * from "./NysTable.js";
 export * from "./NysTextarea.js";
 export * from "./NysTextinput.js";

package/packages/react/index.js

@@ -29,6 +29,9 @@ export * from "./NysSelect.js";
 export * from "./NysSkipnav.js";
 export * from "./NysStep.js";
 export * from "./NysStepper.js";
+export * from "./NysTab.js";
+export * from "./NysTabgroup.js";
+export * from "./NysTabpanel.js";
 export * from "./NysTable.js";
 export * from "./NysTextarea.js";
 export * from "./NysTextinput.js";

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" | "";
   /**  */
@@ -275,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). */
@@ -322,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). */
@@ -635,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). */
@@ -683,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). */
@@ -781,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;
@@ -1054,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.
    * ---
    *
    */
@@ -1396,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.