@ceed/cds 1.29.0 → 1.30.0

package/dist/components/inputs/Input.md

@@ -2,9 +2,7 @@
 
 ## Introduction
 
-The Input component is a fundamental form element for capturing text input from users. It supports various visual styles, sizes, and states to accommodate different use cases across forms, search fields, and data entry interfaces.
-
-Input comes with built-in form integration features such as labels, helper text, error states, and clearable functionality. It also provides specialized behavior for password fields with an automatic visibility toggle.
+Input is a single-line text field component for capturing user input. Built on Joy UI's Input with Framer Motion animation support, it includes built-in form field composition (`label`, `helperText`, `error`) so you can build complete form fields without manual `FormControl` wrappers. It supports clearable inputs, password visibility toggling, and start/end decorators.
 
 ```tsx
 <Input />
@@ -35,20 +33,8 @@ Input comes with built-in form integration features such as labels, helper text,
 
 > **Use built-in form props**
 >
-> This component natively supports `label`, `helperText`, `error`, and `required` props.
-> When building forms, use these built-in props instead of manually composing labels and helper text with Typography or FormControl.
->
-> ```tsx
-> // Recommended: use built-in props
-> <Input label="Email" helperText="We'll never share your email." error={!isValid} />
->
-> // Not recommended: manual composition with Typography
-> <FormControl>
->   <Typography component="label">Email</Typography>
->   <Input />
->   <Typography level="body-xs">We'll never share your email.</Typography>
-> </FormControl>
-> ```
+> This component natively supports `label` and `helperText` props.
+> When building forms, use these built-in props instead of manually composing labels and helper text with Typography.
 
 ## Usage
 
@@ -56,29 +42,22 @@ Input comes with built-in form integration features such as labels, helper text,
 import { Input } from '@ceed/cds';
 
 function MyComponent() {
+  const [value, setValue] = useState('');
+
   return (
     <Input
-      label="Username"
-      placeholder="Enter your username"
-      helperText="Must be at least 3 characters"
+      label="Name"
+      placeholder="Enter your name"
+      value={value}
+      onChange={(e) => setValue(e.target.value)}
     />
   );
 }
 ```
 
-## Examples
-
-### Basic Input
-
-The default Input renders a single-line text field. Without any additional props, it uses the `outlined` variant at `md` size.
-
-```tsx
-<Input />
-```
-
-### Variants
+## Variants
 
-Input supports four visual variants: `solid`, `soft`, `outlined`, and `plain`. Use `outlined` (default) for most form contexts, and `soft` or `plain` for inline or subtle placements.
+Input supports four visual styles: `outlined` (default), `solid`, `soft`, and `plain`.
 
 ```tsx
 <>
@@ -89,9 +68,9 @@ Input supports four visual variants: `solid`, `soft`, `outlined`, and `plain`. U
 </>
 ```
 
-### Sizes
+## Sizes
 
-Input comes in three sizes: `sm`, `md`, and `lg`. Choose a size that fits the surrounding UI density.
+Three sizes are available: `sm`, `md` (default), and `lg`.
 
 ```tsx
 <>
@@ -105,7 +84,7 @@ Input comes in three sizes: `sm`, `md`, and `lg`. Choose a size that fits the su
 
 ### Label
 
-Use the `label` prop to display a label above the Input. This is the recommended way to associate a label with the input field.
+The `label` prop renders a form label above the input.
 
 ```tsx
 <>
@@ -115,7 +94,7 @@ Use the `label` prop to display a label above the Input. This is the recommended
 
 ### Helper Text
 
-Use the `helperText` prop to provide additional guidance below the Input.
+The `helperText` prop renders descriptive text below the input.
 
 ```tsx
 <>
@@ -127,7 +106,7 @@ Use the `helperText` prop to provide additional guidance below the Input.
 
 ### Disabled
 
-Set `disabled` to prevent user interaction. Disabled inputs are visually dimmed and do not receive focus.
+A disabled input cannot be focused or interacted with.
 
 ```tsx
 <Input disabled />
