@eightkk/vue-weave 0.0.0-stage → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (82) hide show
  1. package/CHANGELOG.md +525 -0
  2. package/CONTRIBUTING.md +116 -0
  3. package/LICENSE +21 -0
  4. package/README.ja.md +278 -0
  5. package/README.md +275 -2
  6. package/THIRD_PARTY_NOTICES.md +25 -0
  7. package/dist/core-LWK21xl4.js +13672 -0
  8. package/dist/core.js +1 -0
  9. package/dist/index.js +8505 -0
  10. package/dist/style.css +2 -0
  11. package/dist/types/components/GanttChart.vue.d.ts +353 -0
  12. package/dist/types/components/NetworkGraph.vue.d.ts +252 -0
  13. package/dist/types/components/types.d.ts +27 -0
  14. package/dist/types/composables/useAsyncGraphLayout.d.ts +163 -0
  15. package/dist/types/composables/useEditHistory.d.ts +13 -0
  16. package/dist/types/composables/useEditTransaction.d.ts +46 -0
  17. package/dist/types/composables/useLinkedSelection.d.ts +118 -0
  18. package/dist/types/composables/useTimelineView.d.ts +24 -0
  19. package/dist/types/composables/useWindowedData.d.ts +83 -0
  20. package/dist/types/core/actuals.d.ts +170 -0
  21. package/dist/types/core/calendarFormat.d.ts +65 -0
  22. package/dist/types/core/editTransaction.d.ts +96 -0
  23. package/dist/types/core/exportSvg.d.ts +236 -0
  24. package/dist/types/core/fieldEditing.d.ts +114 -0
  25. package/dist/types/core/graph.d.ts +196 -0
  26. package/dist/types/core/graphAlgorithms.d.ts +51 -0
  27. package/dist/types/core/graphAnalysis.d.ts +96 -0
  28. package/dist/types/core/graphCollapse.d.ts +62 -0
  29. package/dist/types/core/graphCrossings.d.ts +25 -0
  30. package/dist/types/core/graphEditing.d.ts +52 -0
  31. package/dist/types/core/graphExpansion.d.ts +71 -0
  32. package/dist/types/core/graphFlow.d.ts +184 -0
  33. package/dist/types/core/graphForce.d.ts +29 -0
  34. package/dist/types/core/graphGeometry.d.ts +31 -0
  35. package/dist/types/core/graphIncremental.d.ts +93 -0
  36. package/dist/types/core/graphLasso.d.ts +15 -0
  37. package/dist/types/core/graphLayoutRequests.d.ts +218 -0
  38. package/dist/types/core/graphLayouts.d.ts +81 -0
  39. package/dist/types/core/graphObstacleRouting.d.ts +68 -0
  40. package/dist/types/core/graphPortRules.d.ts +111 -0
  41. package/dist/types/core/graphRouting.d.ts +84 -0
  42. package/dist/types/core/graphSnapping.d.ts +34 -0
  43. package/dist/types/core/graphSpatial.d.ts +49 -0
  44. package/dist/types/core/graphSwimlanes.d.ts +77 -0
  45. package/dist/types/core/graphTraversal.d.ts +51 -0
  46. package/dist/types/core/graphView.d.ts +73 -0
  47. package/dist/types/core/index.d.ts +76 -0
  48. package/dist/types/core/interchange.d.ts +6 -0
  49. package/dist/types/core/interchangeCsv.d.ts +75 -0
  50. package/dist/types/core/interchangeICalendar.d.ts +111 -0
  51. package/dist/types/core/interchangeMsProject.d.ts +339 -0
  52. package/dist/types/core/leveling.d.ts +57 -0
  53. package/dist/types/core/pert.d.ts +62 -0
  54. package/dist/types/core/placement.d.ts +100 -0
  55. package/dist/types/core/planComparison.d.ts +275 -0
  56. package/dist/types/core/resourceLoad.d.ts +65 -0
  57. package/dist/types/core/resourceTimeline.d.ts +179 -0
  58. package/dist/types/core/rowHierarchy.d.ts +25 -0
  59. package/dist/types/core/scheduleDiagnostics.d.ts +37 -0
  60. package/dist/types/core/scheduleModel.d.ts +187 -0
  61. package/dist/types/core/scheduleTrace.d.ts +118 -0
  62. package/dist/types/core/scheduling.d.ts +194 -0
  63. package/dist/types/core/sheetEditing.d.ts +36 -0
  64. package/dist/types/core/snapshot.d.ts +388 -0
  65. package/dist/types/core/statusDate.d.ts +36 -0
  66. package/dist/types/core/timeRangeTargets.d.ts +67 -0
  67. package/dist/types/core/timeline.d.ts +194 -0
  68. package/dist/types/core/timelineView.d.ts +101 -0
  69. package/dist/types/core/types.d.ts +805 -0
  70. package/dist/types/core/viewBindings.d.ts +112 -0
  71. package/dist/types/core/windowedData.d.ts +255 -0
  72. package/dist/types/core/workCalendar.d.ts +41 -0
  73. package/dist/types/core/workingTimeScale.d.ts +33 -0
  74. package/dist/types/index.d.ts +52 -0
  75. package/docs/api.md +2009 -0
  76. package/docs/architecture.md +112 -0
  77. package/docs/code-of-conduct.md +24 -0
  78. package/docs/integration.md +964 -0
  79. package/docs/scheduling.md +586 -0
  80. package/docs/security.md +26 -0
  81. package/docs/third-party-licenses.md +33 -0
  82. package/package.json +79 -4
