@brickclay/calendar 0.0.6

package/README.md

@@ -0,0 +1,417 @@
+# Calendar (Angular library)
+
+Reusable calendar/date & time picker components packaged as an Angular library.
+
+This package supports:
+- date range selection
+- single date selection
+- multi-date selection
+- optional time picker (12/24h, optional seconds)
+- inline mode (always visible) or dropdown mode
+
+## Quick start (copy/paste)
+
+### 1) Install
+
+After you publish to npm:
+
+```bash
+npm i @brickclay/calendar
+```
+
+Before publishing (install from local build):
+
+```bash
+# from repo root
+ng build calendar
+cd dist/calendar
+npm pack
+# then install the generated .tgz in your app:
+# (for scoped packages like @brickclay/calendar, npm pack outputs something like:)
+#   brickclay-calendar-<version>.tgz
+npm i path/to/brickclay-calendar-<version>.tgz
+```
+
+### 2) Use in a standalone component (recommended)
+
+```ts
+import { Component } from '@angular/core';
+import { CalendarComponent, CalendarSelection } from '@brickclay/calendar';
+
+@Component({
+  standalone: true,
+  selector: 'app-demo',
+  imports: [CalendarComponent],
+  template: `
+    <lib-calendar
+      [dualCalendar]="true"
+      [enableTimepicker]="true"
+      [autoApply]="true"
+      [closeOnAutoApply]="true"
+      [displayFormat]="'YYYY-MM-DD'"
+      (selected)="onSelected($event)"
+    />
+  `
+})
+export class DemoComponent {
+  onSelected(selection: CalendarSelection) {
+    console.log(selection);
+  }
+}
+```
+
+## Peer dependencies (required in the consuming app)
+
+This library declares these as **peerDependencies**. Your app must already include them:
+
+- `@angular/common`
+- `@angular/core`
+- `@angular/forms`
+- `rxjs`
+- `moment`
+
+## Exports (what you can import from `'@brickclay/calendar'`)
+
+### Components
+
+- **Wrapper**: `CalendarComponent` (selector: `<lib-calendar>`)
+  - Drop-in wrapper around `<app-custom-calendar>`
+  - Mirrors the same inputs/outputs, so you can use `<lib-calendar>` everywhere
+
+- **Standalone components**
+  - `CustomCalendarComponent` (selector: `<app-custom-calendar>`) — the main calendar UI
+  - `ScheduledDatePickerComponent` (selector: `<app-scheduled-date-picker>`) — “single / multiple / range” scheduling UI
+  - `TimePickerComponent` (selector: `<app-time-picker>`) — standalone time picker
+
+### Module (optional)
+
+- `CalendarModule` — exports the 3 standalone components above (for module-based apps)
+
+### Types & services
+
+- Types: `CalendarSelection`, `CalendarRange`, etc.
+- Service: `CalendarManagerService` (coordinates multiple open calendars)
+
+Example import:
+
+```ts
+import { CalendarComponent, CalendarSelection } from '@brickclay/calendar';
+```
+
+## Usage options
+
+### Option A (recommended): use `<lib-calendar>`
+
+`<lib-calendar>` is a thin wrapper around the main calendar and is the easiest way to use the package.
+
+#### Single date picker
+
+```html
+<lib-calendar
+  [singleDatePicker]="true"
+  [autoApply]="true"
+  (selected)="onSelected($event)"
+></lib-calendar>
+```
+
+#### Date range picker (default mode)
+
+```html
+<lib-calendar
+  [singleDatePicker]="false"
+  [dualCalendar]="true"
+  (selected)="onSelected($event)"
+></lib-calendar>
+```
+
+#### Multi-date selection
+
+```html
+<lib-calendar
+  [multiDateSelection]="true"
+  [autoApply]="true"
+  (selected)="onSelected($event)"
+></lib-calendar>
+```
+
+#### Inline mode (always visible, not a dropdown)
+
+```html
+<lib-calendar
+  [inline]="true"
+  [dualCalendar]="true"
+  (selected)="onSelected($event)"
+></lib-calendar>
+```
+
+#### With min/max date
+
+```html
+<lib-calendar
+  [minDate]="minDate"
+  [maxDate]="maxDate"
+  (selected)="onSelected($event)"
+></lib-calendar>
+```
+
+```ts
+minDate = new Date(2025, 0, 1);
+maxDate = new Date(2025, 11, 31);
+```
+
+#### Controlled value (set selection from parent)
+
+Use `selectedValue` when you want to **drive the calendar from your own state**.
+
+```ts
+import { CalendarSelection } from '@brickclay/calendar';
+
+selectedValue: CalendarSelection = {
+  startDate: new Date(),
+  endDate: null
+};
+```
+
+```html
+<lib-calendar
+  [singleDatePicker]="true"
+  [selectedValue]="selectedValue"
+  (selected)="selectedValue = $event"
+></lib-calendar>
+```
+
+### Option B: use `<app-custom-calendar>` directly
+
+If you don’t want the wrapper, you can import and use the standalone component directly:
+
+```ts
+import { Component } from '@angular/core';
+import { CustomCalendarComponent, CalendarSelection } from '@brickclay/calendar';
+
+@Component({
+  standalone: true,
+  selector: 'app-demo',
+  imports: [CustomCalendarComponent],
+  template: `
+    <app-custom-calendar
+      [dualCalendar]="false"
+      [singleDatePicker]="true"
+      (selected)="onSelected($event)"
+    />
+  `
+})
+export class DemoComponent {
+  onSelected(selection: CalendarSelection) {
+    console.log(selection);
+  }
+}
+```
+
+### Option C: module-based usage (`CalendarModule`)
+
+```ts
+import { NgModule } from '@angular/core';
+import { BrowserModule } from '@angular/platform-browser';
+import { CalendarModule } from '@brickclay/calendar';
+import { AppComponent } from './app.component';
+
+@NgModule({
+  declarations: [AppComponent],
+  imports: [BrowserModule, CalendarModule]
+})
+export class AppModule {}
+```
+
+Then use:
+
+```html
+<app-custom-calendar></app-custom-calendar>
+<app-scheduled-date-picker></app-scheduled-date-picker>
+<app-time-picker></app-time-picker>
+```
+
+## Component guides
+
+### `CalendarComponent` (wrapper) — `<lib-calendar>`
+
+This is a wrapper around `CustomCalendarComponent` that forwards all inputs/outputs.
+
+- **Selector**: `<lib-calendar>`
+- **When to use**: almost always (best default)
+
+### `CustomCalendarComponent` — `<app-custom-calendar>`
+
+The main calendar UI. Supports range, single date, multi-date, optional time picker, inline mode, min/max, custom ranges.
+
+- **Selector**: `<app-custom-calendar>`
+- **Outputs**: `(selected)`, `(opened)`, `(closed)`
+
+### `ScheduledDatePickerComponent` — `<app-scheduled-date-picker>`
+
+Higher-level scheduling UI with 3 tabs:
+- single date + time
+- multiple dates + time per date
+- date range + time
+
+Example:
+
+```ts
+import { Component } from '@angular/core';
+import { ScheduledDatePickerComponent, ScheduledDateSelection } from '@brickclay/calendar';
+
+@Component({
+  standalone: true,
+  selector: 'app-demo-scheduled',
+  imports: [ScheduledDatePickerComponent],
+  template: `
+    <app-scheduled-date-picker
+      [timeFormat]="12"
+      [enableSeconds]="false"
+      (scheduled)="onScheduled($event)"
+      (cleared)="onCleared()"
+    />
+  `
+})
+export class DemoScheduledComponent {
+  onScheduled(value: ScheduledDateSelection) {
+    console.log(value);
+  }
+  onCleared() {}
+}
+```
+
+### `TimePickerComponent` — `<app-time-picker>`
+
+Standalone time picker used internally by the calendar/scheduler, but you can use it directly.
+
+Example:
+
+```html
+<app-time-picker
+  [value]="'1:00 AM'"
+  [timeFormat]="12"
+  [showSeconds]="false"
+  [pickerId]="'start-time'"
+  (timeChange)="startTime = $event"
+></app-time-picker>
+```
+
+## API reference
+
+### Types
+
+#### `CalendarSelection`
+
+```ts
+export interface CalendarSelection {
+  startDate: Date | null;
+  endDate: Date | null;
+  selectedDates?: Date[];
+}
+```
+
+#### `CalendarRange`
+
+```ts
+export interface CalendarRange {
+  start: Date;
+  end: Date;
+}
+```
+
+### Inputs/Outputs for `<lib-calendar>` and `<app-custom-calendar>`
+
+They share the same API (the wrapper forwards everything).
+
+#### Outputs
+
+| Output | Type | When it fires |
+| --- | --- | --- |
+| `selected` | `EventEmitter<CalendarSelection>` | When selection changes (and on apply/autoApply depending on config) |
+| `opened` | `EventEmitter<void>` | When the dropdown opens (not used in inline mode) |
+| `closed` | `EventEmitter<void>` | When the dropdown closes (not used in inline mode) |
+
+#### Inputs (with defaults)
+
+| Input | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `enableTimepicker` | `boolean` | `false` | Enables time selection UI |
+| `autoApply` | `boolean` | `false` | Automatically applies after selecting end date (or date) |
+| `closeOnAutoApply` | `boolean` | `false` | Closes dropdown after auto-apply (no-op in inline) |
+| `showCancel` | `boolean` | `true` | Show Cancel button |
+| `linkedCalendars` | `boolean` | `false` | Keeps calendars linked (if enabled by UI logic) |
+| `singleDatePicker` | `boolean` | `false` | Single date mode |
+| `showWeekNumbers` | `boolean` | `false` | Display week numbers |
+| `showISOWeekNumbers` | `boolean` | `false` | Display ISO week numbers |
+| `customRangeDirection` | `boolean` | `false` | Alters selection direction behavior |
+| `lockStartDate` | `boolean` | `false` | Locks start date when selecting end date |
+| `position` | `'center' \| 'left' \| 'right'` | `'left'` | Dropdown alignment |
+| `drop` | `'up' \| 'down'` | `'down'` | Dropdown direction |
+| `dualCalendar` | `boolean` | `false` | Show two calendars (left/right) |
+| `showRanges` | `boolean` | `true` | Show ranges list (Today/Yesterday/...) |
+| `timeFormat` | `12 \| 24` | `24` | Time display mode |
+| `enableSeconds` | `boolean` | `false` | Show seconds in time selection |
+| `customRanges` | `Record<string, CalendarRange>` | `undefined` | Provide your own ranges |
+| `multiDateSelection` | `boolean` | `false` | Multi-date selection mode |
+| `maxDate` | `Date` | `undefined` | Maximum selectable date |
+| `minDate` | `Date` | `undefined` | Minimum selectable date |
+| `placeholder` | `string` | `'Select date range'` | Input placeholder |
+| `opens` | `'left' \| 'right' \| 'center'` | `'left'` | Popup position |
+| `inline` | `boolean` | `false` | Always visible calendar (no dropdown) |
+| `isDisplayCrossIcon` | `boolean` | `true` | Show/hide clear (X) icon |
+| `selectedValue` | `CalendarSelection \| null` | `null` | Controlled value input |
+| `displayFormat` | `string` | `'MM/DD/YYYY'` | Uses Moment formatting tokens |
+
+### Custom ranges example
+
+```ts
+import { CalendarRange } from '@brickclay/calendar';
+
+customRanges: Record<string, CalendarRange> = {
+  'Last 7 Days': { start: new Date(Date.now() - 6 * 86400000), end: new Date() },
+  'This Month': { start: new Date(new Date().getFullYear(), new Date().getMonth(), 1), end: new Date() }
+};
+```
+
+```html
+<lib-calendar [customRanges]="customRanges"></lib-calendar>
+```
+
+## Styling / theming
+
+- The components ship with their own component styles.
+- If your app uses view encapsulation/global resets, you may want to adjust spacing/colors by overriding styles in your app.
+
+## Troubleshooting
+
+### The package installs but Angular can’t resolve imports
+
+- Ensure you import from `'@brickclay/calendar'` (the package entrypoint), not from deep paths.
+- Ensure your app has the **peer dependencies** installed.
+
+### I don’t see the dropdown open/close events
+
+- `opened` / `closed` are meaningful only when `inline` is `false`. In inline mode the calendar is always visible.
+
+### SSR (Angular Universal)
+
+Some UI helpers use browser globals (e.g., DOM querying). If you render on the server, prefer rendering these components only in the browser.
+
+## Build & publish
+
+Build:
+
+```bash
+ng build calendar
+```
+
+Publish:
+
+```bash
+cd dist/calendar
+npm publish
+```
+
+Publishing checklist (recommended):
+- update `projects/calendar/package.json` version
+- ensure `dist/calendar/package.json` has the final `name`, `version`, `description`, `keywords`, etc.

