@tasknotes/calendar 0.0.0-stage → 0.1.1

package/dist/types/core/plan.d.ts

@@ -0,0 +1,42 @@
+import type { Day } from "./date.js";
+import type { ItemStore } from "./store.js";
+import type { CalendarItem, DependencyType, NormalizedItem } from "./types.js";
+/** Minutes of planned (timed, plan-lane, non-background) work on each day. */
+export declare function plannedMinutes<D>(store: ItemStore<D>, days: Day[]): Map<Day, number>;
+/** An item's dependencies with their relationship types resolved ("FS" by default). */
+export declare function itemDependencies(item: Pick<CalendarItem, "dependsOn">): {
+    id: string;
+    type: DependencyType;
+}[];
+/** The relationship created by linking a predecessor edge to a successor edge. */
+export declare function dependencyType(fromEdge: "start" | "finish", toEdge: "start" | "finish"): DependencyType;
+/** Whether a relationship holds: the successor's edge is not before the predecessor's. */
+export declare function dependencySatisfied(type: DependencyType, pred: {
+    startMs: number;
+    endMs: number;
+}, succ: {
+    startMs: number;
+    endMs: number;
+}): boolean;
+/** Items whose relationships are broken, mapped to the ids of the predecessors they break. */
+export declare function dependencyConflicts<D>(store: ItemStore<D>): Map<string, string[]>;
+export interface SlotSearch {
+    /** First and last (exclusive) days to search. */
+    fromDay: Day;
+    toDay: Day;
+    durationMinutes: number;
+    /** Working window as wall minutes, e.g. [540, 1020] for 09:00-17:00. */
+    window: [number, number];
+    /** Don't place anything before this instant (usually now). */
+    notBefore?: number;
+    snapMinutes?: number;
+    /** Items to treat as free time, e.g. the item being placed. */
+    ignore?: (n: NormalizedItem) => boolean;
+    /** Days to skip, e.g. weekends. */
+    skipDay?: (day: Day) => boolean;
+}
+/** Finds the first gap long enough for `durationMinutes` in the working window. */
+export declare function findFreeSlot<D>(store: ItemStore<D>, q: SlotSearch): {
+    startMs: number;
+    endMs: number;
+} | null;

package/dist/types/core/store.d.cts

@@ -0,0 +1,60 @@
+import { type Day, DAY_MS } from "./date.cjs";
+import type { CalendarItem, NormalizedItem } from "./types.cjs";
+import { type TimeZone } from "./zone.cjs";
+export interface StoreOptions {
+    /** Length of timed items without an end, in minutes. */
+    defaultTimedMinutes: number;
+    /** Length of all-day items without an end, in days. */
+    defaultAllDayDays: number;
+}
+export interface StoreChange {
+    added: string[];
+    updated: string[];
+    removed: string[];
+    /** Days whose timed content changed. */
+    days: Set<Day>;
+    /** True when any all-day (or multi-day) placement changed. */
+    spans: boolean;
+}
+/**
+ * Items indexed by the civil days they touch. Every mutation records which days
+ * changed so layouts and DOM columns for untouched days can be reused.
+ */
+export declare class ItemStore<D = unknown> {
+    private zone;
+    private opts;
+    private readonly items;
+    private readonly timedByDay;
+    private readonly spanning;
+    private pending;
+    /** Bumped on every change; cheap staleness check for caches. */
+    version: number;
+    constructor(zone: TimeZone, opts?: Partial<StoreOptions>);
+    private static emptyChange;
+    get size(): number;
+    get timeZone(): TimeZone;
+    /** Re-resolves every item; used when the zone or defaults change. */
+    reconfigure(zone: TimeZone, opts?: Partial<StoreOptions>): void;
+    normalize(item: CalendarItem<D>): NormalizedItem<D> | null;
+    private insert;
+    private index;
+    private unindex;
+    /** Replaces the whole item set, touching only items whose signature changed. */
+    setAll(items: Iterable<CalendarItem<D>>): StoreChange;
+    /** Upserts items without removing others. */
+    upsert(items: Iterable<CalendarItem<D>>): StoreChange;
+    remove(ids: Iterable<string>): StoreChange;
+    private upsertOne;
+    private flush;
+    get(id: string): NormalizedItem<D> | undefined;
+    all(): IterableIterator<NormalizedItem<D>>;
+    /** Timed items touching `day`. */
+    timedOn(day: Day): NormalizedItem<D>[];
+    /** All-day items (and, if asked, multi-day timed items) overlapping [startDay, endDay). */
+    spanningIn(startDay: Day, endDay: Day, includeTimedMultiDay: boolean): NormalizedItem<D>[];
+    /** Every visible item overlapping [startDay, endDay). */
+    inRange(startDay: Day, endDay: Day): NormalizedItem<D>[];
+}
+/** Days spanned by an instant range in a zone, end exclusive. */
+export declare function daysOfRange(startMs: number, endMs: number, zone: TimeZone): [Day, Day];
+export { DAY_MS };

