@k8slens/lds-form 0.53.1 → 0.53.3

package/lib/cjs/FormErrorMessage/FormErrorMessage.d.ts

@@ -1,13 +1,17 @@
 import React from "react";
+/** Props for the FormErrorMessage component. */
 export interface FormErrorMessageProps extends Omit<React.LabelHTMLAttributes<HTMLLabelElement>, "id" | "htmlFor"> {
+    /** HTML `id` for the error message element. */
     id: string;
+    /** `id` of the form control this error message describes. */
     forId: string;
+    /** List of error strings to display. */
     errors: Array<string>;
 }
 /**
- * Form error message component used by `FormField`
+ * Displays validation errors as a list associated with a form control.
  *
- * `import { FormErrorMessage } from @k8slens/lds-form`
+ * Usage: `import { FormErrorMessage } from "@k8slens/lds-form"`
  */
 declare const FormErrorMessage: ({ id, forId, errors, ...props }: FormErrorMessageProps) => React.JSX.Element;
 export default FormErrorMessage;

package/lib/cjs/FormField/FormField.d.ts

@@ -3,20 +3,26 @@ import { FormLabelProps } from "../FormLabel/FormLabel";
 import { FormErrorMessageProps } from "../FormErrorMessage/FormErrorMessage";
 import { ErrorParser } from "../common/useFormComponentData";
 import { Validator } from "../common/validation";
+/** Props for the FormField component. */
 export interface FormFieldProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "id"> {
-    /** the `id` of the child form component (e.g. `input`) */
+    /** The `id` of the child form control (e.g. `<input>`). Optional because HeadlessUI Combobox omits it on first render. */
     id: string | undefined;
-    /** the label text to be rendered in  `<label>{label}</label>` */
+    /** Label text rendered inside a `<label>` element. */
     label: string;
-    /** the identifier of the `<ErrorMessage id={labelId} />` of the child form component, should not be the same as `props.id` */
+    /** Unique `id` for the error message element. Must differ from `id`. */
     errorId: string;
-    /** the identifier of the `<label id={labelId} />` of the child form component, should not be the same as `props.id` */
+    /** Unique `id` for the label element. Must differ from `id`. */
     labelId: string;
+    /** Whether the field is required. */
     required?: boolean;
+    /** Validation error strings to display. */
     errors?: Array<string>;
+    /** Props forwarded to the `FormLabel` component. */
     labelProps?: Partial<FormLabelProps>;
+    /** Props forwarded to the `FormErrorMessage` component. */
     errorProps?: Partial<Omit<FormErrorMessageProps, "forId" | "id">>;
 }
+/** Shared props for form components that combine a field with validation and error display. */
 export interface FormFieldComponentProps<T, 
 /** Custom error string(s) to be used in validation & error parser */
 CustomError extends string> extends Pick<FormFieldProps, "label" | "labelProps" | "errorProps"> {
@@ -24,13 +30,12 @@ CustomError extends string> extends Pick<FormFieldProps, "label" | "labelProps"
     validate?: Validator<T, CustomError>;
     /** Return error message for given error key. */
     errorParser?: ErrorParser<T, CustomError>;
+    /** Called when the value changes with the new value and its validity. */
     onChange?: (value: T, isValid: boolean) => void;
 }
 /**
- * Generic form field component with label and error message.
+ * Generic form field wrapper that renders a label, child control, and error messages.
  *
- * `import { FormField } from @k8slens/lds-form`
- *
- * See `FormComponent`for individual form components.
+ * Usage: `import { FormField } from "@k8slens/lds-form"`
  */
 export default function FormField({ id, label, labelId, errorId, required, errors, children, labelProps, errorProps, ...props }: PropsWithChildren<FormFieldProps>): React.JSX.Element;

package/lib/cjs/FormLabel/FormLabel.d.ts

@@ -1,16 +1,24 @@
 import React, { type ReactElement } from "react";
