@cube-dev/ui-kit 0.120.1 → 0.121.1

package/docs/components/fields/DatePicker.md

@@ -0,0 +1,227 @@
+# DatePicker
+
+A date picker combines a text input with a calendar interface, allowing users to select dates through typing or graphical selection. It supports various date formats, validation, and internationalization features.
+
+## When to Use
+
+- Allow users to select a specific date from a calendar interface
+- Provide date input with visual calendar for better user experience
+- Enable date range selection for booking or filtering scenarios
+- Support various date formats and locales for international applications
+- Offer accessible date entry for users with different abilities
+
+## Component
+
+---
+
+### Properties
+
+- **`description`** `string` — Additional descriptive text
+- **`placeholder`** `string` — Placeholder text when no date is selected
+- **`value`** `DateValue` — The current date value (controlled)
+- **`defaultValue`** `DateValue` — The default date value (uncontrolled)
+- **`placeholderValue`** `DateValue` — Date used as placeholder when calendar opens
+- **`minValue`** `DateValue` — The minimum allowed date
+- **`maxValue`** `DateValue` — The maximum allowed date
+- **`granularity`** `'day' | 'hour' | 'minute' | 'second'` (default: `day`) — Determines the smallest selectable unit
+- **`size`** `'small' | 'medium' | 'large' | (string & {})` (default: `medium`) — DatePicker size
+- **`showMonthAndYearPickers`** `boolean` (default: `false`) — Whether to show month and year picker dropdowns
+- **`useLocale`** `boolean` (default: `false`) — Whether to use locale-specific date formatting
+- **`maxVisibleMonths`** `number` (default: `1`) — Maximum number of months to display in calendar
+- **`onChange`** `(value: DateValue | null) => void` — Callback fired when the date value changes
+- **`onBlur`** `(e: FocusEvent) => void` — Callback fired when the date picker loses focus
+- **`onFocus`** `(e: FocusEvent) => void` — Callback fired when the date picker receives focus
+- **`onOpenChange`** `(isOpen: boolean) => void` — Callback fired when the calendar opens or closes
+
+### Base Properties
+
+Supports [Base properties](../../BaseProperties.md)
+
+### Field Properties
+
+Supports all [Field properties](../../FieldProperties.md)
+
+### Styling Properties
+
+#### styles
+
+Customizes the root wrapper element of the component.
+
+**Sub-elements:**
+- `Prefix` - Element displayed before the input (icon area)
+- `Suffix` - Element displayed after the input (calendar button area)
+- `State` - Container for validation state indicators
+- `InputIcon` - Icon displayed within the input area
+- `ValidationIcon` - Icon displayed for validation state
+
+#### inputStyles
+
+Customizes the date input field specifically.
+
+#### wrapperStyles
+
+Customizes the input wrapper container.
+
+#### triggerStyles
+
+Customizes the calendar trigger button.
+
+### Style Properties
+
+The DatePicker component supports all standard style properties:
+
+`display`, `font`, `preset`, `hide`, `opacity`, `whiteSpace`, `gridArea`, `order`, `gridColumn`, `gridRow`, `placeSelf`, `alignSelf`, `justifySelf`, `zIndex`, `margin`, `inset`, `position`, `width`, `height`, `flexBasis`, `flexGrow`, `flexShrink`, `flex`, `reset`, `padding`, `paddingInline`, `paddingBlock`, `shadow`, `border`, `radius`, `overflow`, `scrollbar`, `outline`, `textAlign`, `color`, `fill`, `fade`, `textTransform`, `fontWeight`, `fontStyle`, `flow`, `placeItems`, `placeContent`, `alignItems`, `alignContent`, `justifyItems`, `justifyContent`, `align`, `justify`, `gap`, `columnGap`, `rowGap`, `gridColumns`, `gridRows`, `gridTemplate`, `gridAreas`
+
+### Modifiers
+
+The `mods` property accepts the following modifiers you can override:
+
+- **`opened`** `boolean` — Whether the calendar is open
+- **`focused`** `boolean` — Whether the input has focus
+- **`disabled`** `boolean` — Whether the date picker is disabled
+- **`invalid`** `boolean` — Whether the date picker has validation errors
+- **`valid`** `boolean` — Whether the date picker is valid
+- **`hovered`** `boolean` — Whether the date picker is being hovered
+- **`inside-form`** `boolean` — Whether the date picker is inside a form field
+
+## Variants
+
+### Sizes
+
+- `small` - Compact size for dense interfaces
+- `medium` - Standard size
+- `large` - Emphasized size for important date selections
+
+## Examples
+
+### Basic Usage
+
+```jsx
+<DatePicker label="Select date" />
+```
+
+### With Default Value
+
+```jsx
+<DatePicker
+  label="Appointment date"
+  defaultValue={today(getLocalTimeZone())}
+/>
+```
+
+### Date Range
+
+```jsx
+<DatePicker
+  label="Start date"
+  minValue={today(getLocalTimeZone())}
+  maxValue={today(getLocalTimeZone()).add({months: 6})}
+/>
+```
+
+### With Time
+
+```jsx
+<DatePicker
+  label="Event datetime"
+  granularity="minute"
+  defaultValue={now(getLocalTimeZone())}
+/>
+```
+
+### Custom Format
+
+```jsx
+<DatePicker
+  label="Birth date"
+  showMonthAndYearPickers
+  maxValue={today(getLocalTimeZone())}
+/>
+```
+
+### With Validation
+
+```jsx
+<DatePicker
+  label="Required date"
+  isRequired
+  validationState="invalid"
+  errorMessage="Please select a date"
+/>
+```
+
+### Disabled State
+
+```jsx
+<DatePicker
+  label="Disabled date picker"
+  isDisabled
+  value={today(getLocalTimeZone())}
+/>
+```
+
+## Accessibility
+
+### Keyboard Navigation
+
+- `Tab` - Moves focus to the date picker
+- `Space/Enter` - Opens the calendar popup when focused on trigger button
+- `Arrow Keys` - Navigate between date segments in the input
+- `Arrow Keys` - Navigate calendar dates when calendar is open
+- `Enter` - Selects the focused date in calendar
+- `Escape` - Closes the calendar without selecting
+- `Home/End` - Navigate to start/end of month in calendar
+- `Page Up/Down` - Navigate to previous/next month
+
+### Screen Reader Support
+
+- Component announces as "date picker" to screen readers
+- Selected date and format are clearly announced
+- Calendar navigation and date selection are properly communicated
+- Validation errors and requirements are announced
+
+### ARIA Properties
+
+- `aria-label` - Provides accessible label when no visible label exists
+- `aria-labelledby` - References external label elements
+- `aria-describedby` - References additional descriptive text
+- `aria-expanded` - Indicates if calendar is open
+- `aria-invalid` - Indicates validation state
+- `aria-required` - Indicates if date selection is required
+
+## Best Practices
+
+1. **Do**: Provide clear labels and format hints
+   ```jsx
+   <DatePicker
+     label="Event date"
+     description="Format: MM/DD/YYYY"
+   />
+   ```
+
+2. **Don't**: Use date picker for approximate dates
+   ```jsx
+   <DatePicker label="Approximately when?" /> {/* Use text input instead */}
+   ```
+
+3. **Validation**: Set appropriate min/max values for date ranges
+4. **Format**: Use consistent date formats throughout your application
+5. **Accessibility**: Always provide meaningful labels and descriptions
+6. **Internationalization**: Support user's locale and date format preferences
+
+## Integration with Forms
+
+This component supports all [Field properties](../../FieldProperties.md) when used within a Form.
+
+## Suggested Improvements
+
+- Add support for date shortcuts (today, tomorrow, next week)
+- Implement preset date ranges for quick selection
+- Add support for multiple date selection modes
+- Consider adding time zone selection capabilities
+- Implement custom calendar themes and styling
+
+## Related Components
+
+- DateRangePicker - For selecting date ranges
+- TimeInput - For time-only selection

