@ninthforge/timeline 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,81 @@
-# 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/timeline
+
+An executive roadmap for Microsoft Power Apps code apps and any React app: themes or teams as swimlanes, initiatives as bars packed into rows, milestones as diamonds, and fiscal quarters across the top. It's part of **[Ninth Forge Plan](https://ninthforge.com)**, the same component as the Ninth Forge Timeline control for model-driven and canvas apps.
+
+- **Two modes:** Dates (Month, Quarter or Half-year zoom, labelled by your fiscal year, e.g. "Q1 FY27") and Now · Next · Later.
+- **Lanes:** packed into as few rows as possible, collapsible, in your order; items without dates wait in a "Not scheduled" tray.
+- **Editing:**
+  - drag to move, drag an edge to resize
+  - Alt+arrows from the keyboard
+  - undo and redo
+- **Colour** by status or lane, with your own colours per value, and text that always stays readable.
+- **Output and access:**
+  - print (board-pack ready) and PNG export
+  - light and dark themes with your accent
+  - right-to-left layouts and high-contrast mode
+  - full keyboard and screen-reader support
+- **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/timeline@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/timeline
+```
+
+## Use
+
+You hold the data. The timeline shows it and tells you what the user changed.
+
+```tsx
+import { useState } from 'react';
+import { Timeline, type TimelineChange, type TimelineItem } from '@ninthforge/timeline';
+
+const initial: TimelineItem[] = [
+  { id: 'i1', name: 'Customer portal v2', lane: 'Customer', status: 'At risk', start: '2026-10-05', end: '2027-03-26', horizon: 'Now' },
+  { id: 'i2', name: 'Portal launch', lane: 'Customer', start: '2027-03-29', dependsOn: ['i1'] }, // no end: a milestone
+  { id: 'i3', name: 'Cloud migration', lane: 'Platform', status: 'On track', start: '2026-07-06', end: '2026-12-18', horizon: 'Now' },
+  { id: 'i4', name: 'Board strategy day', lane: 'Growth', status: 'On track', start: '2026-11-20', end: '2026-11-20', milestone: false },
+  { id: 'i5', name: 'Voice assistant', lane: 'Customer', status: 'Not started', horizon: 'Later' } // no dates: "Not scheduled"
+];
+
+export function Roadmap({ licenseKey, tenantId }: { licenseKey?: string; tenantId?: string }) {
+  const [items, setItems] = useState(initial);
+
+  // Save to your backend; throw (or reject) to put the item back with a message.
+  const onItemChange = async (c: TimelineChange) => {
+    setItems((list) => list.map((i) => (i.id !== c.id ? i : { ...i, ...(c.start ? { start: c.start } : {}), ...(c.end ? { end: c.end } : {}) })));
+  };
+
+  return (
+    <div style={{ height: 560 }}>
+      <Timeline
+        title="Group roadmap"
+        items={items}
+        laneOrder={['Customer', 'Growth', 'Platform']}
+        fiscalYearStart={7}
+        onItemChange={onItemChange}
+        licenseKey={licenseKey}
+        tenantId={tenantId}
+      />
+    </div>
+  );
+}
+```
+
+- **Dates** are ISO `YYYY-MM-DD` strings, end inclusive, handled in UTC. Changes come back the same way.
+- **Milestones:** an item with no end, or an end equal to its start, is a milestone. Set `milestone: false` to keep a one-day item as a bar, or `true` to force a milestone.
+- **Colours:** by `status` (On track, At risk, Off track, Done and Not started have built-in meanings) or by lane (`colorBy="lane"`). `statusColors` and `laneColors` map values to your own hex colours.
+- **`fiscalYearStart`** (1–12) is the first month of your fiscal year. The year is named by the year it ends in, so July 2026 starts FY27.
+
+## 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).