@nysds/components 1.19.2 → 1.19.3

package/dist/packages/nys-radiobutton/src/nys-radiogroup.d.ts

@@ -12,7 +12,7 @@ import { LitElement } from "lit";
  * @slot - Default slot for `nys-radiobutton` elements.
  * @slot description - Custom HTML description content.
  *
- * @example Basic radio group
+ * @example Basic
  * ```html
  * <nys-radiogroup label="Select borough" required>
  *   <nys-radiobutton name="borough" value="bronx" label="The Bronx"></nys-radiobutton>
@@ -20,6 +20,79 @@ import { LitElement } from "lit";
  *   <nys-radiobutton name="borough" value="manhattan" label="Manhattan"></nys-radiobutton>
  * </nys-radiogroup>
  * ```
+ *
+ * @example Tile
+ * ```html
+ * <nys-radiogroup label="Select borough" tile>
+ *   <nys-radiobutton name="borough" value="bronx" label="The Bronx"></nys-radiobutton>
+ *   <nys-radiobutton name="borough" value="brooklyn" label="Brooklyn"></nys-radiobutton>
+ * </nys-radiogroup>
+ * ```
+ *
+ * @example Required
+ * ```html
+ * <nys-radiogroup label="Select borough" required>
+ *   <nys-radiobutton name="borough" value="bronx" label="The Bronx"></nys-radiobutton>
+ *   <nys-radiobutton name="borough" value="brooklyn" label="Brooklyn"></nys-radiobutton>
+ * </nys-radiogroup>
+ * ```
+ *
+ * @example Optional
+ * ```html
+ * <nys-radiogroup label="Select borough" optional>
+ *   <nys-radiobutton name="borough" value="bronx" label="The Bronx"></nys-radiobutton>
+ *   <nys-radiobutton name="borough" value="brooklyn" label="Brooklyn"></nys-radiobutton>
+ * </nys-radiogroup>
+ * ```
+ *
+ * @example Disabled
+ * ```html
+ * <nys-radiogroup label="Select borough">
+ *   <nys-radiobutton name="borough" value="bronx" label="The Bronx" disabled></nys-radiobutton>
+ *   <nys-radiobutton name="borough" value="brooklyn" label="Brooklyn" disabled></nys-radiobutton>
+ * </nys-radiogroup>
+ * ```
+ *
+ * @example Size Small
+ * ```html
+ * <nys-radiogroup label="Select borough" size="sm">
+ *   <nys-radiobutton name="borough" value="bronx" label="The Bronx"></nys-radiobutton>
+ *   <nys-radiobutton name="borough" value="brooklyn" label="Brooklyn"></nys-radiobutton>
+ * </nys-radiogroup>
+ * ```
+ *
+ * @example Other Option
+ * ```html
+ * <nys-radiogroup label="Select borough">
+ *   <nys-radiobutton name="borough" value="bronx" label="The Bronx"></nys-radiobutton>
+ *   <nys-radiobutton name="borough" value="" label="Other" other></nys-radiobutton>
+ * </nys-radiogroup>
+ * ```
+ *
+ * @example Error Message
+ * ```html
+ * <nys-radiogroup label="Select borough" showError errorMessage="Please select a borough">
+ *   <nys-radiobutton name="borough" value="bronx" label="The Bronx"></nys-radiobutton>
+ *   <nys-radiobutton name="borough" value="brooklyn" label="Brooklyn"></nys-radiobutton>
+ * </nys-radiogroup>
+ * ```
+ *
+ * @example Description
+ * ```html
+ * <nys-radiogroup label="Select borough" description="Your primary residence in NYC.">
+ *   <nys-radiobutton name="borough" value="bronx" label="The Bronx"></nys-radiobutton>
+ *   <nys-radiobutton name="borough" value="brooklyn" label="Brooklyn"></nys-radiobutton>
+ * </nys-radiogroup>
+ * ```
+ *
+ * @example Description Slot
+ * ```html
+ * <nys-radiogroup label="Select borough">
+ *   <div slot="description">Your primary <strong>residence</strong> in NYC.</div>
+ *   <nys-radiobutton name="borough" value="bronx" label="The Bronx"></nys-radiobutton>
+ *   <nys-radiobutton name="borough" value="brooklyn" label="Brooklyn"></nys-radiobutton>
+ * </nys-radiogroup>
+ * ```
  */
 export declare class NysRadiogroup extends LitElement {
     static styles: import("lit").CSSResult;

package/dist/packages/nys-select/src/nys-option.d.ts

@@ -9,14 +9,6 @@ import { LitElement } from "lit";
  * @element nys-option
  *
  * @slot - Option label text. Auto-populates the `label` prop if provided.
- *
- * @example Basic options
- * ```html
- * <nys-select>
- *   <nys-option value="ny">New York</nys-option>
- *   <nys-option value="ca" disabled>California</nys-option>
- * </nys-select>
- * ```
  */
 export declare class NysOption extends LitElement {
     /** Prevents selection of this option. */

package/dist/packages/nys-select/src/nys-select.d.ts

@@ -16,24 +16,155 @@ import { LitElement } from "lit";
  * @fires nys-focus - Fired when select gains focus.
  * @fires nys-blur - Fired when select loses focus. Triggers validation.
  *
- * @example Basic select
+ * @example Basic
  * ```html
- * <nys-select label="Select borough">
- *   <option value="bronx">The Bronx</option>
- *   <option value="brooklyn">Brooklyn</option>
- *   <option value="manhattan">Manhattan</option>
+ *  <nys-select label="Select your favorite borough" id="borough">
+ *   <option value="bronx" label="The Bronx"></option>
+ *   <option value="brooklyn" label="Brooklyn"></option>
+ *   <option value="manhattan" label="Manhattan"></option>
+ *   <option value="staten_island" label="Staten Island"></option>
+ *   <option value="queens" label="Queens"></option>
  * </nys-select>
  * ```
  *
- * @example With option groups
+ * @example Default value
  * ```html
- * <nys-select label="Select service">
- *   <optgroup label="Transportation">
- *     <option value="mta">MTA</option>
- *     <option value="dmv">DMV</option>
+ * <nys-select label="Select your favorite borough" id="borough">
+ *   <option value="bronx" label="The Bronx"></option>
+ *   <option value="brooklyn" label="Brooklyn" selected></option>
+ *   <option value="manhattan" label="Manhattan"></option>
+ *   <option value="staten_island" label="Staten Island"></option>
+ *   <option value="queens" label="Queens"></option>
+ * </nys-select>
+ * ```
+ *
+ * @example Option Group
+ * ```html
+ * <nys-select
+ * label="Which New York State service are you contacting us about?"
+ * description="This is for demo purposes and the list might not be exhaustive."
+ * >
+ *   <optgroup label="Transportation Services">
+ *     <option value="mta">MTA / Public Transit</option>
+ *     <option value="dmv">Department of Motor Vehicles (DMV)</option>
+ *     <option value="highway">Highway Maintenance</option>
+ *   </optgroup>
+ *   <optgroup label="Health & Human Services">
+ *     <option value="medicaid">Medicaid / Health Insurance</option>
+ *     <option value="mental-health">Mental Health Support</option>
+ *     <option value="child-family">Child and Family Services</option>
  *   </optgroup>
+ *   <optgroup label="Public Safety">
+ *     <option value="state-police">State Police</option>
+ *     <option value="emergency-management">Emergency Management</option>
+ *     <option value="fire-safety">Fire Safety</option>
+ *   </optgroup>
+ *   <optgroup label="Environment & Energy">
+ *     <option value="environmental-conservation">
+ *       Environmental Conservation
+ *     </option>
+ *     <option value="clean-energy">Clean Energy Programs</option>
+ *     <option value="waste-management">Waste Management</option>
+ *   </optgroup>
+ * </nys-select>
+ * ```
+ * @example Disabled
+ * ```html
+ * <nys-select label="Select your favorite borough" id="borough" disabled>
+ *   <option value="bronx" label="The Bronx"></option>
+ *   <option value="brooklyn" label="Brooklyn"></option>
+ *   <option value="manhattan" label="Manhattan"></option>
+ *   <option value="staten_island" label="Staten Island"></option>
+ *   <option value="queens" label="Queens"></option>
+ * </nys-select>
+ * ```
+ *
+ * @example Disabled Option
+ * ```html
+ * <nys-select label="Select your favorite borough" id="borough">
+ *   <option value="bronx" label="The Bronx"></option>
+ *   <option value="brooklyn" label="Brooklyn"></option>
+ *   <option value="manhattan" label="Manhattan"></option>
+ *   <option value="staten_island" label="Staten Island" disabled></option>
+ *   <option value="queens" label="Queens" disabled></option>
+ * </nys-select>
+ * ```
+ *
+ * @example Required
+ * ```html
+ * <nys-select label="Select your favorite borough" id="borough" required>
+ *   <option value="bronx" label="The Bronx"></option>
+ *   <option value="brooklyn" label="Brooklyn"></option>
+ *   <option value="manhattan" label="Manhattan"></option>
+ *   <option value="staten_island" label="Staten Island"></option>
+ *   <option value="queens" label="Queens"></option>
+ * </nys-select>
+ * ```
+ *
+ * @example Optional
+ * ```html
+ * <nys-select label="Select your favorite borough" id="borough" optional>
+ *   <option value="bronx" label="The Bronx"></option>
+ *   <option value="brooklyn" label="Brooklyn"></option>
+ *   <option value="manhattan" label="Manhattan"></option>
+ *   <option value="staten_island" label="Staten Island"></option>
+ *   <option value="queens" label="Queens"></option>
+ * </nys-select>
+ * ```
+ *
+ * @example Width small
+ * ```html
+ * <nys-select label="Select your favorite borough" id="borough" width="sm">
+ *   <option value="bronx" label="The Bronx"></option>
+ *   <option value="brooklyn" label="Brooklyn"></option>
+ *   <option value="manhattan" label="Manhattan"></option>
+ *   <option value="staten_island" label="Staten Island"></option>
+ *   <option value="queens" label="Queens"></option>
+ * </nys-select>
+ * ```
+ *
+ * @example Width medium
+ * ```html
+ * <nys-select label="Select your favorite borough" id="borough" width="md">
+ *   <option value="bronx" label="The Bronx"></option>
+ *   <option value="brooklyn" label="Brooklyn"></option>
+ *   <option value="manhattan" label="Manhattan"></option>
+ *   <option value="staten_island" label="Staten Island"></option>
+ *   <option value="queens" label="Queens"></option>
  * </nys-select>
  * ```
+ *
+ * @example Width large
+ * ```html
+ * <nys-select label="Select your favorite borough" id="borough" width="lg">
+ *   <option value="bronx" label="The Bronx"></option>
+ *   <option value="brooklyn" label="Brooklyn"></option>
+ *   <option value="manhattan" label="Manhattan"></option>
+ *   <option value="staten_island" label="Staten Island"></option>
+ *   <option value="queens" label="Queens"></option>
+ * </nys-select>
+ * ```
+ *
+ * @example Slotted Description
+ * ```html
+ * <nys-select label="Select your favorite borough" id="borough">
+ *   <label slot="description">This is a slotted description</label>
+ *   <option value="bronx" label="The Bronx"></option>
+ *   <option value="brooklyn" label="Brooklyn"></option>
+ *   <option value="manhattan" label="Manhattan"></option>
+ *   <option value="staten_island" label="Staten Island"></option>
+ *   <option value="queens" label="Queens"></option>
+ * </nys-select>
+ * ```
+ *
+ * @example Error Message
+ * <nys-select label="Select your favorite borough" id="borough" errorMessage="You did not select a borough" showError>
+ *   <option value="bronx" label="The Bronx"></option>
+ *   <option value="brooklyn" label="Brooklyn"></option>
+ *   <option value="manhattan" label="Manhattan"></option>
+ *   <option value="staten_island" label="Staten Island"></option>
+ *   <option value="queens" label="Queens"></option>
+ * </nys-select>
  */
 export declare class NysSelect extends LitElement {
     static styles: import("lit").CSSResult;

package/dist/packages/nys-skipnav/src/nys-skipnav.d.ts

@@ -8,15 +8,15 @@ import { LitElement } from "lit";
  * @summary Skip navigation link for keyboard accessibility. Hidden until focused.
  * @element nys-skipnav
  *
- * @example Default skip link
+ * @example Basic
  * ```html
  * <nys-skipnav></nys-skipnav>
- * <main id="main-content">...</main>
  * ```
  *
  * @example Custom target
  * ```html
  * <nys-skipnav href="#content-area"></nys-skipnav>
+ * <p id="content-area">...</p>
  * ```
  */
 export declare class NysSkipnav extends LitElement {

package/dist/packages/nys-stepper/src/nys-step.d.ts

@@ -74,19 +74,6 @@ import { LitElement } from "lit";
  * @fires nys-step-click - Fired when a navigable (`previous` or `current`) non-selected step is clicked
  *   or activated by keyboard. Detail: `{ href: string, label: string }`. Cancelable — call
  *   `e.preventDefault()` to suppress `window.location.href` navigation.
- *
- * @example Step with page navigation
- * ```html
- * <nys-step label="Personal Info" href="/step-1"></nys-step>
- * ```
- *
- * @example Step with SPA navigation (no href)
- * ```js
- * step.addEventListener('nys-step-click', (e) => {
- *   e.preventDefault(); // no href set, but good practice
- *   showStepContent(e.detail.label);
- * });
- * ```
  */
 export declare class NysStep extends LitElement {
     static styles: import("lit").CSSResult;

package/dist/packages/nys-stepper/src/nys-stepper.d.ts

@@ -48,87 +48,137 @@ import "./nys-step";
  * @slot - Default slot for `nys-step` elements. Only `nys-step` children are accepted; others are removed.
  * @slot actions - Persistent navigation buttons. Must contain exactly one `<div>` wrapping only `<nys-button>` elements.
  *
- * @example Basic stepper
+ * @example Basic
  * ```html
- * <nys-stepper label="Application Progress">
- *   <nys-step label="Personal Info" current></nys-step>
- *   <nys-step label="Contact Details"></nys-step>
- *   <nys-step label="Review"></nys-step>
- * </nys-stepper>
+ * <div class="nys-grid-row">
+ *   <nys-stepper
+ *     id="stepper"
+ *     name="stepper"
+ *     label="Register for Design System Office Hours"
+ *     class="nys-desktop:nys-grid-col-3"
+ *   >
+ *     <nys-step label="Personal Details" href="/nys-stepper/personal.html"></nys-step>
+ *     <nys-step label="Team Info" selected href="/nys-stepper/team.html"></nys-step>
+ *     <nys-step label="Usage Survey" current href="/nys-stepper/survey.html"></nys-step>
+ *     <nys-step label="Newsletter Opt-In" href="/nys-stepper/newsletter.html"></nys-step>
+ *     <div slot="actions">
+ *       <nys-button variant="outline" label="Save & Exit" fullWidth></nys-button>
+ *     </div>
+ *   </nys-stepper>
+ *   <div class="nys-desktop:nys-grid-col-9" id="nys-stepper-content">
+ *     Loading...
+ *   </div>
+ * </div>
  * ```
- *
- * @example Grid layout with sidebar placement
- * Use NYSDS grid utilities to position the stepper as a sidebar alongside form content.
- * **Layout requirements:**
- * - Wrap in `nys-grid-container` > `nys-grid-row`
- * - Use mobile-first classes: `nys-grid-col-12` (stacks on mobile) plus `nys-desktop:nys-grid-col-*`
- * - Columns must total 12 (e.g., 3+9 or 4+8)
- * - Recommended: stepper 3-4 cols, content 8-9 cols
+ * @render Basic
  * ```html
- * <div class="nys-grid-container">
- *   <div class="nys-grid-row">
- *     <nys-stepper label="Application" class="nys-grid-col-12 nys-desktop:nys-grid-col-3">
- *       <nys-step label="Personal Info"></nys-step>
- *       <nys-step label="Contact" current></nys-step>
- *       <nys-step label="Review"></nys-step>
- *     </nys-stepper>
- *     <main class="nys-grid-col-12 nys-desktop:nys-grid-col-9" id="main-content">
- *       <!-- Form content for current step -->
- *       <nys-textinput label="Email" required></nys-textinput>
- *       <nys-textinput label="Phone"></nys-textinput>
- *     </main>
+ * <div class="nys-grid-row">
+ *   <nys-stepper
+ *     id="stepper"
+ *     name="stepper"
+ *     label="Register for Design System Office Hours"
+ *     class="nys-desktop:nys-grid-col-3"
+ *   >
+ *     <nys-step label="Personal Details" href="/nys-stepper/personal.html"></nys-step>
+ *     <nys-step label="Team Info" selected href="/nys-stepper/team.html"></nys-step>
+ *     <nys-step label="Usage Survey" current href="/nys-stepper/survey.html"></nys-step>
+ *     <nys-step label="Newsletter Opt-In" href="/nys-stepper/newsletter.html"></nys-step>
+ *   </nys-stepper>
+ *   <div class="nys-desktop:nys-grid-col-9" id="nys-stepper-content">
+ *     Loading...
  *   </div>
  * </div>
+ * <script>
+ *   document.addEventListener("DOMContentLoaded", async () => {
+ *     const stepper = document.querySelector("nys-stepper");
+ *     if (stepper?.updateComplete) await stepper.updateComplete;
+ *     const selectedStep = document.querySelector("nys-step[selected]");
+ *     const href = selectedStep?.getAttribute("href");
+ *     if (!href) return;
+ *     const res = await fetch(href);
+ *     if (!res.ok) return;
+ *     const container = document.querySelector("#nys-stepper-content");
+ *     if (container) container.innerHTML = await res.text();
+ *   });
+ *
+ *   document.addEventListener("nys-step-click", async (e) => {
+ *     const href = e.detail?.href;
+ *     if (!href) return;
+ *     e.preventDefault();
+ *     const res = await fetch(href);
+ *     if (!res.ok) return;
+ *     const container = document.querySelector("#nys-stepper-content");
+ *     if (container) container.innerHTML = await res.text();
+ *   });
+ * </script>
  * ```
  *
- * @example Navigation buttons in actions slot
- * Add Previous/Next buttons using the actions slot. Wrap buttons in a `<div>`.
+ * @example Actions slot
  * ```html
- * <nys-stepper label="Application">
- *   <nys-step label="Step 1"></nys-step>
- *   <nys-step label="Step 2" current></nys-step>
- *   <nys-step label="Step 3"></nys-step>
- *   <div slot="actions">
- *     <nys-button label="Save and Exit" variant="outline" size="sm" fullWidth></nys-button>
+ * <div class="nys-grid-row">
+ *   <nys-stepper
+ *     id="stepper"
+ *     name="stepper"
+ *     label="Register for Design System Office Hours"
+ *     class="nys-desktop:nys-grid-col-3"
+ *   >
+ *     <nys-step label="Personal Details" href="/nys-stepper/personal.html"></nys-step>
+ *     <nys-step label="Team Info" selected href="/nys-stepper/team.html"></nys-step>
+ *     <nys-step label="Usage Survey" current href="/nys-stepper/survey.html"></nys-step>
+ *     <nys-step label="Newsletter Opt-In" href="/nys-stepper/newsletter.html"></nys-step>
+ *     <div slot="actions">
+ *       <nys-button variant="outline" label="Save & Exit" fullWidth></nys-button>
+ *     </div>
+ *   </nys-stepper>
+ *   <div class="nys-desktop:nys-grid-col-9" id="nys-stepper-content">
+ *     Loading...
  *   </div>
- * </nys-stepper>
+ * </div>
  * ```
- *
- * @example SPA / programmatic navigation
- * Two state variables drive the stepper in any framework or vanilla JS:
- * - `currentStep` (progress boundary) → set `current` on the matching step
- * - `viewingStep` (displayed content) → set `selected` on the matching step
- *
- * Always set both explicitly. Always call `e.preventDefault()` in the
- * `nys-step-click` listener to suppress href navigation. Do NOT nest inside a
- * `<form>` element.
- * ```js
- * let currentStep = 0; // furthest reached
- * let viewingStep = 0; // currently displayed
- *
- * function updateStepper(steps) {
- *   steps.forEach((step, i) => {
- *     step.toggleAttribute('current', i === currentStep);
- *     step.toggleAttribute('selected', i === viewingStep);
+ * @render Actions slot
+ * ```html
+ * <div class="nys-grid-row">
+ *   <nys-stepper
+ *     id="stepper"
+ *     name="stepper"
+ *     label="Register for Design System Office Hours"
+ *     class="nys-desktop:nys-grid-col-3"
+ *   >
+ *     <nys-step label="Personal Details" href="/nys-stepper/personal.html"></nys-step>
+ *     <nys-step label="Team Info" selected href="/nys-stepper/team.html"></nys-step>
+ *     <nys-step label="Usage Survey" current href="/nys-stepper/survey.html"></nys-step>
+ *     <nys-step label="Newsletter Opt-In" href="/nys-stepper/newsletter.html"></nys-step>
+ *     <div slot="actions">
+ *       <nys-button variant="outline" label="Save & Exit" fullWidth></nys-button>
+ *     </div>
+ *   </nys-stepper>
+ *   <div class="nys-desktop:nys-grid-col-9" id="nys-stepper-content">
+ *     Loading...
+ *   </div>
+ * </div>
+ * <script>
+ *   document.addEventListener("DOMContentLoaded", async () => {
+ *     const stepper = document.querySelector("nys-stepper");
+ *     if (stepper?.updateComplete) await stepper.updateComplete;
+ *     const selectedStep = document.querySelector("nys-step[selected]");
+ *     const href = selectedStep?.getAttribute("href");
+ *     if (!href) return;
+ *     const res = await fetch(href);
+ *     if (!res.ok) return;
+ *     const container = document.querySelector("#nys-stepper-content");
+ *     if (container) container.innerHTML = await res.text();
  *   });
- * }
- *
- * document.querySelector('nys-stepper').addEventListener('nys-step-click', (e) => {
- *   e.preventDefault();
- *   const steps = Array.from(document.querySelectorAll('nys-step'));
- *   const clicked = e.composedPath().find(el => el.tagName?.toLowerCase() === 'nys-step');
- *   const index = steps.indexOf(clicked);
- *   if (index !== -1) { viewingStep = index; updateStepper(steps); }
- * });
  *
- * // Advance to next step (call on form submit / "Continue" click)
- * function advance(steps) {
- *   if (currentStep < steps.length - 1) {
- *     currentStep++;
- *     viewingStep = currentStep;
- *     updateStepper(steps);
- *   }
- * }
+ *   document.addEventListener("nys-step-click", async (e) => {
+ *     const href = e.detail?.href;
+ *     if (!href) return;
+ *     e.preventDefault();
+ *     const res = await fetch(href);
+ *     if (!res.ok) return;
+ *     const container = document.querySelector("#nys-stepper-content");
+ *     if (container) container.innerHTML = await res.text();
+ *   });
+ * </script>
  * ```
  */
 export declare class NysStepper extends LitElement {

package/dist/packages/nys-tab/src/nys-tab.d.ts

@@ -20,16 +20,25 @@ import { LitElement } from "lit";
  *
  * @slot - No slots; content is derived from the `label` property.
  *
- * @example `<nys-tab>` and `<nys-tabpanel>` should always be wrapped by `<nys-tabgroup>`
+ * @example Disabled
  * ```html
- * <!-- Always place <nys-tab> elements inside a <nys-tabgroup>. -->
- * <nys-tabgroup name="My Tabs">
- *   <nys-tab label="Overview"></nys-tab>
+ * <nys-tabgroup name="Account Settings">
+ *   <nys-tab label="Profile"></nys-tab>
+ *   <nys-tab label="Security"></nys-tab>
+ *   <nys-tab label="Notifications" disabled></nys-tab>
+ *   <nys-tabpanel><p>Manage your profile information.</p></nys-tabpanel>
+ *   <nys-tabpanel><p>Update your password and 2FA settings.</p></nys-tabpanel>
+ *   <nys-tabpanel><p>Notification preferences (coming soon).</p></nys-tabpanel>
+ * </nys-tabgroup>
+ * ```
+ *
+ * @example Preselected
+ * ```html
+ * <nys-tabgroup name="Reports">
+ *   <nys-tab label="Summary"></nys-tab>
  *   <nys-tab label="Details" selected></nys-tab>
- *   <nys-tab label="Archived" disabled></nys-tab>
- *   <nys-tabpanel><p>Overview content</p></nys-tabpanel>
- *   <nys-tabpanel><p>Details content (shown by default)</p></nys-tabpanel>
- *   <nys-tabpanel><p>Archived content</p></nys-tabpanel>
+ *   <nys-tabpanel><p>Summary view</p></nys-tabpanel>
+ *   <nys-tabpanel><p>Detailed view (shown by default)</p></nys-tabpanel>
  * </nys-tabgroup>
  * ```
  */