@brickclay-org/ui 0.0.1

package/README.md

@@ -0,0 +1,578 @@
+# @brickclay/ui
+
+A comprehensive Angular UI component library featuring a rich collection of customizable, accessible components. Built with modern Angular standards, this library provides everything you need to build beautiful and functional user interfaces.
+
+## 🌟 Features
+
+- 📦 **Comprehensive Component Library** - Rich set of UI components for common use cases
+- ♿ **Accessible by Default** - WCAG compliant components with keyboard navigation and screen reader support
+- 🚀 **Angular 20+ Ready** - Built with latest Angular features and standalone components
+- 📱 **Responsive Design** - Mobile-first components that work on all screen sizes
+- 🎯 **Type-Safe** - Full TypeScript support with comprehensive type definitions
+- ⚡ **Lightweight** - Tree-shakeable and optimized for performance
+- 🎛️ **Highly Customizable** - Extensive configuration options for every component
+
+## 📚 Available Components
+
+### Calendar Components
+
+A powerful calendar suite with advanced date and time selection capabilities. The calendar components support single date selection, date ranges, multiple date selection, and integrated time pickers.
+
+*More components coming soon...*
+
+## Installation
+
+```bash
+npm install @brickclay/ui
+```
+
+### Peer Dependencies
+
+This library requires Angular 20.3.0 or higher:
+
+```bash
+npm install @angular/common@^20.3.0 @angular/core@^20.3.0 moment
+```
+
+## Quick Start
+
+### Standalone Component Usage (Recommended)
+
+```typescript
+import { Component } from '@angular/core';
+import { CustomCalendarComponent, CalendarSelection } from '@brickclay/ui';
+
+@Component({
+  standalone: true,
+  selector: 'app-my-component',
+  imports: [CustomCalendarComponent],
+  template: `
+    <brickclay-custom-calendar
+      (selected)="onDateSelected($event)">
+    </brickclay-custom-calendar>
+  `
+})
+export class MyComponent {
+  onDateSelected(selection: CalendarSelection) {
+    console.log('Selected:', selection);
+  }
+}
+```
+
+### Module-based Usage
+
+```typescript
+import { NgModule } from '@angular/core';
+import { CalendarModule } from '@brickclay/ui';
+
+@NgModule({
+  imports: [CalendarModule],
+  // ...
+})
+export class AppModule {}
+```
+
+## 📅 Calendar
+
+The calendar components provide a complete solution for date and time selection in your Angular applications. All components are standalone and can be imported individually or as part of the `CalendarModule`.
+
+### Components Overview
+
+1. **CustomCalendarComponent** (`brickclay-custom-calendar`) - Main calendar component with support for single date, date range, and multiple date selection
+2. **ScheduledDatePickerComponent** (`brickclay-scheduled-date-picker`) - Advanced scheduling component with time configuration for events
+3. **TimePickerComponent** (`brickclay-time-picker`) - Standalone time selection component with scrollable pickers
+
+### CustomCalendarComponent
+
+A versatile calendar component that supports single date, date range, and multiple date selection modes.
+
+#### Basic Example
+
+```typescript
+import { CustomCalendarComponent, CalendarSelection } from '@brickclay/ui';
+
+@Component({
+  template: `
+    <brickclay-custom-calendar
+      [singleDatePicker]="false"
+      [dualCalendar]="true"
+      [enableTimepicker]="true"
+      [showRanges]="true"
+      [placeholder]="'Select date range'"
+      (selected)="onDateSelected($event)">
+    </brickclay-custom-calendar>
+  `
+})
+export class MyComponent {
+  onDateSelected(selection: CalendarSelection) {
+    console.log('Start:', selection.startDate);
+    console.log('End:', selection.endDate);
+  }
+}
+```
+
+#### Component Selector
+
+`<brickclay-custom-calendar>`
+
+#### Inputs
+
+| Input | Type | Default | Description |
+|-------|------|---------|-------------|
+| `enableTimepicker` | `boolean` | `false` | Enable time selection |
+| `autoApply` | `boolean` | `false` | Automatically apply selection when date is chosen |
+| `closeOnAutoApply` | `boolean` | `false` | Close calendar after auto-apply |
+| `showCancel` | `boolean` | `true` | Show cancel button in footer |
+| `singleDatePicker` | `boolean` | `false` | Enable single date selection mode |
+| `dualCalendar` | `boolean` | `false` | Show two calendars side-by-side |
+| `showRanges` | `boolean` | `true` | Show predefined date range buttons |
+| `multiDateSelection` | `boolean` | `false` | Enable multiple date selection |
+| `inline` | `boolean` | `false` | Always show calendar (no dropdown) |
+| `minDate` | `Date` | `undefined` | Minimum selectable date |
+| `maxDate` | `Date` | `undefined` | Maximum selectable date |
+| `placeholder` | `string` | `'Select date range'` | Input placeholder text |
+| `opens` | `'left' \| 'right' \| 'center'` | `'left'` | Dropdown alignment |
+| `drop` | `'up' \| 'down'` | `'down'` | Dropdown direction |
+| `displayFormat` | `string` | `'MM/DD/YYYY'` | Date display format (moment format) |
+| `customRanges` | `Record<string, CalendarRange>` | `undefined` | Custom predefined ranges |
+| `selectedValue` | `CalendarSelection \| null` | `null` | Pre-selected date(s) |
+| `isDisplayCrossIcon` | `boolean` | `true` | Show/hide clear button |
+
+#### Outputs
+
+| Output | Type | Description |
+|--------|------|-------------|
+| `selected` | `EventEmitter<CalendarSelection>` | Emitted when date selection changes |
+| `opened` | `EventEmitter<void>` | Emitted when calendar opens |
+| `closed` | `EventEmitter<void>` | Emitted when calendar closes |
+
+#### Usage Examples
+
+**Single Date Selection:**
+
+```typescript
+<brickclay-custom-calendar
+  [singleDatePicker]="true"
+  [placeholder]="'Select a date'"
+  (selected)="onDateSelected($event)">
+</brickclay-custom-calendar>
+```
+
+**Date Range with Time Picker:**
+
+```typescript
+<brickclay-custom-calendar
+  [dualCalendar]="true"
+  [enableTimepicker]="true"
+  [enableSeconds]="true"
+  (selected)="onRangeSelected($event)">
+</brickclay-custom-calendar>
+```
+
+**Multiple Date Selection:**
+
+```typescript
+<brickclay-custom-calendar
+  [multiDateSelection]="true"
+  [inline]="true"
+  (selected)="onMultipleDatesSelected($event)">
+</brickclay-custom-calendar>
+```
+
+**Inline Calendar:**
+
+```typescript
+<brickclay-custom-calendar
+  [inline]="true"
+  [dualCalendar]="false"
+  [showRanges]="false"
+  (selected)="onDateSelected($event)">
+</brickclay-custom-calendar>
+```
+
+**Custom Date Ranges:**
+
+```typescript
+import { CalendarRange } from '@brickclay/ui';
+
+const customRanges: Record<string, CalendarRange> = {
+  'Last Week': {
+    start: new Date(2024, 0, 1),
+    end: new Date(2024, 0, 7)
+  },
+  'This Quarter': {
+    start: new Date(2024, 0, 1),
+    end: new Date(2024, 2, 31)
+  }
+};
+
+<brickclay-custom-calendar
+  [customRanges]="customRanges"
+  [showRanges]="true"
+  (selected)="onDateSelected($event)">
+</brickclay-custom-calendar>
+```
+
+**Date Constraints:**
+
+```typescript
+<brickclay-custom-calendar
+  [minDate]="new Date(2024, 0, 1)"
+  [maxDate]="new Date(2024, 11, 31)"
+  (selected)="onDateSelected($event)">
+</brickclay-custom-calendar>
+```
+
+**Pre-selected Values:**
+
+```typescript
+export class MyComponent {
+  selectedValue: CalendarSelection = {
+    startDate: new Date(2024, 5, 15),
+    endDate: new Date(2024, 5, 20)
+  };
+
+  onDateChange() {
+    this.selectedValue = {
+      startDate: new Date(),
+      endDate: new Date()
+    };
+  }
+}
+
+<brickclay-custom-calendar
+  [selectedValue]="selectedValue"
+  (selected)="onDateSelected($event)">
+</brickclay-custom-calendar>
+```
+
+### ScheduledDatePickerComponent
+
+A comprehensive date and time scheduling component with three modes: single date, multiple dates, and date range, each with time configuration.
+
+#### Basic Example
+
+```typescript
+import { ScheduledDatePickerComponent, ScheduledDateSelection } from '@brickclay/ui';
+
+@Component({
+  template: `
+    <brickclay-scheduled-date-picker
+      [timeFormat]="12"
+      (scheduled)="onScheduled($event)">
+    </brickclay-scheduled-date-picker>
+  `
+})
+export class MyComponent {
+  onScheduled(selection: ScheduledDateSelection) {
+    console.log('Mode:', selection.mode);
+    if (selection.mode === 'single' && selection.singleDate) {
+      console.log('Start:', selection.singleDate.startDate);
+      console.log('End:', selection.singleDate.endDate);
+      console.log('All Day:', selection.singleDate.allDay);
+    }
+  }
+}
+```
+
+#### Component Selector
+
+`<brickclay-scheduled-date-picker>`
+
+#### Inputs
+
+| Input | Type | Default | Description |
+|-------|------|---------|-------------|
+| `timeFormat` | `12 \| 24` | `12` | Time format (12-hour or 24-hour) |
+| `enableSeconds` | `boolean` | `false` | Enable seconds in time picker |
+
+#### Outputs
+
+| Output | Type | Description |
+|--------|------|-------------|
+| `scheduled` | `EventEmitter<ScheduledDateSelection>` | Emitted when selection changes |
+| `cleared` | `EventEmitter<void>` | Emitted when clear button is clicked |
+
+#### Features
+
+- **Single Date Mode**: Select one date with optional start and end times
+- **Multiple Dates Mode**: Select multiple dates, each with individual time configuration
+- **Date Range Mode**: Select a date range with start and end times
+- **All Day Toggle**: Mark dates as all-day events
+- **Time Configuration**: Individual time pickers for each date/range
+
+### TimePickerComponent
+
+A standalone time picker component with scrollable hour, minute, and AM/PM selectors.
+
+#### Basic Example
+
+```typescript
+import { TimePickerComponent } from '@brickclay/ui';
+
+@Component({
+  template: `
+    <brickclay-time-picker
+      [value]="selectedTime"
+      [label]="'Start Time'"
+      [timeFormat]="12"
+      (timeChange)="onTimeChange($event)">
+    </brickclay-time-picker>
+  `
+})
+export class MyComponent {
+  selectedTime = '1:00 AM';
+
+  onTimeChange(time: string) {
+    this.selectedTime = time;
+    console.log('New time:', time);
+  }
+}
+```
+
+#### Component Selector
+
+`<brickclay-time-picker>`
+
+#### Inputs
+
+| Input | Type | Default | Description |
+|-------|------|---------|-------------|
+| `value` | `string` | `'1:00 AM'` | Current time value (format: "H:MM AM/PM" or "HH:MM") |
+| `label` | `string` | `'Time'` | Label text |
+| `placeholder` | `string` | `'Select time'` | Placeholder text |
+| `position` | `'left' \| 'right'` | `'left'` | Dropdown position |
+| `pickerId` | `string` | `''` | Unique identifier for the picker |
+| `closePicker` | `number` | `0` | Counter to trigger picker close |
+| `timeFormat` | `12 \| 24` | `12` | Time format (12-hour or 24-hour) |
+| `showSeconds` | `boolean` | `false` | Show seconds selector |
+
+#### Outputs
+
+| Output | Type | Description |
+|--------|------|-------------|
+| `timeChange` | `EventEmitter<string>` | Emitted when time changes |
+| `pickerOpened` | `EventEmitter<string>` | Emitted when picker opens |
+| `pickerClosed` | `EventEmitter<string>` | Emitted when picker closes |
+
+#### Features
+
+- Scrollable time selectors
+- Keyboard navigation support
+- 12-hour and 24-hour formats
+- Optional seconds support
+- Multiple picker coordination (only one open at a time)
+- Click outside to close
+
+#### Time Format Examples
+
+**12-hour format:**
+```typescript
+value="1:00 AM"
+value="12:30 PM"
+value="11:45 PM"
+```
+
+**24-hour format:**
+```typescript
+value="01:00"
+value="13:30"
+value="23:45"
+```
+
+## 📐 TypeScript Interfaces
+
+### CalendarRange
+
+```typescript
+interface CalendarRange {
+  start: Date;
+  end: Date;
+}
+```
+
+### CalendarSelection
+
+```typescript
+interface CalendarSelection {
+  startDate: Date | null;
+  endDate: Date | null;
+  selectedDates?: Date[]; // For multi-date selection
+}
+```
+
+### TimeConfiguration
+
+```typescript
+interface TimeConfiguration {
+  date: Date;
+  allDay: boolean;
+  startTime: string; // Format: "HH:mm" or "HH:mm:ss"
+  endTime: string;
+}
+```
+
+### ScheduledDateSelection
+
+```typescript
+interface ScheduledDateSelection {
+  mode: 'single' | 'multiple' | 'range';
+  singleDate?: {
+    startDate: Date;
+    endDate: Date;
+    allDay: boolean;
+    startTime: string;
+    endTime: string;
+  };
+  multipleDates?: TimeConfiguration[];
+  dateRange?: {
+    startDate: Date;
+    endDate: Date;
+    allDay: boolean;
+    startTime: string;
+    endTime: string;
+  };
+}
+```
+
+## 🎯 Common Use Cases
+
+### Form Integration
+
+```typescript
+import { FormBuilder, FormGroup, Validators } from '@angular/forms';
+import { CustomCalendarComponent } from '@brickclay/ui';
+
+export class BookingFormComponent {
+  bookingForm: FormGroup;
+
+  constructor(private fb: FormBuilder) {
+    this.bookingForm = this.fb.group({
+      checkIn: [null, Validators.required],
+      checkOut: [null, Validators.required]
+    });
+  }
+
+  onDateSelected(selection: CalendarSelection) {
+    this.bookingForm.patchValue({
+      checkIn: selection.startDate,
+      checkOut: selection.endDate
+    });
+  }
+}
+```
+
+### Reactive Forms
+
+```typescript
+<brickclay-custom-calendar
+  [selectedValue]="form.get('dateRange')?.value"
+  (selected)="form.patchValue({ dateRange: $event })">
+</brickclay-custom-calendar>
+```
+
+### Date Filtering
+
+```typescript
+export class DataTableComponent {
+  filterDates: CalendarSelection = { startDate: null, endDate: null };
+
+  onDateFilter(selection: CalendarSelection) {
+    this.filterDates = selection;
+    this.loadFilteredData();
+  }
+
+  loadFilteredData() {
+    const filtered = this.data.filter(item => {
+      if (!this.filterDates.startDate || !this.filterDates.endDate) {
+        return true;
+      }
+      return item.date >= this.filterDates.startDate! && 
+             item.date <= this.filterDates.endDate!;
+    });
+  }
+}
+```
+
+## 📦 Assets Configuration
+
+The calendar components require SVG icons. Configure your `angular.json` to copy assets:
+
+```json
+{
+  "glob": "**/*",
+  "input": "node_modules/@brickclay/ui/assets",
+  "output": "assets"
+}
+```
+
+Or manually copy assets from:
+```
+node_modules/@brickclay/ui/assets/calender/* → your-app/public/assets/calender/
+```
+
+## 🔧 Service
+
+### CalendarManagerService
+
+A service that manages multiple calendar instances, ensuring only one calendar is open at a time when not in inline mode. Used internally by `CustomCalendarComponent`.
+
+## 🌐 Browser Support
+
+- Chrome (latest)
+- Firefox (latest)
+- Safari (latest)
+- Edge (latest)
+
+## 📦 Dependencies
+
+- Angular 20.3.0+
+- moment (for date formatting)
+
+## 🤝 Contributing
+
+We welcome contributions! Please see our contributing guidelines for more information.
+
+## 📄 License
+
+MIT
+
+## 📞 Support
+
+For issues, feature requests, or contributions, please visit our [GitHub repository](https://github.com/brickclay/ui).
+
+## 🗺️ Roadmap
+
+- [ ] Button components
+- [ ] Input components
+- [ ] Card components
+- [ ] Modal/Dialog components
+- [ ] Table components
+- [ ] Form components
+- [ ] Navigation components
+- [ ] Loading/Spinner components
+- [ ] Toast/Notification components
+- [ ] More calendar features
+
+## 📝 Changelog
+
+### Version 0.0.1
+
+**Initial Release:**
+- ✅ Calendar component suite
+  - Single date selection
+  - Date range selection
+  - Multiple date selection
+  - Time picker integration
+  - Inline and dropdown modes
+  - Dual calendar view
+  - Custom date ranges
+  - Date constraints (min/max)
+- ✅ Scheduled date picker component
+- ✅ Standalone time picker component
+- ✅ TypeScript definitions
+- ✅ Comprehensive documentation
+
+---
+
+**Built with ❤️ by the Brickclay team**