@maxio-com/react-ui-components 9.24.1 → 9.26.0

package/dist/skills/maxio-react/SKILL.md

@@ -39,6 +39,9 @@ Use this skill to build React components using `@maxio-com/react-ui-components`.
 - [Components / Flex](references/components-flex.md)
 - [Components / Forms / Checkbox](references/components-forms-checkbox.md)
 - [Components / Forms / ComboBox](references/components-forms-combobox.md)
+- [Components / Forms / DateField](references/components-forms-datefield.md)
+- [Components / Forms / DatePicker](references/components-forms-datepicker.md)
+- [Components / Forms / DateRangePicker](references/components-forms-daterangepicker.md)
 - [Components / Forms / Radio Group](references/components-forms-radio-group.md)
 - [Components / Forms / Select](references/components-forms-select.md)
 - [Components / Forms / TextArea](references/components-forms-textarea.md)

package/dist/skills/maxio-react/references/components-calendar.md

@@ -124,7 +124,7 @@ import { Calendar, I18nProvider } from "@maxio-com/react-ui-components";
 Use Default when users need to select one date from a visible month grid.
 
 ```tsx
-const Default = () => <Calendar aria-label="Billing date" defaultValue={currentDate} />;
+const Default = () => <Calendar aria-label="Billing date" defaultValue={referenceDate} />;
 ```
 
 ### Controlled
@@ -133,7 +133,7 @@ Use Controlled when application state owns the selected date.
 
 ```tsx
 const Controlled = function ControlledCalendar() {
-  const [value, setValue] = useState(currentDate);
+  const [value, setValue] = useState(referenceDate);
   return (
     <Calendar aria-label="Billing date" value={value} onChange={setValue} />
   );
@@ -147,11 +147,11 @@ Use Date Restrictions to limit selection to a billing period and exclude specifi
 ```tsx
 const DateRestrictions = () => <Calendar
     aria-label="Billing date"
-    defaultValue={currentDate}
-    minValue={currentDate.subtract({ days: 7 })}
-    maxValue={currentDate.add({ days: 14 })}
+    defaultValue={referenceDate}
+    minValue={referenceDate.subtract({ days: 7 })}
+    maxValue={referenceDate.add({ days: 14 })}
     isDateUnavailable={(date) =>
-      date.compare(currentDate.add({ days: 5 })) === 0} />;
+      date.compare(referenceDate.add({ days: 5 })) === 0} />;
 ```
 
 ### Disabled
@@ -159,7 +159,7 @@ const DateRestrictions = () => <Calendar
 Use Disabled when calendar interaction is unavailable.
 
 ```tsx
-const Disabled = () => <Calendar aria-label="Billing date" defaultValue={currentDate} isDisabled />;
+const Disabled = () => <Calendar aria-label="Billing date" defaultValue={referenceDate} isDisabled />;
 ```
 
 ### Read Only
@@ -167,7 +167,7 @@ const Disabled = () => <Calendar aria-label="Billing date" defaultValue={current
 Use Read Only to allow browsing without changing the selected date.
 
 ```tsx
-const ReadOnly = () => <Calendar aria-label="Billing date" defaultValue={currentDate} isReadOnly />;
+const ReadOnly = () => <Calendar aria-label="Billing date" defaultValue={referenceDate} isReadOnly />;
 ```
 
 ### Invalid
@@ -177,7 +177,7 @@ Use Invalid with an actionable error message when the selected date fails valida
 ```tsx
 const Invalid = () => <Calendar
     aria-label="Billing date"
-    defaultValue={currentDate}
+    defaultValue={referenceDate}
     isInvalid
     errorMessage="Choose a date within the billing period." />;
 ```
@@ -188,6 +188,6 @@ Use I18nProvider to localize labels, weekday order, and navigation direction.
 
 ```tsx
 const International = () => <I18nProvider locale="pl-PL">