@@ -135,7 +114,7 @@ Set `disabled` to prevent user interaction. Disabled inputs are visually dimmed
 
 ### Error
 
-Set `error` to indicate a validation failure. Combine with `helperText` to explain the error.
+Set `error` to visually indicate a validation failure. Combine with `helperText` to display an error message.
 
 ```tsx
 <>
@@ -145,7 +124,7 @@ Set `error` to indicate a validation failure. Combine with `helperText` to expla
 
 ### Required
 
-Set `required` to mark the field as mandatory. This adds a visual indicator to the label.
+Set `required` to mark the field as required. An asterisk is added to the label automatically.
 
 ```tsx
 <Input
@@ -156,20 +135,9 @@ Set `required` to mark the field as mandatory. This adds a visual indicator to t
 />
 ```
 
-## Form Control
-
-Combine `label`, `helperText`, and `error` props to build a complete form control. This is the recommended pattern for form fields.
-
-```tsx
-<>
-  <Input placeholder="Type in here..." helperText="I'm helper text" label="Label" />
-  <Input placeholder="Invalid input" helperText="I'm helper text" label="Label" error />
-</>
-```
-
 ## Decorators
 
-Use `startDecorator` and `endDecorator` to place icons, buttons, or other elements at the start and end of the input field.
+Use `startDecorator` and `endDecorator` to add icons, buttons, or other elements at the start or end of the input field.
 
 ```tsx
 <Stack spacing={3}>
@@ -209,7 +177,7 @@ width: 300
 </Stack>
 ```
 
-When using `endDecorator` together with `enableClearable`, the clear button is placed before the end decorator:
+When using `endDecorator` together with `enableClearable`, both elements are displayed side by side:
 
 ```tsx
 <Input
@@ -222,7 +190,7 @@ When using `endDecorator` together with `enableClearable`, the clear button is p
 
 ## Clearable Input
 
-Set `enableClearable` to show a clear button when the input has a value. Clicking the button clears the input and returns focus to the field.
+Set `enableClearable` to show a clear button when the input has a value. Clicking the button clears the input content.
 
 ```tsx
 <>
@@ -230,9 +198,16 @@ Set `enableClearable` to show a clear button when the input has a value. Clickin
 </>
 ```
 
+```tsx
+<Input
+  enableClearable
+  placeholder="Type something and clear it"
+/>
+```
+
 ## Password Input
 
-Setting `type="password"` automatically adds a visibility toggle button, allowing users to reveal or hide their password.
+Setting `type="password"` creates a password field with an automatic visibility toggle button.
 
 ```tsx
 <Stack spacing={3}>
@@ -247,9 +222,17 @@ Setting `type="password"` automatically adds a visibility toggle button, allowin
 </Stack>
 ```
 
-### Password Limitations
+### Disabling the Password Toggle
 
-When `type="password"` is used, the `endDecorator` prop is not supported because the password toggle button occupies that position.
+Use `disableTogglePasswordButton` to hide the visibility toggle button on password inputs.
+
+```tsx
+<Input type="password" disableTogglePasswordButton placeholder="Password" />
+```
+
+### Password Input Limitations
+
+Password inputs (`type="password"`) do not support custom `endDecorator` because the password toggle button occupies that slot. If you provide `endDecorator` with a password input, the component logs a warning and ignores it.
 
 ```tsx
 <Stack spacing={3}>
@@ -261,62 +244,69 @@ When `type="password"` is used, the `endDecorator` prop is not supported because
 </Stack>
 ```
 
-## State Management
-
-### Controlled Component
+## Form Control
 
-Use `value` and `onChange` to manage the input state externally. This is useful when you need to synchronize the value with other components or perform validation on change.
+Combining `label`, `helperText`, and `error` produces a complete form field.
 
 ```tsx
 <>
-  <Input placeholder="Type in here…" label="Label" enableClearable value={value} onChange={handleChange} />
+  <Input placeholder="Type in here..." helperText="I'm helper text" label="Label" />
+  <Input placeholder="Invalid input" helperText="I'm helper text" label="Label" error />
 </>
 ```
 