package/assets/calender/calender.svg

@@ -0,0 +1,19 @@
+<svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
+<g clip-path="url(#clip0_3797_46309)">
+<path d="M14.545 5.45448V11.6363C14.545 13.8181 13.4541 15.2727 10.9086 15.2727H5.09047C2.54501 15.2727 1.4541 13.8181 1.4541 11.6363V5.45448C1.4541 3.27266 2.54501 1.81812 5.09047 1.81812H10.9086C13.4541 1.81812 14.545 3.27266 14.545 5.45448Z" stroke="#141414" stroke-width="1.2" stroke-miterlimit="10" stroke-linecap="round" stroke-linejoin="round"/>
+<path d="M5.09082 0.727295V2.90911" stroke="#141414" stroke-width="1.2" stroke-miterlimit="10" stroke-linecap="round" stroke-linejoin="round"/>
+<path d="M10.9092 0.727295V2.90911" stroke="#141414" stroke-width="1.2" stroke-miterlimit="10" stroke-linecap="round" stroke-linejoin="round"/>
+<path d="M1.81836 5.88354H14.182" stroke="#141414" stroke-width="1.2" stroke-miterlimit="10" stroke-linecap="round" stroke-linejoin="round"/>
+<path d="M10.6868 9.23619H10.6933" stroke="#141414" stroke-width="1.4" stroke-linecap="round" stroke-linejoin="round"/>
+<path d="M10.6868 11.4181H10.6933" stroke="#141414" stroke-width="1.4" stroke-linecap="round" stroke-linejoin="round"/>
+<path d="M7.99636 9.23619H8.00289" stroke="#141414" stroke-width="1.4" stroke-linecap="round" stroke-linejoin="round"/>
+<path d="M7.99636 11.4181H8.00289" stroke="#141414" stroke-width="1.4" stroke-linecap="round" stroke-linejoin="round"/>
+<path d="M5.30495 9.23644H5.31149" stroke="#141414" stroke-width="1.4" stroke-linecap="round" stroke-linejoin="round"/>
+<path d="M5.30495 11.4181H5.31149" stroke="#141414" stroke-width="1.4" stroke-linecap="round" stroke-linejoin="round"/>
+</g>
+<defs>
+<clipPath id="clip0_3797_46309">
+<rect width="16" height="16" fill="white"/>
+</clipPath>
+</defs>
+</svg>

