@nysds/components 1.14.0 → 1.15.1

package/packages/react/NysToggle.js

@@ -0,0 +1,59 @@
+import React, { forwardRef, useRef, useEffect } from "react";
+import "../../dist/nysds.es.js";
+import { useEventListener } from "./react-utils.js";
+
+export const NysToggle = forwardRef((props, forwardedRef) => {
+  const ref = useRef(null);
+  const {
+    checked,
+    disabled,
+    noIcon,
+    inverted,
+    id,
+    name,
+    value,
+    label,
+    description,
+    form,
+    size,
+    ...filteredProps
+  } = props;
+
+  /** Event listeners - run once */
+  useEventListener(ref, "nys-change", props.onNysChange);
+  useEventListener(ref, "nys-focus", props.onNysFocus);
+  useEventListener(ref, "nys-blur", props.onNysBlur);
+
+  return React.createElement(
+    "nys-toggle",
+    {
+      ref: (node) => {
+        ref.current = node;
+        if (typeof forwardedRef === "function") {
+          forwardedRef(node);
+        } else if (forwardedRef) {
+          forwardedRef.current = node;
+        }
+      },
+      ...filteredProps,
+      id: props.id,
+      name: props.name,
+      value: props.value,
+      label: props.label,
+      description: props.description,
+      form: props.form,
+      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,
+      noIcon: props.noIcon ? true : undefined,
+      inverted: props.inverted ? true : undefined,
+      style: { ...props.style },
+    },
+    props.children,
+  );
+});

package/packages/react/NysTooltip.d.ts

