Gantt Examples

The example browser reads the shared demo catalog directly. Every registered Gantt demo and framework variant appears here automatically; there is no separate manual inventory to maintain.

Source code

1
import '@revolist/ui/styles.scss';
2
import { createControl } from '@revolist/ui';
3
import './gantt-showcase.scss';
4
import { defineCustomElements } from '@revolist/revogrid/loader';
5
defineCustomElements();
6

7
import { GanttPlugin } from '@revolist/gantt';
8
import { ExportExcelPlugin, RowStatusPlugin } from '@revolist/revogrid-pro';
9
import {
10
  STANDARD_CALENDAR,
11
  SHOWCASE_ASSIGNMENTS,
12
  SHOWCASE_BASELINES,
13
  SHOWCASE_COLUMNS_WITH_COMPLETION,
14
  SHOWCASE_DEFAULT_HIDDEN,
15
  SHOWCASE_DEPENDENCIES,
16
  SHOWCASE_GANTT_CONFIG,
17
  SHOWCASE_RESOURCES,
18
  SHOWCASE_TASKS,
19
  renderShowcaseTaskBarColor,
20
  renderShowcaseTaskBarContent,
21
} from '../shared/gantt-project-data';
22
import { currentTheme } from '../../composables/useRandomData';
23

24
// ─── Entry point ──────────────────────────────────────────────────────────────
25

26
export function load(parentSelector: string): void {
27
  const parent = document.querySelector(parentSelector);
28
  if (!parent) return;
29
  const darkTheme = currentTheme().isDark();
30

31
  const container = document.createElement('div');
32
  container.className = `gantt-showcase-shell grow h-full ${darkTheme ? 'gantt-showcase-shell--dark' : 'gantt-showcase-shell--light'}`;
33
  parent.appendChild(container);
34

35
  const grid = document.createElement('revo-grid') as HTMLRevoGridElement;
36
  const controls = document.createElement('div');
37
  controls.className = 'gantt-showcase-controls';
38
  container.appendChild(controls);
39

40
  grid.theme = darkTheme ? 'darkCompact' : 'compact';
41
  grid.readonly = false;
42
  grid.range = true;
43
  grid.resize = true;
44
  grid.rowSize = 42;
45
  grid.rowHeaders = false;
46
  grid.hideAttribution = true;
47
  grid.autoSizeColumn = false;
48
  grid.classList.add('gantt-showcase-grid');
49
  grid.plugins = [GanttPlugin, ExportExcelPlugin, RowStatusPlugin];
50
  grid.hideColumns = [...SHOWCASE_DEFAULT_HIDDEN];
51
  grid.columns = [...SHOWCASE_COLUMNS_WITH_COMPLETION];
52
  grid.source = [...SHOWCASE_TASKS];
53
  grid.ganttDependencies = [...SHOWCASE_DEPENDENCIES];
54
  grid.ganttCalendars = [{ ...STANDARD_CALENDAR }];
55
  grid.ganttResources = [...SHOWCASE_RESOURCES];
56
  grid.ganttAssignments = [...SHOWCASE_ASSIGNMENTS];
57
  grid.ganttBaselines = [...SHOWCASE_BASELINES];
58
  let showCriticalPath = Boolean(
59
    SHOWCASE_GANTT_CONFIG.visuals.showCriticalPath,
60
  );
61
  let showBaseline = false;
62

63
  function applyGanttConfig() {
64
    grid.gantt = {
65
      ...SHOWCASE_GANTT_CONFIG,
66
      visuals: {
67
        ...SHOWCASE_GANTT_CONFIG.visuals,
68
        showCriticalPath,
69
        showBaseline,
70
        taskBarColorHook: renderShowcaseTaskBarColor,
71
        taskBarContentHook: renderShowcaseTaskBarContent,
72
      },
73
    } as typeof grid.gantt;
74
  }
75

76
  function createToggle(
77
    label: string,
78
    checked: () => boolean,
79
    onChange: (value: boolean) => void,
80
  ) {
81
    const control = createControl(document, 'button', { class: 'rv-btn-sm' });
82
    control.textContent = label;
83
    const sync = () => {
84
      control.setAttribute('aria-pressed', String(checked()));
85
      control.classList.toggle('rv-btn-primary', checked());
86
    };
87
    control.addEventListener('click', () => {
88
      onChange(!checked());
89
      applyGanttConfig();
90
      sync();
91
    });
92
    sync();
93
    return control;
94
  }
95

96
  controls.append(
97
    createToggle(
98
      'Critical path',
99
      () => showCriticalPath,
100
      (value) => {
101
        showCriticalPath = value;
102
      },
103
    ),
104
    createToggle(
105
      'Baselines',
106
      () => showBaseline,
107
      (value) => {
108
        showBaseline = value;
109
      },
110
    ),
111
  );
112

113
  applyGanttConfig();
114
  container.appendChild(grid);
115
}

1
import '@revolist/ui/styles.scss';
2
import { ButtonControl as UiButton } from '@revolist/ui/react-control';
3
import './gantt-showcase.scss';
4
import React, { useMemo, useRef, useState } from 'react';
5
import { RevoGrid } from '@revolist/react-datagrid';
6
import { GanttPlugin } from '@revolist/gantt';
7
import { ExportExcelPlugin, RowStatusPlugin } from '@revolist/revogrid-pro';
8
import {
9
  STANDARD_CALENDAR,
10
  SHOWCASE_ASSIGNMENTS,
11
  SHOWCASE_BASELINES,
12
  SHOWCASE_COLUMNS_WITH_COMPLETION,
13
  SHOWCASE_DEFAULT_HIDDEN,
14
  SHOWCASE_DEPENDENCIES,
15
  SHOWCASE_GANTT_CONFIG,
16
  SHOWCASE_RESOURCES,
17
  SHOWCASE_TASKS,
18
  renderShowcaseTaskBarColor,
19
  renderShowcaseTaskBarContent,
20
} from '../shared/gantt-project-data';
21
import type { GanttPluginConfig } from '@revolist/gantt';
22
import { currentTheme } from '../../composables/useRandomData';
23

24
const plugins = [GanttPlugin, ExportExcelPlugin, RowStatusPlugin];
25
const source = [...SHOWCASE_TASKS];
26
const dependencies = [...SHOWCASE_DEPENDENCIES];
27
const calendars = [{ ...STANDARD_CALENDAR }];
28
const resources = [...SHOWCASE_RESOURCES];
29
const assignments = [...SHOWCASE_ASSIGNMENTS];
30
const baselines = [...SHOWCASE_BASELINES];
31
const columns = [...SHOWCASE_COLUMNS_WITH_COMPLETION];
32
const hiddenColumns = [...SHOWCASE_DEFAULT_HIDDEN];
33

34
function GanttShowcase() {
35
  const { isDark } = currentTheme();
36
  const darkTheme = isDark();
37
  const gridRef = useRef<HTMLRevoGridElement>(null);
38
  const [showCriticalPath, setShowCriticalPath] = useState(
39
    Boolean(SHOWCASE_GANTT_CONFIG.visuals.showCriticalPath),
40
  );
41
  const [showBaseline, setShowBaseline] = useState(false);
42
  const ganttConfig: GanttPluginConfig = useMemo(
43
    () =>
44
      ({
45
        ...SHOWCASE_GANTT_CONFIG,
46
        visuals: {
47
          ...SHOWCASE_GANTT_CONFIG.visuals,
48
          showCriticalPath,
49
          showBaseline,
50
          taskBarColorHook: renderShowcaseTaskBarColor,
51
          taskBarContentHook: renderShowcaseTaskBarContent,
52
        },
53
      }) as GanttPluginConfig,
54
    [showCriticalPath, showBaseline],
55
  );
56

57
  return (
58
    <div
59
      className={`gantt-showcase-shell grow h-full ${darkTheme ? 'gantt-showcase-shell--dark' : 'gantt-showcase-shell--light'}`}
60
    >
61
      <div className="gantt-showcase-controls">
62
        <UiButton
63
          className={`rv-btn-sm ${showCriticalPath ? 'rv-btn-primary' : ''}`}
64
          aria-pressed={showCriticalPath}
65
          onClick={() => setShowCriticalPath((value) => !value)}
66
        >
67
          Critical path
68
        </UiButton>
69
        <UiButton
70
          className={`rv-btn-sm ${showBaseline ? 'rv-btn-primary' : ''}`}
71
          aria-pressed={showBaseline}
72
          onClick={() => setShowBaseline((value) => !value)}
73
        >
74
          Baselines
75
        </UiButton>
76
      </div>
77
      <RevoGrid
78
        ref={gridRef}
79
        className="gantt-showcase-grid"
80
        theme={darkTheme ? 'darkCompact' : 'compact'}
81
        hideAttribution
82
        readonly={false}
83
        range
84
        resize
85
        rowSize={42}
86
        rowHeaders={false}
87
        autoSizeColumn={false}
88
        plugins={plugins}
89
        hideColumns={hiddenColumns}
90
        source={source}
91
        columns={columns}
92
        gantt={ganttConfig}
93
        ganttDependencies={dependencies}
94
        ganttCalendars={calendars}
95
        ganttResources={resources}
96
        ganttAssignments={assignments}
97
        ganttBaselines={baselines}
98
      />
99
    </div>
100
  );
101
}
102

103
export default GanttShowcase;

1
<template>
2
  <div :class="shellClass">
3
    <div class="gantt-showcase-controls">
4
      <button
5
        v-rv-control
6
        class="rv-btn rv-btn-sm"
7
        :class="{ 'rv-btn-primary': showCriticalPath }"
8
        :aria-pressed="showCriticalPath"
9
        @click="showCriticalPath = !showCriticalPath"
10
      >
11
        Critical path
12
      </button>
13
      <button
14
        v-rv-control
15
        class="rv-btn rv-btn-sm"
16
        :class="{ 'rv-btn-primary': showBaseline }"
17
        :aria-pressed="showBaseline"
18
        @click="showBaseline = !showBaseline"
19
      >
20
        Baselines
21
      </button>
22
    </div>
23
    <RevoGrid
24
      ref="gridRef"
25
      class="gantt-showcase-grid skip-style cell-border"
26
      hide-attribution
27
      :readonly="false"
28
      :range="true"
29
      :resize="true"
30
      :row-size="42"
31
      :row-headers="false"
32
      :auto-size-column="false"
33
      :theme="gridTheme"
34
      :plugins="plugins"
35
      :hide-columns.prop="hiddenColumns"
36
      :source="source"
37
      :columns="columns"
38
      :gantt.prop="ganttConfig"
39
      :gantt-dependencies.prop="dependencies"
40
      :gantt-calendars.prop="calendars"
41
      :gantt-resources.prop="resources"
42
      :gantt-assignments.prop="assignments"
43
      :gantt-baselines.prop="baselines"
44
    />
45
  </div>
46
</template>
47

48
<script setup lang="ts">
49
import '@revolist/ui/styles.scss';
50
import { vRvControl } from '@revolist/ui/vue-control';
51
import { computed, onMounted, ref } from 'vue';
52
import RevoGrid from '@revolist/vue3-datagrid';
53
import { ExportExcelPlugin, RowStatusPlugin } from '@revolist/revogrid-pro';
54
import {
55
  STANDARD_CALENDAR,
56
  SHOWCASE_ASSIGNMENTS,
57
  SHOWCASE_BASELINES,
58
  SHOWCASE_COLUMNS_WITH_COMPLETION,
59
  SHOWCASE_DEFAULT_HIDDEN,
60
  SHOWCASE_DEPENDENCIES,
61
  SHOWCASE_GANTT_CONFIG,
62
  SHOWCASE_RESOURCES,
63
  SHOWCASE_TASKS,
64
  renderShowcaseTaskBarColor,
65
  renderShowcaseTaskBarContent,
66
} from '../shared/gantt-project-data';
67
import { currentThemeVue } from '../../composables/useRandomData';
68

69
// ── Static grid data ──────────────────────────────────────────────────────────
70
const plugins = ref<unknown[]>([]);
71
const source = ref([...SHOWCASE_TASKS]);
72
const dependencies = ref([...SHOWCASE_DEPENDENCIES]);
73
const calendars = ref([{ ...STANDARD_CALENDAR }]);
74
const resources = ref([...SHOWCASE_RESOURCES]);
75
const assignments = ref([...SHOWCASE_ASSIGNMENTS]);
76
const baselines = ref([...SHOWCASE_BASELINES]);
77
const columns = ref([...SHOWCASE_COLUMNS_WITH_COMPLETION]);
78
const hiddenColumns = [...SHOWCASE_DEFAULT_HIDDEN];
79
const showCriticalPath = ref(
80
  Boolean(SHOWCASE_GANTT_CONFIG.visuals.showCriticalPath),
81
);
82
const showBaseline = ref(false);
83
const { isDark } = currentThemeVue();
84
const gridTheme = computed(() => (isDark.value ? 'darkCompact' : 'compact'));
85
const shellClass = computed(() => [
86
  'gantt-showcase',
87
  'gantt-showcase-shell',
88
  'grow',
89
  'h-full',
90
  isDark.value ? 'gantt-showcase-shell--dark' : 'gantt-showcase-shell--light',
91
]);
92

93
const ganttConfig = computed(() => ({
94
  ...SHOWCASE_GANTT_CONFIG,
95
  visuals: {
96
    ...SHOWCASE_GANTT_CONFIG.visuals,
97
    showCriticalPath: showCriticalPath.value,
98
    showBaseline: showBaseline.value,
99
    taskBarColorHook: renderShowcaseTaskBarColor,
100
    taskBarContentHook: renderShowcaseTaskBarContent,
101
  },
102
}));
103

104
// ── Refs ──────────────────────────────────────────────────────────────────────
105
const gridRef = ref<InstanceType<typeof RevoGrid> | HTMLRevoGridElement | null>(
106
  null,
107
);
108

109
onMounted(async () => {
110
  const { GanttPlugin } = await import('@revolist/gantt');
111

112
  plugins.value = [GanttPlugin, ExportExcelPlugin, RowStatusPlugin];
113
});
114
</script>
115

116
<style src="./gantt-showcase.scss" lang="scss"></style>
117

118
<style scoped>
119
.gantt-showcase :deep(revo-grid) {
120
  flex: 1;
121
  min-height: 0;
122
}
123
</style>

1
import '@revolist/ui/styles.css';
2
import { UiControlDirective } from '@revolist/ui/angular-control';
3
import { Component, NO_ERRORS_SCHEMA, ViewEncapsulation } from '@angular/core';
4
import { RevoGrid } from '@revolist/angular-datagrid';
5
import { GanttPlugin } from '@revolist/gantt';
6
import { ExportExcelPlugin, RowStatusPlugin } from '@revolist/revogrid-pro';
7
import type { GanttPluginConfig } from '@revolist/gantt';
8
import {
9
  STANDARD_CALENDAR,
10
  SHOWCASE_ASSIGNMENTS,
11
  SHOWCASE_BASELINES,
12
  SHOWCASE_COLUMNS_WITH_COMPLETION,
13
  SHOWCASE_DEFAULT_HIDDEN,
14
  SHOWCASE_DEPENDENCIES,
15
  SHOWCASE_GANTT_CONFIG,
16
  SHOWCASE_RESOURCES,
17
  SHOWCASE_TASKS,
18
  renderShowcaseTaskBarColor,
19
  renderShowcaseTaskBarContent,
20
} from '../shared/gantt-project-data';
21
import { currentTheme } from '../../composables/useRandomData';
22

23
function createGanttConfig(
24
  showCriticalPath: boolean,
25
  showBaseline: boolean,
26
): GanttPluginConfig {
27
  return {
28
    ...SHOWCASE_GANTT_CONFIG,
29
    visuals: {
30
      ...SHOWCASE_GANTT_CONFIG.visuals,
31
      showCriticalPath,
32
      showBaseline,
33
      taskBarColorHook: renderShowcaseTaskBarColor,
34
      taskBarContentHook: renderShowcaseTaskBarContent,
35
    },
36
  } as GanttPluginConfig;
37
}
38

