@ceed/ads 1.38.1 → 1.40.0

package/dist/components/DialogFrame/DialogFrame.d.ts

@@ -4,6 +4,12 @@ export interface DialogFrameProps {
     children: React.ReactNode;
     actions: React.ReactNode;
     fullscreen?: boolean;
+    /**
+     * When provided, the dialog root renders as a `<form>` and this handler runs on submit.
+     * This enables native submit-on-Enter and lets a `type="submit"` button in `actions`
+     * submit the fields in the content area. When omitted, the root stays a `<div>`.
+     */
+    onSubmit?: React.FormEventHandler<HTMLFormElement>;
 }
 declare const DialogFrame: React.ForwardRefExoticComponent<Omit<Omit<Pick<{
     children?: React.ReactNode;
@@ -18,5 +24,5 @@ declare const DialogFrame: React.ForwardRefExoticComponent<Omit<Omit<Pick<{
     variant?: import("@mui/types").OverridableStringUnion<import("@mui/joy").VariantProp, import("@mui/joy").ModalDialogPropsVariantOverrides> | undefined;
 } & import("@mui/joy").ModalDialogSlotsAndSlotProps & Omit<Omit<React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & {
     ref?: ((instance: HTMLDivElement | null) => void) | React.RefObject<HTMLDivElement> | null | undefined;
-}, "children" | "layout" | "color" | "maxWidth" | "minWidth" | "variant" | "sx" | "size" | "invertedColors" | "orientation" | keyof import("@mui/joy").ModalDialogSlotsAndSlotProps> & import("@mui/system").MUIStyledCommonProps<import("@mui/joy").Theme>, "style" | "title" | "children" | "onAnimationStart" | "onDragStart" | "onDragEnd" | "onDrag" | "layout" | "color" | "content" | "maxWidth" | "minWidth" | "translate" | "ref" | "slot" | "key" | "defaultChecked" | "defaultValue" | "suppressContentEditableWarning" | "suppressHydrationWarning" | "accessKey" | "autoFocus" | "className" | "contentEditable" | "contextMenu" | "dir" | "draggable" | "hidden" | "id" | "lang" | "nonce" | "spellCheck" | "tabIndex" | "radioGroup" | "role" | "about" | "datatype" | "inlist" | "prefix" | "property" | "rel" | "resource" | "rev" | "typeof" | "vocab" | "autoCapitalize" | "autoCorrect" | "autoSave" | "itemProp" | "itemScope" | "itemType" | "itemID" | "itemRef" | "results" | "security" | "unselectable" | "inputMode" | "is" | "aria-activedescendant" | "aria-atomic" | "aria-autocomplete" | "aria-braillelabel" | "aria-brailleroledescription" | "aria-busy" | "aria-checked" | "aria-colcount" | "aria-colindex" | "aria-colindextext" | "aria-colspan" | "aria-controls" | "aria-current" | "aria-describedby" | "aria-description" | "aria-details" | "aria-disabled" | "aria-dropeffect" | "aria-errormessage" | "aria-expanded" | "aria-flowto" | "aria-grabbed" | "aria-haspopup" | "aria-hidden" | "aria-invalid" | "aria-keyshortcuts" | "aria-label" | "aria-labelledby" | "aria-level" | "aria-live" | "aria-modal" | "aria-multiline" | "aria-multiselectable" | "aria-orientation" | "aria-owns" | "aria-placeholder" | "aria-posinset" | "aria-pressed" | "aria-readonly" | "aria-relevant" | "aria-required" | "aria-roledescription" | "aria-rowcount" | "aria-rowindex" | "aria-rowindextext" | "aria-rowspan" | "aria-selected" | "aria-setsize" | "aria-sort" | "aria-valuemax" | "aria-valuemin" | "aria-valuenow" | "aria-valuetext" | "dangerouslySetInnerHTML" | "onCopy" | "onCopyCapture" | "onCut" | "onCutCapture" | "onPaste" | "onPasteCapture" | "onCompositionEnd" | "onCompositionEndCapture" | "onCompositionStart" | "onCompositionStartCapture" | "onCompositionUpdate" | "onCompositionUpdateCapture" | "onFocus" | "onFocusCapture" | "onBlur" | "onBlurCapture" | "onChange" | "onChangeCapture" | "onBeforeInput" | "onBeforeInputCapture" | "onInput" | "onInputCapture" | "onReset" | "onResetCapture" | "onSubmit" | "onSubmitCapture" | "onInvalid" | "onInvalidCapture" | "onLoad" | "onLoadCapture" | "onError" | "onErrorCapture" | "onKeyDown" | "onKeyDownCapture" | "onKeyPress" | "onKeyPressCapture" | "onKeyUp" | "onKeyUpCapture" | "onAbort" | "onAbortCapture" | "onCanPlay" | "onCanPlayCapture" | "onCanPlayThrough" | "onCanPlayThroughCapture" | "onDurationChange" | "onDurationChangeCapture" | "onEmptied" | "onEmptiedCapture" | "onEncrypted" | "onEncryptedCapture" | "onEnded" | "onEndedCapture" | "onLoadedData" | "onLoadedDataCapture" | "onLoadedMetadata" | "onLoadedMetadataCapture" | "onLoadStart" | "onLoadStartCapture" | "onPause" | "onPauseCapture" | "onPlay" | "onPlayCapture" | "onPlaying" | "onPlayingCapture" | "onProgress" | "onProgressCapture" | "onRateChange" | "onRateChangeCapture" | "onResize" | "onResizeCapture" | "onSeeked" | "onSeekedCapture" | "onSeeking" | "onSeekingCapture" | "onStalled" | "onStalledCapture" | "onSuspend" | "onSuspendCapture" | "onTimeUpdate" | "onTimeUpdateCapture" | "onVolumeChange" | "onVolumeChangeCapture" | "onWaiting" | "onWaitingCapture" | "onAuxClick" | "onAuxClickCapture" | "onClick" | "onClickCapture" | "onContextMenu" | "onContextMenuCapture" | "onDoubleClick" | "onDoubleClickCapture" | "onDragCapture" | "onDragEndCapture" | "onDragEnter" | "onDragEnterCapture" | "onDragExit" | "onDragExitCapture" | "onDragLeave" | "onDragLeaveCapture" | "onDragOver" | "onDragOverCapture" | "onDragStartCapture" | "onDrop" | "onDropCapture" | "onMouseDown" | "onMouseDownCapture" | "onMouseEnter" | "onMouseLeave" | "onMouseMove" | "onMouseMoveCapture" | "onMouseOut" | "onMouseOutCapture" | "onMouseOver" | "onMouseOverCapture" | "onMouseUp" | "onMouseUpCapture" | "onSelect" | "onSelectCapture" | "onTouchCancel" | "onTouchCancelCapture" | "onTouchEnd" | "onTouchEndCapture" | "onTouchMove" | "onTouchMoveCapture" | "onTouchStart" | "onTouchStartCapture" | "onPointerDown" | "onPointerDownCapture" | "onPointerMove" | "onPointerMoveCapture" | "onPointerUp" | "onPointerUpCapture" | "onPointerCancel" | "onPointerCancelCapture" | "onPointerEnter" | "onPointerLeave" | "onPointerOver" | "onPointerOverCapture" | "onPointerOut" | "onPointerOutCapture" | "onGotPointerCapture" | "onGotPointerCaptureCapture" | "onLostPointerCapture" | "onLostPointerCaptureCapture" | "onScroll" | "onScrollCapture" | "onWheel" | "onWheelCapture" | "onAnimationStartCapture" | "onAnimationEnd" | "onAnimationEndCapture" | "onAnimationIteration" | "onAnimationIterationCapture" | "onTransitionEnd" | "onTransitionEndCapture" | "variant" | "size" | "invertedColors" | "orientation" | keyof import("@mui/system").MUIStyledCommonProps<import("@mui/joy").Theme> | keyof import("@mui/joy").ModalDialogSlotsAndSlotProps> & import("@mui/system").MUIStyledCommonProps<import("@mui/joy").Theme>, "title" | "children"> & DialogFrameProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+}, "children" | "layout" | "color" | "maxWidth" | "minWidth" | "variant" | "sx" | "size" | "invertedColors" | "orientation" | keyof import("@mui/joy").ModalDialogSlotsAndSlotProps> & import("@mui/system").MUIStyledCommonProps<import("@mui/joy").Theme>, "style" | "title" | "children" | "onAnimationStart" | "onDragStart" | "onDragEnd" | "onDrag" | "layout" | "color" | "content" | "maxWidth" | "minWidth" | "translate" | "ref" | "slot" | "key" | "defaultChecked" | "defaultValue" | "suppressContentEditableWarning" | "suppressHydrationWarning" | "accessKey" | "autoFocus" | "className" | "contentEditable" | "contextMenu" | "dir" | "draggable" | "hidden" | "id" | "lang" | "nonce" | "spellCheck" | "tabIndex" | "radioGroup" | "role" | "about" | "datatype" | "inlist" | "prefix" | "property" | "rel" | "resource" | "rev" | "typeof" | "vocab" | "autoCapitalize" | "autoCorrect" | "autoSave" | "itemProp" | "itemScope" | "itemType" | "itemID" | "itemRef" | "results" | "security" | "unselectable" | "inputMode" | "is" | "aria-activedescendant" | "aria-atomic" | "aria-autocomplete" | "aria-braillelabel" | "aria-brailleroledescription" | "aria-busy" | "aria-checked" | "aria-colcount" | "aria-colindex" | "aria-colindextext" | "aria-colspan" | "aria-controls" | "aria-current" | "aria-describedby" | "aria-description" | "aria-details" | "aria-disabled" | "aria-dropeffect" | "aria-errormessage" | "aria-expanded" | "aria-flowto" | "aria-grabbed" | "aria-haspopup" | "aria-hidden" | "aria-invalid" | "aria-keyshortcuts" | "aria-label" | "aria-labelledby" | "aria-level" | "aria-live" | "aria-modal" | "aria-multiline" | "aria-multiselectable" | "aria-orientation" | "aria-owns" | "aria-placeholder" | "aria-posinset" | "aria-pressed" | "aria-readonly" | "aria-relevant" | "aria-required" | "aria-roledescription" | "aria-rowcount" | "aria-rowindex" | "aria-rowindextext" | "aria-rowspan" | "aria-selected" | "aria-setsize" | "aria-sort" | "aria-valuemax" | "aria-valuemin" | "aria-valuenow" | "aria-valuetext" | "dangerouslySetInnerHTML" | "onCopy" | "onCopyCapture" | "onCut" | "onCutCapture" | "onPaste" | "onPasteCapture" | "onCompositionEnd" | "onCompositionEndCapture" | "onCompositionStart" | "onCompositionStartCapture" | "onCompositionUpdate" | "onCompositionUpdateCapture" | "onFocus" | "onFocusCapture" | "onBlur" | "onBlurCapture" | "onChange" | "onChangeCapture" | "onBeforeInput" | "onBeforeInputCapture" | "onInput" | "onInputCapture" | "onReset" | "onResetCapture" | "onSubmit" | "onSubmitCapture" | "onInvalid" | "onInvalidCapture" | "onLoad" | "onLoadCapture" | "onError" | "onErrorCapture" | "onKeyDown" | "onKeyDownCapture" | "onKeyPress" | "onKeyPressCapture" | "onKeyUp" | "onKeyUpCapture" | "onAbort" | "onAbortCapture" | "onCanPlay" | "onCanPlayCapture" | "onCanPlayThrough" | "onCanPlayThroughCapture" | "onDurationChange" | "onDurationChangeCapture" | "onEmptied" | "onEmptiedCapture" | "onEncrypted" | "onEncryptedCapture" | "onEnded" | "onEndedCapture" | "onLoadedData" | "onLoadedDataCapture" | "onLoadedMetadata" | "onLoadedMetadataCapture" | "onLoadStart" | "onLoadStartCapture" | "onPause" | "onPauseCapture" | "onPlay" | "onPlayCapture" | "onPlaying" | "onPlayingCapture" | "onProgress" | "onProgressCapture" | "onRateChange" | "onRateChangeCapture" | "onResize" | "onResizeCapture" | "onSeeked" | "onSeekedCapture" | "onSeeking" | "onSeekingCapture" | "onStalled" | "onStalledCapture" | "onSuspend" | "onSuspendCapture" | "onTimeUpdate" | "onTimeUpdateCapture" | "onVolumeChange" | "onVolumeChangeCapture" | "onWaiting" | "onWaitingCapture" | "onAuxClick" | "onAuxClickCapture" | "onClick" | "onClickCapture" | "onContextMenu" | "onContextMenuCapture" | "onDoubleClick" | "onDoubleClickCapture" | "onDragCapture" | "onDragEndCapture" | "onDragEnter" | "onDragEnterCapture" | "onDragExit" | "onDragExitCapture" | "onDragLeave" | "onDragLeaveCapture" | "onDragOver" | "onDragOverCapture" | "onDragStartCapture" | "onDrop" | "onDropCapture" | "onMouseDown" | "onMouseDownCapture" | "onMouseEnter" | "onMouseLeave" | "onMouseMove" | "onMouseMoveCapture" | "onMouseOut" | "onMouseOutCapture" | "onMouseOver" | "onMouseOverCapture" | "onMouseUp" | "onMouseUpCapture" | "onSelect" | "onSelectCapture" | "onTouchCancel" | "onTouchCancelCapture" | "onTouchEnd" | "onTouchEndCapture" | "onTouchMove" | "onTouchMoveCapture" | "onTouchStart" | "onTouchStartCapture" | "onPointerDown" | "onPointerDownCapture" | "onPointerMove" | "onPointerMoveCapture" | "onPointerUp" | "onPointerUpCapture" | "onPointerCancel" | "onPointerCancelCapture" | "onPointerEnter" | "onPointerLeave" | "onPointerOver" | "onPointerOverCapture" | "onPointerOut" | "onPointerOutCapture" | "onGotPointerCapture" | "onGotPointerCaptureCapture" | "onLostPointerCapture" | "onLostPointerCaptureCapture" | "onScroll" | "onScrollCapture" | "onWheel" | "onWheelCapture" | "onAnimationStartCapture" | "onAnimationEnd" | "onAnimationEndCapture" | "onAnimationIteration" | "onAnimationIterationCapture" | "onTransitionEnd" | "onTransitionEndCapture" | "variant" | "size" | "invertedColors" | "orientation" | keyof import("@mui/system").MUIStyledCommonProps<import("@mui/joy").Theme> | keyof import("@mui/joy").ModalDialogSlotsAndSlotProps> & import("@mui/system").MUIStyledCommonProps<import("@mui/joy").Theme>, "title" | "children" | "onSubmit"> & DialogFrameProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
 export { DialogFrame };

