@tasknotes/calendar 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,215 @@
+import { type Day } from "../core/date.js";
+import type { ItemOrder } from "../core/layout.js";
+import { ItemStore } from "../core/store.js";
+import type { CalendarItem, DateInput, NormalizedItem } from "../core/types.js";
+import { type TimeZone } from "../core/zone.js";
+import { type ElMeta, type ViewContext } from "./context.js";
+import { Formatter } from "./format.js";
+import { type CalendarOptions, type CalendarText, type DayArg, type ExternalDragSource, type Hit, type TimelineAnchor, type ViewInfo, type ViewType } from "./options.js";
+/**
+ * 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;
+}

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

@@ -0,0 +1,107 @@
+import type { Day } from "../core/date.cjs";
+import type { ItemOrder } from "../core/layout.cjs";
+import type { ItemStore, StoreChange } from "../core/store.cjs";
+import type { NormalizedItem } from "../core/types.cjs";
+import type { TimeZone } from "../core/zone.cjs";
+import type { Formatter } from "./format.cjs";
+import type { CalendarOptions, CalendarText, DayArg, Hit, ItemVariant, ViewInfo } from "./options.cjs";
+export type Variant = ItemVariant;
+export interface ElMeta<D = unknown> {
+    n: NormalizedItem<D>;
+    day: Day;
+    isStart: boolean;
+    isEnd: boolean;
+    variant: Variant;
+    mirror: boolean;
+}
+/** A time or day range being selected, or previewed for an external drop. */
+export interface Selection {
+    startMs: number;
+    endMs: number;
+    allDay: boolean;
+    startDay: Day;
+    endDay: Day;
+    rowId?: string;
+}
+/** What views get from the calendar. */
+export interface ViewContext<D = unknown> {
+    readonly doc: Document;
+    readonly win: Window;
+    readonly store: ItemStore<D>;
+    readonly opts: CalendarOptions<D>;
+    readonly zone: TimeZone;
+    readonly fmt: Formatter;
+    readonly text: CalendarText;
+    readonly order: ItemOrder<D>;
+    readonly view: ViewInfo;
+    readonly firstDay: number;
+    /** Visible days in order (hidden weekdays removed). */
+    readonly days: Day[];
+    readonly today: Day;
+    readonly conflicts: ReadonlyMap<string, string[]>;
+    readonly slot: {
+        min: number;
+        max: number;
+        duration: number;
+        snap: number;
+        scroll: number;
+    };
+    /** Item currently being dragged, if any. */
+    readonly draggingId: string | null;
+    now(): number;
+    meta: WeakMap<Element, ElMeta<D>>;
+    dayArg(day: Day): DayArg;
+    dayClasses(day: Day): string[];
+    isEditable(n: NormalizedItem<D>, what: "start" | "duration"): boolean;
+    /** Renders the element for an item (no position). */
+    createItemEl(meta: ElMeta<D>): HTMLElement;
+    /** Refreshes parts of an item element that depend on position (time label). */
+    refreshItemEl(el: HTMLElement, meta: ElMeta<D>): void;
+    destroyItemEl(el: HTMLElement): void;
+    /** Builds a nav link (day number / header) for a day. */
+    navLink(day: Day, label: Node | string, cls: string): HTMLElement;
+    openMore(day: Day, anchor: HTMLElement, jsEvent: MouseEvent | KeyboardEvent): void;
+    /** Follows a date link: `onNavLink`, or switches to `view` at `day`. */
+    navigate(day: Day, jsEvent: MouseEvent | KeyboardEvent, view?: "day" | "month"): void;
+    /** Swallows the click that follows a drag the view handled itself. */
+    suppressNextClick(): void;
+    /** Row override for the item being dragged in the timeline. */
+    readonly dragRow: {
+        id: string;
+        rowId: string;
+    } | null;
+}
+export interface View {
+    readonly el: HTMLElement;
+    /** Rebuilds everything when `change` is null; otherwise only what it touched. */
+    render(change: StoreChange | null): void;
+    hit(clientX: number, clientY: number): Hit | null;
+    showSelection(sel: Selection | null): void;
+    /** Called once a minute. */
+    tick?(): void;
+    resize?(): void;
+    getScroll(): {
+        top: number;
+        left: number;
+    };
+    setScroll(s: {
+        top: number;
+        left: number;
+    }): void;
+    scrollToTime?(minute: number): void;
+    /** Item elements currently shown for an id. */
+    elementsFor(id: string): HTMLElement[];
+    destroy(): void;
+}
+export declare class ItemPool<D> {
+    private readonly ctx;
+    readonly container: HTMLElement;
+    private readonly recs;
+    private used;
+    constructor(ctx: ViewContext<D>, container: HTMLElement);
+    begin(): void;
+    place(key: string, meta: ElMeta<D>): HTMLElement;
+    end(): void;
+    clear(): void;
+    elementsFor(id: string): HTMLElement[];
+}

