@nysds/components 1.15.0 → 1.15.1

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,
+  );
+});

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,
+  );
+});