@marianmeres/stuic 3.187.0 → 3.189.0

package/dist/components/Gantt/Gantt.svelte.d.ts

@@ -0,0 +1,134 @@
+import type { HTMLAttributes } from "svelte/elements";
+import type { Snippet } from "svelte";
+import type { Weekday } from "@marianmeres/calendar-utils";
+import type { THC } from "../Thc/Thc.svelte";
+import type { IntentColorKey } from "../../utils/design-tokens.js";
+import type { GanttAxis, GanttColumn, GanttDateInput, GanttGroup, GanttPlacement, GanttUnit } from "./gantt-geometry.js";
+/** Where a bar's own label is drawn. */
+export type GanttBarLabels = "inside" | "after" | "none";
+/** One bar (or milestone) on a row's track. */
+export interface GanttBar {
+    /** Stable key — falls back to the index, which is fine for a static list. */
+    id?: string;
+    /** First day, inclusive. `YYYY-MM-DD`, or a `Date` (its **local** calendar date). */
+    from: GanttDateInput;
+    /** Last day, **inclusive**. Omitted = a single day. */
+    to?: GanttDateInput;
+    /** Text on the bar (see `barLabels`) */
+    label?: THC;
+    /** Semantic color */
+    intent?: IntentColorKey;
+    /** `0`–`1` — a darker fill from the bar's start ("% complete") */
+    progress?: number;
+    /** Draw a diamond at `from` instead of a bar (`to` is ignored) */
+    milestone?: boolean;
+    /** Draw thinner and on top — an emphasis range inside a wider bar of the same row */
+    inset?: boolean;
+    /** Renders the bar as a link */
+    href?: string;
+    /** Native tooltip (`title`) — the cheap way to show the detail a bar has no room for */
+    title?: string;
+    /** Not clickable, dimmed */
+    disabled?: boolean;
+    /** Additional classes for this bar */
+    class?: string;
+    /** Anything of yours — handed back by `onSelect` */
+    data?: unknown;
+}
+/** One lane of the chart: a label on the left, any number of bars on its track. */
+export interface GanttRow {
+    /** Stable key — falls back to the index */
+    id?: string;
+    /** The left column's primary line */
+    label?: THC;
+    /** Secondary line under the label */
+    description?: THC;
+    /** The row's bars — one for a classic task, several for a resource lane */
+    bars: GanttBar[];
+    /** Renders the row label as a link */
+    href?: string;
+    /** Anything of yours — handed back by `onSelect` */
+    data?: unknown;
+}
+/** What `onSelect` (and the `renderBar` snippet) receives. */
+export interface GanttSelectDetail {
+    bar: GanttBar;
+    row: GanttRow;
+    rowIndex: number;
+    barIndex: number;
+    /** The bar's track geometry, or `null` for a milestone (see `point`) */
+    placement: GanttPlacement | null;
+    /** A milestone's 0..1 position on the track, or `null` for a bar */
+    point: number | null;
+}
+export interface Props extends Omit<HTMLAttributes<HTMLDivElement>, "children"> {
+    /** The lanes, in display order (sort them yourself) */
+    rows: GanttRow[];
+    /** Window start, inclusive. Default: the earliest date in `rows` */
+    from?: GanttDateInput;
+    /** Window end, inclusive. Default: the latest date in `rows` */
+    to?: GanttDateInput;
+    /** Column granularity. `week`/`month` snap the window outwards to whole units */
+    unit?: GanttUnit;
+    /** First day of a week for `unit="week"` (1 = Monday … 7 = Sunday) */
+    weekStartsOn?: Weekday;
+    /** BCP 47 tag for month/weekday names and the default `aria-label`s */
+    locale?: string;
+    /** The day the marker line sits on. `null` removes it. Default: today */
+    today?: GanttDateInput | null;
+    /**
+     * MINIMUM column width in px (the horizontal zoom). The chart always fills its
+     * parent; when the axis needs less than that, the columns share out the rest.
+     * When it needs more, the frame scrolls horizontally.
+     *
+     * `"fit"` drops the minimum: the columns always divide the available width, so
+     * the chart never scrolls horizontally however many of them there are.
+     *
+     * Default: the `--stuic-gantt-unit-width` token.
+     */
+    unitWidth?: number | "fit";
+    /** Show the left label column. Default: whenever any row has a label */
+    labels?: boolean;
+    /** Where a bar's own `label` is drawn */
+    barLabels?: GanttBarLabels;
+    /** Fires on a bar click (and Enter/Space) — also what makes bars focusable */
+    onSelect?: (detail: GanttSelectDetail) => void;
+    /** Override a unit cell's header text */
+    formatColumn?: (column: GanttColumn, axis: GanttAxis) => string;
+    /** Override a group cell's header text (the month over its days, the year over its months) */
+    formatGroup?: (group: GanttGroup, axis: GanttAxis) => string;
+    /** Override a bar's accessible name */
+    formatBarAria?: (detail: GanttSelectDetail) => string;
+    /** Override the whole bar body (progress, label) */
+    renderBar?: Snippet<[GanttSelectDetail]>;
+    /** Override the left column's cell */
+    renderRowLabel?: Snippet<[{
+        row: GanttRow;
+        index: number;
+    }]>;
+    /** The header's top-left cell (above the labels) */
+    renderCorner?: Snippet<[{
+        axis: GanttAxis;
+    }]>;
+    /** Shown in place of the rows when `rows` is empty (the axis still renders) */
+    empty?: Snippet;
+    /** Skip all default styling */
+    unstyled?: boolean;
+    /** Additional CSS classes */
+    class?: string;
+    /** Class for the sticky header */
+    classHeader?: string;
+    /** Class for every row */
+    classRow?: string;
+    /** Class for every left-column cell */
+    classRowLabel?: string;
+    /** Class for every row's track */
+    classTrack?: string;
+    /** Class for every bar */
+    classBar?: string;
+    /** Bindable element reference */
+    el?: HTMLElement;
+}
+declare const Gantt: import("svelte").Component<Props, {}, "el">;
+type Gantt = ReturnType<typeof Gantt>;
+export default Gantt;

