@jaeungkim/gantt-chart 1.3.0 → 1.4.0

package/dist/index.d.cts

@@ -1,12 +1,428 @@
-export { default as ReactGanttChart } from './Gantt';
-export type { GanttProps } from './props';
-export type { GanttDetailApi, GanttHandle, GanttTaskCreateApi, GanttScrollApi, GanttScrollOptions, GanttZoomAnchor, } from './timeline/hooks/useGanttScrollApi';
-export type { Task, TaskDependency, DependencyType, TaskTransformed, GanttInteractionConfig, } from './shared/task';
-export type { GanttDependencyChange } from './dependencies/hooks/useGanttLinkDrag';
-export type { GanttMoveRejection, GanttTaskMove, GanttTaskMoveChange, } from './core/reorder';
-export type { GanttTaskDraft } from './bars/hooks/useGanttDrawCreate';
-export type { GanttDateRange, GanttDetailRenderProps, GanttDetailRenderer, GanttFormatOverrides, GanttScaleFormat, GanttScaleKey, GanttTheme, Holiday, } from './shared/types';
-export type { GanttRow } from './rows/utils/rows';
-export { CALENDAR_DAYS, createWorkingCalendar, type WorkingCalendar, type WorkingCalendarOptions, } from './core/calendar';
-export { buildTaskTree, collectSubtreeIds, rollUpTasks, type TaskTree, } from './core/tree';
-export { moveTask, sortTasksBySequence, validateMove, type GanttMoveOptions, } from './core/reorder';
+import { Dayjs } from 'dayjs';
+import { ForwardRefExoticComponent } from 'react';
+import { ReactNode } from 'react';
+import { RefAttributes } from 'react';
+
+export declare function buildTaskTree(tasks: TaskNode[]): TaskTree;
+
+/** The default calendar: every day counts, so arithmetic through it is plain calendar arithmetic. */
+export declare const CALENDAR_DAYS: WorkingCalendar;
+
+/**
+ * The subtree's ids including the root itself (breadth first)
+ * An id that is not in the tree yields an empty array
+ */
+export declare function collectSubtreeIds(tasks: TaskNode[], rootId: string, tree?: TaskTree): string[];
+
+/** A calendar that skips weekends and holidays, configured like the chart's non-working-day shading. */
+export declare function createWorkingCalendar(options?: WorkingCalendarOptions): WorkingCalendar;
+
+export declare type DependencyType = 'FS' | 'SS' | 'FF' | 'SF';
+
+/** The rendered timeline range, as reported by `onRangeChange` */
+export declare interface GanttDateRange {
+    start: Dayjs;
+    end: Dayjs;
+}
+
+/** The link the user drew, handed to `onDependencyCreate` before anything is committed */
+export declare interface GanttDependencyChange {
+    /** Task the drag started on */
+    predecessorId: string;
+    /** Task the drag was dropped on - the one whose `dependencies` gains the entry */
+    successorId: string;
+    type: DependencyType;
+}
+
+/** Opening and closing the detail panel from outside the chart */
+export declare interface GanttDetailApi {
+    /** Opens the detail panel on a task; unknown ids and a panel-less chart (no `renderDetail`/`showDetail`) are ignored */
+    openDetail: (taskId: string) => void;
+    /** Closes the detail panel */
+    closeDetail: () => void;
+}
+
+export declare type GanttDetailRenderer = (props: GanttDetailRenderProps) => ReactNode;
+
+/** Props handed to a `renderDetail` override */
+export declare interface GanttDetailRenderProps {
+    task: TaskTransformed;
+    /** Closes the panel - wire it to your own close control */
+    close: () => void;
+    scale: GanttScaleKey;
+    /**
+     * Patches the open task through the chart's normal commit path (the store, then
+     * `onTasksChange`), so a custom body can commit edits in uncontrolled mode. Applies NO
+     * permission checks - a custom body enforces its own rules.
+     */
+    update: (patch: Partial<Omit<Task, 'id'>>) => void;
+}
+
+/** Per-scale label overrides, e.g. `{ quarter: { header: (d) => ... } }` */
+export declare type GanttFormatOverrides = Partial<Record<GanttScaleKey, GanttScaleFormat>>;
+
+/** Imperative API exposed through the ref */
+export declare interface GanttHandle extends GanttScrollApi, GanttDetailApi, GanttTaskCreateApi {
+}
+
+/** Chart-wide interaction settings - every gesture is allowed by default (task creation also needs `onTaskCreate`), and a task's own field of the same name wins. */
+export declare interface GanttInteractionConfig {
+    readOnly?: boolean;
+    allowMove?: boolean;
+    allowResize?: boolean;
+    allowProgressChange?: boolean;
+    allowLinkCreate?: boolean;
+    allowLinkDelete?: boolean;
+    allowTaskCreate?: boolean;
+    /** Turns row reordering on - opt-in (default false). */
+    allowReorder?: boolean;
+    minDate?: string;
+    maxDate?: string;
+}
+
+export declare interface GanttMoveOptions {
+    /** Whether the parentId hierarchy is on - off, depth comes from `sequence` and a reparent is refused */
+    hierarchy: boolean;
+    /** Whether this task may be moved at all - left out, every task may */
+    canReorder?: (task: Task) => boolean;
+}
+
+/** Why a move was refused - null from `validateMove` means it is allowed */
+export declare type GanttMoveRejection = "unknown-task" | "unknown-parent" | "read-only" | "cycle" | "reparent-disabled" | "no-op";
+
+export declare interface GanttProps {
+    /** Task data array. Applied only when the contents change (a new array with equal contents is ignored); `[]` clears the chart. */
+    tasks?: Task[];
+    /** Callback invoked when tasks change */
+    onTasksChange?: (updatedTasks: Task[]) => void;
+    /** Chart height (px or a CSS value, default 600) */
+    height?: number | string;
+    /** Chart width (px or a CSS value, default `"100%"`) */
+    width?: number | string;
+    /** Theme setting. One of 'light', 'dark', or 'system'; omitted, the host page's `color-scheme` decides. */
+    theme?: GanttTheme;
+    /** Scale the chart starts at (default `"month"`). A mount-time seed; use `setScale` on the ref to change it later. */
+    defaultScale?: GanttScaleKey;
+    /** Called whenever the scale changes, from any source (ref, Ctrl/Cmd + wheel, `zoomToFit()`, keyboard). Not on mount. */
+    onScaleChange?: (scale: GanttScaleKey) => void;
+    /** Additional CSS class name */
+    className?: string;
+    /** Whether to shade non-working days and show holiday names (default true). `false` hides both. */
+    showNonWorkingDays?: boolean;
+    /** Which weekdays are worked, 0 = Sunday (default Mon-Fri). Pass a stable array. */
+    workingWeekdays?: number[];
+    /** Days off beyond the weekend. A bare `YYYY-MM-DD` string is one with no label. Pass a stable array. */
+    holidays?: (string | Holiday)[];
+    /** Scroll here once after the first render. Takes `"today"` or a date string; later data updates leave the scroll alone. */
+    initialScrollTo?: "today" | string;
+    /** Blocks every editing gesture on every task. Any `allowX` flag at either level beats it, and reordering defaults to false whether or not this is set. */
+    readOnly?: boolean;
+    /** Allows/blocks moving bars, and `Delete` on a focused row (default true). Beats `readOnly`. */
+    allowMove?: boolean;
+    /** Allows/blocks resizing bars (default true). Beats `readOnly`. */
+    allowResize?: boolean;
+    /** Allows/blocks dragging the progress handle (default true). Beats `readOnly`. */
+    allowProgressChange?: boolean;
+    /** Earliest date any bar may be dragged to (ISO string). A task's own `minDate` wins. */
+    minDate?: string;
+    /** Latest date any bar may be dragged to (ISO string). A task's own `maxDate` wins. */
+    maxDate?: string;
+    /** Pins the timeline to start here (ISO string) instead of fitting to the tasks */
+    visibleStart?: string;
+    /** Pins the timeline to end here (ISO string) instead of fitting to the tasks */
+    visibleEnd?: string;
+    /** BCP 47 locale tag for every date label, e.g. `"ko-KR"`, via `Intl.DateTimeFormat`. Omitted or unusable falls back to the built-in English labels. */
+    locale?: string;
+    /** Per-scale label overrides (`tick`, `header`, `tooltip`). They win over `locale`, and the `Dayjs` handed in is in UTC mode. */
+    formats?: GanttFormatOverrides;
+    /** First day of the week, 0 = Sunday .. 6 = Saturday. Set it to group the week scale's top header by week instead of by month (off when omitted). */
+    firstDayOfWeek?: number;
+    /** Whether to show the task list pane on the left (default false). Names only; per-task detail belongs in `renderDetail`. */
+    showTaskList?: boolean;
+    /** Whether the task list prints each row's `sequence` as a leading number column (default false). */
+    showRowNumbers?: boolean;
+    /** Whether to use the parentId hierarchy (default false). Parents become summary rows (dates and progress rolled up, dragging moves the subtree); row order still comes from `sequence`. */
+    hierarchy?: boolean;
+    /** Ids of collapsed parents. Controlled: given, this value is what the chart shows. */
+    collapsedIds?: string[];
+    /** Initial collapsed list (uncontrolled seed; later changes are ignored) */
+    defaultCollapsedIds?: string[];
+    /** Called whenever the collapsed state changes. In controlled and uncontrolled mode alike. */
+    onCollapsedChange?: (collapsedIds: string[]) => void;
+    /** Allows/blocks drawing dependencies between bars (default true). Beats `readOnly`. */
+    allowLinkCreate?: boolean;
+    /** Allows/blocks selecting and deleting dependency arrows (default true). Beats `readOnly`. */
+    allowLinkDelete?: boolean;
+    /** Allows/blocks drawing a new task below the last row (default true). Beats `readOnly`. */
+    allowTaskCreate?: boolean;
+    /**
+     * Whether task-list rows can be dragged to a new position or a new parent (default false). A
+     * task's own `allowReorder` wins, and a move rewrites `sequence` (re-parenting also `parentId`).
+     */
+    allowReorder?: boolean;
+    /** Called with the link the user drew, before it is applied. Return false to reject it; self-links, duplicates and cycles never reach it. */
+    onDependencyCreate?: (change: GanttDependencyChange) => boolean | void;
+    /** Called with the arrow the user asked to remove, before it is applied. Return false to keep it. */
+    onDependencyDelete?: (change: GanttDependencyChange) => boolean | void;
+    /** Called with the range drawn below the last row, snapped to the current scale. The chart adds nothing itself; the host passes a new `tasks` array back. */
+    onTaskCreate?: (draft: GanttTaskDraft) => void;
+    /**
+     * Called with the move the user made, before it is applied. Return false to reject it (sync only,
+     * revert by passing the previous `tasks` back). Carries `toParentId`/`toIndex` and `afterId`/`beforeId`;
+     * moves the chart already refuses never reach it.
+     */
+    onTaskMove?: (change: GanttTaskMoveChange) => boolean | void;
+    /** Fires when a bar or a task-list row is clicked (not after a drag) */
+    onTaskClick?: (task: TaskTransformed, event: React.MouseEvent) => void;
+    /** Fires on a double click. The two clicks that make it up still fire `onTaskClick` */
+    onTaskDoubleClick?: (task: TaskTransformed, event: React.MouseEvent) => void;
+    /** Fires when the selection changes, null when the empty timeline is clicked. Passing it turns selection on. */
+    onTaskSelect?: (task: TaskTransformed | null) => void;
+    /** Whether clicking selects a row. Omitted, selection is on when `onTaskSelect` is given or the detail panel is on. */
+    selectable?: boolean;
+    /** Panel body shown beside the chart for one task. Passing it turns the panel on, and the timeline narrows rather than being covered. The props include `update` for committing edits. */
+    renderDetail?: GanttDetailRenderer;
+    /**
+     * Whether the detail panel is available (omitted, it exists exactly when `renderDetail` is given;
+     * `true` alone shows the built-in field list, editable in place where the task's interaction
+     * flags allow). A click on a bar or row opens it, `Enter` on a focused row too. Turning it on
+     * also turns row selection on unless `selectable` says otherwise.
+     */
+    showDetail?: boolean;
+    /** Id of the task whose detail is open, `null` for closed. Controlled: given, this value is what the chart shows. */
+    detailTaskId?: string | null;
+    /** Called on every open and close. In controlled and uncontrolled mode alike. */
+    onDetailChange?: (task: TaskTransformed | null) => void;
+    /** Hover and drag tooltips (default true). `false` suppresses both. */
+    showTooltip?: boolean;
+    /** Whether Ctrl/Cmd + wheel steps through the scales (default false). The date under the cursor stays put. */
+    zoomOnWheel?: boolean;
+    /** Whether scrolling or dragging past an end grows the rendered range (default false). It extends by about a viewport at a time. */
+    infiniteScroll?: boolean;
+    /** Called whenever the rendered timeline range changes. The hook for lazy-loading tasks. */
+    onRangeChange?: (range: GanttDateRange) => void;
+    /** Whether a bar drag reaching a viewport edge scrolls the timeline (default true) */
+    autoScrollOnDrag?: boolean;
+    /** Snap a drag result forward off non-working days (default false). Uses the same days that shade the timeline; bars still span them visually. */
+    workingCalendar?: boolean;
+}
+
+/** One rendered row: one task, or several sharing a `lane` */
+export declare interface GanttRow {
+    /** Stable key - the ids on the row, joined with "+" */
+    id: string;
+    tasks: TaskTransformed[];
+    /** Indentation level, 0-based */
+    depth: number;
+    /** `aria-level`, 1-based */
+    level: number;
+    /** `aria-posinset` among the rows that share a parent */
+    posinset: number;
+    /** `aria-setsize` for that same set */
+    setsize: number;
+}
+
+/** Replaces the generated labels of one scale - whatever is left out keeps the built-in (or locale) label. */
+export declare interface GanttScaleFormat {
+    /** Bottom header row - one label per tick */
+    tick?: (date: Dayjs) => string;
+    /** Top header row - one label per group */
+    header?: (date: Dayjs) => string;
+    /**
+     * Every date the chart writes as a single date: the bar's hover tooltip, its live drag readout
+     * and aria-label, the header's drag guide labels (through `edge` and `range`, which follow this
+     * slot), and the detail panel's Start and End where they are not editable - an editable date is
+     * a native `<input type="date">` and never reaches a formatter.
+     */
+    tooltip?: (date: Dayjs) => string;
+}
+
+export declare type GanttScaleKey = 'day' | 'week' | 'month' | 'quarter' | 'year';
+
+/** Imperative scroll and zoom API */
+export declare interface GanttScrollApi {
+    /** Scroll horizontally to a given date */
+    scrollToDate: (date: string | Date | Dayjs, options?: GanttScrollOptions) => void;
+    /** Scroll horizontally to today */
+    scrollToToday: (options?: GanttScrollOptions) => void;
+    /** Scroll horizontally and vertically to a given task */
+    scrollToTask: (taskId: string, options?: GanttScrollOptions) => void;
+    /** Switches the scale, keeping the center date centered; an unknown key is ignored */
+    setScale: (scale: GanttScaleKey) => void;
+    /** Switches to the finest scale the whole project fits at and scrolls it into view (no-op with no tasks) */
+    zoomToFit: () => void;
+    /** The scroll container DOM node (null when unavailable) */
+    getScrollElement: () => HTMLDivElement | null;
+}
+
+/** Options for the scrollTo* methods */
+export declare interface GanttScrollOptions {
+    /** Whether to animate the scroll (default true) */
+    smooth?: boolean;
+    /** Where the target lands inside the viewport (default 'center') */
+    align?: "start" | "center";
+}
+
+/** Proposing a new task from outside the chart */
+export declare interface GanttTaskCreateApi {
+    /** Sends a one-tick draft at today to `onTaskCreate`, as the "Add task" button does; no-op without `onTaskCreate` or with `allowTaskCreate` false */
+    addTask: () => void;
+}
+
+/** The task the user drew, handed to `onTaskCreate` - nothing is committed by the chart */
+export declare interface GanttTaskDraft {
+    /** UTC ISO string, snapped to the current scale */
+    startDate: string;
+    endDate: string;
+}
+
+/** Where a task is going: a parent, and a slot among that parent's children */
+export declare interface GanttTaskMove {
+    taskId: string;
+    /** New parent, null for the root level */
+    toParentId: string | null;
+    /** Slot among the new parent's children, counted in the list as it stands after the move */
+    toIndex: number;
+}
+
+/** The move that was applied - `toIndex` for an index-based API, `afterId`/`beforeId` for a position-based one */
+export declare interface GanttTaskMoveChange extends GanttTaskMove {
+    fromParentId: string | null;
+    fromIndex: number;
+    /** Sibling the task now follows - null when it is the first child */
+    afterId: string | null;
+    /** Sibling the task now precedes - null when it is the last child */
+    beforeId: string | null;
+}
+
+/** Chart theme - 'system' follows the OS setting; omit the prop to follow the host page's `color-scheme`. */
+export declare type GanttTheme = 'light' | 'dark' | 'system';
+
+/** A day off beyond the weekend. A bare `YYYY-MM-DD` string is the same thing with no label. */
+export declare interface Holiday {
+    /** UTC `YYYY-MM-DD`. A string carrying a time or an offset is read as a UTC instant. */
+    date: string;
+    /** Inclusive last day, read the same way as `date`. Omit for a single day. */
+    endDate?: string;
+    /** Written in the tick row over the holiday's band, when the band is wide enough to hold it */
+    label?: string;
+    /** Any CSS color. Tinted onto the grid at the weekend shade's weight, never painted over it. */
+    color?: string;
+}
+
+/**
+ * Applies a move, renumbering every sequence from the resulting row order; `parentId` is rewritten
+ * on the moved task only. Null when refused (`validateMove` says why); unchanged tasks keep identity.
+ */
+export declare function moveTask(tasks: Task[], move: GanttTaskMove, options: GanttMoveOptions): {
+    tasks: Task[];
+    change: GanttTaskMoveChange;
+} | null;
+
+/** Gantt chart component. Creates a store per instance, so two charts on one page cannot share state. */
+export declare const ReactGanttChart: ForwardRefExoticComponent<GanttProps & RefAttributes<GanttHandle>>;
+
+/**
+ * The tasks with every parent recomputed as a summary row: start/end always from the children
+ * (deepest first, so a move travels all the way up); an explicit progress is left alone.
+ */
+export declare function rollUpTasks(tasks: Task[], tree?: TaskTree): Task[];
+
+/** Sort tasks by their sequence hierarchy - row order comes from this and nothing else */
+export declare function sortTasksBySequence<T extends Pick<Task, "sequence">>(tasks: T[]): T[];
+
+export declare interface Task {
+    id: string;
+    name: string;
+    startDate: string;
+    endDate: string;
+    parentId: string | null;
+    sequence: string;
+    /** Progress 0-100 (%) - omitted means no progress display */
+    progress?: number;
+    /** Bar color (any CSS color) - progress fill and hover shade derive from it; omitted, the `--gantt-*` tokens decide */
+    color?: string;
+    /** Extra class name put on this task's bar and its task-list row */
+    className?: string;
+    /** Lane this task shares a row with - lane-mates draw side by side, overlaps stack onto extra rows */
+    lane?: string;
+    dependencies?: TaskDependency[];
+    /** Blocks every gesture on this task - overrides the chart's `readOnly` prop */
+    readOnly?: boolean;
+    /** Allows/blocks moving this task - overrides both `readOnly` settings */
+    allowMove?: boolean;
+    /** Allows/blocks resizing this task - overrides both `readOnly` settings */
+    allowResize?: boolean;
+    /** Allows/blocks dragging this task's progress handle - overrides both `readOnly` settings */
+    allowProgressChange?: boolean;
+    /** Allows/blocks starting a dependency drag from this task - overrides both `readOnly` settings */
+    allowLinkCreate?: boolean;
+    /** Allows/blocks deleting a dependency this task owns - overrides both `readOnly` settings */
+    allowLinkDelete?: boolean;
+    /** Allows/blocks dragging this row to a new position or parent - opt-in, off unless this or the chart's `allowReorder` turns it on */
+    allowReorder?: boolean;
+    /** Earliest date this task may be dragged to (ISO string) - overrides the chart's `minDate` */
+    minDate?: string;
+    /** Latest date this task may be dragged to (ISO string) - overrides the chart's `maxDate` */
+    maxDate?: string;
+}
+
+export declare interface TaskDependency {
+    /** The predecessor's id - a task's `dependencies` list the tasks it waits on */
+    targetId: string;
+    type: DependencyType;
+}
+
+/** The minimum a task needs for the tree math - TaskTransformed fits as-is */
+declare type TaskNode = Pick<Task, "id" | "parentId">;
+
+export declare interface TaskTransformed extends Task {
+    barLeft: number;
+    barWidth: number;
+    depth: number;
+    order: number;
+    originalOrder: number;
+    /** Row with children - its dates roll up, so resize and progress editing are off and dragging moves the subtree. */
+    isSummary?: boolean;
+    dependencies?: TaskDependency[];
+}
+
+/**
+ * A normalized tree built from parentId. Orphans, self-references and cycles lose their
+ * parent link and become roots, so what comes out is always acyclic.
+ */
+export declare interface TaskTree {
+    /** parent id -> child ids (in input order) */
+    childIds: Map<string, string[]>;
+    /** task id -> normalized parent id (null for a root, an orphan or a cycle) */
+    parentOf: Map<string, string | null>;
+    /** task id -> depth from the root */
+    depthOf: Map<string, number>;
+    /** Root ids, in input order - the sibling list childIds has no key for */
+    rootIds: string[];
+}
+
+/** Whether a move can be applied, and why not when it cannot - runs on every frame of a row drag */
+export declare function validateMove(tasks: Task[], move: GanttTaskMove, options: GanttMoveOptions): GanttMoveRejection | null;
+
+/** Day arithmetic that can skip non-working days. */
+export declare interface WorkingCalendar {
+    /** False for the default calendar (every day counts) */
+    readonly skipsNonWorkingDays: boolean;
+    isWorkingDay(date: Dayjs): boolean;
+    /** Moves `days` days forward (or backward), skipping non-working days */
+    addDays(date: Dayjs, days: number): Dayjs;
+    /** Days from `from` to `to`, counted the same way `addDays` moves. Signed. */
+    daysBetween(from: Dayjs, to: Dayjs): number;
+    /** The date itself when it is a working day, otherwise the next one (time of day kept) */
+    snapForward(date: Dayjs): Dayjs;
+}
+
+export declare interface WorkingCalendarOptions {
+    /** Working weekdays as UTC day numbers, 0 = Sunday (default Mon-Fri) */
+    workingWeekdays?: number[];
+    /** Non-working dates as UTC `YYYY-MM-DD` strings */
+    holidays?: string[];
+}
+
+export { }