package/dist/types/core/store.d.ts

@@ -0,0 +1,60 @@
+import { type Day, DAY_MS } from "./date.js";
+import type { CalendarItem, NormalizedItem } from "./types.js";
+import { type TimeZone } from "./zone.js";
+export interface StoreOptions {
+    /** Length of timed items without an end, in minutes. */
+    defaultTimedMinutes: number;
+    /** Length of all-day items without an end, in days. */
+    defaultAllDayDays: number;
+}
+export interface StoreChange {
+    added: string[];
+    updated: string[];
+    removed: string[];
+    /** Days whose timed content changed. */
+    days: Set<Day>;
+    /** True when any all-day (or multi-day) placement changed. */
+    spans: boolean;
+}
+/**
+ * Items indexed by the civil days they touch. Every mutation records which days
+ * changed so layouts and DOM columns for untouched days can be reused.
+ */
+export declare class ItemStore<D = unknown> {
+    private zone;
+    private opts;
+    private readonly items;
+    private readonly timedByDay;
+    private readonly spanning;
+    private pending;
+    /** Bumped on every change; cheap staleness check for caches. */
+    version: number;
+    constructor(zone: TimeZone, opts?: Partial<StoreOptions>);
+    private static emptyChange;
+    get size(): number;
+    get timeZone(): TimeZone;
+    /** Re-resolves every item; used when the zone or defaults change. */
+    reconfigure(zone: TimeZone, opts?: Partial<StoreOptions>): void;
+    normalize(item: CalendarItem<D>): NormalizedItem<D> | null;
+    private insert;
+    private index;
+    private unindex;
+    /** Replaces the whole item set, touching only items whose signature changed. */
+    setAll(items: Iterable<CalendarItem<D>>): StoreChange;
+    /** Upserts items without removing others. */
+    upsert(items: Iterable<CalendarItem<D>>): StoreChange;
+    remove(ids: Iterable<string>): StoreChange;
+    private upsertOne;
+    private flush;
+    get(id: string): NormalizedItem<D> | undefined;
+    all(): IterableIterator<NormalizedItem<D>>;
+    /** Timed items touching `day`. */
+    timedOn(day: Day): NormalizedItem<D>[];
+    /** All-day items (and, if asked, multi-day timed items) overlapping [startDay, endDay). */
+    spanningIn(startDay: Day, endDay: Day, includeTimedMultiDay: boolean): NormalizedItem<D>[];
+    /** Every visible item overlapping [startDay, endDay). */
+    inRange(startDay: Day, endDay: Day): NormalizedItem<D>[];
+}
+/** Days spanned by an instant range in a zone, end exclusive. */
+export declare function daysOfRange(startMs: number, endMs: number, zone: TimeZone): [Day, Day];
+export { DAY_MS };

package/dist/types/core/types.d.cts