39
@Component({
40
  selector: 'gantt-showcase-grid',
41
  standalone: true,
42
  host: {
43
    class: 'gantt-showcase-angular-host',
44
  },
45
  // Allows Angular demos to bind RevoGrid plugin props that are not wrapper inputs.
46
  schemas: [NO_ERRORS_SCHEMA],
47
  imports: [UiControlDirective, RevoGrid],
48
  encapsulation: ViewEncapsulation.None,
49
  styleUrls: ['./gantt-showcase.scss'],
50
  template: `
51
    <div [class]="shellClass">
52
      <div class="gantt-showcase-controls">
53
        <button
54
          rvControl
55
          class="rv-btn rv-btn-sm"
56
          [class.rv-btn-primary]="showCriticalPath"
57
          [attr.aria-pressed]="showCriticalPath"
58
          (click)="setCriticalPath(!showCriticalPath)"
59
        >
60
          Critical path
61
        </button>
62
        <button
63
          rvControl
64
          class="rv-btn rv-btn-sm"
65
          [class.rv-btn-primary]="showBaseline"
66
          [attr.aria-pressed]="showBaseline"
67
          (click)="setBaseline(!showBaseline)"
68
        >
69
          Baselines
70
        </button>
71
      </div>
72
      <revo-grid
73
        class="gantt-showcase-grid skip-style cell-border"
74
        [theme]="theme"
75
        [hideAttribution]="true"
76
        [readonly]="false"
77
        [range]="true"
78
        [resize]="true"
79
        [rowSize]="42"
80
        [rowHeaders]="false"
81
        [autoSizeColumn]="false"
82
        [plugins]="plugins"
83
        [hideColumns]="hiddenColumns"
84
        [source]="source"
85
        [columns]="columns"
86
        [gantt]="ganttConfig"
87
        [ganttDependencies]="dependencies"
88
        [ganttCalendars]="calendars"
89
        [ganttResources]="resources"
90
        [ganttAssignments]="assignments"
91
        [ganttBaselines]="baselines"
92
      ></revo-grid>
93
    </div>
94
  `,
95
})
96
export class GanttShowcaseGridComponent {
97
  readonly isDark = currentTheme().isDark();
98
  readonly theme = this.isDark ? 'darkCompact' : 'compact';
99
  readonly shellClass = `gantt-showcase-shell grow h-full ${this.isDark ? 'gantt-showcase-shell--dark' : 'gantt-showcase-shell--light'}`;
100
  readonly plugins = [GanttPlugin, ExportExcelPlugin, RowStatusPlugin];
101
  showCriticalPath = Boolean(SHOWCASE_GANTT_CONFIG.visuals.showCriticalPath);
102
  showBaseline = false;
103
  ganttConfig = createGanttConfig(this.showCriticalPath, this.showBaseline);
104
  readonly source = [...SHOWCASE_TASKS];
105
  readonly dependencies = [...SHOWCASE_DEPENDENCIES];
106
  readonly calendars = [{ ...STANDARD_CALENDAR }];
107
  readonly resources = [...SHOWCASE_RESOURCES];
108
  readonly assignments = [...SHOWCASE_ASSIGNMENTS];
109
  readonly baselines = [...SHOWCASE_BASELINES];
110
  readonly columns = [...SHOWCASE_COLUMNS_WITH_COMPLETION];
111
  readonly hiddenColumns = [...SHOWCASE_DEFAULT_HIDDEN];
112

113
  setCriticalPath(value: boolean): void {
114
    this.showCriticalPath = value;
115
    this.ganttConfig = createGanttConfig(
116
      this.showCriticalPath,
117
      this.showBaseline,
118
    );
119
  }
120

121
  setBaseline(value: boolean): void {
122
    this.showBaseline = value;
123
    this.ganttConfig = createGanttConfig(
124
      this.showCriticalPath,
125
      this.showBaseline,
126
    );
127
  }
128
}

Search examplesFramework

Topic

20 of 20 Gantt examples

Planning

TreePerformanceServer-side

Remote Gantt

Load server-scheduled task hierarchies with native Query, sibling paging and revision-consistent dependencies.

Source files

src/index.ts
src/gantt.remote.utils.ts
src/gantt.remote.bootstrap.ts
src/backend/seed.ts
src/backend/service.ts
src/backend/module.ts
tree-remote/backend/contracts.ts
tree-remote/backend/seed.ts
tree-remote/backend/service.ts
composables/makeData.ts
composables/useRandomData.ts

Live preview Guide API

Microsoft ProjectImportExport

Microsoft Project

Import Microsoft Project XML or MPP14, edit the schedule, inspect conversion warnings, and export the current project as XML.

Source files

src/index.ts
src/gantt-microsoft-project-data.ts
src/gantt-microsoft-project.css
src/recipes/current-schedule-snapshot.ts

Live preview Guide API

ExamplesValidationContext Menu

Feature Recipes

Runnable example of the application-owned Gantt example recipes for column presets, context menus, validation, editor forms, and task status indicators.

Source files

src/index.ts
src/GanttExampleRecipesShared.ts
src/gantt-example-recipes.css
src/shared/gantt-project-data.ts
src/shared/gantt-project-base-data.ts
src/shared/gantt-showcase-data.ts
src/shared/gantt-showcase-columns.ts
src/shared/gantt-showcase-columns.css
src/shared/gantt-showcase-icons.ts
src/recipes/current-schedule-snapshot.ts
src/recipes/index.ts
src/recipes/print-pdf-recipe.css
gantt/features/context-menu/context-menu-extensions.ts
src/recipes/feature-helper-examples.ts
src/recipes/graphql-adapter.ts
src/recipes/grid-projection-examples.ts
src/recipes/persistence-examples.ts
src/recipes/postgres-persistence.ts
src/recipes/print-pdf-recipe.ts
src/recipes/rest-adapter.ts
src/recipes/validation-recipes.ts

Live preview Guide API

EditorFormsTaskUpdate

Task Editor Form

Standalone task editor UI built from the exported Gantt field schema and submit normalizer.

Source files

src/index.ts

Live preview Guide API

HistoryRead OnlyLocalizationCustomization

Production Patterns

Try undo/redo, read-only and locked tasks, localized dates, custom visuals, JSON/Excel export, and a 750-task virtualized project.

Source files

src/index.ts
src/GanttProductionPatternsShared.ts
src/gantt-production-patterns.css
src/shared/gantt-project-data.ts
src/shared/gantt-project-base-data.ts
src/shared/gantt-showcase-data.ts
src/shared/gantt-showcase-columns.ts
src/shared/gantt-showcase-columns.css
src/shared/gantt-showcase-icons.ts
src/recipes/current-schedule-snapshot.ts
src/recipes/index.ts
src/recipes/print-pdf-recipe.css
gantt/features/context-menu/context-menu-extensions.ts
src/recipes/feature-helper-examples.ts
src/recipes/graphql-adapter.ts
src/recipes/grid-projection-examples.ts
src/recipes/persistence-examples.ts
src/recipes/postgres-persistence.ts
src/recipes/print-pdf-recipe.ts
src/recipes/rest-adapter.ts
src/recipes/validation-recipes.ts

Live preview Guide API

ShowcaseFull Feature

Full Showcase

Comprehensive Gantt implementation featuring toolbars, resources, and assignments.

Source files

src/index.ts
shared/gantt-project-data.ts
shared/gantt-project-base-data.ts
shared/gantt-showcase-data.ts
shared/gantt-showcase-columns.ts
shared/gantt-showcase-columns.css
shared/gantt-showcase-icons.ts
src/gantt-showcase.scss

Live preview API

Scheduling

Project ManagementScheduling

Basic

A powerful Gantt chart plugin for project scheduling and task management.

Source files

src/index.ts

Live preview Guide API

Big DataPerformanceDependencies

10,000 Tasks

Test virtual scrolling and task editing with 10,000 tasks and 19,796 dependencies across three months.

Source files

src/index.ts

Live preview Guide API

Big DataPerformanceDependenciesZoom

Twenty-Year Timeline

Test responsive horizontal scrolling, zooming, and task editing with 100 tasks and 194 dependencies across twenty years.

Source files

src/index.ts

Live preview Guide API

SchedulingAutomation

Scheduling

Advanced scheduling features including auto-scheduling and constraint handling.

Source files

src/index.ts

Live preview Guide API

DependenciesLead Lag

Advanced Dependencies

Finish-start, start-start, finish-finish, and start-finish links with lag, lead, and editable dependency columns.

Source files

src/index.ts
src/gantt-advanced-data.ts
src/GanttAdvancedVanillaDemo.ts

Live preview Guide API

ConstraintsDeadlines

Constraints And Deadlines

Constraint windows, hard constraints, deadline indicators, and scheduling warnings.

Source files

src/index.ts
src/gantt-advanced-data.ts
src/GanttAdvancedVanillaDemo.ts

Live preview Guide API

ALAPScheduling

Project Finish ALAP

Backward scheduling from a project finish anchor with successor-driven task placement.

Source files

src/index.ts
src/gantt-advanced-data.ts
src/GanttAdvancedVanillaDemo.ts

Live preview Guide API

Resources & Work

ResourcesScheduling

Resource Planning

Resource assignments, allocation units, cost, over-allocation warnings, and deterministic auto-leveling.

Source files

src/index.ts
src/gantt-advanced-data.ts
src/GanttAdvancedVanillaDemo.ts
src/gantt-resource-planning-toolbar.ts

Live preview Guide API

SchedulingLead LagWork

Scheduler Features

A single scheduler-focused example showing dependency lag, dependency lead, and fixed-duration, fixed-work, and fixed-units effort modes.

Source files

src/index.ts
src/gantt-advanced-data.ts
src/GanttAdvancedVanillaDemo.ts

Live preview Guide API

ProgressWork

Progress And Work

Fixed-duration, fixed-work, fixed-units, actuals, remaining duration, and split-range scheduling.

Source files

src/index.ts
src/gantt-advanced-data.ts
src/GanttAdvancedVanillaDemo.ts

Live preview Guide API

Split TasksScheduling

Split Tasks

Pause and resume work within task spans using split ranges while preserving planned working duration.

Source files

src/index.ts
src/gantt-advanced-data.ts
src/GanttAdvancedVanillaDemo.ts

Live preview Guide API

Analysis & Optimization

BaselinesProject Management

Baselines

Compare current project progress against approved baselines in real-time.

Source files

src/index.ts

Live preview Guide API

Critical PathOptimization

Critical Path

Highlight tasks on the critical path to identify project bottlenecks.

Source files

src/index.ts

Live preview Guide API

Critical PathSlack

Critical Path Analysis

Show early/late dates, total slack, and noncritical parallel work with positive float.

Source files

src/index.ts
src/gantt-advanced-data.ts
src/GanttAdvancedVanillaDemo.ts

Live preview Guide API

Copyable application recipes

These helpers live in the examples workspace. Copy the relevant recipes files beside your application example and use relative imports; they are not exports of @revolist/gantt.

Context menuGrid actions

Context menu extensions

Duplicate, delete, assign-resource, and export actions for Gantt row menus.

packages/gantt/src/gantt/features/context-menu/context-menu-extensions.ts

Open preview

Source code

1
/**
2
 * @packageDocumentation
3
 * Helpers for extending the Gantt context menu through RevoGrid Pro.
4
 *
5
 * The helpers create task-aware context-menu items for duplicate, delete,
6
 * assign-resource, and export actions. They keep persistence and permission
7
 * decisions in the host application while providing a consistent Gantt context
8
 * object with the focused task, grid element, providers, selected range, and
9
 * close callback.
10
 */
11
import exportIcon from '@fortawesome/fontawesome-free/svgs/solid/file-export.svg?raw';
12
import type { Cell, PluginProviders, RangeArea } from '@revolist/revogrid';
13
import {
14
  EXCEL_EXPORT_EVENT,
15
  type ContextMenuItem,
16
  type ExportExcelEvent,
17
} from '@revolist/revogrid-pro';
18

19
import type { TaskEntity, TaskId } from '../../core';
20
import { GANTT_TASK_CREATE_EVENT } from '../../grid/gantt-events';
21
import type { GanttCreateTaskOptions } from '../../grid/gantt-plugin.types';
22

23
type ContextMenuActionContext = NonNullable<
24
  Parameters<NonNullable<ContextMenuItem['action']>>[4]
25
>;
26

27
export interface GanttContextMenuExtensionContext {
28
  readonly event: MouseEvent;
29
  readonly focused?: Cell | null;
30
  readonly range?: RangeArea | null;
31
  readonly close?: () => void;
32
  readonly revogrid: HTMLRevoGridElement;
33
  readonly providers: PluginProviders;
34
  readonly taskId: TaskId | null;
35
  readonly task: Partial<TaskEntity> | null;
36
}
37

38
export interface GanttContextMenuBaseItemOptions {
39
  readonly name?: ContextMenuItem['name'];
40
  readonly class?: string;
41
  readonly rowClass?: ContextMenuItem['rowClass'];
42
  readonly icon?: string;
43
  readonly hidden?: ContextMenuItem['hidden'];
44
  readonly keepOpen?: boolean;
45
}
46

47
export interface DuplicateTaskMenuItemOptions extends GanttContextMenuBaseItemOptions {
48
  readonly copyName?: (
49
    task: Partial<TaskEntity>,
50
    context: GanttContextMenuExtensionContext,
51
  ) => string;
52
  readonly createTaskOptions?: (
53
    context: GanttContextMenuExtensionContext,
54
  ) => GanttCreateTaskOptions | null | undefined;
55
}
56

57
export interface DeleteTaskMenuItemOptions extends GanttContextMenuBaseItemOptions {
58
  readonly onDeleteTask: (context: GanttContextMenuExtensionContext) => void;
59
  readonly confirm?: (context: GanttContextMenuExtensionContext) => boolean;
60
}
61

62
export interface AssignResourceMenuItemOptions extends GanttContextMenuBaseItemOptions {
63
  readonly onAssignResource: (
64
    context: GanttContextMenuExtensionContext,
65
  ) => void;
66
}
67

68
export interface ExportMenuItemOptions extends GanttContextMenuBaseItemOptions {
69
  readonly exportOptions?:
70
    | ExportExcelEvent
71
    | ((
72
        context: GanttContextMenuExtensionContext,
73
      ) => ExportExcelEvent | undefined);
74
}
75

76
export function createDuplicateTaskMenuItem(
77
  options: DuplicateTaskMenuItemOptions = {},
78
): ContextMenuItem {
79
  return createMenuItem(options, {
80
    name: options.name ?? 'Duplicate',
81
    action: (context) => {
82
      const createOptions =
83
        options.createTaskOptions?.(context) ??
84
        createDuplicateTaskOptions(context, options.copyName);
85

86
      if (!createOptions) {
87
        return;
88
      }
89

90
      dispatchGridEvent(
91
        context.revogrid,
92
        GANTT_TASK_CREATE_EVENT,
93
        createOptions,
94
      );
95
    },
96
  });
97
}
98

99
export function createDeleteTaskMenuItem(
100
  options: DeleteTaskMenuItemOptions,
101
): ContextMenuItem {
102
  return createMenuItem(options, {
103
    name: options.name ?? 'Delete',
104
    action: (context) => {
105
      if (!context.taskId) {
106
        return;
107
      }
108

109
      if (options.confirm && !options.confirm(context)) {
110
        return;
111
      }
112

113
      options.onDeleteTask(context);
114
    },
115
  });
116
}
117

118
export function createAssignResourceMenuItem(
119
  options: AssignResourceMenuItemOptions,
120
): ContextMenuItem {
121
  return createMenuItem(options, {
122
    name: options.name ?? 'Assign resource',
123
    action: (context) => {
124
      if (!context.taskId) {
125
        return;
126
      }
127

128
      options.onAssignResource(context);
129
    },
130
  });
131
}
132

133
export function createExportMenuItem(
134
  options: ExportMenuItemOptions = {},
135
): ContextMenuItem {
136
  return {
137
    ...createMenuItem(
138
      { ...options, icon: options.icon ?? exportIcon },
139
      {
140
        name: options.name ?? 'Export Gantt',
141
        action: (context) => {
142
          const detail =
143
            typeof options.exportOptions === 'function'
144
              ? options.exportOptions(context)
145
              : options.exportOptions;
146

147
          dispatchGridEvent(
148
            context.revogrid,
149
            EXCEL_EXPORT_EVENT,
150
            detail ?? { sheetName: 'Gantt' },
151
          );
152
        },
153
      },
154
    ),
155
    title: typeof options.name === 'string' ? options.name : 'Export Gantt',
156
  };
157
}
158

