@nysds/components 1.15.0 → 1.15.1

package/packages/react/NysTable.d.ts

@@ -0,0 +1,80 @@
+import React from "react";
+import { NysTable as NysTableElement } from "../../dist/nysds.es.js";
+
+export type { NysTableElement };
+
+export interface NysTableProps extends Pick<
+  React.AllHTMLAttributes<HTMLElement>,
+  | "children"
+  | "dir"
+  | "hidden"
+  | "id"
+  | "lang"
+  | "slot"
+  | "style"
+  | "title"
+  | "translate"
+  | "onClick"
+  | "onFocus"
+  | "onBlur"
+> {
+  /** undefined */
+  striped?: boolean;
+
+  /** undefined */
+  sortable?: boolean;
+
+  /** undefined */
+  bordered?: boolean;
+
+  /** undefined */
+  id?: NysTableElement["id"];
+
+  /** undefined */
+  name?: NysTableElement["name"];
+
+  /** undefined */
+  download?: NysTableElement["download"];
+
+  /** 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 download button or sortable headers are clicked. */
+  onNysClick?: (event: CustomEvent) => void;
+
+  /** Fired when a sortable column header is clicked.  Can be prevented by calling `event.preventDefault()` to override default sort behavior. Detail: { columnIndex: number, columnLabel: string, sortDirection: "asc" | "desc" | "none" } */
+  onNysColumnSort?: (event: CustomEvent) => void;
+}
+
+/**
+ * `<nys-table>` is a responsive table component that can display native HTML tables,
+ * supports striped and bordered styling, sortable columns, and CSV download.
+ * ---
+ *
+ *
+ * ### **Events:**
+ *  - **nys-click** - Fired when the download button or sortable headers are clicked.
+ * - **nys-column-sort** - Fired when a sortable column header is clicked.  Can be prevented by calling `event.preventDefault()` to override default sort behavior. Detail: { columnIndex: number, columnLabel: string, sortDirection: "asc" | "desc" | "none" }
+ *
+ * ### **Slots:**
+ *  - _default_ - Accepts a `<table>` element. Only the first table is rendered.
+ */
+export const NysTable: React.ForwardRefExoticComponent<NysTableProps>;

package/packages/react/NysTable.js

@@ -0,0 +1,41 @@
+import React, { forwardRef, useRef, useEffect } from "react";
+import "../../dist/nysds.es.js";
+import { useEventListener } from "./react-utils.js";
+
+export const NysTable = forwardRef((props, forwardedRef) => {
+  const ref = useRef(null);
+  const { striped, sortable, bordered, id, name, download, ...filteredProps } =
+    props;
+
+  /** Event listeners - run once */
+  useEventListener(ref, "nys-click", props.onNysClick);
+  useEventListener(ref, "nys-column-sort", props.onNysColumnSort);
+
+  return React.createElement(
+    "nys-table",
+    {
+      ref: (node) => {
+        ref.current = node;
+        if (typeof forwardedRef === "function") {
+          forwardedRef(node);
+        } else if (forwardedRef) {
+          forwardedRef.current = node;
+        }
+      },
+      ...filteredProps,
+      id: props.id,
+      name: props.name,
+      download: props.download,
+      class: props.className,
+      exportparts: props.exportparts,
+      for: props.htmlFor,
+      part: props.part,
+      tabindex: props.tabIndex,
+      striped: props.striped ? true : undefined,
+      sortable: props.sortable ? true : undefined,
+      bordered: props.bordered ? true : undefined,
+      style: { ...props.style },
+    },
+    props.children,
+  );
+});

package/packages/react/NysTextarea.d.ts

