@powerportalspro/react-calendar 0.0.0-stage → 12.0.0

package/dist/index.d.cts

@@ -0,0 +1,368 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { TableRecordReference, TableRecord, MultiTableViewDefinition, MultiTableSeries, MultiTableItem } from '@powerportalspro/core';
+import { MultiTableForms, ViewSort } from '@powerportalspro/react-fluent';
+import { ReactNode, CSSProperties, ReactElement } from 'react';
+import { ToolbarButtonProps } from '@fluentui/react-components';
+
+/**
+ * How the calendar lays out its appointments — by the hour over a day or a week, a month of days, or
+ * a list — named as the calendar's API names them on both stacks. A layout, not a view: a view is
+ * the saved query that decides which appointments are shown. FullCalendar calls these views.
+ */
+type CalendarLayout = 'day' | 'workWeek' | 'week' | 'month' | 'agenda';
+declare const calendarLayouts: readonly CalendarLayout[];
+
+/**
+ * How an appointment shows the time it takes, as Outlook's "Show as" does: busy as appointments are
+ * drawn, free hollow, tentative striped, out of office in purple. The values are those of
+ * `AppointmentShowAs` in C#, which the Blazor Calendar sends, and of the one `@powerportalspro/core`
+ * exports, which React code passes: this folder can't import that package.
+ */
+declare const AppointmentShowAs: {
+    readonly Busy: 0;
+    readonly Free: 1;
+    readonly Tentative: 2;
+    readonly OutOfOffice: 3;
+};
+type AppointmentShowAs = (typeof AppointmentShowAs)[keyof typeof AppointmentShowAs];
+interface CalendarAppointment$1 {
+    id: string;
+    subject: string;
+    start: Date | string;
+    end: Date | string;
+    allDay?: boolean;
+    location?: string | null;
+    /** An occurrence of a recurring series. */
+    recurring?: boolean;
+    /** False when the user may not move or resize this appointment; null or absent follows the calendar. */
+    editable?: boolean | null;
+    /** False when it can be moved but not resized: its table keeps no end it may change. */
+    durationEditable?: boolean | null;
+    /** The table of the row behind it, for a calendar that shows several. Absent for an appointment of the host's. */
+    table?: string | null;
+    /** The CSS color it is drawn in, its table's. Absent for the calendar's own. */
+    color?: string | null;
+    /** How it shows the time it takes. Busy when absent. */
+    showAs?: AppointmentShowAs | null;
+    /** Whether it was canceled: its subject is struck through. */
+    canceled?: boolean | null;
+    /**
+     * The record behind it — for one the calendar loaded, every column of the view or query — for a
+     * tooltip that shows more. A `TableRecord` in React; this folder can't import its type.
+     */
+    record?: unknown;
+}
+/** A move or resize the user made, which the host saves or refuses. */
+interface CalendarAppointmentChange {
+    id: string;
+    start: Date;
+    end: Date | null;
+    allDay: boolean;
+    /** The table of the row moved, when the calendar loaded it. */
+    table?: string | null;
+}
+
+/** A time to start a new appointment over: what selecting a range in the calendar gives. */
+interface CalendarRange {
+    start: Date;
+    end: Date;
+    allDay: boolean;
+}
+/**
+ * A `<Calendar>` as a control in its toolbar sees it: the period it shows, the record it is about,
+ * and what it can be asked to do. Read it with {@link useCalendarContext}; a `<CalendarButton>`
+ * hands it to its click. The Blazor `CalendarContext` is its twin.
+ */
+interface CalendarContextValue {
+    /** The layout shown. */
+    layout: CalendarLayout;
+    /** The first moment shown; undefined until the calendar has drawn. */
+    start: Date | undefined;
+    /** The moment after the last one shown; undefined until the calendar has drawn. */
+    end: Date | undefined;
+    /** The record the calendar is about: its `regarding`. */
+    regarding: TableRecordReference | undefined;
+    /**
+     * Whether {@link createAppointment} has something to start: an `editable` calendar whose host
+     * handles `onRangeSelect`, or that loads its own appointments for a user who may create them.
+     * False until that is known.
+     */
+    canCreateAppointments: boolean;
+    /**
+     * Starts a new appointment, as selecting a time does in an `editable` calendar: the host's to
+     * handle when it handles `onRangeSelect`; otherwise, in a calendar that loads its own
+     * appointments, a form to create one, when the user may. Without a range, the appointment starts
+     * at the next half hour when the period shown takes in today, and otherwise at 8:00 on its first
+     * day, and lasts half an hour. Does nothing unless the calendar is `editable`.
+     */
+    createAppointment: (range?: CalendarRange) => Promise<void>;
+    /** Reads the appointments of the range shown again. */
+    refresh: () => void;
+}
+/** The calendar a control in its toolbar sits in. Throws outside a `<Calendar>`'s toolbar. */
+declare function useCalendarContext(): CalendarContextValue;
+
+/**
+ * An appointment as the calendar draws it: what it shows, how it shows the time it takes, and — for
+ * one the calendar loaded — the record behind it, with every column of the view or query, for a
+ * tooltip that shows more. The Blazor `CalendarAppointment` is its twin.
+ */
+interface CalendarAppointment extends Omit<CalendarAppointment$1, 'record' | 'showAs'> {
+    /** How it shows the time it takes. Busy when absent. */
+    showAs?: AppointmentShowAs | null;
+    /** The record behind it: every column of the view or query, for one the calendar loaded. */
+    record?: TableRecord | null;
+}
+
+/** Where a {@link Calendar} opens an appointment's details and another table's form. */
+type CalendarFormLocation = 'center' | 'left' | 'right';
+interface CalendarProps {
+    /**
+     * The appointments to show, when the host has them. Without it, the calendar loads the rows of
+     * each range it shows from Dataverse — appointments, tasks and the other tables the server
+     * registered — as the view picked, {@link regarding} and the user's access allow.
+     */
+    appointments?: readonly CalendarAppointment[];
+    /**
+     * Only the rows about this record, when the calendar loads its own: through each table's
+     * regarding column, and the activities it takes part in (see {@link matchParties}).
+     */
+    regarding?: TableRecordReference;
+    /**
+     * The tables the calendar may show, by logical name: of those the server registered
+     * (`AddMultiTableSource`, or notes and activities by default) and the user may read. Every one when
+     * omitted.
+     */
+    tables?: readonly string[];
+    /**
+     * The tables shown at first when the calendar shows every table — no view of its own: the others
+     * the user may read are offered in the table menu, switched off. Defaults to appointments and tasks.
+     * With none of them to show, every table is.
+     */
+    defaultTables?: readonly string[];
+    /**
+     * Dataverse views the user can pick from, by id: each shows its own table's rows that it picks.
+     * With more than one view on offer — these, {@link multiTableViewIds} and
+     * {@link customViewDefinitions} — the toolbar has a picker. With none, the calendar shows every
+     * table (see {@link defaultTables}).
+     */
+    viewIds?: readonly string[];
+    /**
+     * Views of several tables the user can pick from: ones the server registered (`AddMultiTableView`)
+     * or kept in Dataverse (`ppp_multitableview`), by id.
+     */
+    multiTableViewIds?: readonly string[];
+    /**
+     * The view the calendar opens on, one of those offered. Without it, the first of {@link viewIds},
+     * then of {@link multiTableViewIds}, then of {@link customViewDefinitions}.
+     */
+    defaultViewId?: string;
+    /**
+     * Views defined in code, of one table or several, offered beside {@link viewIds}: each table with
+     * which of its rows show.
+     */
+    customViewDefinitions?: readonly MultiTableViewDefinition[];
+    /**
+     * Whether activities the {@link regarding} record takes part in — as a sender, recipient or
+     * attendee — show beside those about it. Unset, each table's setting, else the server's.
+     */
+    matchParties?: boolean;
+    /** How recurring appointments show. Unset, each table's setting: each occurrence on its own. */
+    series?: MultiTableSeries;
+    /**
+     * Draws a table's rows the page's own way, by logical name: the row, with the whole record read in
+     * its `record`, in place of all the calendar draws of it — its time, subject, place and repeat icon.
+     * For the rows the calendar loads, not `appointments` the host gives it. A row is drawn as its range
+     * is read, so a change to what a template shows reaches it with the next range or refresh.
+     */
+    templates?: Readonly<Record<string, (item: MultiTableItem) => ReactNode>>;
+    /**
+     * The forms a row of another table than appointments opens in, by table, in place of the default
+     * one: `{ task: { edit: TaskForm } }`.
+     */
+    forms?: Readonly<Record<string, MultiTableForms>>;
+    /**
+     * Where an appointment's details and another table's form open: a dialog in the `center` (the
+     * default), or a side panel on the `left` or the `right`.
+     */
+    formLocation?: CalendarFormLocation;
+    /** The order of the views in the picker. Defaults to `ViewSort.NameAscending`. */
+    viewSort?: ViewSort;
+    /**
+     * When `true`, the toolbar has a Filter button, which opens the view's filters to change, as a
+     * grid's does — a tab for each table shown: conditions on its columns, nested in groups, and
+     * related tables to filter by — every filter FetchXML can express, over the columns and tables the
+     * user may read. The changes last while the calendar shows the view; another view starts from its
+     * own filters. Not offered for {@link appointments} the host gives the calendar, nor for a view of
+     * several tables kept in Dataverse. Defaults to `false`: the user can take away every filter the
+     * view has, which a view meant to narrow a page's rows may not want.
+     */
+    allowFiltering?: boolean;
+    /**
+     * Lets signed-in users save the calendar as they've arranged it — the view it shows with their
+     * filter, and its layout — as views of their own, offered in the view picker beside the page's,
+     * and choose their default view and hide the views they don't use. A view saved on a calendar or a
+     * grid of appointments with no {@link savedViewsKey} is offered on both, each keeping its own
+     * layout of it. Off by default. Needs the Power Portals Pro Core solution's saved-view tables; an
+     * internal user also needs the `Power Portals Pro Saved Views` security role.
+     */
+    allowSavedViews?: boolean;
+    /**
+     * Names this calendar among the controls of appointments, so the views saved on it and the user's
+     * default and hidden views are its own: it offers the views saved on it as well as the views saved on
+     * controls with no key, and its default and hidden views are set for it alone. Without one, the
+     * calendar shares its views with every grid and calendar of appointments that has none, and its
+     * default and hidden views with every calendar that has none. Letters, digits, `-`, `_` and `.`.
+     */
+    savedViewsKey?: string;
+    /**
+     * Where a user who isn't signed in is sent to sign in, from the saved views' menu, which asks them
+     * to first; they come back to this page (`ReturnUrl`). Defaults to `/Account/Login`.
+     */
+    signInUrl?: string;
+    /**
+     * Whether the toolbar has a search box, when the calendar loads its own appointments. A search
+     * finds each table's search columns as a grid's search does. Defaults to `true`.
+     */
+    allowSearch?: boolean;
+    /**
+     * Whether the search is kept in the URL with the rest of the calendar's state. Off by default:
+     * what users search for can be sensitive, and stays in the browser's history and in referrers.
+     * Has no effect without {@link persistedStateQueryParameter}.
+     */
+    includeSearchInPersistedState?: boolean;
+    /**
+     * The layout it opens in: the hours of a `day`, a `workWeek` or a `week`, a `month` of days, or an
+     * `agenda` list. Defaults to `week`; the first of {@link layouts} when that leaves it out.
+     */
+    defaultLayout?: CalendarLayout;
+    /**
+     * The layouts the user can switch between, in the order the picker lists them. With one, the
+     * picker is hidden and the calendar stays in it: a link naming another is ignored, and a day's
+     * number no longer opens that day unless `day` is offered. Every layout when omitted.
+     */
+    layouts?: readonly CalendarLayout[];
+    /**
+     * Whether appointments can be moved, resized and created by selecting a range. A loaded row can be
+     * moved when the user may change it and its start, and it isn't closed — completed, canceled or
+     * inactive; resized when they may change its end too. The calendar saves the move, unless
+     * {@link onAppointmentChange} does.
+     */
+    editable?: boolean;
+    /**
+     * The tables an appointment's Regarding can name a record of, in the order its form's table
+     * picker lists them. Tables Regarding can't point to are ignored. Every one it can when omitted;
+     * either way, only the tables whose records the user may read and point a lookup to are offered.
+     * The Blazor Calendar's
+     * `RegardingTables` is its twin.
+     */
+    regardingTables?: readonly string[];
+    /** Height of the whole calendar, toolbar included. Defaults to `600px`. */
+    height?: CSSProperties['height'];
+    /**
+     * An appointment was clicked or activated from the keyboard. Without it, an appointment the
+     * calendar loaded opens in a dialog of its details.
+     */
+    onAppointmentClick?: (id: string) => void;
+    /**
+     * The fields the details dialog shows, in place of the calendar's own: column edits and the like,
+     * read from the appointment's record as on a record page. The calendar's own show when it is,
+     * where, what it is regarding, its status and its description, read-only.
+     */
+    appointmentDetails?: ReactNode;
+    /**
+     * What an appointment's tooltip shows, in place of its subject, when, where and whether it
+     * repeats: given the appointment, whose `record` holds every column of the view for one the
+     * calendar loaded. A tooltip isn't interactive, so it shows what this draws, not controls to use.
+     */
+    appointmentTooltip?: (appointment: CalendarAppointment) => ReactNode;
+    /** A range was selected to create an appointment in, or a New button clicked. */
+    onRangeSelect?: (range: CalendarRange) => void;
+    /**
+     * An appointment was moved or resized. Resolve false to put it back, as when the save is
+     * refused.
+     */
+    onAppointmentChange?: (change: CalendarAppointmentChange) => boolean | Promise<boolean>;
+    /** The visible range changed, by navigation or a change of layout. */
+    onRangeChange?: (range: {
+        start: Date;
+        end: Date;
+        layout: CalendarLayout;
+    }) => void;
+    /**
+     * Controls for the toolbar: `<CalendarButton>`s, such as `<NewAppointmentCalendarButton>`, or any
+     * other element. They appear in the order given, ahead of the search box, as a grid's toolbar
+     * buttons do, and read the calendar through `useCalendarContext`. The Blazor Calendar's
+     * `ToolbarItems` is its twin.
+     */
+    children?: ReactNode;
+    /**
+     * The name of a URL query parameter to keep the calendar's state in — its layout, the period it
+     * shows, the appointment view picked and (with {@link includeSearchInPersistedState}) the search —
+     * so a reload or a link opens it where it was left. Each change replaces the browser's history
+     * entry rather than adding one. What the calendar would open on anyway is left out: the layout
+     * while it is the one it opens in, the appointment view while it is the default one, and the date while
+     * the period shown takes in today, so a link to the current week keeps following today. The URL is
+     * read once, when the calendar opens; a value it can't read is ignored.
+     *
+     * The Blazor Calendar keeps the same value, so a link made on one stack opens the same calendar
+     * on the other.
+     */
+    persistedStateQueryParameter?: string;
+}
+/**
+ * An Outlook-style calendar of appointments — and of tasks and any other table it is given — laid out
+ * by day, week or month, or as an agenda.
+ */
+declare function Calendar({ appointments, regarding, tables, defaultTables, viewIds, multiTableViewIds, defaultViewId, customViewDefinitions, matchParties, series, templates, forms, formLocation, viewSort, allowFiltering, allowSavedViews, savedViewsKey, signInUrl, allowSearch, includeSearchInPersistedState, defaultLayout, layouts, editable, regardingTables, height, onAppointmentClick, appointmentDetails, appointmentTooltip, onRangeSelect, onAppointmentChange, onRangeChange, persistedStateQueryParameter, children, }: CalendarProps): react_jsx_runtime.JSX.Element;
+
+interface CalendarButtonProps {
+    /** Called when the button is clicked, with the calendar as it is then. */
+    onClick?: (calendar: CalendarContextValue) => void | Promise<void>;
+    /** The text on the button. */
+    label?: string;
+    /** An icon shown before the text, such as `<ArrowDownloadRegular />`. */
+    icon?: ReactElement;
+    /** Shown when the pointer rests on the button; also its name for a screen reader when it has no label. */
+    tooltip?: string;
+    /** How the button is drawn. `subtle` by default, as the calendar's own toolbar buttons are. */
+    appearance?: ToolbarButtonProps['appearance'];
+    /** Whether the button can't be clicked. */
+    disabled?: boolean;
+    /** A class added to the button. */
+    className?: string;
+}
+/**
+ * A button for a `<Calendar>`'s toolbar: place it among the calendar's children, and a click hands
+ * it the calendar as it is then — the period shown, the record it is about, and what it can be
+ * asked to do. The grid's `<GridButton>` is its counterpart, and the Blazor `CalendarButton` its
+ * twin.
+ *
+ * ```tsx
+ * <Calendar regarding={account} editable>
+ *   <NewAppointmentCalendarButton />
+ *   <CalendarButton label="Export" icon={<ArrowDownloadRegular />} onClick={(calendar) => exportRange(calendar.start, calendar.end)} />
+ * </Calendar>
+ * ```
+ */
+declare function CalendarButton({ onClick, label, icon, tooltip, appearance, disabled, className, }: CalendarButtonProps): react_jsx_runtime.JSX.Element;
+interface NewAppointmentCalendarButtonProps {
+    /** The text on the button. "New" by default. */
+    label?: string;
+    /** The icon shown before the text. A plus by default. */
+    icon?: ReactElement;
+    /** Shown when the pointer rests on the button. */
+    tooltip?: string;
+    /** How the button is drawn. `subtle` by default. */
+    appearance?: ToolbarButtonProps['appearance'];
+}
+/**
+ * A New button for a `<Calendar>`'s toolbar: it starts a new appointment as selecting a time does —
+ * from the next half hour when the period shown takes in today, and otherwise from 8:00 on its
+ * first day. Shown only where that starts something: in an `editable` calendar whose host handles
+ * `onRangeSelect`, or that loads its own appointments for a user who may create them. The Blazor
+ * `NewAppointmentCalendarButton` is its twin.
+ */
+declare function NewAppointmentCalendarButton({ label, icon, tooltip, appearance, }: NewAppointmentCalendarButtonProps): react_jsx_runtime.JSX.Element | null;
+
+export { AppointmentShowAs, Calendar, type CalendarAppointment, type CalendarAppointmentChange, CalendarButton, type CalendarButtonProps, type CalendarContextValue, type CalendarFormLocation, type CalendarLayout, type CalendarProps, type CalendarRange, NewAppointmentCalendarButton, type NewAppointmentCalendarButtonProps, calendarLayouts, useCalendarContext };