ngx-resource-scheduler 0.1.1 → 0.1.4

package/README.md

@@ -1,24 +1,180 @@
-# NgxResourceScheduler
+# ngx-resource-scheduler
 
-This library was generated with [Angular CLI](https://github.com/angular/angular-cli) version 18.2.0.
+A lightweight, flexible **resource scheduler** for Angular.
 
-## Code scaffolding
+## ✨ Features
 
-Run `ng generate component component-name --project ngx-resource-scheduler` to generate a new component. You can also use `ng generate directive|pipe|service|class|guard|interface|enum|module --project ngx-resource-scheduler`.
-> Note: Don't forget to add `--project ngx-resource-scheduler` or else it will be added to the default project in your `angular.json` file. 
+- Days ↔ Resources as primary axis
+- Configurable visible range (1–7 days)
+- Configurable working hours (e.g. `08:00–20:00`)
+- Timezone-aware (UTC, local, or IANA zones)
+- Overlapping event layout
+- Slot & event click callbacks
+- Custom event rendering via `ng-template`
+- Built-in toolbar **or** external navigation
+- Clean, modern styling (system fonts)
 
-## Build
+## 📦 Installation
 
-Run `ng build ngx-resource-scheduler` to build the project. The build artifacts will be stored in the `dist/` directory.
+```bash
+npm install ngx-resource-scheduler
+````
 
-## Publishing
+## 🚀 Basic Usage
 
-After building your library with `ng build ngx-resource-scheduler`, go to the dist folder `cd dist/ngx-resource-scheduler` and run `npm publish`.
+### html
+```html
+<ngx-resource-scheduler
+  [startDate]="startDate"
+  [resources]="resources"
+  [events]="events">
+</ngx-resource-scheduler>
+```
 
-## Running unit tests
+### TS
 
-Run `ng test ngx-resource-scheduler` to execute the unit tests via [Karma](https://karma-runner.github.io).
+```ts
+startDate = new Date();
 
-## Further help
+resources = [
+  { id: 'r1', title: 'Room A' },
+  { id: 'r2', title: 'Room B' },
+];
 
-To get more help on the Angular CLI use `ng help` or go check out the [Angular CLI Overview and Command Reference](https://angular.dev/tools/cli) page.
+events = [
+  {
+    id: 'e1',
+    title: 'Meeting',
+    resourceId: 'r1',
+    start: new Date('2025-01-10T10:00:00Z'),
+    end: new Date('2025-01-10T11:00:00Z'),
+  },
+];
+```
+
+## 🔧 Inputs
+
+### Required
+| Input  | Type | Type |
+| ------------- | ------------- | ------------- |
+| startDate  | Date | First visible day (recommended at 00:00) |
+| resources  | SchedulerResource[] | List of schedulable resources
+| events  | SchedulerEvent[] | Events (UTC instants recommended)
+
+### Layout & Range
+
+| Input  | Default | Description |
+| ------------- | ------------- | ------------- |
+| `nDays` |  `7` | Number of visible days (1–7)  |
+| `primaryAxis` | `days` | `days` or `resources` |
+| `dayStart` | `08:00` | Start of visible hours |
+| `dayEnd` | `20:00` | End of visible hours |
+| `slotDuration` | `00:30` | Slot resolution |
+| `snapToSlot` | `true` | Snap clicks to slots |
+
+### Appearance
+
+| Input  | Default | Description |
+| ------------- | ------------- | ------------- |
+| `showToolbar` | `true` | Show built-in navigation toolbar |
+| `showSlotLines` | `true` | Show slot grid lines |
+| `slotLineStyle` | `slot` | `slot`, `hour`, or `both` |
+| `readonly` | `false` | Disable interactions |
+| `timezone` | `local` | `local`, `UTC`, or IANA zone (e.g. `Europe/Kiev`) |
+
+> **Important**
+>
+> Events should be provided as UTC instants. The scheduler converts them for display using timezone.
+
+## 🎯 Outputs
+
+| Output  | Payload | Description |
+| ------------- | ------------- | ------------- |
+| `slotClick` | `SchedulerSlotClick` | User clicked an empty slot |
+| `eventClick` | `SchedulerEventClick` | User clicked an event |
+| `rangeChange` | `SchedulerRangeChange` | Visible date range changed |
+| `startDateChange` | `Date` | Navigation occurred |
+| `eventChange` | - | Under development |
+
+## 🧭 Navigation example (External Controls)
+
+You can hide the toolbar and control navigation from outside the scheduler.
+
+```html
+<button (click)="scheduler.prev()">Prev</button>
+<button (click)="scheduler.today()">Today</button>
+<button (click)="scheduler.next()">Next</button>
+
+<ngx-resource-scheduler
+  #scheduler
+  [showToolbar]="false"
+  [nDays]="7"
+  [resources]="resources"
+  [events]="events">
+</ngx-resource-scheduler>
+```
+
+No date math required.
+
+## 🎨 Custom Event Template
+
+You can fully customize how events are rendered.
+
+```html
+<ngx-resource-scheduler
+  [events]="events"
+  [eventTemplate]="eventTpl">
+</ngx-resource-scheduler>
+
+<ng-template
+  #eventTpl
+  let-event
+  let-startZoned="startZoned"
+  let-endZoned="endZoned">
+  <div>
+    <strong>{{ event.title }}</strong>
+    <div>
+      {{ startZoned | date:'HH:mm' }}–{{ endZoned | date:'HH:mm' }}
+    </div>
+  </div>
+</ng-template>
+```
+
+### Template Context
+
+| Variable | Description |
+| ------------- | ------------- |
+| `event` / `$implicit` | The event |
+| `startZoned` | Start date in scheduler timezone |
+| `endZoned` | End date in scheduler timezone |
+| `resourceId` | Resource id |
+| `day` | Day of the cell |
+
+## 🧩 Styling Events
+
+### HTML
+```html
+<ngx-resource-scheduler
+  [eventClass]="eventClass"
+  [eventStyle]="eventStyle">
+</ngx-resource-scheduler>
+```
+
+### TS
+```ts
+eventClass = (e) => ({
+  'is-important': e.title.includes('Important'),
+});
+
+eventStyle = (e) => ({
+  backgroundColor: '#ffe4e6',
+});
+```
+
+> Layout styles (top, left, height, width) are managed internally and cannot be overridden.
+
+## 📌 Notes
+
+* Drag & resize are not included in v1 (comming to v2)
+* Designed for clarity and extensibility
+* No external calendar dependencies