@nysds/components 1.14.0 → 1.15.1

package/packages/react/NysBadge.d.ts

@@ -0,0 +1,75 @@
+import React from "react";
+import { NysBadge as NysBadgeElement } from "../../dist/nysds.es.js";
+
+export type { NysBadgeElement };
+
+export interface NysBadgeProps extends Pick<
+  React.AllHTMLAttributes<HTMLElement>,
+  | "children"
+  | "dir"
+  | "hidden"
+  | "id"
+  | "lang"
+  | "slot"
+  | "style"
+  | "title"
+  | "translate"
+  | "onClick"
+  | "onFocus"
+  | "onBlur"
+> {
+  /** undefined */
+  prefixIcon?: string | boolean;
+
+  /** undefined */
+  suffixIcon?: string | boolean;
+
+  /** Unique identifier. */
+  id?: NysBadgeElement["id"];
+
+  /** Name attribute for form association. */
+  name?: NysBadgeElement["name"];
+
+  /** Badge size: `sm` (smaller text) or `md` (default). */
+  size?: NysBadgeElement["size"];
+
+  /** Semantic intent affecting color: `neutral`, `error`, `success`, or `warning`. */
+  intent?: NysBadgeElement["intent"];
+
+  /** Secondary label displayed before the main label. */
+  prefixLabel?: NysBadgeElement["prefixLabel"];
+
+  /** Primary label text displayed in the badge. */
+  label?: NysBadgeElement["label"];
+
+  /** undefined */
+  variant?: NysBadgeElement["variant"];
+
+  /** 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;
+}
+
+/**
+ * Compact label for status, counts, or categorization with semantic styling.
+ * ---
+ *
+ */
+export const NysBadge: React.ForwardRefExoticComponent<NysBadgeProps>;

package/packages/react/NysBadge.js

@@ -0,0 +1,40 @@
+import React, { forwardRef } from "react";
+import "../../dist/nysds.es.js";
+
+export const NysBadge = forwardRef((props, forwardedRef) => {
+  const {
+    prefixIcon,
+    suffixIcon,
+    id,
+    name,
+    size,
+    intent,
+    prefixLabel,
+    label,
+    variant,
+    ...filteredProps
+  } = props;
+
+  return React.createElement(
+    "nys-badge",
+    {
+      ...filteredProps,
+      id: props.id,
+      name: props.name,
+      size: props.size,
+      intent: props.intent,
+      prefixLabel: props.prefixLabel,
+      label: props.label,
+      variant: props.variant,
+      class: props.className,
+      exportparts: props.exportparts,
+      for: props.htmlFor,
+      part: props.part,
+      tabindex: props.tabIndex,
+      prefixicon: props.prefixIcon ? true : undefined,
+      suffixicon: props.suffixIcon ? true : undefined,
+      style: { ...props.style },
+    },
+    props.children,
+  );
+});

package/packages/react/NysButton.d.ts

@@ -0,0 +1,141 @@
+import React from "react";
+import { NysButton as NysButtonElement, Event } from "../../dist/nysds.es.js";
+
+export type { NysButtonElement, Event };
+
+export interface NysButtonProps extends Pick<
+  React.AllHTMLAttributes<HTMLElement>,
+  | "children"
+  | "dir"
+  | "hidden"
+  | "id"
+  | "lang"
+  | "slot"
+  | "style"
+  | "title"
+  | "translate"
+  | "onClick"
+  | "onFocus"
+  | "onBlur"
+> {
+  /** Expands button to fill container width. Use for mobile layouts or stacked button groups. */
+  fullWidth?: boolean;
+
+  /** Adjusts colors for dark backgrounds. */
+  inverted?: boolean;
+
+  /** Renders circular icon-only button. Requires `icon` prop. `label` becomes aria-label. */
+  circle?: boolean;
+
+  /** Prevents interaction. Avoid disabling without explanation—show validation errors instead. */
+  disabled?: boolean;
+
+  /** Unique identifier. Auto-generated if not provided. */
+  id?: NysButtonElement["id"];
+
+  /** Name for form submission. */
+  name?: NysButtonElement["name"];
+
+  /** Button height: `sm` (40px) for dense UIs, `md` (48px, default) for standard use, `lg` (56px) for prominent CTAs. */
+  size?: NysButtonElement["size"];
+
+  /** Visual style: `filled` for primary (one per section), `outline` for secondary, `ghost` for tertiary, `text` for inline actions. Avoid `text` for navigation. */
+  variant?: NysButtonElement["variant"];
+
+  /** Visible button text. Use sentence case, action-oriented text (e.g., "Save Draft"). Becomes aria-label in `circle` mode. */
+  label?: NysButtonElement["label"];
+
+  /** Screen reader label. Required for icon-only buttons if `label` is not set. */
+  ariaLabel?: NysButtonElement["ariaLabel"];
+
+  /** ID of controlled element (e.g., dropdown or modal). Sets `aria-controls`. */
+  ariaControls?: NysButtonElement["ariaControls"];
+
+  /** Material Symbol icon before label. Not shown for `text` variant or `circle` mode. */
+  prefixIcon?: NysButtonElement["prefixIcon"];
+
+  /** Material Symbol icon after label. Use `chevron_down` for dropdowns, `open_in_new` for external links. Not shown for `text` variant or `circle` mode. */
+  suffixIcon?: NysButtonElement["suffixIcon"];
+
+  /** Icon for circle mode. Required when `circle` is true. Scales with size (sm=24px, md=32px, lg=40px). */
+  icon?: NysButtonElement["icon"];
+
+  /** Form `id` to associate with. Use when button is outside the form element. */
+  form?: NysButtonElement["form"];
+
+  /** Value submitted with form data. Only used when `type="submit"`. */
+  value?: NysButtonElement["value"];
+
+  /** Additional screen reader description. Sets `aria-description`. */
+  ariaDescription?: NysButtonElement["ariaDescription"];
+
+  /** Form behavior: `button` (default, no form action), `submit` (submits form), `reset` (resets form). Always set explicitly to avoid unintended submissions. */
+  type?: NysButtonElement["type"];
+
+  /** URL to navigate to. Renders as `<a>` tag. Omit for action buttons. */
+  href?: NysButtonElement["href"];
+
+  /** Link target: `_self` (same tab), `_blank` (new tab—add `suffixIcon="open_in_new"`), `_parent`, `_top`, or frame name. */
+  target?: NysButtonElement["target"];
+
+  /** 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;
+
+  /** Click handler. Use instead of `@click` to ensure keyboard accessibility. */
+  onClick?: NysButtonElement["onClick"];
+
+  /** Fired when the button receives focus. */
+  onNysFocus?: (event: CustomEvent) => void;
+
+  /** Fired when the button loses focus. */
+  onNysBlur?: (event: CustomEvent) => void;
+
+  /** Fired when the button is clicked (mouse or keyboard). Not fired when disabled. */
+  onNysClick?: (event: CustomEvent) => void;
+}
+
+/**
+ * Button for actions and CTAs with variants, sizes, and icon support.
+ * ---
+ *
+ *
+ * ### **Events:**
+ *  - **nys-focus** - Fired when the button receives focus.
+ * - **nys-blur** - Fired when the button loses focus.
+ * - **nys-click** - Fired when the button is clicked (mouse or keyboard). Not fired when disabled.
+ *
+ * ### **Slots:**
+ *  - **prefix-icon** - Icon before label. Not shown for `text` variant.
+ * - **suffix-icon** - Icon after label. Not shown for `text` variant.
+ * - **circle-icon** - Icon for circle mode. Overrides `icon` prop.
+ *
+ * ### **CSS Properties:**
+ *  - **--nys-button-color** - Text color of the button label. _(default: undefined)_
+ * - **--nys-button-color--hover** - Text color when hovered. _(default: undefined)_
+ * - **--nys-button-color--active** - Text color when active/pressed. _(default: undefined)_
+ * - **--nys-button-background-color** - Background color of the button. _(default: undefined)_
+ * - **--nys-button-background-color--hover** - Background color when hovered. _(default: undefined)_
+ * - **--nys-button-background-color--active** - Background color when active/pressed. _(default: undefined)_
+ * - **--nys-button-border-color** - Border color of the button. _(default: undefined)_
+ * - **--nys-button-border-color--hover** - Border color when hovered. _(default: undefined)_
+ * - **--nys-button-border-color--active** - Border color when active/pressed. _(default: undefined)_
+ */
+export const NysButton: React.ForwardRefExoticComponent<NysButtonProps>;

package/packages/react/NysButton.js

@@ -0,0 +1,81 @@
+import React, { forwardRef, useRef, useEffect } from "react";
+import "../../dist/nysds.es.js";
+import { useEventListener, useProperties } from "./react-utils.js";
+
+export const NysButton = forwardRef((props, forwardedRef) => {
+  const ref = useRef(null);
+  const {
+    fullWidth,
+    inverted,
+    circle,
+    disabled,
+    id,
+    name,
+    size,
+    variant,
+    label,
+    ariaLabel,
+    ariaControls,
+    prefixIcon,
+    suffixIcon,
+    icon,
+    form,
+    value,
+    ariaDescription,
+    type,
+    href,
+    target,
+    onClick,
+    ...filteredProps
+  } = props;
+
+  /** Event listeners - run once */
+  useEventListener(ref, "nys-focus", props.onNysFocus);
+  useEventListener(ref, "nys-blur", props.onNysBlur);
+  useEventListener(ref, "nys-click", props.onNysClick);
+
+  /** Properties - run whenever a property has changed */
+  useProperties(ref, "onClick", props.onClick);
+
+  return React.createElement(
+    "nys-button",
+    {
+      ref: (node) => {
+        ref.current = node;
+        if (typeof forwardedRef === "function") {
+          forwardedRef(node);
+        } else if (forwardedRef) {
+          forwardedRef.current = node;
+        }
+      },
+      ...filteredProps,
+      id: props.id,
+      name: props.name,
+      size: props.size,
+      variant: props.variant,
+      label: props.label,
+      ariaLabel: props.ariaLabel,
+      ariaControls: props.ariaControls,
+      prefixIcon: props.prefixIcon,
+      suffixIcon: props.suffixIcon,
+      icon: props.icon,
+      form: props.form,
+      value: props.value,
+      ariaDescription: props.ariaDescription,
+      type: props.type,
+      href: props.href,
+      target: props.target,
+      class: props.className,
+      exportparts: props.exportparts,
+      for: props.htmlFor,
+      part: props.part,
+      tabindex: props.tabIndex,
+      fullWidth: props.fullWidth ? true : undefined,
+      inverted: props.inverted ? true : undefined,
+      circle: props.circle ? true : undefined,
+      disabled: props.disabled ? true : undefined,
+      style: { ...props.style },
+    },
+    props.children,
+  );
+});

package/packages/react/NysCheckbox.d.ts

@@ -0,0 +1,139 @@
+import React from "react";
+import {
+  NysCheckbox as NysCheckboxElement,
+  CustomEvent,
+  Event,
+} from "../../dist/nysds.es.js";
+
+export type { NysCheckboxElement, CustomEvent, Event };
+
+export interface NysCheckboxProps extends Pick<
+  React.AllHTMLAttributes<HTMLElement>,
+  | "children"
+  | "dir"
+  | "hidden"
+  | "id"
+  | "lang"
+  | "slot"
+  | "style"
+  | "title"
+  | "translate"
+  | "onClick"
+  | "onFocus"
+  | "onBlur"
+> {
+  /** Whether checkbox is checked. */
+  checked?: boolean;
+
+  /** Prevents interaction. */
+  disabled?: boolean;
+
+  /** Marks as required. Validates that checkbox is checked. */
+  required?: boolean;
+
+  /** Shows error message when true. */
+  showError?: boolean;
+
+  /** Internal: Set by parent checkboxgroup. Do not set manually. */
+  groupExist?: boolean;
+
+  /** Renders as tile with larger clickable area. Apply to group for consistency. */
+  tile?: boolean;
+
+  /** Adjusts colors for dark backgrounds. */
+  inverted?: boolean;
+
+  /** undefined */
+  other?: boolean;
+
+  /** undefined */
+  showOtherError?: boolean;
+
+  /** Visible label text. Required for accessibility. */
+  label?: NysCheckboxElement["label"];
+
+  /** Helper text below label. Use slot for custom HTML. */
+  description?: NysCheckboxElement["description"];
+
+  /** Unique identifier. Auto-generated if not provided. */
+  id?: NysCheckboxElement["id"];
+
+  /** Name for form submission. Use same name for grouped checkboxes. */
+  name?: NysCheckboxElement["name"];
+
+  /** Value submitted when checked. */
+  value?: NysCheckboxElement["value"];
+
+  /** Form `id` to associate with when checkbox is outside form element. */
+  form?: NysCheckboxElement["form"];
+
+  /** Error message text. Shown only when `showError` is true. */
+  errorMessage?: NysCheckboxElement["errorMessage"];
+
+  /** Tooltip text shown on hover/focus of info icon. */
+  tooltip?: NysCheckboxElement["tooltip"];
+
+  /** Checkbox size: `sm` (24px) or `md` (32px, default). */
+  size?: NysCheckboxElement["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;
+
+  /** Fired when checked state changes. Detail: `{id, checked, name, value}`. */
+  onNysChange?: (event: CustomEvent) => void;
+
+  /** Fired when "other" text input value changes. Detail: `{id, name, value}`. */
+  onNysOtherInput?: (event: CustomEvent) => void;
+
+  /** Fired when checkbox gains focus. */
+  onNysFocus?: (event: CustomEvent) => void;
+
+  /** Fired when checkbox loses focus. */
+  onNysBlur?: (event: CustomEvent) => void;
+
+  /** undefined */
+  onNysError?: (event: CustomEvent) => void;
+
+  /** undefined */
+  onNysErrorClear?: (event: CustomEvent) => void;
+}
+
+/**
+ * Checkbox for binary choices or multi-select options.
+ * ---
+ *
+ *
+ * ### **Events:**
+ *  - **nys-change** - Fired when checked state changes. Detail: `{id, checked, name, value}`.
+ * - **nys-other-input** - Fired when "other" text input value changes. Detail: `{id, name, value}`.
+ * - **nys-focus** - Fired when checkbox gains focus.
+ * - **nys-blur** - Fired when checkbox loses focus.
+ * - **nys-error**
+ * - **nys-error-clear**
+ *
+ * ### **Methods:**
+ *  - **checkValidity(): _boolean_** - Functions
+ * --------------------------------------------------------------------------
+ *
+ * ### **Slots:**
+ *  - **description** - Custom HTML description content.
+ */
+export const NysCheckbox: React.ForwardRefExoticComponent<NysCheckboxProps>;

package/packages/react/NysCheckbox.js

@@ -0,0 +1,76 @@
+import React, { forwardRef, useRef, useEffect } from "react";
+import "../../dist/nysds.es.js";
+import { useEventListener } from "./react-utils.js";
+
+export const NysCheckbox = forwardRef((props, forwardedRef) => {
+  const ref = useRef(null);
+  const {
+    checked,
+    disabled,
+    required,
+    showError,
+    groupExist,
+    tile,
+    inverted,
+    other,
+    showOtherError,
+    label,
+    description,
+    id,
+    name,
+    value,
+    form,
+    errorMessage,
+    tooltip,
+    size,
+    ...filteredProps
+  } = props;
+
+  /** Event listeners - run once */
+  useEventListener(ref, "nys-change", props.onNysChange);
+  useEventListener(ref, "nys-other-input", props.onNysOtherInput);
+  useEventListener(ref, "nys-focus", props.onNysFocus);
+  useEventListener(ref, "nys-blur", props.onNysBlur);
+  useEventListener(ref, "nys-error", props.onNysError);
+  useEventListener(ref, "nys-error-clear", props.onNysErrorClear);
+
+  return React.createElement(
+    "nys-checkbox",
+    {
+      ref: (node) => {
+        ref.current = node;
+        if (typeof forwardedRef === "function") {
+          forwardedRef(node);
+        } else if (forwardedRef) {
+          forwardedRef.current = node;
+        }
+      },
+      ...filteredProps,
+      label: props.label,
+      description: props.description,
+      id: props.id,
+      name: props.name,
+      value: props.value,
+      form: props.form,
+      errorMessage: props.errorMessage,
+      tooltip: props.tooltip,
+      size: props.size,
+      class: props.className,
+      exportparts: props.exportparts,
+      for: props.htmlFor,
+      part: props.part,
+      tabindex: props.tabIndex,
+      checked: props.checked ? true : undefined,
+      disabled: props.disabled ? true : undefined,
+      required: props.required ? true : undefined,
+      showError: props.showError ? true : undefined,
+      groupExist: props.groupExist ? true : undefined,
+      tile: props.tile ? true : undefined,
+      inverted: props.inverted ? true : undefined,
+      other: props.other ? true : undefined,
+      showOtherError: props.showOtherError ? true : undefined,
+      style: { ...props.style },
+    },
+    props.children,
+  );
+});

package/packages/react/NysCheckboxgroup.d.ts

@@ -0,0 +1,91 @@
+import React from "react";
+import { NysCheckboxgroup as NysCheckboxgroupElement } from "../../dist/nysds.es.js";
+
+export type { NysCheckboxgroupElement };
+
+export interface NysCheckboxgroupProps extends Pick<
+  React.AllHTMLAttributes<HTMLElement>,
+  | "children"
+  | "dir"
+  | "hidden"
+  | "id"
+  | "lang"
+  | "slot"
+  | "style"
+  | "title"
+  | "translate"
+  | "onClick"
+  | "onFocus"
+  | "onBlur"
+> {
+  /** Requires at least one checkbox to be checked. */
+  required?: boolean;
+
+  /** Shows "Optional" flag. */
+  optional?: boolean;
+
+  /** Shows error message when true. */
+  showError?: boolean;
+
+  /** Renders all checkboxes as tiles with larger clickable area. */
+  tile?: boolean;
+
+  /** Adjusts colors for dark backgrounds. Applied to all children. */
+  inverted?: boolean;
+
+  /** Unique identifier. Auto-generated if not provided. */
+  id?: NysCheckboxgroupElement["id"];
+
+  /** Name for form submission. Set on group, not individual checkboxes. */
+  name?: NysCheckboxgroupElement["name"];
+
+  /** Error message text. Shown only when `showError` is true. */
+  errorMessage?: NysCheckboxgroupElement["errorMessage"];
+
+  /** Visible label text for the group. */
+  label?: NysCheckboxgroupElement["label"];
+
+  /** Helper text below label. Use slot for custom HTML. */
+  description?: NysCheckboxgroupElement["description"];
+
+  /** Tooltip text shown on hover/focus of info icon. */
+  tooltip?: NysCheckboxgroupElement["tooltip"];
+
+  /** Form `id` to associate with. Applied to all children. */
+  form?: NysCheckboxgroupElement["form"];
+
+  /** Checkbox size for all children: `sm` (24px) or `md` (32px, default). */
+  size?: NysCheckboxgroupElement["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;
+}
+
+/**
+ * Container for grouping checkboxes as a single form control.
+ * ---
+ *
+ *
+ * ### **Slots:**
+ *  - _default_ - Default slot for `nys-checkbox` elements.
+ * - **description** - Custom HTML description content.
+ */
+export const NysCheckboxgroup: React.ForwardRefExoticComponent<NysCheckboxgroupProps>;

package/packages/react/NysCheckboxgroup.js

@@ -0,0 +1,48 @@
+import React, { forwardRef } from "react";
+import "../../dist/nysds.es.js";
+
+export const NysCheckboxgroup = forwardRef((props, forwardedRef) => {
+  const {
+    required,
+    optional,
+    showError,
+    tile,
+    inverted,
+    id,
+    name,
+    errorMessage,
+    label,
+    description,
+    tooltip,
+    form,
+    size,
+    ...filteredProps
+  } = props;
+
+  return React.createElement(
+    "nys-checkboxgroup",
+    {
+      ...filteredProps,
+      id: props.id,
+      name: props.name,
+      errorMessage: props.errorMessage,
+      label: props.label,
+      description: props.description,
+      tooltip: props.tooltip,
+      form: props.form,
+      size: props.size,
+      class: props.className,
+      exportparts: props.exportparts,
+      for: props.htmlFor,
+      part: props.part,
+      tabindex: props.tabIndex,
+      required: props.required ? true : undefined,
+      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,
+  );
+});