@@ -0,0 +1,69 @@
+import type { Day } from "./date.cjs";
+export type DateInput = Date | string | number;
+/** Dependency relationship, predecessor edge then successor edge: "FS" = finish-to-start. */
+export type DependencyType = "FS" | "SS" | "FF" | "SF";
+export interface ItemDependency {
+    id: string;
+    /** Default "FS". */
+    type?: DependencyType;
+}
+/**
+ * One thing on the calendar. `end` is exclusive, as in FullCalendar and iCal:
+ * an all-day item on the 3rd has start "2026-10-03", end "2026-10-04".
+ */
+export interface CalendarItem<D = unknown> {
+    id: string;
+    title: string;
+    start: DateInput;
+    end?: DateInput | null;
+    /** Defaults to true for date-only `start` strings. */
+    allDay?: boolean;
+    /** Free-form kind used for styling and behaviour, e.g. "task", "event", "timeblock", "timeEntry". */
+    kind?: string;
+    /** Main colour. Background, border and text derive from it unless set. */
+    color?: string;
+    backgroundColor?: string;
+    borderColor?: string;
+    textColor?: string;
+    className?: string | string[];
+    /** Overrides the calendar-wide `editable` option. */
+    editable?: boolean;
+    startEditable?: boolean;
+    durationEditable?: boolean;
+    /** "background" items shade their time range without taking layout space. */
+    display?: "auto" | "background" | "none";
+    completed?: boolean;
+    /**
+     * Items this one depends on. A plain id is finish-to-start; `{ id, type }`
+     * sets the relationship ("SS": this starts no earlier than `id` starts, and so on).
+     */
+    dependsOn?: readonly (string | ItemDependency)[];
+    /** Time-grid lane. "actual" items (tracked time) sit in a narrow side lane. */
+    lane?: "plan" | "actual";
+    /** Items sharing a groupId move together when one is dragged. */
+    groupId?: string;
+    /** Change token. When set, the store compares it instead of serialising the item. */
+    rev?: string | number;
+    data?: D;
+}
+/** An item resolved against the calendar's time zone. */
+export interface NormalizedItem<D = unknown> {
+    readonly id: string;
+    readonly item: CalendarItem<D>;
+    readonly allDay: boolean;
+    /** Instants (ms). For all-day items these are the zone's midnights. */
+    readonly startMs: number;
+    readonly endMs: number;
+    /** Civil days, end exclusive. */
+    readonly startDay: Day;
+    readonly endDay: Day;
+    readonly sig: string;
+}
+export interface DateRange {
+    /** First visible day. */
+    startDay: Day;
+    /** Day after the last visible day. */
+    endDay: Day;
+    start: Date;
+    end: Date;
+}

package/dist/types/core/types.d.ts

@@ -0,0 +1,69 @@
+import type { Day } from "./date.js";
+export type DateInput = Date | string | number;
+/** Dependency relationship, predecessor edge then successor edge: "FS" = finish-to-start. */
+export type DependencyType = "FS" | "SS" | "FF" | "SF";
+export interface ItemDependency {
+    id: string;
+    /** Default "FS". */
+    type?: DependencyType;
+}
+/**
+ * One thing on the calendar. `end` is exclusive, as in FullCalendar and iCal:
+ * an all-day item on the 3rd has start "2026-10-03", end "2026-10-04".
+ */
+export interface CalendarItem<D = unknown> {
+    id: string;
+    title: string;
+    start: DateInput;
+    end?: DateInput | null;
+    /** Defaults to true for date-only `start` strings. */
+    allDay?: boolean;
+    /** Free-form kind used for styling and behaviour, e.g. "task", "event", "timeblock", "timeEntry". */
+    kind?: string;
+    /** Main colour. Background, border and text derive from it unless set. */
+    color?: string;
+    backgroundColor?: string;
+    borderColor?: string;
+    textColor?: string;
+    className?: string | string[];
+    /** Overrides the calendar-wide `editable` option. */
+    editable?: boolean;
+    startEditable?: boolean;
+    durationEditable?: boolean;
+    /** "background" items shade their time range without taking layout space. */
+    display?: "auto" | "background" | "none";
+    completed?: boolean;
+    /**
+     * Items this one depends on. A plain id is finish-to-start; `{ id, type }`
+     * sets the relationship ("SS": this starts no earlier than `id` starts, and so on).
+     */
+    dependsOn?: readonly (string | ItemDependency)[];
+    /** Time-grid lane. "actual" items (tracked time) sit in a narrow side lane. */
+    lane?: "plan" | "actual";
+    /** Items sharing a groupId move together when one is dragged. */
+    groupId?: string;
+    /** Change token. When set, the store compares it instead of serialising the item. */
+    rev?: string | number;
+    data?: D;
+}
+/** An item resolved against the calendar's time zone. */
+export interface NormalizedItem<D = unknown> {
+    readonly id: string;
+    readonly item: CalendarItem<D>;
+    readonly allDay: boolean;
+    /** Instants (ms). For all-day items these are the zone's midnights. */
+    readonly startMs: number;
+    readonly endMs: number;
+    /** Civil days, end exclusive. */
+    readonly startDay: Day;
+    readonly endDay: Day;
+    readonly sig: string;
+}
+export interface DateRange {
+    /** First visible day. */
+    startDay: Day;
+    /** Day after the last visible day. */
+    endDay: Day;
+    start: Date;
+    end: Date;
+}