159
export function createGanttContextMenuExtensionItems(options: {
160
  readonly duplicate?: DuplicateTaskMenuItemOptions | false;
161
  readonly delete?: DeleteTaskMenuItemOptions | false;
162
  readonly assignResource?: AssignResourceMenuItemOptions | false;
163
  readonly export?: ExportMenuItemOptions | false;
164
}): ContextMenuItem[] {
165
  return [
166
    options.duplicate === false
167
      ? null
168
      : createDuplicateTaskMenuItem(options.duplicate),
169
    options.delete === false || !options.delete
170
      ? null
171
      : createDeleteTaskMenuItem(options.delete),
172
    options.assignResource === false || !options.assignResource
173
      ? null
174
      : createAssignResourceMenuItem(options.assignResource),
175
    options.export === false ? null : createExportMenuItem(options.export),
176
  ].filter((item): item is ContextMenuItem => item !== null);
177
}
178

179
function createMenuItem(
180
  options: GanttContextMenuBaseItemOptions,
181
  defaults: {
182
    readonly name: ContextMenuItem['name'];
183
    readonly action: (context: GanttContextMenuExtensionContext) => void;
184
  },
185
): ContextMenuItem {
186
  return {
187
    name: defaults.name,
188
    class: options.class,
189
    rowClass: options.rowClass,
190
    icon: options.icon,
191
    hidden: options.hidden,
192
    keepOpen: options.keepOpen,
193
    action: (event, focused, range, close, actionContext) => {
194
      const context = createExtensionContext(
195
        event,
196
        focused,
197
        range,
198
        close,
199
        actionContext,
200
      );
201

202
      if (!context) {
203
        return;
204
      }
205

206
      defaults.action(context);
207
    },
208
  };
209
}
210

211
function createExtensionContext(
212
  event: MouseEvent,
213
  focused: Cell | null | undefined,
214
  range: RangeArea | null | undefined,
215
  close: (() => void) | undefined,
216
  actionContext: ContextMenuActionContext | undefined,
217
): GanttContextMenuExtensionContext | null {
218
  if (!actionContext) {
219
    return null;
220
  }
221

222
  const task = getFocusedTask(focused, actionContext.providers);
223

224
  return {
225
    event,
226
    focused,
227
    range,
228
    close,
229
    revogrid: actionContext.revogrid,
230
    providers: actionContext.providers,
231
    taskId: typeof task?.id === 'string' ? task.id : null,
232
    task,
233
  };
234
}
235

236
function getFocusedTask(
237
  focused: Cell | null | undefined,
238
  providers: PluginProviders,
239
): Partial<TaskEntity> | null {
240
  if (!focused) {
241
    return null;
242
  }
243

244
  const model = providers.data.getModel?.(focused.y, 'rgRow') as
245
    | Partial<TaskEntity>
246
    | undefined;
247

248
  return typeof model?.id === 'string' ? model : null;
249
}
250

251
function createDuplicateTaskOptions(
252
  context: GanttContextMenuExtensionContext,
253
  copyName?: (
254
    task: Partial<TaskEntity>,
255
    context: GanttContextMenuExtensionContext,
256
  ) => string,
257
): GanttCreateTaskOptions | null {
258
  if (!context.taskId || !context.task) {
259
    return null;
260
  }
261

262
  return {
263
    parentId: context.task.parentId,
264
    insertAfterTaskId: context.taskId,
265
    startDate: context.task.startDate,
266
    endDate: context.task.endDate,
267
    name:
268
      copyName?.(context.task, context) ??
269
      `${context.task.name ?? 'Task'} copy`,
270
  };
271
}
272

273
function dispatchGridEvent<T>(
274
  revogrid: HTMLRevoGridElement,
275
  eventName: string,
276
  detail: T,
277
): void {
278
  revogrid.dispatchEvent(
279
    new CustomEvent(eventName, {
280
      detail,
281
      bubbles: true,
282
    }),
283
  );
284
}

EditingDiagnostics

Feature helper examples

Role editability, task editor fields, popover models, and diagnostics summaries.

examples/components/src/components/gantt/recipes/feature-helper-examples.ts

Open preview

Source code

1
/**
2
 * @packageDocumentation
3
 * Grouped example API for Gantt editing, validation, diagnostics, and popovers.
4
 *
5
 * These recipes show how to combine the small quick-win helpers into
6
 * application-facing wiring: role-based before-change guards, custom task
7
 * editor forms, task detail popover models, dependency validation summaries,
8
 * resource over-allocation summaries, and composed task validation handlers.
9
 */
10
import {
11
  GANTT_BEFORE_ASSIGNMENT_CHANGE_EVENT,
12
  GANTT_BEFORE_DEPENDENCY_CHANGE_EVENT,
13
  GANTT_BEFORE_TASK_CHANGE_EVENT,
14
  type GanttBeforeAssignmentChangeDetail,
15
  type GanttBeforeDependencyChangeDetail,
16
  type GanttBeforeTaskChangeDetail,
17
} from '@revolist/gantt';
18
import type {
19
  AssignmentEntity,
20
  ResourceEntity,
21
  TaskEntity,
22
  TaskId,
23
  TaskUpdate,
24
} from '@revolist/gantt';
25
import type { SchedulerConflict, SchedulerIssue } from '@revolist/gantt';
26
import type { ResourcePlanningRowData, GanttGridRow } from '@revolist/gantt';
27
import {
28
  createGanttRoleEditabilityHelpers,
29
  type GanttBeforeChangeDetailByEventName,
30
  type GanttBeforeChangeEventName,
31
  type GanttRoleEditabilityContext,
32
  type GanttRoleEditabilityPolicy,
33
} from '@revolist/gantt';
34
import {
35
  TASK_EDITOR_FIELD_SCHEMA,
36
  createTaskEditorFormValues,
37
  normalizeTaskEditorSubmit,
38
  type NormalizeTaskEditorSubmitOptions,
39
  type TaskEditorFieldId,
40
  type TaskEditorFieldSchema,
41
  type TaskEditorFormValues,
42
  type TaskEditorSubmitResult,
43
} from '@revolist/gantt';
44
import {
45
  createTaskDetailPopoverModel,
46
  type TaskDetailPopoverModel,
47
} from '@revolist/gantt';
48
import {
49
  buildDependencyValidationSummary,
50
  type DependencyValidationSummary,
51
  type DependencyValidationSummaryInput,
52
} from '@revolist/gantt';
53
import {
54
  buildResourceOverallocationSummary,
55
  type ResourceOverallocationSummary,
56
  type ResourceOverallocationSummaryInput,
57
  type ResourceOverallocationLoadSummary,
58
} from '@revolist/gantt';
59
import {
60
  createApprovalGateValidator,
61
  createForbiddenDateRangeValidator,
62
  createGanttBeforeTaskChangeValidationHandler,
63
  createLockedPhaseValidator,
64
  createRoleGuardValidator,
65
  validateGanttBeforeTaskChange,
66
  type GanttBeforeTaskChangeValidator,
67
  type GanttDateRange,
68
  type GanttValidationContext,
69
  type GanttValidationDecision,
70
  type GanttValidationReject,
71
} from './validation-recipes';
72

73
export interface GanttExampleCancelableEvent<TDetail> {
74
  readonly detail: TDetail;
75
  preventDefault(): void;
76
}
77

78
export interface GanttRoleBasedEditabilityRecipeOptions {
79
  readonly policy?: GanttRoleEditabilityPolicy;
80
  readonly getRoleContext: () => GanttRoleEditabilityContext;
81
  readonly onDeny?: (
82
    eventName: GanttBeforeChangeEventName,
83
    detail: GanttBeforeChangeDetailByEventName[GanttBeforeChangeEventName],
84
  ) => void;
85
}
86

87
export interface GanttRoleBasedEditabilityRecipe {
88
  readonly policy: GanttRoleEditabilityPolicy;
89
  readonly handlers: {
90
    readonly [GANTT_BEFORE_TASK_CHANGE_EVENT]: (
91
      event: GanttExampleCancelableEvent<GanttBeforeTaskChangeDetail>,
92
    ) => void;
93
    readonly [GANTT_BEFORE_DEPENDENCY_CHANGE_EVENT]: (
94
      event: GanttExampleCancelableEvent<GanttBeforeDependencyChangeDetail>,
95
    ) => void;
96
    readonly [GANTT_BEFORE_ASSIGNMENT_CHANGE_EVENT]: (
97
      event: GanttExampleCancelableEvent<GanttBeforeAssignmentChangeDetail>,
98
    ) => void;
99
  };
100
  readonly canEdit: <TEventName extends GanttBeforeChangeEventName>(
101
    eventName: TEventName,
102
    detail: Pick<GanttBeforeChangeDetailByEventName[TEventName], 'action'>,
103
  ) => boolean;
104
}
105

106
export interface CustomTaskEditorRecipeOptions {
107
  readonly task: TaskEntity;
108
  readonly resources?: readonly ResourceEntity[];
109
  readonly assignments?: readonly AssignmentEntity[];
110
  readonly fieldIds?: readonly TaskEditorFieldId[];
111
  readonly includeUnchanged?: boolean;
112
  readonly onSubmitPatch?: (patch: TaskUpdate) => void;
113
}
114

115
export interface CustomTaskEditorRecipe {
116
  readonly fields: readonly TaskEditorFieldSchema[];
117
  readonly initialValues: TaskEditorFormValues;
118
  readonly submit: (
119
    values: TaskEditorFormValues,
120
    options?: NormalizeTaskEditorSubmitOptions,
121
  ) => TaskEditorSubmitResult;
122
}
123

124
export interface TaskDetailPopoverRecipeOptions {
125
  readonly row: GanttGridRow;
126
  readonly task?: TaskEntity;
127
  readonly resources?: readonly ResourceEntity[];
128
  readonly assignments?: readonly AssignmentEntity[];
129
}
130

131
export interface TaskDetailPopoverRecipe {
132
  readonly model: TaskDetailPopoverModel;
133
  readonly sectionTitles: readonly string[];
134
  readonly warningMessages: readonly string[];
135
}
136

137
export interface DependencyValidationSummaryRecipe {
138
  readonly summary: DependencyValidationSummary;
139
  readonly hasBlockingConflicts: boolean;
140
  readonly badgeLabel: string;
141
  readonly focusTaskIds: readonly TaskId[];
142
}
143

144
export interface ResourceOverallocationSummaryRecipe {
145
  readonly summary: ResourceOverallocationSummary;
146
  readonly hasOverallocations: boolean;
147
  readonly badgeLabel: string;
148
  readonly worstResourceId: string | null;
149
}
150

151
export interface CustomValidationRecipeOptions {
152
  readonly context: GanttValidationContext | (() => GanttValidationContext);
153
  readonly rolePolicy?: GanttRoleEditabilityPolicy;
154
  readonly freezeWindows?: readonly GanttDateRange[];
155
  readonly lockedPhaseIds?: readonly string[];
156
  readonly phaseByTaskId?: Readonly<Record<TaskId, string>>;
157
  readonly validators?: readonly GanttBeforeTaskChangeValidator<GanttValidationContext>[];
158
  readonly onReject?: (rejection: GanttValidationReject) => void;
159
}
160

161
export interface CustomValidationRecipe {
162
  readonly validators: readonly GanttBeforeTaskChangeValidator<GanttValidationContext>[];
163
  readonly handler: (
164
    event: GanttExampleCancelableEvent<GanttBeforeTaskChangeDetail>,
165
  ) => void;
166
  readonly validate: (
167
    detail: GanttBeforeTaskChangeDetail,
168
  ) => GanttValidationDecision;
169
}
170

171
const DEFAULT_ROLE_POLICY: GanttRoleEditabilityPolicy = {
172
  roles: {
173
    viewer: [],
174
    planner: ['task:*', 'dependency:create', 'dependency:delete'],
175
    resourceManager: ['assignment:edit'],
176
    admin: ['*'],
177
  },
178
};
179

180
const DEFAULT_EDITOR_FIELDS: readonly TaskEditorFieldId[] = [
181
  'name',
182
  'startDate',
183
  'endDate',
184
  'duration',
185
  'progressPercent',
186
  'constraintType',
187
  'constraintDate',
188
  'deadlineDate',
189
  'resourceLabels',
190
  'notes',
191
];
192

193
/**
194
 * Recipe: attach these handlers to the three cancelable Gantt before-change events.
195
 * The app owns role lookup; the helper only turns roles into deterministic decisions.
196
 */
197
export function createRoleBasedEditabilityRecipe(
198
  options: GanttRoleBasedEditabilityRecipeOptions,
199
): GanttRoleBasedEditabilityRecipe {
200
  const policy = options.policy ?? DEFAULT_ROLE_POLICY;
201
  const editability = createGanttRoleEditabilityHelpers(policy);
202

203
  function handle<TEventName extends GanttBeforeChangeEventName>(
204
    eventName: TEventName,
205
    event: GanttExampleCancelableEvent<
206
      GanttBeforeChangeDetailByEventName[TEventName]
207
    >,
208
  ): void {
209
    if (editability.decide(eventName, event.detail, options.getRoleContext())) {
210
      return;
211
    }
212

213
    event.preventDefault();
214
    options.onDeny?.(eventName, event.detail);
215
  }
216

217
  return {
218
    policy,
219
    handlers: {
220
      [GANTT_BEFORE_TASK_CHANGE_EVENT]: (event) =>
221
        handle(GANTT_BEFORE_TASK_CHANGE_EVENT, event),
222
      [GANTT_BEFORE_DEPENDENCY_CHANGE_EVENT]: (event) =>
223
        handle(GANTT_BEFORE_DEPENDENCY_CHANGE_EVENT, event),
224
      [GANTT_BEFORE_ASSIGNMENT_CHANGE_EVENT]: (event) =>
225
        handle(GANTT_BEFORE_ASSIGNMENT_CHANGE_EVENT, event),
226
    },
227
    canEdit: (eventName, detail) =>
228
      editability.decide(eventName, detail, options.getRoleContext()),
229
  };
230
}
231

232
/**
233
 * Recipe: use the schema to render any UI form, then normalize submitted values
234
 * into the task mutation patch expected by Gantt task services.
235
 */
236
export function createCustomTaskEditorFormRecipe(
237
  options: CustomTaskEditorRecipeOptions,
238
): CustomTaskEditorRecipe {
239
  const fieldIds = new Set(options.fieldIds ?? DEFAULT_EDITOR_FIELDS);
240
  const fields = TASK_EDITOR_FIELD_SCHEMA.filter((field) =>
241
    fieldIds.has(field.id),
242
  );
243
  const initialValues = createTaskEditorFormValues(
244
    options.task,
245
    options.resources,
246
    options.assignments,
247
  );
248

249
  return {
250
    fields,
251
    initialValues,
252
    submit: (values, submitOptions) => {
253
      const result = normalizeTaskEditorSubmit(options.task, values, {
254
        includeUnchanged:
255
          submitOptions?.includeUnchanged ?? options.includeUnchanged,
256
      });
257

258
      if (result.ok) {
259
        options.onSubmitPatch?.(result.patch);
260
      }
261

262
      return result;
263
    },
264
  };
265
}
266

267
/**
268
 * Recipe: resolve the presentation-free popover model at hover/focus time and
269
 * let the framework render sections, fields, warnings, and resource assignments.
270
 */
271
export function createTaskDetailPopoverRecipe(
272
  options: TaskDetailPopoverRecipeOptions,
273
): TaskDetailPopoverRecipe {
274
  const model = createTaskDetailPopoverModel(options);
275
  const warnings =
276
    model.sections
277
      .find((section) => section.id === 'warnings')
278
      ?.fields.flatMap((field) =>
279
        Array.isArray(field.value) ? field.value : [field.displayValue],
280
      )
281
      .filter(Boolean) ?? [];
282

283
  return {
284
    model,
285
    sectionTitles: model.sections.map((section) => section.title),
286
    warningMessages: warnings,
287
  };
288
}
289