package/dist/components/Gantt/README.md

@@ -0,0 +1,298 @@
+# Gantt
+
+Horizontal schedule chart: a shared time axis across the top, one lane per row,
+and bars for the ranges each lane occupies. The classic project plan (task per
+row, progress, milestones), but the same component also draws resource lanes —
+a row can hold any number of bars.
+
+Everything is **whole-day and inclusive at both ends**: `from: "2026-09-01",
+to: "2026-09-03"` is three days, and no timezone can shift a bar by one. Columns
+can be days, weeks or months; bars are positioned through the columns, so a
+February column is the same width as March while still holding fewer days.
+
+Read-only by design — there is no drag-to-reschedule and no dependency arrows.
+For a vertical event list (activity feeds, audit logs) use `Timeline` instead.
+
+## Props
+
+| Prop            | Type                                  | Default    | Description                                                           |
+| --------------- | ------------------------------------- | ---------- | --------------------------------------------------------------------- |
+| `rows`          | `GanttRow[]`                          | required   | The lanes, in display order (sort them yourself)                      |
+| `from`          | `string \| Date`                      | -          | Window start, inclusive. Default: the earliest date in `rows`         |
+| `to`            | `string \| Date`                      | -          | Window end, inclusive. Default: the latest date in `rows`             |
+| `unit`          | `"day" \| "week" \| "month"`          | `"day"`    | Column granularity; `week`/`month` snap the window out to whole units |
+| `weekStartsOn`  | `1`–`7`                               | `1`        | First day of a week for `unit="week"` (1 = Monday … 7 = Sunday)       |
+| `locale`        | `string`                              | -          | BCP 47 tag for month/weekday names and the default `aria-label`s      |
+| `today`         | `string \| Date \| null`              | today      | The day the marker line sits on; `null` removes it                    |
+| `unitWidth`     | `number \| "fit"`                     | token      | **Minimum** column width in px (the zoom); `"fit"` drops the minimum  |
+| `labels`        | `boolean`                             | auto       | Show the left label column; defaults to on when any row has a `label` |
+| `barLabels`     | `"inside" \| "after" \| "none"`       | `"inside"` | Where a bar's own `label` is drawn                                    |
+| `onSelect`      | `(detail: GanttSelectDetail) => void` | -          | Bar click / Enter / Space — also what makes bars focusable buttons    |
+| `formatColumn`  | `(column, axis) => string`            | -          | Override a unit cell's header text                                    |
+| `formatGroup`   | `(group, axis) => string`             | -          | Override a group cell's header text                                   |
+| `formatBarAria` | `(detail) => string`                  | -          | Override a bar's accessible name                                      |
+| `unstyled`      | `boolean`                             | `false`    | Skip all default styling (the `data-*` contract stays)                |
+| `class`         | `string`                              | -          | Additional CSS classes (merged via twMerge)                           |
+| `classHeader`   | `string`                              | -          | Class for the sticky header                                           |
+| `classRow`      | `string`                              | -          | Class for every row                                                   |
+| `classRowLabel` | `string`                              | -          | Class for every left-column cell                                      |
+| `classTrack`    | `string`                              | -          | Class for every row's track                                           |
+| `classBar`      | `string`                              | -          | Class for every bar                                                   |
+| `el`            | `HTMLElement`                         | -          | Element reference (bindable)                                          |
+
+Any other attribute (`aria-label`, `style`, `data-*`, …) is passed to the root `<div>`.
+
+### `GanttRow`
+
+| Field         | Type         | Description                                                   |
+| ------------- | ------------ | ------------------------------------------------------------- |
+| `bars`        | `GanttBar[]` | The row's ranges — one for a classic task, several for a lane |
+| `id`          | `string`     | Stable key (falls back to the index)                          |
+| `label`       | `THC`        | The left column's primary line                                |
+| `description` | `THC`        | Secondary line under the label                                |
+| `href`        | `string`     | Renders the row label as a link                               |
+| `data`        | `unknown`    | Anything of yours — handed back by `onSelect`                 |
+
+### `GanttBar`
+
+| Field       | Type             | Description                                                               |
+| ----------- | ---------------- | ------------------------------------------------------------------------- |
+| `from`      | `string \| Date` | First day, inclusive. `YYYY-MM-DD`, or a `Date` (its **local** date)      |
+| `to`        | `string \| Date` | Last day, **inclusive**. Omitted = a single day                           |
+| `label`     | `THC`            | Text on the bar (see `barLabels`)                                         |
+| `intent`    | `IntentColorKey` | `"primary" \| "accent" \| "success" \| "warning" \| "destructive"`        |
+| `progress`  | `number`         | `0`–`1` — a darker fill from the bar's start ("% complete"); clamped      |
+| `milestone` | `boolean`        | Draw a diamond at `from` instead of a bar (`to` is ignored)               |
+| `inset`     | `boolean`        | Draw thinner and on top — an emphasis range inside a wider bar of the row |
+| `href`      | `string`         | Renders the bar as a link                                                 |
+| `title`     | `string`         | Native tooltip — the cheap way to show what a bar has no room for         |
+| `disabled`  | `boolean`        | Not clickable, dimmed                                                     |
+| `id`        | `string`         | Stable key (falls back to the index)                                      |
+| `class`     | `string`         | Additional classes for this bar                                           |
+| `data`      | `unknown`        | Anything of yours — handed back by `onSelect`                             |
+
+A bar that falls entirely outside the window is **dropped**, not pinned to the
+edge — a hairline at the window's edge reads as "starts today", which is exactly
+the wrong thing to tell a planner. A bar that only overhangs is clipped and
+flagged with `data-clipped-start` / `data-clipped-end` (squared-off corners).
+
+## Snippet Props
+
+| Snippet          | Argument            | Description                                                             |
+| ---------------- | ------------------- | ----------------------------------------------------------------------- |
+| `renderBar`      | `GanttSelectDetail` | Override the whole bar body (progress, label)                           |
+| `renderRowLabel` | `{ row, index }`    | Override the left column's cell                                         |
+| `renderCorner`   | `{ axis }`          | The header's top-left cell, above the labels                            |
+| `empty`          | –                   | Shown instead of the rows when `rows` is empty (the axis still renders) |
+
+`GanttSelectDetail` is `{ bar, row, rowIndex, barIndex, placement, point }` —
+`placement` is `{ start, end, clippedStart, clippedEnd, days }` in 0..1 track
+fractions for a bar, and `point` is the 0..1 position of a milestone. Exactly one
+of the two is set.
+
+## Usage
+
+### A project plan
+
+```svelte
+<script lang="ts">
+	import { Gantt, type GanttRow } from "@marianmeres/stuic";
+
+	const rows: GanttRow[] = [
+		{
+			label: "Design",
+			description: "2 people",
+			bars: [
+				{
+					from: "2026-09-07",
+					to: "2026-09-18",
+					label: "Wireframes",
+					intent: "primary",
+					progress: 0.65,
+				},
+			],
+		},
+		{
+			label: "Build",
+			bars: [
+				{
+					from: "2026-09-15",
+					to: "2026-10-09",
+					label: "Implementation",
+					intent: "primary",
+				},
+			],
+		},
+		{
+			label: "Launch",
+			bars: [
+				{ from: "2026-10-15", milestone: true, label: "Go live", intent: "success" },
+			],
+		},
+	];
+</script>
+
+<Gantt {rows} onSelect={(d) => console.log(d.row.label, d.bar.from)} />
+```
+
+### Resource lanes (several bars per row)
+
+`inset` draws a thinner bar on top of a wider one — the wide bar is the whole
+occupancy, the thin one the part that matters.
+
+```svelte
+<Gantt
+	rows={[
+		{
+			label: "Truck #1",
+			bars: [
+				{
+					from: "2026-09-02",
+					to: "2026-09-06",
+					intent: "primary",
+					title: "Job A — out to return",
+				},
+				{
+					from: "2026-09-03",
+					to: "2026-09-05",
+					intent: "success",
+					inset: true,
+					title: "Job A — event days",
+				},
+			],
+		},
+	]}
+	from="2026-09-01"
+	to="2026-09-14"
+/>
+```
+
+### Zoom, scales and fitting
+
+```svelte
+<!-- a bindable zoom -->
+<input type="range" min="12" max="80" bind:value={unitWidth} />
+<Gantt {rows} {unitWidth} />
+
+<!-- coarser scales; the window snaps out to whole weeks / months -->
+<Gantt {rows} unit="week" weekStartsOn={7} />
+<Gantt {rows} unit="month" unitWidth={90} barLabels="none" />
+
+<!-- no horizontal scroll: the columns divide the available width -->
+<Gantt {rows} unitWidth="fit" barLabels="after" />
+```
+
+The chart always fills its parent. `unitWidth` is a **minimum**: when the axis
+needs less width than the frame has, the columns share out what is left — so there
+is never a dead gutter to the right of the last column — and when it needs more,
+the frame scrolls horizontally. `unitWidth="fit"` drops the minimum entirely: the
+columns always divide the available width, so the chart never scrolls sideways.
+
+Bar labels that sit past their bar (`barLabels="after"`, and every milestone
+label) are clipped at the chart's right edge rather than extending the scroll
+area — a label is never worth a scrollbar on a chart that otherwise fits.
+
+### Sticky header
+
+The header is already `position: sticky`; give the chart a height and it sticks
+while the rows scroll under it. The left label column is sticky horizontally at
+all times.
+
+```svelte
+<Gantt {rows} style="--stuic-gantt-max-height: 20rem;" />
+```
+
+### Empty
+
+```svelte
+<Gantt rows={[]} from="2026-09-01" to="2026-09-21">
+	{#snippet empty()}
+		<EmptyState title="Nothing planned" description="Widen the window." />
+	{/snippet}
+</Gantt>
+```
+
+## Geometry helpers
+
+The date → track math is a separate, browser-free module, exported for building
+your own axis-aligned overlays (a "capacity" strip, a legend, a print layout):
+
+```ts
+import { buildGanttAxis, placeRange, placePoint } from "@marianmeres/stuic";
+
+const axis = buildGanttAxis("2026-09-01", "2026-09-30", { unit: "day" });
+placeRange("2026-09-03", "2026-09-04", axis);
+// → { start: 0.0666…, end: 0.1333…, clippedStart: false, clippedEnd: false, days: 2 }
+placePoint("2026-09-15", axis); // → 0.4833… (the middle of that day)
+```
+
+`buildGanttAxis` **throws** on an unparseable or backwards window, and on one
+that would need more than `GANTT_MAX_COLUMNS` (2000) columns — at that zoom
+nothing is readable, and quietly building 100k nodes is worse than saying so.
+
+## Accessibility
+
+- A bar with `onSelect` renders as a `<button>` (focusable, Enter/Space), with
+  `href` as an `<a>`, and otherwise as a `<span role="img">`.
+- Every bar gets an `aria-label` built from the row and bar labels plus the
+  localized date range — only plain-string labels can contribute, so give
+  html/component labels a `title` or use `formatBarAria`.
+- The gridlines, weekend shading and the today line are `aria-hidden`.
+
+## CSS Variables
+
+| Variable                              | Default                          | Description                       |
+| ------------------------------------- | -------------------------------- | --------------------------------- |
+| `--stuic-gantt-unit-width`            | `2.5rem`                         | One column (the horizontal zoom)  |
+| `--stuic-gantt-label-width`           | `12rem`                          | The sticky left column            |
+| `--stuic-gantt-row-height`            | `2.5rem`                         | Minimum row height                |
+| `--stuic-gantt-max-height`            | `none`                           | Set it to get a sticky header     |
+| `--stuic-gantt-bg`                    | `--stuic-color-background`       | Frame background                  |
+| `--stuic-gantt-border-color`          | `--stuic-color-border`           | Frame, row and column borders     |
+| `--stuic-gantt-font-size`             | `--text-base`                    | Base size                         |
+| `--stuic-gantt-header-bg`             | `--stuic-color-surface`          | Both header tiers                 |
+| `--stuic-gantt-header-text`           | `--stuic-color-foreground`       | Header text                       |
+| `--stuic-gantt-header-font-size`      | `--text-xs`                      | Header text size                  |
+| `--stuic-gantt-header-padding`        | `0.25rem 0.375rem`               | Header cell padding               |
+| `--stuic-gantt-header-sub-text`       | `--stuic-color-muted-foreground` | Weekday / week-number line        |
+| `--stuic-gantt-grid-line-color`       | `--stuic-color-border`           | Column separators                 |
+| `--stuic-gantt-weekend-bg`            | `--stuic-color-muted`            | Saturday/Sunday shading           |
+| `--stuic-gantt-today-color`           | `--stuic-color-destructive`      | Today line and header flag        |
+| `--stuic-gantt-today-width`           | `2px`                            | Today line thickness              |
+| `--stuic-gantt-row-bg-hover`          | translucent muted                | Row hover (keeps shading visible) |
+| `--stuic-gantt-label-bg`              | `--stuic-color-background`       | Left column (must stay opaque)    |
+| `--stuic-gantt-label-padding`         | `0.375rem 0.75rem`               | Left column padding               |
+| `--stuic-gantt-label-font-size`       | `--text-base`                    | Row title size                    |
+| `--stuic-gantt-label-text`            | `--stuic-color-foreground`       | Row title color                   |
+| `--stuic-gantt-description-font-size` | `--text-xs`                      | Row description size              |
+| `--stuic-gantt-description-text`      | `--stuic-color-muted-foreground` | Row description color             |
+| `--stuic-gantt-bar-height`            | `1.25rem`                        | Bar height                        |
+| `--stuic-gantt-bar-height-inset`      | `0.625rem`                       | `inset` bar height                |
+| `--stuic-gantt-bar-bg`                | `--stuic-color-muted-foreground` | Bar fill (per-intent overrides)   |
+| `--stuic-gantt-bar-text`              | `--stuic-color-background`       | Bar label color                   |
+| `--stuic-gantt-bar-font-size`         | `--text-xs`                      | Bar label size                    |
+| `--stuic-gantt-bar-padding-inline`    | `0.375rem`                       | Bar label inset                   |
+| `--stuic-gantt-bar-progress-bg`       | bar color, darkened              | The `progress` fill               |
+| `--stuic-gantt-bar-opacity-disabled`  | `0.45`                           | Disabled bar                      |
+| `--stuic-gantt-milestone-size`        | `0.875rem`                       | Diamond size                      |
+| `--stuic-gantt-empty-padding`         | `2rem 1rem`                      | Empty area padding                |
+
+Structural tokens are resolved as fallbacks at the usage sites, so
+`--stuic-gantt-radius` → `--stuic-radius-container` (the frame),
+`--stuic-gantt-bar-radius` → `--stuic-radius` (bars),
+`--stuic-gantt-border-width` → `--stuic-border-width`, and
+`--stuic-gantt-transition` → `--stuic-transition`.
+
+## Data attributes
+
+Kept in `unstyled` mode too — they describe the data, not the styling.
+
+| Element           | Attributes                                                                                                              |
+| ----------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| root              | `data-unit`, `data-fit`, `data-labels`, `data-bar-labels`                                                               |
+| header group cell | `data-group` (`"2026-09"` / `"2026"`)                                                                                   |
+| header unit cell  | `data-date`, `data-weekend`, `data-today`                                                                               |
+| gridline          | `data-weekend`, `data-today`                                                                                            |
+| today line        | `data-today-marker`                                                                                                     |
+| row               | `data-row-id`                                                                                                           |
+| bar               | `data-kind` (`bar`/`milestone`), `data-intent`, `data-inset`, `data-disabled`, `data-clipped-start`, `data-clipped-end` |