package/dist/types/dom/context.d.ts

@@ -0,0 +1,107 @@
+import type { Day } from "../core/date.js";
+import type { ItemOrder } from "../core/layout.js";
+import type { ItemStore, StoreChange } from "../core/store.js";
+import type { NormalizedItem } from "../core/types.js";
+import type { TimeZone } from "../core/zone.js";
+import type { Formatter } from "./format.js";
+import type { CalendarOptions, CalendarText, DayArg, Hit, ItemVariant, ViewInfo } from "./options.js";
+export type Variant = ItemVariant;
+export interface ElMeta<D = unknown> {
+    n: NormalizedItem<D>;
+    day: Day;
+    isStart: boolean;
+    isEnd: boolean;
+    variant: Variant;
+    mirror: boolean;
+}
+/** A time or day range being selected, or previewed for an external drop. */
+export interface Selection {
+    startMs: number;
+    endMs: number;
+    allDay: boolean;
+    startDay: Day;
+    endDay: Day;
+    rowId?: string;
+}
+/** What views get from the calendar. */
+export interface ViewContext<D = unknown> {
+    readonly doc: Document;
+    readonly win: Window;
+    readonly store: ItemStore<D>;
+    readonly opts: CalendarOptions<D>;
+    readonly zone: TimeZone;
+    readonly fmt: Formatter;
+    readonly text: CalendarText;
+    readonly order: ItemOrder<D>;
+    readonly view: ViewInfo;
+    readonly firstDay: number;
+    /** Visible days in order (hidden weekdays removed). */
+    readonly days: Day[];
+    readonly today: Day;
+    readonly conflicts: ReadonlyMap<string, string[]>;
+    readonly slot: {
+        min: number;
+        max: number;
+        duration: number;
+        snap: number;
+        scroll: number;
+    };
+    /** Item currently being dragged, if any. */
+    readonly draggingId: string | null;
+    now(): number;
+    meta: WeakMap<Element, ElMeta<D>>;
+    dayArg(day: Day): DayArg;
+    dayClasses(day: Day): string[];
+    isEditable(n: NormalizedItem<D>, what: "start" | "duration"): boolean;
+    /** Renders the element for an item (no position). */
+    createItemEl(meta: ElMeta<D>): HTMLElement;
+    /** Refreshes parts of an item element that depend on position (time label). */
+    refreshItemEl(el: HTMLElement, meta: ElMeta<D>): void;
+    destroyItemEl(el: HTMLElement): void;
+    /** Builds a nav link (day number / header) for a day. */
+    navLink(day: Day, label: Node | string, cls: string): HTMLElement;
+    openMore(day: Day, anchor: HTMLElement, jsEvent: MouseEvent | KeyboardEvent): void;
+    /** Follows a date link: `onNavLink`, or switches to `view` at `day`. */
+    navigate(day: Day, jsEvent: MouseEvent | KeyboardEvent, view?: "day" | "month"): void;
+    /** Swallows the click that follows a drag the view handled itself. */
+    suppressNextClick(): void;
+    /** Row override for the item being dragged in the timeline. */
+    readonly dragRow: {
+        id: string;
+        rowId: string;
+    } | null;
+}
+export interface View {
+    readonly el: HTMLElement;
+    /** Rebuilds everything when `change` is null; otherwise only what it touched. */
+    render(change: StoreChange | null): void;
+    hit(clientX: number, clientY: number): Hit | null;
+    showSelection(sel: Selection | null): void;
+    /** Called once a minute. */
+    tick?(): void;
+    resize?(): void;
+    getScroll(): {
+        top: number;
+        left: number;
+    };
+    setScroll(s: {
+        top: number;
+        left: number;
+    }): void;
+    scrollToTime?(minute: number): void;
+    /** Item elements currently shown for an id. */
+    elementsFor(id: string): HTMLElement[];
+    destroy(): void;
+}
+export declare class ItemPool<D> {
+    private readonly ctx;
+    readonly container: HTMLElement;
+    private readonly recs;
+    private used;
+    constructor(ctx: ViewContext<D>, container: HTMLElement);
+    begin(): void;
+    place(key: string, meta: ElMeta<D>): HTMLElement;
+    end(): void;
+    clear(): void;
+    elementsFor(id: string): HTMLElement[];
+}

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