@@ -0,0 +1,60 @@
+import React from "react";
+import { NysTooltip as NysTooltipElement } from "../../dist/nysds.es.js";
+
+export type { NysTooltipElement };
+
+export interface NysTooltipProps extends Pick<
+  React.AllHTMLAttributes<HTMLElement>,
+  | "children"
+  | "dir"
+  | "hidden"
+  | "id"
+  | "lang"
+  | "slot"
+  | "style"
+  | "title"
+  | "translate"
+  | "onClick"
+  | "onFocus"
+  | "onBlur"
+> {
+  /** Adjusts colors for dark backgrounds. */
+  inverted?: boolean;
+
+  /** Unique identifier. Auto-generated if not provided. */
+  id?: NysTooltipElement["id"];
+
+  /** Tooltip content text. Required. */
+  text?: NysTooltipElement["text"];
+
+  /** ID of the trigger element to attach this tooltip to. Required. */
+  for?: NysTooltipElement["for"];
+
+  /** Preferred position relative to trigger. Auto-adjusts if space is insufficient. */
+  position?: NysTooltipElement["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;
+}
+
+/**
+ * Contextual tooltip with auto-positioning, keyboard support, and screen reader integration.
+ * ---
+ *
+ */
+export const NysTooltip: React.ForwardRefExoticComponent<NysTooltipProps>;

package/packages/react/NysTooltip.js

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

package/packages/react/NysUnavFooter.d.ts

@@ -0,0 +1,48 @@
+import React from "react";
+import { NysUnavFooter as NysUnavFooterElement } from "../../dist/nysds.es.js";
+
+export type { NysUnavFooterElement };
+
+export interface NysUnavFooterProps extends Pick<
+  React.AllHTMLAttributes<HTMLElement>,
+  | "children"
+  | "dir"
+  | "hidden"
+  | "id"
+  | "lang"
+  | "slot"
+  | "style"
+  | "title"
+  | "translate"
+  | "onClick"
+  | "onFocus"
+  | "onBlur"
+> {
+  /** 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;
+}
+
+/**
+ * Universal NYS footer with logo and statewide links. Required site-wide.
+ * ---
+ *
+ */
+export const NysUnavFooter: React.ForwardRefExoticComponent<NysUnavFooterProps>;

package/packages/react/NysUnavFooter.js

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

package/packages/react/NysUnavHeader.d.ts

@@ -0,0 +1,72 @@
+import React from "react";
+import { NysUnavHeader as NysUnavHeaderElement } from "../../dist/nysds.es.js";
+
+export type { NysUnavHeaderElement };
+
+export interface NysUnavHeaderProps extends Pick<
+  React.AllHTMLAttributes<HTMLElement>,
+  | "children"
+  | "dir"
+  | "hidden"
+  | "id"
+  | "lang"
+  | "slot"
+  | "style"
+  | "title"
+  | "translate"
+  | "onClick"
+  | "onFocus"
+  | "onBlur"
+> {
+  /** Internal: Whether trust bar panel is expanded. */
+  trustbarVisible?: boolean;
+
+  /** Internal: Whether search dropdown is visible (mobile). */
+  searchDropdownVisible?: boolean;
+
+  /** Internal: Whether language dropdown is visible. */
+  languageVisible?: boolean;
+
+  /** Internal: Whether search input is focused. */
+  isSearchFocused?: boolean;
+
+  /** Hides the translation dropdown. */
+  hideTranslate?: boolean;
+
+  /** Hides the search functionality. */
+  hideSearch?: boolean;
+
+  /** The URL endpoint of the search, make sure to include the query param. */
+  searchUrl?: NysUnavHeaderElement["searchUrl"];
+
+  /** The list of languages this site can be translated to, default to use Smartling */
+  languages?: NysUnavHeaderElement["languages"];
+
+  /** 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;
+}
+
+/**
+ *
+ * ---
+ *
+ */
+export const NysUnavHeader: React.ForwardRefExoticComponent<NysUnavHeaderProps>;

package/packages/react/NysUnavHeader.js

@@ -0,0 +1,38 @@
+import React, { forwardRef } from "react";
+import "../../dist/nysds.es.js";
+
+export const NysUnavHeader = forwardRef((props, forwardedRef) => {
+  const {
+    trustbarVisible,
+    searchDropdownVisible,
+    languageVisible,
+    isSearchFocused,
+    hideTranslate,
+    hideSearch,
+    searchUrl,
+    languages,
+    ...filteredProps
+  } = props;
+
+  return React.createElement(
+    "nys-unavheader",
+    {
+      ...filteredProps,
+      searchUrl: props.searchUrl,
+      languages: props.languages,
+      class: props.className,
+      exportparts: props.exportparts,
+      for: props.htmlFor,
+      part: props.part,
+      tabindex: props.tabIndex,
+      trustbarVisible: props.trustbarVisible ? true : undefined,
+      searchDropdownVisible: props.searchDropdownVisible ? true : undefined,
+      languageVisible: props.languageVisible ? true : undefined,
+      isSearchFocused: props.isSearchFocused ? true : undefined,
+      hideTranslate: props.hideTranslate ? true : undefined,
+      hideSearch: props.hideSearch ? true : undefined,
+      style: { ...props.style },
+    },
+    props.children,
+  );
+});

package/packages/react/README.md

@@ -0,0 +1,92 @@
+# `@nysds/components/react` — Auto-generated React Wrappers
+
+⚠️ This folder is **fully auto-generated** — do not edit files inside it directly!
+Files are regenerated every time `npm run cem` runs, which is called automatically by `npm run build:all`.
+
+---
+
+## How it works
+
+```
+npm run cem
+  └─► cem analyze --config custom-elements-manifest.config.mjs
+        └─► customElementReactWrapperPlugin  (custom-element-react-wrappers)
+              └─► packages/react/
+                    ├── index.js        <= barrel, one export per component
+                    ├── index.d.ts      <= TypeScript types
+                    ├── react-utils.js  <= auto generated internal hooks used by wrappers, do not use directly
+                    ├── NysButton.js    <= one file per component
+                    └── ...etc.
+```
+
+The plugin is configured in `custom-elements-manifest.config.mjs` at the repo root.
+The `./react` subpath export is declared in the root `package.json`, pointing at this folder.
+
+---
+
+## Usage
+
+```tsx
+import { NysButton, NysTextinput } from "@nysds/components/react";
+
+function MyForm() {
+  return (
+    <>
+      <NysTextinput
+        label="First name"
+        onNysInput={(e) => console.log(e.detail)}
+      />
+      <NysButton
+        label="Submit"
+        variant="filled"
+        onNysClick={() => console.log("clicked!")}
+      />
+    </>
+  );
+}
+```
+
+All props are typed. Custom events map to `on<EventName>` React callbacks.
+
+---
+
+## Event name convention
+
+| DOM event        | React prop       |
+|------------------|------------------|
+| `nys-click`      | `onNysClick`     |
+| `nys-change`     | `onNysChange`    |
+| `nys-input`      | `onNysInput`     |
+| `nys-focus`      | `onNysFocus`     |
+| `nys-blur`       | `onNysBlur`      |
+| `nys-open`       | `onNysOpen`      |
+| `nys-close`      | `onNysClose`     |
+| `nys-step-click` | `onNysStepClick` |
+| *(any new event)*| *(auto-added)*   |
+
+---
+
+## Adding a new component
+
+Nothing to do. Once a new Lit component is picked up by `cem analyze`, its wrapper is generated on the next `npm run cem` / `npm run build:all`.
+
+---
+
+## Why not React 19 native web component support?
+
+React 19 improves web component interop but doesn't bridge custom events to `on*` callbacks, and provides no TypeScript prop types from the element class. These wrappers handle both and keep the same developer experience as any standard React component library.
+
+---
+
+## Repo layout
+
+```
+custom-elements-manifest.config.mjs  <= plugin configured here
+package.json                         <= "./react" subpath export declared here
+packages/
+  react/                             <= auto-generated, do not edit
+    index.js
+    index.d.ts
+    react-utils.js
+    NysButton.js  ...etc.
+```

package/packages/react/index.d.ts

@@ -0,0 +1,37 @@
+export * from "./NysAccordion.js";
+export * from "./NysAccordionItem.js";
+export * from "./NysAvatar.js";
+export * from "./NysAlert.js";
+export * from "./NysBacktotop.js";
+export * from "./NysBadge.js";
+export * from "./NysButton.js";
+export * from "./NysCombobox.js";
+export * from "./NysCheckbox.js";
+export * from "./NysCheckboxgroup.js";
+export * from "./NysDatepicker.js";
+export * from "./NysDivider.js";
+export * from "./NysDropdownMenu.js";
+export * from "./NysDropdownMenuItem.js";
+export * from "./NysErrorMessage.js";
+export * from "./NysFileinput.js";
+export * from "./NysFileItem.js";
+export * from "./NysGlobalHeader.js";
+export * from "./NysIcon.js";
+export * from "./NysGlobalFooter.js";
+export * from "./NysModal.js";
+export * from "./NysLabel.js";
+export * from "./NysRadiobutton.js";
+export * from "./NysRadiogroup.js";
+export * from "./NysOption.js";
+export * from "./NysSelect.js";
+export * from "./NysPagination.js";
+export * from "./NysTable.js";
+export * from "./NysTextarea.js";
+export * from "./NysStep.js";
+export * from "./NysStepper.js";
+export * from "./NysSkipnav.js";
+export * from "./NysTextinput.js";
+export * from "./NysTooltip.js";
+export * from "./NysToggle.js";
+export * from "./NysUnavFooter.js";
+export * from "./NysUnavHeader.js";

package/packages/react/index.js

@@ -0,0 +1,37 @@
+export * from "./NysAccordion.js";
+export * from "./NysAccordionItem.js";
+export * from "./NysAvatar.js";
+export * from "./NysAlert.js";
+export * from "./NysBacktotop.js";
+export * from "./NysBadge.js";
+export * from "./NysButton.js";
+export * from "./NysCombobox.js";
+export * from "./NysCheckbox.js";
+export * from "./NysCheckboxgroup.js";
+export * from "./NysDatepicker.js";
+export * from "./NysDivider.js";
+export * from "./NysDropdownMenu.js";
+export * from "./NysDropdownMenuItem.js";
+export * from "./NysErrorMessage.js";
+export * from "./NysFileinput.js";
+export * from "./NysFileItem.js";
+export * from "./NysGlobalHeader.js";
+export * from "./NysIcon.js";
+export * from "./NysGlobalFooter.js";
+export * from "./NysModal.js";
+export * from "./NysLabel.js";
+export * from "./NysRadiobutton.js";
+export * from "./NysRadiogroup.js";
+export * from "./NysOption.js";
+export * from "./NysSelect.js";
+export * from "./NysPagination.js";
+export * from "./NysTable.js";
+export * from "./NysTextarea.js";
+export * from "./NysStep.js";
+export * from "./NysStepper.js";
+export * from "./NysSkipnav.js";
+export * from "./NysTextinput.js";
+export * from "./NysTooltip.js";
+export * from "./NysToggle.js";
+export * from "./NysUnavFooter.js";
+export * from "./NysUnavHeader.js";

package/packages/react/react-utils.js

@@ -0,0 +1,40 @@
+import { useEffect, useRef } from "react";
+
+export function useProperties(targetElement, propName, value) {
+  useEffect(() => {
+    if (
+      value !== undefined &&
+      targetElement.current &&
+      targetElement.current[propName] !== value
+    ) {
+      try {
+        targetElement.current[propName] = value;
+      } catch (e) {
+        console.warn(e);
+      }
+    }
+  }, [value, targetElement]);
+}
+
+export function useEventListener(targetElement, eventName, eventHandler) {
+  // Store the latest handler in a ref so we never need to re-subscribe
+  // just because the consumer passed a new function reference.
+  const savedHandler = useRef(eventHandler);
+  useEffect(() => {
+    savedHandler.current = eventHandler;
+  }, [eventHandler]);
+
+  useEffect(() => {
+    const element = targetElement.current;
+    if (!element || eventHandler === undefined) return;
+
+    // Stable wrapper — identity never changes, so add/remove are always paired.
+    const listener = (event) => savedHandler.current(event);
+
+    element.addEventListener(eventName, listener);
+
+    return () => {
+      element.removeEventListener(eventName, listener);
+    };
+  }, [eventName, targetElement]);
+}

package/dist/nys-stepper/newsletter.html

@@ -1,4 +0,0 @@
-<div style="padding: 2rem;">
-  <h2>Newsletter Opt-In</h2>
-  <p>Subscribe to our newsletter to stay updated on the latest features and offers.</p>
-</div>

package/dist/nys-stepper/personal.html

@@ -1,6 +0,0 @@
-<div style="padding: 2rem;">
-  <h2>Personal Details</h2>
-  <p>This is the form to enter your personal information. Fill in your name, address, and contact details here.</p>
-  <nys-textinput label="Name" required width="md"></nys-textinput>
-  <nys-textinput label="Agency Email" required width="md"></nys-textinput>
-</div>

package/dist/nys-stepper/survey.html

@@ -1,5 +0,0 @@
-<div style="padding: 2rem;">
-  <h2>Usage Survey</h2>
-  <p>Tell us how you plan to use this application. Your feedback helps us improve.</p>
-  <nys-textarea label="Project Details" resize="none"></nys-textarea>
-</div>

package/dist/nys-stepper/team.html

@@ -1,6 +0,0 @@
-<div style="padding: 2rem;">
-  <h2>Team Information</h2>
-  <p>Provide details about your team. Who are you working with? What is your role?</p>
-  <nys-textinput label="Agency Name" required width="md"></nys-textinput>
-  <nys-textinput label="Team Name" required width="md"></nys-textinput>
-</div>