@getdom/studio 0.1.1 → 0.2.0

package/src/pages/data/gantt/ganttTime.js

@@ -0,0 +1,223 @@
+import { resolveResourceKey, resolveResourceValue } from '../_shared/resourceRecord.js';
+
+/**
+ * Parses an instant or local calendar date without interpreting YYYY-MM-DD as UTC.
+ * Invalid, missing, and overflowing calendar dates return null.
+ * @param {unknown} value Date, timestamp, or ISO-compatible string.
+ * @returns {Date|null} Independent valid date.
+ */
+export function parseGanttDate(value) {
+	if (value === null || value === undefined || value === '') return null;
+	let date;
+	if (typeof value === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(value)) {
+		const [year, month, day] = value.split('-').map(Number);
+		date = new Date(year, month - 1, day);
+		if (date.getFullYear() !== year || date.getMonth() !== month - 1 || date.getDate() !== day) return null;
+	} else if (value instanceof Date || typeof value === 'string' || typeof value === 'number') {
+		date = new Date(value);
+	}
+	return date && Number.isFinite(date.getTime()) ? date : null;
+}
+
+/**
+ * Advances local calendar days, preserving wall-clock time across DST boundaries.
+ * @param {Date} date Starting date.
+ * @param {number} days Number of calendar days.
+ * @returns {Date} Shifted copy.
+ */
+export function addGanttDays(date, days) {
+	const result = new Date(date);
+	result.setDate(result.getDate() + days);
+	return result;
+}
+
+/**
+ * Creates fixed-width visible cells; omitted time retains its original timestamps.
+ * Hour cells follow elapsed time so DST days contain their actual 23 or 25 hours.
+ * @param {object} options Range, zoom, workingHours, weekendDays, and hiding flags.
+ * @returns {{cells: Array<object>, width: number, cellWidth: number, start: Date, end: Date}} Axis geometry.
+ */
+export function createGanttAxis(options) {
+	const start = parseGanttDate(options.startDate) || new Date();
+	start.setHours(0, 0, 0, 0);
+	const days = Math.min(3660, Math.max(1, Math.floor(Number(options.days) || 84)));
+	const end = addGanttDays(start, days);
+	const hourly = options.zoom === 'days';
+	const cellWidth = hourly ? 32 : options.zoom === 'months' ? 14 : 48;
+	const workingHours = options.workingHours || [6, 18];
+	const hourStart = Math.max(0, Math.min(23, Number(workingHours[0]) || 0));
+	const hourEnd = Math.max(hourStart + 1, Math.min(24, Number(workingHours[1]) || 24));
+	const weekends = Array.isArray(options.weekendDays) ? options.weekendDays : [0, 6];
+	const cells = [];
+	for (let day = start; day < end; day = addGanttDays(day, 1)) {
+		const weekend = weekends.includes(day.getDay());
+		if (weekend && options.hideWeekends) continue;
+		const nextDay = addGanttDays(day, 1);
+		for (let cursor = day; cursor < nextDay;) {
+			const next = hourly ? new Date(Math.min(+cursor + 3600000, +nextDay)) : nextDay;
+			const outsideHours = hourly && (cursor.getHours() < hourStart || cursor.getHours() >= hourEnd);
+			if (!(outsideHours && options.hideNonWorkingHours)) {
+				cells.push({ start: +cursor, end: +next, left: cells.length * cellWidth, width: cellWidth, muted: weekend || outsideHours });
+			}
+			cursor = next;
+		}
+	}
+	return { cells, width: cells.length * cellWidth, cellWidth, start, end };
+}
+
+/**
+ * Maps an instant to compressed-axis pixels. Hidden periods map to their boundary.
+ * @param {object} axis Result of createGanttAxis.
+ * @param {number|Date} value Instant to locate.
+ * @returns {number} Clamped horizontal coordinate.
+ */
+export function ganttDateToX(axis, value) {
+	const time = +value;
+	let low = 0;
+	let high = axis.cells.length;
+	while (low < high) {
+		const middle = (low + high) >> 1;
+		if (axis.cells[middle].end <= time) low = middle + 1;
+		else high = middle;
+	}
+	const cell = axis.cells[low];
+	if (!cell) return axis.width;
+	return cell.left + Math.max(0, (time - cell.start) / (cell.end - cell.start)) * cell.width;
+}
+
+/**
+ * Converts pixels back into real time, distinguishing range starts from ends at a gap.
+ * @param {object} axis Visible axis.
+ * @param {number} x Horizontal coordinate.
+ * @param {'start'|'end'} edge Boundary bias at omitted periods.
+ * @returns {number|null} Timestamp, or null for an empty axis.
+ */
+export function ganttXToDate(axis, x, edge = 'start') {
+	if (!axis.cells.length) return null;
+	const bounded = Math.max(0, Math.min(axis.width, x));
+	const index = Math.min(axis.cells.length - 1, Math.max(0, edge === 'end' ? Math.ceil(bounded / axis.cellWidth) - 1 : Math.floor(bounded / axis.cellWidth)));
+	const cell = axis.cells[index];
+	return cell.start + ((bounded - cell.left) / cell.width) * (cell.end - cell.start);
+}
+
+/**
+ * Resolves an item span. Explicit ends take precedence; durations must be positive.
+ * Day durations are whole local calendar days; hours/minutes are elapsed time.
+ * @param {object} item Application-owned record.
+ * @param {object} fields Field resolvers and durationUnit.
+ * @param {number} index Source index supplied to resolvers.
+ * @returns {{start: number, end: number}|null} Valid exclusive-end interval.
+ */
+export function resolveGanttSpan(item, fields, index = 0) {
+	const start = parseGanttDate(resolveResourceValue(item, fields.startKey, index));
+	if (!start) return null;
+	const rawEnd = resolveResourceValue(item, fields.endKey, index);
+	let end = parseGanttDate(rawEnd);
+	if (rawEnd === undefined || rawEnd === null || rawEnd === '') {
+		const duration = Number(resolveResourceValue(item, fields.durationKey, index));
+		if (!Number.isFinite(duration) || duration <= 0) return null;
+		if (fields.durationUnit === 'days') {
+			if (!Number.isInteger(duration)) return null;
+			end = addGanttDays(start, duration);
+		} else {
+			end = new Date(+start + duration * (fields.durationUnit === 'minutes' ? 60000 : 3600000));
+		}
+	}
+	return end && +end > +start ? { start: +start, end: +end } : null;
+}
+
+/**
+ * Projects item records into lane geometry and stacks overlapping spans.
+ * Source records are never sorted in place or mutated. Invalid/off-axis items are omitted.
+ * @param {Array<object>} rows Application-owned resource or feature rows.
+ * @param {Array<object>} items Application-owned scheduled items.
+ * @param {object} fields Logical field mappings and rowHeight.
+ * @param {object} axis Visible axis.
+ * @returns {Array<object>} Rows retaining source identity, with stacked item records.
+ */
+export function layoutGanttRows(rows, items, fields, axis) {
+	const groups = new Map();
+	for (const [index, item] of items.entries()) {
+		const span = resolveGanttSpan(item, fields, index);
+		if (!span) continue;
+		const left = ganttDateToX(axis, span.start);
+		const right = ganttDateToX(axis, span.end);
+		if (right <= left) continue;
+		const rowId = resolveResourceValue(item, fields.itemRowKey, index);
+		const group = groups.get(rowId) || [];
+		group.push({ item, key: resolveResourceKey(item, fields.itemKey, index), title: resolveResourceValue(item, fields.titleKey, index), tone: resolveResourceValue(item, fields.toneKey, index), ...span, left, width: right - left });
+		groups.set(rowId, group);
+	}
+	return rows.map((row, index) => {
+		const key = resolveResourceKey(row, fields.rowKey, index);
+		const records = (groups.get(key) || []).sort((a, b) => a.start - b.start || a.end - b.end);
+		const tracks = [];
+		for (const record of records) {
+			let track = tracks.findIndex((end) => end <= record.left);
+			if (track === -1) track = tracks.length;
+			tracks[track] = record.left + record.width;
+			record.top = 12 + track * 36;
+		}
+		return { row, key, label: resolveResourceValue(row, fields.rowLabelKey, index), records, height: Math.max(Number(fields.rowHeight) || 64, 24 + tracks.length * 36) };
+	});
+}
+
+/**
+ * Resolves the shared movement, resize, and creation increment in axis pixels.
+ * @param {object} axis Visible time axis.
+ * @param {string} zoom Current zoom level.
+ * @param {number} selectionStep Hourly-view increment in minutes.
+ * @returns {number} Positive pixel increment.
+ */
+export function ganttSnapWidth(axis, zoom, selectionStep = 30) {
+	return axis.cellWidth * (zoom === 'days' ? Math.min(60, Math.max(1, Number(selectionStep) || 30)) / 60 : 1);
+}
+
+/**
+ * Moves a span by snapped pointer distance without changing its source record.
+ * Week/month movement preserves both local wall-clock endpoints across DST;
+ * hourly movement preserves elapsed duration. Hidden cells affect where the
+ * pointer lands, but are never subtracted from the stored interval.
+ * @param {object} axis Visible time axis.
+ * @param {{start: number, end: number}} span Original exclusive interval.
+ * @param {number} anchorX Axis coordinate where the item was grabbed.
+ * @param {number} deltaX Pointer travel in axis pixels, including scrolling.
+ * @param {string} zoom Current zoom.
+ * @param {number} selectionStep Hourly increment in minutes.
+ * @returns {{start: number, end: number}} Proposed interval.
+ */
+export function moveGanttSpan(axis, span, anchorX, deltaX, zoom, selectionStep = 30) {
+	const step = ganttSnapWidth(axis, zoom, selectionStep);
+	const delta = Math.round(deltaX / step) * step;
+	if (!axis.cells.length || !delta) return { start: span.start, end: span.end };
+	const anchor = Math.max(0, Math.min(axis.width - step, Math.floor(anchorX / step) * step));
+	const target = Math.max(0, Math.min(axis.width - step, anchor + delta));
+	const from = ganttXToDate(axis, anchor);
+	const to = ganttXToDate(axis, target);
+	if (zoom === 'days') return { start: span.start + to - from, end: span.end + to - from };
+	const first = new Date(from);
+	const last = new Date(to);
+	const days = (Date.UTC(last.getFullYear(), last.getMonth(), last.getDate()) - Date.UTC(first.getFullYear(), first.getMonth(), first.getDate())) / 86400000;
+	return { start: +addGanttDays(new Date(span.start), days), end: +addGanttDays(new Date(span.end), days) };
+}
+
+/**
+ * Adjusts only an item's exclusive end using the shared visible-time increment.
+ * A changed span retains at least one visible selection increment. The true end
+ * is preserved for zero movement, including ends inside hidden nights/weekends.
+ * @param {object} axis Visible time axis.
+ * @param {{start: number, end: number}} span Original exclusive interval.
+ * @param {number} deltaX Pointer travel from the original right edge.
+ * @param {string} zoom Current zoom.
+ * @param {number} selectionStep Hourly increment in minutes.
+ * @returns {{start: number, end: number}} Proposed interval.
+ */
+export function resizeGanttSpan(axis, span, deltaX, zoom, selectionStep = 30) {
+	const step = ganttSnapWidth(axis, zoom, selectionStep);
+	const delta = Math.round(deltaX / step) * step;
+	if (!axis.cells.length || !delta) return { start: span.start, end: span.end };
+	const minimum = Math.min(axis.width, ganttDateToX(axis, span.start) + step);
+	const position = Math.max(minimum, Math.min(axis.width, ganttDateToX(axis, span.end) + delta));
+	const end = ganttXToDate(axis, position, 'end');
+	return { start: span.start, end: end > span.start ? end : span.end };
+}

