@ninthforge/scheduler 0.0.0-stage → 1.0.0-rc.1

package/LICENSE.md

@@ -0,0 +1,9 @@
+Copyright (c) 2026 Inspire Labs Pty Ltd, trading as Ninth Forge. All rights reserved.
+
+This repository and its contents are proprietary and confidential. No licence is
+granted to use, copy, modify or distribute any part of it except under a written
+agreement with Inspire Labs Pty Ltd. Packages published from this repository are
+licensed under the Ninth Forge End User Licence Agreement at https://ninthforge.com/legal/eula.
+
+Free-pack packages and `@ninthforge/tokens` are released under the MIT licence; for
+those packages, the licence file inside the package applies to that package only.

package/README.md

@@ -1,3 +1,94 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @ninthforge/scheduler
+
+A resource scheduler for Microsoft Power Apps code apps and any React app: people, rooms, vehicles, equipment or field jobs on one board. It's part of **[Ninth Forge Plan](https://ninthforge.com)**, the same component as the Ninth Forge Scheduler control for model-driven and canvas apps.
+
+- **Views:** Day, Week, Two weeks, Month and Agenda. Agenda is the default below 600 px.
+- **Editing:**
+  - drag to move or reassign, drag an edge to resize, drag across empty time to create
+  - assign work from the Unassigned panel
+  - every edit works from the keyboard too
+  - 20-step undo
+- **Rules and capacity:**
+  - overlapping bookings allowed, warned or blocked
+  - unavailable time (leave, maintenance)
+  - capacity per day with a utilisation strip
+- **Output and access:**
+  - print and PNG export
+  - light and dark themes with your accent
+  - right-to-left layouts and high-contrast mode
+- **Lean and private:**
+  - no runtime dependencies beyond React (16.14 or later)
+  - no network calls, and the licence check is offline
+
+## Install
+
+```
+npm install @ninthforge/scheduler@next
+```
+
+Release candidates (1.0.0-rc.N) are under npm's `next` tag until 1.0.0 on 27 January 2027.
+
+```
+# from 1.0.0
+npm install @ninthforge/scheduler
+```
+
+## Use
+
+You hold the data. The scheduler shows it and tells you what the user changed.
+
+```tsx
+import { useState } from 'react';
+import { Scheduler, type CreateRequest, type SchedBooking, type SchedChange, type SchedResource } from '@ninthforge/scheduler';
+
+const resources: SchedResource[] = [
+  { id: 'r1', name: 'Aisha Khan', group: 'Customer Care', subtitle: 'Agent', capacityHours: 8 },
+  { id: 'r2', name: 'Ben Walker', group: 'Customer Care', subtitle: 'Agent', capacityHours: 8 }
+];
+
+export function Roster({ licenseKey, tenantId }: { licenseKey?: string; tenantId?: string }) {
+  const [bookings, setBookings] = useState<SchedBooking[]>([
+    { id: 'b1', name: 'Morning shift', start: '2027-02-01T01:00:00Z', end: '2027-02-01T05:00:00Z', resourceId: 'r1', status: 'Confirmed' },
+    { id: 'b2', name: 'Callback queue', start: '2027-02-01T02:00:00Z', end: '2027-02-01T03:00:00Z', resourceId: null, status: 'Tentative' }
+  ]);
+
+  // Save to your backend; throw (or reject) to put the booking back with a message.
+  const onBookingChange = async (c: SchedChange) => {
+    setBookings((list) =>
+      list.map((b) =>
+        b.id !== c.id
+          ? b
+          : { ...b, ...(c.start ? { start: c.start } : {}), ...(c.end ? { end: c.end } : {}), ...('resourceId' in c ? { resourceId: c.resourceId ?? null } : {}) }
+      )
+    );
+  };
+  const onCreate = (r: CreateRequest) =>
+    setBookings((list) => [...list, { id: `new-${list.length + 1}`, name: 'New shift', start: r.start, end: r.end, resourceId: r.resourceId }]);
+
+  return (
+    <div style={{ height: 600 }}>
+      <Scheduler
+        preset="people"
+        title="Team rosters"
+        resources={resources}
+        bookings={bookings}
+        onBookingChange={onBookingChange}
+        onCreate={onCreate}
+        licenseKey={licenseKey}
+        tenantId={tenantId}
+      />
+    </div>
+  );
+}
+```
+
+- **Times** are instants: UTC milliseconds or ISO date-times with `Z` or an offset. Changes come back as ISO UTC strings. They're shown in `timeZone`, which defaults to the browser's. Pass `ianaZone('Europe/London')` or `fixedZone(minutes)` to pin one.
+- **Unassigned work** is any booking with `resourceId: null`. It's listed in the Unassigned panel and can be dragged onto a row.
+- **`preset`** (`people`, `rooms`, `vehicles`, `equipment`, `jobs`) sets the labels, default view, snapping, overlap rule and working hours. Every one can be overridden with its own prop.
+- **`onRangeChange`** reports the dates on screen, so you can load just that window.
+
+## Licence
+
+Ninth Forge Plan is a paid product. Without a key, everything works, with a small "Unlicensed" badge in the corner. Pass your Plan key as `licenseKey` and your Microsoft Entra tenant ID as `tenantId`. The check is offline. Trials and keys: [ninthforge.com](https://ninthforge.com).
+
+See `LICENSE.md` for the terms.