@@ -0,0 +1,24 @@
1
+ import type { MaybeRefOrGetter, ShallowRef } from 'vue';
2
+ import type { TimelineViewInput, TimelineViewSort, TimelineViewState } from '../core/timelineView.js';
3
+ import type { TimeRange } from '../core/timeline.js';
4
+ import type { TimelineBar, TimelineDependency, TimelineRow } from '../core/types.js';
5
+ /**
6
+ * Reactive search, sort and column state for a Gantt chart. The source data is never changed: `projection`
7
+ * is a display copy and `columns` the ordered visible columns. State updates are immutable and JSON-safe.
8
+ */
9
+ export declare function useTimelineView<R extends TimelineRow = TimelineRow, B extends TimelineBar = TimelineBar, D extends TimelineDependency = TimelineDependency>(source: MaybeRefOrGetter<TimelineViewInput<R, B, D>>, initial?: TimelineViewState): {
10
+ state: ShallowRef<TimelineViewState>;
11
+ projection: import("vue").ComputedRef<import("../index.js").TimelineViewProjection<R, B, D>>;
12
+ columns: import("vue").ComputedRef<import("../index.js").TimelineColumn<R>[]>;
13
+ diagnostics: import("vue").ComputedRef<import("../index.js").TimelineViewDiagnostic[]>;
14
+ setSearch: (text: string, columnIds?: string[]) => void;
15
+ setSort: (sort: readonly TimelineViewSort[]) => void;
16
+ setColumnVisible: (id: string, visible: boolean) => void;
17
+ setColumnWidth: (id: string, width: number) => void;
18
+ moveColumn: (id: string, index: number) => void;
19
+ toggleCollapsed: (id: string, collapsed?: boolean) => void;
20
+ setWindow: (window: TimeRange | undefined, zoom?: string) => void;
21
+ restore: (json: unknown) => void;
22
+ reset: () => void;
23
+ snapshot: () => TimelineViewState;
24
+ };
@@ -0,0 +1,83 @@
1
+ import { type ComputedRef, type MaybeRefOrGetter, type ShallowRef } from 'vue';
2
+ import { type DanglingLink, type SplitDanglingLinksOptions, type WindowedCellStatus, type WindowedCoverage, type WindowedDataOptions, type WindowedDataPage, type WindowedDataRequest, type WindowedDataState, type WindowedView } from '../core/windowedData.js';
3
+ /** Fetches one request. `signal` is aborted when the result is no longer wanted; the result is ignored either way. */
4
+ export type WindowedDataLoader<T, L = never> = (request: WindowedDataRequest, context: {
5
+ signal: AbortSignal;
6
+ }) => readonly T[] | WindowedDataPage<T, L> | Promise<readonly T[] | WindowedDataPage<T, L>>;
7
+ /** The last failure: of a request of the current condition, or of the view itself (no `request`, e.g. too many cells). */
8
+ export interface WindowedDataError {
9
+ request?: WindowedDataRequest;
10
+ error: unknown;
11
+ }
12
+ export interface UseWindowedDataOptions<T, L = never> extends WindowedDataOptions<T, L> {
13
+ /** What is shown, such as the payload of GanttChart `visible-window-change`. Undefined requests nothing. */
14
+ view: MaybeRefOrGetter<WindowedView | undefined>;
15
+ /**
16
+ * A token for everything else the data depends on: a filter, a query, a data version. When it changes, every request
17
+ * is aborted and all loaded data is dropped, so results for another condition are never attached. Default `''`. A value
18
+ * that is not a string, or a getter that throws, is reported through `error` (never thrown) and drops all data until a
19
+ * valid condition is read again.
20
+ */
21
+ condition?: MaybeRefOrGetter<string>;
22
+ /** Fetches a request. Supplied by the application; may return the items, `{ items, links }` or a promise of either. */
23
+ load: WindowedDataLoader<T, L>;
24
+ /** Ends of a link for `resolvedLinks` and `danglingLinks`. Default `link.from` and `link.to` (each accessor falls back on its own). */
25
+ linkEnds?: SplitDanglingLinksOptions<L>;
26
+ }
27
+ export interface WindowedData<T, L = never> {
28
+ /** The core state (`WindowedDataState`); read cells, requests and data from it. */
29
+ state: Readonly<ShallowRef<WindowedDataState<T, L>>>;
30
+ /** Every loaded item of the current condition, deduplicated by ID. It keeps its contents while requests load or fail. */
31
+ items: ComputedRef<T[]>;
32
+ /** Every loaded link of the current condition, deduplicated by ID, including dangling ones. */
33
+ links: ComputedRef<L[]>;
34
+ /** Links whose both ends are loaded items: safe for GanttChart `dependencies` or NetworkGraph `edges`. */
35
+ resolvedLinks: ComputedRef<L[]>;
36
+ /** Links with an end that is not loaded; they move to `resolvedLinks` when it arrives. */
37
+ danglingLinks: ComputedRef<DanglingLink<L>[]>;
38
+ /** Coverage of the current view. */
39
+ coverage: ComputedRef<WindowedCoverage>;
40
+ /** Aggregate status of the current view (`coverage.status`). */
41
+ status: ComputedRef<WindowedCellStatus>;
42
+ /** True only when every cell of the current view has loaded. The data is still only the loaded part of the whole. */
43
+ complete: ComputedRef<boolean>;
44
+ /** True while a request is in flight. */
45
+ pending: ComputedRef<boolean>;
46
+ /**
47
+ * The current failure of the current condition, or undefined. Per-cell failures are in `state`. Precedence, from the
48
+ * first that applies: (1) a failed request (`{ request, error }`), cleared by `retry`, `invalidate` or a new condition;
49
+ * (2) an invalid view (such as one with more than `maxCells` cells, or chunk indices beyond the safe integer range) or
50
+ * condition (not a string), or a `view` or `condition` getter that throws, reported without `request` and never thrown,
51
+ * not even by the `useWindowedData` call when the first read of `condition` fails: the state then has no view and
52
+ * nothing in flight (`complete` false) and keeps the data of the current condition (an invalid condition drops all
53
+ * data). It clears when a valid condition and view are read again (on the next change, or when requests start), and
54
+ * the view is then requested again; (3) a `linkEnds` accessor that
55
+ * throws, reported as `{ error }` without `request`: `resolvedLinks` and `danglingLinks` are then both empty (never a
56
+ * partial split), while `items`, `links`, `status` and `complete` are unaffected. (3) is derived from the loaded links
57
+ * and clears by itself as soon as the split succeeds again (new links, or whatever the accessor reads changed); while (1)
58
+ * or (2) is shown, (3) is not evaluated and appears afterwards if it still applies. Reading `error` evaluates the split
59
+ * (cached, like `resolvedLinks`) unless (1) or (2) applies; nothing is evaluated for an application that reads none of them.
60
+ */
61
+ error: ComputedRef<WindowedDataError | undefined>;
62
+ /** Coverage of any window, for example one row (`{ start, end, rowIds: [id] }`) or the whole plan. */
63
+ coverageOf: (window: WindowedView) => WindowedCoverage;
64
+ /** Requests failed cells again (all, or those in `window`) that the current view needs. Loaded data stays. */
65
+ retry: (window?: WindowedView) => void;
66
+ /** Reloads the current view; loaded data stays on display until it is replaced by ID. */
67
+ invalidate: () => void;
68
+ /** Aborts every request in flight. */
69
+ cancel: () => void;
70
+ /** Cancels, stops watching and ignores every later result. Called automatically with the owning scope. */
71
+ dispose: () => void;
72
+ }
73
+ /**
74
+ * Loads only what a view shows. The view (a time window and optionally row IDs) is aligned to chunks, missing cells are
75
+ * requested through `load`, superseded requests are aborted, late, aborted and out-of-order responses are ignored, items
76
+ * that overlapping requests return twice are kept once, failed cells keep the loaded data and wait for `retry`, and a
77
+ * new `condition` drops data that belongs to another one. A new condition is processed before the new view is checked,
78
+ * so an invalid view never keeps the old condition's requests or data; responses are matched by request ID and
79
+ * condition. Requests start when the owning component mounts (immediately
80
+ * outside a component), so nothing is requested during server rendering. All decisions are made by the pure core
81
+ * functions (`setWindowedView`, `resolveWindowedRequest`, ...), which can also be used without Vue.
82
+ */
83
+ export declare function useWindowedData<T, L = never>(options: UseWindowedDataOptions<T, L>): WindowedData<T, L>;
@@ -0,0 +1,170 @@
1
+ import { type ScheduleFailure, type ScheduleInput, type ScheduleResult, type ScheduleSuccess } from './scheduling.js';
2
+ import { type PlanningDiagnostic, type PlanningDiagnosticSeverity } from './scheduleDiagnostics.js';
3
+ import { type TimeRange } from './timeline.js';
4
+ import type { ChartTone, TimelineBar } from './types.js';
5
+ import type { EntityRef } from './viewBindings.js';
6
+ /** What has actually happened to one task, as recorded at the status date. */
7
+ export interface TaskActuals {
8
+ /**
9
+ * Recorded working intervals, half-open `[start, end)` in absolute time: for example a start, an interruption and a
10
+ * resume give two intervals. They are kept exactly as given, also on non-working time. Each must have `end > start`,
11
+ * align with the horizon and quantum, and lie inside `input.range`.
12
+ */
13
+ intervals: readonly TimeRange[];
14
+ /**
15
+ * Working time still to do, in the input's units on the task's calendar (a multiple of the quantum). When omitted, it
16
+ * is the task's `duration` minus the elapsed length of its actual intervals (overlaps counted once), but at least 0.
17
+ */
18
+ remainingWork?: number;
19
+ /** The task is complete: it has no remaining work and ends at the end of its last actual interval. */
20
+ finished?: boolean;
21
+ }
22
+ /**
23
+ * `actual-overlap`: two actual intervals of a task overlap (error). `actual-after-status-date`: an actual interval lies
24
+ * after the status date (warning). `actual-outside-calendar`: an actual interval covers time that is not working time of
25
+ * the task's calendar after pauses (warning). `actual-contradiction`: a task is `finished` but has a positive
26
+ * `remainingWork` (error).
27
+ */
28
+ export type ActualsDiagnosticCode = 'actual-overlap' | 'actual-after-status-date' | 'actual-outside-calendar' | 'actual-contradiction';
29
+ /** A problem of recorded actuals, shaped like a `PlanningDiagnostic` so that both can go in one list. */
30
+ export interface ActualsDiagnostic {
31
+ /** Stable for the same problem: a JSON array of the code, the task ID and the range, if any. */
32
+ id: string;
33
+ code: ActualsDiagnosticCode;
34
+ severity: PlanningDiagnosticSeverity;
35
+ /** The task, as `{ kind: 'task', id }`. */
36
+ entities: readonly EntityRef[];
37
+ /** The overlapping, late or off-calendar part. */
38
+ range?: TimeRange;
39
+ /** Always empty; present for compatibility with `PlanningDiagnostic`. */
40
+ reasonIds: readonly string[];
41
+ }
42
+ /** `not-started`: no actual interval. `finished`: actuals and no remaining work. `in-progress`: actuals and remaining work. */
43
+ export type ActualsTaskState = 'not-started' | 'in-progress' | 'finished';
44
+ /** One task of `rescheduleFromActuals`: what happened, what remains and how it compares with the plan. */
45
+ export interface ActualsTask {
46
+ id: string;
47
+ state: ActualsTaskState;
48
+ /** The recorded actual intervals, in input order and with the input values (copies). Empty for summaries. */
49
+ actual: readonly TimeRange[];
50
+ /**
51
+ * The forecast work of the remaining work: the working segments the scheduler placed. Empty for a finished, manual or
52
+ * summary task, for a milestone, and when the schedule failed.
53
+ */
54
+ remaining: readonly TimeRange[];
55
+ /** Elapsed length of the actual intervals, overlaps counted once. For a summary, the sum over its leaf subtasks. */
56
+ performedWork: number;
57
+ /** Remaining working time that was scheduled. 0 for finished and manual tasks; a summary sums its leaf subtasks. */
58
+ remainingWork: number;
59
+ /**
60
+ * The forecast dates: from the first actual start (or the forecast start of an unstarted task) to the forecast finish
61
+ * (or the last actual end of a finished task). When the schedule failed, the span of the actuals; absent without them.
62
+ */
63
+ start?: number;
64
+ end?: number;
65
+ /** The dates of the same task in `plan`, when the plan succeeded. */
66
+ plan?: TimeRange;
67
+ /** Parts of the actual intervals outside the task's working time (calendar after pauses), merged and sorted. */
68
+ offCalendar: readonly TimeRange[];
69
+ parentId?: string;
70
+ summary?: true;
71
+ manual?: true;
72
+ }
73
+ /** The result of `rescheduleFromActuals`; `ok` is `schedule.ok`, so checking it narrows `schedule`. */
74
+ export type RescheduleFromActualsResult = RescheduleFromActualsFields & {
75
+ ok: true;
76
+ schedule: ScheduleSuccess;
77
+ } | RescheduleFromActualsFields & {
78
+ ok: false;
79
+ schedule: ScheduleFailure;
80
+ };
81
+ /** The fields of `RescheduleFromActualsResult`. */
82
+ export interface RescheduleFromActualsFields {
83
+ ok: boolean;
84
+ statusDate: number;
85
+ /**
86
+ * The forecast schedule: a `ScheduleResult` for the same tasks and links. A started task spans from its first actual
87
+ * start to its forecast finish, and its `work` lists its actual intervals (sorted by start) and then its remaining
88
+ * work; its latest dates and float describe the remaining work. A finished task has its actual span, latest dates equal
89
+ * to its dates, no float and is not critical. A failure names tasks and links of the input.
90
+ */
91
+ schedule: ScheduleResult;
92
+ /** `scheduleTasks(input)`: the original plan, for comparison. */
93
+ plan: ScheduleResult;
94
+ /** One entry per active task, in input order. Inactive tasks are left out. */
95
+ tasks: readonly ActualsTask[];
96
+ /**
97
+ * The actuals diagnostics, task by task in input order, then `toPlanningDiagnostics(schedule)`: an infeasible or
98
+ * cyclic forecast, or the manual conflicts of a successful one.
99
+ */
100
+ diagnostics: readonly (ActualsDiagnostic | PlanningDiagnostic)[];
101
+ }
102
+ /**
103
+ * Reschedule a plan from recorded actual intervals at a status date. Unlike `rescheduleFromStatusDate`, which derives
104
+ * done work from a progress share and the plan, the actual intervals are facts: they are never moved, clipped to a
105
+ * calendar or merged with the forecast. Only the remaining work is scheduled, by the same rules as `scheduleTasks`.
106
+ *
107
+ * - **Not started** (no entry, or no intervals): the task starts no earlier than the status date, in addition to its
108
+ * own bounds and links. An explicit `remainingWork` replaces its duration.
109
+ * - **In progress** (intervals and remaining work): the remaining work starts no earlier than the status date or the
110
+ * last actual end, whichever is later, on the task's calendar and pauses. As in `rescheduleFromStatusDate`, its start
111
+ * has happened: its `startNoEarlierThan`, `startNoLaterThan`, `fixedStart`, `mode`, incoming FS and SS links and the
112
+ * start bounds inherited from its summaries no longer apply. Incoming FF and SF links, finish bounds and the deadline
113
+ * still bind the finish, so the remaining work may resume later. Outgoing links use the first actual start (SS, SF)
114
+ * and the forecast finish (FS, FF).
115
+ * - **Finished** (`finished`, or no remaining work): the task spans its actuals and ignores every incoming link and
116
+ * bound except the project deadline, like a manual task. Successors follow its last actual end.
117
+ *
118
+ * Manual tasks keep their manual dates; their actuals are reported and checked but do not move them. Summary tasks
119
+ * roll up the actual and forecast dates of their subtasks. Entries of inactive tasks are validated and ignored.
120
+ *
121
+ * Contradictions are returned as diagnostics: overlapping intervals of one task, intervals after the status date (the
122
+ * forecast then starts after them), intervals outside working time (kept as recorded) and a finished task with positive
123
+ * `remainingWork` (its `remainingWork` is scheduled). A forecast that cannot meet a bound or link is returned as the
124
+ * failure in `schedule` and as a diagnostic, with the actuals still in `tasks`. Throws a RangeError for a status date
125
+ * that is not finite, aligned or inside `input.range`, for an actual interval that is not finite, aligned with the
126
+ * horizon and quantum, of positive length or inside `input.range` (the scheduler's messages for the same defects in its
127
+ * input, followed by ` (actual interval of task <id>)`), and for an invalid `remainingWork`; and an Error for actuals
128
+ * that are not a Map, an unknown or summary task, an entry without an intervals array, an invalid `finished` flag and a
129
+ * finished task without intervals. The arguments are not modified.
130
+ */
131
+ export declare function rescheduleFromActuals(input: ScheduleInput, statusDate: number, actuals: ReadonlyMap<string, TaskActuals>): RescheduleFromActualsResult;
132
+ /** Options of `actualsTimelineBars`. */
133
+ export interface ActualsTimelineBarOptions {
134
+ /** The bar label of a task; the part is appended, as in "Cut A · actual". Default: the task ID. */
135
+ label?: (taskId: string) => string;
136
+ /** The row of a task. Default: the task ID. */
137
+ rowId?: (taskId: string) => string;
138
+ /** The bar ID of one part of a task. Default: `taskId + ':' + part`. */
139
+ barId?: (taskId: string, part: 'actual' | 'forecast') => string;
140
+ /** Words appended to the label of each part. Defaults "actual" and "forecast". */
141
+ partLabels?: {
142
+ actual?: string;
143
+ forecast?: string;
144
+ };
145
+ /** Bar descriptions of each part. Defaults "Recorded actual work" and "Remaining work forecast". */
146
+ descriptions?: {
147
+ actual?: string;
148
+ forecast?: string;
149
+ };
150
+ /** Tones of each part. Defaults: `teal` for actual work and `blue` for the forecast. */
151
+ tones?: {
152
+ actual?: ChartTone;
153
+ forecast?: ChartTone;
154
+ };
155
+ /**
156
+ * The baseline set that carries the original plan on the first bar of each task. Default: `timelineBaselineId`, the
157
+ * unnamed `baseline`; any other ID adds a named entry to `baselines`. `false` adds none.
158
+ */
159
+ baselineId?: string | false;
160
+ }
161
+ /**
162
+ * Project a `rescheduleFromActuals` result into GanttChart bars, so that one row shows the original plan, the recorded
163
+ * actuals and the remaining forecast. Each task with actuals gets a solid "actual" bar spanning them, with their merged
164
+ * intervals as `segments` when there are several; each task with work still to do, and each unstarted or manual task,
165
+ * gets an outline "forecast" bar with its remaining work segments. Solid and outline differ without colour, also in
166
+ * forced colours. The plan dates become a baseline of the first bar of the task. Summary tasks get no bar: show their
167
+ * rows with GanttChart `showSummaries`, which rolls up the bars of their subtasks. Without a successful schedule, only
168
+ * actual bars are returned. The result is not modified.
169
+ */
170
+ export declare function actualsTimelineBars(result: RescheduleFromActualsResult, options?: ActualsTimelineBarOptions): TimelineBar[];
@@ -0,0 +1,65 @@
1
+ import { type TimeRange } from './timeline.js';
2
+ import type { TimelineBand, TimelineZoomPreset } from './types.js';
3
+ export interface IntlTimeFormatterOptions {
4
+ /**
5
+ * BCP 47 locale (or list). Default `en-US`. The runtime's default locale is never used, so server and client render
6
+ * the same text for the same locale, time zone and options.
7
+ */
8
+ locale?: string | readonly string[];
9
+ /** IANA time zone such as `Europe/Berlin`. Default `UTC`. Cannot be combined with `utcOffsetMinutes`. */
10
+ timeZone?: string;
11
+ /**
12
+ * Fixed offset from UTC in minutes, without daylight-saving rules. Cannot be combined with `timeZone`. A
13
+ * `timeZoneName` in `format` then reads as UTC, because the shifted time is formatted in UTC.
14
+ */
15
+ utcOffsetMinutes?: number;
16
+ /**
17
+ * `Intl.DateTimeFormat` options. Default `{ hour: '2-digit', minute: '2-digit', hourCycle: 'h23' }` (`09:00`). Its
18
+ * `timeZone` is ignored; use the `timeZone` option.
19
+ */
20
+ format?: Intl.DateTimeFormatOptions;
21
+ }
22
+ /**
23
+ * A `formatTime`-compatible function based on a cached `Intl.DateTimeFormat`. The output depends only on the time and
24
+ * the options (and the runtime's Intl data), never on the runtime's default locale or time zone, so it is safe for
25
+ * server rendering. Throws RangeError for an invalid time zone, offset, locale or non-finite time.
26
+ */
27
+ export declare function intlTimeFormatter(options?: IntlTimeFormatterOptions): (time: number) => string;
28
+ /** A zoom level of `calendarZoomPresets`, from finest to coarsest. */
29
+ export type CalendarZoomLevel = 'hours' | 'days' | 'weeks' | 'months' | 'quarters' | 'years';
30
+ export interface CalendarZoomPresetOptions {
31
+ /** Locale of the band and tick labels. Default `en-US` (never the runtime's default locale). */
32
+ locale?: string | readonly string[];
33
+ /** IANA time zone of the calendar. Default UTC. Cannot be combined with `utcOffsetMinutes`. */
34
+ timeZone?: string;
35
+ /** Fixed offset from UTC in minutes. Cannot be combined with `timeZone`. */
36
+ utcOffsetMinutes?: number;
37
+ /** First day of a week band, 0 = Sunday to 6 = Saturday. Default 1 (Monday). */
38
+ weekStartsOn?: number;
39
+ /** Levels to return, in this order, without duplicates. Default all six, finest first. */
40
+ levels?: readonly CalendarZoomLevel[];
41
+ /** Preset button labels by level. Defaults: Hours, Days, Weeks, Months, Quarters, Years. */
42
+ labels?: Partial<Record<CalendarZoomLevel, string>>;
43
+ }
44
+ /** A `TimelineZoomPreset` for one calendar level, with every optional field filled and a matching tick formatter. */
45
+ export interface CalendarZoomPreset extends TimelineZoomPreset {
46
+ /** The level, also used as the preset `id`. */
47
+ id: CalendarZoomLevel;
48
+ tickSteps: readonly number[];
49
+ headerBands: readonly (readonly TimelineBand[])[];
50
+ snap: number;
51
+ /**
52
+ * Locale-aware labels for this level, for the chart's `formatTime` while the preset is active (GanttChart does not
53
+ * read it from the preset): `HH:mm` for hours; a date for the other levels, followed by the time when it is not
54
+ * local midnight.
55
+ */
56
+ formatTime: (time: number) => string;
57
+ }
58
+ /**
59
+ * Ready-made `zoomPresets` for common calendar views of `range` in epoch milliseconds: hours, days, weeks, months,
60
+ * quarters and years. Each preset has a pixel density, tick steps, snap and header bands from `calendarBands`, whose
61
+ * boundaries follow local dates in `timeZone` (so a month band across a daylight-saving change starts at local
62
+ * midnight). Ticks stay uniform elapsed-time steps from `range.start`, as GanttChart draws them; start the range on a
63
+ * band boundary to align them. Labels use `locale` (default `en-US`); quarter bands read `Q1` to `Q4`.
64
+ */
65
+ export declare function calendarZoomPresets(range: TimeRange, options?: CalendarZoomPresetOptions): CalendarZoomPreset[];
@@ -0,0 +1,96 @@
1
+ /** Where an edit transaction originated. */
2
+ export type TransactionSource = 'pointer' | 'keyboard' | 'api' | 'undo' | 'redo';
3
+ /** One atomic save request. `restore` replaces the whole document with a history snapshot. */
4
+ export type EditTransaction<P, S> = {
5
+ operationId: string;
6
+ documentId: string;
7
+ /** Opaque version the request is based on. Versions are compared for equality only. */
8
+ baseVersion: string;
9
+ source: TransactionSource;
10
+ } & ({
11
+ kind: 'changes';
12
+ changes: readonly P[];
13
+ } | {
14
+ kind: 'restore';
15
+ snapshot: S;
16
+ });
17
+ /** The server's answer to one save request. */
18
+ export type SaveResult<S> = {
19
+ status: 'accepted';
20
+ operationId: string;
21
+ version: string;
22
+ state: S;
23
+ } | {
24
+ status: 'rejected';
25
+ operationId: string;
26
+ code: string;
27
+ } | {
28
+ status: 'conflict';
29
+ operationId: string;
30
+ currentVersion: string;
31
+ } | {
32
+ status: 'uncertain';
33
+ operationId: string;
34
+ };
35
+ /** What a submit, undo, redo or reconcile call resolves to. */
36
+ export type TransactionOutcome<S> = SaveResult<S> | {
37
+ status: 'busy';
38
+ } | {
39
+ status: 'invalid';
40
+ reason: string;
41
+ } | {
42
+ status: 'discarded';
43
+ operationId: string;
44
+ };
45
+ /** Application hooks. `validate` and `apply` are synchronous and must not mutate their arguments. */
46
+ export interface TransactionAdapter<S, P> {
47
+ /** Return `false` or a reason string to reject the changes; `true` or nothing accepts them. */
48
+ validate(state: S, changes: readonly P[]): boolean | string | void;
49
+ apply(state: S, changes: readonly P[]): S;
50
+ save(request: EditTransaction<P, S>, candidate: S): Promise<SaveResult<S>>;
51
+ }
52
+ export type TransactionStatus = 'idle' | 'saving' | 'rejected' | 'conflict' | 'uncertain';
53
+ /** The in-flight (or unresolved) operation. */
54
+ export interface PendingTransaction {
55
+ operationId: string;
56
+ kind: 'changes' | 'restore';
57
+ source: TransactionSource;
58
+ baseVersion: string;
59
+ /** Epoch at the time of submission; a response is only adopted while it still matches. */
60
+ epoch: number;
61
+ }
62
+ export type TransactionFailure = Exclude<SaveResult<unknown>, {
63
+ status: 'accepted';
64
+ }>;
65
+ /** Immutable transaction state. Every transition returns a new value. */
66
+ export interface TransactionCoreState<S> {
67
+ acceptedState: S;
68
+ acceptedVersion: string;
69
+ candidateState: S | undefined;
70
+ status: TransactionStatus;
71
+ pending: PendingTransaction | undefined;
72
+ /** Last non-accepted result, kept until `clearResult`, the next submission or a refresh. */
73
+ result: TransactionFailure | undefined;
74
+ epoch: number;
75
+ /** Operation IDs committed in this epoch, used to ignore duplicate accepted responses. */
76
+ committed: readonly string[];
77
+ }
78
+ export declare function createTransactionState<S>(acceptedState: S, acceptedVersion: string): TransactionCoreState<S>;
79
+ /** Start saving. Returns `undefined` while another save is in flight for the document. */
80
+ export declare function beginTransaction<S>(state: TransactionCoreState<S>, pending: Omit<PendingTransaction, 'epoch' | 'baseVersion'>, candidate: S): TransactionCoreState<S> | undefined;
81
+ export interface SettleResult<S> {
82
+ state: TransactionCoreState<S>;
83
+ outcome: TransactionOutcome<S>;
84
+ /** The operation whose accepted state was just committed, if any. The caller records history for it. */
85
+ committed: PendingTransaction | undefined;
86
+ }
87
+ /**
88
+ * Apply a response. The response is adopted only when it answers the current pending operation in the
89
+ * current epoch; anything else changes nothing. `allowUncertain` lets reconcile settle an operation that
90
+ * ended as uncertain.
91
+ */
92
+ export declare function settleTransaction<S>(state: TransactionCoreState<S>, operationId: string, epoch: number, result: SaveResult<S>, allowUncertain?: boolean): SettleResult<S>;
93
+ /** Replace the accepted state with an externally confirmed one and invalidate all in-flight responses. */
94
+ export declare function refreshTransactionState<S>(state: TransactionCoreState<S>, acceptedState: S, acceptedVersion: string): TransactionCoreState<S>;
95
+ /** Dismiss a rejected, conflict or uncertain result. Never changes the accepted input. */
96
+ export declare function clearTransactionResult<S>(state: TransactionCoreState<S>): TransactionCoreState<S>;