@ziix/calendar 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,433 @@
+import { Dayjs } from 'dayjs';
+
+export declare function buildAxis(slot?: SlotConfig): SlotAxis;
+
+/**
+ * The public, framework-agnostic calendar. Construct with a host element and
+ * options, then `render()`. Mirrors the imperative surface hosts rely on
+ * (render/destroy/refetchEvents/addEvent/getEventById/gotoDate/changeView/…) so
+ * Preact and React callers can drive it through a ref.
+ */
+export declare class Calendar {
+    readonly el: HTMLElement;
+    options: CalendarOptions;
+    readonly events: EventStore;
+    readonly resources: ResourceStore;
+    private _date;
+    private _view;
+    private viewImpl;
+    private bodyEl;
+    private titleEl;
+    constructor(el: HTMLElement, options?: CalendarOptions);
+    get tz(): string | undefined;
+    get date(): Dayjs;
+    get view(): ViewType;
+    get axis(): SlotAxis;
+    get locale(): Locale;
+    get firstDay(): number;
+    /** Start of the currently-shown view range, in the calendar timezone. */
+    get activeStart(): Dayjs;
+    /** End of the currently-shown view range. */
+    get activeEnd(): Dayjs;
+    /** The active view's type and date window (parity with FullCalendar's `view`). */
+    getView(): {
+        type: ViewType;
+        activeStart: Dayjs;
+        activeEnd: Dayjs;
+    };
+    private isDayClosed;
+    get editable(): boolean;
+    get selectable(): boolean;
+    now(): Dayjs;
+    render(): this;
+    destroy(): void;
+    private createView;
+    private mountView;
+    changeView(type: ViewType): void;
+    gotoDate(date: string | Date | Dayjs): void;
+    today(): void;
+    prev(): void;
+    next(): void;
+    /** Refetch resources (if a function source), rebuild structure, then events. */
+    reload(): Promise<void>;
+    private refetchResources;
+    refetchEvents(): Promise<void>;
+    addEvent(input: EventInput): EventHandle;
+    getEventById(id: string | number): EventHandle | null;
+    getEvents(): CalEvent[];
+    getResources(): CalResource[];
+    getResourceById(id: string | number): ResourceHandle | null;
+    private resourceHandle;
+    private handle;
+    /** Build the inner body of an event, honouring the `renderEvent` hook. */
+    renderEventContent(event: CalEvent): HTMLElement;
+    private defaultEventContent;
+    fireEventClick(event: CalEvent, el: HTMLElement, jsEvent: MouseEvent): void;
+    fireEventMount(event: CalEvent, el: HTMLElement): void;
+    /** Attach a right-click handler to an event bar when `onEventContextMenu` is set. */
+    bindContextMenu(el: HTMLElement, event: CalEvent): void;
+    /** Whether events are allowed to overlap on the same resource (default true). */
+    private allowsOverlap;
+    private hasCollision;
+    /**
+     * Apply a drag/resize result: gate on `eventOverlap`, mutate the event,
+     * re-render, and fire `onEventChange`. Returns false (and reverts the live
+     * preview by re-rendering) when the move is rejected.
+     */
+    commitEventChange(event: CalEvent, start: Dayjs, end: Dayjs, resourceId: string | null): boolean;
+    /** Gate a drag-selection on `selectAllow`, then fire `onSelect`. */
+    commitSelect(start: Dayjs, end: Dayjs, resource: CalResource | null, jsEvent: MouseEvent): boolean;
+    private renderToolbar;
+    private renderToolbarToken;
+    private updateTitle;
+    private emitDatesSet;
+}
+
+export declare interface CalendarOptions {
+    view?: ViewType;
+    date?: string | Date;
+    locale?: Locale | string;
+    timezone?: string;
+    firstDay?: number;
+    weekends?: boolean;
+    slot?: SlotConfig;
+    /** Intl options for the default event time rendering. */
+    timeFormat?: Intl.DateTimeFormatOptions;
+    nowIndicator?: boolean;
+    /**
+     * Mark the shown day as closed/non-business — tints the time grid with the
+     * `--zc-nonbusiness` colour. Pass a boolean, or a predicate evaluated against
+     * the current date (re-evaluated on navigation).
+     */
+    dayClosed?: boolean | ((date: Dayjs) => boolean);
+    editable?: boolean;
+    selectable?: boolean;
+    height?: number | string;
+    /**
+     * Minimum height (px) of a single stacked event in the timeline. The resource
+     * row grows to `levels × eventMinHeight` so overlapping events keep this height
+     * instead of being squashed. Default 48.
+     */
+    eventMinHeight?: number;
+    toolbar?: ToolbarConfig | false;
+    buttons?: Record<string, CustomButton>;
+    resources?: ResourceSource;
+    resourceArea?: ResourceAreaConfig;
+    resourceGroupField?: string;
+    resourceOrder?: string;
+    events?: EventSource_2;
+    /** Custom event body renderer. Return a string (innerHTML) or a node. */
+    renderEvent?: (event: CalEvent) => HTMLElement | string;
+    /** Custom resource label renderer. */
+    renderResource?: (resource: CalResource) => HTMLElement | string;
+    eventOverlap?: boolean | (() => boolean);
+    selectAllow?: (info: {
+        start: Dayjs;
+        end: Dayjs;
+        resource: CalResource | null;
+    }) => boolean;
+    onEventClick?: (info: EventClickInfo) => void;
+    /** Right-click on an event. The native menu is suppressed before this fires. */
+    onEventContextMenu?: (info: EventContextMenuInfo) => void;
+    onEventChange?: (info: EventChangeInfo) => void;
+    onSelect?: (info: SelectInfo) => void;
+    onDatesSet?: (info: DatesSetInfo) => void;
+    onEventMount?: (info: EventMountInfo) => void;
+    onEventsSet?: (events: CalEvent[]) => void;
+}
+
+/** Normalised event used internally and exposed to callbacks. */
+export declare interface CalEvent {
+    id: string;
+    title: string;
+    start: Dayjs;
+    end: Dayjs;
+    resourceId: string | null;
+    allDay: boolean;
+    color?: string;
+    textColor?: string;
+    extendedProps: Record<string, unknown>;
+    /** The original, untouched input. */
+    raw: EventInput;
+}
+
+/** Normalised resource used internally and exposed to callbacks. */
+export declare interface CalResource {
+    id: string;
+    title: string;
+    group: string | null;
+    order: number;
+    /** Arbitrary domain data, mutable via the resource handle's setExtendedProp. */
+    extendedProps: Record<string, unknown>;
+    raw: ResourceInput;
+}
+
+export declare interface CustomButton {
+    text?: string;
+    /** CSS class for an icon span (e.g. an icon-font class). */
+    icon?: string;
+    onClick: (jsEvent: MouseEvent) => void;
+}
+
+/** A start/end window expressed in the calendar's timezone. */
+export declare interface DateRange {
+    start: Dayjs;
+    end: Dayjs;
+}
+
+export declare interface DatesSetInfo {
+    start: Dayjs;
+    end: Dayjs;
+    view: ViewType;
+}
+
+/** Minutes from midnight for a Dayjs, read in its own (tz-applied) clock. */
+export declare function dayMinutes(d: Dayjs): number;
+
+export declare interface EventChangeInfo {
+    event: CalEvent;
+    oldEvent: CalEvent;
+    /** Undo the change (e.g. when a server persist fails) and re-render. */
+    revert: () => void;
+}
+
+export declare interface EventClickInfo {
+    event: CalEvent;
+    el: HTMLElement;
+    jsEvent: MouseEvent;
+}
+
+export declare interface EventContextMenuInfo {
+    event: CalEvent;
+    el: HTMLElement;
+    /** The contextmenu event; `preventDefault()` has already been called. */
+    jsEvent: MouseEvent;
+}
+
+/** Handle returned by addEvent/getEventById, mirroring the imperative API hosts rely on. */
+export declare interface EventHandle {
+    id: string;
+    event: CalEvent;
+    remove(): void;
+    setExtendedProp(key: string, value: unknown): void;
+}
+
+/** Raw event as supplied by the host application. */
+export declare interface EventInput {
+    id: string | number;
+    title?: string;
+    start: string | Date;
+    end?: string | Date;
+    resourceId?: string | number;
+    allDay?: boolean;
+    /** Background colour (any CSS colour). */
+    color?: string;
+    /** Foreground/text colour. */
+    textColor?: string;
+    /** Arbitrary domain data forwarded to renderEvent and callbacks. */
+    extendedProps?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+
+export declare interface EventMountInfo {
+    event: CalEvent;
+    el: HTMLElement;
+}
+
+declare type EventSource_2 = EventInput[] | ((range: DateRange) => EventInput[] | Promise<EventInput[]>);
+export { EventSource_2 as EventSource }
+
+/** Normalises raw event input, dedupes by id, and answers range/resource queries. */
+export declare class EventStore {
+    private tz?;
+    private map;
+    constructor(tz?: string | undefined);
+    normalize(input: EventInput): CalEvent;
+    /** Replace the entire set, deduping by id (last write wins). */
+    set(inputs: EventInput[]): void;
+    add(input: EventInput): CalEvent;
+    remove(id: string | number): boolean;
+    get(id: string | number): CalEvent | undefined;
+    all(): CalEvent[];
+    /**
+     * Events overlapping [start, end). When `resourceId` is supplied (including
+     * `null` for unassigned), only events on that resource are returned.
+     */
+    inRange(start: Dayjs, end: Dayjs, resourceId?: string | null): CalEvent[];
+}
+
+/** Format an absolute instant in the given timezone via Intl. */
+export declare function intlFormat(d: Dayjs, opts: Intl.DateTimeFormatOptions, localeTag: string, tz?: string): string;
+
+/**
+ * Locale strings and behaviour. This is the single place every piece of text the
+ * calendar renders itself can be translated — pass your app's translations here.
+ * All other visible text (column headers, resource labels, event content) is
+ * supplied by you through the render hooks, and dates are formatted via `Intl`
+ * using `intl`.
+ */
+export declare interface Locale {
+    /** BCP-47-ish code, e.g. 'da'. */
+    code: string;
+    /** Day the week starts on (0 = Sunday). Overrides `firstDay` option when set. */
+    firstDay?: number;
+    /** Toolbar button labels. */
+    buttons?: {
+        today?: string;
+        prev?: string;
+        next?: string;
+    };
+    /** Accessible labels for icon buttons. */
+    ariaLabels?: {
+        today?: string;
+        prev?: string;
+        next?: string;
+    };
+    /** Intl locale tag for date formatting; defaults to `code`. */
+    intl?: string;
+}
+
+/** Format minutes-from-midnight back to a zero-padded 'HH:mm'. */
+export declare function minutesToTime(min: number): string;
+
+/** "Now" in the calendar timezone. */
+export declare function nowTz(tz?: string): Dayjs;
+
+export declare interface PackedEvent {
+    event: CalEvent;
+    /** Column index within the cluster. */
+    col: number;
+    /** Number of columns in the cluster. */
+    cols: number;
+    /** Left offset as a 0..1 fraction of the column width. */
+    left: number;
+    /** Width as a 0..1 fraction of the column width. */
+    width: number;
+}
+
+/**
+ * Pack events that share a single column (resource/day) into side-by-side
+ * sub-columns so overlapping events never cover each other — the classic
+ * interval-graph greedy colouring FullCalendar uses.
+ *
+ * Events are expected to already belong to the same column; callers filter by
+ * resource first.
+ */
+export declare function packEvents(events: CalEvent[]): PackedEvent[];
+
+export declare interface ResourceAreaConfig {
+    width?: number | string;
+    columns?: ResourceColumn[];
+}
+
+export declare interface ResourceColumn {
+    /** Resource field to read for a plain-text cell. */
+    field?: string;
+    /** Column header text. */
+    header?: string;
+    width?: number | string;
+    /** Custom cell renderer; takes precedence over `field`. */
+    render?: (resource: CalResource) => HTMLElement | string;
+}
+
+/** Handle returned by getResourceById; lets hosts push live data into a resource. */
+export declare interface ResourceHandle {
+    id: string;
+    resource: CalResource;
+    /** Update an extendedProps value and re-render the resource area. */
+    setExtendedProp(key: string, value: unknown): void;
+    /** Update a top-level resource field (e.g. title) and re-render. */
+    setProp(key: 'title' | 'group', value: string): void;
+}
+
+/** Raw resource as supplied by the host application. */
+export declare interface ResourceInput {
+    id: string | number;
+    title?: string;
+    group?: string;
+    order?: number;
+    /** Arbitrary domain data (e.g. workHours, punchinout, badges). */
+    extendedProps?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+
+export declare type ResourceSource = ResourceInput[] | ((range: DateRange) => ResourceInput[] | Promise<ResourceInput[]>);
+
+/** Normalises resources, reads the configured group/order fields, and sorts. */
+export declare class ResourceStore {
+    private groupField;
+    private orderField;
+    private list;
+    constructor(groupField?: string, orderField?: string);
+    normalize(input: ResourceInput): CalResource;
+    set(inputs: ResourceInput[]): void;
+    all(): CalResource[];
+    get(id: string | number): CalResource | undefined;
+    /**
+     * Resources in display order. With `resourceOrder: 'id'` they are sorted by a
+     * natural id comparison (so 'E2' precedes 'E10'); with a numeric order field
+     * they sort by it; otherwise the original input order is preserved (sort is
+     * stable), matching FullCalendar's default.
+     */
+    ordered(): CalResource[];
+    /**
+     * Grouped resources preserving first-seen group order. Returns a flat list of
+     * `{ group, resources }` buckets; ungrouped resources land in a `null` bucket.
+     */
+    grouped(): Array<{
+        group: string | null;
+        resources: CalResource[];
+    }>;
+}
+
+export declare interface SelectInfo {
+    start: Dayjs;
+    end: Dayjs;
+    resource: CalResource | null;
+    jsEvent: MouseEvent | PointerEvent;
+}
+
+/** Resolved, numeric time-axis derived from a SlotConfig. */
+export declare interface SlotAxis {
+    /** First visible minute from midnight. */
+    min: number;
+    /** Last visible minute from midnight. */
+    max: number;
+    /** Minutes per slot. */
+    duration: number;
+    /** Minutes between axis labels. */
+    labelInterval: number;
+    /** Number of whole slots between min and max. */
+    slots: number;
+    /** Total visible minutes (max - min). */
+    totalMinutes: number;
+}
+
+/** Vertical/horizontal time-axis configuration. */
+export declare interface SlotConfig {
+    /** Slot granularity in minutes (default 15). */
+    duration?: number;
+    /** First visible time as 'HH:mm' (default '00:00'). */
+    min?: string;
+    /** Last visible time as 'HH:mm', '24:00' allowed (default '24:00'). */
+    max?: string;
+    /** Minutes between axis labels (default 60). */
+    labelInterval?: number;
+}
+
+/** Parse 'HH:mm' / 'HH:mm:ss' / '24:00' into minutes from midnight. */
+export declare function timeToMinutes(t: string): number;
+
+export declare interface ToolbarConfig {
+    start?: string;
+    center?: string;
+    end?: string;
+}
+
+/** Parse a value into a Dayjs anchored to `tz` (the shop timezone), if given. */
+export declare function toTz(value: string | Date | Dayjs, tz?: string): Dayjs;
+
+/** Built-in view identifiers. */
+export declare type ViewType = 'day' | 'resource-day' | 'timeline';
+
+export { }

package/dist/ziix-calendar.css

@@ -0,0 +1 @@
+.zc{--zc-border: #e2e2e2;--zc-bg: #ffffff;--zc-muted-bg: #f6f6f6;--zc-fg: #1a1a1a;--zc-muted-fg: #6b7280;--zc-today-bg: #f0f6ff;--zc-now: #ef4444;--zc-btn-bg: transparent;--zc-btn-fg: var(--zc-fg);--zc-btn-border: var(--zc-border);--zc-btn-hover-bg: var(--zc-muted-bg);--zc-btn-active-bg: #e7efff;--zc-event-bg: #c7dbff;--zc-event-border: #a9c6ff;--zc-event-fg: #1e3a5f;--zc-nonbusiness: oklch(0 0 0 / .045);--zc-radius: 6px;--zc-font: inherit;display:flex;flex-direction:column;box-sizing:border-box;font-family:var(--zc-font);color:var(--zc-fg);background:var(--zc-bg)}.zc *,.zc *:before,.zc *:after{box-sizing:border-box}.zc-toolbar{display:flex;align-items:center;justify-content:space-between;gap:.5rem;padding:.5rem .75rem;flex:0 0 auto}.zc-toolbar-section{display:flex;align-items:center;gap:.375rem}.zc-btn-group{display:inline-flex}.zc-btn-group .zc-btn:not(:first-child){border-top-left-radius:0;border-bottom-left-radius:0;margin-left:-1px}.zc-btn-group .zc-btn:not(:last-child){border-top-right-radius:0;border-bottom-right-radius:0}.zc-toolbar-center{flex:1 1 auto;justify-content:center}.zc-title{margin:0;font-size:1rem;font-weight:600;text-transform:capitalize}.zc-btn{-webkit-appearance:none;-moz-appearance:none;appearance:none;cursor:pointer;font:inherit;font-size:.875rem;line-height:1.2;padding:.375rem .75rem;border-radius:var(--zc-radius);border:1px solid var(--zc-btn-border);background:var(--zc-btn-bg);color:var(--zc-btn-fg)}.zc-btn:hover{background:var(--zc-btn-hover-bg)}.zc-btn:active{background:var(--zc-btn-active-bg)}.zc-body{flex:1 1 auto;overflow:auto;position:relative;border-top:1px solid var(--zc-border)}.zc-timegrid{display:flex;align-items:stretch;position:relative;min-height:100%}.zc-axis{position:relative;flex:0 0 56px;border-right:1px solid var(--zc-border)}.zc-axis-label{position:absolute;right:6px;transform:translateY(-50%);font-size:.6875rem;color:var(--zc-muted-fg);white-space:nowrap}.zc-col{position:relative;flex:1 1 auto}.zc-slot-line{position:absolute;left:0;right:0;border-top:1px solid var(--zc-border);opacity:.4}.zc-slot-line.zc-slot-major{opacity:1}.zc-event{position:absolute;overflow:hidden;border-radius:var(--zc-radius);border:1px solid var(--zc-event-border);background:var(--zc-event-bg);color:var(--zc-event-fg);font-size:.75rem;cursor:pointer}.zc-event-main{padding:2px 4px;height:100%}.zc-event-default{display:flex;flex-direction:column;gap:1px;line-height:1.2}.zc-event-time{font-variant-numeric:tabular-nums;opacity:.85}.zc-event-title{font-weight:600;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}.zc-timeline{position:absolute;top:0;right:0;bottom:0;left:0;display:flex;align-items:stretch}.zc-tl-resource-area{display:flex;flex-direction:column;overflow:hidden;border-right:1px solid var(--zc-border);background:var(--zc-bg)}.zc-tl-resource-head,.zc-tl-resource-row{display:flex;align-items:stretch;flex:0 0 auto}.zc-tl-resource-head{border-bottom:1px solid var(--zc-border);background:var(--zc-muted-bg);font-weight:600;font-size:.75rem}.zc-tl-col-head{display:flex;align-items:center;padding:0 .5rem;overflow:hidden;white-space:nowrap}.zc-tl-resource-body{flex:1 1 auto;overflow:hidden}.zc-tl-resource-row{border-bottom:1px solid var(--zc-border)}.zc-tl-col-cell{display:flex;flex-direction:column;justify-content:center;padding:.25rem .5rem;overflow:hidden;font-size:.8125rem;min-width:0}.zc-tl-group-row{display:flex;align-items:center;padding:0 .5rem;background:var(--zc-muted-bg);color:var(--zc-muted-fg);font-size:.6875rem;font-weight:700;text-transform:uppercase;letter-spacing:.03em}.zc-tl-time-area{display:flex;flex-direction:column;flex:1 1 auto;min-width:0;overflow:hidden}.zc-tl-time-head{flex:0 0 auto;overflow:hidden;position:relative;border-bottom:1px solid var(--zc-border);background:var(--zc-muted-bg)}.zc-tl-axis{position:relative;height:100%}.zc-tl-axis-label{position:absolute;top:0;bottom:0;display:flex;align-items:center;padding-left:4px;font-size:.6875rem;color:var(--zc-muted-fg);white-space:nowrap;border-left:1px solid var(--zc-border)}.zc-tl-time-body{flex:1 1 auto;overflow:auto;position:relative}.zc-tl-time-canvas{position:relative;min-height:100%}.zc-tl-overlay{position:absolute;top:0;right:0;bottom:0;left:0;pointer-events:none;z-index:0}.zc-tl-vline{position:absolute;top:0;bottom:0;border-left:1px solid var(--zc-border);opacity:.6}.zc-tl-now{position:absolute;top:0;bottom:0;border-left:2px solid var(--zc-now);z-index:3}.zc-tl-rows{position:relative;z-index:1}.zc-tl-row{position:relative;border-bottom:1px solid var(--zc-border)}.zc-tl-group-spacer{background:var(--zc-muted-bg);opacity:.5}.zc-tl-event{display:flex;align-items:stretch}.zc-tl-event .zc-event-main{padding:3px 6px}.zc-rg{position:absolute;top:0;right:0;bottom:0;left:0;overflow-y:auto;overflow-x:hidden}.zc-rg-head{position:sticky;top:0;z-index:5;display:flex;align-items:stretch;background:var(--zc-muted-bg);border-bottom:1px solid var(--zc-border)}.zc-rg-corner{flex:0 0 56px;width:56px;border-right:1px solid var(--zc-border)}.zc-rg-head-cols{flex:1 1 auto;display:flex;flex-direction:column;min-width:0}.zc-rg-group-row,.zc-rg-label-row{display:flex;align-items:stretch}.zc-rg-group-band{display:flex;align-items:center;justify-content:center;padding:2px 4px;border-left:1px solid var(--zc-border);font-size:.625rem;font-weight:700;text-transform:uppercase;letter-spacing:.03em;color:var(--zc-muted-fg);overflow:hidden;white-space:nowrap}.zc-rg-label{flex:1 1 0;display:flex;align-items:center;justify-content:center;padding:4px 6px;border-left:1px solid var(--zc-border);font-size:.8125rem;font-weight:600;min-width:0;overflow:hidden;text-align:center}.zc-rg-canvas{display:flex;align-items:stretch}.zc-rg-cols{position:relative;flex:1 1 auto;display:flex;align-items:stretch;min-width:0}.zc-rg-col{position:relative;flex:1 1 0;border-left:1px solid var(--zc-border);min-width:0}.zc-rg-col>.zc-select-box{left:2px;right:2px}.zc-rg-now{z-index:4}.zc-body.zc-closed .zc-col,.zc-body.zc-closed .zc-tl-time-canvas,.zc-body.zc-closed .zc-rg-cols{background:var(--zc-nonbusiness)}.zc-event.zc-dragging{z-index:6;opacity:.9;box-shadow:0 2px 8px #0000002e}.zc-resize-handle{position:absolute;z-index:2}.zc-resize-s{left:0;right:0;bottom:0;height:6px;cursor:ns-resize}.zc-resize-e,.zc-resize-w{top:0;bottom:0;width:6px;cursor:ew-resize}.zc-resize-e{right:0}.zc-resize-w{left:0}.zc-select-box{position:absolute;z-index:5;background:var(--zc-event-bg);border:1px solid var(--zc-event-border);opacity:.45;pointer-events:none;border-radius:var(--zc-radius)}.zc-col>.zc-select-box{left:2px;right:2px}.zc-tl-select{top:2px;bottom:2px}.zc-tl-row.zc-drop-target{background:var(--zc-today-bg)}.zc-now-indicator{position:absolute;left:0;right:0;height:0;border-top:2px solid var(--zc-now);z-index:4;pointer-events:none}.zc-now-indicator:before{content:"";position:absolute;left:-1px;top:-4px;width:7px;height:7px;border-radius:50%;background:var(--zc-now)}