package/dist/components/Gantt/gantt-geometry.d.ts

@@ -0,0 +1,131 @@
+/**
+ * The Gantt's geometry: a date window in, columns and 0..1 track fractions out.
+ *
+ * Kept out of the component (and out of the browser) on purpose — everything
+ * that could be wrong by a day is decided here, in plain functions a node test
+ * can pin. The component only multiplies fractions by a width.
+ *
+ * Whole-day semantics throughout (`YYYY-MM-DD`, both ends inclusive), so a bar
+ * never shifts by a day because the visitor is in Auckland. The day arithmetic
+ * reuses `Calendar/iso-date.js`, which is DST-safe via `@marianmeres/calendar-utils`.
+ */
+import type { Weekday } from "@marianmeres/calendar-utils";
+import { type IsoDate } from "../Calendar/iso-date.js";
+/** Column granularity of the time axis. */
+export type GanttUnit = "day" | "week" | "month";
+/** What a consumer may hand in as a date — normalized via `normalizeIsoDate`. */
+export type GanttDateInput = IsoDate | Date;
+/** One cell of the axis' bottom (unit) header row, and one background gridline. */
+export interface GanttColumn {
+    /** The column's first calendar day, `YYYY-MM-DD`. */
+    date: IsoDate;
+    /** Calendar days the column covers (1 / 7 / 28–31). */
+    days: number;
+    /** Days from the axis' first day to this column's first day. */
+    offset: number;
+    /** Position in `axis.columns`. */
+    index: number;
+    /** Primary header label (day of month, or the month name for `unit: "month"`). */
+    label: string;
+    /** Secondary header label (weekday for days, ISO-ish week number for weeks). */
+    subLabel?: string;
+    /** Index into `axis.groups` — the top header row this column sits under. */
+    groupIndex: number;
+    /** Saturday or Sunday (`unit: "day"` only — a week/month column is never one). */
+    isWeekend: boolean;
+    /** The column contains `today`. */
+    isToday: boolean;
+}
+/** One cell of the axis' top header row — the month over its days, the year over its months. */
+export interface GanttGroup {
+    /** Stable key (`"2026-09"` / `"2026"`). */
+    key: string;
+    label: string;
+    /** Columns the cell spans. */
+    span: number;
+    /** Index of the first column it spans. */
+    from: number;
+}
+export interface GanttAxis {
+    unit: GanttUnit;
+    /** The window as asked for. */
+    from: IsoDate;
+    to: IsoDate;
+    /**
+     * The window as drawn. For `week`/`month` it is snapped outwards to whole
+     * units — a half-drawn week column would put its label on a lie.
+     */
+    start: IsoDate;
+    end: IsoDate;
+    columns: GanttColumn[];
+    groups: GanttGroup[];
+    /** Calendar days from `start` to `end`, inclusive. */
+    totalDays: number;
+}
+/** A range's position on the track, as 0..1 fractions of the axis' full width. */
+export interface GanttPlacement {
+    /** Left edge, 0..1. */
+    start: number;
+    /** Right edge, 0..1 (always `> start`). */
+    end: number;
+    /** The range begins before the axis — the component squares off that end. */
+    clippedStart: boolean;
+    clippedEnd: boolean;
+    /** Inclusive day count of the *visible* part. */
+    days: number;
+}
+export interface GanttAxisOptions {
+    unit?: GanttUnit;
+    /** First day of a week for `unit: "week"` (1 = Monday … 7 = Sunday). */
+    weekStartsOn?: Weekday;
+    /** BCP 47 tag for the month and weekday names; `undefined` = the runtime's. */
+    locale?: string;
+    /** The day to flag as today, or `null` for none. */
+    today?: IsoDate | null;
+}
+/** Cap on generated columns — a mistyped year would otherwise build 700k of them. */
+export declare const GANTT_MAX_COLUMNS = 2000;
+/** ISO-8601 week number of `iso` (weeks start Monday; week 1 holds the first Thursday). */
+export declare function isoWeekNumber(iso: IsoDate): number;
+/**
+ * The columns and the two header rows for a `[from, to]` window (both inclusive).
+ *
+ * Throws on an unparseable window, and on one so wide it would exceed
+ * {@link GANTT_MAX_COLUMNS} columns — at that zoom nothing is readable anyway,
+ * and silently drawing 100k nodes is worse than saying so.
+ */
+export declare function buildGanttAxis(from: GanttDateInput, to: GanttDateInput, options?: GanttAxisOptions): GanttAxis;
+/**
+ * Where a day offset sits on the track, 0..1.
+ *
+ * Columns all render at the same width but do not all cover the same number of
+ * days (February against March), so this maps through the column the offset
+ * falls in rather than dividing by `totalDays`. Fractional offsets are allowed
+ * — `offset + 0.5` is the middle of that day.
+ */
+export declare function dayToFraction(offset: number, axis: GanttAxis): number;
+/**
+ * A `[from, to]` inclusive range as a track placement, or `null` when it misses
+ * the axis entirely.
+ *
+ * A miss is `null` rather than a zero-width bar on purpose: a hairline pinned to
+ * the window's edge reads as "starts today", which is exactly the wrong thing to
+ * tell a planner.
+ */
+export declare function placeRange(from: GanttDateInput, to: GanttDateInput, axis: GanttAxis): GanttPlacement | null;
+/**
+ * The middle of a single day as a 0..1 fraction (milestones, the today line), or
+ * `null` when the day is outside the axis.
+ */
+export declare function placePoint(date: GanttDateInput, axis: GanttAxis): number | null;
+/**
+ * The `[min, max]` of every date in `ranges` — what the axis defaults to when
+ * the consumer gives no explicit window. `null` when nothing is datable.
+ */
+export declare function boundsOf(ranges: Iterable<{
+    from?: GanttDateInput;
+    to?: GanttDateInput;
+}>): {
+    from: IsoDate;
+    to: IsoDate;
+} | null;