package/assets/calender/chevron-down.svg

@@ -0,0 +1,10 @@
+<svg width="12" height="7" viewBox="0 0 12 7" fill="none" xmlns="http://www.w3.org/2000/svg">
+<g clip-path="url(#clip0_535_3111)">
+<path d="M0.835938 1.16797L5.83593 6.16797L10.8359 1.16797" stroke="#6B7080" stroke-width="1.66667" stroke-linecap="round" stroke-linejoin="round"/>
+</g>
+<defs>
+<clipPath id="clip0_535_3111">
+<rect width="7" height="12" fill="white" transform="matrix(0 -1 1 0 0 7)"/>
+</clipPath>
+</defs>
+</svg>

package/assets/calender/chevron-left.svg

@@ -0,0 +1,3 @@
+<svg width="7" height="12" viewBox="0 0 7 12" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M5.83398 0.833313L0.833984 5.83331L5.83398 10.8333" stroke="#6B7080" stroke-width="1.66667" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>

package/assets/calender/chevron-right.svg

@@ -0,0 +1,3 @@
+<svg width="7" height="12" viewBox="0 0 7 12" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M0.833984 10.8333L5.83398 5.83331L0.833984 0.833313" stroke="#6B7080" stroke-width="1.66667" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>

package/assets/calender/chevron-up.svg