@@ -0,0 +1,138 @@
+import React from "react";
+import {
+  NysTextarea as NysTextareaElement,
+  CustomEvent,
+  Event,
+} from "../../dist/nysds.es.js";
+
+export type { NysTextareaElement, CustomEvent, Event };
+
+export interface NysTextareaProps extends Pick<
+  React.AllHTMLAttributes<HTMLElement>,
+  | "children"
+  | "dir"
+  | "hidden"
+  | "id"
+  | "lang"
+  | "slot"
+  | "style"
+  | "title"
+  | "translate"
+  | "onClick"
+  | "onFocus"
+  | "onBlur"
+> {
+  /** Prevents interaction. */
+  disabled?: boolean;
+
+  /** Makes textarea read-only but focusable. */
+  readonly?: boolean;
+
+  /** Marks as required. Shows "Required" flag and validates on blur. */
+  required?: boolean;
+
+  /** Shows "Optional" flag. Use when most fields are required. */
+  optional?: boolean;
+
+  /** Adjusts colors for dark backgrounds. */
+  inverted?: boolean;
+
+  /** Shows error message when true. Set by validation or manually. */
+  showError?: boolean;
+
+  /** Unique identifier. Auto-generated if not provided. */
+  id?: NysTextareaElement["id"];
+
+  /** Name for form submission. */
+  name?: NysTextareaElement["name"];
+
+  /** Visible label text. Required for accessibility. */
+  label?: NysTextareaElement["label"];
+
+  /** Helper text below label. Use slot for custom HTML. */
+  description?: NysTextareaElement["description"];
+
+  /** Placeholder text. Don't use as label replacement. */
+  placeholder?: NysTextareaElement["placeholder"];
+
+  /** Current textarea value. */
+  value?: NysTextareaElement["value"];
+
+  /** Tooltip text shown on hover/focus of info icon. */
+  tooltip?: NysTextareaElement["tooltip"];
+
+  /** Form `id` to associate with when textarea is outside form element. */
+  form?: NysTextareaElement["form"];
+
+  /** Maximum character length. */
+  maxlength?: NysTextareaElement["maxlength"];
+
+  /** Textarea width: `sm` (88px), `md` (200px), `lg` (384px), `full` (100%, default). */
+  width?: NysTextareaElement["width"];
+
+  /** Visible height in lines. */
+  rows?: NysTextareaElement["rows"];
+
+  /** Resize behavior: `vertical` (default, user can resize height), `none` (fixed size). */
+  resize?: NysTextareaElement["resize"];
+
+  /** Error message text. Shown only when `showError` is true. */
+  errorMessage?: NysTextareaElement["errorMessage"];
+
+  /** 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 on input change. Detail: `{id, value}`. */
+  onNysInput?: (event: CustomEvent) => void;
+
+  /** Fired when textarea gains focus. */
+  onNysFocus?: (event: CustomEvent) => void;
+
+  /** Fired when textarea loses focus. Triggers validation. */
+  onNysBlur?: (event: CustomEvent) => void;
+
+  /** Fired when user selects text. Detail: `{id, value}`. */
+  onNysSelect?: (event: CustomEvent) => void;
+
+  /** undefined */
+  onNysSelectionchange?: (event: CustomEvent) => void;
+}
+
+/**
+ * Multi-line text input for comments, descriptions, and feedback.
+ * ---
+ *
+ *
+ * ### **Events:**
+ *  - **nys-input** - Fired on input change. Detail: `{id, value}`.
+ * - **nys-focus** - Fired when textarea gains focus.
+ * - **nys-blur** - Fired when textarea loses focus. Triggers validation.
+ * - **nys-select** - Fired when user selects text. Detail: `{id, value}`.
+ * - **nys-selectionchange**
+ *
+ * ### **Methods:**
+ *  - **checkValidity(): _boolean_** - Functions
+ * --------------------------------------------------------------------------
+ *
+ * ### **Slots:**
+ *  - **description** - Custom HTML description content below the label.
+ */
+export const NysTextarea: React.ForwardRefExoticComponent<NysTextareaProps>;

package/packages/react/NysTextarea.js

@@ -0,0 +1,77 @@
+import React, { forwardRef, useRef, useEffect } from "react";
+import "../../dist/nysds.es.js";
+import { useEventListener } from "./react-utils.js";
+
+export const NysTextarea = forwardRef((props, forwardedRef) => {
+  const ref = useRef(null);
+  const {
+    disabled,
+    readonly,
+    required,
+    optional,
+    inverted,
+    showError,
+    id,
+    name,
+    label,
+    description,
+    placeholder,
+    value,
+    tooltip,
+    form,
+    maxlength,
+    width,
+    rows,
+    resize,
+    errorMessage,
+    ...filteredProps
+  } = props;
+
+  /** Event listeners - run once */
+  useEventListener(ref, "nys-input", props.onNysInput);
+  useEventListener(ref, "nys-focus", props.onNysFocus);
+  useEventListener(ref, "nys-blur", props.onNysBlur);
+  useEventListener(ref, "nys-select", props.onNysSelect);
+  useEventListener(ref, "nys-selectionchange", props.onNysSelectionchange);
+
+  return React.createElement(
+    "nys-textarea",
+    {
+      ref: (node) => {
+        ref.current = node;
+        if (typeof forwardedRef === "function") {
+          forwardedRef(node);
+        } else if (forwardedRef) {
+          forwardedRef.current = node;
+        }
+      },
+      ...filteredProps,
+      id: props.id,
+      name: props.name,
+      label: props.label,
+      description: props.description,
+      placeholder: props.placeholder,
+      value: props.value,
+      tooltip: props.tooltip,
+      form: props.form,
+      maxlength: props.maxlength,
+      width: props.width,
+      rows: props.rows,
+      resize: props.resize,
+      errorMessage: props.errorMessage,
+      class: props.className,
+      exportparts: props.exportparts,
+      for: props.htmlFor,
+      part: props.part,
+      tabindex: props.tabIndex,
+      disabled: props.disabled ? true : undefined,
+      readonly: props.readonly ? true : undefined,
+      required: props.required ? true : undefined,
+      optional: props.optional ? true : undefined,
+      inverted: props.inverted ? true : undefined,
+      showError: props.showError ? true : undefined,
+      style: { ...props.style },
+    },
+    props.children,
+  );
+});

