@ceed/ads 1.36.0 → 1.37.0

package/dist/components/Select/Select.d.ts

@@ -1,5 +1,8 @@
 import React, { ComponentProps } from 'react';
 import { Select as JoySelect, type SelectProps as JoySelectProps } from '@mui/joy';
+import FormControl from '../FormControl';
+import FormLabel from '../FormLabel';
+import FormHelperText from '../FormHelperText';
 import { SelectValue } from '@mui/base';
 export type { JoySelectProps };
 export type { OptionProps } from '@mui/joy';
@@ -24,11 +27,16 @@ export { Option };
 export type InferOptionValue<OptionValue> = OptionValue extends {
     value: infer V;
 } ? V : OptionValue;
-export interface SelectProps<OptionValue extends OptionType, Multiple extends boolean = false> extends Omit<ComponentProps<typeof JoySelect<OptionValue, any, Multiple>>, 'value' | 'onChange' | 'multiple'> {
+export interface SelectProps<OptionValue extends OptionType, Multiple extends boolean = false> extends Omit<ComponentProps<typeof JoySelect<OptionValue, any, Multiple>>, 'value' | 'onChange' | 'multiple' | 'slotProps'> {
     options: OptionValue[];
     label?: string;
     helperText?: string;
     error?: boolean;
+    slotProps?: ComponentProps<typeof JoySelect<OptionValue, any, Multiple>>['slotProps'] & {
+        formControl?: ComponentProps<typeof FormControl>;
+        formLabel?: ComponentProps<typeof FormLabel>;
+        formHelperText?: ComponentProps<typeof FormHelperText>;
+    };
     value?: SelectValue<InferOptionValue<OptionValue>, Multiple>;
     onChange?: (event: Omit<React.SyntheticEvent<HTMLElement>, 'target'> & {
         target: {

package/dist/components/inputs/Select.md

@@ -207,6 +207,58 @@ Combining `label`, `helperText`, and `error` produces a complete form field. Her
   </>
 ```
 
+## Slot Props and Deterministic Ids
+
+The `slotProps` prop targets both Joy Select's own slots (`button`, `listbox`, `root`, …) and the wrapper slots that `Select` composes around it (`formControl`, `formLabel`, `formHelperText`). Pass `id` (or `slotProps.formControl.id`) to pin the field's ids deterministically — `FormControl` derives the button `id` and the label `id` (`${id}-label`) from it, which keeps `byLabelText` / `byRole('combobox', { name })` queries stable in tests.
+
+```tsx
+<Stack
+    spacing={3}
+    sx={{
+      minWidth: 240
+    }}
+  >
+    {/* id seeds deterministic FormControl ids: button#pet, label#pet-label (testable via byLabelText/byRole) */}
+    <Select
+      id="pet"
+      label="Pet"
+      defaultValue="cat"
+      options={options}
+      slotProps={{
+        formLabel: {
+          sx: {
+            color: "primary.500"
+          }
+        },
+        formHelperText: {
+          sx: {
+            fontStyle: "italic"
+          }
+        },
+        button: {
+          "aria-describedby": "pet-extra"
+        }
+      }}
+      helperText="Wired via slotProps"
+    />
+  </Stack>
+```
+
+```tsx
+<Select
+  id="pet"
+  label="Pet"
+  helperText="Wired via slotProps"
+  options={options}
+  slotProps={{
+    formLabel: { sx: { color: 'primary.500' } },
+    formHelperText: { sx: { fontStyle: 'italic' } },
+    button: { 'aria-describedby': 'pet-extra' },
+  }}
+/>
+// → renders button#pet and label#pet-label, connected via aria-labelledby
+```
+
 ## Required Field
 
 Set `required` to mark the field as required. An asterisk is added to the label automatically.
@@ -557,25 +609,27 @@ function LocationSelect() {
 
 ### Key Props
 
-| Prop             | Type                                                             | Default           | Description                                          |
-| ---------------- | ---------------------------------------------------------------- | ----------------- | ---------------------------------------------------- |
-| `options`        | `OptionType[]`                                                   | `[]`              | Array of options (objects or primitives)             |
-| `value`          | `InferOptionValue<OptionType> \| InferOptionValue<OptionType>[]` | -                 | Selected value(s) for controlled mode                |
-| `defaultValue`   | `InferOptionValue<OptionType> \| InferOptionValue<OptionType>[]` | -                 | Initial value for uncontrolled mode                  |
-| `onChange`       | `(event: { target: { name?, value } }, newValue) => void`        | -                 | Callback when selection changes                      |
-| `multiple`       | `boolean`                                                        | `false`           | Allow multiple selections (value becomes an array)   |
-| `label`          | `string`                                                         | -                 | Form label displayed above the select                |
-| `helperText`     | `string`                                                         | -                 | Helper text displayed below the select               |
-| `error`          | `boolean`                                                        | `false`           | Applies danger color to indicate validation error    |
-| `required`       | `boolean`                                                        | `false`           | Marks the field as required (adds asterisk to label) |
-| `disabled`       | `boolean`                                                        | `false`           | Disables the select                                  |
-| `placeholder`    | `string`                                                         | `'Choose one...'` | Placeholder text when no value is selected           |
-| `size`           | `'sm' \| 'md' \| 'lg'`                                           | `'md'`            | Select size                                          |
-| `variant`        | `'outlined' \| 'plain' \| 'solid' \| 'soft'`                     | `'outlined'`      | Visual style variant                                 |
-| `color`          | `'primary' \| 'neutral' \| 'danger' \| 'success' \| 'warning'`   | `'neutral'`       | Color scheme                                         |
-| `startDecorator` | `ReactNode`                                                      | -                 | Content rendered before the select trigger text      |
-| `endDecorator`   | `ReactNode`                                                      | -                 | Content rendered after the select trigger text       |
-| `sx`             | `SxProps`                                                        | -                 | Custom styles using the MUI system                   |
+| Prop             | Type                                                                    | Default           | Description                                                    |
+| ---------------- | ----------------------------------------------------------------------- | ----------------- | -------------------------------------------------------------- |
+| `options`        | `OptionType[]`                                                          | `[]`              | Array of options (objects or primitives)                       |
+| `value`          | `InferOptionValue<OptionType> \| InferOptionValue<OptionType>[]`        | -                 | Selected value(s) for controlled mode                          |
+| `defaultValue`   | `InferOptionValue<OptionType> \| InferOptionValue<OptionType>[]`        | -                 | Initial value for uncontrolled mode                            |
+| `onChange`       | `(event: { target: { name?, value } }, newValue) => void`               | -                 | Callback when selection changes                                |
+| `multiple`       | `boolean`                                                               | `false`           | Allow multiple selections (value becomes an array)             |
+| `label`          | `string`                                                                | -                 | Form label displayed above the select                          |
+| `helperText`     | `string`                                                                | -                 | Helper text displayed below the select                         |
+| `error`          | `boolean`                                                               | `false`           | Applies danger color to indicate validation error              |
+| `required`       | `boolean`                                                               | `false`           | Marks the field as required (adds asterisk to label)           |
+| `disabled`       | `boolean`                                                               | `false`           | Disables the select                                            |
+| `placeholder`    | `string`                                                                | `'Choose one...'` | Placeholder text when no value is selected                     |
+| `size`           | `'sm' \| 'md' \| 'lg'`                                                  | `'md'`            | Select size                                                    |
+| `variant`        | `'outlined' \| 'plain' \| 'solid' \| 'soft'`                            | `'outlined'`      | Visual style variant                                           |
+| `color`          | `'primary' \| 'neutral' \| 'danger' \| 'success' \| 'warning'`          | `'neutral'`       | Color scheme                                                   |
+| `startDecorator` | `ReactNode`                                                             | -                 | Content rendered before the select trigger text                |
+| `endDecorator`   | `ReactNode`                                                             | -                 | Content rendered after the select trigger text                 |
+| `id`             | `string`                                                                | -                 | Seeds deterministic ids: button `id`, label `${id}-label`      |
+| `slotProps`      | `{ formControl?, formLabel?, formHelperText?, button?, listbox?, ... }` | -                 | Props forwarded to composed wrapper slots and Joy Select slots |
+| `sx`             | `SxProps`                                                               | -                 | Custom styles using the MUI system                             |
 
 ### Option Type
 
@@ -611,7 +665,8 @@ const options = [
 
 ## Accessibility
 
-- **Label association**: When you use the `label` prop, the component automatically connects the label to the select element via `aria-labelledby`. Always provide a label for screen reader users.
+- **Label association**: When you use the `label` prop, the component automatically connects the label to the select element via `aria-labelledby` (the internal `FormControl` propagates a `labelId` to both the label and the button slot). You do not need to wire `useId` or a custom `FormLabel` externally. Always provide a label for screen reader users.
+- **Deterministic ids for tests**: Pass `id` (or `slotProps.formControl.id`) to fix the generated ids, so `byLabelText` / `byRole('combobox', { name })` resolve to a stable accessible name.
 - **Keyboard navigation**: The select can be opened with Enter or Space, navigated with Arrow Up/Down and Home/End, confirmed with Enter, and dismissed with Escape.
 - **Error announcement**: When `error` is set, `aria-invalid` is applied. Pair it with a descriptive `helperText` so assistive technology can announce the error reason.
 - **Required state**: The `required` prop adds `aria-required` and a visible asterisk to the label, communicating the requirement both visually and programmatically.