-    <Calendar aria-label="Billing date" defaultValue={currentDate} />
+    <Calendar aria-label="Billing date" defaultValue={referenceDate} />
 </I18nProvider>;
 ```

package/dist/skills/maxio-react/references/components-forms-datefield.md

@@ -0,0 +1,192 @@
+# DateField
+
+## Usage Guidelines
+
+### Overview
+
+DateField provides localized, individually editable date and time segments for keyboard entry.
+
+#### When to Use
+
+- Use for billing, scheduling, or reporting dates.
+- Use when users know the date and can enter it directly.
+
+#### When Not to Use
+
+- Use DateRangePicker when a task requires two endpoints.
+- Use DatePicker when users need a calendar to browse dates.
+- Do not use for free-form dates or recurring schedule expressions.
+
+### Variants
+
+| Variant           | Purpose                      | Usage notes                                |
+| :---------------- | :--------------------------- | :----------------------------------------- |
+| Default           | Enter a date                 | Provide a specific label.                  |
+| Empty             | Start without a value        | Date placeholders follow the locale.       |
+| Disabled          | Prevent interaction          | Use when the field is unavailable.         |
+| Read only         | Prevent edits                | Keep the existing value available to read. |
+| Invalid           | Explain a validation failure | Supply an actionable error message.        |
+| Date restrictions | Limit permitted dates        | Explain the limits in the description.     |
+
+### Behavior
+
+- **Mouse and touch**: select a date segment to edit it.
+- **Keyboard**: Tab moves between editable segments; arrow keys adjust values and typing replaces segment contents.
+- **Focus management**: preserve visible keyboard focus. Date segments are separate focus targets.
+- **Controlled state**: use controlled values when application state owns the selection; otherwise supply an initial value.
+
+### Accessibility
+
+- Provide a visible `label`, or `aria-label` / `aria-labelledby` when the layout supplies visual context.
+- Use `description` for instructions and `errorMessage` for validation feedback; React Aria associates them with the field.
+- Preserve segment keyboard behavior, accessible names, and visible focus indicators.
+- Explain restrictions in text; do not rely on color alone to communicate errors or unavailable dates.
+
+### Content
+
+- Use a task-specific label such as "Billing date".
+- Explain date limits before entry, for example "Choose dates within the billing period."
+- Keep errors actionable, such as "Choose a date on or after the invoice date."
+- Allow for locale-specific date order, time zones, and right-to-left layouts.
+
+### Related
+
+- **[DatePicker](components-forms-datepicker.md)**: Add calendar selection to a single date input.
+- **[DateRangePicker](components-forms-daterangepicker.md)**: Collect a start and end date.
+
+## React
+
+```tsx
+import { DateField } from '@maxio-com/react-ui-components';
+```
+
+### State Management
+
+#### Controlled
+
+Use `value` and `onChange` as shown in the Controlled story. The parent must apply
+changes to `value` before they appear in the input.
+
+#### Uncontrolled
+
+Use `defaultValue`, as shown in the Default story, to initialize internal state.
+Omit it to start empty.
+
+### Date Values and Forms
+
+Install `@internationalized/date` in the consuming application to construct values
+with `parseDate` or the appropriate date-time constructor. Values are date objects
+from that package, not JavaScript `Date` instances or strings.
+
+A cleared value is `null`. Use `name` for native form submission.
+Use `isRequired`, `validate`, and `validationBehavior` for validation. Pair custom
+invalid state with `isInvalid` and `errorMessage`.
+
+### Localization
+
+Use React Aria's `I18nProvider`, as shown in the International story, to set date
+order and reading direction. Date-time values support `granularity` and time zones.
+
+## Imports
+
+```tsx
+import { DateField, I18nProvider } from "@maxio-com/react-ui-components";
+```
+
+## Prop Types
+
+### DateField
+
+| Prop | Type | Required | Default | Description | Source |
+| --- | --- | --- | --- | --- | --- |
+| `description` | `ReactNode` | no | - | Instructions associated with the field. | DateFieldProps |
+| `errorMessage` | `ReactNode \| ((validation: ValidationResult) => ReactNode)` | no | - | Validation feedback, or a function formatting native validation errors. | DateFieldProps |
+| `label` | `ReactNode` | no | - | Visible accessible label. Supply aria-label when omitted. | DateFieldProps |
+
+## Stories
+
+### Default
+
+Use for an initial, uncontrolled date. Provide a visible label or an accessible name.
+
+```tsx
+const Default = () => <DateField label="Billing date" defaultValue={initialValue} />;
+```
+
+### Empty
+
+Use when users should make an explicit selection. Placeholders and segment order follow the locale.
+
+```tsx
+const Empty = () => <DateField label="Billing date" defaultValue={undefined} />;
+```
+
+### Controlled
+
+Use when application state owns the selection. Apply onChange values back to value to display edits.
+
+```tsx
+const Controlled = () => {
+    const [value, setValue] = useState<DateValue | null>(initialValue);
+
+    return (
+        <DateField
+            label="Billing date"
+            defaultValue={initialValue}
+            value={value}
+            onChange={setValue} />
+    );
+};
+```
+
+### Disabled
+
+Use when the field is unavailable. Prevents editing and selection.
+
+```tsx
+const Disabled = () => <DateField label="Billing date" defaultValue={initialValue} isDisabled />;
+```
+
+### Read Only
+
+Use to display a value while preventing edits.
+
+```tsx
+const ReadOnly = () => <DateField label="Billing date" defaultValue={initialValue} isReadOnly />;
+```
+
+### Invalid
+
+Pair isInvalid with an actionable errorMessage. Do not communicate errors using color alone.
+
+```tsx
+const Invalid = () => <DateField
+    label="Billing date"
+    defaultValue={initialValue}
+    isInvalid
+    errorMessage="Choose a date within the billing period." />;
+```
+
+### Date Restrictions
+
+Use minValue, maxValue, and isDateUnavailable to limit dates. Explain restrictions with description.
+
+```tsx
+const DateRestrictions = () => <DateField
+    label="Billing date"
+    defaultValue={initialValue}
+    minValue={parseDate('2026-09-01')}
+    maxValue={parseDate('2026-09-30')}
+    description="Choose dates in September 2026."
+    isDateUnavailable={(date) => date.day === 20} />;
+```
+
+### International
+
+Use I18nProvider to localize date order and reading direction. Localize visible labels in the consuming app.
+
+```tsx
+const International = () => <I18nProvider locale="pl-PL">
+    <DateField label="Billing date" defaultValue={initialValue} />
+</I18nProvider>;
+```

package/dist/skills/maxio-react/references/components-forms-datepicker.md

@@ -0,0 +1,221 @@
+# DatePicker
+
+## Usage Guidelines
+
+### Overview
+
+DatePicker combines localized date entry with a calendar popover for selecting one date.
+
+#### When to Use
+
+- Use for billing, scheduling, or reporting dates.
+- Use when users benefit from both typed entry and calendar selection.
+
+#### When Not to Use
+
+- Use DateRangePicker when a task requires two endpoints.
+- Use Calendar for a month grid that stays visible.
+- Do not use for free-form dates or recurring schedule expressions.
+
+### Variants
+
+| Variant           | Purpose                          | Usage notes                                |
+| :---------------- | :------------------------------- | :----------------------------------------- |
+| Default           | Enter a date                     | Provide a specific label.                  |
+| Empty             | Start without a value            | Date placeholders follow the locale.       |
+| Disabled          | Prevent interaction              | Use when the field is unavailable.         |
+| Read only         | Prevent edits                    | Keep the existing value available to read. |
+| Invalid           | Explain a validation failure     | Supply an actionable error message.        |
+| Date restrictions | Limit permitted dates            | Explain the limits in the description.     |
+| Presets           | Offer frequently used selections | Give each shortcut a clear label.          |
+
+### Behavior
+
+- **Mouse and touch**: select a date segment to edit it. Open the calendar button to browse and select dates.
+- **Keyboard**: Tab moves between editable segments; arrow keys adjust values and typing replaces segment contents. In the calendar, arrow keys move focus and Enter or Space selects a date. Escape dismisses the popover.
+- **Focus management**: preserve visible keyboard focus. Closing the popover returns focus to its trigger.
+- **Controlled state**: use controlled values when application state owns the selection; otherwise supply an initial value.
+- **Presets**: selecting a shortcut updates the selection and closes the popover. Disabled or restricted shortcuts cannot be selected.
+- **Display text**: a null preset shows its label instead of empty date segments. That text is not editable or a keyboard tab stop; users can replace it through the calendar or presets.
+
+### Accessibility
+
+- Provide a visible `label`, or `aria-label` / `aria-labelledby` when the layout supplies visual context.
+- Use `description` for instructions and `errorMessage` for validation feedback; React Aria associates them with the field.
+- Preserve segment keyboard behavior, accessible names, and visible focus indicators.
+- Explain restrictions in text; do not rely on color alone to communicate errors or unavailable dates.
+- Localize preset labels and the preset group name alongside the surrounding interface.
+
+### Content
+
+- Use a task-specific label such as "Billing date".
+- Explain date limits before entry, for example "Choose dates within the billing period."
+- Keep errors actionable, such as "Choose a date on or after the invoice date."
+- Allow for locale-specific date order, time zones, and right-to-left layouts.
+
+### Related
+
+- **[DateField](components-forms-datefield.md)**: Use segmented entry without a calendar popover.
+- **[DateRangePicker](components-forms-daterangepicker.md)**: Collect a start and end date.
+- **[Calendar](components-calendar.md)**: Keep a month grid visible on the page.
+
+## React
+
+```tsx
+import { DatePicker } from '@maxio-com/react-ui-components';
+```
+
+### State Management
+
+#### Controlled
+
+Use `value` and `onChange` as shown in the Controlled story. The parent must apply
+changes to `value` before they appear in the input.
+
+#### Uncontrolled
+
+Use `defaultValue`, as shown in the Default story, to initialize internal state.
+Omit it to start empty.
+
+### Date Values and Forms
+
+Install `@internationalized/date` in the consuming application to construct values
+with `parseDate` or the appropriate date-time constructor. Values are date objects
+from that package, not JavaScript `Date` instances or strings.
+
+A cleared value is `null`. Use `name` for native form submission.
+Use `isRequired`, `validate`, and `validationBehavior` for validation. Pair custom
+invalid state with `isInvalid` and `errorMessage`.
+
+### Localization
+
+Use React Aria's `I18nProvider`, as shown in the International story, to set date
+order and reading direction. Date-time values support `granularity` and time zones.
+
+### Preset Values
+
+Each `presets` entry has a `label`, `value`, and optional `isDisabled`. Set
+`presetsLabel` to localize the group name, which defaults to "Presets".
+A null value clears the selection. Its `label` replaces empty
+segments with non-editable text; the first matching preset supplies that text.
+Preset labels do not become submitted date values or satisfy required validation.
+
+## Imports
+
+```tsx
+import { DatePicker, I18nProvider } from "@maxio-com/react-ui-components";
+```
+
+## Prop Types
+
+### DatePicker
+
+| Prop | Type | Required | Default | Description | Source |
+| --- | --- | --- | --- | --- | --- |
+| `description` | `ReactNode` | no | - | Instructions associated with the field. | DatePickerProps |
+| `errorMessage` | `ReactNode \| ((validation: ValidationResult) => ReactNode)` | no | - | Validation feedback, or a function formatting native validation errors. | DatePickerProps |
+| `label` | `ReactNode` | no | - | Visible accessible label. Supply aria-label when omitted. | DatePickerProps |
+| `presets` | `readonly DatePreset<T>[]` | no | - | Optional shortcuts. Values use the same date type as the picker. | DatePickerProps |
+| `presetsLabel` | `string` | no | - | Accessible name for the preset group; localize alongside preset labels. | DatePickerProps |
+
+## Stories
+
+### Default
+
+Use for an initial, uncontrolled date. Provide a visible label or an accessible name.
+
+```tsx
+const Default = () => <DatePicker label="Billing date" defaultValue={initialValue} />;
+```
+
+### Empty
+
+Use when users should make an explicit selection. Placeholders and segment order follow the locale.
+
+```tsx
+const Empty = () => <DatePicker label="Billing date" defaultValue={undefined} />;
+```
+
+### Controlled
+
+Use when application state owns the selection. Apply onChange values back to value to display edits.
+
+```tsx
+const Controlled = () => {
+    const [value, setValue] = useState<DateValue | null>(initialValue);
+
+    return (
+        <DatePicker
+            label="Billing date"
+            defaultValue={initialValue}
+            value={value}
+            onChange={setValue} />
+    );
+};
+```
+
+### Disabled
+
+Use when the field is unavailable. Prevents editing and selection.
+
+```tsx
+const Disabled = () => <DatePicker label="Billing date" defaultValue={initialValue} isDisabled />;
+```
+
+### Read Only
+
+Use to display a value while preventing edits.
+
+```tsx
+const ReadOnly = () => <DatePicker label="Billing date" defaultValue={initialValue} isReadOnly />;
+```
+
+### Invalid
+
+Pair isInvalid with an actionable errorMessage. Do not communicate errors using color alone.
+
+```tsx
+const Invalid = () => <DatePicker
+    label="Billing date"
+    defaultValue={initialValue}
+    isInvalid
+    errorMessage="Choose a date within the billing period." />;
+```
+
+### Date Restrictions
+
+Use minValue, maxValue, and isDateUnavailable to limit dates. Explain restrictions with description.
+
+```tsx
+const DateRestrictions = () => <DatePicker
+    label="Billing date"
+    defaultValue={initialValue}
+    minValue={parseDate('2026-09-01')}
+    maxValue={parseDate('2026-09-30')}
+    description="Choose dates in September 2026."
+    isDateUnavailable={(date) => date.day === 20} />;
+```
+
+### International
+
+Use I18nProvider to localize date order and reading direction. Localize visible labels in the consuming app.
+
+```tsx
+const International = () => <I18nProvider locale="pl-PL">
+    <DatePicker label="Billing date" defaultValue={initialValue} />
+</I18nProvider>;
+```
+
+### Presets
+
+Use labeled shortcuts for common dates. A null preset clears the value and shows its label as non-editable text. Date restrictions and disabled/read-only state apply to shortcuts.
+
+```tsx
+const Presets = () => <DatePicker
+    label="Billing date"
+    defaultValue={initialValue}
+    presets={[
+      { label: 'Today', value: referenceDate },
+      { label: 'Evergreen', value: null },
+    ]} />;
+```