+/** Props for the FormLabel component. */
 export interface FormLabelProps extends Omit<React.LabelHTMLAttributes<HTMLLabelElement>, "id" | "htmlFor"> {
+    /** HTML `id` for the label element. */
     id: string;
+    /** `id` of the form control this label is for. */
     forId: string;
+    /** Label content — a string or React element. */
     label: ReactElement | string;
+    /** Whether the associated field is required (used together with `showRequired`). */
     required?: boolean;
-    /** Show required asterisk and visually hidden "required" text. Default: false */
+    /**
+     * Show required asterisk and visually hidden "required" text.
+     * @default false
+     */
     showRequired?: boolean;
 }
 /**
- * Form label component used by `FormField`
+ * A `<label>` element with optional required indicator. Used internally by `FormField`.
  *
- * `import { FormLabel } from @k8slens/lds-form`
+ * Usage: `import { FormLabel } from "@k8slens/lds-form"`
  */
 declare const FormLabel: ({ id, forId, label, showRequired, required, ...props }: FormLabelProps) => React.JSX.Element;
 export default FormLabel;

package/lib/cjs/FormSwitchGroup/FormSwitchGroup.d.ts

@@ -1,18 +1,30 @@
 import React, { PropsWithChildren, ReactNode } from "react";
 import { type SwitchProps } from "@k8slens/lds/lib/es/Switch/Switch.d";
 import { FormFieldComponentProps } from "../FormField/FormField";
+/** Describes a single switch within a `FormSwitchGroup`. */
 export declare type SwitchValue = {
+    /** Unique identifier for this switch. */
     id: string;
+    /** Label displayed next to the switch. */
     label: string;
+    /** Whether the switch is on. */
     checked: boolean | undefined;
+    /** Whether this individual switch is disabled. */
     disabled?: boolean;
+    /** Optional description rendered below the label. */
     description?: string | ReactNode;
 };
+/** Props for the FormSwitchGroup component. */
 export interface FormSwitchGroupProps<CustomError extends string> extends Omit<FormFieldComponentProps<number, CustomError>, "onChange" | "value">, Omit<SwitchProps, "value" | "onChange" | "label"> {
+    /** HTML `id` attribute for the field. */
     id?: string;
+    /** Props forwarded to the wrapper div. */
     wrapperProps?: React.HTMLAttributes<HTMLDivElement>;
+    /** Array of switch items to render. */
     values: Array<SwitchValue>;
+    /** Called when any switch changes with the full array and the IDs that changed. */
     onChange(values: Array<SwitchValue>, updatedKeys: Array<string>): void;
+    /** Validation error strings to display. */
     errors?: Array<string>;
 }
 /**

package/lib/es/FormErrorMessage/FormErrorMessage.d.ts

@@ -1,13 +1,17 @@
 import React from "react";
+/** Props for the FormErrorMessage component. */
 export interface FormErrorMessageProps extends Omit<React.LabelHTMLAttributes<HTMLLabelElement>, "id" | "htmlFor"> {
+    /** HTML `id` for the error message element. */
     id: string;
+    /** `id` of the form control this error message describes. */
     forId: string;
+    /** List of error strings to display. */
     errors: Array<string>;
 }
 /**
- * Form error message component used by `FormField`
+ * Displays validation errors as a list associated with a form control.
  *
- * `import { FormErrorMessage } from @k8slens/lds-form`
+ * Usage: `import { FormErrorMessage } from "@k8slens/lds-form"`
  */
 declare const FormErrorMessage: ({ id, forId, errors, ...props }: FormErrorMessageProps) => React.JSX.Element;
 export default FormErrorMessage;

package/lib/es/FormField/FormField.d.ts

@@ -3,20 +3,26 @@ import { FormLabelProps } from "../FormLabel/FormLabel";
 import { FormErrorMessageProps } from "../FormErrorMessage/FormErrorMessage";
 import { ErrorParser } from "../common/useFormComponentData";
 import { Validator } from "../common/validation";