package/src/pages/data/month-calendar/DomMonthCalendar.vue

@@ -245,6 +245,36 @@ export const monthCalendarProps = {
 		default: true,
 		_edit: { description: 'Render weekday headers.' },
 	},
+	stickyDayHeaders: {
+		type: Boolean,
+		default: null,
+		_edit: { description: 'Pin weekday headers to the active scrollport, below sticky month titles. When omitted, enabled in continuous mode and disabled in separated months.' },
+	},
+	showDayNames: {
+		type: Boolean,
+		default: true,
+		_edit: { description: 'Show the weekday name beside the date inside each day cell, including the mobile day list.' },
+	},
+	todayIndicator: {
+		type: String,
+		default: 'cell',
+		/**
+		 * Accepts supported visual treatments for the current date.
+		 *
+		 * @param {string} value Requested indicator style.
+		 * @returns {boolean} Whether the indicator is supported.
+		 */
+		validator: (value) => ['cell', 'circle', 'none'].includes(value),
+		_edit: { group: 'Styling', options: ['cell', 'circle', 'none'], description: 'Highlight today with a cell outline, a coloured circle behind the date, or no visual indicator.' },
+	},
+	/**
+	 * @type {MonthCalendarDayClass}
+	 */
+	todayDateClass: {
+		type: [String, Array, Object, Function],
+		default: 'bg-primary text-primary-fg',
+		_edit: { group: 'Styling', description: 'Classes for today’s date circle. Replaces the default primary background and foreground colours when todayIndicator is circle.' },
+	},
 	/**
 	 * @type {MonthCalendarDayClass}
 	 */
