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

package/dist/index.d.cts

@@ -0,0 +1,585 @@
+import * as React from 'react';
+
+/**
+ * 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;
+}
+
+/** Which days count as working days. `mon-fri` skips Saturdays and Sundays; `all` counts every day. */
+type WorkingWeek = 'mon-fri' | 'all';
+
+/**
+ * Time zones for instant (UTC millisecond) maths.
+ *
+ * A `Zone` answers one question: at this instant, how many minutes **east of UTC** is the
+ * wall clock? Perth is +480, New York −300 (winter) / −240 (summer). Everything that turns
+ * instants into dates, hours or pixels goes through a Zone — never through the machine's
+ * local getters, which are wrong whenever the user's Dataverse zone differs from the browser's.
+ */
+type Zone = (utcMs: number) => number;
+/** No offset, ever. Also the right zone for time-zone-independent ("floating") values. */
+declare const UTC: Zone;
+declare function fixedZone(minutesEast: number): Zone;
+/** The browser's own zone. Only for demos; in Power Apps use `pcfZone`. */
+declare function browserZone(): Zone;
+/** An IANA zone such as `Europe/London`, via `Intl`. Used by the demo and the tests. */
+declare function ianaZone(name: string): Zone;
+/**
+ * The Power Apps user's zone, from `context.userSettings.getTimeZoneOffsetMinutes(date)`.
+ *
+ * Measured in Dev (DECISIONS 2026-10-25): it returns minutes **east** of UTC (Perth +480,
+ * Pacific −480 in January, −420 in July), so `sign` defaults to +1. It must always be given a
+ * date: without one the PCF API returned the standard offset during daylight time.
+ */
+declare function pcfZone(getOffset: (date: Date) => number, sign?: 1 | -1): Zone;
+
+/**
+ * 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'>>;
+
+/**
+ * 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;
+}
+
+/**
+ * Day: one day of hours. Week, Two weeks and Month: days across, bookings as bars within each
+ * day (Month is the calendar month). Agenda: a list by day, then resource, for 7 days from the
+ * date; the default below 600 px wide.
+ */
+type SchedulerView = 'day' | 'week' | 'twoWeeks' | 'month' | 'agenda';
+/** Scenario defaults (docs/specs/scheduler.md, "Scenarios"). `custom` sets nothing. */
+type SchedulerPreset = 'people' | 'rooms' | 'vehicles' | 'equipment' | 'jobs' | 'custom';
+/** What happens when a booking overlaps another on the same resource. */
+type ConflictMode = 'allow' | 'warn' | 'block';
+interface SchedResource {
+    id: string;
+    name: string;
+    /** Group by this (team, building, depot, category, area). */
+    group?: string;
+    /** Second line: role, rego, asset id. */
+    subtitle?: string;
+    /** Hours per day for utilisation (default from the preset, else 8). */
+    capacityHours?: number;
+    /** Rooms: seats, checked against booking attendees. */
+    seats?: number;
+    /** Working hours as decimal wall hours (9.5) or "09:30". Default from the preset. */
+    workStart?: number | string;
+    workEnd?: number | string;
+    /** Hex colour for the row marker. */
+    color?: string;
+    /** Image URL for the avatar (no network fetch by the component; the browser loads it). */
+    image?: string;
+    /** Sort order within the group; then by name. */
+    sort?: number;
+}
+interface SchedBooking {
+    id: string;
+    name: string;
+    /** An instant: UTC ms, or an ISO date-time with offset/Z. */
+    start: number | string;
+    end: number | string;
+    /** Empty = unassigned (shown in the Unassigned panel). */
+    resourceId: string | null;
+    /** Drives colour and the legend (e.g. Tentative / Confirmed / Done / Cancelled). */
+    status?: string;
+    /** Hex colour; overrides the status colour. */
+    color?: string;
+    allDay?: boolean;
+    subtitle?: string;
+    /** `unavailable` = leave, maintenance, closed: drawn hatched, counts against capacity. */
+    kind?: 'booking' | 'unavailable';
+    attendees?: number;
+    location?: string;
+    /** No editing for this booking (e.g. no write access). */
+    readOnly?: boolean;
+}
+interface SchedulerLabels {
+    /** "Person", "Room", "Vehicle", "Asset", "Technician", "Resource". */
+    resource: string;
+    resources: string;
+    /** "Shift", "Booking", "Hire", "Job". */
+    booking: string;
+    bookings: string;
+    /** What `group` means, for the Group by menu: "Team", "Building", "Depot", "Category", "Area". */
+    group: string;
+}
+/** The editable fields of a booking. Times in changes are ISO strings in UTC (`…Z`). */
+interface SchedFields {
+    start: string;
+    end: string;
+    resourceId: string | null;
+}
+/**
+ * One edit to one booking: the new values of the fields that changed, the old values of the
+ * same fields, and what caused it. Hosts save it (return a promise to keep it optimistic;
+ * reject to put it back).
+ */
+interface SchedChange extends Partial<SchedFields> {
+    id: string;
+    previous: Partial<SchedFields>;
+    source: 'drag' | 'keyboard' | 'assign' | 'undo' | 'redo';
+}
+/** Where the user asked for a new booking (drag across empty time, or Insert). */
+interface CreateRequest {
+    resourceId: string;
+    /** ISO UTC. */
+    start: string;
+    end: string;
+}
+/** What users may change. `true`/omitted = everything the handlers allow. */
+type SchedEditable = boolean | {
+    move?: boolean;
+    resize?: boolean;
+    create?: boolean;
+    assign?: boolean;
+};
+interface SchedulerProps extends WatermarkHostProps {
+    resources: SchedResource[];
+    bookings: SchedBooking[];
+    /** The host is still loading data: the empty state says so, and the board is marked busy. */
+    loading?: boolean;
+    /** Scenario defaults for labels, view, snapping, conflict mode and working hours. Default `custom`. */
+    preset?: SchedulerPreset;
+    title?: string;
+    /** Controlled view, or `defaultView` (preset default otherwise). */
+    view?: SchedulerView;
+    defaultView?: SchedulerView;
+    onViewChange?: (view: SchedulerView) => void;
+    /** The date shown (ISO `YYYY-MM-DD` in the scheduler's zone), controlled or default. Default: today. */
+    date?: string;
+    defaultDate?: string;
+    onDateChange?: (date: string) => void;
+    /**
+     * The instants on screen changed (view, date or working-hours toggle): `[start, end)` in UTC ms.
+     * Hosts load just this window (the PCF filters its dataset; canvas apps filter `Items`).
+     */
+    onRangeChange?: (range: {
+        start: number;
+        end: number;
+    }) => void;
+    /** Zone all times are shown in. Default: the browser's. In Power Apps the PCF passes the user's Dataverse zone. */
+    timeZone?: Zone;
+    /** "Now" for the now line (UTC ms). Default: the clock. Tests and demos pin it. */
+    now?: number;
+    workingWeek?: WorkingWeek;
+    /** Day view: show only working hours (default true; the toolbar toggles it). */
+    hideNonWorking?: boolean;
+    /** Snap for drags (minutes); default from the preset. */
+    snapMinutes?: number;
+    conflictMode?: ConflictMode;
+    /**
+     * Group resources by `group` (default true when any resource has one). Controlled when set;
+     * the toolbar's Group by menu reports changes through `onGroupByChange`.
+     */
+    groupBy?: boolean;
+    onGroupByChange?: (groupBy: boolean) => void;
+    /** Override the preset's words. */
+    labels?: Partial<SchedulerLabels>;
+    /** Status → hex colour. Unknown statuses get palette colours in order of appearance. */
+    statusColors?: Record<string, 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 resource 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). The resource column mirrors; time runs left to right. */
+    dir?: 'ltr' | 'rtl';
+    showToolbar?: boolean;
+    /** Show the Unassigned panel (default: preset; `jobs` shows it open). */
+    showUnassigned?: boolean;
+    /** Every edit (move, resize, assign, undo). Return a promise for an optimistic save. */
+    onBookingChange?: (change: SchedChange) => void | Promise<void>;
+    /** Drag across empty time on a row (or Insert): the host opens its form / creates the row. */
+    onCreate?: (request: CreateRequest) => void;
+    /** Switch editing off, or parts of it. Default: on wherever a handler is given. */
+    editable?: SchedEditable;
+    /** Selection (single booking). */
+    onSelect?: (id: string | null) => void;
+    /** Enter or double-click on a booking. */
+    onOpen?: (booking: SchedBooking) => void;
+}
+
+declare function Scheduler(props: SchedulerProps): React.JSX.Element;
+
+interface PresetDefaults {
+    labels: SchedulerLabels;
+    view: SchedulerView;
+    snapMinutes: number;
+    conflictMode: ConflictMode;
+    /** Decimal wall hours. */
+    workStart: number;
+    workEnd: number;
+    /** What capacity means in the row header: hours booked, or seats (rooms). */
+    capacity: 'hours' | 'seats';
+    capacityHours: number;
+    /** Unassigned panel open by default. */
+    showUnassigned: boolean;
+}
+/**
+ * One engine, five scenarios (docs/specs/scheduler.md, "Scenarios", Matt 2026-10-25).
+ * A preset only sets defaults; every prop still overrides it.
+ */
+declare const PRESETS: Record<SchedulerPreset, PresetDefaults>;
+declare const VIEW_LABEL: Record<SchedulerView, string>;
+
+interface Scenario {
+    resources: SchedResource[];
+    bookings: SchedBooking[];
+}
+/** Sample resources and bookings for a preset, ±3 weeks around `anchor` (ISO date), wall times in `zone`. */
+declare function sampleScenario(preset: SchedulerPreset, anchor: string, zone: Zone): Scenario;
+/**
+ * The scale target (docs/specs/scheduler.md, "Scale"): `resources` people in 10 teams, each with
+ * `perResource` bookings inside the two weeks from the Monday of `anchor`'s week (so a Two weeks
+ * view shows resources × perResource bookings), plus some overlaps, leave and unassigned jobs.
+ */
+declare function scaleScenario(anchor: string, zone: Zone, resources?: number, perResource?: number): Scenario;
+
+interface Item {
+    booking: SchedBooking;
+    id: string;
+    start: number;
+    /** Never before start; zero-length bookings get 15 minutes so they can be seen and grabbed. */
+    end: number;
+    resourceId: string | null;
+    kind: 'booking' | 'unavailable';
+    cancelled: boolean;
+}
+declare function normalise(bookings: readonly SchedBooking[]): Item[];
+/** First day shown and how many: Day = that day; Week / Two weeks start on the Monday. */
+declare function viewRange(date: string, view: SchedulerView): {
+    startDay: number;
+    days: number;
+};
+/**
+ * Stack overlapping items into lanes (greedy, by start then longest first): each item gets the
+ * first lane free at its start. Returns lane per item id and how many lanes the row needs.
+ */
+declare function assignLanes(items: readonly Item[]): {
+    lane: Map<string, number>;
+    lanes: number;
+};
+/** Ids of items that overlap another item on the same resource. Cancelled bookings never conflict. */
+declare function conflicts(items: readonly Item[]): Set<string>;
+interface GroupRow {
+    kind: 'group';
+    key: string;
+    label: string;
+    count: number;
+    collapsed: boolean;
+    top: number;
+    height: number;
+}
+interface ResourceRow {
+    kind: 'resource';
+    key: string;
+    resource: SchedResource;
+    /** Items overlapping the visible range, with their lanes. */
+    items: Item[];
+    lane: Map<string, number>;
+    lanes: number;
+    conflicts: Set<string>;
+    top: number;
+    height: number;
+    /** Position among resource rows (for aria-rowindex and keyboard). */
+    index: number;
+}
+type Row = GroupRow | ResourceRow;
+/**
+ * Rows for the board: optional group headers, then resources with their bookings in the
+ * range [from, to). Heights grow with the number of overlapping lanes.
+ */
+declare function buildRows(resources: readonly SchedResource[], items: readonly Item[], opts: {
+    from: number;
+    to: number;
+    groupBy: boolean;
+    collapsed?: ReadonlySet<string>;
+    filter?: string;
+    textScale?: number;
+}): Row[];
+/** Today's ISO date in a zone. */
+declare function todayIn(zone: Zone, now?: number): string;
+
+/**
+ * NF Capacity: utilisation per resource (or team) per week, for a heatmap. Hosts that already
+ * have totals (a Power BI model) pass `CapacityRow`s straight to `<CapacityHeatmap>`; Power Apps
+ * and code apps can build them from bookings with `weeklyUtilisation`.
+ */
+interface CapacityCell {
+    /** The week's Monday, ISO `YYYY-MM-DD`. */
+    week: string;
+    /** Hours booked in working time. */
+    booked: number;
+    /** Hours available that week. */
+    capacity: number;
+}
+interface CapacityRow {
+    id: string;
+    /** A resource or a team. */
+    name: string;
+    group?: string;
+    cells: CapacityCell[];
+}
+/** The five steps on the board: under 60%, 60–79%, 80–94%, 95–100%, over 100%. */
+type CapacityStep = 0 | 1 | 2 | 3 | 4;
+declare const STEP_LABELS: readonly ["under 60%", "60–79%", "80–94%", "95–100%", "over 100%"];
+/** Utilisation as a whole percentage, or `null` when nothing is available (capacity 0). */
+declare function utilisationPct(c: Pick<CapacityCell, 'booked' | 'capacity'>): number | null;
+declare function capacityStep(c: Pick<CapacityCell, 'booked' | 'capacity'>): CapacityStep;
+/** The key a cell is selected and highlighted by: row id + U+001F + week. A row id alone means the whole row. */
+declare function cellKey(rowId: string, week: string): string;
+/** `count` Mondays from the week containing `fromIso`. */
+declare function weekStarts(fromIso: string, count: number): string[];
+interface WeeklyOptions {
+    zone: Zone;
+    /** `mon-fri` (default): capacity counts five days a week. */
+    week?: WorkingWeek;
+    /** Defaults for resources that don't set their own (decimal hours or "09:00"). */
+    workStart?: number | string;
+    workEnd?: number | string;
+    /** Hours per day (default 8). */
+    capacityHours?: number;
+}
+/**
+ * Booked vs available hours per resource per week, using the Scheduler's capacity rules:
+ * bookings clipped to each working day, cancelled ones ignored, leave counting up to a full day.
+ */
+declare function weeklyUtilisation(resources: readonly SchedResource[], bookings: readonly SchedBooking[], weeks: readonly string[], o: WeeklyOptions): CapacityRow[];
+/** Rows summed by `group` (resources → teams), in first-seen order. Rows without a group keep their name. */
+declare function rollUp(rows: readonly CapacityRow[]): CapacityRow[];
+/** Every week that appears in the rows, sorted. */
+declare function weeksOf(rows: readonly CapacityRow[]): string[];
+/** A week in full, for tooltips and screen readers: "16 Nov 2026". */
+declare function weekName(week: string): string;
+/** Column labels like the board: "2 Nov", then "9", "16", …, and the month again when it changes. */
+declare function weekLabels(weeks: readonly string[]): string[];
+/**
+ * A message title naming who is overbooked: "Front-end squad overbooked in Nov", with "and 2
+ * others" when more rows are over, or "No one over capacity".
+ */
+declare function capacityHeadline(rows: readonly CapacityRow[], noun?: string): string;
+interface StepColor {
+    background: string;
+    text: string;
+}
+/**
+ * The five step colours from the accent: three tints, a deep shade at 95–100%, and the Negative
+ * token over 100%. Text on each reaches 4.5:1. `override` (a host's five colours) wins.
+ */
+declare function stepColors(accent: string, surface: string, override?: readonly string[]): StepColor[];
+
+interface CapacityFormatContext {
+    field: 'utilisation' | 'hours';
+    use: 'label' | 'tooltip';
+}
+interface CapacityColors {
+    /** Five colours, lowest step first (under 60% … over 100%). */
+    steps: string[];
+    foreground: string;
+    background: string;
+}
+/** What a hook receives: the row, and the cell when the pointer is on one. */
+interface CapacityTarget {
+    row: CapacityRow;
+    cell: CapacityCell;
+    /** `cellKey(row.id, cell.week)`. */
+    key: string;
+}
+interface CapacityHeatmapProps extends WatermarkHostProps {
+    /** Resources or teams, with booked and available hours per week (`weeklyUtilisation`, `rollUp`, or a host's totals). */
+    rows: CapacityRow[];
+    /** Column order. Default: every week in the rows, sorted. */
+    weeks?: string[];
+    /** Default: a message naming the most overbooked row ("Front-end squad overbooked in Nov"). */
+    title?: string;
+    /** Column labels. Default "2 Nov", "9", "16", … */
+    weekLabel?: (weekIso: string, index: number) => string;
+    /** Header over the names column. */
+    rowHeader?: string;
+    theme?: 'light' | 'dark' | Partial<ComponentTheme>;
+    accent?: string;
+    /** A Plan key (or several). Missing keys show a small watermark; nothing breaks. */
+    licenseKey?: string | PromiseLike<string | undefined>;
+    tenantId?: string;
+    height?: number | string;
+    className?: string;
+    dir?: 'ltr' | 'rtl';
+    /** Hide the legend (the host draws its own). */
+    showLegend?: boolean;
+    /** `none`: no built-in tooltip (the host shows its own from `onHover`). */
+    tooltip?: 'built-in' | 'none';
+    onHover?: (target: CapacityTarget | null, at: PointerInfo) => void;
+    /** Click, Enter or Space on a cell. `null` when Escape clears. */
+    onSelect?: (target: CapacityTarget | null, info: SelectInfo) => void;
+    /** Cell keys (`cellKey`) or row ids kept at full strength; the rest dim. */
+    highlighted?: readonly string[];
+    onContextMenu?: (target: CapacityTarget, at: PointerInfo) => void;
+    formatValue?: HostFormat<CapacityFormatContext>;
+    colors?: Partial<CapacityColors>;
+    animate?: boolean;
+}
+/**
+ * NF Capacity: who is booked how much, week by week. A resource (or team) × week heatmap with
+ * % labels, five steps from the accent, and over 100% in the Negative colour.
+ */
+declare function CapacityHeatmap(props: CapacityHeatmapProps): React.JSX.Element;
+
+/** 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 CapacityCell, type CapacityColors, type CapacityFormatContext, CapacityHeatmap, type CapacityHeatmapProps, type CapacityRow, type CapacityStep, type CapacityTarget, type ConflictMode, type CreateRequest, PRESETS, type PresetDefaults, STEP_LABELS, type Scenario, type SchedBooking, type SchedChange, type SchedEditable, type SchedFields, type SchedResource, Scheduler, type SchedulerLabels, type SchedulerPreset, type SchedulerProps, type SchedulerView, UTC, VERSION, VIEW_LABEL, type WeeklyOptions, type Zone, assignLanes, browserZone, buildRows, capacityHeadline, capacityStep, cellKey, conflicts, fixedZone, ianaZone, normalise, pcfZone, rollUp, sampleScenario, scaleScenario, stepColors, todayIn, utilisationPct, viewRange, weekLabels, weekName, weekStarts, weeklyUtilisation, weeksOf };