@nysds/components 1.19.2 → 1.19.3

package/dist/packages/nys-checkbox/src/nys-checkboxgroup.d.ts

@@ -12,13 +12,87 @@ import { LitElement } from "lit";
  * @slot - Default slot for `nys-checkbox` elements.
  * @slot description - Custom HTML description content.
  *
- * @example Basic checkbox group
+ * @example Basic
  * ```html
  * <nys-checkboxgroup label="Select landmarks" required>
  *   <nys-checkbox name="landmarks" value="adirondacks" label="Adirondacks"></nys-checkbox>
  *   <nys-checkbox name="landmarks" value="niagara" label="Niagara Falls"></nys-checkbox>
  * </nys-checkboxgroup>
  * ```
+ *
+ * @example Tile
+ * ```html
+ * <nys-checkboxgroup label="Select landmarks" tile>
+ *   <nys-checkbox name="landmarks" value="adirondacks" label="Adirondacks"></nys-checkbox>
+ *   <nys-checkbox name="landmarks" value="niagara" label="Niagara Falls"></nys-checkbox>
+ * </nys-checkboxgroup>
+ * ```
+ *
+ * @example Required
+ * ```html
+ * <nys-checkboxgroup label="Select landmarks" required>
+ *   <nys-checkbox name="landmarks" value="adirondacks" label="Adirondacks"></nys-checkbox>
+ *   <nys-checkbox name="landmarks" value="niagara" label="Niagara Falls"></nys-checkbox>
+ * </nys-checkboxgroup>
+ * ```
+ *
+ * @example Optional
+ * ```html
+ * <nys-checkboxgroup label="Select landmarks" optional>
+ *   <nys-checkbox name="landmarks" value="adirondacks" label="Adirondacks"></nys-checkbox>
+ *   <nys-checkbox name="landmarks" value="niagara" label="Niagara Falls"></nys-checkbox>
+ * </nys-checkboxgroup>
+ * ```
+ *
+ * @example Disabled
+ * ```html
+ * <nys-checkboxgroup label="Select landmarks">
+ *   <nys-checkbox name="landmarks" value="adirondacks" label="Adirondacks" disabled></nys-checkbox>
+ *   <nys-checkbox name="landmarks" value="niagara" label="Niagara Falls" disabled></nys-checkbox>
+ * </nys-checkboxgroup>
+ * ```
+ *
+ * @example Size Small
+ * ```html
+ * <nys-checkboxgroup label="Select landmarks" size="sm">
+ *   <nys-checkbox name="landmarks" value="adirondacks" label="Adirondacks"></nys-checkbox>
+ *   <nys-checkbox name="landmarks" value="niagara" label="Niagara Falls"></nys-checkbox>
+ * </nys-checkboxgroup>
+ * ```
+ *
+ * @example Other Option
+ * ```html
+ * <nys-checkboxgroup label="Select landmarks">
+ *   <nys-checkbox name="landmarks" value="adirondacks" label="Adirondacks"></nys-checkbox>
+ *   <nys-checkbox name="landmarks" value="niagara" label="Niagara Falls"></nys-checkbox>
+ *   <nys-checkbox name="landmarks" value="" label="Other" other></nys-checkbox>
+ * </nys-checkboxgroup>
+ * ```
+ *
+ * @example Error Message
+ * ```html
+ * <nys-checkboxgroup label="Select landmarks" showError errorMessage="Please select at least one landmark">
+ *   <nys-checkbox name="landmarks" value="adirondacks" label="Adirondacks"></nys-checkbox>
+ *   <nys-checkbox name="landmarks" value="niagara" label="Niagara Falls"></nys-checkbox>
+ * </nys-checkboxgroup>
+ * ```
+ *
+ * @example Description
+ * ```html
+ * <nys-checkboxgroup label="Select landmarks" description="Choose wisely, you can only pick one.">
+ *   <nys-checkbox name="landmarks" value="adirondacks" label="Adirondacks"></nys-checkbox>
+ *   <nys-checkbox name="landmarks" value="niagara" label="Niagara Falls"></nys-checkbox>
+ * </nys-checkboxgroup>
+ * ```
+ *
+ * @example Description Slot
+ * ```html
+ * <nys-checkboxgroup label="Select landmarks">
+ *   <div slot="description">Your <strong>ABSOLUTE</strong> favorite one.</div>
+ *   <nys-checkbox name="landmarks" value="adirondacks" label="Adirondacks"></nys-checkbox>
+ *   <nys-checkbox name="landmarks" value="niagara" label="Niagara Falls"></nys-checkbox>
+ * </nys-checkboxgroup>
+ * ```
  */
 export declare class NysCheckboxgroup extends LitElement {
     static styles: import("lit").CSSResult;
@@ -60,6 +134,7 @@ export declare class NysCheckboxgroup extends LitElement {
     private _slottedDescriptionText;
     private _hasOtherError;
     private _otherErrorCheckbox;
+    private _hasSharedNames;
     private _internals;
     /**
      * Lifecycle methods
@@ -96,5 +171,7 @@ export declare class NysCheckboxgroup extends LitElement {
     private _handleChildErrorClear;
     private _handleOtherInput;
     private _checkOtherInputs;
+    /** Drupal-like naming support **/
+    private _checkSharedNames;
     render(): import("lit-html").TemplateResult<1>;
 }

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

@@ -19,6 +19,170 @@ import { LitElement } from "lit";
  * @fires nys-input - Fired on input change. Detail: `{ id, value }`.
  * @fires nys-focus - Fired when combobox receives focus.
  * @fires nys-blur - Fired when combobox loses focus.
+ *
+ *
+ * @example Basic
+ * ```html
+ * <nys-combobox label="Select your favorite fruit">
+ *   <option value="apple">Apple</option>
+ *   <option value="banana">Banana</option>
+ *   <option value="cherry">Cherry</option>
+ *   <option value="date">Date</option>
+ *   <option value="elderberry">Elderberry</option>
+ *   <option value="fig">Fig</option>
+ *   <option value="grape">Grape</option>
+ *   <option value="honeydew">Honeydew</option>
+ *   <option value="kiwi">Kiwi</option>
+ *   <option value="lemon">Lemon</option>
+ *   <option value="mango">Mango</option>
+ *   <option value="nectarine">Nectarine</option>
+ *   <option value="orange">Orange</option>
+ *   <option value="papaya">Papaya</option>
+ *   <option value="quince">Quince</option>
+ *   <option value="raspberry">Raspberry</option>
+ *   <option value="strawberry">Strawberry</option>
+ *   <option value="tangerine">Tangerine</option>
+ *   <option value="watermelon">Watermelon</option>
+ * </nys-combobox>
+ * ```
+ *
+ * @example Default Value
+ * ```html
+ * <nys-combobox label="Select your favorite fruit" value="mango">
+ *   <option value="apple">Apple</option>
+ *   <option value="banana">Banana</option>
+ *   <option value="mango" selected>Mango</option>
+ *   <option value="orange">Orange</option>
+ *   <option value="strawberry">Strawberry</option>
+ * </nys-combobox>
+ * ```
+ *
+ * @example Option Group
+ * ```html
+ * <nys-combobox label="Select a fruit" description="Fruits organized by category">
+ *   <optgroup label="Citrus">
+ *     <option value="lemon">Lemon</option>
+ *     <option value="lime">Lime</option>
+ *     <option value="orange">Orange</option>
+ *     <option value="grapefruit">Grapefruit</option>
+ *     <option value="tangerine">Tangerine</option>
+ *   </optgroup>
+ *   <optgroup label="Berries">
+ *     <option value="strawberry">Strawberry</option>
+ *     <option value="blueberry">Blueberry</option>
+ *     <option value="raspberry">Raspberry</option>
+ *     <option value="blackberry">Blackberry</option>
+ *     <option value="cranberry">Cranberry</option>
+ *   </optgroup>
+ *   <optgroup label="Tropical">
+ *     <option value="mango">Mango</option>
+ *     <option value="pineapple">Pineapple</option>
+ *     <option value="papaya">Papaya</option>
+ *     <option value="coconut">Coconut</option>
+ *     <option value="passionfruit">Passionfruit</option>
+ *   </optgroup>
+ *   <optgroup label="Stone Fruits">
+ *     <option value="peach">Peach</option>
+ *     <option value="plum">Plum</option>
+ *     <option value="cherry">Cherry</option>
+ *     <option value="apricot">Apricot</option>
+ *     <option value="nectarine">Nectarine</option>
+ *   </optgroup>
+ * </nys-combobox>
+ * ```
+ *
+ * @example Disabled
+ * ```html
+ * <nys-combobox label="Select your favorite fruit" disabled>
+ *   <option value="apple">Apple</option>
+ *   <option value="banana">Banana</option>
+ *   <option value="orange">Orange</option>
+ *   <option value="strawberry">Strawberry</option>
+ * </nys-combobox>
+ * ```
+ *
+ * @example Required
+ * ```html
+ * <nys-combobox label="Select your favorite fruit" required>
+ *   <option value="apple">Apple</option>
+ *   <option value="banana">Banana</option>
+ *   <option value="orange">Orange</option>
+ *   <option value="strawberry">Strawberry</option>
+ * </nys-combobox>
+ * ```
+ *
+ * @example Optional
+ * ```html
+ * <nys-combobox label="Select your favorite fruit" optional>
+ *   <option value="apple">Apple</option>
+ *   <option value="banana">Banana</option>
+ *   <option value="orange">Orange</option>
+ *   <option value="strawberry">Strawberry</option>
+ * </nys-combobox>
+ * ```
+ *
+ * @example Width Medium
+ * ```html
+ * <nys-combobox label="Select your favorite fruit" width="md">
+ *   <option value="apple">Apple</option>
+ *   <option value="banana">Banana</option>
+ *   <option value="orange">Orange</option>
+ *   <option value="strawberry">Strawberry</option>
+ * </nys-combobox>
+ * ```
+ *
+ * @example Width Large
+ * ```html
+ * <nys-combobox label="Select your favorite fruit" width="lg">
+ *   <option value="apple">Apple</option>
+ *   <option value="banana">Banana</option>
+ *   <option value="orange">Orange</option>
+ *   <option value="strawberry">Strawberry</option>
+ * </nys-combobox>
+ * ```
+ *
+ * @example Description
+ * ```html
+ * <nys-combobox label="Select your favorite fruit" description="Choose from the list of available fruits.">
+ *   <option value="apple">Apple</option>
+ *   <option value="banana">Banana</option>
+ *   <option value="orange">Orange</option>
+ *   <option value="strawberry">Strawberry</option>
+ * </nys-combobox>
+ * ```d
+ *
+ * @example Description Slot
+ * ```html
+ * <nys-combobox label="Select your favorite fruit">
+ *   <label slot="description">This is a description slot</label>
+ *   <option value="apple">Apple</option>
+ *   <option value="banana">Banana</option>
+ *   <option value="orange">Orange</option>
+ *   <option value="strawberry">Strawberry</option>
+ * </nys-combobox>
+ * ```
+ *
+ * @example Error Message
+ * ```html
+ * <nys-combobox label="Select your favorite fruit" showError errorMessage="Please select a fruit">
+ *   <option value="apple">Apple</option>
+ *   <option value="banana">Banana</option>
+ *   <option value="orange">Orange</option>
+ *   <option value="strawberry">Strawberry</option>
+ * </nys-combobox>
+ * ```
+ *
+ * @example Disabled Options
+ * ```html
+ * <nys-combobox label="Select your favorite fruit" description="Some fruits are out of season">
+ *   <option value="apple">Apple</option>
+ *   <option value="banana">Banana</option>
+ *   <option value="cherry" disabled>Cherry (Out of season)</option>
+ *   <option value="mango">Mango</option>
+ *   <option value="strawberry" disabled>Strawberry (Out of season)</option>
+ *   <option value="orange">Orange</option>
+ * </nys-combobox>
+ * ```
  */
 export declare class NysCombobox extends LitElement {
     static styles: import("lit").CSSResult;

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

@@ -9,12 +9,17 @@ import { LitElement } from "lit";
  * @fires nys-blur - Fired when input or calendar loses focus. Triggers validation.
  * @fires nys-input - Fired on date selection. Detail: `{id, value}`.
  *
- * @example Basic date picker
+ * @example Basic
  * ```html
- * <nys-datepicker label="Birth Date" required></nys-datepicker>
+ * <nys-datepicker
+ *  id="my-datepicker"
+ *  name="my-datepicker"
+ *  label="Schedule an appointment"
+ *  description="Enter in MM/DD/YYYY format"
+ * ></nys-datepicker>
  * ```
  *
- * @example With width and description
+ * @example Width Large
  * ```html
  * <nys-datepicker
  *   label="Event Date"
@@ -23,24 +28,75 @@ import { LitElement } from "lit";
  * </nys-datepicker>
  * ```
  *
- * @example Hide buttons, set start date
+ * @example Width Full
+ * ```html
+ * <nys-datepicker
+ *   label="Event Date"
+ *   description="Select the date of your event"
+ *   width="full">
+ * </nys-datepicker>
+ * ```
+ *
+ * @example Custom Start Date
  * ```html
  * <nys-datepicker
  *   label="Appointment"
- *   hideTodayButton
- *   hideClearButton
  *   startDate="2024-01-01">
  * </nys-datepicker>
  * ```
  *
- * @example With validation error message
+ * @example Without Buttons
+ * ```html
+ * <nys-datepicker
+ *   label="Appointment"
+ *   hideTodayButton
+ *   hideClearButton>
+ * </nys-datepicker>
+ * ```
+ *
+ * @example Error Message
  * ```html
  * <nys-datepicker
  *   label="Start Date"
- *   required
+ *   showError
  *   errorMessage="Please select a valid start date">
  * </nys-datepicker>
  * ```
+ *
+ * @example Date Range
+ * ```html
+ * <nys-datepicker
+ *   label="Select a date"
+ *   description="Only dates within April 4/5/2026 - 7/15/2026 are selectable"
+ *   minDate="2026-04-05"
+ *   maxDate="2026-07-15">
+ * </nys-datepicker>
+ * ```
+ *
+ * @example Disabled
+ * ```html
+ * <nys-datepicker
+ *   label="Disabled datepicker"
+ *   disabled
+ *   value="2025-01-15">
+ * </nys-datepicker>
+ * ```
+ *
+ * @example Required
+ * ```html
+ * <nys-datepicker
+ *   label="Start Date"
+ *   required>
+ * </nys-datepicker>
+ * ```
+ *
+ * @example Optional
+ * ```html
+ * <nys-datepicker
+ *   label="Start Date"
+ *   optional>
+ * </nys-datepicker>
+ * ```
  */
 export declare class NysDatepicker extends LitElement {
     static styles: import("lit").CSSResult;

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

@@ -7,12 +7,35 @@ import { LitElement } from "lit";
  * @summary Horizontal divider for visual separation of content sections.
  * @element nys-divider
  *
- * @example Basic divider
+ * @example Basic
  * ```html
  * <p>Section one content</p>
  * <nys-divider></nys-divider>
  * <p>Section two content</p>
  * ```
+ *
+ * @example Inverted
+ * ```html
+ * <p>Section one content</p>
+ * <nys-divider inverted></nys-divider>
+ * <p>Section two content</p>
+ * ```
+ *
+ * @render Inverted
+ * ```html
+ * <div style="display: flex; flex-direction: column; background-color: var(--nys-color-ink, #1b1b1b); color: var(--nys-color-ink-reverse, #fff); padding: var(--nys-space-200, 16px);">
+ *   <p>Section one content</p>
+ *   <nys-divider inverted></nys-divider>
+ *   <p>Section two content</p>
+ * </div>
+ * ```
+ *
+ * @example Subtle
+ * ```html
+ * <p>Section one content</p>
+ * <nys-divider subtle></nys-divider>
+ * <p>Section two content</p>
+ * ```
  */
 export declare class NysDivider extends LitElement {
     static styles: import("lit").CSSResult;

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

@@ -1,5 +1,6 @@
 import { LitElement } from "lit";
 import "./nys-dropdownmenuitem";
+type Position = "bottom-start" | "bottom-end" | "top-start" | "top-end";
 /**
  * Dropdown menus enable users to select an action from a list of options.
  * They’re commonly used to save space by grouping related actions, or to provide actions in a confined space.
@@ -7,25 +8,31 @@ import "./nys-dropdownmenuitem";
  * @summary Action menu with auto-positioning, keyboard support, and screen reader integration.
  * @element nys-dropdownmenu
  *
- * @example Basic dropdown
+ * @example Basic
  * ```html
- * <button id="my-trigger">Actions</button>
- * <nys-dropdownmenu for="my-trigger">
- *   <nys-dropdownmenuitem label="Edit" link="/edit"></nys-dropdownmenuitem>
- *   <nys-dropdownmenuitem label="Delete" link="/delete"></nys-dropdownmenuitem>
+ * <nys-button id="my-trigger-id" label="Open Menu"></nys-button>
+ * <nys-dropdownmenu id="my-dropdownmenu" for="my-trigger-id">
+ *   <nys-dropdownmenuitem label="Profile" href="/profile"></nys-dropdownmenuitem>
+ *   <nys-dropdownmenuitem label="Repositories & Github Pages" href="/repos"></nys-dropdownmenuitem>
+ *   <nys-dropdownmenuitem label="Organizations" href="/organizations"></nys-dropdownmenuitem>
+ *   <nys-dropdownmenuitem label="Sign out" href="/logout"></nys-dropdownmenuitem>
  * </nys-dropdownmenu>
+ * </div>
  * ```
  *
- * @example Positioned dropdown
+ * @render Basic
  * ```html
- * <button id="settings-btn">Settings</button>
- * <nys-dropdownmenu for="settings-btn" position="top-start">
- *   <nys-dropdownmenuitem label="Profile" link="/profile"></nys-dropdownmenuitem>
- *   <nys-dropdownmenuitem label="Logout" link="/logout"></nys-dropdownmenuitem>
- * </nys-dropdownmenu>
+ * <div style="margin: 200px; display: flex; justify-content: center; align-items: center;">
+ *   <nys-button id="my-trigger-id" label="Open Menu"></nys-button>
+ *   <nys-dropdownmenu id="my-dropdownmenu" for="my-trigger-id">
+ *     <nys-dropdownmenuitem label="Profile" href="/profile"></nys-dropdownmenuitem>
+ *     <nys-dropdownmenuitem label="Repositories & Github Pages" href="/repos"></nys-dropdownmenuitem>
+ *     <nys-dropdownmenuitem label="Organizations" href="/organizations"></nys-dropdownmenuitem>
+ *     <nys-dropdownmenuitem label="Sign out" href="/logout"></nys-dropdownmenuitem>
+ *   </nys-dropdownmenu>
+ * </div>
  * ```
  */
-type Position = "bottom-start" | "bottom-end" | "top-start" | "top-end";
 export declare class NysDropdownMenu extends LitElement {
     static styles: import("lit").CSSResult;
     for: string;

package/dist/packages/nys-dropdownmenu/src/nys-dropdownmenuitem.d.ts

@@ -7,16 +7,6 @@ import { LitElement } from "lit";
  *
  * @summary Dropdown item to display label and provide href link.
  * @element nys-dropdownmenuitem
- *
- * @example Basic item
- * ```html
- * <nys-dropdownmenuitem label="Edit" link="/edit"></nys-dropdownmenuitem>
- * ```
- *
- * @example Disabled item
- * ```html
- * <nys-dropdownmenuitem label="Delete" link="/delete" disabled></nys-dropdownmenuitem>
- * ```
  */
 export declare class NysDropdownMenuItem extends LitElement {
     static styles: import("lit").CSSResult;

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

@@ -7,6 +7,16 @@ import { LitElement } from "lit";
  *
  * @summary Internal error message display with icon and ARIA alert support.
  * @element nys-errormessage
+ *
+ * @example Basic
+ * ```html
+ * <nys-errormessage showError errorMessage="This is an error message"></nys-errormessage>
+ * ```
+ *
+ * @example Divider
+ * ```html
+ * <nys-errormessage showError errorMessage="This is an error message" showDivider></nys-errormessage>
+ * ```
  */
 export declare class NysErrorMessage extends LitElement {
     static styles: import("lit").CSSResult;

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

@@ -6,21 +6,88 @@ import "./nys-fileitem";
  *
  * Use for document uploads, image uploads, or any file submission. Enable `dropzone` for drag-and-drop UI.
  *
+ * Read or write the current selection via the `files` (`File[]`) and `value` (`File | null`)
+ * properties — useful for rehydrating state or binding from a framework form model.
+ * Setting them is silent (does not emit `nys-change`).
+ *
  * @summary File input with drag-and-drop, validation, and progress tracking.
  * @element nys-fileinput
  *
  * @slot description - Custom HTML description content.
  *
  * @fires nys-change - Fired when files are added or removed. Detail: `{id, files}`.
+ * @fires nys-blur - Fired when focus leaves the component. Triggers validation.
+ *
+ * @example Basic
+ * ```html
+ * <nys-fileinput
+ *   label="Upload a file"
+ * ></nys-fileinput>
+ * ```
+ *
+ * @example Dropzone
+ * ```html
+ * <nys-fileinput
+ *   label="Upload a file"
+ *   dropzone
+ * ></nys-fileinput>
+ * ```
+ *
+ * @example Multiple
+ * ```html
+ * <nys-fileinput
+ *   label="Upload a file"
+ *   multiple
+ * ></nys-fileinput>
+ * ```
+ *
+ * @example Accepted Filetypes
+ * ```html
+ * <nys-fileinput
+ *   label="Upload a file"
+ *   description="Accepted file types: .jpg, .png, .pdf"
+ *   accept="image/png, image/jpeg, .pdf"
+ * ></nys-fileinput>
+ * ```
+ *
+ * @example Width Large
+ * ```html
+ * <nys-fileinput
+ *   label="Upload a file"
+ *   width="lg"
+ * ></nys-fileinput>
+ * ```
+ *
+ * @example Width Large Dropzone
+ * ```html
+ * <nys-fileinput
+ *   label="Upload a file"
+ *   width="lg"
+ *   dropzone
+ * ></nys-fileinput>
+ * ```
+ *
+ * @example Disabled
+ * ```html
+ * <nys-fileinput
+ *   label="Upload a file"
+ *   disabled
+ * ></nys-fileinput>
+ * ```
  *
- * @example Single file upload
+ * @example Description
  * ```html
- * <nys-fileinput label="Upload document" accept=".pdf,.doc" required></nys-fileinput>
+ * <nys-fileinput
+ *   label="Upload a file"
+ *   description="Make sure the file is not blurry and readable"
+ * ></nys-fileinput>
  * ```
  *
- * @example Multiple files with dropzone
+ * @example Description Slot
  * ```html
- * <nys-fileinput label="Upload images" accept="image/*" multiple dropzone></nys-fileinput>
+ * <nys-fileinput label="Upload a file">
+ *   <div slot="description">Make sure the file is <strong>legible</strong></div>
+ * </nys-fileinput>
  * ```
  */
 export declare class NysFileinput extends LitElement {
@@ -69,6 +136,28 @@ export declare class NysFileinput extends LitElement {
     /** Adjusts colors for dark backgrounds. */
     inverted: boolean;
     private _selectedFiles;
+    /**
+     * The currently selected files. Read to get the current selection; set to
+     * replace it (e.g. rehydrating state after navigation, or binding from a
+     * framework form model). Property-only — a `File[]` cannot round-trip through
+     * an HTML attribute. Setting this is silent (does not emit `nys-change`),
+     * matching native input behavior and avoiding feedback loops in two-way bindings.
+     */
+    get files(): File[];
+    set files(incoming: File[]);
+    /**
+     * Single-file convenience accessor (parity with `nys-textinput`'s `value`).
+     * Reads the first selected file (or `null`); setting replaces the selection.
+     */
+    get value(): File | null;
+    set value(file: File | null);
+    /**
+     * Programmatically set the selection and await async validation/processing.
+     * Same as assigning `files`, but resolves once every file has finished its
+     * magic-byte validation and read — use when you need to read `checkValidity()`
+     * or the settled selection immediately after.
+     */
+    setFiles(incoming: File[]): Promise<void>;
     private _dragActive;
     private get _isDropDisabled();
     private get _buttonAriaLabel();
@@ -101,6 +190,7 @@ export declare class NysFileinput extends LitElement {
      */
     private _saveSelectedFiles;
     private _processFile;
+    private _handleBlur;
     private _dispatchChangeEvent;
     private _openFileDialog;
     private _handlePostFileSelectionFocus;