-### Uncontrolled Component
+```tsx
+<Input
+  label="Email"
+  helperText="We'll never share your email"
+  required
+/>
+
+<Input
+  label="Email"
+  error
+  helperText="Invalid email address"
+/>
+```
+
+## Controlled / Uncontrolled
 
-Use `defaultValue` for simpler cases where you do not need to track the value in state. The input manages its own value internally.
+### Controlled
+
+Use `value` and `onChange` for controlled behavior.
 
 ```tsx
-<Input defaultValue="Initial text" placeholder="Type in here..." />
+<>
+  <Input placeholder="Type in here…" label="Label" enableClearable value={value} onChange={handleChange} />
+</>
 ```
 
-## Common Use Cases
+```tsx
+const [value, setValue] = useState('');
 
-### Login Form
+<Input
+  value={value}
+  onChange={(e) => setValue(e.target.value)}
+  placeholder="Controlled input"
+/>
+```
 
-```tsx
-function LoginForm() {
-  const [email, setEmail] = useState('');
-  const [password, setPassword] = useState('');
+### Uncontrolled
 
-  return (
-    <Stack spacing={2}>
-      <Input
-        label="Email"
-        type="email"
-        placeholder="you@example.com"
-        required
-        value={email}
-        onChange={(e) => setEmail(e.target.value)}
-      />
-      <Input
-        label="Password"
-        type="password"
-        placeholder="Enter your password"
-        required
-        value={password}
-        onChange={(e) => setPassword(e.target.value)}
-      />
-      <Button type="submit">Sign In</Button>
-    </Stack>
-  );
-}
+Use `defaultValue` for uncontrolled behavior.
+
+```tsx
+<Input defaultValue="Initial value" placeholder="Uncontrolled input" />
 ```
 
-### Search Field with Clear
+## Common Use Cases
+
+### Search Field
 
 ```tsx