@@ -0,0 +1,8 @@
+type Attrs = Record<string, string | number | boolean | null | undefined>;
+/** Creates an element in `doc` (popout windows have their own document). */
+export declare function h<K extends keyof HTMLElementTagNameMap>(doc: Document, tag: K, cls?: string | null, attrs?: Attrs | null, ...children: (Node | string | null | undefined | false)[]): HTMLElementTagNameMap[K];
+export declare function setAttrs(el: Element, attrs: Attrs): void;
+export declare function classList(value: string[] | string | undefined | null): string[];
+export declare function setStyle(el: HTMLElement, props: Record<string, string | number | null>): void;
+export declare function pct(n: number): string;
+export {};

package/dist/types/dom/dom.d.ts

@@ -0,0 +1,8 @@
+type Attrs = Record<string, string | number | boolean | null | undefined>;
+/** Creates an element in `doc` (popout windows have their own document). */
+export declare function h<K extends keyof HTMLElementTagNameMap>(doc: Document, tag: K, cls?: string | null, attrs?: Attrs | null, ...children: (Node | string | null | undefined | false)[]): HTMLElementTagNameMap[K];
+export declare function setAttrs(el: Element, attrs: Attrs): void;
+export declare function classList(value: string[] | string | undefined | null): string[];
+export declare function setStyle(el: HTMLElement, props: Record<string, string | number | null>): void;
+export declare function pct(n: number): string;
+export {};

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

@@ -0,0 +1,30 @@
+import { type Day } from "../core/date.cjs";
+/** Locale-aware labels. Formatting happens on UTC dates built from civil days, so zones never shift them. */
+export declare class Formatter {
+    private readonly cache;
+    readonly locale: string | undefined;
+    readonly hour12: boolean;
+    constructor(locale: string | undefined, hour12: boolean | undefined);
+    private fmt;
+    private d;
+    weekdayShort(day: Day): string;
+    weekdayLong(day: Day): string;
+    weekdayNarrow(day: Day): string;
+    dayNumber(day: Day): string;
+    monthShort(day: Day): string;
+    monthLong(day: Day): string;
+    monthYear(day: Day): string;
+    year(day: Day): string;
+    fullDate(day: Day): string;
+    longDate(day: Day): string;
+    listDay(day: Day): string;
+    /** "Oct 19 – 25, 2026" style. */
+    range(startDay: Day, lastDay: Day): string;
+    /** Wall-clock minutes to a label. `compact` drops ":00" in 12-hour formats ("9am"). */
+    time(minute: number, compact?: boolean): string;
+    /** Hour labels for the gutter. */
+    slotLabel(minute: number): string;
+    isoDate(day: Day): string;
+}
+/** First day of the week for a locale (0 = Sunday), from Intl.Locale weekInfo where supported. */
+export declare function localeFirstDay(locale: string | undefined): number;

package/dist/types/dom/format.d.ts

@@ -0,0 +1,30 @@
+import { type Day } from "../core/date.js";
+/** Locale-aware labels. Formatting happens on UTC dates built from civil days, so zones never shift them. */
+export declare class Formatter {
+    private readonly cache;
+    readonly locale: string | undefined;
+    readonly hour12: boolean;
+    constructor(locale: string | undefined, hour12: boolean | undefined);
+    private fmt;
+    private d;
+    weekdayShort(day: Day): string;
+    weekdayLong(day: Day): string;
+    weekdayNarrow(day: Day): string;
+    dayNumber(day: Day): string;
+    monthShort(day: Day): string;
+    monthLong(day: Day): string;
+    monthYear(day: Day): string;
+    year(day: Day): string;
+    fullDate(day: Day): string;
+    longDate(day: Day): string;
+    listDay(day: Day): string;
+    /** "Oct 19 – 25, 2026" style. */
+    range(startDay: Day, lastDay: Day): string;
+    /** Wall-clock minutes to a label. `compact` drops ":00" in 12-hour formats ("9am"). */
+    time(minute: number, compact?: boolean): string;
+    /** Hour labels for the gutter. */
+    slotLabel(minute: number): string;
+    isoDate(day: Day): string;
+}
+/** First day of the week for a locale (0 = Sunday), from Intl.Locale weekInfo where supported. */
+export declare function localeFirstDay(locale: string | undefined): number;