@nysds/components 1.14.0 → 1.15.1

package/packages/react/NysCombobox.d.ts

@@ -0,0 +1,126 @@
+import React from "react";
+import {
+  NysCombobox as NysComboboxElement,
+  CustomEvent,
+  Event,
+} from "../../dist/nysds.es.js";
+
+export type { NysComboboxElement, CustomEvent, Event };
+
+export interface NysComboboxProps extends Pick<
+  React.AllHTMLAttributes<HTMLElement>,
+  | "children"
+  | "dir"
+  | "hidden"
+  | "id"
+  | "lang"
+  | "slot"
+  | "style"
+  | "title"
+  | "translate"
+  | "onClick"
+  | "onFocus"
+  | "onBlur"
+> {
+  /** undefined */
+  disabled?: boolean;
+
+  /** undefined */
+  required?: boolean;
+
+  /** undefined */
+  optional?: boolean;
+
+  /** undefined */
+  inverted?: boolean;
+
+  /** undefined */
+  showError?: boolean;
+
+  /** undefined */
+  id?: NysComboboxElement["id"];
+
+  /** undefined */
+  name?: NysComboboxElement["name"];
+
+  /** undefined */
+  label?: NysComboboxElement["label"];
+
+  /** undefined */
+  description?: NysComboboxElement["description"];
+
+  /** undefined */
+  value?: NysComboboxElement["value"];
+
+  /** undefined */
+  tooltip?: NysComboboxElement["tooltip"];
+
+  /** undefined */
+  form?: NysComboboxElement["form"];
+
+  /** undefined */
+  width?: NysComboboxElement["width"];
+
+  /** undefined */
+  errorMessage?: NysComboboxElement["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 combobox receives focus. */
+  onNysFocus?: (event: CustomEvent) => void;
+
+  /** Fired when combobox loses focus. */
+  onNysBlur?: (event: CustomEvent) => void;
+
+  /** Fired when selection changes. Detail: `{ id, value }`. */
+  onNysChange?: (event: CustomEvent) => void;
+}
+
+/**
+ * `<nys-combobox>` is a form-enabled combo box combining text input with a filterable dropdown.
+ *
+ * Features:
+ * - Type to filter options
+ * - Keyboard navigation (Arrow keys, Enter, Escape)
+ * - Mouse and keyboard interaction
+ * - Clears non-selected text on blur
+ * - Clear button when value is selected
+ * - Integrates with forms via ElementInternals
+ * - Supports native <option> and <optgroup> elements
+ * - Accessible per W3C ARIA Authoring Practices
+ * ---
+ *
+ *
+ * ### **Events:**
+ *  - **nys-input** - Fired on input change. Detail: `{ id, value }`.
+ * - **nys-focus** - Fired when combobox receives focus.
+ * - **nys-blur** - Fired when combobox loses focus.
+ * - **nys-change** - Fired when selection changes. Detail: `{ id, value }`.
+ *
+ * ### **Slots:**
+ *  - **description** - Optional custom description content below the label.
+ * - **default** - Options (<option>, <optgroup>) to populate the dropdown
+ */
+export const NysCombobox: React.ForwardRefExoticComponent<NysComboboxProps>;

package/packages/react/NysCombobox.js

@@ -0,0 +1,66 @@
+import React, { forwardRef, useRef, useEffect } from "react";
+import "../../dist/nysds.es.js";
+import { useEventListener } from "./react-utils.js";
+
+export const NysCombobox = forwardRef((props, forwardedRef) => {
+  const ref = useRef(null);
+  const {
+    disabled,
+    required,
+    optional,
+    inverted,
+    showError,
+    id,
+    name,
+    label,
+    description,
+    value,
+    tooltip,
+    form,
+    width,
+    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-change", props.onNysChange);
+
+  return React.createElement(
+    "nys-combobox",
+    {
+      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,
+      value: props.value,
+      tooltip: props.tooltip,
+      form: props.form,
+      width: props.width,
+      errorMessage: props.errorMessage,
+      class: props.className,
+      exportparts: props.exportparts,
+      for: props.htmlFor,
+      part: props.part,
+      tabindex: props.tabIndex,
+      disabled: props.disabled ? 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/NysDatepicker.d.ts

@@ -0,0 +1,122 @@
+import React from "react";
+import {
+  NysDatepicker as NysDatepickerElement,
+  CustomEvent,
+  Event,
+} from "../../dist/nysds.es.js";
+
+export type { NysDatepickerElement, CustomEvent, Event };
+
+export interface NysDatepickerProps extends Pick<
+  React.AllHTMLAttributes<HTMLElement>,
+  | "children"
+  | "dir"
+  | "hidden"
+  | "id"
+  | "lang"
+  | "slot"
+  | "style"
+  | "title"
+  | "translate"
+  | "onClick"
+  | "onFocus"
+  | "onBlur"
+> {
+  /** Hide the "Today" button in calendar popup. */
+  hideTodayButton?: boolean;
+
+  /** Hide the "Clear" button in calendar popup. */
+  hideClearButton?: boolean;
+
+  /** Disable interaction. */
+  disabled?: boolean;
+
+  /** Mark as required. Shows "Required" flag and validates on blur. */
+  required?: boolean;
+
+  /** Show "Optional" flag. Use when most fields are required. */
+  optional?: boolean;
+
+  /** Show error state. */
+  showError?: boolean;
+
+  /** Dark background mode. */
+  inverted?: boolean;
+
+  /** Unique identifier. Auto-generated if not provided. */
+  id?: NysDatepickerElement["id"];
+
+  /** Name for form submission. */
+  name?: NysDatepickerElement["name"];
+
+  /** Input width: `md` (200px), `lg` (384px), `full` (100%). */
+  width?: NysDatepickerElement["width"];
+
+  /** Error message text. */
+  errorMessage?: NysDatepickerElement["errorMessage"];
+
+  /** Form `id` to associate with when input is outside form. */
+  form?: NysDatepickerElement["form"];
+
+  /** Tooltip text on info icon hover. */
+  tooltip?: NysDatepickerElement["tooltip"];
+
+  /** Input type. Currently only supports `date`. */
+  type?: NysDatepickerElement["type"];
+
+  /** Label text. Required for accessibility. */
+  label?: NysDatepickerElement["label"];
+
+  /** Helper text below label. */
+  description?: NysDatepickerElement["description"];
+
+  /** Initial date when calendar opens (YYYY-MM-DD). */
+  startDate?: NysDatepickerElement["startDate"];
+
+  /** Selected date. Accepts Date object or ISO string (YYYY-MM-DD). */
+  value?: NysDatepickerElement["value"];
+
+  /** 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 date selection. Detail: `{id, value}`. */
+  onNysInput?: (event: CustomEvent) => void;
+
+  /** Fired when input or calendar loses focus. Triggers validation. */
+  onNysBlur?: (event: CustomEvent) => void;
+}
+
+/**
+ * Date picker with calendar popup and native fallback.
+ * ---
+ *
+ *
+ * ### **Events:**
+ *  - **nys-input** - Fired on date selection. Detail: `{id, value}`.
+ * - **nys-blur** - Fired when input or calendar loses focus. Triggers validation.
+ *
+ * ### **Methods:**
+ *  - **checkValidity(): _boolean_** - Passive check of validity:
+ * - Returns true/false
+ * - Does NOT update UI or show errors
+ * - Used in form submission checks
+ */
+export const NysDatepicker: React.ForwardRefExoticComponent<NysDatepickerProps>;

package/packages/react/NysDatepicker.js

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

package/packages/react/NysDivider.d.ts

@@ -0,0 +1,51 @@
+import React from "react";
+import { NysDivider as NysDividerElement } from "../../dist/nysds.es.js";
+
+export type { NysDividerElement };
+
+export interface NysDividerProps extends Pick<
+  React.AllHTMLAttributes<HTMLElement>,
+  | "children"
+  | "dir"
+  | "hidden"
+  | "id"
+  | "lang"
+  | "slot"
+  | "style"
+  | "title"
+  | "translate"
+  | "onClick"
+  | "onFocus"
+  | "onBlur"
+> {
+  /** Adjusts colors for dark backgrounds. */
+  inverted?: boolean;
+
+  /** 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;
+}
+
+/**
+ * Horizontal divider for visual separation of content sections.
+ * ---
+ *
+ */
+export const NysDivider: React.ForwardRefExoticComponent<NysDividerProps>;

package/packages/react/NysDivider.js

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

package/packages/react/NysDropdownMenu.d.ts

@@ -0,0 +1,54 @@
+import React from "react";
+import { NysDropdownMenu as NysDropdownMenuElement } from "../../dist/nysds.es.js";
+
+export type { NysDropdownMenuElement };
+
+export interface NysDropdownMenuProps extends Pick<
+  React.AllHTMLAttributes<HTMLElement>,
+  | "children"
+  | "dir"
+  | "hidden"
+  | "id"
+  | "lang"
+  | "slot"
+  | "style"
+  | "title"
+  | "translate"
+  | "onClick"
+  | "onFocus"
+  | "onBlur"
+> {
+  /** undefined */
+  showDropdown?: boolean;
+
+  /** undefined */
+  for?: NysDropdownMenuElement["for"];
+
+  /** Preferred position relative to trigger. */
+  position?: NysDropdownMenuElement["position"];
+
+  /** 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 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;
+}
+
+/**
+ *
+ * ---
+ *
+ */
+export const NysDropdownMenu: React.ForwardRefExoticComponent<NysDropdownMenuProps>;

package/packages/react/NysDropdownMenu.js

@@ -0,0 +1,22 @@
+import React, { forwardRef } from "react";
+import "../../dist/nysds.es.js";
+
+export const NysDropdownMenu = forwardRef((props, forwardedRef) => {
+  const { showDropdown, position, ...filteredProps } = props;
+
+  return React.createElement(
+    "nys-dropdownmenu",
+    {
+      ...filteredProps,
+      for: props.for,
+      position: props.position,
+      class: props.className,
+      exportparts: props.exportparts,
+      part: props.part,
+      tabindex: props.tabIndex,
+      showDropdown: props.showDropdown ? true : undefined,
+      style: { ...props.style },
+    },
+    props.children,
+  );
+});

package/packages/react/NysDropdownMenuItem.d.ts

@@ -0,0 +1,75 @@
+import React from "react";
+import {
+  NysDropdownMenuItem as NysDropdownMenuItemElement,
+  CustomEvent,
+} from "../../dist/nysds.es.js";
+
+export type { NysDropdownMenuItemElement, CustomEvent };
+
+export interface NysDropdownMenuItemProps extends Pick<
+  React.AllHTMLAttributes<HTMLElement>,
+  | "children"
+  | "dir"
+  | "hidden"
+  | "id"
+  | "lang"
+  | "slot"
+  | "style"
+  | "title"
+  | "translate"
+  | "onClick"
+  | "onFocus"
+  | "onBlur"
+> {
+  /** undefined */
+  disabled?: boolean;
+
+  /** undefined */
+  label?: NysDropdownMenuItemElement["label"];
+
+  /** undefined */
+  href?: NysDropdownMenuItemElement["href"];
+
+  /** undefined */
+  target?: NysDropdownMenuItemElement["target"];
+
+  /** undefined */
+  prefixIcon?: NysDropdownMenuItemElement["prefixIcon"];
+
+  /** undefined */
+  divider?: NysDropdownMenuItemElement["divider"];
+
+  /** 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;
+
+  /** undefined */
+  onNysClick?: (event: CustomEvent) => void;
+}
+
+/**
+ * Dropdown item to display label and provide href link.
+ * ---
+ *
+ *
+ * ### **Events:**
+ *  - **nys-click**
+ */
+export const NysDropdownMenuItem: React.ForwardRefExoticComponent<NysDropdownMenuItemProps>;

package/packages/react/NysDropdownMenuItem.js

@@ -0,0 +1,47 @@
+import React, { forwardRef, useRef, useEffect } from "react";
+import "../../dist/nysds.es.js";
+import { useEventListener } from "./react-utils.js";
+
+export const NysDropdownMenuItem = forwardRef((props, forwardedRef) => {
+  const ref = useRef(null);
+  const {
+    disabled,
+    label,
+    href,
+    target,
+    prefixIcon,
+    divider,
+    ...filteredProps
+  } = props;
+
+  /** Event listeners - run once */
+  useEventListener(ref, "nys-click", props.onNysClick);
+
+  return React.createElement(
+    "nys-dropdownmenuitem",
+    {
+      ref: (node) => {
+        ref.current = node;
+        if (typeof forwardedRef === "function") {
+          forwardedRef(node);
+        } else if (forwardedRef) {
+          forwardedRef.current = node;
+        }
+      },
+      ...filteredProps,
+      label: props.label,
+      href: props.href,
+      target: props.target,
+      prefixIcon: props.prefixIcon,
+      divider: props.divider,
+      class: props.className,
+      exportparts: props.exportparts,
+      for: props.htmlFor,
+      part: props.part,
+      tabindex: props.tabIndex,
+      disabled: props.disabled ? true : undefined,
+      style: { ...props.style },
+    },
+    props.children,
+  );
+});