+import { Input } from '@ceed/cds';
+import SearchIcon from '@mui/icons-material/Search';
+
 function SearchField({ onSearch }) {
   const [query, setQuery] = useState('');
 
@@ -335,80 +325,152 @@ function SearchField({ onSearch }) {
 }
 ```
 
+### Login Form
+
+```tsx
+import { Input, Button, Stack } from '@ceed/cds';
+
+function LoginForm({ onSubmit }) {
+  return (
+    <form onSubmit={onSubmit}>
+      <Stack spacing={2}>
+        <Input
+          label="Email"
+          type="email"
+          required
+          placeholder="Enter your email"
+        />
+        <Input
+          label="Password"
+          type="password"
+          required
+          placeholder="Enter your password"
+        />
+        <Button type="submit">Sign In</Button>
+      </Stack>
+    </form>
+  );
+}
+```
+
 ### Form with Validation
 
 ```tsx
-function ProfileForm() {
-  const [name, setName] = useState('');
+import { useState } from 'react';
+import { Input, Button, Stack } from '@ceed/cds';
+
+function ValidatedForm() {
+  const [email, setEmail] = useState('');
   const [submitted, setSubmitted] = useState(false);
-  const hasError = submitted && name.trim().length === 0;
+  const isValid = /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
 
   return (
-    <Stack spacing={2}>
-      <Input
-        label="Full Name"
-        required
-        placeholder="John Doe"
-        value={name}
-        onChange={(e) => setName(e.target.value)}
-        error={hasError}
-        helperText={hasError ? 'Name is required' : 'Enter your legal name'}
-      />
-      <Button onClick={() => setSubmitted(true)}>Save</Button>
-    </Stack>
+    <form onSubmit={(e) => { e.preventDefault(); setSubmitted(true); }}>
+      <Stack spacing={2}>
+        <Input
+          label="Email"
+          required
+          value={email}
+          onChange={(e) => setEmail(e.target.value)}
+          error={submitted && !isValid}
+          helperText={submitted && !isValid ? 'Please enter a valid email' : undefined}
+          placeholder="user@example.com"
+        />
+        <Button type="submit">Submit</Button>
+      </Stack>
+    </form>
   );
 }
 ```
 
+## Props and Customization
+
+### Key Props
+
+| Prop                          | Type                                                           | Default      | Description                                                                     |
+| ----------------------------- | -------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------- |
+| `label`                       | `ReactNode`                                                    | -            | Label text displayed above the input                                            |
+| `helperText`                  | `ReactNode`                                                    | -            | Helper text displayed below the input                                           |
+| `error`                       | `boolean`                                                      | `false`      | Applies danger color to indicate validation error                               |
+| `enableClearable`             | `boolean`                                                      | `false`      | Shows a clear button when the input has a value                                 |
+| `disableTogglePasswordButton` | `boolean`                                                      | `false`      | Hides the password visibility toggle (only applies when `type="password"`)      |
+| `value`                       | `string`                                                       | -            | Input value for controlled mode                                                 |
+| `defaultValue`                | `string`                                                       | -            | Initial value for uncontrolled mode                                             |
+| `onChange`                    | `(event: ChangeEvent<HTMLInputElement>) => void`               | -            | Callback when the input value changes                                           |
+| `placeholder`                 | `string`                                                       | -            | Placeholder text when the input is empty                                        |
+| `type`                        | `string`                                                       | `'text'`     | HTML input type (`text`, `password`, `email`, `number`, etc.)                   |
+| `disabled`                    | `boolean`                                                      | `false`      | Disables the input                                                              |
+| `readOnly`                    | `boolean`                                                      | `false`      | Makes the input read-only (focusable but not editable)                          |
+| `required`                    | `boolean`                                                      | `false`      | Marks the field as required (adds asterisk to label)                            |
+| `name`                        | `string`                                                       | -            | HTML name attribute for form submission                                         |
+| `size`                        | `'sm' \| 'md' \| 'lg'`                                         | `'md'`       | Input size                                                                      |
+| `variant`                     | `'outlined' \| 'solid' \| 'soft' \| 'plain'`                   | `'outlined'` | Visual style variant                                                            |
+| `color`                       | `'primary' \| 'neutral' \| 'danger' \| 'success' \| 'warning'` | `'neutral'`  | Color scheme                                                                    |
+| `startDecorator`              | `ReactNode`                                                    | -            | Content rendered at the start of the input                                      |
+| `endDecorator`                | `ReactNode`                                                    | -            | Content rendered at the end of the input (not supported with `type="password"`) |
+| `sx`                          | `SxProps`                                                      | -            | Custom styles using the MUI system                                              |
+
+> **Note**: Input also accepts all Joy UI Input props and Framer Motion props.
+
 ## Best Practices
 
-1. **Always provide a label**: Every input should have a visible label so users understand what to enter.
+1. **Use built-in `label` and `helperText`** instead of wrapping with FormControl manually.
 
 ```tsx
-// ✅ Good: clear label
-<Input label="Email address" placeholder="you@example.com" />
-
-// ❌ Bad: placeholder only, no label
-<Input placeholder="Email address" />
+// ✅ Good
+<Input label="Email" helperText="Enter your work email" />
+
+// ❌ Bad
+<FormControl>
+  <FormLabel>Email</FormLabel>
+  <Input />
+  <FormHelperText>Enter your work email</FormHelperText>
+</FormControl>
 ```
 
-2. **Use helper text for guidance, error text for problems**: Provide contextual help via `helperText`, and switch to error messaging when validation fails.
+2. **Choose the right input type** for the data being captured.
 
 ```tsx
-// ✅ Good: helpful context + error state
-<Input
-  label="Password"
-  type="password"
-  helperText={hasError ? 'Must be at least 8 characters' : 'Choose a strong password'}
-  error={hasError}
-/>
+// ✅ Good: Appropriate types
+<Input type="email" label="Email" />
+<Input type="password" label="Password" />
+<Input type="tel" label="Phone" />
 
-// ❌ Bad: no guidance at all
-<Input label="Password" type="password" />
+// ❌ Bad: Generic text for everything
+<Input type="text" label="Email" />
 ```
 
-3. **Choose the right input type**: Use `type` to match the expected data (e.g., `email`, `tel`, `password`, `number`). This enables appropriate browser behavior and mobile keyboards.
+3. **Always provide labels** for accessibility. If a visible label is not appropriate, use `aria-label`.
 
 ```tsx
-// ✅ Good: appropriate type for email
-<Input label="Email" type="email" />
+// ✅ Good: Visible label
+<Input label="Search" />
+
+// ✅ Good: Hidden label for icon-only inputs
+<Input aria-label="Search" startDecorator={<SearchIcon />} />
 
-// ❌ Bad: generic text type for email
-<Input label="Email" type="text" />
+// ❌ Bad: No label at all
+<Input placeholder="Search..." />
 ```
 
-4. **Use `enableClearable` for search and filter inputs**: Allow users to quickly reset their input in search and filter contexts.
+4. **Use `enableClearable` for search and filter inputs** where users frequently need to clear and re-enter values.
 
-5. **Use built-in form props instead of manual composition**: Prefer `label`, `helperText`, `error`, and `required` props over wrapping with FormControl and Typography. This ensures consistent spacing, accessibility, and error handling.
+5. **Do not use `endDecorator` with password inputs.** The password toggle button occupies the end slot. Use `startDecorator` instead for additional icons.
 
 ## Accessibility
 
-- **Label association**: The `label` prop automatically creates a properly associated `<label>` element. If you cannot use the `label` prop, provide an `aria-label` or `aria-labelledby` attribute.
-- **Error announcement**: When `error` is set, the error state is conveyed to assistive technologies via `aria-invalid`. Combine with descriptive `helperText` so screen readers can announce the error message.
-- **Keyboard interaction**: Input supports standard keyboard behavior. The clear button and password toggle are focusable and can be activated with Enter or Space.
-- **Testing note**: When using Testing Library, find a `type="password"` input using the `textbox` role, as ARIA does not define a separate `password` role.
+- **Label association**: The `label` prop automatically connects the label to the input via `htmlFor`/`id` pairing.
+- **Keyboard navigation**: Standard keyboard support — Tab to focus, type to input, Escape to blur (when applicable).
+- **Error announcement**: When `error` is set, `aria-invalid` is applied. Pair with `helperText` so assistive technology announces the error.
+- **Required state**: The `required` prop adds `aria-required` and a visible asterisk to the label.
+- **Password toggle**: The visibility toggle button is keyboard-accessible and includes an appropriate `aria-label`.
+
+## Testing Notes
+
+When using Testing Library, always query password inputs by `textbox` role:
 
 ```tsx
-// Finding a password input in tests
 const passwordInput = screen.getByRole('textbox', { name: /password/i });
 ```
+
+This is because the ARIA specification does not define a `password` role — password inputs use the default `textbox` role.

package/dist/components/inputs/MonthPicker.md

@@ -229,6 +229,18 @@ The `displayFormat` prop controls what users see in the input field, independent
     setValue6(e.target.value);
     args.onChange?.(e);
   }} />
+  <MonthPicker {...args} value={value6} label="MMM YYYY" name="MMM YYYY" displayFormat="MMM YYYY" onChange={e => {
+    setValue6(e.target.value);
+    args.onChange?.(e);
+  }} />
+  <MonthPicker {...args} value={value6} label="MMM YYYY (en-US)" name="MMM YYYY (en-US)" displayFormat="MMM YYYY" locale="en-US" onChange={e => {
+    setValue6(e.target.value);
+    args.onChange?.(e);
+  }} />
+  <MonthPicker {...args} value={value6} label="MMM YYYY (ko-KR)" name="MMM YYYY (ko-KR)" displayFormat="MMM YYYY" locale="ko-KR" onChange={e => {
+    setValue6(e.target.value);
+    args.onChange?.(e);
+  }} />
 </Stack>
 ```
 
@@ -248,9 +260,7 @@ A controlled example with an external reset button to clear the selected value.
 </div>
 ```
 
-## Common Use Cases
-
-### Billing Period Selection
+## Billing Period Selection
 
 ```tsx
 function BillingPeriodSelector() {
@@ -268,7 +278,7 @@ function BillingPeriodSelector() {
 }
 ```
 
-### Report Month Filter with Display Format
+## Report Month Filter with Display Format
 
 ```tsx
 function ReportFilter() {
@@ -286,7 +296,7 @@ function ReportFilter() {
 }
 ```
 
-### Credit Card Expiry
+## Credit Card Expiry
 
 ```tsx
 function CreditCardExpiry() {
@@ -359,6 +369,50 @@ const handleChange = (e) => {
 };
 ```
 
+## Props and Customization
+
+### Key Props
+
+| Prop            | Type                                                    | Default        | Description                                                                                                |
+| --------------- | ------------------------------------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------- |
+| `value`         | `string`                                                | -              | Selected month string in `format` (controlled mode)                                                        |
+| `defaultValue`  | `string`                                                | `''`           | Initial month string (uncontrolled mode)                                                                   |
+| `onChange`      | `(event: { target: { name?, value: string } }) => void` | -              | Callback when the month changes                                                                            |
+| `format`        | `string`                                                | `'YYYY/MM/DD'` | Format of the `value` and `onChange` value                                                                 |
+| `displayFormat` | `string`                                                | `'YYYY/MM'`    | Format displayed in the input field. Supports `MMM` (short month name) and `MMMM` (full month name) tokens |
+| `label`         | `ReactNode`                                             | -              | Form label displayed above the input                                                                       |
+| `helperText`    | `ReactNode`                                             | -              | Helper text displayed below the input                                                                      |
+| `error`         | `boolean`                                               | `false`        | Applies danger color to indicate validation error                                                          |
+| `required`      | `boolean`                                               | `false`        | Marks the field as required                                                                                |
+| `disabled`      | `boolean`                                               | `false`        | Disables the entire component                                                                              |
+| `name`          | `string`                                                | -              | HTML name attribute for form submission                                                                    |
+| `minDate`       | `string`                                                | -              | Minimum selectable month (in `format`)                                                                     |
+| `maxDate`       | `string`                                                | -              | Maximum selectable month (in `format`)                                                                     |
+| `disableFuture` | `boolean`                                               | `false`        | Disables all future months                                                                                 |
+| `disablePast`   | `boolean`                                               | `false`        | Disables all past months                                                                                   |
+| `locale`        | `string`                                                | `'default'`    | Locale for month names (BCP 47 format)                                                                     |
+
+### Alphabetic Month Tokens (MMM / MMMM)
+
+The `displayFormat` prop supports alphabetic month tokens for more human-readable month display:
+
+| Token  | Output                 | Example                        |
+| ------ | ---------------------- | ------------------------------ |
+| `MMM`  | Abbreviated month name | `Jan`, `Feb`, `Apr`            |
+| `MMMM` | Full month name        | `January`, `February`, `April` |
+
+Use the `locale` prop to control the language of month names.
+
+```tsx
+<MonthPicker displayFormat="MMM YYYY" locale="en-US" />
+// → "Apr 2026"
+
+<MonthPicker displayFormat="MMMM YYYY" locale="ko-KR" />
+// → "4월 2026"
+```
+
+> **Note**: MonthPicker also accepts all Input props (e.g., `size`, `variant`, `color`, `sx`).
+
 ## Accessibility
 
 - The input has `role="textbox"` and the calendar toggle button has `aria-label="Toggle Calendar"` for screen reader identification.