@reliability-design/web 1.0.3 → 1.1.1

package/dist/components/rel-date-picker/README.md

@@ -0,0 +1,253 @@
+# rel-date-picker
+
+A fully accessible date picker component built with Lit for the Reliability Design System. Features a trigger button with calendar popover including month/year dropdowns.
+
+## Features
+
+- Trigger button with calendar popover
+- Month and year dropdowns for easy navigation
+- Single date selection
+- Optional clear button
+- Min/max date constraints
+- Custom disabled date predicate
+- Keyboard navigation
+- Full ARIA support
+- Token-driven styling
+
+## Usage
+
+### Basic
+
+```html
+<rel-date-picker></rel-date-picker>
+```
+
+### With Value
+
+```html
+<rel-date-picker value="2026-01-16"></rel-date-picker>
+```
+
+### With Label
+
+```html
+<rel-date-picker label="Select appointment date"></rel-date-picker>
+```
+
+### With Min/Max
+
+```html
+<rel-date-picker
+  min="2026-01-01"
+  max="2026-12-31"
+  placeholder="Select a date in 2026"
+></rel-date-picker>
+```
+
+### Clearable
+
+```html
+<rel-date-picker value="2026-01-16" clearable></rel-date-picker>
+```
+
+### Disabled
+
+```html
+<rel-date-picker value="2026-01-16" disabled></rel-date-picker>
+```
+
+### Programmatic Control (JavaScript)
+
+```javascript
+const picker = document.querySelector('rel-date-picker');
+
+// Set value
+picker.value = '2026-01-16';
+
+// Open programmatically
+picker.open = true;
+
+// Custom disabled dates (e.g., disable weekends)
+picker.isDateDisabled = (date) => {
+  const day = date.getDay();
+  return day === 0 || day === 6; // Sunday or Saturday
+};
+
+// Listen to changes
+picker.addEventListener('rel-change', (e) => {
+  console.log('Selected date:', e.detail.value); // "2026-01-16"
+  console.log('Date object:', e.detail.date); // Date object
+});
+
+// Listen to popover open/close
+picker.addEventListener('rel-open-change', (e) => {
+  console.log('Popover open:', e.detail.open); // boolean
+});
+```
+
+## Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `value` | `string \| null` | `null` | Selected date in ISO format (YYYY-MM-DD) |
+| `placeholder` | `string` | `"Select date"` | Placeholder text when no date selected |
+| `label` | `string \| null` | `null` | Accessible label for the date picker |
+| `disabled` | `boolean` | `false` | Disables all interaction |
+| `required` | `boolean` | `false` | Sets aria-required (no validation logic) |
+| `min` | `string \| null` | `null` | Minimum selectable date (ISO format) |
+| `max` | `string \| null` | `null` | Maximum selectable date (ISO format) |
+| `week-start` | `"sun" \| "mon"` | `"sun"` | First day of the week |
+| `locale` | `string` | `"en-US"` | Locale for month names (uses Intl.DateTimeFormat) |
+| `open` | `boolean` | `false` | Controls popover open state |
+| `close-on-select` | `boolean` | `true` | Close popover after selecting a date |
+| `clearable` | `boolean` | `false` | Show clear button when date is selected |
+
+## Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `isDateDisabled` | `(date: Date) => boolean` | Custom function to disable specific dates |
+
+## Events
+
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `rel-change` | `{ value: string \| null, date: Date \| null }` | Fired when selected date changes |
+| `rel-open-change` | `{ open: boolean }` | Fired when popover opens/closes |
+
+## Keyboard Navigation
+
+### Trigger Button
+- **Enter/Space**: Opens the popover
+- **Arrow Down**: Opens the popover
+
+### Inside Calendar
+- **Arrow keys**: Navigate days (left/right) and weeks (up/down)
+- **Home/End**: Jump to week start/end
+- **PageUp/PageDown**: Change month
+- **Shift + PageUp/PageDown**: Change year
+- **Enter/Space**: Select focused day
+- **Escape**: Close popover
+
+### Month/Year Dropdowns
+- **Tab**: Navigate between dropdowns
+- **Click**: Select month or year
+
+## Calendar Features
+
+### Month Dropdown
+- Lists all 12 months localized to the specified locale
+- Scroll through months quickly
+- Current month is highlighted
+
+### Year Dropdown
+- Scrollable list of years
+- Range automatically calculated:
+  - With min/max: Uses constrained range with buffer
+  - Without: Defaults to [currentYear - 100, currentYear + 10]
+- Current year is highlighted
+
+## Custom Disabled Dates
+
+Use the `isDateDisabled` property to implement custom logic:
+
+```javascript
+const picker = document.querySelector('rel-date-picker');
+
+// Disable weekends
+picker.isDateDisabled = (date) => {
+  const day = date.getDay();
+  return day === 0 || day === 6;
+};
+
+// Disable specific dates
+const blackoutDates = ['2026-01-15', '2026-01-20', '2026-01-25'];
+picker.isDateDisabled = (date) => {
+  const iso = date.toISOString().split('T')[0];
+  return blackoutDates.includes(iso);
+};
+
+// Disable dates before today
+picker.isDateDisabled = (date) => {
+  const today = new Date();
+  today.setHours(0, 0, 0, 0);
+  return date < today;
+};
+```
+
+## Complete Example
+
+```html
+<rel-date-picker
+  id="appointment-picker"
+  label="Appointment Date"
+  placeholder="Choose a date"
+  min="2026-01-01"
+  max="2026-12-31"
+  clearable
+  required
+></rel-date-picker>
+
+<script>
+  const picker = document.getElementById('appointment-picker');
+
+  // Disable weekends
+  picker.isDateDisabled = (date) => {
+    const day = date.getDay();
+    return day === 0 || day === 6;
+  };
+
+  // Handle selection
+  picker.addEventListener('rel-change', (e) => {
+    if (e.detail.value) {
+      console.log('Appointment scheduled for:', e.detail.value);
+    } else {
+      console.log('Appointment cleared');
+    }
+  });
+
+  // Handle popover state
+  picker.addEventListener('rel-open-change', (e) => {
+    console.log('Calendar', e.detail.open ? 'opened' : 'closed');
+  });
+</script>
+```
+
+## Accessibility
+
+- Trigger button has proper `aria-haspopup`, `aria-expanded`, and `aria-label`
+- Calendar popover uses `role="dialog"`
+- Day buttons use `role="gridcell"` with proper `aria-label` and `aria-selected`
+- All interactive elements are keyboard accessible
+- Focus management:
+  - Opening popover focuses first day
+  - Closing popover returns focus to trigger
+- Visible focus rings on all interactive elements
+- Respects user's locale for month names and date formatting
+
+## Styling
+
+The component uses design tokens from the Reliability Design System. All colors, spacing, and typography are inherited from CSS variables.
+
+Key tokens used:
+- `--rel-colors-*` for all colors
+- `--rel-spacing-*` for spacing
+- `--rel-fontSizes-*`, `--rel-fontWeights-*` for typography
+- `--rel-borders-*` for borders and radius
+- `--rel-shadows-*` for popover shadow
+- Selected date: `--rel-colors-green-primary`
+- Today indicator: `--rel-colors-blue-primary`
+- Focus rings: `--rel-colors-blue-primary`
+
+## Date Format
+
+- **Input/Output**: ISO 8601 format (YYYY-MM-DD)
+- **Display**: Localized format based on `locale` attribute
+- **Example**:
+  - Value: `"2026-01-16"`
+  - Display (en-US): `"January 16, 2026"`
+  - Display (es-ES): `"16 de enero de 2026"`
+
+## Browser Support
+
+Works in all modern browsers with ES2020 support and native Web Components.

package/dist/components/rel-date-picker/index.ts

@@ -0,0 +1 @@
+export * from "./rel-date-picker";