package/packages/react/NysTextinput.d.ts

@@ -0,0 +1,144 @@
+import React from "react";
+import {
+  NysTextinput as NysTextinputElement,
+  CustomEvent,
+  Event,
+} from "../../dist/nysds.es.js";
+
+export type { NysTextinputElement, CustomEvent, Event };
+
+export interface NysTextinputProps extends Pick<
+  React.AllHTMLAttributes<HTMLElement>,
+  | "children"
+  | "dir"
+  | "hidden"
+  | "id"
+  | "lang"
+  | "slot"
+  | "style"
+  | "title"
+  | "translate"
+  | "onClick"
+  | "onFocus"
+  | "onBlur"
+> {
+  /** Prevents interaction. */
+  disabled?: boolean;
+
+  /** Makes input read-only but focusable. */
+  readonly?: boolean;
+
+  /** Marks as required. Shows "Required" flag and validates on blur. */
+  required?: boolean;
+
+  /** Shows "Optional" flag. Use when most fields are required. */
+  optional?: boolean;
+
+  /** Adjusts colors for dark backgrounds. */
+  inverted?: boolean;
+
+  /** Shows error message when true. Set by validation or manually. */
+  showError?: boolean;
+
+  /** Unique identifier. Auto-generated if not provided. */
+  id?: NysTextinputElement["id"];
+
+  /** Name for form submission. */
+  name?: NysTextinputElement["name"];
+
+  /** Input type: `text` (default), `email`, `number`, `password`, `search`, `tel` (auto-masked), `url`. */
+  type?: NysTextinputElement["type"];
+
+  /** Visible label text. Required for accessibility. */
+  label?: NysTextinputElement["label"];
+
+  /** Helper text below label. Use slot for custom HTML. */
+  description?: NysTextinputElement["description"];
+
+  /** Placeholder text. Don't use as label replacement. */
+  placeholder?: NysTextinputElement["placeholder"];
+
+  /** Current input value. */
+  value?: NysTextinputElement["value"];
+
+  /** Tooltip text shown on hover/focus of info icon. */
+  tooltip?: NysTextinputElement["tooltip"];
+
+  /** Form `id` to associate with when input is outside form element. */
+  form?: NysTextinputElement["form"];
+
+  /** Regex pattern for validation. Shows error on mismatch. */
+  pattern?: NysTextinputElement["pattern"];
+
+  /** Maximum character length. */
+  maxlength?: NysTextinputElement["maxlength"];
+
+  /** Accessible label. When set, assuming "label" isn't provided for private special cases (i.e., <checkbox other>). */
+  ariaLabel?: NysTextinputElement["ariaLabel"];
+
+  /** Input width: `sm` (88px), `md` (200px), `lg` (384px), `full` (100%, default). */
+  width?: NysTextinputElement["width"];
+
+  /** Step increment for `type="number"`. */
+  step?: NysTextinputElement["step"];
+
+  /** Minimum value for `type="number"`. */
+  min?: NysTextinputElement["min"];
+
+  /** Maximum value for `type="number"`. */
+  max?: NysTextinputElement["max"];
+
+  /** Error message text. Shown only when `showError` is true. */
+  errorMessage?: NysTextinputElement["errorMessage"];
+
+  /** 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 on input change. Detail: `{id, value}`. */
+  onNysInput?: (event: CustomEvent) => void;
+
+  /** Fired when input gains focus. */
+  onNysFocus?: (event: CustomEvent) => void;
+
+  /** Fired when input loses focus. Triggers validation. */
+  onNysBlur?: (event: CustomEvent) => void;
+}
+
+/**
+ * Text input for short single-line data with validation and masking support.
+ * ---
+ *
+ *
+ * ### **Events:**
+ *  - **nys-input** - Fired on input change. Detail: `{id, value}`.
+ * - **nys-focus** - Fired when input gains focus.
+ * - **nys-blur** - Fired when input loses focus. Triggers validation.
+ *
+ * ### **Methods:**
+ *  - **checkValidity(): _boolean_** - Functions
+ * --------------------------------------------------------------------------
+ *
+ * ### **Slots:**
+ *  - **description** - Custom HTML description content below the label.
+ * - **startButton** - Button at input start. Use single `nys-button` only.
+ * - **endButton** - Button at input end. Use single `nys-button` only.
+ */
+export const NysTextinput: React.ForwardRefExoticComponent<NysTextinputProps>;

package/packages/react/NysTextinput.js