290
/**
291
 * Recipe: combine scheduler diagnostics and projected row warnings into one
292
 * compact dependency-health object for side panels, badges, or command palettes.
293
 */
294
export function createDependencyValidationSummaryRecipe(
295
  input: DependencyValidationSummaryInput,
296
): DependencyValidationSummaryRecipe {
297
  const summary = buildDependencyValidationSummary(input);
298
  const focusTaskIds = [
299
    ...new Set(
300
      summary.groups.flatMap((group) =>
301
        group.items.flatMap((item) => item.relatedTaskIds),
302
      ),
303
    ),
304
  ];
305

306
  return {
307
    summary,
308
    hasBlockingConflicts: summary.conflictCount > 0,
309
    badgeLabel:
310
      summary.totalCount === 0
311
        ? 'No schedule issues'
312
        : `${summary.totalCount} schedule issues`,
313
    focusTaskIds,
314
  };
315
}
316

317
/**
318
 * Recipe: feed either projected resource rows, raw load summaries, or scheduler
319
 * conflicts into a summary object that a resource dashboard can render.
320
 */
321
export function createResourceOverallocationSummaryRecipe(
322
  input: ResourceOverallocationSummaryInput,
323
): ResourceOverallocationSummaryRecipe {
324
  const summary = buildResourceOverallocationSummary(input);
325

326
  return {
327
    summary,
328
    hasOverallocations: summary.totalCount > 0,
329
    badgeLabel:
330
      summary.totalCount === 0
331
        ? 'No over-allocation'
332
        : `${summary.totalCount} over-allocation windows`,
333
    worstResourceId: summary.groups[0]?.resourceId ?? null,
334
  };
335
}
336

337
/**
338
 * Recipe: compose custom before-task-change validation from small validators.
339
 * Add this handler to `gantt-before-task-change` and render `onReject` however
340
 * the app reports validation failures.
341
 */
342
export function createCustomValidationRecipe(
343
  options: CustomValidationRecipeOptions,
344
): CustomValidationRecipe {
345
  const configuredValidators: GanttBeforeTaskChangeValidator<GanttValidationContext>[] =
346
    [];
347

348
  if (options.rolePolicy) {
349
    configuredValidators.push(
350
      createRoleGuardValidator({ policy: options.rolePolicy }),
351
    );
352
  }
353

354
  if (options.freezeWindows?.length) {
355
    configuredValidators.push(
356
      createForbiddenDateRangeValidator({ ranges: options.freezeWindows }),
357
    );
358
  }
359

360
  if (options.lockedPhaseIds?.length) {
361
    configuredValidators.push(
362
      createLockedPhaseValidator({
363
        lockedPhaseIds: options.lockedPhaseIds,
364
        getPhaseId: (detail) =>
365
          detail.taskId ? options.phaseByTaskId?.[detail.taskId] : null,
366
      }),
367
    );
368
  }
369

370
  configuredValidators.push(createApprovalGateValidator());
371
  configuredValidators.push(...(options.validators ?? []));
372

373
  const resolveContext = (): GanttValidationContext =>
374
    typeof options.context === 'function'
375
      ? (options.context as () => GanttValidationContext)()
376
      : options.context;
377

378
  return {
379
    validators: configuredValidators,
380
    handler: (event) => {
381
      createGanttBeforeTaskChangeValidationHandler({
382
        context: resolveContext,
383
        validators: configuredValidators,
384
        onReject: options.onReject,
385
      })(event as CustomEvent<GanttBeforeTaskChangeDetail>);
386
    },
387
    validate: (detail) =>
388
      validateGanttBeforeTaskChange(
389
        detail,
390
        resolveContext(),
391
        configuredValidators,
392
      ),
393
  };
394
}
395

396
export function createResourceLoadSummaryExample(
397
  resourceId: string,
398
  resourceName: string,
399
  planning: ResourcePlanningRowData,
400
): ResourceOverallocationLoadSummary {
401
  return {
402
    resourceId,
403
    resourceName,
404
    planning,
405
  };
406
}
407

408
export function createSchedulerDiagnosticsExample(
409
  conflicts: readonly SchedulerConflict[] = [],
410
  issues: readonly SchedulerIssue[] = [],
411
): DependencyValidationSummaryInput {
412
  return {
413
    conflicts,
414
    issues,
415
  };
416
}

GraphQLPersistence

GraphQL adapter

Configurable project snapshot load/save operations over a GraphQL endpoint.

examples/components/src/components/gantt/recipes/graphql-adapter.ts

Open preview

Source code

1
/**
2
 * @packageDocumentation
3
 * GraphQL persistence adapter example for Gantt project snapshots.
4
 *
5
 * The adapter wraps configurable GraphQL load and save operations around the
6
 * JSON project snapshot helpers. It accepts an injected `fetch` implementation
7
 * for tests, SSR, and framework adapters, and converts HTTP, GraphQL, response,
8
 * network, and snapshot-validation failures into typed adapter errors.
9
 */
10
import type { ProjectSnapshot } from '@revolist/gantt';
11
import {
12
  exportProjectSnapshot,
13
  parseProjectSnapshotJson,
14
} from '@revolist/gantt';
15

16
export type ProjectSnapshotGraphqlErrorCode =
17
  | 'GRAPHQL_ERROR'
18
  | 'HTTP_ERROR'
19
  | 'INVALID_RESPONSE'
20
  | 'INVALID_SNAPSHOT'
21
  | 'NETWORK_ERROR';
22

23
export interface ProjectSnapshotGraphqlErrorDetails {
24
  readonly status?: number;
25
  readonly payload?: unknown;
26
  readonly cause?: unknown;
27
}
28

29
export class ProjectSnapshotGraphqlError extends Error {
30
  constructor(
31
    public readonly code: ProjectSnapshotGraphqlErrorCode,
32
    message: string,
33
    public readonly details: ProjectSnapshotGraphqlErrorDetails = {},
34
  ) {
35
    super(message);
36
    this.name = 'ProjectSnapshotGraphqlError';
37
  }
38
}
39

40
export interface ProjectSnapshotGraphqlAdapterOptions {
41
  /** GraphQL HTTP endpoint. */
42
  readonly url: string;
43
  /** Optional headers for authentication, tenancy, or content negotiation. */
44
  readonly headers?: Readonly<Record<string, string>>;
45
  /** Custom fetch implementation for tests, SSR, or framework adapters. */
46
  readonly fetchImpl?: typeof fetch;
47
  /** JSON indentation used for readable save payloads. */
48
  readonly space?: number | string;
49
  /** Query used by load(). Must return a serialized project snapshot string. */
50
  readonly loadQuery?: string;
51
  /** Mutation used by save(). Receives the serialized snapshot in `$snapshot`. */
52
  readonly saveMutation?: string;
53
  /** Response data field read by load(). */
54
  readonly loadField?: string;
55
  /** Response data field checked by save(). */
56
  readonly saveField?: string;
57
}
58

59
export interface ProjectSnapshotGraphqlRequestOptions {
60
  readonly signal?: AbortSignal;
61
  readonly variables?: Readonly<Record<string, unknown>>;
62
}
63

64
interface GraphqlResponsePayload {
65
  readonly data?: Record<string, unknown> | null;
66
  readonly errors?: unknown;
67
}
68

69
const DEFAULT_LOAD_QUERY = `
70
  query LoadProjectSnapshot {
71
    projectSnapshot
72
  }
73
`;
74

75
const DEFAULT_SAVE_MUTATION = `
76
  mutation SaveProjectSnapshot($snapshot: String!) {
77
    saveProjectSnapshot(snapshot: $snapshot)
78
  }
79
`;
80

81
/**
82
 * Framework-neutral example for persisting project snapshots through GraphQL.
83
 */
84
export class ProjectSnapshotGraphqlAdapter {
85
  private readonly fetchImpl: typeof fetch;
86

87
  constructor(private readonly options: ProjectSnapshotGraphqlAdapterOptions) {
88
    this.fetchImpl = options.fetchImpl ?? fetch;
89
  }
90

91
  async load(
92
    request: ProjectSnapshotGraphqlRequestOptions = {},
93
  ): Promise<ProjectSnapshot> {
94
    const payload = await this.execute({
95
      query: this.options.loadQuery ?? DEFAULT_LOAD_QUERY,
96
      variables: request.variables,
97
      signal: request.signal,
98
    });
99
    const field = this.options.loadField ?? 'projectSnapshot';
100
    const snapshotJson = payload.data?.[field];
101

102
    if (typeof snapshotJson !== 'string') {
103
      throw new ProjectSnapshotGraphqlError(
104
        'INVALID_RESPONSE',
105
        'Project snapshot GraphQL response did not include a serialized snapshot.',
106
        { payload },
107
      );
108
    }
109

110
    const parsed = parseProjectSnapshotJson(snapshotJson);
111

112
    if (parsed.ok === false) {
113
      throw new ProjectSnapshotGraphqlError('INVALID_SNAPSHOT', parsed.error, {
114
        payload: snapshotJson,
115
      });
116
    }
117

118
    return parsed.project;
119
  }
120

121
  async save(
122
    project: ProjectSnapshot,
123
    request: ProjectSnapshotGraphqlRequestOptions = {},
124
  ): Promise<void> {
125
    const snapshot = exportProjectSnapshot(project, {
126
      space: this.options.space,
127
    });
128
    const payload = await this.execute({
129
      query: this.options.saveMutation ?? DEFAULT_SAVE_MUTATION,
130
      variables: {
131
        ...request.variables,
132
        snapshot,
133
      },
134
      signal: request.signal,
135
    });
136
    const field = this.options.saveField ?? 'saveProjectSnapshot';
137

138
    if (
139
      payload.data &&
140
      field in payload.data &&
141
      payload.data[field] === false
142
    ) {
143
      throw new ProjectSnapshotGraphqlError(
144
        'INVALID_RESPONSE',
145
        'Project snapshot GraphQL save operation was rejected.',
146
        { payload },
147
      );
148
    }
149
  }
150

151
  private async execute(request: {
152
    readonly query: string;
153
    readonly variables?: Readonly<Record<string, unknown>>;
154
    readonly signal?: AbortSignal;
155
  }): Promise<GraphqlResponsePayload> {
156
    const response = await this.request(() =>
157
      this.fetchImpl(this.options.url, {
158
        method: 'POST',
159
        headers: {
160
          'content-type': 'application/json',
161
          ...this.options.headers,
162
        },
163
        body: JSON.stringify({
164
          query: request.query,
165
          variables: request.variables ?? {},
166
        }),
167
        signal: request.signal,
168
      }),
169
    );
170

171
    const payload = await this.readPayload(response);
172

173
    if (!response.ok) {
174
      throw new ProjectSnapshotGraphqlError(
175
        'HTTP_ERROR',
176
        'Project snapshot GraphQL request returned an error.',
177
        {
178
          status: response.status,
179
          payload,
180
        },
181
      );
182
    }
183

184
    if (payload.errors) {
185
      throw new ProjectSnapshotGraphqlError(
186
        'GRAPHQL_ERROR',
187
        'Project snapshot GraphQL operation returned errors.',
188
        { payload },
189
      );
190
    }
191

192
    return payload;
193
  }
194

195
  private async request(run: () => Promise<Response>): Promise<Response> {
196
    try {
197
      return await run();
198
    } catch (error) {
199
      throw new ProjectSnapshotGraphqlError(
200
        'NETWORK_ERROR',
201
        'Project snapshot GraphQL request failed.',
202
        {
203
          cause: error,
204
        },
205
      );
206
    }
207
  }
208

209
  private async readPayload(
210
    response: Response,
211
  ): Promise<GraphqlResponsePayload> {
212
    const text = await response.text();
213

214
    if (!text) {
215
      return {};
216
    }
217

218
    try {
219
      const payload = JSON.parse(text) as GraphqlResponsePayload;
220

221
      if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
222
        throw new Error('GraphQL response must be a JSON object.');
223
      }
224

225
      return payload;
226
    } catch (error) {
227
      throw new ProjectSnapshotGraphqlError(
228
        'INVALID_RESPONSE',
229
        'Project snapshot GraphQL response could not be parsed.',
230
        {
231
          status: response.status,
232
          payload: text,
233
          cause: error,
234
        },
235
      );
236
    }
237
  }
238
}

GridExport

Grid projection examples

Column presets, Excel row mapping, status indicators, and menu composition.

examples/components/src/components/gantt/recipes/grid-projection-examples.ts

Open preview

Source code

1
/**
2
 * @packageDocumentation
3
 * Grouped example API for grid, export, rendering, and context-menu quick wins.
4
 *
5
 * The recipes demonstrate how an application can map projected Gantt rows to
6
 * spreadsheet-safe exports, choose packaged Gantt column presets, derive
7
 * read-only/locked task indicator metadata, and compose context-menu actions
8
 * without depending on internal projection details.
9
 */
10
import type { ColumnRegular } from '@revolist/revogrid';
11
import type { ContextMenuItem } from '@revolist/revogrid-pro';
12

13
import type { ProjectSnapshot, TaskId } from '@revolist/gantt';
14
import {
15
  mapGanttRowsToExcelExport,
16
  type GanttExcelExportRow,
17
  type GanttExcelMappingOptions,
18
} from '@revolist/gantt';
19
import {
20
  printGanttContainer,
21
  type GanttPrintDateRange,
22
  type GanttPrintOptions,
23
  type GanttPrintResult,
24
} from './print-pdf-recipe';
25
import {
26
  createGanttColumnPreset,
27
  getGanttColumnPresetProps,
28
  type GanttColumnPresetName,
29
  type GanttColumnPresetProp,
30
} from '@revolist/gantt';
31
import {
32
  exportGanttExcel,
33
  type GanttExcelExportOptions,
34
} from '@revolist/gantt';
35
import {
36
  createTaskStatusIndicators,
37
  type TaskStatusIndicatorProjection,
38
} from '@revolist/gantt';
39
import type { GanttGridRow } from '@revolist/gantt';
40
import {
41
  createGanttContextMenuExtensionItems,
42
  type AssignResourceMenuItemOptions,
43
  type DeleteTaskMenuItemOptions,
44
  type DuplicateTaskMenuItemOptions,
45
  type ExportMenuItemOptions,
46
  type GanttContextMenuExtensionContext,
47
} from '@revolist/gantt';
48

49
export interface GanttExcelExportRecipeOptions extends GanttExcelMappingOptions {
50
  readonly rows: readonly GanttGridRow[];
51
  readonly project: ProjectSnapshot;
52
}
53

54
export interface GanttExcelExportRecipe {
55
  readonly rows: readonly GanttExcelExportRow[];
56
  readonly fieldNames: readonly (keyof GanttExcelExportRow)[];
57
}
58

59
export interface GanttPdfExcelReportingRecipeOptions {
60
  readonly grid: HTMLRevoGridElement;
61
  readonly target: Element | null | undefined;
62
  readonly document?: Document;
63
  readonly window?: GanttPrintOptions['window'];
64
  readonly now?: () => Date | string;
65
  readonly pdf?: Omit<GanttPrintOptions, 'document' | 'window' | 'metadata'>;
66
  readonly excel?: GanttExcelExportOptions;
67
}
68

69
export interface GanttPdfExcelReportingExportOptions {
70
  readonly range?: GanttPrintDateRange;
71
  readonly excel?: GanttExcelExportOptions;
72
}
73

74
export interface GanttPdfExcelReportingRecipe {
75
  exportPdf(
76
    project: ProjectSnapshot,
77
    range?: GanttPrintDateRange,
78
  ): GanttPrintResult;
79
  exportExcel(
80
    options?: GanttExcelExportOptions,
81
  ): CustomEvent<GanttExcelExportOptions>;
82
  exportReport(
83
    project: ProjectSnapshot,
84
    options?: GanttPdfExcelReportingExportOptions,
85
  ): {
86
    readonly pdf: GanttPrintResult;
87
    readonly excel: CustomEvent<GanttExcelExportOptions>;
88
  };
89
}
90

