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

package/dist/index.d.cts

@@ -0,0 +1,439 @@
+import * as React from 'react';
+
+/**
+ * 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;
+}
+
+/**
+ * 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;
+}
+
+type Zoom = 'week' | 'month' | 'quarter';
+interface Tick {
+    day: number;
+    x: number;
+    width: number;
+    label: string;
+}
+interface TimeScale {
+    zoom: Zoom;
+    startDay: number;
+    /** Exclusive. */
+    endDay: number;
+    dayWidth: number;
+    width: number;
+    x(day: number): number;
+    /** Day at a pixel offset (for drag, later). */
+    dayAt(x: number): number;
+    major: Tick[];
+    minor: Tick[];
+    /** Weekend bands, only at week zoom. */
+    weekends: {
+        x: number;
+        width: number;
+    }[];
+}
+
+/**
+ * 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;
+}
+/** A host formatter, e.g. one built from a Power BI format string. `C` says what is formatted. */
+type HostFormat<C> = (value: number, ctx: C) => string;
+
+/**
+ * "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'>>;
+
+type GanttTaskKind = 'task' | 'phase' | 'milestone';
+interface GanttTask {
+    id: string;
+    name: string;
+    /** ISO date. Phases without dates take the span of their children. */
+    start?: string;
+    /** ISO date, inclusive. */
+    end?: string;
+    /** Milestones: the date. Falls back to `start`. */
+    date?: string;
+    kind?: GanttTaskKind;
+    parentId?: string | null;
+    /** 0–100. */
+    progress?: number;
+    owner?: {
+        name: string;
+        initials?: string;
+    };
+    baselineStart?: string;
+    baselineEnd?: string;
+    /** Finish-to-start predecessors by id. */
+    dependsOn?: string[];
+    /** Locks this row's bar: no move, resize, progress or link. */
+    readOnly?: boolean;
+}
+/** Edits the user can make on the chart. */
+type EditAction = 'move' | 'resize' | 'progress' | 'link' | 'add' | 'rename';
+/** Optional grid columns beside the task name. */
+type GanttColumn = 'owner' | 'progress' | 'start' | 'end' | 'duration';
+/** Which grid columns show. Owner and Done show by default; dates and duration don't. */
+type GanttColumns = Partial<Record<GanttColumn, boolean>>;
+/** `false` disables all editing; an object switches individual actions off. */
+type Editable = boolean | Partial<Record<EditAction, boolean>>;
+/** One edit, as the host receives it. Only the changed fields are present. */
+interface GanttChange {
+    id: string;
+    name?: string;
+    start?: string;
+    end?: string;
+    date?: string;
+    progress?: number;
+    parentId?: string | null;
+    dependsOn?: string[];
+    /** The same fields before the edit — for undo, and for hosts that diff. */
+    previous: Partial<GanttTask>;
+    source: 'drag' | 'keyboard' | 'undo' | 'redo';
+}
+/** Where the user asked for a new task. */
+interface AddTaskRequest {
+    /** Parent for the new task (`null` = top level). */
+    parentId?: string | null;
+    /** Insert after this task (the host decides ordering). */
+    afterId?: string;
+    /** Suggested start date (ISO). */
+    start?: string;
+}
+interface GanttProps extends WatermarkHostProps {
+    tasks: GanttTask[];
+    /** Shown in the toolbar and used as the accessible name. */
+    title?: string;
+    zoom?: Zoom;
+    defaultZoom?: Zoom;
+    onZoomChange?: (zoom: Zoom) => void;
+    selectedId?: string | null;
+    /** `info.multi` is true when Ctrl or Cmd was held (hosts that keep a multi-selection). */
+    onSelect?: (id: string | null, info: SelectInfo) => void;
+    /** Enter key or double-click on a row — open the record. */
+    onOpen?: (task: GanttTask) => void;
+    /** Override "today" (ISO) — useful for demos and tests. */
+    today?: string;
+    showToolbar?: boolean;
+    /** Baseline bars; the toolbar toggle controls this when uncontrolled. */
+    showBaseline?: boolean;
+    /** Height of the whole control. Default fills its container. */
+    height?: number | string;
+    /** `light`, `dark`, or a partial theme layered over light. */
+    theme?: 'light' | 'dark' | Partial<ComponentTheme>;
+    /** Shortcut for the most common customisation. */
+    accent?: string;
+    /**
+     * Text size, 1 = 100 % (0.75–2). Every label, value and title scales together, and rows 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;
+    /** Ninth Forge licence 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;
+    /**
+     * Grid columns beside the task name. Users can change them from the toolbar's
+     * Columns menu; `onColumnsChange` reports that.
+     */
+    columns?: GanttColumns;
+    onColumnsChange?: (columns: Required<GanttColumns>) => void;
+    /** Initial width of the task grid in px. Users can drag the divider; `onGridWidthChange` reports it. */
+    gridWidth?: number;
+    onGridWidthChange?: (width: number) => void;
+    /** Show the toolbar filter box (name or owner). Default true. */
+    showFilter?: boolean;
+    className?: string;
+    /**
+     * Editing on the chart. Needs `onTaskChange` (and `onAddTask` for adding).
+     * Default: everything on when the handlers are given.
+     */
+    editable?: Editable;
+    /**
+     * Called for every edit. Return a promise for an optimistic save: the chart keeps
+     * the edit while it's pending, and reverts with a toast if the promise rejects.
+     */
+    onTaskChange?: (change: GanttChange) => void | Promise<void>;
+    /** "+ Add task", Insert / Ctrl+Insert, and the row menu. */
+    onAddTask?: (request: AddTaskRequest) => void;
+    /** Each task has at most one predecessor (e.g. a single lookup column); linking replaces it after a confirm. */
+    singlePredecessor?: boolean;
+    /**
+     * Which days are working days. `mon-fri` (default): durations count working days, and drags or
+     * keyboard nudges that land on a weekend snap to the nearest working day in the direction of travel.
+     * `all`: every day counts and nothing snaps. Weekends are shaded either way.
+     */
+    workingWeek?: 'mon-fri' | 'all';
+    /**
+     * Text direction. Default: inherited from the page. With `rtl` the task list, toolbar and
+     * tooltips mirror; the timeline keeps time running left to right.
+     */
+    dir?: 'ltr' | 'rtl';
+    /** The host is still loading rows: the empty state says "Loading tasks…" instead. */
+    loading?: 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);
+    /**
+     * `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;
+    /** `none`: no built-in tooltip (the host shows its own from `onHover`). Default `built-in`. */
+    tooltip?: 'built-in' | 'none';
+    /**
+     * The pointer moved over a task row, or the keyboard moved to one (at its bar). Called once
+     * with `null` on leaving the rows.
+     */
+    onHover?: (task: GanttTask | null, at: PointerInfo) => void;
+    /** Task 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 a task. When set, the browser's menu and the
+     * chart's own row menu don't open.
+     */
+    onContextMenu?: (task: GanttTask, at: PointerInfo) => void;
+    /** Formats numbers the chart shows: % done. */
+    formatValue?: HostFormat<GanttFormatContext>;
+    /** Formats dates the chart shows (grid columns and the tooltip). */
+    formatDate?: (iso: string) => string;
+    /** Colours from the host (a report theme, or high contrast). */
+    colors?: Partial<GanttColors>;
+    /** `false`: no entrance animation or transitions (export snapshots). Default true. */
+    animate?: boolean;
+}
+/** What `formatValue` is formatting. */
+interface GanttFormatContext {
+    field: 'progress';
+    use: 'grid' | 'tooltip';
+}
+/**
+ * Host colours. `foreground` and `background` (high contrast) replace every grey: lines,
+ * muted text, shading and the tooltip.
+ */
+interface GanttColors {
+    bar: string;
+    progress: string;
+    phase: string;
+    milestone: string;
+    foreground: string;
+    background: string;
+}
+
+declare function Gantt(props: GanttProps): React.JSX.Element;
+
+declare const ROW_H = 40;
+declare const HEADER_H = 52;
+interface Row {
+    task: GanttTask;
+    kind: GanttTaskKind;
+    depth: number;
+    index: number;
+    hasChildren: boolean;
+    collapsed: boolean;
+    /** Day numbers; NaN when the task has no usable dates. */
+    start: number;
+    end: number;
+    baselineStart: number;
+    baselineEnd: number;
+    /** 0–100; phases roll up their children weighted by duration. */
+    progress: number;
+}
+/** Flatten the task tree into visible rows, deriving phase spans from their children. */
+declare function buildRows(tasks: GanttTask[], collapsed?: ReadonlySet<string>): Row[];
+/** First and last day that any row (or baseline) touches. */
+declare function rowsRange(rows: Row[]): {
+    from: number;
+    to: number;
+} | null;
+interface BarGeometry {
+    left: number;
+    width: number;
+}
+/** Inclusive end: a task from day 4 to day 15 covers 12 day-widths. */
+declare function barGeometry(start: number, end: number, scale: TimeScale): BarGeometry | null;
+interface DependencyLink {
+    /** `from>to` */
+    key: string;
+    from: string;
+    to: string;
+    /** Row indexes of the two ends (for culling to the visible range). */
+    fromIndex: number;
+    toIndex: number;
+    /** Connector line. */
+    d: string;
+    /** Arrowhead. */
+    arrow: string;
+    /** Same route minus both ends, for a wide invisible hit stroke that never covers bar handles. */
+    hit: string;
+}
+/**
+ * Finish-to-start connectors, one per link. With `window` (row indexes), only links whose
+ * vertical span crosses it are built — big plans then pay for what's on screen, not 5,000 paths.
+ */
+declare function dependencyLinks(rows: Row[], scale: TimeScale, rowH?: number, window?: {
+    first: number;
+    last: number;
+}): DependencyLink[];
+/** Finish-to-start connectors as one SVG path plus arrowheads. */
+declare function dependencyPaths(rows: Row[], scale: TimeScale, rowH?: number): {
+    lines: string;
+    arrows: string;
+};
+
+/**
+ * Editing logic for the Gantt — pure functions, no React, so node:test covers them.
+ * Days are day numbers (see @ninthforge/core); tasks carry ISO `YYYY-MM-DD` strings.
+ */
+
+/**
+ * Finish-to-start links whose successor starts too early, keyed `from>to`.
+ * After a task, the successor must start the next day or later. A milestone is a point
+ * in time, so its successor may start on the milestone's date.
+ */
+declare function brokenLinks(rows: Row[]): Set<string>;
+type LinkCheck = 'ok' | 'self' | 'cycle' | 'exists';
+/** Can `toId` be made to depend on `fromId`? Refuses self-links and cycles. */
+declare function validateLink(tasks: GanttTask[], fromId: string, toId: string): LinkCheck;
+
+/** Realistic sample plan used by the demo, docs and tests. */
+declare const sampleTasks: GanttTask[];
+
+/** 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 AddTaskRequest, type DependencyLink, type EditAction, type Editable, Gantt, type GanttChange, type GanttColors, type GanttColumn, type GanttColumns, type GanttFormatContext, type GanttProps, type GanttTask, type GanttTaskKind, HEADER_H, ROW_H, type Row, VERSION, type Zoom, barGeometry, brokenLinks, buildRows, dependencyLinks, dependencyPaths, rowsRange, sampleTasks, validateLink };