@@ -0,0 +1,83 @@
+import React, { forwardRef, useRef, useEffect } from "react";
+import "../../dist/nysds.es.js";
+import { useEventListener } from "./react-utils.js";
+
+export const NysTextinput = forwardRef((props, forwardedRef) => {
+  const ref = useRef(null);
+  const {
+    disabled,
+    readonly,
+    required,
+    optional,
+    inverted,
+    showError,
+    id,
+    name,
+    type,
+    label,
+    description,
+    placeholder,
+    value,
+    tooltip,
+    form,
+    pattern,
+    maxlength,
+    ariaLabel,
+    width,
+    step,
+    min,
+    max,
+    errorMessage,
+    ...filteredProps
+  } = props;
+
+  /** Event listeners - run once */
+  useEventListener(ref, "nys-input", props.onNysInput);
+  useEventListener(ref, "nys-focus", props.onNysFocus);
+  useEventListener(ref, "nys-blur", props.onNysBlur);
+
+  return React.createElement(
+    "nys-textinput",
+    {
+      ref: (node) => {
+        ref.current = node;
+        if (typeof forwardedRef === "function") {
+          forwardedRef(node);
+        } else if (forwardedRef) {
+          forwardedRef.current = node;
+        }
+      },
+      ...filteredProps,
+      id: props.id,
+      name: props.name,
+      type: props.type,
+      label: props.label,
+      description: props.description,
+      placeholder: props.placeholder,
+      value: props.value,
+      tooltip: props.tooltip,
+      form: props.form,
+      pattern: props.pattern,
+      maxlength: props.maxlength,
+      ariaLabel: props.ariaLabel,
+      width: props.width,
+      step: props.step,
+      min: props.min,
+      max: props.max,
+      errorMessage: props.errorMessage,
+      class: props.className,
+      exportparts: props.exportparts,
+      for: props.htmlFor,
+      part: props.part,
+      tabindex: props.tabIndex,
+      disabled: props.disabled ? true : undefined,
+      readonly: props.readonly ? true : undefined,
+      required: props.required ? true : undefined,
+      optional: props.optional ? true : undefined,
+      inverted: props.inverted ? true : undefined,
+      showError: props.showError ? true : undefined,
+      style: { ...props.style },
+    },
+    props.children,
+  );
+});

package/packages/react/NysToggle.d.ts

@@ -0,0 +1,102 @@
+import React from "react";
+import {
+  NysToggle as NysToggleElement,
+  CustomEvent,
+  Event,
+} from "../../dist/nysds.es.js";
+
+export type { NysToggleElement, CustomEvent, Event };
+
+export interface NysToggleProps extends Pick<
+  React.AllHTMLAttributes<HTMLElement>,
+  | "children"
+  | "dir"
+  | "hidden"
+  | "id"
+  | "lang"
+  | "slot"
+  | "style"
+  | "title"
+  | "translate"
+  | "onClick"
+  | "onFocus"
+  | "onBlur"
+> {
+  /** Whether toggle is on. */
+  checked?: boolean;
+
+  /** Prevents interaction. */
+  disabled?: boolean;
+
+  /** Hides check/close icon inside toggle knob. */
+  noIcon?: boolean;
+
+  /** Adjusts colors for dark backgrounds. */
+  inverted?: boolean;
+
+  /** Unique identifier. Auto-generated if not provided. */
+  id?: NysToggleElement["id"];
+
+  /** Name for form submission. */
+  name?: NysToggleElement["name"];
+
+  /** Value submitted when toggle is on. */
+  value?: NysToggleElement["value"];
+
+  /** Visible label text. */
+  label?: NysToggleElement["label"];
+
+  /** Helper text below label. Use slot for custom HTML. */
+  description?: NysToggleElement["description"];
+
+  /** Form `id` to associate with. */
+  form?: NysToggleElement["form"];
+
+  /** Toggle size: `sm` or `md` (default). */
+  size?: NysToggleElement["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 toggle state changes. Detail: `{id, checked}`. */
+  onNysChange?: (event: CustomEvent) => void;
+
+  /** Fired when toggle gains focus. */
+  onNysFocus?: (event: CustomEvent) => void;
+
+  /** Fired when toggle loses focus. */
+  onNysBlur?: (event: CustomEvent) => void;
+}
+
+/**
+ * Toggle switch for binary settings with immediate effect.
+ * ---
+ *
+ *
+ * ### **Events:**
+ *  - **nys-change** - Fired when toggle state changes. Detail: `{id, checked}`.
+ * - **nys-focus** - Fired when toggle gains focus.
+ * - **nys-blur** - Fired when toggle loses focus.
+ *
+ * ### **Slots:**
+ *  - **description** - Custom HTML description content.
+ */
+export const NysToggle: React.ForwardRefExoticComponent<NysToggleProps>;