91
export interface GanttColumnPresetRecipeOptions {
92
  readonly preset: GanttColumnPresetName;
93
  readonly extraColumns?: readonly ColumnRegular[];
94
}
95

96
export interface GanttColumnPresetRecipe {
97
  readonly preset: GanttColumnPresetName;
98
  readonly presetProps: readonly GanttColumnPresetProp[];
99
  readonly columns: readonly ColumnRegular[];
100
}
101

102
export interface GanttTaskStatusIndicatorRecipeOptions {
103
  readonly rows: readonly Pick<GanttGridRow, 'id'>[];
104
  readonly projectReadOnly?: boolean;
105
  readonly lockedTaskIds?: ReadonlySet<TaskId> | readonly TaskId[];
106
  readonly labels?: Parameters<typeof createTaskStatusIndicators>[0]['labels'];
107
  readonly classNames?: Parameters<
108
    typeof createTaskStatusIndicators
109
  >[0]['classNames'];
110
}
111

112
export interface GanttTaskStatusIndicatorRecipeRow {
113
  readonly taskId: TaskId;
114
  readonly status: TaskStatusIndicatorProjection;
115
  readonly className: string;
116
  readonly title: string;
117
  readonly ariaLabel: string | undefined;
118
}
119

120
export interface GanttContextMenuQuickWinRecipeOptions {
121
  readonly duplicate?: DuplicateTaskMenuItemOptions | false;
122
  readonly delete?: DeleteTaskMenuItemOptions | false;
123
  readonly assignResource?: AssignResourceMenuItemOptions | false;
124
  readonly export?: ExportMenuItemOptions | false;
125
}
126

127
const EMPTY_EXCEL_FIELD_NAMES = Object.freeze(
128
  [],
129
) as readonly (keyof GanttExcelExportRow)[];
130

131
/**
132
 * Framework-neutral Excel recipe for customers that export the projected Gantt
133
 * task table instead of serializing renderer-only timeline fields.
134
 */
135
export function createGanttExcelExportRecipe(
136
  options: GanttExcelExportRecipeOptions,
137
): GanttExcelExportRecipe {
138
  const rows = mapGanttRowsToExcelExport(options.rows, options.project, {
139
    includeResourceRows: options.includeResourceRows,
140
  });
141

142
  return {
143
    rows,
144
    fieldNames: rows[0]
145
      ? (Object.keys(rows[0]) as (keyof GanttExcelExportRow)[])
146
      : EMPTY_EXCEL_FIELD_NAMES,
147
  };
148
}
149

150
/**
151
 * Framework-neutral reporting recipe for toolbars that offer both stakeholder
152
 * PDF reports and spreadsheet handoff from the same Gantt grid.
153
 */
154
export function createGanttPdfExcelReportingRecipe(
155
  options: GanttPdfExcelReportingRecipeOptions,
156
): GanttPdfExcelReportingRecipe {
157
  const exportPdf = (
158
    project: ProjectSnapshot,
159
    range?: GanttPrintDateRange,
160
  ): GanttPrintResult =>
161
    printGanttContainer(options.target, {
162
      ...options.pdf,
163
      document: options.document,
164
      window: options.window,
165
      metadata: {
166
        title: project.name,
167
        subtitle: `${project.tasks.length} tasks | ${project.resources.length} resources`,
168
        range,
169
        printedAt: options.now?.() ?? new Date(),
170
      },
171
    });
172
  const exportExcel = (
173
    excelOptions?: GanttExcelExportOptions,
174
  ): CustomEvent<GanttExcelExportOptions> =>
175
    exportGanttExcel(options.grid, {
176
      ...options.excel,
177
      ...excelOptions,
178
    });
179

180
  return {
181
    exportPdf,
182
    exportExcel,
183
    exportReport(project, reportOptions = {}) {
184
      return {
185
        pdf: exportPdf(project, reportOptions.range),
186
        excel: exportExcel(reportOptions.excel),
187
      };
188
    },
189
  };
190
}
191

192
/**
193
 * Framework-neutral column recipe for switching between Gantt-aware presets and
194
 * customer-defined columns before assigning the result to `grid.columns`.
195
 */
196
export function createGanttColumnPresetRecipe(
197
  options: GanttColumnPresetRecipeOptions,
198
): GanttColumnPresetRecipe {
199
  const presetColumns = createGanttColumnPreset(options.preset);
200

201
  return {
202
    preset: options.preset,
203
    presetProps: getGanttColumnPresetProps(options.preset),
204
    columns: [...presetColumns, ...(options.extraColumns ?? [])],
205
  };
206
}
207

208
/**
209
 * Framework-neutral visual-indicator recipe for read-only projects and locked
210
 * tasks. The returned class/title values can be bound to a custom cell renderer
211
 * or status column without changing the projected task row.
212
 */
213
export function createGanttTaskStatusIndicatorRecipe(
214
  options: GanttTaskStatusIndicatorRecipeOptions,
215
): readonly GanttTaskStatusIndicatorRecipeRow[] {
216
  const lockedTaskIds = toTaskIdSet(options.lockedTaskIds);
217

218
  return options.rows.map((row) => {
219
    const status = createTaskStatusIndicators({
220
      taskId: row.id,
221
      projectReadOnly: options.projectReadOnly,
222
      taskLocked: lockedTaskIds.has(row.id),
223
      labels: options.labels,
224
      classNames: options.classNames,
225
    });
226

227
    return {
228
      taskId: row.id,
229
      status,
230
      className: status.classNames.join(' '),
231
      title: status.label,
232
      ariaLabel: status.label || undefined,
233
    };
234
  });
235
}
236

237
/**
238
 * Framework-neutral context-menu recipe for composing the Gantt quick actions
239
 * with RevoGrid Pro's context-menu plugin.
240
 */
241
export function createGanttContextMenuQuickWinRecipe(
242
  options: GanttContextMenuQuickWinRecipeOptions,
243
): readonly ContextMenuItem[] {
244
  return createGanttContextMenuExtensionItems(options);
245
}
246

247
export function createTaskNameExcelExportMenuItem(
248
  workbookName: string,
249
): ContextMenuItem {
250
  return createGanttContextMenuQuickWinRecipe({
251
    duplicate: false,
252
    delete: false,
253
    assignResource: false,
254
    export: {
255
      exportOptions: (context: GanttContextMenuExtensionContext) => ({
256
        sheetName: context.task?.name ?? 'Gantt',
257
        workbookName,
258
      }),
259
    },
260
  })[0];
261
}
262

263
function toTaskIdSet(
264
  taskIds: ReadonlySet<TaskId> | readonly TaskId[] | undefined,
265
): ReadonlySet<TaskId> {
266
  if (!taskIds) {
267
    return new Set();
268
  }
269

270
  return taskIds instanceof Set ? taskIds : new Set(taskIds);
271
}

PersistenceRecipes

Persistence examples

Grouped recipes for REST, GraphQL, PostgreSQL, JSON snapshots, print/PDF, and framework metadata.

examples/components/src/components/gantt/recipes/persistence-examples.ts

Open preview

Source code

1
/**
2
 * @packageDocumentation
3
 * Grouped example API for Gantt persistence, reporting, and framework metadata.
4
 *
5
 * The recipes wrap REST, GraphQL, Supabase/PostgreSQL, JSON snapshot, and print
6
 * helpers with injected state and transport dependencies. They are designed as
7
 * copyable integration patterns for applications that own the backend, file
8
 * picker, print shell, or framework-specific demo catalog.
9
 */
10
import type { ProjectSnapshot } from '@revolist/gantt';
11
import {
12
  cloneProjectSnapshot,
13
  exportProjectSnapshot,
14
  parseProjectSnapshotJson,
15
  type ProjectSnapshotParseResult,
16
} from '@revolist/gantt';
17
import {
18
  ProjectSnapshotGraphqlAdapter,
19
  type ProjectSnapshotGraphqlAdapterOptions,
20
  type ProjectSnapshotGraphqlRequestOptions,
21
} from './graphql-adapter';
22
import {
23
  buildCreateProjectSnapshotTableSql,
24
  buildLoadProjectSnapshotSql,
25
  buildSaveProjectSnapshotSql,
26
  ProjectSnapshotSupabaseAdapter,
27
  type PostgresStatement,
28
  type ProjectSnapshotPostgresOptions,
29
  type ProjectSnapshotPostgresRow,
30
  type SupabaseLikeClient,
31
} from './postgres-persistence';
32
import {
33
  printGanttContainer,
34
  type GanttPrintDateRange,
35
  type GanttPrintOptions,
36
  type GanttPrintResult,
37
} from './print-pdf-recipe';
38
import {
39
  ProjectSnapshotRestAdapter,
40
  type ProjectSnapshotRestAdapterOptions,
41
  type ProjectSnapshotRestRequestOptions,
42
} from './rest-adapter';
43

44
export type GanttPersistenceRecipeId =
45
  | 'rest-project-snapshot'
46
  | 'graphql-project-snapshot'
47
  | 'supabase-postgres-project-snapshot'
48
  | 'postgres-sql-project-snapshot'
49
  | 'print-pdf-export'
50
  | 'json-snapshot-helpers'
51
  | 'portal-svelte-gantt'
52
  | 'portal-resource-filter';
53

54
export type GanttPersistenceRecipeChannel =
55
  | 'persistence'
56
  | 'export'
57
  | 'reporting'
58
  | 'framework';
59

60
export type GanttPersistenceRecipeFramework =
61
  | 'framework-neutral'
62
  | 'svelte'
63
  | 'vanilla';
64

65
export interface GanttPersistenceRecipeMetadata {
66
  readonly id: GanttPersistenceRecipeId;
67
  readonly title: string;
68
  readonly channel: GanttPersistenceRecipeChannel;
69
  readonly frameworks: readonly GanttPersistenceRecipeFramework[];
70
  readonly sourceFiles: readonly string[];
71
  readonly dependencies: readonly string[];
72
  readonly summary: string;
73
}
74

75
export interface ProjectSnapshotState {
76
  getProject(): ProjectSnapshot;
77
  setProject(project: ProjectSnapshot): void;
78
}
79

80
export interface ProjectSnapshotPersistenceRecipe {
81
  readonly metadata: GanttPersistenceRecipeMetadata;
82
  load(
83
    request?:
84
      | ProjectSnapshotRestRequestOptions
85
      | ProjectSnapshotGraphqlRequestOptions,
86
  ): Promise<ProjectSnapshot>;
87
  save(
88
    request?:
89
      | ProjectSnapshotRestRequestOptions
90
      | ProjectSnapshotGraphqlRequestOptions,
91
  ): Promise<void>;
92
}
93

94
export interface ProjectSnapshotStorageRecipe {
95
  readonly metadata: GanttPersistenceRecipeMetadata;
96
  load(projectId: string): Promise<ProjectSnapshot | null>;
97
  save(): Promise<ProjectSnapshot>;
98
}
99

100
export interface ProjectSnapshotSqlExecutor {
101
  query<T>(
102
    statement: PostgresStatement,
103
  ): Promise<{ readonly rows: readonly T[] }>;
104
}
105

106
export interface ProjectSnapshotPostgresRecipe {
107
  readonly metadata: GanttPersistenceRecipeMetadata;
108
  createTable(): Promise<void>;
109
  load(projectId: string): Promise<ProjectSnapshot | null>;
110
  save(): Promise<ProjectSnapshot>;
111
  buildReportingStatement(projectId: string): PostgresStatement;
112
}
113

114
export interface GanttPrintPdfRecipeOptions {
115
  readonly target: Element | null | undefined;
116
  readonly document?: Document;
117
  readonly window?: GanttPrintOptions['window'];
118
  readonly now?: () => Date | string;
119
}
120

121
export interface GanttPrintPdfRecipe {
122
  readonly metadata: GanttPersistenceRecipeMetadata;
123
  exportProject(
124
    project: ProjectSnapshot,
125
    range?: GanttPrintDateRange,
126
  ): GanttPrintResult;
127
}
128

129
export interface ProjectSnapshotJsonRecipeOptions {
130
  readonly readText?: () => string | Promise<string>;
131
  readonly writeText?: (
132
    fileName: string,
133
    contents: string,
134
  ) => void | Promise<void>;
135
  readonly fileName?: (project: ProjectSnapshot) => string;
136
}
137

138
export interface ProjectSnapshotJsonRecipe {
139
  readonly metadata: GanttPersistenceRecipeMetadata;
140
  clone(project: ProjectSnapshot): ProjectSnapshot;
141
  export(project: ProjectSnapshot, space?: number | string): string;
142
  parse(json: string): ProjectSnapshotParseResult;
143
  load(): Promise<ProjectSnapshot>;
144
  save(project: ProjectSnapshot, space?: number | string): Promise<string>;
145
}
146

147
export const GANTT_PERSISTENCE_QUICK_WIN_EXAMPLES: readonly GanttPersistenceRecipeMetadata[] =
148
  [
149
    {
150
      id: 'rest-project-snapshot',
151
      title: 'REST project snapshot persistence',
152
      channel: 'persistence',
153
      frameworks: ['framework-neutral'],
154
      sourceFiles: [
155
        'examples/components/src/components/gantt/recipes/rest-adapter.ts',
156
        'packages/gantt/src/gantt/core/project-snapshot-json.ts',
157
      ],
158
      dependencies: ['fetch'],
159
      summary:
160
        'Loads and saves a serialized ProjectSnapshot through an injected fetch implementation.',
161
    },
162
    {
163
      id: 'graphql-project-snapshot',
164
      title: 'GraphQL project snapshot persistence',
165
      channel: 'persistence',
166
      frameworks: ['framework-neutral'],
167
      sourceFiles: [
168
        'examples/components/src/components/gantt/recipes/graphql-adapter.ts',
169
        'packages/gantt/src/gantt/core/project-snapshot-json.ts',
170
      ],
171
      dependencies: ['fetch'],
172
      summary:
173
        'Uses configurable GraphQL operations and variables to load and save ProjectSnapshot JSON.',
174
    },
175
    {
176
      id: 'supabase-postgres-project-snapshot',
177
      title: 'Supabase/PostgreSQL project snapshot persistence',
178
      channel: 'persistence',
179
      frameworks: ['framework-neutral'],
180
      sourceFiles: [
181
        'examples/components/src/components/gantt/recipes/postgres-persistence.ts',
182
        'packages/gantt/src/gantt/core/project-snapshot-json.ts',
183
      ],
184
      dependencies: ['Supabase-like client'],
185
      summary:
186
        'Persists JSONB snapshots with a minimal Supabase-style client shape.',
187
    },
188
    {
189
      id: 'postgres-sql-project-snapshot',
190
      title: 'PostgreSQL SQL project snapshot persistence',
191
      channel: 'reporting',
192
      frameworks: ['framework-neutral'],
193
      sourceFiles: [
194
        'examples/components/src/components/gantt/recipes/postgres-persistence.ts',
195
      ],
196
      dependencies: ['PostgreSQL query executor'],
197
      summary:
198
        'Builds parameterized DDL, load, save, and reporting SQL without owning the database client.',
199
    },
200
    {
201
      id: 'print-pdf-export',
202
      title: 'Print/PDF export',
203
      channel: 'export',
204
      frameworks: ['framework-neutral', 'vanilla'],
205
      sourceFiles: [
206
        'examples/components/src/components/gantt/recipes/print-pdf-recipe.ts',
207
      ],
208
      dependencies: ['DOM print API'],
209
      summary:
210
        'Prepares a printable Gantt container that users can route to browser print or Save as PDF.',
211
    },
212
    {
213
      id: 'json-snapshot-helpers',
214
      title: 'JSON snapshot helpers',
215
      channel: 'persistence',
216
      frameworks: ['framework-neutral'],
217
      sourceFiles: ['packages/gantt/src/gantt/core/project-snapshot-json.ts'],
218
      dependencies: ['JSON'],
219
      summary:
220
        'Clones, serializes, parses, imports, and exports ProjectSnapshot payloads.',
221
    },
222
    {
223
      id: 'portal-svelte-gantt',
224
      title: 'Portal Svelte Gantt demo',
225
      channel: 'framework',
226
      frameworks: ['svelte'],
227
      sourceFiles: [
228
        'apps/portal/src/components/gantt/GanttSvelteExample.svelte',
229
        'apps/portal/src/components/gantt/GanttSvelteExample.md',
230
      ],
231
      dependencies: ['@revolist/svelte-datagrid'],
232
      summary:
233
        'Existing portal reference showing Gantt usage through the Svelte wrapper.',
234
    },
235
    {
236
      id: 'portal-resource-filter',
237
      title: 'Portal resource filter demo',
238
      channel: 'framework',
239
      frameworks: ['framework-neutral', 'vanilla'],
240
      sourceFiles: [
241
        'apps/portal/src/components/gantt/GanttResourceFilterExample.ts',
242
      ],
243
      dependencies: ['resourceFilterIds'],
244
      summary:
245
        'Existing portal reference for filtering projected Gantt rows by assigned resource IDs.',
246
    },
247
  ];
