@nysds/nys-checkbox 1.21.1 → 1.22.0

package/dist/nys-checkbox.d.ts

@@ -4,6 +4,51 @@ import "@nysds/nys-label";
 import "@nysds/nys-errormessage";
 import "@nysds/nys-icon";
 import "@nysds/nys-textinput";
+/** Detail payload for the `nys-change` event fired by `nys-checkbox`. */
+export interface NysCheckboxChangeDetail {
+    id: string;
+    checked: boolean;
+    name: string;
+    value: string;
+}
+/** The `nys-change` event fired by `nys-checkbox`. */
+export type NysCheckboxChangeEvent = CustomEvent<NysCheckboxChangeDetail>;
+/** Detail payload for the `nys-other-input` event fired by `nys-checkbox`. */
+export interface NysCheckboxOtherInputDetail {
+    id: string;
+    name: string;
+    value: string;
+}
+/** The `nys-other-input` event fired by `nys-checkbox`. */
+export type NysCheckboxOtherInputEvent = CustomEvent<NysCheckboxOtherInputDetail>;
+/**
+ * Detail payload for the `nys-error` group-coordination event.
+ * @internal
+ */
+export interface NysCheckboxErrorDetail {
+    id: string;
+    name: string;
+    type: "other";
+    message: string;
+    sourceCheckbox: NysCheckbox;
+}
+/**
+ * The `nys-error` group-coordination event.
+ * @internal
+ */
+export type NysCheckboxErrorEvent = CustomEvent<NysCheckboxErrorDetail>;
+/**
+ * Detail payload for the `nys-error-clear` group-coordination event.
+ * @internal
+ */
+export interface NysCheckboxErrorClearDetail {
+    sourceCheckbox: NysCheckbox;
+}
+/**
+ * The `nys-error-clear` group-coordination event.
+ * @internal
+ */
+export type NysCheckboxErrorClearEvent = CustomEvent<NysCheckboxErrorClearDetail>;
 /**
  * A checkbox input for binary choices or multi-select lists. Can be used standalone or in a `nys-checkboxgroup`.
  * Form-associated with validation via ElementInternals.
@@ -13,13 +58,27 @@ import "@nysds/nys-textinput";
  *
  * @summary Checkbox for binary choices or multi-select options.
  * @element nys-checkbox
+ * @formControl checked nys-change
  *
  * @slot description - Custom HTML description content.
  *
- * @fires nys-change - Fired when checked state changes. Detail: `{id, checked, name, value}`.
- * @fires nys-focus - Fired when checkbox gains focus.
- * @fires nys-blur - Fired when checkbox loses focus.
- * @fires nys-other-input - Fired when "other" text input value changes. Detail: `{id, name, value}`.
+ * @fires {NysCheckboxChangeEvent} nys-change - Fired when checked state changes. Detail: `{id, checked, name, value}`. Bubbles and composed.
+ * @fires {Event} nys-focus - Fired when checkbox gains focus. Bubbles and composed.
+ * @fires {Event} nys-blur - Fired when checkbox loses focus. Bubbles and composed.
+ * @fires {NysCheckboxOtherInputEvent} nys-other-input - Fired when "other" text input value changes. Detail: `{id, name, value}`.
+ * @fires {NysCheckboxErrorEvent} nys-error - Internal group coordination: reports an empty "other" field to the parent `nys-checkboxgroup`. Not part of the public API.
+ * @fires {NysCheckboxErrorClearEvent} nys-error-clear - Internal group coordination: clears a previously reported "other" field error. Not part of the public API.
+ *
+ * @usagedos
+ * - Use for binary decisions (agree/disagree), confirmation, or multi-select lists.
+ * - Use for selecting multiple options from a list of up to 10 choices.
+ * - Use `nys-checkboxgroup` to group checkboxes with a shared label and description.
+ *
+ * @usagedonts
+ * - Use when users need to select only one option. Use a `<nys-radiobutton>` for 1–6 choices or a <nys-select> for 7 or more.
+ * - Use a checkbox when changing its state immediately affects the system. Use a `<nys-toggle>` instead (e.g., enabling Dark Mode).
+ * - Use when you have more than 10 options to choose from.
+ * - Change the state of one checkbox based on another being clicked.
  *
  * @example Single
  * ```html
@@ -63,7 +122,12 @@ export declare class NysCheckbox extends NysFormControlElement {
     showError: boolean;
     /** Error message text. Shown only when `showError` is true. */
     errorMessage: string;
-    /** Internal: Set by parent checkboxgroup. Do not set manually. */
+    /**
+     * Set by the parent `nys-checkboxgroup` (via property) when all checkboxes
+     * in the group share a name, so the group owns the combined form value.
+     * Internal coordination state. Do not set manually.
+     * @internal
+     */
     groupExist: boolean;
     /** Renders as tile with larger clickable area. Apply to group for consistency. */
     tile: boolean;
@@ -74,7 +138,13 @@ export declare class NysCheckbox extends NysFormControlElement {
      * @default "md"
      */
     size: "sm" | "md";
+    /** Renders an additional free-text input when checked ("Other" option). */
     other: boolean;
+    /**
+     * Whether the "other" free-text field is in an error state. Managed by the
+     * component during validation; treat as read-only.
+     * @internal
+     */
     showOtherError: boolean;
     /**
      * Id of an element in the host's light-DOM tree to borrow the accessible name
@@ -129,8 +199,8 @@ export declare class NysCheckbox extends NysFormControlElement {
     checkValidity(): boolean;
     private _handleInvalid;
     private _manageLabelClick;
-    get _hasDescription(): boolean;
-    get _isStandalone(): boolean;
+    private get _hasDescription();
+    private get _isStandalone();
     /**
      * Event Handlers
      * --------------------------------------------------------------------------