package/dist/components/feedback/Dialog.md

@@ -204,41 +204,45 @@ function DeleteConfirmation({ itemName, open, onClose, onDelete }) {
 
 ## Form Dialog
 
+> ✅ **Best Practice** ✅
+>
+> For any dialog that collects input and submits, **always pass `onSubmit`** to DialogFrame — never wire the confirm button with `onClick` alone. When `onSubmit` is provided, DialogFrame renders its root as a `<form>`, so the fields in the content area and the `type="submit"` button in `actions` belong to the same form. This is what enables **submit-on-Enter** (pressing Enter inside an input submits) plus native constraint validation (`required`, `type="email"`, etc.).
+>
+> An `onClick` handler on the action button cannot do this: the button lives in `actions`, a sibling of the content area, so without a wrapping `<form>` there is no implicit submit and Enter does nothing.
+
 ```tsx
 function QuickAddDialog({ open, onClose, onSubmit }) {
-  const [name, setName] = useState('');
-  const [email, setEmail] = useState('');
-
-  const handleSubmit = () => {
-    onSubmit({ name, email });
-    setName('');
-    setEmail('');
+  const handleSubmit = (event) => {
+    event.preventDefault();
+    const formData = new FormData(event.currentTarget);
+    onSubmit({ name: formData.get('name'), email: formData.get('email') });
     onClose();
   };
 
   return (
     <Modal open={open} onClose={onClose}>
+      {/* onSubmit makes the root a <form>; Enter in any field submits */}
       <DialogFrame
         title="Add New User"
+        onSubmit={handleSubmit}
         actions={
           <>
             <Button variant="plain" color="neutral" onClick={onClose}>
               Cancel
             </Button>
-            <Button onClick={handleSubmit} disabled={!name || !email}>
-              Add User
-            </Button>
+            {/* type="submit" ties this button to the DialogFrame form */}
+            <Button type="submit">Add User</Button>
           </>
         }
       >
         <Stack gap={2}>
           <FormControl>
             <FormLabel>Name</FormLabel>
-            <Input value={name} onChange={(e) => setName(e.target.value)} placeholder="Enter name" autoFocus />
+            <Input name="name" placeholder="Enter name" autoFocus required />
           </FormControl>
           <FormControl>
             <FormLabel>Email</FormLabel>
-            <Input type="email" value={email} onChange={(e) => setEmail(e.target.value)} placeholder="Enter email" />
+            <Input type="email" name="email" placeholder="Enter email" required />
           </FormControl>
         </Stack>
       </DialogFrame>
@@ -398,13 +402,14 @@ function SelectOptionDialog({ open, onClose, options, onSelect }) {
 
 ### Key Props
 
-| Prop         | Type                             | Default | Description                            |
-| ------------ | -------------------------------- | ------- | -------------------------------------- |
-| `title`      | `string`                         | -       | Dialog title displayed in the header   |
-| `children`   | `ReactNode`                      | -       | Dialog body content                    |
-| `actions`    | `ReactNode`                      | -       | Action buttons displayed in the footer |
-| `fullscreen` | `boolean`                        | `false` | Enable fullscreen mode                 |
-| `onKeyDown`  | `(event: KeyboardEvent) => void` | -       | Keyboard event handler                 |
+| Prop         | Type                                          | Default | Description                                                                                                                                              |
+| ------------ | --------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `title`      | `string`                                      | -       | Dialog title displayed in the header                                                                                                                     |
+| `children`   | `ReactNode`                                   | -       | Dialog body content                                                                                                                                      |
+| `actions`    | `ReactNode`                                   | -       | Action buttons displayed in the footer                                                                                                                   |
+| `fullscreen` | `boolean`                                     | `false` | Enable fullscreen mode                                                                                                                                   |
+| `onSubmit`   | `(event: FormEvent<HTMLFormElement>) => void` | -       | When provided, the dialog root renders as a `<form>`, enabling submit-on-Enter and a `type="submit"` action button. Omit it and the root stays a `<div>` |
+| `onKeyDown`  | `(event: KeyboardEvent) => void`              | -       | Keyboard event handler                                                                                                                                   |
 
 ### Structure
 
@@ -572,6 +577,25 @@ DialogFrame inherits accessibility features from Modal:
 />
 ```
 
+5. **Use `onSubmit` for input dialogs**: For any dialog that collects values and submits, pass `onSubmit` and mark the confirm button `type="submit"`. This renders the root as a `<form>`, giving you submit-on-Enter and native validation for free.
+
+```tsx
+// ✅ Good: onSubmit + type="submit" — Enter submits, `required` is enforced
+<DialogFrame
+  onSubmit={handleSubmit}
+  actions={
+    <>
+      <Button variant="plain" color="neutral" onClick={onClose}>
+        Cancel
+      </Button>
+      <Button type="submit">Save</Button>
+    </>
+  }
+>
+  <Input name="email" required />
+</DialogFrame>
+```
+
 ### ❌ Don't
 
 1. **Don't use for notifications**: Use Toast instead
@@ -607,6 +631,20 @@ showToast({ message: 'Item saved!' });
 
 4. **Don't block critical workflows**: Important features should be accessible
 
+5. **Don't submit input dialogs with `onClick` only**: Pressing Enter in a field won't submit, because the button in `actions` sits outside any form.
+
+```tsx
+// ❌ Bad: onClick-only — Enter in the input does nothing
+<DialogFrame actions={<Button onClick={handleSubmit}>Save</Button>}>
+  <Input value={value} onChange={...} />
+</DialogFrame>
+
+// ✅ Good: onSubmit + type="submit" — Enter submits
+<DialogFrame onSubmit={handleSubmit} actions={<Button type="submit">Save</Button>}>
+  <Input name="value" />
+</DialogFrame>
+```
+
 ## Performance Considerations
 
 ### Lazy Load Dialog Content

package/dist/components/inputs/DatePicker.md

@@ -100,7 +100,7 @@ Set `error` to `true` and combine with `helperText` to communicate validation fa
 
 ## Disabled and Read-Only States
 
-The `disabled` prop prevents all interaction. The `readOnly` prop displays the value but blocks changes, while `inputReadOnly` disables keyboard typing but still allows calendar selection -- useful for mobile scenarios.
+The `disabled` prop prevents all interaction. The `readOnly` prop displays the value but blocks changes, while `inputReadOnly` disables keyboard typing but still allows calendar selection -- useful for mobile scenarios. When `inputReadOnly` is set, clicking the input opens the calendar (not just the calendar button).
 
 ```tsx
 <DatePicker
@@ -620,7 +620,7 @@ function RegionalDateField({ locale }: { locale: string }) {
 | `disableFuture`     | `boolean`                                               | `false`        | Disables all future dates                                                                                                                               |
 | `disablePast`       | `boolean`                                               | `false`        | Disables all past dates                                                                                                                                 |
 | `shouldDisableDate` | `(date: string) => boolean`                             | -              | Custom function to disable specific dates. Receives date in `format`. Return `true` to disable                                                          |
-| `inputReadOnly`     | `boolean`                                               | `false`        | Prevents keyboard typing in the input (users must use the calendar popup)                                                                               |
+| `inputReadOnly`     | `boolean`                                               | `false`        | Prevents keyboard typing in the input; users select via the calendar, which opens on clicking either the input or the calendar button                   |
 | `hideClearButton`   | `boolean`                                               | `false`        | Hides the clear button in the calendar popup                                                                                                            |
 
 ### format vs displayFormat

package/dist/components/inputs/DateRangePicker.md

@@ -741,7 +741,7 @@ const getDuration = (value) => {
 | `maxDate`         | `string`                                                | -              | Maximum selectable date (in `format`)                                                                                |
 | `disableFuture`   | `boolean`                                               | `false`        | Disables all future dates                                                                                            |
 | `disablePast`     | `boolean`                                               | `false`        | Disables all past dates                                                                                              |
-| `inputReadOnly`   | `boolean`                                               | `false`        | Prevents keyboard typing (calendar-only input)                                                                       |
+| `inputReadOnly`   | `boolean`                                               | `false`        | Prevents keyboard typing; calendar-only input that opens on clicking either the input or the calendar button         |
 | `hideClearButton` | `boolean`                                               | `false`        | Hides the clear button in the calendar popup                                                                         |
 | `numberOfMonths`  | `number`                                                | `1`            | Number of calendar months to show side by side in the popup                                                          |