248

249
export function createRestProjectPersistenceRecipe(
250
  options: ProjectSnapshotRestAdapterOptions,
251
  state: ProjectSnapshotState,
252
): ProjectSnapshotPersistenceRecipe {
253
  const adapter = new ProjectSnapshotRestAdapter(options);
254

255
  return {
256
    metadata: getPersistenceRecipeMetadata('rest-project-snapshot'),
257
    async load(request) {
258
      const project = await adapter.load(
259
        request as ProjectSnapshotRestRequestOptions | undefined,
260
      );
261
      state.setProject(project);
262
      return project;
263
    },
264
    async save(request) {
265
      await adapter.save(
266
        state.getProject(),
267
        request as ProjectSnapshotRestRequestOptions | undefined,
268
      );
269
    },
270
  };
271
}
272

273
export function createGraphqlProjectPersistenceRecipe(
274
  options: ProjectSnapshotGraphqlAdapterOptions,
275
  state: ProjectSnapshotState,
276
): ProjectSnapshotPersistenceRecipe {
277
  const adapter = new ProjectSnapshotGraphqlAdapter(options);
278

279
  return {
280
    metadata: getPersistenceRecipeMetadata('graphql-project-snapshot'),
281
    async load(request) {
282
      const project = await adapter.load(
283
        request as ProjectSnapshotGraphqlRequestOptions | undefined,
284
      );
285
      state.setProject(project);
286
      return project;
287
    },
288
    async save(request) {
289
      await adapter.save(
290
        state.getProject(),
291
        request as ProjectSnapshotGraphqlRequestOptions | undefined,
292
      );
293
    },
294
  };
295
}
296

297
export function createSupabasePostgresPersistenceRecipe(
298
  client: SupabaseLikeClient<ProjectSnapshotPostgresRow>,
299
  state: ProjectSnapshotState,
300
  options: ProjectSnapshotPostgresOptions = {},
301
): ProjectSnapshotStorageRecipe {
302
  const adapter = new ProjectSnapshotSupabaseAdapter(client, options);
303

304
  return {
305
    metadata: getPersistenceRecipeMetadata(
306
      'supabase-postgres-project-snapshot',
307
    ),
308
    async load(projectId) {
309
      const project = await adapter.load(projectId);
310

311
      if (project) {
312
        state.setProject(project);
313
      }
314

315
      return project;
316
    },
317
    async save() {
318
      const project = await adapter.save(state.getProject());
319
      state.setProject(project);
320
      return project;
321
    },
322
  };
323
}
324

325
export function createPostgresSqlPersistenceRecipe(
326
  executor: ProjectSnapshotSqlExecutor,
327
  state: ProjectSnapshotState,
328
  options: ProjectSnapshotPostgresOptions = {},
329
): ProjectSnapshotPostgresRecipe {
330
  return {
331
    metadata: getPersistenceRecipeMetadata('postgres-sql-project-snapshot'),
332
    async createTable() {
333
      await executor.query(buildCreateProjectSnapshotTableSql(options));
334
    },
335
    async load(projectId) {
336
      const result = await executor.query<{ readonly snapshot: unknown }>(
337
        buildLoadProjectSnapshotSql(projectId, options),
338
      );
339
      const snapshot = result.rows[0]?.snapshot;
340

341
      if (snapshot === undefined) {
342
        return null;
343
      }
344

345
      const parsed = parseProjectSnapshotJson(
346
        typeof snapshot === 'string' ? snapshot : JSON.stringify(snapshot),
347
      );
348

349
      if (parsed.ok === false) {
350
        throw new Error(parsed.error);
351
      }
352

353
      state.setProject(parsed.project);
354
      return parsed.project;
355
    },
356
    async save() {
357
      const project = state.getProject();
358
      const result = await executor.query<ProjectSnapshotPostgresRow>(
359
        buildSaveProjectSnapshotSql(project, options),
360
      );
361
      const persisted = result.rows[0]?.snapshot ?? project;
362
      const parsed = parseProjectSnapshotJson(
363
        typeof persisted === 'string' ? persisted : JSON.stringify(persisted),
364
      );
365

366
      if (parsed.ok === false) {
367
        throw new Error(parsed.error);
368
      }
369

370
      state.setProject(parsed.project);
371
      return parsed.project;
372
    },
373
    buildReportingStatement(projectId) {
374
      return {
375
        text: [
376
          'select',
377
          "  snapshot->>'id' as project_id,",
378
          "  snapshot->>'name' as project_name,",
379
          "  jsonb_array_length(snapshot->'tasks') as task_count,",
380
          "  jsonb_array_length(snapshot->'resources') as resource_count,",
381
          "  jsonb_array_length(snapshot->'dependencies') as dependency_count",
382
          `from ${quoteQualifiedIdentifier(options.tableName ?? 'gantt_project_snapshots')}`,
383
          'where project_id = $1;',
384
        ].join('\n'),
385
        values: [projectId],
386
      };
387
    },
388
  };
389
}
390

391
export function createPrintPdfExportRecipe(
392
  options: GanttPrintPdfRecipeOptions,
393
): GanttPrintPdfRecipe {
394
  return {
395
    metadata: getPersistenceRecipeMetadata('print-pdf-export'),
396
    exportProject(project, range) {
397
      return printGanttContainer(options.target, {
398
        document: options.document,
399
        window: options.window,
400
        metadata: {
401
          title: project.name,
402
          subtitle: `${project.tasks.length} tasks | ${project.resources.length} resources`,
403
          range,
404
          printedAt: options.now?.() ?? new Date(),
405
        },
406
      });
407
    },
408
  };
409
}
410

411
export function createJsonSnapshotRecipe(
412
  options: ProjectSnapshotJsonRecipeOptions = {},
413
): ProjectSnapshotJsonRecipe {
414
  return {
415
    metadata: getPersistenceRecipeMetadata('json-snapshot-helpers'),
416
    clone: cloneProjectSnapshot,
417
    export(project, space) {
418
      return exportProjectSnapshot(project, { space });
419
    },
420
    parse: parseProjectSnapshotJson,
421
    async load() {
422
      if (!options.readText) {
423
        throw new Error(
424
          'Project snapshot JSON load requires an injected readText function.',
425
        );
426
      }
427

428
      const parsed = parseProjectSnapshotJson(await options.readText());
429

430
      if (parsed.ok === false) {
431
        throw new Error(parsed.error);
432
      }
433

434
      return parsed.project;
435
    },
436
    async save(project, space) {
437
      if (!options.writeText) {
438
        throw new Error(
439
          'Project snapshot JSON save requires an injected writeText function.',
440
        );
441
      }
442

443
      const contents = exportProjectSnapshot(project, { space });
444
      const fileName =
445
        options.fileName?.(project) ?? `${project.id}-gantt-project.json`;
446

447
      await options.writeText(fileName, contents);
448

449
      return contents;
450
    },
451
  };
452
}
453

454
export function getPersistenceRecipeMetadata(
455
  id: GanttPersistenceRecipeId,
456
): GanttPersistenceRecipeMetadata {
457
  const metadata = GANTT_PERSISTENCE_QUICK_WIN_EXAMPLES.find(
458
    (example) => example.id === id,
459
  );
460

461
  if (!metadata) {
462
    throw new Error(`Unknown Gantt persistence recipe "${id}".`);
463
  }
464

465
  return metadata;
466
}
467

468
function quoteQualifiedIdentifier(identifier: string): string {
469
  const parts = identifier.split('.');
470

471
  if (parts.some((part) => !/^[A-Za-z_][A-Za-z0-9_]*$/.test(part))) {
472
    throw new Error(
473
      `PostgreSQL identifier "${identifier}" is not supported by this example.`,
474
    );
475
  }
476

477
  return parts.map((part) => `"${part}"`).join('.');
478
}

PostgreSQLSupabase

PostgreSQL persistence

SQL builders and a Supabase-style adapter for project snapshot storage.

examples/components/src/components/gantt/recipes/postgres-persistence.ts

Open preview

Source code

1
/**
2
 * @packageDocumentation
3
 * PostgreSQL and Supabase-style persistence example for Gantt project snapshots.
4
 *
5
 * The module provides parameterized SQL builders for a JSONB snapshot table and
6
 * a small Supabase-like adapter shape. It intentionally avoids importing a
7
 * concrete database client so applications can use the same snapshot contract
8
 * with Supabase, node-postgres, serverless SQL clients, or tests.
9
 */
10
import type { ProjectSnapshot } from '@revolist/gantt';
11
import {
12
  exportProjectSnapshot,
13
  parseProjectSnapshotJson,
14
} from '@revolist/gantt';
15

16
export const PROJECT_SNAPSHOT_TABLE = 'gantt_project_snapshots';
17

18
export interface PostgresStatement {
19
  readonly text: string;
20
  readonly values: readonly unknown[];
21
}
22

23
export interface ProjectSnapshotPostgresOptions {
24
  readonly tableName?: string;
25
}
26

27
export interface ProjectSnapshotPostgresRow {
28
  readonly project_id: string;
29
  readonly version: string;
30
  readonly snapshot: unknown;
31
  readonly updated_at: string;
32
}
33

34
export type ProjectSnapshotPostgresErrorCode =
35
  | 'INVALID_IDENTIFIER'
36
  | 'INVALID_SNAPSHOT'
37
  | 'QUERY_ERROR';
38

39
export interface ProjectSnapshotPostgresErrorDetails {
40
  readonly cause?: unknown;
41
  readonly payload?: unknown;
42
}
43

44
export class ProjectSnapshotPostgresError extends Error {
45
  constructor(
46
    public readonly code: ProjectSnapshotPostgresErrorCode,
47
    message: string,
48
    public readonly details: ProjectSnapshotPostgresErrorDetails = {},
49
  ) {
50
    super(message);
51
    this.name = 'ProjectSnapshotPostgresError';
52
  }
53
}
54

55
export interface SupabaseLikeError {
56
  readonly message: string;
57
  readonly code?: string;
58
  readonly details?: string;
59
  readonly hint?: string;
60
}
61

62
export interface SupabaseLikeResult<T> {
63
  readonly data: T;
64
  readonly error: SupabaseLikeError | null;
65
}
66

67
export interface SupabaseLikeMaybeSingleQuery<T> {
68
  maybeSingle(): Promise<SupabaseLikeResult<T | null>>;
69
}
70

71
export interface SupabaseLikeSingleQuery<T> {
72
  single(): Promise<SupabaseLikeResult<T>>;
73
}
74

75
export interface SupabaseLikeFilterBuilder<T> {
76
  eq(column: string, value: unknown): SupabaseLikeMaybeSingleQuery<T>;
77
}
78

79
export interface SupabaseLikeUpsertBuilder<T> {
80
  select(columns?: string): SupabaseLikeSingleQuery<T>;
81
}
82

83
export interface SupabaseLikeTable<T> {
84
  select(columns?: string): SupabaseLikeFilterBuilder<T>;
85
  upsert(
86
    row: T,
87
    options?: { readonly onConflict?: string },
88
  ): SupabaseLikeUpsertBuilder<T>;
89
}
90

91
export interface SupabaseLikeClient<T> {
92
  from(table: string): SupabaseLikeTable<T>;
93
}
94

95
/**
96
 * SQL shape for storing one JSONB project snapshot per project id.
97
 */
98
export function buildCreateProjectSnapshotTableSql(
99
  options: ProjectSnapshotPostgresOptions = {},
100
): PostgresStatement {
101
  const table = quoteQualifiedIdentifier(
102
    options.tableName ?? PROJECT_SNAPSHOT_TABLE,
103
  );
104

105
  return {
106
    text: [
107
      `create table if not exists ${table} (`,
108
      '  project_id text primary key,',
109
      '  version text not null,',
110
      '  snapshot jsonb not null,',
111
      '  updated_at timestamptz not null,',
112
      "  constraint gantt_project_snapshots_snapshot_object check (jsonb_typeof(snapshot) = 'object')",
113
      ');',
114
    ].join('\n'),
115
    values: [],
116
  };
117
}
118

119
export function buildLoadProjectSnapshotSql(
120
  projectId: string,
121
  options: ProjectSnapshotPostgresOptions = {},
122
): PostgresStatement {
123
  const table = quoteQualifiedIdentifier(
124
    options.tableName ?? PROJECT_SNAPSHOT_TABLE,
125
  );
126

127
  return {
128
    text: `select snapshot from ${table} where project_id = $1 limit 1;`,
129
    values: [projectId],
130
  };
131
}
132

133
export function buildSaveProjectSnapshotSql(
134
  project: ProjectSnapshot,
135
  options: ProjectSnapshotPostgresOptions = {},
136
): PostgresStatement {
137
  const table = quoteQualifiedIdentifier(
138
    options.tableName ?? PROJECT_SNAPSHOT_TABLE,
139
  );
140

141
  return {
142
    text: [
143
      `insert into ${table} (project_id, version, snapshot, updated_at)`,
144
      'values ($1, $2, $3::jsonb, $4::timestamptz)',
145
      'on conflict (project_id) do update set',
146
      '  version = excluded.version,',
147
      '  snapshot = excluded.snapshot,',
148
      '  updated_at = excluded.updated_at',
149
      'returning project_id, version, snapshot, updated_at;',
150
    ].join('\n'),
151
    values: [
152
      project.id,
153
      project.version,
154
      exportProjectSnapshot(project),
155
      project.updatedAt,
156
    ],
157
  };
158
}
159

160
/**
161
 * Framework-neutral Supabase-style example for storing ProjectSnapshot JSON.
162
 * The client shape is intentionally local and minimal, so no Supabase package is
163
 * required by the Gantt package or by consumers using another data client.
164
 */
165
export class ProjectSnapshotSupabaseAdapter {
166
  constructor(
167
    private readonly client: SupabaseLikeClient<ProjectSnapshotPostgresRow>,
168
    private readonly options: ProjectSnapshotPostgresOptions = {},
169
  ) {}
170

171
  async load(projectId: string): Promise<ProjectSnapshot | null> {
172
    const result = await this.client
173
      .from(this.tableName)
174
      .select('snapshot')
175
      .eq('project_id', projectId)
176
      .maybeSingle();
177

178
    if (result.error) {
179
      throw createQueryError(result.error);
180
    }
181

182
    if (!result.data) {
183
      return null;
184
    }
185

186
    return parseSnapshotPayload(result.data.snapshot);
187
  }
188

189
  async save(project: ProjectSnapshot): Promise<ProjectSnapshot> {
190
    const result = await this.client
191
      .from(this.tableName)
192
      .upsert(toProjectSnapshotRow(project), { onConflict: 'project_id' })
193
      .select('project_id, version, snapshot, updated_at')
194
      .single();
195

196
    if (result.error) {
197
      throw createQueryError(result.error);
198
    }
199

200
    return parseSnapshotPayload(result.data.snapshot);
201
  }
202

203
  private get tableName(): string {
204
    return this.options.tableName ?? PROJECT_SNAPSHOT_TABLE;
205
  }
206
}
207

208
export function toProjectSnapshotRow(
209
  project: ProjectSnapshot,
210
): ProjectSnapshotPostgresRow {
211
  return {
212
    project_id: project.id,
213
    version: project.version,
214
    snapshot: JSON.parse(exportProjectSnapshot(project)) as ProjectSnapshot,
215
    updated_at: project.updatedAt,
216
  };
217
}
218

