@nysds/components 1.12.0 → 1.13.0

package/README.md

@@ -1,5 +1,7 @@
 # New York State Design System
 
+![Version](https://img.shields.io/github/v/release/ITS-HCD/nysds) ![Accessibility: WCAG 2.2 AA](https://img.shields.io/badge/accessibility-WCAG%202.2%20AA-green)
+
 This repository contains a library of reusable code components for building New York State applications and websites. These components are built using LitElement and styled with custom CSS properties (variables) for easy customization.
 
 ## About the New York State Design System
@@ -30,4 +32,4 @@ npm install @nysds/components @nysds/styles
 ```html
 <script type="module" src="[path-to-dir]/nysds.js"></script>
 <link rel="stylesheet" href="[path-to-dir]/nysds-full.min.css" />
-```
+```

package/dist/.vscode/vscode.html-custom-data.json

@@ -4,7 +4,7 @@
   "tags": [
     {
       "name": "nys-accordion",
-      "description": "The \"nys-accordion\" is the wrapper that groups individual accordion items within it.\nThe items within is called \"nys-accordionitem\"\n---\n",
+      "description": "`<nys-accordion>` groups one or more `<nys-accordionitem>` elements.\n\nFeatures:\n- Optionally enforces single-expanded-item behavior via `singleSelect`.\n- Propagates shared visual `bordered` property to child items.\n- Generates a stable unique identifier if none is provided.\n---\n\n\n### **Events:**\n - **nys-accordionitem-toggle** - Fired when a child `<nys-accordionitem>` is toggled. Event detail includes `{ id: string, heading: string, expanded: boolean }`.\n\n### **Slots:**\n - **default** - Place one or more `<nys-accordionitem>` components here.",
       "attributes": [
         { "name": "id", "values": [] },
         { "name": "singleSelect", "values": [] },
@@ -14,7 +14,7 @@
     },
     {
       "name": "nys-accordionitem",
-      "description": "\n---\n\n\n### **Events:**\n - **nys-accordionitem-toggle**",
+      "description": "`<nys-accordionitem>` represents a single collapsible item inside a `<nys-accordion>`.\n---\n\n\n### **Events:**\n - **nys-accordionitem-toggle** - Fired when the item is expanded or collapsed.\n\n### **Slots:**\n - _default_ - Default slot for the content inside the accordion panel.",
       "attributes": [
         { "name": "id", "values": [] },
         { "name": "heading", "values": [] },
@@ -25,7 +25,7 @@
     },
     {
       "name": "nys-alert",
-      "description": "\n---\n\n\n### **Events:**\n - **nys-close**",
+      "description": "`<nys-alert>` renders an informational, success, warning, or error alert.\n---\n\n\n### **Events:**\n - **nys-close** - Fired when alert is dismissed (manual or timeout).\n\n### **Slots:**\n - _default_ - Default slot for additional alert content.",
       "attributes": [
         { "name": "id", "values": [] },
         { "name": "heading", "values": [] },
@@ -54,7 +54,7 @@
     },
     {
       "name": "nys-avatar",
-      "description": "\n---\n",
+      "description": "`<nys-avatar>` displays a user avatar as an image, initials, or icon.\n---\n\n\n### **Slots:**\n - _default_ - Default slot for custom icon content. Fallback icon is used if slot is empty. Features: - Computes foreground color for sufficient contrast based on background. - Supports interactive avatars with button role. - Fallback to icon when image or initials are missing. - Lazy loading for performance optimization.",
       "attributes": [
         { "name": "id", "values": [] },
         { "name": "ariaLabel", "values": [] },
@@ -70,7 +70,7 @@
     },
     {
       "name": "nys-backtotop",
-      "description": "\n---\n",
+      "description": "`<nys-backtotop>` renders a button that scrolls the page to the top.\n\nFeatures:\n- Automatically appears after scrolling past 1.5 viewport heights\n  if the page is at least 4 screens tall.\n- Adapts to mobile screens (renders as a circle button when narrow).\n- Can be explicitly shown with the `visible` attribute.\n---\n\n\n### **Events:**\n - **nys-click** - Fired when the button is clicked (scrolls page to top).",
       "attributes": [
         { "name": "position", "values": [] },
         { "name": "visible", "values": [] }
@@ -79,7 +79,7 @@
     },
     {
       "name": "nys-badge",
-      "description": "\n---\n",
+      "description": "`<nys-badge>` displays a badge with optional prefix/suffix icons and labels.\n\nFeatures:\n- Conveys an intent (`neutral`, `error`, `success`, `warning`) which affects default icons and styling.\n- Supports custom prefix and suffix icons.\n---\n",
       "attributes": [
         { "name": "id", "values": [] },
         { "name": "name", "values": [] },
@@ -103,7 +103,7 @@
     },
     {
       "name": "nys-button",
-      "description": "\n---\n\n\n### **Events:**\n - **nys-focus**\n- **nys-blur**\n- **nys-click**",
+      "description": "`<nys-button>` is a versatile button component supporting:\n- Multiple variants (`filled`, `outline`, `ghost`, `text`)\n- Sizes (`sm`, `md`, `lg`) and full-width layout\n- Icons (prefix, suffix, or circle) and optional labels\n- Native `<button>` or link `<a>` behavior with form association\n- Keyboard and accessibility support (`aria-label`, `aria-controls`, `aria-description`)\n---\n\n\n### **Events:**\n - **nys-focus** - Fired when button receives focus\n- **nys-blur** - Fired when button loses focus\n- **nys-click** - Fired on button click",
       "attributes": [
         { "name": "id", "values": [] },
         { "name": "name", "values": [] },
@@ -160,7 +160,7 @@
     },
     {
       "name": "nys-checkbox",
-      "description": "\n---\n\n\n### **Events:**\n - **nys-change**\n- **nys-focus**\n- **nys-blur**",
+      "description": "`<nys-checkbox>` is an accessible, form-associated checkbox component.\nCan be used standalone or within a `<nys-checkboxgroup>`.\n\nFeatures:\n- Supports labels, descriptions, and tooltips\n- Displays error messages with `showError` and `errorMessage`\n- Keyboard interaction with spacebar toggle\n- Form integration via ElementInternals (`checked` value submitted)\n---\n\n\n### **Events:**\n - **nys-change** - Fired when checkbox value changes\n- **nys-focus** - Fired on focus\n- **nys-blur** - Fired on blur\n\n### **Methods:**\n - **checkValidity(): _boolean_** - Functions\n--------------------------------------------------------------------------\n\n### **Slots:**\n - **description** - Slot to provide a custom description element",
       "attributes": [
         { "name": "checked", "values": [] },
         { "name": "disabled", "values": [] },
@@ -183,7 +183,7 @@
     },
     {
       "name": "nys-checkboxgroup",
-      "description": "\n---\n",
+      "description": "`<nys-checkboxgroup>` is a form-associated container for multiple `<nys-checkbox>` components.\nHandles grouping, validation, required constraints, form submission, and accessibility.\n\nFeatures:\n- Manages multiple checkboxes as a single form field\n- Supports required/optional flags and error messages\n- Propagates size, tile, and inverted styling to child checkboxes\n- Keyboard and screen reader accessible via fieldset/legend\n---\n\n\n### **Events:**\n - **nys-change** - Fired when any child checkbox changes\n- **nys-focus** - Fired when any child checkbox gains focus\n- **nys-blur** - Fired when any child checkbox loses focus\n\n### **Slots:**\n - **default** - Slot for child `<nys-checkbox>` elements\n- **description** - Slot for custom description content",
       "attributes": [
         { "name": "id", "values": [] },
         { "name": "name", "values": [] },
@@ -201,15 +201,43 @@
       ],
       "references": []
     },
+    {
+      "name": "nys-datepicker",
+      "description": "`<nys-datepicker>` is a form-associated, accessible date picker component.\nOptionally wraps a `<wc-datepicker>` for custom calendar UI.\n\nEvents:\n---\n\n\n### **Events:**\n - **nys-blur** - Dispatched when input or calendar loses focus\n- **nys-input** - Dispatched when user selects or types a valid date Notes: - Uses native date input on Safari or mobile devices (custom calendar removed for these scenarios)\n\n### **Methods:**\n - **checkValidity(): _boolean_** - Passive check of validity:\n- Returns true/false\n- Does NOT update UI or show errors\n- Used in form submission checks",
+      "attributes": [
+        { "name": "id", "values": [] },
+        { "name": "name", "values": [] },
+        {
+          "name": "width",
+          "values": [{ "name": "md" }, { "name": "lg" }, { "name": "full" }]
+        },
+        { "name": "hideTodayButton", "values": [] },
+        { "name": "hideClearButton", "values": [] },
+        { "name": "disabled", "values": [] },
+        { "name": "required", "values": [] },
+        { "name": "optional", "values": [] },
+        { "name": "showError", "values": [] },
+        { "name": "errorMessage", "values": [] },
+        { "name": "form", "values": [] },
+        { "name": "tooltip", "values": [] },
+        { "name": "type", "values": [] },
+        { "name": "label", "values": [] },
+        { "name": "description", "values": [] },
+        { "name": "startDate", "values": [] },
+        { "name": "inverted", "values": [] },
+        { "name": "value", "values": [{ "name": "Date" }] }
+      ],
+      "references": []
+    },
     {
       "name": "nys-divider",
-      "description": "\n---\n",
+      "description": "`<nys-divider>` renders a horizontal rule `<hr>` element with optional styling.\nCan be inverted for dark backgrounds.\n---\n",
       "attributes": [{ "name": "inverted", "values": [] }],
       "references": []
     },
     {
       "name": "nys-errormessage",
-      "description": "\n---\n",
+      "description": "THIS IS A PRIVATE COMPONENT!\n`<nys-errormessage>` displays an error message for form elements.\nCan optionally show a divider and supports native form validation messages.\n---\n",
       "attributes": [
         { "name": "showError", "values": [] },
         { "name": "errorMessage", "values": [] },
@@ -219,7 +247,7 @@
     },
     {
       "name": "nys-fileinput",
-      "description": "\n---\n\n\n### **Events:**\n - **nys-change**",
+      "description": "`<nys-fileinput>` provides accessible file selection with optional\ndrag-and-drop support, progress tracking, validation, and form submission.\n\nFeatures:\n- Supports single or multiple file uploads\n- Optional drag-and-drop dropzone\n- File type validation and upload progress\n- Form-associated with native validation behavior\n- Keyboard and screen reader accessible\n---\n\n\n### **Events:**\n - **nys-change** - Fired when files are added or removed\n\n### **Slots:**\n - **description** - Custom description content under the label",
       "attributes": [
         { "name": "id", "values": [] },
         { "name": "name", "values": [] },
@@ -242,7 +270,7 @@
     },
     {
       "name": "nys-fileitem",
-      "description": "\n---\n\n\n### **Events:**\n - **nys-fileRemove**",
+      "description": "`<nys-fileitem>` displays an individual file in a file input component.\nIt shows the file name, upload status, progress bar, and error messages.\n---\n\n\n### **Events:**\n - **nys-fileRemove**",
       "attributes": [
         { "name": "filename", "values": [] },
         {
@@ -262,7 +290,7 @@
     },
     {
       "name": "nys-globalfooter",
-      "description": "\n---\n",
+      "description": "`<nys-globalfooter>` renders a New York State–style global footer.\n\nDisplays an agency name with an optional homepage link and supports\nstructured footer content via slots.\n---\n\n\n### **Slots:**\n - **default** - Footer content such as headings, links, or groups Layout behavior: - Multiple `<h4>` elements trigger a multi-column layout - Single group content renders in a compact layout",
       "attributes": [
         { "name": "agencyName", "values": [] },
         { "name": "homepageLink", "values": [] }
@@ -271,7 +299,7 @@
     },
     {
       "name": "nys-globalheader",
-      "description": "\n---\n",
+      "description": "`<nys-globalheader>` renders a New York State–style global header.\n\nDisplays an optional application name, agency name, and homepage link.\nSupports slotted navigation content with automatic active-link detection\nand a responsive mobile menu.\n---\n\n\n### **Slots:**\n - **default** - Primary navigation list, typically a `<ul>` with links\n- **user-actions** - Optional user action elements such as login or profile Behavior: - Automatically highlights the best matching link based on the current URL - Duplicates navigation content for desktop and mobile layouts - Provides a toggleable mobile menu when navigation content exists",
       "attributes": [
         { "name": "appName", "values": [] },
         { "name": "agencyName", "values": [] },
@@ -281,7 +309,7 @@
     },
     {
       "name": "nys-icon",
-      "description": "\n---\n",
+      "description": "`<nys-icon>` renders an SVG icon from the internal icon library.\n\nIcons are inline SVGs and support sizing, rotation, flipping, color,\nand accessibility labeling.\n---\n",
       "attributes": [
         { "name": "name", "values": [] },
         { "name": "ariaLabel", "values": [] },
@@ -317,7 +345,7 @@
     },
     {
       "name": "nys-label",
-      "description": "\n---\n",
+      "description": "THIS IS A PRIVATE COMPONENT!\n`NysLabel` is a component for rendering form labels with optional\ndescriptions, flags (required/optional), and tooltips.\n---\n",
       "attributes": [
         { "name": "for", "values": [] },
         { "name": "label", "values": [] },
@@ -330,7 +358,7 @@
     },
     {
       "name": "nys-modal",
-      "description": "\n---\n\n\n### **Events:**\n - **nys-open**\n- **nys-close**",
+      "description": "`<nys-modal>` renders an accessible modal dialog.\n\nSupports headings, optional subheading, body content, and action buttons.\nManages focus trapping, escape key handling, and body scroll locking.\n---\n\n\n### **Events:**\n - **nys-open** - Emitted when the modal opens\n- **nys-close** - Emitted when the modal closes\n\n### **Slots:**\n - _default_ - Modal body content\n- **actions** - Action buttons shown in the footer",
       "attributes": [
         { "name": "id", "values": [] },
         { "name": "heading", "values": [] },
@@ -346,7 +374,7 @@
     },
     {
       "name": "nys-pagination",
-      "description": "\n---\n\n\n### **Events:**\n - **nys-change**",
+      "description": "`<nys-pagination>` renders page navigation controls.\n\nDisplays previous and next buttons, page numbers, and ellipses\nwhen pages are skipped. Handles page bounds automatically.\n---\n\n\n### **Events:**\n - **nys-change** - Fired when the page changes detail: { page: number }",
       "attributes": [
         { "name": "id", "values": [] },
         { "name": "name", "values": [] },
@@ -358,7 +386,7 @@
     },
     {
       "name": "nys-radiobutton",
-      "description": "\n---\n\n\n### **Events:**\n - **nys-change**\n- **nys-focus**\n- **nys-blur**",
+      "description": "`<nys-radiobutton>` represents a single radio button for use in a `<nys-radiogroup>`.\n\nFeatures:\n- Single selection per group\n- Supports labels, descriptions, tile layout, inverted style, and size variants\n- Integrates with forms and dispatches `nys-change` events on selection\n---\n\n\n### **Events:**\n - **nys-change** - Fired when the radio is selected or deselected detail: { id: string, checked: boolean, name: string, value: string }\n- **nys-focus** - Fired when the radio gains focus\n- **nys-blur** - Fired when the radio loses focus\n\n### **Methods:**\n - **checkValidity(): _boolean_** - Functions\n--------------------------------------------------------------------------\n\n### **Slots:**\n - **description** - Optional description text announced to screen readers",
       "attributes": [
         { "name": "checked", "values": [] },
         { "name": "disabled", "values": [] },
@@ -377,7 +405,7 @@
     },
     {
       "name": "nys-radiogroup",
-      "description": "\n---\n",
+      "description": "`<nys-radiogroup>` groups `<nys-radiobutton>` elements into a single\nselectable control.\n\nSupports keyboard navigation, validation, and native form submission\nthrough ElementInternals.\n---\n\n\n### **Events:**\n - **nys-change** - Fired when selection changes detail: { name: string; value: string }\n\n### **Slots:**\n - **default** - One or more `<nys-radiobutton>` elements\n- **description** - Optional descriptive text announced to screen readers",
       "attributes": [
         { "name": "id", "values": [] },
         { "name": "name", "values": [] },
@@ -409,7 +437,7 @@
     },
     {
       "name": "nys-select",
-      "description": "\n---\n\n\n### **Events:**\n - **nys-change**\n- **nys-focus**\n- **nys-blur**",
+      "description": "`<nys-select>` is a custom select/dropdown component.\n\nFeatures:\n- Supports slotted `<nys-option>` elements, native `<option>` and `<optgroup>`\n- Integrates with forms via ElementInternals\n- Handles validation, error messages, and required/optional states\n- Inverted style and width variants supported\n---\n\n\n### **Events:**\n - **nys-change** - Fired when the selected value changes detail: { id: string, value: string }\n- **nys-focus** - Fired when the select gains focus\n- **nys-blur** - Fired when the select loses focus\n\n### **Methods:**\n - **checkValidity(): _boolean_** - Functions\n--------------------------------------------------------------------------\n\n### **Slots:**\n - **description** - Optional description text announced to screen readers\n- **default** - Options (<nys-option>, <option>, <optgroup>) to populate the dropdown",
       "attributes": [
         { "name": "id", "values": [] },
         { "name": "name", "values": [] },
@@ -439,7 +467,7 @@
     },
     {
       "name": "nys-skipnav",
-      "description": "\n---\n",
+      "description": "`<nys-skipnav>` provides an accessible skip navigation link for keyboard\nand screen reader users to jump directly to the main content of a page.\n\nFeatures:\n- Default target is `#main-content` if `href` is not provided\n- Link becomes visible on focus and hides on blur\n- Ensures the target element is focusable for accessibility\n---\n",
       "attributes": [
         { "name": "id", "values": [] },
         { "name": "href", "values": [] }
@@ -461,7 +489,7 @@
     },
     {
       "name": "nys-stepper",
-      "description": "\n---\n",
+      "description": "`<nys-stepper>` manages a sequence of `<nys-step>` elements, providing\nmulti-step navigation for forms or workflows.\n\nFeatures:\n- Tracks selected and current steps\n- Displays a step counter (e.g., \"Step 2 of 5\")\n- Supports compact/expanded view toggle\n- Validates that only `<nys-step>` or `<div slot=\"actions\">` children are used\n---\n\n\n### **Events:**\n - **nys-step-click** - Fired when a step is clicked; bubbles with the event path",
       "attributes": [
         { "name": "id", "values": [] },
         { "name": "name", "values": [] },
@@ -471,9 +499,22 @@
       ],
       "references": []
     },
+    {
+      "name": "nys-table",
+      "description": "`<nys-table>` is a responsive table component that can display native HTML tables,\nsupports striped and bordered styling, sortable columns, and CSV download.\n---\n\n\n### **Events:**\n - **nys-click** - Fired when the download button or sortable headers are clicked.\n\n### **Slots:**\n - _default_ - Accepts a `<table>` element. Only the first table is rendered.",
+      "attributes": [
+        { "name": "id", "values": [] },
+        { "name": "name", "values": [] },
+        { "name": "striped", "values": [] },
+        { "name": "sortable", "values": [] },
+        { "name": "bordered", "values": [] },
+        { "name": "download", "values": [] }
+      ],
+      "references": []
+    },
     {
       "name": "nys-textarea",
-      "description": "\n---\n\n\n### **Events:**\n - **nys-input**\n- **nys-focus**\n- **nys-blur**\n- **nys-select**\n- **nys-selectionchange**",
+      "description": "`<nys-textarea>` is a form-enabled textarea with validation, accessibility support,\nand live error messages. Integrates with forms via ElementInternals.\n---\n\n\n### **Events:**\n - **nys-input** - Fired on input, detail: `{ id, value }`\n- **nys-focus** - Fired on focus.\n- **nys-blur** - Fired on blur.\n- **nys-select** - Fired on text selection, detail: `{ id, value }`\n- **nys-selectionchange** - Fired on selection change, detail: `{ id, value }`\n\n### **Methods:**\n - **checkValidity(): _boolean_** - Functions\n--------------------------------------------------------------------------\n\n### **Slots:**\n - **description** - Optional slot for custom description content below the label.",
       "attributes": [
         { "name": "id", "values": [] },
         { "name": "name", "values": [] },
@@ -511,7 +552,7 @@
     },
     {
       "name": "nys-textinput",
-      "description": "\n---\n\n\n### **Events:**\n - **nys-input**\n- **nys-focus**\n- **nys-blur**",
+      "description": "`<nys-textinput>` is a form-enabled text input with validation, optional\nmasking, password toggle, accessibility support, and live error messages.\nWorks with forms via ElementInternals.\n---\n\n\n### **Events:**\n - **nys-input** - Fired on input change. Detail: `{ id, value }`.\n- **nys-focus** - Fired when input receives focus.\n- **nys-blur** - Fired when input loses focus.\n\n### **Methods:**\n - **checkValidity(): _boolean_** - Functions\n--------------------------------------------------------------------------\n\n### **Slots:**\n - **description** - Optional custom description content below the label.\n- **startButton** - Slot for a single <nys-button> at the start of the input.\n- **endButton** - Slot for a single <nys-button> at the end of the input.",
       "attributes": [
         { "name": "id", "values": [] },
         { "name": "name", "values": [] },
@@ -561,7 +602,7 @@
     },
     {
       "name": "nys-toggle",
-      "description": "\n---\n\n\n### **Events:**\n - **nys-change**\n- **nys-focus**\n- **nys-blur**",
+      "description": "`<nys-toggle>` is a form-associated toggle switch with label, description,\nsize variants, inverted styles, and optional icons. Supports keyboard\ninteraction and integrates with forms via ElementInternals.\n---\n\n\n### **Events:**\n - **nys-change** - Fired when toggle changes state. Detail: `{ id, checked }`.\n- **nys-focus** - Fired when toggle receives focus.\n- **nys-blur** - Fired when toggle loses focus.\n\n### **Slots:**\n - **description** - Optional slot to provide additional description below the label.",
       "attributes": [
         { "name": "id", "values": [] },
         { "name": "name", "values": [] },
@@ -579,7 +620,7 @@
     },
     {
       "name": "nys-tooltip",
-      "description": "\n---\n",
+      "description": "`<nys-tooltip>` is a custom tooltip component for NYS design system elements.\nIt supports dynamic positioning, screen-reader accessibility, keyboard interaction,\nand viewport overflow handling.\n\nThe tooltip automatically positions itself relative to a target element specified\nvia the `for` attribute, but can also respect a user-defined position.\n---\n\n\n### **Events:**\n - **nys-focus** - Dispatched when the reference element receives focus (via keyboard or programmatically).\n- **nys-blur** - Dispatched when the reference element loses focus or mouse leaves the tooltip. Notes: - Tooltip visibility is automatically managed on hover/focus of the reference element. - The component adjusts position dynamically to prevent overflow off-screen. - Supports keyboard dismissal with the Escape key.",
       "attributes": [
         { "name": "id", "values": [] },
         { "name": "text", "values": [] },
@@ -591,13 +632,13 @@
     },
     {
       "name": "nys-unavfooter",
-      "description": "\n---\n",
+      "description": "`<nys-unavfooter>` is a footer component for New York State websites.\nIt displays the official NYS logo linking to ny.gov and a set of primary navigation links.\n\nFeatures:\n- Renders the NYS logo as an inline SVG linking to https://www.ny.gov\n- Provides key navigation links\n---\n",
       "attributes": [],
       "references": []
     },
     {
       "name": "nys-unavheader",
-      "description": "\n---\n",
+      "description": "`<nys-unavheader>` is a universal header for New York State websites.\n\nFeatures:\n- Trust bar indicating official NYS site status, with expandable details\n- NYS logo linking to the homepage\n- Search bar with dropdown behavior for mobile and desktop\n- Language translation dropdown supporting multiple languages\n- Accessible interactions with ARIA attributes and keyboard handling\n---\n",
       "attributes": [
         { "name": "trustbarVisible", "values": [] },
         { "name": "searchDropdownVisible", "values": [] },