@besaitech/ng-design-system 0.0.77 → 0.0.79

package/calendar/index.d.ts

@@ -0,0 +1,277 @@
+import * as _angular_core from '@angular/core';
+import { SdsSegmentedOption } from '@besaitech/ng-design-system';
+
+/** Which span of time the calendar is showing. */
+type SdsEventCalendarView = 'month' | 'week' | '3day' | 'day';
+/**
+ * How an event is tinted. These map onto the library's existing accent roles, so an event picks a
+ * meaning-free hue — it is NOT a severity and NOT a status. Anything clinical that needs to say
+ * "how bad" belongs in `sds-severity`, which has its own measured ramp.
+ */
+type SdsEventColor = 'brand' | 'blue' | 'green' | 'amber' | 'red' | 'indigo' | 'neutral';
+/**
+ * One thing on the calendar.
+ *
+ * <p>`start`/`end` are Dates or anything `new Date(...)` parses. Everything is computed in the
+ * BROWSER's timezone: a calendar shows a person their own day, and converting on the way in is the
+ * caller's job if their data says otherwise.
+ */
+interface SdsCalendarEvent<T = unknown> {
+    id: string;
+    title: string;
+    start: Date | string | number;
+    /** Defaults to `start` + `defaultMinutes` when absent — a zero-length block is unclickable. */
+    end?: Date | string | number;
+    /** Second line, shown where there is room: a room, a reason, a phone number. */
+    subtitle?: string;
+    allDay?: boolean;
+    color?: SdsEventColor;
+    /** Struck through and faded — a cancelled appointment is still part of the day's record. */
+    cancelled?: boolean;
+    /** Whatever the caller wants back on click. The component never reads it. */
+    meta?: T;
+}
+/** An event resolved to real Dates, with its place in the grid worked out. */
+interface PlacedEvent<T = unknown> {
+    event: SdsCalendarEvent<T>;
+    start: Date;
+    end: Date;
+    /** 0..1 of the visible day height. */
+    top: number;
+    height: number;
+    /** 0..1 across the column: side-by-side layout for events sharing a time. */
+    left: number;
+    width: number;
+}
+declare function toDate(value: Date | string | number): Date;
+/** Minutes since local midnight. Read off the clock, never from an epoch difference — see below. */
+declare function minutesOfDay(d: Date): number;
+declare function startOfWeek(d: Date, firstDayOfWeek: number): Date;
+/**
+ * The days a view shows.
+ *
+ * <p>`month` is always a 6×7 block, never 4–6 ragged rows: a grid that changes height as you page
+ * through the year makes everything below it jump.
+ */
+declare function visibleDays(view: SdsEventCalendarView, date: Date, firstDayOfWeek: number): Date[];
+/** The half-open range a view covers — what a host should fetch for. */
+declare function visibleRange(view: SdsEventCalendarView, date: Date, firstDayOfWeek: number): {
+    start: Date;
+    end: Date;
+};
+/** Paging: one month, one week, three days or one day at a time, in the view's own unit. */
+declare function step(view: SdsEventCalendarView, date: Date, direction: 1 | -1): Date;
+/** Whether an event touches a given day at all. Half-open: an event ending at 00:00 is not there. */
+declare function occursOn(start: Date, end: Date, day: Date): boolean;
+/**
+ * Place one day's timed events in the grid, side by side where they overlap.
+ *
+ * <p>The classic column packing: events are clustered into runs that transitively overlap, each
+ * takes the leftmost column that is free at its time, and the whole cluster is then divided by the
+ * widest point. So two appointments at 09:00 each take half the width and a third takes a third —
+ * and a 14:00 appointment with nothing beside it is full width, because it is in its own cluster.
+ *
+ * <p><b>Vertical position is read off the clock, not from an epoch difference.</b> On the two days a
+ * year when the clocks move, a 09:00–10:00 appointment is still drawn at 09:00 and one hour tall;
+ * computing it from elapsed milliseconds would slide every event after the change by an hour.
+ *
+ * <p>Events are clipped to the visible window rather than dropped: a night shift starting at 06:00
+ * on a grid that opens at 08:00 should still show, flush to the top, not vanish.
+ */
+declare function placeDay<T>(events: readonly SdsCalendarEvent<T>[], day: Date, startHour: number, endHour: number, defaultMinutes: number): PlacedEvent<T>[];
+/**
+ * A dragged minute, snapped to the grid and held inside the visible window.
+ *
+ * <p>Clamping is not cosmetic: without it a drag that leaves the top of the grid proposes a time
+ * before the practice opens, and the host either books it or has to invent the same rule itself.
+ */
+declare function snapMinute(minute: number, stepMinutes: number, startHour: number, endHour: number): number;
+/** The all-day (and multi-day) events touching a given day, in a stable order. */
+declare function allDayOn<T>(events: readonly SdsCalendarEvent<T>[], day: Date, defaultMinutes: number): SdsCalendarEvent<T>[];
+/** Every event touching a day, all-day first then by start — what a month cell lists. */
+declare function eventsOn<T>(events: readonly SdsCalendarEvent<T>[], day: Date, defaultMinutes: number): SdsCalendarEvent<T>[];
+
+/** Where an event was dropped. The component reports; the host decides whether it sticks. */
+interface SdsCalendarDrop<T = unknown> {
+    event: SdsCalendarEvent<T>;
+    start: Date;
+    end: Date;
+}
+/** A click on empty time: what a host turns into "new appointment". */
+interface SdsCalendarSlot {
+    start: Date;
+    end: Date;
+}
+interface SdsCalendarRange {
+    start: Date;
+    end: Date;
+    view: SdsEventCalendarView;
+}
+/**
+ * A calendar of events — month, week, three days or one day.
+ *
+ * <p><b>Not {@link SdsCalendar}</b>, which is the month grid inside the date picker and exists to
+ * pick a date. This one shows what is ON the days, and it owns no data: the host passes `events`
+ * and listens to `rangeChange` to fetch the next lot.
+ *
+ * <p><b>It stores nothing and decides nothing.</b> `view` and `date` are two-way models, so the
+ * host can deep-link a view or restore one; every interaction is an output. That is what lets the
+ * same component serve a doctor's diary, a room's bookings or a delivery schedule without knowing
+ * what any of them are.
+ *
+ * <p><b>Dates come from `Intl`, control words come from you.</b> Day and month names follow
+ * `[locale]` automatically, so the part that is genuinely per-language needs no wiring — but
+ * "Today", "All day" and "+2 more" are inputs with English defaults, and a non-English app MUST
+ * pass them. An icon-only control's accessible name is the only name it has.
+ *
+ * <p><b>Mobile.</b> The week view keeps a readable minimum column width and scrolls sideways under
+ * its own header rather than squeezing seven columns onto a phone; the month view drops from chips
+ * to dots below `sm`. Both are CSS, so there is no resize listener to get wrong and no layout that
+ * depends on JavaScript having run.
+ *
+ * @example
+ * <sds-event-calendar
+ *   [events]="appointments()"
+ *   [(view)]="view"
+ *   [(date)]="focused"
+ *   [todayLabel]="'calendar.today' | translate"
+ *   (eventClick)="open($event)"
+ *   (rangeChange)="load($event)" />
+ */
+declare class SdsEventCalendar<T = unknown> {
+    private readonly destroyRef;
+    private readonly host;
+    readonly events: _angular_core.InputSignal<readonly SdsCalendarEvent<T>[]>;
+    /** Two-way: the host can deep-link or restore a view. */
+    readonly view: _angular_core.ModelSignal<SdsEventCalendarView>;
+    /** Two-way: any day inside the span being shown. */
+    readonly date: _angular_core.ModelSignal<Date>;
+    /** 1 = Monday (the European week), 0 = Sunday. */
+    readonly firstDayOfWeek: _angular_core.InputSignalWithTransform<number, unknown>;
+    /** The hours the time grid shows. Events outside are clipped to the edge, never dropped. */
+    readonly startHour: _angular_core.InputSignalWithTransform<number, unknown>;
+    readonly endHour: _angular_core.InputSignalWithTransform<number, unknown>;
+    readonly hourHeight: _angular_core.InputSignalWithTransform<number, unknown>;
+    /** How long an event with no `end` is assumed to last. */
+    readonly defaultMinutes: _angular_core.InputSignalWithTransform<number, unknown>;
+    /** CSS height of the scrolling body (month: of the whole grid). */
+    readonly height: _angular_core.InputSignal<string>;
+    /** BCP-47 tag for day and month names. Empty follows the browser. */
+    readonly locale: _angular_core.InputSignal<string>;
+    readonly nowIndicator: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    readonly showToolbar: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    readonly showViewSwitcher: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Chips per month cell before it collapses to "+N". */
+    readonly maxPerCell: _angular_core.InputSignalWithTransform<number, unknown>;
+    /** Control words. English defaults — a non-English app must pass every one of these. */
+    readonly todayLabel: _angular_core.InputSignal<string>;
+    readonly previousLabel: _angular_core.InputSignal<string>;
+    readonly nextLabel: _angular_core.InputSignal<string>;
+    readonly allDayLabel: _angular_core.InputSignal<string>;
+    /** `{count}` is substituted. */
+    readonly moreLabel: _angular_core.InputSignal<string>;
+    readonly viewSwitcherLabel: _angular_core.InputSignal<string>;
+    readonly monthLabel: _angular_core.InputSignal<string>;
+    readonly weekLabel: _angular_core.InputSignal<string>;
+    readonly threeDayLabel: _angular_core.InputSignal<string>;
+    readonly dayLabel: _angular_core.InputSignal<string>;
+    /**
+     * Let an event be dragged to another time or day. <b>Opt-in</b>: a calendar whose host does not
+     * persist the move would show an appointment settle somewhere it has not been booked, which is
+     * worse than not offering the gesture.
+     */
+    readonly draggable: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Drag across empty time to propose a span. The plain click keeps emitting `slotClick`. */
+    readonly selectable: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Both gestures snap to this. 15 minutes is the finest grid anybody reads off a week view. */
+    readonly snapMinutes: _angular_core.InputSignalWithTransform<number, unknown>;
+    readonly eventClick: _angular_core.OutputEmitterRef<SdsCalendarEvent<T>>;
+    /**
+     * An event was dragged somewhere else. The component does NOT move it: it reports where it was
+     * dropped and redraws from `events` as before, so the diary only changes once the host says it
+     * did. A drag that moved the chip locally would show a booking that does not exist whenever the
+     * write is refused.
+     */
+    readonly eventDrop: _angular_core.OutputEmitterRef<SdsCalendarDrop<T>>;
+    /** A span was dragged out across empty time — "book something from here to here". */
+    readonly rangeSelect: _angular_core.OutputEmitterRef<SdsCalendarSlot>;
+    /** A click on empty time, snapped to the hour that was clicked. */
+    readonly slotClick: _angular_core.OutputEmitterRef<SdsCalendarSlot>;
+    readonly dayClick: _angular_core.OutputEmitterRef<Date>;
+    /** The span now on screen — fetch for this. Fires whenever the view or the date moves. */
+    readonly rangeChange: _angular_core.OutputEmitterRef<SdsCalendarRange>;
+    /** Ticks the now-indicator. One timer, cleared with the component. */
+    private readonly now;
+    /** The gesture in flight, if any. Null between gestures — there is never more than one. */
+    private readonly drag;
+    /** Set once the pointer has moved far enough to be a drag rather than a click. */
+    private readonly dragging;
+    /**
+     * A finished drag still produces a click, and it arrives AFTER pointerup — so checking
+     * "am I dragging" inside the click handler is always false by then. Measured: dropping an event
+     * emitted `eventDrop` AND `slotClick`, so a host both moved the appointment and opened a
+     * "new appointment" panel for where the finger lifted. This survives until the click it has to
+     * swallow, and is cleared either way.
+     */
+    private suppressClick;
+    constructor();
+    protected readonly days: _angular_core.Signal<Date[]>;
+    protected readonly hours: _angular_core.Signal<number[]>;
+    protected readonly bodyHeight: _angular_core.Signal<number>;
+    protected readonly columns: _angular_core.Signal<string>;
+    /** Keeps a day column readable on a phone; the grid scrolls sideways instead of squeezing. */
+    protected readonly minWidth: _angular_core.Signal<number>;
+    private readonly intl;
+    protected readonly weekdayNames: _angular_core.Signal<string[]>;
+    protected readonly title: _angular_core.Signal<string>;
+    protected readonly viewOptions: _angular_core.Signal<SdsSegmentedOption<unknown>[]>;
+    protected readonly hasAllDay: _angular_core.Signal<boolean>;
+    protected readonly nowTop: _angular_core.Signal<number | null>;
+    protected placed(day: Date): PlacedEvent<T>[];
+    protected allDayEvents(day: Date): SdsCalendarEvent<T>[];
+    protected cellEvents(day: Date): SdsCalendarEvent<T>[];
+    protected isToday(day: Date): boolean;
+    protected inFocusedMonth(day: Date): boolean;
+    protected shortWeekday(day: Date): string;
+    protected hourLabel(hour: number): string;
+    protected clock(value: Date | string | number): string;
+    protected hourTop(hour: number): number;
+    protected chipClass(e: SdsCalendarEvent<T>): string;
+    protected dotClass(e: SdsCalendarEvent<T>): string;
+    protected setView(next: unknown): void;
+    protected move(direction: 1 | -1): void;
+    protected goToday(): void;
+    /** A click on empty grid becomes a slot of `defaultMinutes`, snapped to the hour clicked. */
+    protected onGridClick(event: MouseEvent, day: Date): void;
+    protected canDrag(placed: PlacedEvent<T>): boolean;
+    protected isDragging(placed: PlacedEvent<T>): boolean;
+    /** The dashed block: where this drag would land on this column, or null. */
+    protected ghostFor(dayIndex: number): {
+        top: number;
+        height: number;
+        label: string;
+    } | null;
+    protected startSelect(event: PointerEvent, dayIndex: number): void;
+    protected startMove(event: PointerEvent, placed: PlacedEvent<T>, dayIndex: number): void;
+    /**
+     * Listeners are attached for the gesture and removed on release, rather than living on the host
+     * for the component's whole life. A calendar sitting idle on a dashboard should not be handling
+     * every pointer move on the page.
+     */
+    private begin;
+    private finish;
+    private snap;
+    private minuteAt;
+    private atMinute;
+    private columnAt;
+    private columnFor;
+    /** True once, for the click that a just-finished drag is about to produce. */
+    private swallowed;
+    private hhmm;
+    protected onEventClick(event: MouseEvent, placed: PlacedEvent<T>): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<SdsEventCalendar<any>, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<SdsEventCalendar<any>, "sds-event-calendar", never, { "events": { "alias": "events"; "required": false; "isSignal": true; }; "view": { "alias": "view"; "required": false; "isSignal": true; }; "date": { "alias": "date"; "required": false; "isSignal": true; }; "firstDayOfWeek": { "alias": "firstDayOfWeek"; "required": false; "isSignal": true; }; "startHour": { "alias": "startHour"; "required": false; "isSignal": true; }; "endHour": { "alias": "endHour"; "required": false; "isSignal": true; }; "hourHeight": { "alias": "hourHeight"; "required": false; "isSignal": true; }; "defaultMinutes": { "alias": "defaultMinutes"; "required": false; "isSignal": true; }; "height": { "alias": "height"; "required": false; "isSignal": true; }; "locale": { "alias": "locale"; "required": false; "isSignal": true; }; "nowIndicator": { "alias": "nowIndicator"; "required": false; "isSignal": true; }; "showToolbar": { "alias": "showToolbar"; "required": false; "isSignal": true; }; "showViewSwitcher": { "alias": "showViewSwitcher"; "required": false; "isSignal": true; }; "maxPerCell": { "alias": "maxPerCell"; "required": false; "isSignal": true; }; "todayLabel": { "alias": "todayLabel"; "required": false; "isSignal": true; }; "previousLabel": { "alias": "previousLabel"; "required": false; "isSignal": true; }; "nextLabel": { "alias": "nextLabel"; "required": false; "isSignal": true; }; "allDayLabel": { "alias": "allDayLabel"; "required": false; "isSignal": true; }; "moreLabel": { "alias": "moreLabel"; "required": false; "isSignal": true; }; "viewSwitcherLabel": { "alias": "viewSwitcherLabel"; "required": false; "isSignal": true; }; "monthLabel": { "alias": "monthLabel"; "required": false; "isSignal": true; }; "weekLabel": { "alias": "weekLabel"; "required": false; "isSignal": true; }; "threeDayLabel": { "alias": "threeDayLabel"; "required": false; "isSignal": true; }; "dayLabel": { "alias": "dayLabel"; "required": false; "isSignal": true; }; "draggable": { "alias": "draggable"; "required": false; "isSignal": true; }; "selectable": { "alias": "selectable"; "required": false; "isSignal": true; }; "snapMinutes": { "alias": "snapMinutes"; "required": false; "isSignal": true; }; }, { "view": "viewChange"; "date": "dateChange"; "eventClick": "eventClick"; "eventDrop": "eventDrop"; "rangeSelect": "rangeSelect"; "slotClick": "slotClick"; "dayClick": "dayClick"; "rangeChange": "rangeChange"; }, never, never, true, never>;
+}
+
+export { SdsEventCalendar, allDayOn, eventsOn, minutesOfDay, occursOn, placeDay, snapMinute, startOfWeek, step, toDate, visibleDays, visibleRange };
+export type { PlacedEvent, SdsCalendarDrop, SdsCalendarEvent, SdsCalendarRange, SdsCalendarSlot, SdsEventCalendarView, SdsEventColor };