@@ -0,0 +1,10 @@
+<svg width="12" height="7" viewBox="0 0 12 7" fill="none" xmlns="http://www.w3.org/2000/svg">
+<g clip-path="url(#clip0_535_3113)">
+<path d="M10.8359 6.16797L5.83593 1.16797L0.835938 6.16797" stroke="#6B7080" stroke-width="1.66667" stroke-linecap="round" stroke-linejoin="round"/>
+</g>
+<defs>
+<clipPath id="clip0_535_3113">
+<rect width="7" height="12" fill="white" transform="matrix(0 -1 1 0 0 7)"/>
+</clipPath>
+</defs>
+</svg>

package/assets/calender/pagination-left-gray.svg

@@ -0,0 +1,3 @@
+<svg width="6" height="10" viewBox="0 0 6 10" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M5 9L1 5L5 1" stroke="#B9BBC6" stroke-width="1.33333" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>

package/assets/calender/pagination-right-gray.svg

@@ -0,0 +1,10 @@
+<svg width="6" height="10" viewBox="0 0 6 10" fill="none" xmlns="http://www.w3.org/2000/svg">
+<g clip-path="url(#clip0_268_9)">
+<path d="M1 9L5 5L1 1" stroke="#B9BBC6" stroke-width="1.33333" stroke-linecap="round" stroke-linejoin="round"/>
+</g>
+<defs>
+<clipPath id="clip0_268_9">
+<rect width="6" height="10" fill="white"/>
+</clipPath>
+</defs>
+</svg>