package/dist/types/core/zone.d.cts

@@ -0,0 +1,43 @@
+import { type Day } from "./date.cjs";
+/**
+ * Converts between instants (epoch ms) and wall-clock time in one zone.
+ * "local" uses the runtime's zone; any IANA name uses Intl.
+ */
+export interface TimeZone {
+    readonly id: string;
+    /** UTC offset in minutes (east positive) at an instant. */
+    offsetAt(ms: number): number;
+}
+export interface WallTime {
+    day: Day;
+    /** Minutes since local midnight, 0..1439. */
+    minute: number;
+}
+export declare function getTimeZone(id: string | undefined | null): TimeZone;
+export declare function isValidTimeZone(id: string): boolean;
+export declare function wallTime(ms: number, zone: TimeZone): WallTime;
+export declare function dayOf(ms: number, zone: TimeZone): Day;
+/**
+ * Wall-clock time to instant. Times inside a DST gap move forward by the gap
+ * (02:30 on a spring-forward day becomes 03:30); ambiguous times resolve to the
+ * earlier instant. This matches how Date resolves local times.
+ */
+export declare function toInstant(day: Day, minute: number, zone: TimeZone): number;
+export declare function startOfDayInstant(day: Day, zone: TimeZone): number;
+/** Length of a civil day in minutes (1380 or 1500 on DST change days). */
+export declare function dayLengthMinutes(day: Day, zone: TimeZone): number;
+export type ParsedDate = {
+    kind: "day";
+    day: Day;
+} | {
+    kind: "instant";
+    ms: number;
+};
+/**
+ * Parses calendar input. Date-only strings are civil days; date-times without
+ * an offset are wall-clock times in `zone`; anything with Z or an offset is an
+ * absolute instant.
+ */
+export declare function parseDateInput(value: Date | string | number, zone: TimeZone): ParsedDate | null;
+/** Formats an instant as a floating local date-time ("YYYY-MM-DDTHH:mm") in `zone`. */
+export declare function formatFloating(ms: number, zone: TimeZone): string;

package/dist/types/core/zone.d.ts

@@ -0,0 +1,43 @@
+import { type Day } from "./date.js";
+/**
+ * Converts between instants (epoch ms) and wall-clock time in one zone.
+ * "local" uses the runtime's zone; any IANA name uses Intl.
+ */
+export interface TimeZone {
+    readonly id: string;
+    /** UTC offset in minutes (east positive) at an instant. */
+    offsetAt(ms: number): number;
+}
+export interface WallTime {
+    day: Day;
+    /** Minutes since local midnight, 0..1439. */
+    minute: number;
+}
+export declare function getTimeZone(id: string | undefined | null): TimeZone;
+export declare function isValidTimeZone(id: string): boolean;
+export declare function wallTime(ms: number, zone: TimeZone): WallTime;
+export declare function dayOf(ms: number, zone: TimeZone): Day;
+/**
+ * Wall-clock time to instant. Times inside a DST gap move forward by the gap
+ * (02:30 on a spring-forward day becomes 03:30); ambiguous times resolve to the
+ * earlier instant. This matches how Date resolves local times.
+ */
+export declare function toInstant(day: Day, minute: number, zone: TimeZone): number;
+export declare function startOfDayInstant(day: Day, zone: TimeZone): number;
+/** Length of a civil day in minutes (1380 or 1500 on DST change days). */
+export declare function dayLengthMinutes(day: Day, zone: TimeZone): number;
+export type ParsedDate = {
+    kind: "day";
+    day: Day;
+} | {
+    kind: "instant";
+    ms: number;
+};
+/**
+ * Parses calendar input. Date-only strings are civil days; date-times without
+ * an offset are wall-clock times in `zone`; anything with Z or an offset is an
+ * absolute instant.
+ */
+export declare function parseDateInput(value: Date | string | number, zone: TimeZone): ParsedDate | null;
+/** Formats an instant as a floating local date-time ("YYYY-MM-DDTHH:mm") in `zone`. */
+export declare function formatFloating(ms: number, zone: TimeZone): string;