+/** Props for the FormField component. */
 export interface FormFieldProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "id"> {
-    /** the `id` of the child form component (e.g. `input`) */
+    /** The `id` of the child form control (e.g. `<input>`). Optional because HeadlessUI Combobox omits it on first render. */
     id: string | undefined;
-    /** the label text to be rendered in  `<label>{label}</label>` */
+    /** Label text rendered inside a `<label>` element. */
     label: string;
-    /** the identifier of the `<ErrorMessage id={labelId} />` of the child form component, should not be the same as `props.id` */
+    /** Unique `id` for the error message element. Must differ from `id`. */
     errorId: string;
-    /** the identifier of the `<label id={labelId} />` of the child form component, should not be the same as `props.id` */
+    /** Unique `id` for the label element. Must differ from `id`. */
     labelId: string;
+    /** Whether the field is required. */
     required?: boolean;
+    /** Validation error strings to display. */
     errors?: Array<string>;
+    /** Props forwarded to the `FormLabel` component. */
     labelProps?: Partial<FormLabelProps>;
+    /** Props forwarded to the `FormErrorMessage` component. */
     errorProps?: Partial<Omit<FormErrorMessageProps, "forId" | "id">>;
 }
+/** Shared props for form components that combine a field with validation and error display. */
 export interface FormFieldComponentProps<T, 
 /** Custom error string(s) to be used in validation & error parser */
 CustomError extends string> extends Pick<FormFieldProps, "label" | "labelProps" | "errorProps"> {
@@ -24,13 +30,12 @@ CustomError extends string> extends Pick<FormFieldProps, "label" | "labelProps"
     validate?: Validator<T, CustomError>;
     /** Return error message for given error key. */
     errorParser?: ErrorParser<T, CustomError>;
+    /** Called when the value changes with the new value and its validity. */
     onChange?: (value: T, isValid: boolean) => void;
 }
 /**
- * Generic form field component with label and error message.
+ * Generic form field wrapper that renders a label, child control, and error messages.
  *
- * `import { FormField } from @k8slens/lds-form`
- *
- * See `FormComponent`for individual form components.
+ * Usage: `import { FormField } from "@k8slens/lds-form"`
  */
 export default function FormField({ id, label, labelId, errorId, required, errors, children, labelProps, errorProps, ...props }: PropsWithChildren<FormFieldProps>): React.JSX.Element;

package/lib/es/FormLabel/FormLabel.d.ts

@@ -1,16 +1,24 @@
 import React, { type ReactElement } from "react";
+/** Props for the FormLabel component. */
 export interface FormLabelProps extends Omit<React.LabelHTMLAttributes<HTMLLabelElement>, "id" | "htmlFor"> {
+    /** HTML `id` for the label element. */
     id: string;
+    /** `id` of the form control this label is for. */
     forId: string;
+    /** Label content — a string or React element. */
     label: ReactElement | string;
+    /** Whether the associated field is required (used together with `showRequired`). */
     required?: boolean;
-    /** Show required asterisk and visually hidden "required" text. Default: false */
+    /**
+     * Show required asterisk and visually hidden "required" text.
+     * @default false
+     */
     showRequired?: boolean;
 }
 /**
- * Form label component used by `FormField`
+ * A `<label>` element with optional required indicator. Used internally by `FormField`.
  *
- * `import { FormLabel } from @k8slens/lds-form`
+ * Usage: `import { FormLabel } from "@k8slens/lds-form"`
  */
 declare const FormLabel: ({ id, forId, label, showRequired, required, ...props }: FormLabelProps) => React.JSX.Element;
 export default FormLabel;

package/lib/es/FormSwitchGroup/FormSwitchGroup.d.ts

@@ -1,18 +1,30 @@
 import React, { PropsWithChildren, ReactNode } from "react";
 import { type SwitchProps } from "@k8slens/lds/lib/es/Switch/Switch.d";
 import { FormFieldComponentProps } from "../FormField/FormField";
+/** Describes a single switch within a `FormSwitchGroup`. */
 export declare type SwitchValue = {
+    /** Unique identifier for this switch. */
     id: string;
+    /** Label displayed next to the switch. */
     label: string;
+    /** Whether the switch is on. */
     checked: boolean | undefined;
+    /** Whether this individual switch is disabled. */
     disabled?: boolean;
+    /** Optional description rendered below the label. */
     description?: string | ReactNode;
 };