@@ -302,6 +332,8 @@ const dragState = ref(createEmptyDragState());
 const activeContinuousMonthValue = ref('');
 const calendarRoot = ref(null);
 const externalContinuousScrollHost = ref(null);
+let monthHeaderResizeObserver = null;
+const resolvedStickyDayHeaders = computed(() => props.stickyDayHeaders ?? props.continuous);
 const resolvedWeekStartsOn = computed(() => clampWeekStartsOn(props.weekStartsOn));
 const defaultMutedDayClass = 'bg-secondary/20 text-muted-fg/55';
 const rangeStart = computed(() => parseDate(props.startDate));
@@ -367,12 +399,16 @@ const wideWeekGridColumns = computed(() => {
 
 onMounted(() => {
 	nextTick(configureExternalContinuousScrollTracking);
+	nextTick(configureMonthHeaderOffsets);
 });
 
 onBeforeUnmount(() => {
 	removeExternalContinuousScrollTracking();
+	monthHeaderResizeObserver?.disconnect();
 });
 
+watch([calendarSections, () => props.stickyMonthHeaders], () => nextTick(configureMonthHeaderOffsets), { flush: 'post' });
+
 watch(
 	() => [props.continuous, props.containedContinuousScroll, props.startDate, props.months, props.weekStartsOn],
 	() => {
@@ -678,6 +714,7 @@ function rowHeaderLabelFor(week) {
  * @returns {Date|null} First day of the configured month, or null when the props are incomplete.
  */
 function initialDateFromProps() {
+	if (props.initialYear == null || props.initialMonth == null) return null;
 	const year = Number(props.initialYear);
 	const month = Number(props.initialMonth);
 	if (!Number.isFinite(year) || !Number.isFinite(month)) return null;
@@ -1354,6 +1391,33 @@ function onSectionScroll(section, event) {
 	updateActiveContinuousMonthForScrollHost(scrollHost, scrollHost);
 }
 
+/**
+ * Measures month headings so sticky weekday rows clear wrapped titles and slots.
+ * Reconnects after range or layout changes and releases the previous observer.
+ *
+ * @returns {void}
+ */
+function configureMonthHeaderOffsets() {
+	monthHeaderResizeObserver?.disconnect();
+	if (!calendarRoot.value || typeof ResizeObserver === 'undefined') return;
+	monthHeaderResizeObserver = new ResizeObserver(updateMonthHeaderOffsets);
+	for (const header of calendarRoot.value.querySelectorAll('[data-month-heading]')) {
+		monthHeaderResizeObserver.observe(header);
+	}
+}
+
+/**
+ * Stores each heading's actual height on its section for sibling sticky rows.
+ *
+ * @param {ResizeObserverEntry[]} entries Month headings whose sizes changed.
+ * @returns {void}
+ */
+function updateMonthHeaderOffsets(entries) {
+	for (const { target } of entries) {
+		target.parentElement?.style.setProperty('--dom-month-calendar-month-heading-height', `${target.getBoundingClientRect().height}px`);
+	}
+}
+
 /**
  * Attaches active-month tracking to the nearest parent scrollport when continuous mode is externally scrolled.
  *
@@ -1437,7 +1501,8 @@ function updateActiveContinuousMonthForScrollHost(scrollHost, scope) {
 
 	const hostTop = scrollHost === window ? 0 : scrollHost.getBoundingClientRect().top;
 	const header = scope.querySelector('[data-continuous-day-headers]');
-	const headerHeight = header instanceof HTMLElement ? header.getBoundingClientRect().height : 0;
+	const stickyHeader = header instanceof HTMLElement && resolvedStickyDayHeaders.value && getComputedStyle(header).display !== 'none';
+	const headerHeight = stickyHeader ? header.getBoundingClientRect().height : 0;
 	const activationTop = hostTop + headerHeight + 1;
 	const activeRow = scopedRows.reduce((current, row) => {
 		if (!(row instanceof HTMLElement)) return current;
@@ -1484,6 +1549,7 @@ function onDayClick(cell, event) {
 		>
 			<div
 				v-if="section.continuous && stickyMonthHeaders"
+				data-month-heading
 				class="dom-month-calendar__continuous-mobile-header sticky top-0 z-30 mb-3 items-center justify-between gap-3 border-b border-border bg-canvas/95 py-3 shadow-sm backdrop-blur"
 			>
 				<span class="text-[11px] font-semibold uppercase tracking-wide text-muted-fg">Month</span>
@@ -1491,8 +1557,9 @@ function onDayClick(cell, event) {
 			</div>
 			<header
 				v-if="!section.continuous"
+				data-month-heading
 				class="mb-4 flex flex-wrap items-end justify-between gap-3"
-				:class="stickyMonthHeaders && 'sticky top-0 z-20 border-b border-border bg-canvas/95 py-3 shadow-sm backdrop-blur'"
+				:class="stickyMonthHeaders && 'sticky top-0 z-30 border-b border-border bg-canvas/95 py-3 shadow-sm backdrop-blur'"
 			>
 				<h2 :id="section.id" class="text-3xl font-bold tracking-tight text-canvas-fg">{{ section.label }}</h2>
 				<div class="text-sm font-medium text-muted-fg">
@@ -1508,13 +1575,14 @@ function onDayClick(cell, event) {
 			</header>
 			<h2 v-else :id="section.id" class="sr-only">{{ section.label }}</h2>
 
+			<!-- Parent-scrolled grids use clip to round resting corners without trapping sticky headers. -->
 			<div
 				class="rounded-2xl border border-border bg-canvas"
 				:data-continuous-section="section.continuous ? '' : undefined"
 				:class="[
 					section.continuous && containedContinuousScroll && 'max-h-[70vh] overflow-auto overscroll-contain',
-					section.continuous && !containedContinuousScroll && 'overflow-x-auto md:overflow-visible',
-					!section.continuous && 'overflow-x-auto',
+					section.continuous && !containedContinuousScroll && (resolvedStickyDayHeaders ? 'overflow-clip' : 'overflow-x-auto md:overflow-clip'),
+					!section.continuous && (resolvedStickyDayHeaders ? 'overflow-clip' : 'overflow-x-auto'),
 				]"
 				@scroll.passive="onSectionScroll(section, $event)"
 			>
@@ -1530,8 +1598,9 @@ function onDayClick(cell, event) {
 						:data-continuous-day-headers="section.continuous ? '' : undefined"
 						class="dom-month-calendar__day-headers grid border-b border-border"
 						:class="[
-							section.continuous ? 'sticky top-0 z-20 bg-secondary shadow-sm' : 'bg-secondary/30',
+							resolvedStickyDayHeaders ? 'sticky z-20 bg-secondary shadow-sm' : 'bg-secondary/30',
 						]"
+						:style="resolvedStickyDayHeaders ? { top: stickyMonthHeaders && !(section.continuous && containedContinuousScroll) ? 'var(--dom-month-calendar-month-heading-height, 0px)' : '0px' } : undefined"
 					>
 						<div
 							v-if="hasRowRail"
@@ -1612,7 +1681,7 @@ function onDayClick(cell, event) {
 								clickable && !cell.disabled && hoverableDays && 'hover:bg-secondary/50',
 								clickable && cell.disabled && 'cursor-not-allowed opacity-55',
 								!clickable && 'cursor-default',
-								cell.today && !cell.hidden && 'ring-2 ring-inset ring-ring/40',
+								cell.today && !cell.hidden && todayIndicator === 'cell' && 'ring-2 ring-inset ring-ring/40',
 								dayClassFor(cell),
 								dragAndDrop && dragState.active && canDropOnCell(cell) && !isDropTarget(cell) && 'bg-primary/5',
 								dragAndDrop && isDropTarget(cell) && 'bg-primary/10 ring-2 ring-inset ring-ring/60',
@@ -1627,9 +1696,15 @@ function onDayClick(cell, event) {
 							@drop="onDayDrop(cell, $event)"
 						>
 							<template v-if="!cell.hidden">
-								<div class="flex items-start justify-between gap-2">
-									<span class="text-base font-bold leading-none tabular-nums">{{ cell.day }}</span>
-									<span class="text-base lowercase leading-none tabular-nums">{{ cell.weekday }}</span>
+								<div class="flex items-center justify-between gap-2">
+									<span
+										class="text-base font-bold leading-none tabular-nums"
+										:class="[
+											todayIndicator === 'circle' && 'inline-flex size-7 shrink-0 items-center justify-center rounded-full',
+											cell.today && todayIndicator === 'circle' && resolveDayClass(todayDateClass, cell),
+										]"
+									>{{ cell.day }}</span>
+									<span v-if="showDayNames" class="text-base lowercase leading-none tabular-nums">{{ cell.weekday }}</span>
 								</div>
 								<div class="mt-3 min-h-0 flex-1 h-full">
 									<slot