219
function parseSnapshotPayload(payload: unknown): ProjectSnapshot {
220
  const json = typeof payload === 'string' ? payload : JSON.stringify(payload);
221
  const parsed = parseProjectSnapshotJson(json);
222

223
  if (parsed.ok === false) {
224
    throw new ProjectSnapshotPostgresError('INVALID_SNAPSHOT', parsed.error, {
225
      payload,
226
    });
227
  }
228

229
  return parsed.project;
230
}
231

232
function createQueryError(
233
  error: SupabaseLikeError,
234
): ProjectSnapshotPostgresError {
235
  return new ProjectSnapshotPostgresError('QUERY_ERROR', error.message, {
236
    cause: error,
237
  });
238
}
239

240
function quoteQualifiedIdentifier(identifier: string): string {
241
  const parts = identifier.split('.');
242

243
  if (parts.some((part) => !/^[A-Za-z_][A-Za-z0-9_]*$/.test(part))) {
244
    throw new ProjectSnapshotPostgresError(
245
      'INVALID_IDENTIFIER',
246
      `PostgreSQL identifier "${identifier}" is not supported by this example.`,
247
      { payload: identifier },
248
    );
249
  }
250

251
  return parts.map((part) => `"${part}"`).join('.');
252
}

PrintPDF

Print/PDF recipe

DOM print preparation for browser print and Save as PDF workflows.

examples/components/src/components/gantt/recipes/print-pdf-recipe.ts

Open preview

Source code

1
/**
2
 * @packageDocumentation
3
 * Print and Save-as-PDF recipe API for Gantt reporting.
4
 *
5
 * The helpers prepare a target Gantt container for browser printing, attach
6
 * optional report metadata, call an injected `window.print()` implementation,
7
 * and clean up after printing. The browser print dialog remains the PDF engine,
8
 * which keeps this recipe dependency-free and suitable for stakeholder reports.
9
 */
10
type ISODateString = import('@revolist/gantt').TaskEntity['startDate'];
11
import './print-pdf-recipe.css';
12

13
export type GanttPrintOrientation = 'portrait' | 'landscape';
14

15
export interface GanttPrintDateRange {
16
  readonly startDate?: ISODateString;
17
  readonly endDate?: ISODateString;
18
  readonly label?: string;
19
}
20

21
export interface GanttPrintableMetadataOptions {
22
  readonly title?: string;
23
  readonly subtitle?: string;
24
  readonly range?: GanttPrintDateRange;
25
  readonly printedAt?: Date | string;
26
}
27

28
export interface GanttPrintableMetadata {
29
  readonly title: string;
30
  readonly subtitle?: string;
31
  readonly range?: GanttPrintDateRange;
32
  readonly rangeLabel?: string;
33
  readonly printedAt?: string;
34
}
35

36
export interface GanttPrintStyleOptions {
37
  readonly pageSize?: string;
38
  readonly orientation?: GanttPrintOrientation;
39
  readonly margin?: string;
40
  readonly printRootClass?: string;
41
  readonly printHeaderClass?: string;
42
  readonly hideSelectors?: readonly string[];
43
  readonly preserveColor?: boolean;
44
}
45

46
export interface GanttPrintOptions extends GanttPrintStyleOptions {
47
  readonly metadata?: GanttPrintableMetadataOptions;
48
  readonly document?: Document;
49
  readonly window?: GanttPrintWindow;
50
  readonly cleanupDelayMs?: number;
51
}
52

53
export interface GanttPrintWindow {
54
  print(): void;
55
  removeEventListener?(type: 'afterprint', listener: () => void): void;
56
  addEventListener?(
57
    type: 'afterprint',
58
    listener: () => void,
59
    options?: AddEventListenerOptions,
60
  ): void;
61
}
62

63
export interface GanttPrintResult {
64
  readonly ok: boolean;
65
  readonly reason?:
66
    | 'missing-target'
67
    | 'missing-document'
68
    | 'missing-window-print'
69
    | 'print-failed';
70
  readonly error?: unknown;
71
}
72

73
interface NormalizedGanttPrintOptions {
74
  readonly pageSize: string;
75
  readonly orientation: GanttPrintOrientation;
76
  readonly margin: string;
77
  readonly printRootClass: string;
78
  readonly printHeaderClass: string;
79
  readonly hideSelectors: readonly string[];
80
  readonly preserveColor: boolean;
81
}
82

83
const DEFAULT_PRINT_OPTIONS: NormalizedGanttPrintOptions = {
84
  pageSize: 'A4',
85
  orientation: 'landscape',
86
  margin: '12mm',
87
  printRootClass: 'revo-gantt-print-root',
88
  printHeaderClass: 'revo-gantt-print-header',
89
  hideSelectors: [
90
    '[data-gantt-print-hidden]',
91
    '.gantt-toolbar',
92
    '.rgContextMenu',
93
  ],
94
  preserveColor: true,
95
};
96

97
export function createGanttPrintOptions(
98
  options: GanttPrintStyleOptions = {},
99
): NormalizedGanttPrintOptions {
100
  return {
101
    pageSize: options.pageSize ?? DEFAULT_PRINT_OPTIONS.pageSize,
102
    orientation: options.orientation ?? DEFAULT_PRINT_OPTIONS.orientation,
103
    margin: options.margin ?? DEFAULT_PRINT_OPTIONS.margin,
104
    printRootClass:
105
      options.printRootClass ?? DEFAULT_PRINT_OPTIONS.printRootClass,
106
    printHeaderClass:
107
      options.printHeaderClass ?? DEFAULT_PRINT_OPTIONS.printHeaderClass,
108
    hideSelectors: options.hideSelectors ?? DEFAULT_PRINT_OPTIONS.hideSelectors,
109
    preserveColor: options.preserveColor ?? DEFAULT_PRINT_OPTIONS.preserveColor,
110
  };
111
}
112

113
export function createGanttPrintStyles(
114
  options: GanttPrintStyleOptions = {},
115
): string {
116
  const normalized = createGanttPrintOptions(options);
117
  const hideRule =
118
    normalized.hideSelectors.length > 0
119
      ? `${normalized.hideSelectors.join(', ')} { display: none !important; }`
120
      : '';
121
  const colorRule = normalized.preserveColor
122
    ? 'print-color-adjust: exact; -webkit-print-color-adjust: exact;'
123
    : '';
124

125
  return [
126
    '@media print {',
127
    `  @page { size: ${normalized.pageSize} ${normalized.orientation}; margin: ${normalized.margin}; }`,
128
    `  body.gantt-print-active { ${colorRule} }`,
129
    `  body.gantt-print-active:not(.${normalized.printRootClass}) > *:not(.${normalized.printRootClass}):not(.revo-gantt-print-ancestor), body.gantt-print-active .revo-gantt-print-ancestor > *:not(.${normalized.printRootClass}):not(.revo-gantt-print-ancestor) { display: none !important; }`,
130
    '  body.gantt-print-active .revo-gantt-print-ancestor { display: block !important; height: auto !important; overflow: visible !important; }',
131
    `  .${normalized.printRootClass} { display: block !important; width: 100% !important; overflow: visible !important; }`,
132
    `  .${normalized.printRootClass} revo-grid { height: var(--gantt-print-height, 500px) !important; overflow: visible !important; }`,
133
    `  .${normalized.printRootClass} .rgRoot { height: 100% !important; overflow: visible !important; }`,
134
    `  .${normalized.printHeaderClass} { margin: 0 0 12px; break-after: avoid; }`,
135
    `  .${normalized.printHeaderClass} h1 { margin: 0 0 4px; font-size: 18pt; line-height: 1.2; }`,
136
    `  .${normalized.printHeaderClass} p { margin: 0; font-size: 9pt; color: #4b5563; }`,
137
    hideRule ? `  ${hideRule}` : '',
138
    '}',
139
  ]
140
    .filter(Boolean)
141
    .join('\n');
142
}
143

144
export function createPrintableGanttMetadata(
145
  options: GanttPrintableMetadataOptions = {},
146
): GanttPrintableMetadata {
147
  const rangeLabel = formatGanttPrintRange(options.range);
148
  const printedAt =
149
    options.printedAt instanceof Date
150
      ? options.printedAt.toISOString()
151
      : options.printedAt;
152

153
  return {
154
    title: normalizeTitle(options.title),
155
    subtitle: normalizeOptionalText(options.subtitle),
156
    range: options.range,
157
    rangeLabel,
158
    printedAt,
159
  };
160
}
161

162
export function formatGanttPrintRange(
163
  range: GanttPrintDateRange | undefined,
164
): string | undefined {
165
  if (!range) {
166
    return undefined;
167
  }
168

169
  if (range.label) {
170
    return range.label;
171
  }
172

173
  if (range.startDate && range.endDate) {
174
    return `${range.startDate} - ${range.endDate}`;
175
  }
176

177
  return range.startDate ?? range.endDate;
178
}
179

180
export function printGanttContainer(
181
  target: Element | null | undefined,
182
  options: GanttPrintOptions = {},
183
): GanttPrintResult {
184
  if (!target) {
185
    return { ok: false, reason: 'missing-target' };
186
  }
187

188
  const ownerDocument = options.document ?? target.ownerDocument;
189
  if (!ownerDocument) {
190
    return { ok: false, reason: 'missing-document' };
191
  }
192

193
  const printWindow = options.window ?? ownerDocument.defaultView;
194
  if (!printWindow || typeof printWindow.print !== 'function') {
195
    return { ok: false, reason: 'missing-window-print' };
196
  }
197

198
  const normalized = createGanttPrintOptions(options);
199
  const cleanup = prepareGanttPrintDom(
200
    target,
201
    ownerDocument,
202
    options.metadata,
203
    normalized,
204
  );
205

206
  let cleanupTimer: number | undefined;
207
  const cleanupOnce = createOnce(() => {
208
    printWindow.removeEventListener?.('afterprint', cleanupOnce);
209
    if (cleanupTimer !== undefined)
210
      ownerDocument.defaultView?.clearTimeout(cleanupTimer);
211
    cleanup();
212
  });
213

214
  try {
215
    printWindow.addEventListener?.('afterprint', cleanupOnce, {
216
      once: true,
217
    } as AddEventListenerOptions);
218
    if (options.cleanupDelayMs !== undefined) {
219
      cleanupTimer = ownerDocument.defaultView?.setTimeout(
220
        cleanupOnce,
221
        options.cleanupDelayMs,
222
      );
223
    }
224
    printWindow.print();
225
    if (options.cleanupDelayMs === undefined) cleanupOnce();
226
    return { ok: true };
227
  } catch (error) {
228
    cleanupOnce();
229
    return { ok: false, reason: 'print-failed', error };
230
  }
231
}
232

233
function prepareGanttPrintDom(
234
  target: Element,
235
  ownerDocument: Document,
236
  metadataOptions: GanttPrintableMetadataOptions | undefined,
237
  options: NormalizedGanttPrintOptions,
238
): () => void {
239
  // Virtualized rows need a definite viewport height when print ancestors become
240
  // auto-sized. Capture the current viewport, then restore application styles.
241
  const grids = [
242
    ...(target.matches('revo-grid') ? [target as HTMLElement] : []),
243
    ...Array.from(target.querySelectorAll<HTMLElement>('revo-grid')),
244
  ];
245
  const gridHeights = grids.map((grid) => ({
246
    grid,
247
    previous: grid.style.getPropertyValue('--gantt-print-height'),
248
    priority: grid.style.getPropertyPriority('--gantt-print-height'),
249
  }));
250
  for (const { grid } of gridHeights) {
251
    const height = grid.getBoundingClientRect().height;
252
    if (height > 0)
253
      grid.style.setProperty('--gantt-print-height', `${height}px`);
254
  }
255
  const printStyle = ownerDocument.createElement('style');
256
  printStyle.dataset.ganttPrintStyle = '';
257
  printStyle.textContent = createGanttPrintStyles(options);
258
  ownerDocument.head.appendChild(printStyle);
259
  const body = ownerDocument.body;
260
  const hadActiveClass = body.classList.contains('gantt-print-active');
261
  const addedAncestors: Element[] = [];
262
  for (
263
    let ancestor = target.parentElement;
264
    ancestor && ancestor !== body;
265
    ancestor = ancestor.parentElement
266
  ) {
267
    if (!ancestor.classList.contains('revo-gantt-print-ancestor')) {
268
      ancestor.classList.add('revo-gantt-print-ancestor');
269
      addedAncestors.push(ancestor);
270
    }
271
  }
272
  const hadRootClass = target.classList.contains(options.printRootClass);
273
  const hadDefaultRootClass = target.classList.contains(
274
    DEFAULT_PRINT_OPTIONS.printRootClass,
275
  );
276
  const headerClasses = [
277
    DEFAULT_PRINT_OPTIONS.printHeaderClass,
278
    options.printHeaderClass,
279
  ].filter(
280
    (className, index, classNames) => classNames.indexOf(className) === index,
281
  );
282
  const header = createPrintHeader(
283
    ownerDocument,
284
    createPrintableGanttMetadata(metadataOptions),
285
    headerClasses.join(' '),
286
  );
287

288
  body.classList.add('gantt-print-active');
289
  target.classList.add(DEFAULT_PRINT_OPTIONS.printRootClass);
290
  target.classList.add(options.printRootClass);
291
  target.insertBefore(header, target.firstChild);
292

293
  return () => {
294
    header.remove();
295
    printStyle.remove();
296
    for (const { grid, previous, priority } of gridHeights) {
297
      if (previous)
298
        grid.style.setProperty('--gantt-print-height', previous, priority);
299
      else grid.style.removeProperty('--gantt-print-height');
300
    }
301

302
    if (!hadRootClass) {
303
      target.classList.remove(options.printRootClass);
304
    }
305

306
    if (!hadDefaultRootClass) {
307
      target.classList.remove(DEFAULT_PRINT_OPTIONS.printRootClass);
308
    }
309

310
    for (const ancestor of addedAncestors) {
311
      ancestor.classList.remove('revo-gantt-print-ancestor');
312
    }
313
    if (!hadActiveClass) body.classList.remove('gantt-print-active');
314
  };
315
}
316

317
function createPrintHeader(
318
  ownerDocument: Document,
319
  metadata: GanttPrintableMetadata,
320
  headerClass: string,
321
): HTMLElement {
322
  const header = ownerDocument.createElement('header');
323
  const title = ownerDocument.createElement('h1');
324
  const details = [
325
    metadata.subtitle,
326
    metadata.rangeLabel,
327
    metadata.printedAt ? `Printed ${metadata.printedAt}` : undefined,
328
  ].filter((value): value is string => Boolean(value));
329

330
  header.className = headerClass;
331
  title.textContent = metadata.title;
332
  header.appendChild(title);
333

334
  if (details.length > 0) {
335
    const paragraph = ownerDocument.createElement('p');
336
    paragraph.textContent = details.join(' | ');
337
    header.appendChild(paragraph);
338
  }
339

340
  return header;
341
}
342

343
function normalizeTitle(title: string | undefined): string {
344
  const normalized = title?.trim();
345
  return normalized || 'Gantt schedule';
346
}
347

348
function normalizeOptionalText(value: string | undefined): string | undefined {
349
  const normalized = value?.trim();
350
  return normalized || undefined;
351
}
352

353
function createOnce(callback: () => void): () => void {
354
  let called = false;
355

356
  return () => {
357
    if (called) {
358
      return;
359
    }
360

361
    called = true;
362
    callback();
363
  };
364
}

RESTPersistence

REST adapter

Fetch-based project snapshot persistence with injected request options.

examples/components/src/components/gantt/recipes/rest-adapter.ts

Open preview

Source code

1
/**
2
 * @packageDocumentation
3
 * REST persistence adapter example for Gantt project snapshots.
4
 *
5
 * The adapter loads and saves serialized `ProjectSnapshot` JSON through a
6
 * configurable endpoint and injected `fetch` implementation. It is intended as
7
 * a minimal backend integration pattern that keeps authentication headers,
8
 * abort signals, transport, and storage ownership in the host application.
9
 */
