@vamos-ui/react 0.0.0-stage → 0.2.0

package/dist/scheduler/resource-calendar.d.ts

@@ -0,0 +1,218 @@
+/**
+ * Resource calendar: people (rooms, equipment) as rows, days or hours as columns, holding
+ * blocks (shifts, absences, bookings, allocations). Template palette, rule warnings, a working
+ * calendar with holidays, a one-code-per-cell variant for attendance sheets, and a full
+ * keyboard grid. Built on `useTimeScale` maths, `usePointerDrag` and `@tanstack/react-virtual`.
+ */
+import * as React from "react";
+import type { IsoDate, WorkCalendar } from "../locale-data/core/types.js";
+import { type ScheduleTone } from "./shared.js";
+export declare const resourceCalendarLabels: {
+    grid: string;
+    resource: string;
+    today: string;
+    previous: string;
+    next: string;
+    templates: string;
+    templatesHint: string;
+    armed: string;
+    assign: string;
+    clear: string;
+    remove: string;
+    removed: string;
+    undo: string;
+    moveHint: string;
+    moved: string;
+    empty: string;
+    noResources: string;
+    cellEmpty: string;
+    total: string;
+    headcount: string;
+    pending: string;
+    approved: string;
+    rejected: string;
+    draft: string;
+    am: string;
+    pm: string;
+    weekend: string;
+    warning: string;
+    danger: string;
+    readOnly: string;
+    cellActions: string;
+    selection: string;
+    saveFailed: string;
+    loading: string;
+};
+export type ResourceCalendarLabels = typeof resourceCalendarLabels;
+export interface Resource {
+    id: string;
+    title: string;
+    avatarUrl?: string | null;
+    /** Used by `groupBy="group"` ("Kitchen", "Front of house"). */
+    group?: string;
+    /** Second line under the name ("Chef de partie", "9 days left"). */
+    meta?: React.ReactNode;
+    /** The row can't be edited (e.g. people viewing their own row in a team plan). */
+    readOnly?: boolean;
+}
+export type ResourceBlockStatus = "pending" | "approved" | "rejected" | "draft";
+export interface ResourceBlock {
+    id: string;
+    resourceId: string;
+    /**
+     * Day unit: `YYYY-MM-DD` (whole days, `end` inclusive) or UTC ISO instants for timed shifts
+     * (shown on the start day). Hour unit: UTC ISO instants.
+     */
+    start: string;
+    end: string;
+    kind?: string;
+    label?: string;
+    /** Short code for `variant="codes"` ("M", "AL", "S"). Falls back to `label`. */
+    code?: string;
+    tone?: ScheduleTone | (string & {});
+    status?: ResourceBlockStatus;
+    halfDay?: "am" | "pm";
+    editable?: boolean;
+    note?: string;
+}
+export interface ResourceTemplate {
+    id: string;
+    label: string;
+    /** Wall-clock shift times; without them the template makes whole-day blocks. */
+    start?: string;
+    end?: string;
+    tone?: ScheduleTone | (string & {});
+    kind?: string;
+    code?: string;
+    /** Typed key that assigns it in `variant="codes"` (default: the code's first letter). */
+    shortcut?: string;
+    status?: ResourceBlockStatus;
+}
+export interface ResourceRuleViolation {
+    blockId?: string;
+    day?: IsoDate;
+    message: string;
+    severity: "warning" | "danger";
+    /** `"column"`: flags the day's header (over capacity) instead of a cell. */
+    scope?: "cell" | "column";
+}
+export interface ResourceRuleContext {
+    resource: Resource;
+    /** This resource's blocks (rejected ones excluded). */
+    blocks: ResourceBlock[];
+    /** Every visible block, for team-level rules. */
+    allBlocks: ResourceBlock[];
+    range: {
+        start: IsoDate;
+        end: IsoDate;
+    };
+    timeZone: string;
+}
+/** A warning rule. Rules never block an edit; they explain what's off. */
+export interface ResourceRule {
+    id: string;
+    /** Runs once per resource (rest hours, weekly caps). */
+    check?(ctx: ResourceRuleContext): ResourceRuleViolation[];
+    /** Runs once for the whole team (absence limits). Violations with a `day` flag that column. */
+    checkTeam?(ctx: Omit<ResourceRuleContext, "resource" | "blocks"> & {
+        resources: Resource[];
+    }): ResourceRuleViolation[];
+}
+export interface ResourceBlocksChange {
+    created?: ResourceBlock[];
+    updated?: ResourceBlock[];
+    deleted?: string[];
+}
+export interface ResourceCellRef {
+    resourceId: string;
+    day: IsoDate;
+    /** Hour unit: the slot's UTC ISO start. */
+    start?: string;
+}
+export interface ResourceCellAction {
+    id: string;
+    label: string;
+    tone?: "default" | "danger";
+}
+export interface ResourceCalendarProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "onChange"> {
+    resources: Resource[];
+    blocks: ResourceBlock[];
+    /** Visible days, inclusive `YYYY-MM-DD`. */
+    range: {
+        start: IsoDate;
+        end: IsoDate;
+    };
+    /** Shows ‹ Today › in the toolbar; you move `range`. */
+    onRangeChange?(range: {
+        start: IsoDate;
+        end: IsoDate;
+    }): void;
+    /** Columns are days, or hour slots of each day. Default `"day"`. */
+    unit?: "day" | "hour";
+    /** Hour unit: visible hours. Default 08:00–20:00. */
+    hours?: {
+        start: string;
+        end: string;
+    };
+    /** `"codes"`: one short code per cell (attendance sheets). Default `"blocks"`. */
+    variant?: "blocks" | "codes";
+    templates?: ResourceTemplate[];
+    workCalendar?: WorkCalendar;
+    rules?: ResourceRule[];
+    /** Create / update / delete. Applied optimistically; a rejected promise reverts with a toast. */
+    onBlocksChange?(change: ResourceBlocksChange): void | Promise<void>;
+    /** Extra items in the cell menu ("Request time off"). */
+    cellActions?: ResourceCellAction[];
+    onCellAction?(action: {
+        id: string;
+        cells: ResourceCellRef[];
+    }): void;
+    /** Click / Enter on a block when no template is armed. Default opens the cell menu. */
+    onBlockOpen?(block: ResourceBlock): void;
+    renderBlock?(block: ResourceBlock, state: {
+        compact: boolean;
+    }): React.ReactNode;
+    /** Content of the summary row per column. Default: number of people scheduled. `false` hides the row. */
+    summary?: ((day: IsoDate, blocks: ResourceBlock[]) => React.ReactNode) | false;
+    /** Trailing value in each row header ("38 h"). */
+    rowSummary?(resource: Resource, blocks: ResourceBlock[]): React.ReactNode;
+    groupBy?: "group" | null;
+    /** Rejected blocks are hidden unless this is set. */
+    showRejected?: boolean;
+    readOnly?: boolean;
+    loading?: boolean;
+    /** IANA zone for timed blocks. Default: `LocaleProvider` `timeZone`. */
+    timeZone?: string;
+    /** Max height of the scrolling grid (CSS length). Default `"32rem"`. */
+    height?: string | number;
+    /** Rows are virtualized from this count. Default 60. */
+    virtualizeAt?: number;
+    /** Extra toolbar content. */
+    toolbar?: React.ReactNode;
+    /** Fixed "now" (tests, screenshots). */
+    now?: Date | number;
+    labels?: Partial<ResourceCalendarLabels>;
+}
+export declare const resourceCalendarVariants: (props?: ({
+    variant?: "blocks" | "codes" | null | undefined;
+    framed?: boolean | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+/**
+ * ```tsx
+ * <ResourceCalendar
+ *   resources={staff}
+ *   blocks={shifts}
+ *   range={{ start: "2026-11-09", end: "2026-11-15" }}
+ *   templates={[{ id: "am", label: "Morning", start: "08:00", end: "16:00", tone: "chart-2" }]}
+ *   rules={[minRest(11 * 60)]}
+ *   onBlocksChange={save}
+ * />
+ * ```
+ */
+export declare const ResourceCalendar: React.ForwardRefExoticComponent<ResourceCalendarProps & React.RefAttributes<HTMLDivElement>>;
+/** Warns when two timed blocks of a person are closer than `minutes` (e.g. 11 h rest). */
+export declare function minRestRule(minutes: number, message?: (gapMin: number, locale?: string) => string): ResourceRule;
+/** Warns when a person's timed blocks in the visible range exceed `maxMinutes` (e.g. 45 h week). */
+export declare function maxHoursRule(maxMinutes: number, message?: (totalMin: number) => string): ResourceRule;
+/** Flags days on which more than `max` people have a block of one of `kinds` (e.g. 3 absent). */
+export declare function maxConcurrentRule(max: number, kinds: string[], message?: (count: number) => string): ResourceRule;