package/docs/components/fields/FileInput.md

@@ -0,0 +1,194 @@
+# FileInput
+
+A file input component that allows users to select and upload files through a customizable interface. It supports drag-and-drop functionality, file type restrictions, and multiple file selection.
+
+## When to Use
+
+- Allow users to upload documents, images, or other files
+- Provide drag-and-drop file upload functionality
+- Enable multiple file selection for batch uploads
+- Restrict file types and sizes for specific use cases
+- Create a more accessible alternative to the native file input
+
+## Component
+
+---
+
+### Properties
+
+- **`placeholder`** `string` — Text displayed when no file is selected
+- **`buttonText`** `string` — Text displayed on the selection button
+- **`accept`** `string` — Comma-separated list of accepted file types
+- **`multiple`** `boolean` (default: `false`) — Whether multiple files can be selected
+- **`capture`** `undefined | 'user' | 'environment'` — Camera to use for file capture on mobile devices
+- **`type`** `'file' | 'text'` (default: `file`) — How to process the selected file(s)
+- **`onChange`** `function` — Callback fired when files are selected
+- **`onBlur`** `function` — Callback fired when the file input loses focus
+- **`onFocus`** `function` — Callback fired when the file input receives focus
+
+### Base Properties
+
+Supports [Base properties](../../BaseProperties.md)
+
+### Field Properties
+
+Supports all [Field properties](../../FieldProperties.md)
+
+### Styling Properties
+
+#### styles
+
+Customizes the root element of the component.
+
+**Sub-elements:**
+- `Button` - The clickable button element for file selection
+- `Placeholder` - Text shown when no file is selected
+- `Value` - Text showing the selected file name(s)
+- `Input` - The hidden native file input element
+
+### Style Properties
+
+The FileInput component supports all standard style properties:
+
+`display`, `font`, `preset`, `hide`, `opacity`, `whiteSpace`, `gridArea`, `order`, `gridColumn`, `gridRow`, `placeSelf`, `alignSelf`, `justifySelf`, `zIndex`, `margin`, `inset`, `position`, `width`, `height`, `flexBasis`, `flexGrow`, `flexShrink`, `flex`, `reset`, `padding`, `paddingInline`, `paddingBlock`, `shadow`, `border`, `radius`, `overflow`, `scrollbar`, `outline`, `textAlign`, `color`, `fill`, `fade`, `textTransform`, `fontWeight`, `fontStyle`, `flow`, `placeItems`, `placeContent`, `alignItems`, `alignContent`, `justifyItems`, `justifyContent`, `align`, `justify`, `gap`, `columnGap`, `rowGap`, `gridColumns`, `gridRows`, `gridTemplate`, `gridAreas`
+
+### Modifiers
+
+The `mods` property accepts the following modifiers you can override:
+
+- **`drag-hover`** `boolean` — Whether files are being dragged over the component
+- **`disabled`** `boolean` — Whether the file input is disabled
+- **`invalid`** `boolean` — Whether the file input has validation errors
+- **`valid`** `boolean` — Whether the file input is valid
+- **`focused`** `boolean` — Whether the file input has focus
+- **`inside-form`** `boolean` — Whether the file input is inside a form field
+
+## Examples
+
+### Basic Usage
+
+```jsx
+<FileInput label="Upload document" />
+```
+
+### Multiple Files
+
+```jsx
+<FileInput
+  label="Upload images"
+  multiple
+  accept="image/*"
+/>
+```
+
+### With File Type Restrictions
+
+```jsx
+<FileInput
+  label="Upload PDF"
+  accept=".pdf"
+  placeholder="Select PDF file..."
+/>
+```
+
+### Custom Button Text
+
+```jsx
+<FileInput
+  label="Profile picture"
+  buttonText="Choose Photo"
+  accept="image/jpeg,image/png"
+/>
+```
+
+### With Validation
+
+```jsx
+<FileInput
+  label="Required document"
+  isRequired
+  validationState="invalid"
+  errorMessage="Please select a file"
+/>
+```
+
+### Disabled State
+
+```jsx
+<FileInput
+  label="Disabled file input"
+  isDisabled
+  buttonText="Upload"
+/>
+```
+
+### Custom Placeholder
+
+```jsx
+<FileInput
+  label="Document upload"
+  placeholder="Drag files here or click to browse..."
+  buttonText="Browse"
+/>
+```
+
+## Accessibility
+
+### Keyboard Navigation
+
+- `Tab` - Moves focus to the file input button
+- `Space/Enter` - Opens the file selection dialog
+- Screen readers can access the hidden file input directly
+
+### Screen Reader Support
+
+- Component announces as "button" for file selection
+- Selected file names are announced when changed
+- File type restrictions and requirements are communicated
+- Validation errors are announced when present
+
+### ARIA Properties
+
+- `aria-label` - Provides accessible label when no visible label exists
+- `aria-labelledby` - References external label elements
+- `aria-describedby` - References additional descriptive text
+- `aria-required` - Indicates if file selection is required
+- `aria-invalid` - Indicates validation state
+
+## Best Practices
+
+1. **Do**: Provide clear file type and size requirements
+   ```jsx
+   <FileInput
+     label="Upload resume"
+     accept=".pdf,.doc,.docx"
+     description="PDF or Word document, max 5MB"
+   />
+   ```
+
+2. **Don't**: Use unclear button text or placeholders
+   ```jsx
+   <FileInput buttonText="Click" /> {/* What does clicking do? */}
+   ```
+
+3. **File Types**: Always specify accepted file types for better UX
+4. **Size Limits**: Implement file size validation for uploads
+5. **Multiple Files**: Clearly indicate when multiple files are allowed
+6. **Error Handling**: Provide helpful feedback for invalid files
+
+## Integration with Forms
+
+This component supports all [Field properties](../../FieldProperties.md) when used within a Form.
+
+## Suggested Improvements
+
+- Add visual progress indicators for file uploads
+- Implement file preview functionality for images
+- Add support for file size and type validation messages
+- Consider adding file removal functionality for selected files
+- Implement custom drag-and-drop visual feedback
+
+## Related Components
+
+- [Button](../actions/Button.md) - For triggering file dialogs programmatically
+- [Field](../form/Field.md) - For form integration and validation