package/assets/calender/timer.svg

@@ -0,0 +1,4 @@
+<svg width="14" height="14" viewBox="0 0 14 14" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M7 14C10.8593 14 14 10.8593 14 7C14 3.14067 10.8594 0 7 0C3.14063 0 0 3.14067 0 7C0 10.8593 3.14067 14 7 14ZM7 0.933318C10.346 0.933318 13.0667 3.65398 13.0667 7C13.0667 10.346 10.346 13.0667 7 13.0667C3.65398 13.0667 0.933318 10.346 0.933318 7C0.933318 3.65398 3.65401 0.933318 7 0.933318Z" fill="#BBBDC5"/>
+<path d="M9.04153 9.23071C9.12788 9.3007 9.23052 9.33339 9.3332 9.33339C9.47086 9.33339 9.60619 9.27272 9.69718 9.15839C9.85819 8.95772 9.82549 8.66372 9.62486 8.50271L7.46652 6.77604V3.26671C7.46652 3.01004 7.25653 2.80005 6.99986 2.80005C6.74319 2.80005 6.5332 3.01004 6.5332 3.26671V7.00006C6.5332 7.1424 6.59855 7.27539 6.7082 7.36404L9.04153 9.23071Z" fill="#BBBDC5"/>
+</svg>

package/calendar/calendar.module.d.ts

@@ -0,0 +1,21 @@
+import * as i0 from "@angular/core";
+import * as i1 from "@angular/common";
+import * as i2 from "./components/custom-calendar/custom-calendar.component";
+import * as i3 from "./components/scheduled-date-picker/scheduled-date-picker.component";
+import * as i4 from "./components/time-picker/time-picker.component";
+/**
+ * Optional NgModule wrapper for projects that prefer module-based usage.
+ *
+ * Note:
+ * - The components themselves are standalone, so you can also import them
+ *   directly into any standalone component without using this module.
+ * - This module is mainly for:
+ *   - Existing apps that still use feature modules
+ *   - Easier "plug-and-play" integration: import CalendarModule once and use
+ *     the three exported components anywhere in your templates.
+ */
+export declare class CalendarModule {
+    static ɵfac: i0.ɵɵFactoryDeclaration<CalendarModule, never>;
+    static ɵmod: i0.ɵɵNgModuleDeclaration<CalendarModule, never, [typeof i1.CommonModule, typeof i2.CustomCalendarComponent, typeof i3.ScheduledDatePickerComponent, typeof i4.TimePickerComponent], [typeof i2.CustomCalendarComponent, typeof i3.ScheduledDatePickerComponent, typeof i4.TimePickerComponent]>;
+    static ɵinj: i0.ɵɵInjectorDeclaration<CalendarModule>;
+}