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

package/dist/index.d.cts

@@ -0,0 +1,416 @@
+import * as React from 'react';
+
+/**
+ * Optimistic editing for Ninth Forge components — pure functions, no React.
+ *
+ * A change is `{ id, …fields, previous, source }`: the new values of some fields of one item,
+ * the old values of the same fields, and what caused it. Components define which fields are
+ * editable (`keys`), when two values count as the same (`equal`), and what "no value" is for
+ * a field when undoing (`blank`). Shared by the Gantt and the Scheduler.
+ */
+/** One edit to one item. `F` is the editable field set; `S` the sources a component uses. */
+type Change<F extends object, S extends string = string> = Partial<F> & {
+    id: string;
+    /** The same fields before the edit — for undo, and for hosts that diff. */
+    previous: Partial<F>;
+    source: S;
+};
+
+/**
+ * One action offered in a component's empty state, e.g. "Load sample data" on a Ninth Forge
+ * sample table. The host decides when to offer it and runs it; the component only shows it.
+ */
+interface EmptyAction {
+    label: string;
+    onClick: () => void;
+    /** Running: the button gives way to `status` ("Loading sample data… 120 of 380"). */
+    busy?: boolean;
+    status?: string;
+    /** Shown under the button, e.g. what the action does. */
+    hint?: string;
+    /** The last attempt failed (the button stays, so the user can retry). */
+    error?: string;
+}
+
+/** The host props every Plan component takes for its watermark. */
+interface WatermarkHostProps {
+    /**
+     * `false` draws no watermark at all (no link, no space). The licence is still checked; the
+     * host decides when, e.g. Power BI Desktop for authoring (DECISIONS 2026-10-31). Default true.
+     */
+    watermark?: boolean;
+    /** `text`: words only, no coloured mark (Power BI certification). Default `mark`. */
+    watermarkStyle?: 'mark' | 'text';
+    /** The host opens the link itself (Power BI's `launchUrl`): the watermark becomes a button. */
+    onWatermarkClick?: () => void;
+}
+
+interface Tick {
+    day: number;
+    x: number;
+    width: number;
+    label: string;
+}
+
+type RoadmapZoom = 'month' | 'quarter' | 'half';
+interface RoadmapScale {
+    zoom: RoadmapZoom;
+    fiscalYearStart: number;
+    startDay: number;
+    /** Exclusive. */
+    endDay: number;
+    dayWidth: number;
+    width: number;
+    x(day: number): number;
+    dayAt(px: number): number;
+    /** Years (or fiscal years) on top. */
+    major: Tick[];
+    /** Months, quarters or halves below. */
+    minor: Tick[];
+    /** Quarter zoom only: the months under each quarter (empty at other zooms). */
+    months: Tick[];
+}
+
+/**
+ * Host hooks shared by the Plan components (Gantt, Timeline, capacity heatmap) when a host such
+ * as a Power BI visual wraps them. Same shapes as `@ninthforge/charts`' hooks. All optional:
+ * Power Apps passes none of them.
+ */
+/** Passed with a selection: `multi` is true when Ctrl or Cmd was held (add to the selection). */
+interface SelectInfo {
+    multi: boolean;
+}
+/** Where the pointer (or, from the keyboard, the item's anchor) is, in client coordinates. */
+interface PointerInfo extends SelectInfo {
+    clientX: number;
+    clientY: number;
+}
+
+/**
+ * "Copy diagnostics": one click copies what support needs to reproduce a problem, and nothing
+ * else. Product and control version, licence state (never the key), host, browser, locale, time
+ * zone, the mapped property names and the row count. No data values and no personal data: the
+ * input types only take names and counts, and every string is trimmed to one short line.
+ *
+ * Framework-free. The drop-in menu item is `CopyDiagnosticsItem` in `@ninthforge/core/react`.
+ */
+/** Where the control runs. PCF wrappers and Power BI visuals pass it when they know. */
+type DiagnosticsHost = 'model-driven' | 'canvas' | 'canvas (Studio)' | 'custom page' | 'Power BI' | 'code app' | 'web page';
+/**
+ * The licence as diagnostics reads it: a `LicenseResult` from `@ninthforge/license` fits. Only
+ * `status`, `payload.tier`, `payload.org` and `payload.exp` are read; the key itself never
+ * reaches this function, and the tenant ID and key id are left out.
+ */
+interface DiagnosticsLicence {
+    status: string;
+    payload?: {
+        tier?: string;
+        org?: string;
+        exp?: string;
+    } | null;
+}
+interface DiagnosticsInput {
+    /** The product, e.g. `Plan`, `Charts`. */
+    product: string;
+    /** The control, e.g. `Gantt` or `nf_NinthForge.PlanGantt`. */
+    control: string;
+    /** The control or package version, e.g. `0.4.4`. */
+    version: string;
+    licence?: DiagnosticsLicence | null;
+    /** Overrides detection (Power BI visuals, code apps, or a PCF that knows its host). */
+    host?: DiagnosticsHost;
+    /**
+     * Mapped properties: `{ taskStart: 'nf_start' }` gives `taskStart → nf_start`, and a list
+     * gives the names alone. Names only, never values.
+     */
+    properties?: Readonly<Record<string, string | null | undefined>> | readonly string[];
+    /** Rows the control received. */
+    rows?: number;
+    /**
+     * A few product-specific settings, e.g. `{ 'Save mode': 'direct' }`. Settings only: never
+     * record values, user names or e-mail addresses.
+     */
+    extra?: Readonly<Record<string, string | number | boolean | null | undefined>>;
+    now?: Date;
+}
+/**
+ * What a host adds to a component's own diagnostics (the component fills product, version,
+ * licence and its row count): a PCF passes its control name, mapped properties and settings.
+ */
+type DiagnosticsHostInfo = Partial<Pick<DiagnosticsInput, 'control' | 'version' | 'host' | 'properties' | 'rows' | 'extra'>>;
+
+/**
+ * Text size: type roles and one scale for every component (the same roles in Power Apps and Power BI).
+ *
+ * Components size text by role, never by a pixel number, so one setting ("Text size", 75–200 %)
+ * makes every label, value and title bigger or smaller together. The same numbers reach CSS
+ * (`--nf-text-<role>`) and layout maths (`textSize(role, scale)`), so label fitting and row
+ * heights match what the browser draws.
+ */
+/** What the text is for, not how big it is. */
+type TextRole = 'caption' | 'body' | 'label' | 'value' | 'callout' | 'header' | 'title' | 'hero';
+/** Per-role sizes at 100 %, in CSS pixels, that replace the defaults. The scale still applies. */
+type TextSizes = Partial<Record<TextRole, number>>;
+
+/** A component theme. Every key becomes a `--nf-<kebab-key>` CSS variable. */
+interface ComponentTheme {
+    accent: string;
+    accentTint: string;
+    accentText: string;
+    surface: string;
+    surfaceAlt: string;
+    ink: string;
+    muted: string;
+    line: string;
+    lineSoft: string;
+    phase: string;
+    milestone: string;
+    baseline: string;
+    selected: string;
+    focus: string;
+    positive: string;
+    negative: string;
+    tooltipBg: string;
+    tooltipInk: string;
+    font: string;
+    monoFont: string;
+}
+
+type TimelineZoom = RoadmapZoom;
+/** Dates on an axis, or Now / Next / Later columns. */
+type TimelineMode = 'dates' | 'horizon';
+interface TimelineItem {
+    id: string;
+    name: string;
+    /** ISO date (`YYYY-MM-DD`). No start and no end: shown in the "Not scheduled" tray. */
+    start?: string;
+    /** ISO date, inclusive. Empty, or the same as start: a milestone (unless `milestone` is false). */
+    end?: string;
+    /** Overrides the date rule: true = milestone on its start, false = a bar even if one day long. */
+    milestone?: boolean;
+    /** Swimlane (theme, team, product…). Empty: the "No lane" lane, last. */
+    lane?: string;
+    /** Drives colour: a semantic word (On track, At risk, Off track, Done, Not started) or any value. */
+    status?: string;
+    /** Now / Next / Later, for that mode. */
+    horizon?: string;
+    /** Hex colour override for this item. */
+    color?: string;
+    /** Ids of items this one depends on (read-only connectors). */
+    dependsOn?: string[];
+    /** Locks this item: no move or resize. */
+    readOnly?: boolean;
+}
+/** The editable fields: dates only in v1 (lanes and horizons are v1.x). */
+interface TimelineFields {
+    start: string;
+    end: string;
+}
+type TimelineChange = Change<TimelineFields, 'drag' | 'keyboard' | 'undo' | 'redo'>;
+type TimelineEditable = boolean | {
+    move?: boolean;
+    resize?: boolean;
+};
+interface TimelineProps extends WatermarkHostProps {
+    items: TimelineItem[];
+    title?: string;
+    zoom?: TimelineZoom;
+    defaultZoom?: TimelineZoom;
+    onZoomChange?: (zoom: TimelineZoom) => void;
+    mode?: TimelineMode;
+    defaultMode?: TimelineMode;
+    onModeChange?: (mode: TimelineMode) => void;
+    /** First month of the fiscal year (1–12, default 1): quarters and halves are labelled "Q1 FY27". */
+    fiscalYearStart?: number;
+    /** Colour items by status (default) or by lane. */
+    colorBy?: 'status' | 'lane';
+    /** Value → hex, checked before the built-in mapping (e.g. Dataverse choice colours). */
+    statusColors?: Record<string, string>;
+    laneColors?: Record<string, string>;
+    /** Lane order (by name); lanes not listed follow alphabetically, "No lane" last. */
+    laneOrder?: string[];
+    /** Read-only connectors from `dependsOn`. */
+    showDependencies?: boolean;
+    /** Override "today" (ISO date): demos and tests. */
+    today?: string;
+    theme?: 'light' | 'dark' | Partial<ComponentTheme>;
+    accent?: string;
+    /** Ninth Forge licence key (a Plan key). Missing keys show a small watermark; nothing breaks. */
+    /** An action offered when there's nothing to show, e.g. "Load sample data" (PCF on a Ninth Forge sample table). */
+    emptyAction?: EmptyAction;
+    /** One or more keys; or a promise of them (the PCF reading its licence-key environment variable). */
+    licenseKey?: string | PromiseLike<string | undefined>;
+    /** Host tenant (PCF: context.orgSettings.tenantId). */
+    tenantId?: string;
+    /**
+     * Show the small "renew within N days" notice while the licence is in its 14-day grace
+     * period. The licensing spec shows it to makers only: the PCF passes `true` only for makers
+     * (Studio in canvas, an admin or customiser in model-driven). Default `true`; turn it off in a
+     * code app your end users see.
+     */
+    renewalNotice?: boolean;
+    /**
+     * Text size, 1 = 100 % (0.75–2). Every label, value and title scales together; rows, lanes
+     * and the lane names column grow with it. The PCF's "Text size" input (percent) sets it.
+     */
+    textScale?: number;
+    /** Per-role sizes at 100 % in px, e.g. `{ body: 14 }`; the scale still applies. */
+    textSizes?: TextSizes;
+    /**
+     * `false` hides the Export menu (print, PNG and Copy diagnostics), e.g. in Power BI, whose
+     * sandbox blocks downloads, new windows and usually the clipboard. Default true.
+     */
+    exports?: boolean;
+    /**
+     * "Copy diagnostics" in the Export menu: copies what support needs (version, licence state,
+     * host, browser, locale, time zone, mapped property names, row count; never data values or
+     * the key). A function adds what the host knows, e.g. the PCF's control name and mapped
+     * properties. `false` hides the item. Default: shown.
+     */
+    diagnostics?: false | (() => DiagnosticsHostInfo);
+    height?: number | string;
+    className?: string;
+    /** Text direction (default: inherited). Lane names mirror; time runs left to right. */
+    dir?: 'ltr' | 'rtl';
+    showToolbar?: boolean;
+    /** The host is still loading: the empty state says so. */
+    loading?: boolean;
+    /** Every move, resize and undo. Return a promise for an optimistic save. */
+    onItemChange?: (change: TimelineChange) => void | Promise<void>;
+    /** Switch editing off, or parts of it. Default: on when `onItemChange` is given. */
+    editable?: TimelineEditable;
+    /** `info.multi` is true when Ctrl or Cmd was held (hosts that keep a multi-selection). */
+    onSelect?: (id: string | null, info: SelectInfo) => void;
+    /** Enter or double-click on an item. */
+    onOpen?: (item: TimelineItem) => void;
+    /**
+     * The pointer moved over an item, or the keyboard moved to one (at its bar). Called once with
+     * `null` on leaving the items.
+     */
+    onHover?: (item: TimelineItem | null, at: PointerInfo) => void;
+    /** Item ids kept at full strength; the rest dim. Empty or undefined: nothing dims. */
+    highlighted?: readonly string[];
+    /** Right-click, the Menu key or Shift+F10 on an item. When set, the browser's menu doesn't open. */
+    onContextMenu?: (item: TimelineItem, at: PointerInfo) => void;
+    /** Colours from the host. `foreground` and `background` (high contrast) replace every grey. */
+    colors?: Partial<TimelineColors>;
+    /** `false`: no entrance animation or transitions (export snapshots). Default true. */
+    animate?: boolean;
+}
+interface TimelineColors {
+    /** The today line. */
+    today: string;
+    foreground: string;
+    background: string;
+}
+
+declare function Timeline(props: TimelineProps): React.JSX.Element;
+
+/** An item with its dates resolved to UTC day numbers. */
+interface Placed {
+    item: TimelineItem;
+    id: string;
+    /** Day number (inclusive). */
+    start: number;
+    /** Day number (inclusive). Equal to start for milestones. */
+    end: number;
+    milestone: boolean;
+}
+/**
+ * Where an item goes. Rules (Matt, 2026-10-26):
+ * - `milestone` set → it decides (true: a diamond on the start; false: a bar, even one day long)
+ * - otherwise an empty end, or an end equal to the start, is a milestone
+ * - only an end: a milestone on that date
+ * - no dates at all: unscheduled (the "Not scheduled" tray)
+ * - an end before the start is swapped, so nothing disappears
+ */
+declare function place(item: TimelineItem): Placed | null;
+/**
+ * Pack spans into as few rows as possible without overlaps: sort by start, then longest,
+ * then id (deterministic), and put each span in the first row that has ended before it starts.
+ * Ends are inclusive day numbers.
+ */
+declare function packRows(spans: readonly {
+    id: string;
+    start: number;
+    end: number;
+}[]): {
+    row: Map<string, number>;
+    rows: number;
+};
+interface Lane {
+    key: string;
+    label: string;
+    items: Placed[];
+    /** Packed row per item id. */
+    row: Map<string, number>;
+    rows: number;
+    collapsed: boolean;
+    top: number;
+    height: number;
+    /** Position among lanes (zebra tint, keyboard). */
+    index: number;
+}
+/** Lanes with packed rows and vertical positions, plus the items without dates. */
+declare function buildLanes(items: readonly TimelineItem[], scale: Pick<RoadmapScale, 'dayWidth'>, opts?: {
+    laneOrder?: readonly string[];
+    collapsed?: ReadonlySet<string>;
+    filter?: string;
+    textScale?: number;
+}): {
+    lanes: Lane[];
+    unscheduled: TimelineItem[];
+};
+/** Validated palette for values without a colour (distinct in lightness as well as hue). */
+declare const PALETTE: string[];
+type BarStyle = 'solid' | 'outline' | 'done';
+interface Appearance {
+    /** Fill (or outline) colour. */
+    color: string;
+    /** Text on the fill: always 4.5:1. */
+    text: string;
+    style: BarStyle;
+}
+/**
+ * Colour for an item. Order: the item's own colour → the host's map for the value (e.g.
+ * Dataverse choice colours) → the meaning of the status word → a palette colour per value.
+ * Text on bars is always readable (`accentForText` shades the fill just enough).
+ */
+declare function appearance(item: TimelineItem, o: {
+    colorBy: 'status' | 'lane';
+    accent: string;
+    statusColors?: Readonly<Record<string, string>>;
+    laneColors?: Readonly<Record<string, string>>;
+    seen: Map<string, string>;
+}): Appearance;
+/** Items per horizon column (case-insensitive), plus any without a recognised horizon. */
+declare function horizonColumns(items: readonly TimelineItem[]): {
+    key: string;
+    items: TimelineItem[];
+}[];
+
+declare const SAMPLE_LANES: string[];
+declare function sampleRoadmap(): TimelineItem[];
+
+interface TimelineExport {
+    title: string;
+    lanes: Lane[];
+    unscheduled: TimelineItem[];
+    /** The screen's scale: print refits it to the page, PNG uses it as is. */
+    scale: RoadmapScale;
+    looks: ReadonlyMap<string, Appearance>;
+    theme: ComponentTheme;
+    today: number;
+    /** "26 Oct 2026". */
+    printedOn: string;
+    showDependencies: boolean;
+    mode: TimelineMode;
+    fiscalYearStart?: number;
+}
+/** The print document. Pure: same inputs, same HTML. */
+declare function timelinePrintHtml(o: TimelineExport): string;
+
+/** This package's version, for Copy diagnostics. `version.test.ts` keeps it equal to package.json. */
+declare const VERSION = "1.0.0-rc.1";
+
+export { type Appearance, type Lane, PALETTE, type Placed, SAMPLE_LANES, Timeline, type TimelineChange, type TimelineEditable, type TimelineFields, type TimelineItem, type TimelineMode, type TimelineProps, type TimelineZoom, VERSION, appearance, buildLanes, horizonColumns, packRows, place, sampleRoadmap, timelinePrintHtml };