package/dist/types/dom/calendar.d.cts

@@ -0,0 +1,215 @@
+import { type Day } from "../core/date.cjs";
+import type { ItemOrder } from "../core/layout.cjs";
+import { ItemStore } from "../core/store.cjs";
+import type { CalendarItem, DateInput, NormalizedItem } from "../core/types.cjs";
+import { type TimeZone } from "../core/zone.cjs";
+import { type ElMeta, type ViewContext } from "./context.cjs";
+import { Formatter } from "./format.cjs";
+import { type CalendarOptions, type CalendarText, type DayArg, type ExternalDragSource, type Hit, type TimelineAnchor, type ViewInfo, type ViewType } from "./options.cjs";
+/**
+ * A calendar bound to one element. Works in any document, including Obsidian
+ * popout windows: all listeners, timers and observers use the element's window.
+ */
+export declare class Calendar<D = unknown> implements ViewContext<D> {
+    readonly host: HTMLElement;
+    /** The document/window the calendar currently lives in; see `adopt()`. */
+    doc: Document;
+    win: Window;
+    readonly root: HTMLElement;
+    readonly store: ItemStore<D>;
+    readonly meta: WeakMap<Element, ElMeta<D>>;
+    opts: CalendarOptions<D>;
+    zone: TimeZone;
+    fmt: Formatter;
+    text: CalendarText;
+    order: ItemOrder<D>;
+    view: ViewInfo;
+    firstDay: number;
+    days: Day[];
+    today: Day;
+    conflicts: Map<string, string[]>;
+    slot: {
+        min: number;
+        max: number;
+        duration: number;
+        snap: number;
+        scroll: number;
+    };
+    draggingId: string | null;
+    dragRow: {
+        id: string;
+        rowId: string;
+    } | null;
+    private readonly toolbarEl;
+    private readonly viewHost;
+    private current;
+    private anchor;
+    private session;
+    private selection;
+    private suppressClick;
+    private selectedIds;
+    private popover;
+    private timer;
+    private resizeObs;
+    private destroyed;
+    private pendingChange;
+    private frame;
+    constructor(host: HTMLElement, options?: Partial<CalendarOptions<D>>, items?: Iterable<CalendarItem<D>>);
+    private observeResize;
+    private readonly onAdoptCheck;
+    /**
+     * Hosts may move a live calendar into another window (e.g. Obsidian's
+     * "Move to new window"). Listeners, timers and observers belong to a window,
+     * so rebind them to the root's current document and rebuild the view there.
+     */
+    adopt(): void;
+    /** Replaces all items, re-rendering only what changed. */
+    setItems(items: Iterable<CalendarItem<D>>): void;
+    upsertItems(items: Iterable<CalendarItem<D>>): void;
+    removeItems(ids: Iterable<string>): void;
+    getItem(id: string): CalendarItem<D> | undefined;
+    /**
+     * Updates options. Only what the change affects is rebuilt.
+     *
+     * In the timeline, a new `date`, range or scale keeps what is on screen
+     * instead of jumping back to the anchor date: a scale change keeps the
+     * instant at the middle of the visible track, other changes keep the left
+     * edge. Pass `anchor` to pin a different instant, e.g. the one under the
+     * pointer when zooming with the wheel.
+     */
+    setOptions(next: Partial<CalendarOptions<D>>, how?: {
+        anchor?: TimelineAnchor;
+    }): void;
+    /** What a timeline rebuild should keep on screen. */
+    private timelineKeep;
+    /** Re-renders everything, e.g. after render hooks start returning different content. */
+    rerender(): void;
+    getOptions(): Readonly<CalendarOptions<D>>;
+    changeView(view: ViewType, date?: DateInput): void;
+    gotoDate(date: DateInput): void;
+    prev(): void;
+    next(): void;
+    goToday(): void;
+    /** The anchor date, as local midnight of that civil day in the calendar zone. */
+    getDate(): Date;
+    getView(): ViewInfo;
+    /** Clears the current selection. */
+    unselect(): void;
+    /** Re-measures (e.g. after the host was shown or resized by a parent). */
+    updateSize(): void;
+    getScroll(): {
+        top: number;
+        left: number;
+    };
+    setScroll(s: {
+        top: number;
+        left: number;
+    }): void;
+    scrollToTime(time: string | number): void;
+    /**
+     * Scrolls a date (or instant) into view. In the timeline `align` places it
+     * at the start, middle or end of the visible track; other views move to
+     * the date if it is outside the range, and time grids scroll to its time.
+     */
+    scrollToDate(date: DateInput, opts?: {
+        align?: "start" | "center" | "end";
+        smooth?: boolean;
+    }): void;
+    /** What is under a client point: a time slot, a day, or a timeline row and date. Null outside the view. */
+    hitTest(clientX: number, clientY: number): Hit | null;
+    /** Item elements currently rendered for an id. */
+    elementsFor(id: string): HTMLElement[];
+    /**
+     * Starts dragging something from outside the calendar (a task tray, an
+     * unscheduled list). Call from a pointerdown handler; the calendar follows
+     * the pointer and fires `onExternalDrop` on release.
+     */
+    beginExternalDrag(ev: PointerEvent, source: ExternalDragSource<D>): void;
+    destroy(): void;
+    now(): number;
+    suppressNextClick(): void;
+    dayArg(day: Day): DayArg;
+    dayClasses(day: Day): string[];
+    isEditable(n: NormalizedItem<D>, what: "start" | "duration"): boolean;
+    navLink(day: Day, label: Node | string, cls: string): HTMLElement;
+    navigate(day: Day, jsEvent: MouseEvent | KeyboardEvent, view?: "day" | "month"): void;
+    createItemEl(meta: ElMeta<D>): HTMLElement;
+    refreshItemEl(el: HTMLElement, meta: ElMeta<D>): void;
+    private selectedSet;
+    private applySelected;
+    destroyItemEl(el: HTMLElement): void;
+    openMore(day: Day, anchor: HTMLElement, jsEvent: MouseEvent | KeyboardEvent): void;
+    private resolveText;
+    private todayDay;
+    private toDay;
+    private toMs;
+    private step;
+    private computeRange;
+    private computeTitle;
+    private rebuild;
+    private createView;
+    private renderToolbar;
+    private applyChange;
+    /** Renders pending changes now. Called automatically on the next frame. */
+    flush(): void;
+    private merge;
+    private scheduleTick;
+    private itemArg;
+    /** Start and (for timed and list items) end labels; the end is hidden on short items by CSS. */
+    private timeLabel;
+    private fillTime;
+    private ariaLabel;
+    private defaultContent;
+    private addHandles;
+    /** Start and finish link handles (a milestone has one). */
+    private addPorts;
+    private refreshMore;
+    private closeMore;
+    private bindEvents;
+    private unbindEvents;
+    private listenDoc;
+    private itemElFrom;
+    private readonly onDocPointerDown;
+    private readonly onPointerDown;
+    private activate;
+    private readonly onTouchMove;
+    private readonly onPointerMove;
+    private readonly onPointerUp;
+    private readonly onPointerCancel;
+    private readonly onDocKeyDown;
+    /** Proposal for the current pointer position. */
+    private track;
+    private trackExternal;
+    private externalItem;
+    private timelineSnap;
+    private civil;
+    private civilToMs;
+    private hitCivil;
+    private dayProposal;
+    private timedProposal;
+    private moveProposal;
+    private resizeProposal;
+    private withProposal;
+    private selectionFor;
+    private clickSlot;
+    private fireSelect;
+    private unselectSilently;
+    /** Ends the current pointer session, committing unless `cancel`. */
+    private endSession;
+    private commit;
+    /** Runs in the capture phase so the click ending a drag never reaches content inside the calendar, React portals included. */
+    private readonly onClickCapture;
+    private readonly onClick;
+    private readonly onDblClick;
+    private readonly onContextMenu;
+    private hoverId;
+    private readonly onMouseOver;
+    private readonly onMouseOut;
+    private leaveHover;
+    private readonly onKeyDown;
+    /** Alt+Arrow moves an item; Alt+Shift+Arrow changes its end; arrows on a focused grip move that edge. */
+    private nudge;
+    private readonly onNativeDragOver;
+    private readonly onNativeDragLeave;
+    private readonly onNativeDrop;
+}