10
import type { ProjectSnapshot } from '@revolist/gantt';
11
import {
12
  exportProjectSnapshot,
13
  parseProjectSnapshotJson,
14
} from '@revolist/gantt';
15

16
export type ProjectSnapshotRestErrorCode =
17
  | 'HTTP_ERROR'
18
  | 'INVALID_SNAPSHOT'
19
  | 'NETWORK_ERROR';
20

21
export interface ProjectSnapshotRestErrorDetails {
22
  readonly status?: number;
23
  readonly payload?: unknown;
24
  readonly cause?: unknown;
25
}
26

27
export class ProjectSnapshotRestError extends Error {
28
  constructor(
29
    public readonly code: ProjectSnapshotRestErrorCode,
30
    message: string,
31
    public readonly details: ProjectSnapshotRestErrorDetails = {},
32
  ) {
33
    super(message);
34
    this.name = 'ProjectSnapshotRestError';
35
  }
36
}
37

38
export interface ProjectSnapshotRestAdapterOptions {
39
  /** Endpoint that returns and accepts a serialized project snapshot. */
40
  readonly url: string;
41
  /** Optional headers for authentication, tenancy, or content negotiation. */
42
  readonly headers?: Readonly<Record<string, string>>;
43
  /** Custom fetch implementation for tests, SSR, or framework adapters. */
44
  readonly fetchImpl?: typeof fetch;
45
  /** JSON indentation used for readable save payloads. */
46
  readonly space?: number | string;
47
}
48

49
export interface ProjectSnapshotRestRequestOptions {
50
  readonly signal?: AbortSignal;
51
}
52

53
/**
54
 * Framework-neutral example for persisting project snapshots through REST.
55
 */
56
export class ProjectSnapshotRestAdapter {
57
  private readonly fetchImpl: typeof fetch;
58

59
  constructor(private readonly options: ProjectSnapshotRestAdapterOptions) {
60
    this.fetchImpl = options.fetchImpl ?? fetch;
61
  }
62

63
  async load(
64
    request: ProjectSnapshotRestRequestOptions = {},
65
  ): Promise<ProjectSnapshot> {
66
    const response = await this.request(() =>
67
      this.fetchImpl(this.options.url, {
68
        method: 'GET',
69
        headers: this.options.headers,
70
        signal: request.signal,
71
      }),
72
    );
73

74
    await this.assertOk(response);
75
    const json = await response.text();
76
    const parsed = parseProjectSnapshotJson(json);
77

78
    if (parsed.ok === false) {
79
      throw new ProjectSnapshotRestError('INVALID_SNAPSHOT', parsed.error, {
80
        status: response.status,
81
        payload: json,
82
      });
83
    }
84

85
    return parsed.project;
86
  }
87

88
  async save(
89
    project: ProjectSnapshot,
90
    request: ProjectSnapshotRestRequestOptions = {},
91
  ): Promise<void> {
92
    const response = await this.request(() =>
93
      this.fetchImpl(this.options.url, {
94
        method: 'PUT',
95
        headers: {
96
          'content-type': 'application/json',
97
          ...this.options.headers,
98
        },
99
        body: exportProjectSnapshot(project, { space: this.options.space }),
100
        signal: request.signal,
101
      }),
102
    );
103

104
    await this.assertOk(response);
105
  }
106

107
  private async request(run: () => Promise<Response>): Promise<Response> {
108
    try {
109
      return await run();
110
    } catch (error) {
111
      throw new ProjectSnapshotRestError(
112
        'NETWORK_ERROR',
113
        'Project snapshot request failed.',
114
        {
115
          cause: error,
116
        },
117
      );
118
    }
119
  }
120

121
  private async assertOk(response: Response): Promise<void> {
122
    if (response.ok) {
123
      return;
124
    }
125

126
    throw new ProjectSnapshotRestError(
127
      'HTTP_ERROR',
128
      'Project snapshot request returned an error.',
129
      {
130
        status: response.status,
131
        payload: await readErrorPayload(response),
132
      },
133
    );
134
  }
135
}
136

137
async function readErrorPayload(response: Response): Promise<unknown> {
138
  const text = await response.text();
139
  if (!text) {
140
    return undefined;
141
  }
142

143
  try {
144
    return JSON.parse(text);
145
  } catch {
146
    return text;
147
  }
148
}

ValidationPermissions

Validation recipes

Forbidden dates, locked phases, approval gates, and role-guard checks.

examples/components/src/components/gantt/recipes/validation-recipes.ts

Open preview

Source code

1
/**
2
 * @packageDocumentation
3
 * Validation recipe API for cancelable Gantt task changes.
4
 *
5
 * The module provides small composable validators for role guards, forbidden
6
 * date ranges, locked phases, and approval gates. Validators can be attached to
7
 * `gantt-before-task-change` through a generated event handler or invoked
8
 * directly before applying task mutations in non-DOM flows.
9
 */
10
import type { TaskEntity, TaskId } from '@revolist/gantt';
11
type ISODateString = import('@revolist/gantt').TaskEntity['startDate'];
12
import type {
13
  GanttBeforeTaskChangeAction,
14
  GanttBeforeTaskChangeDetail,
15
} from '@revolist/gantt';
16
import {
17
  createGanttRoleEditabilityHelpers,
18
  type GanttRoleEditabilityContext,
19
  type GanttRoleEditabilityPolicy,
20
} from '@revolist/gantt';
21

22
export interface GanttValidationDecision {
23
  readonly ok: boolean;
24
  readonly code?: string;
25
  readonly message?: string;
26
}
27

28
export type GanttBeforeTaskChangeValidator<TContext = GanttValidationContext> =
29
  (
30
    detail: GanttBeforeTaskChangeDetail,
31
    context: TContext,
32
  ) => GanttValidationDecision | boolean;
33

34
export interface GanttValidationContext {
35
  readonly getTaskById?: (taskId: TaskId) => TaskEntity | null | undefined;
36
  readonly roleContext?: GanttRoleEditabilityContext;
37
  readonly approvals?: GanttApprovalRegistry;
38
}
39

40
export interface GanttValidationReject {
41
  readonly detail: GanttBeforeTaskChangeDetail;
42
  readonly decision: GanttValidationDecision;
43
}
44

45
export interface GanttValidationHandlerOptions<TContext> {
46
  readonly context: TContext | (() => TContext);
47
  readonly validators: readonly GanttBeforeTaskChangeValidator<TContext>[];
48
  readonly onReject?: (rejection: GanttValidationReject) => void;
49
}
50

51
export interface GanttDateRange {
52
  readonly startDate: ISODateString;
53
  readonly endDate: ISODateString;
54
  readonly label?: string;
55
}
56

57
export interface ForbiddenDateRangeValidatorOptions {
58
  readonly ranges: readonly GanttDateRange[];
59
  readonly actions?: readonly GanttBeforeTaskChangeAction[];
60
  readonly message?: (range: GanttDateRange) => string;
61
}
62

63
export interface LockedPhaseValidatorOptions<TContext> {
64
  readonly lockedPhaseIds: readonly string[];
65
  readonly getPhaseId: (
66
    detail: GanttBeforeTaskChangeDetail,
67
    context: TContext,
68
  ) => string | null | undefined;
69
  readonly actions?: readonly GanttBeforeTaskChangeAction[];
70
  readonly message?: (phaseId: string) => string;
71
}
72

73
export interface ApprovalRecord {
74
  readonly approved: boolean;
75
  readonly approvedBy?: string;
76
  readonly expiresAt?: string;
77
}
78

79
export type GanttApprovalRegistry =
80
  | Readonly<Record<TaskId, ApprovalRecord | undefined>>
81
  | ((
82
      detail: GanttBeforeTaskChangeDetail,
83
    ) => ApprovalRecord | null | undefined);
84

85
export interface ApprovalGateValidatorOptions<
86
  TContext extends GanttValidationContext,
87
> {
88
  readonly actions?: readonly GanttBeforeTaskChangeAction[];
89
  readonly requiresApproval?: (
90
    detail: GanttBeforeTaskChangeDetail,
91
    context: TContext,
92
  ) => boolean;
93
  readonly isApprovalValid?: (
94
    approval: ApprovalRecord,
95
    detail: GanttBeforeTaskChangeDetail,
96
    context: TContext,
97
  ) => boolean;
98
  readonly message?: string;
99
}
100

101
export interface RoleGuardValidatorOptions<
102
  TContext extends GanttValidationContext,
103
> {
104
  readonly policy: GanttRoleEditabilityPolicy;
105
  readonly getRoleContext?: (
106
    detail: GanttBeforeTaskChangeDetail,
107
    context: TContext,
108
  ) => GanttRoleEditabilityContext;
109
  readonly message?: string;
110
}
111

112
export function createGanttBeforeTaskChangeValidationHandler<TContext>(
113
  options: GanttValidationHandlerOptions<TContext>,
114
): (event: CustomEvent<GanttBeforeTaskChangeDetail>) => void {
115
  return (event) => {
116
    const context =
117
      typeof options.context === 'function'
118
        ? (options.context as () => TContext)()
119
        : options.context;
120
    const decision = validateGanttBeforeTaskChange(
121
      event.detail,
122
      context,
123
      options.validators,
124
    );
125

126
    if (decision.ok) {
127
      return;
128
    }
129

130
    event.preventDefault();
131
    options.onReject?.({
132
      detail: event.detail,
133
      decision,
134
    });
135
  };
136
}
137

138
export function validateGanttBeforeTaskChange<TContext>(
139
  detail: GanttBeforeTaskChangeDetail,
140
  context: TContext,
141
  validators: readonly GanttBeforeTaskChangeValidator<TContext>[],
142
): GanttValidationDecision {
143
  for (const validator of validators) {
144
    const decision = normalizeDecision(validator(detail, context));
145

146
    if (!decision.ok) {
147
      return decision;
148
    }
149
  }
150

151
  return allow();
152
}
153

154
export function createForbiddenDateRangeValidator<
155
  TContext extends GanttValidationContext,
156
>(
157
  options: ForbiddenDateRangeValidatorOptions,
158
): GanttBeforeTaskChangeValidator<TContext> {
159
  const actions = new Set(options.actions);
160

161
  return (detail, context) => {
162
    if (!matchesAction(actions, detail.action)) {
163
      return allow();
164
    }
165

166
    const range = resolveProposedTaskRange(detail, context);
167
    if (!range) {
168
      return allow();
169
    }
170

171
    const forbiddenRange = options.ranges.find((candidate) =>
172
      rangesOverlap(range, candidate),
173
    );
174
    if (!forbiddenRange) {
175
      return allow();
176
    }
177

178
    return deny(
179
      'forbidden-date-range',
180
      options.message?.(forbiddenRange) ??
181
        `Task changes cannot overlap ${forbiddenRange.label ?? 'the forbidden range'}.`,
182
    );
183
  };
184
}
185

186
export function createLockedPhaseValidator<TContext>(
187
  options: LockedPhaseValidatorOptions<TContext>,
188
): GanttBeforeTaskChangeValidator<TContext> {
189
  const actions = new Set(options.actions);
190
  const lockedPhaseIds = new Set(options.lockedPhaseIds);
191

192
  return (detail, context) => {
193
    if (!matchesAction(actions, detail.action)) {
194
      return allow();
195
    }
196

197
    const phaseId = options.getPhaseId(detail, context);
198
    if (!phaseId || !lockedPhaseIds.has(phaseId)) {
199
      return allow();
200
    }
201

202
    return deny(
203
      'locked-phase',
204
      options.message?.(phaseId) ?? `Phase "${phaseId}" is locked.`,
205
    );
206
  };
207
}
208

209
export function createApprovalGateValidator<
210
  TContext extends GanttValidationContext,
211
>(
212
  options: ApprovalGateValidatorOptions<TContext> = {},
213
): GanttBeforeTaskChangeValidator<TContext> {
214
  const defaultActions: readonly GanttBeforeTaskChangeAction[] = [
215
    'move',
216
    'resize',
217
    'progress',
218
  ];
219
  const actions = new Set(options.actions ?? defaultActions);
220

221
  return (detail, context) => {
222
    if (!matchesAction(actions, detail.action)) {
223
      return allow();
224
    }
225

226
    if (
227
      options.requiresApproval &&
228
      !options.requiresApproval(detail, context)
229
    ) {
230
      return allow();
231
    }
232

233
    const approval = getApproval(detail, context.approvals);
234
    const isApprovalValid = options.isApprovalValid ?? defaultApprovalCheck;
235

236
    if (approval && isApprovalValid(approval, detail, context)) {
237
      return allow();
238
    }
239

240
    return deny(
241
      'approval-required',
242
      options.message ?? 'Task change requires approval.',
243
    );
244
  };
245
}
246

247
export function createRoleGuardValidator<
248
  TContext extends GanttValidationContext,
249
>(
250
  options: RoleGuardValidatorOptions<TContext>,
251
): GanttBeforeTaskChangeValidator<TContext> {
252
  const editability = createGanttRoleEditabilityHelpers(options.policy);
253

254
  return (detail, context) => {
255
    const roleContext = options.getRoleContext?.(detail, context) ??
256
      context.roleContext ?? { roles: undefined };
257

258
    return editability.canEditTask(detail, roleContext)
259
      ? allow()
260
      : deny(
261
          'role-denied',
262
          options.message ?? 'Current role cannot edit this task.',
263
        );
264
  };
265
}
266

267
function resolveProposedTaskRange<TContext extends GanttValidationContext>(
268
  detail: GanttBeforeTaskChangeDetail,
269
  context: TContext,
270
): GanttDateRange | null {
271
  const task = detail.taskId ? context.getTaskById?.(detail.taskId) : null;
272
  const startDate =
273
    detail.changes.startDate ??
274
    detail.previousValues.startDate ??
275
    task?.startDate;
276
  const endDate =
277
    detail.changes.endDate ?? detail.previousValues.endDate ?? task?.endDate;
278

279
  return startDate && endDate ? { startDate, endDate } : null;
280
}
281

282
function rangesOverlap(left: GanttDateRange, right: GanttDateRange): boolean {
283
  return left.startDate <= right.endDate && right.startDate <= left.endDate;
284
}
285

286
function matchesAction(
287
  actions: ReadonlySet<GanttBeforeTaskChangeAction>,
288
  action: GanttBeforeTaskChangeAction,
289
): boolean {
290
  return actions.size === 0 || actions.has(action);
291
}
292

293
function getApproval(
294
  detail: GanttBeforeTaskChangeDetail,
295
  approvals: GanttApprovalRegistry | undefined,
296
): ApprovalRecord | null | undefined {
297
  if (!approvals || !detail.taskId) {
298
    return null;
299
  }
300

301
  return typeof approvals === 'function'
302
    ? approvals(detail)
303
    : approvals[detail.taskId];
304
}
305

306
function defaultApprovalCheck(approval: ApprovalRecord): boolean {
307
  if (!approval.approved) {
308
    return false;
309
  }
310

311
  return !approval.expiresAt || Date.parse(approval.expiresAt) > Date.now();
312
}
313

314
function normalizeDecision(
315
  decision: GanttValidationDecision | boolean,
316
): GanttValidationDecision {
317
  return typeof decision === 'boolean' ? { ok: decision } : decision;
318
}
319

320
function allow(): GanttValidationDecision {
321
  return { ok: true };
322
}
323

324
function deny(code: string, message: string): GanttValidationDecision {
325
  return {
326
    ok: false,
327
    code,
328
    message,
329
  };
330
}

Gantt Examples

Planning

Remote Gantt

Microsoft Project

Feature Recipes

Task Editor Form

Production Patterns

Full Showcase

Scheduling

Basic

10,000 Tasks

Twenty-Year Timeline

Scheduling

Advanced Dependencies

Constraints And Deadlines

Project Finish ALAP

Resources & Work

Resource Planning

Scheduler Features

Progress And Work

Split Tasks

Analysis & Optimization

Baselines

Critical Path

Critical Path Analysis

Copyable application recipes

Application recipe sources

Context menu extensions

Feature helper examples

GraphQL adapter

Grid projection examples

Persistence examples

PostgreSQL persistence

Print/PDF recipe

REST adapter

Validation recipes