+/** Props for the FormSwitchGroup component. */
 export interface FormSwitchGroupProps<CustomError extends string> extends Omit<FormFieldComponentProps<number, CustomError>, "onChange" | "value">, Omit<SwitchProps, "value" | "onChange" | "label"> {
+    /** HTML `id` attribute for the field. */
     id?: string;
+    /** Props forwarded to the wrapper div. */
     wrapperProps?: React.HTMLAttributes<HTMLDivElement>;
+    /** Array of switch items to render. */
     values: Array<SwitchValue>;
+    /** Called when any switch changes with the full array and the IDs that changed. */
     onChange(values: Array<SwitchValue>, updatedKeys: Array<string>): void;
+    /** Validation error strings to display. */
     errors?: Array<string>;
 }
 /**

package/llms.txt

@@ -29,53 +29,87 @@ import "@k8slens/lds-form/lib/es/index.css";
 
 ### FormField
 
-Wrapper component that groups label, input, and error message.
+Generic form field wrapper that renders a label, child control, and error messages.
 
 ```tsx
 import { FormField, FormLabel, FormInput, FormErrorMessage } from "@k8slens/lds-form";
 
-<FormField>
-  <FormLabel>Email</FormLabel>
-  <FormInput type="email" />
-  <FormErrorMessage>Please enter a valid email</FormErrorMessage>
+<FormField id="email" label="Email" labelId="email-label" errorId="email-error">
+  <input id="email" type="email" />
 </FormField>
 ```
 
+**FormFieldProps**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `id` | `string \| undefined` | — | The `id` of the child form control. Optional because HeadlessUI Combobox omits it on first render. |
+| `label` | `string` | — | Label text rendered inside a `<label>` element. |
+| `errorId` | `string` | — | Unique `id` for the error message element. Must differ from `id`. |
+| `labelId` | `string` | — | Unique `id` for the label element. Must differ from `id`. |
+| `required` | `boolean` | — | Whether the field is required. |
+| `errors` | `Array<string>` | — | Validation error strings to display. |
+| `labelProps` | `Partial<FormLabelProps>` | — | Props forwarded to the `FormLabel` component. |
+| `errorProps` | `Partial<Omit<FormErrorMessageProps, "forId" \| "id">>` | — | Props forwarded to the `FormErrorMessage` component. |
+
+**FormFieldComponentProps** — shared props for form components combining a field with validation:
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `label` | `string` | Label text. |
+| `labelProps` | `Partial<FormLabelProps>` | Props forwarded to `FormLabel`. |
+| `errorProps` | `Partial<...>` | Props forwarded to `FormErrorMessage`. |
+| `validate` | `Validator<T, CustomError>` | Validation function — return `undefined` if valid, error key(s) if invalid. |
+| `errorParser` | `ErrorParser<T, CustomError>` | Return error message string for a given error key. |
+| `onChange` | `(value: T, isValid: boolean) => void` | Called when value changes with new value and validity. |
+
 ### FormInput
 
-Input with label, validation, and error handling. Wraps core Input in FormField.
+Input with label, validation, and error handling. Wraps core `Input` in `FormField`.
 
 ```tsx
-import { FormInput } from "@k8slens/lds-form";
-
 <FormInput name="email" type="email" label="Email" value={email} onChange={setEmail} />
 ```
 
 ### FormLabel
 
-Label component for form fields.
+A `<label>` element with optional required indicator. Used internally by `FormField`.
 
-### FormErrorMessage
+```tsx
+<FormLabel id="email-label" forId="email" label="Email" required showRequired />
+```
 
-Displays validation error messages.
+**FormLabelProps**
 
-### FormSwitchGroup
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `id` | `string` | — | HTML `id` for the label element. |
+| `forId` | `string` | — | `id` of the form control this label is for. |
+| `label` | `ReactElement \| string` | — | Label content — a string or React element. |
+| `required` | `boolean` | — | Whether the associated field is required (used together with `showRequired`). |
+| `showRequired` | `boolean` | `false` | Show required asterisk and visually hidden "required" text. |
 
-Multiple toggle switches with shared label and error handling.
+### FormErrorMessage
 
-```tsx
-import { FormSwitchGroup } from "@k8slens/lds-form";
+Displays validation errors as a list associated with a form control.
 
-<FormSwitchGroup label="Notifications" values={options} onChange={setOptions} />
+```tsx
+<FormErrorMessage id="email-error" forId="email" errors={["Please enter a valid email"]} />
 ```
 
+**FormErrorMessageProps**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `id` | `string` | HTML `id` for the error message element. |
+| `forId` | `string` | `id` of the form control this error message describes. |
+| `errors` | `Array<string>` | List of error strings to display. |
+
 ### FormTextarea
 
 Textarea wrapped in a FormField with label and error handling. Combines FormField + Textarea from @k8slens/lds.
 
 ```tsx
-import { FormTextarea } from "@k8slens/lds-form";
-
 <FormTextarea
   name="description"
   label="Description"
@@ -86,16 +120,33 @@ import { FormTextarea } from "@k8slens/lds-form";
 />
 ```
 
-**FormTextarea Props:**
-- Extends `TextareaProps` from @k8slens/lds Textarea component
-- `name` (required) - Field name for form submission
-- `label` - Field label text
-- `labelProps` - Props passed to FormLabel
-- `errorProps` - Props passed to FormErrorMessage
-- `errors` - Array of error messages to display
-- `required` (default: false) - Whether the field is required
-- `id` - Optional field ID (auto-generated if not provided)
-- All Textarea props: `maxLength`, `autoResize`, `icon`, `placeholder`, etc.
+**Props:** Extends `TextareaProps` from @k8slens/lds + `FormFieldComponentProps`. Adds `name` (required) for form submission. Accepts all Textarea props (`maxLength`, `autoResize`, `icon`, `placeholder`, etc.).
+
+### FormSwitchGroup
+
+Multiple toggle switches with shared label and error handling.
+
+```tsx
+<FormSwitchGroup label="Notifications" values={options} onChange={setOptions} />
+```
+
+**SwitchValue** — describes a single switch item:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `string` | Unique identifier for this switch. |
+| `label` | `string` | Label displayed next to the switch. |
+| `checked` | `boolean \| undefined` | Whether the switch is on. |
+| `disabled` | `boolean` | Whether this individual switch is disabled. |
+| `description` | `string \| ReactNode` | Optional description rendered below the label. |
+
+**FormSwitchGroupProps** — extends `FormFieldComponentProps`:
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `values` | `Array<SwitchValue>` | Array of switch items to render. |
+| `onChange` | `(values: Array<SwitchValue>, updatedKeys: Array<string>) => void` | Called when any switch changes with the full array and the IDs that changed. |
+| `wrapperProps` | `React.HTMLAttributes<HTMLDivElement>` | Props forwarded to the wrapper div. |
 
 ## Hooks
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k8slens/lds-form",
-  "version": "0.53.1",
+  "version": "0.53.3",
   "description": "Lens Design System – React Form components",
   "author": "Mirantis Inc",
   "license": "MIT",
@@ -29,10 +29,10 @@
     "format": "oxlint --fix . && prettier --write ."
   },
   "dependencies": {
-    "@k8slens/lds": "^0.58.1"
+    "@k8slens/lds": "^0.58.3"
   },
   "devDependencies": {
-    "@k8slens/lds-tokens": "^0.59.1",
+    "@k8slens/lds-tokens": "^0.59.3",
     "@rollup/plugin-node-resolve": "15.0.2",
     "@storybook/react": "6.5.16",
     "@testing-library/react": "14.0.0",
@@ -56,5 +56,5 @@
       "\\.svg": "<rootDir>/../../__mocks__/SVGStub.js"
     }
   },
-  "gitHead": "5eda1efad729aad60ce149aeca5e9dbd7f92ec3a"
+  "gitHead": "9897b4ea31cc01ec39bdd3200b0bacbdd760e351"
 }