@arbidocs/blocks 0.4.71 → 0.4.72

package/dist/calendar/types.d.ts

@@ -0,0 +1,605 @@
+/**
+ * Shared types for `@arbidocs/blocks/calendar`: the presentational calendar block (grid, mini month,
+ * calendar list, event editor / details, scope dialog, time-zone picker, settings form).
+ *
+ * The block is props-in / callbacks-out. `EventDraft` mirrors the backend `EventCreate` / `EventWrite`
+ * shapes (snake_case kept) so the app can send it as-is.
+ */
+import type { ReactNode } from 'react';
+export type CalendarViewKind = 'day' | 'week' | 'work_week' | 'month' | 'agenda' | 'year';
+export type CalendarLayer = 'event' | 'facts' | 'workflows' | 'tasks';
+export type OverlayLayer = Exclude<CalendarLayer, 'event'>;
+export type EventStatus = 'confirmed' | 'tentative' | 'cancelled';
+export type PartStat = 'needs_action' | 'accepted' | 'declined' | 'tentative' | 'delegated';
+export type ShowAs = 'free' | 'tentative' | 'busy' | 'oof' | 'working_elsewhere';
+export type Sensitivity = 'normal' | 'private' | 'confidential';
+export type AttendeeRole = 'required' | 'optional' | 'chair' | 'non_participant';
+export type AttendeeKind = 'individual' | 'room' | 'resource' | 'group' | 'unknown';
+export type EditScope = 'this' | 'following' | 'all';
+export interface GridEvent {
+    /** Unique per occurrence (API instance_id / overlay instance_id). */
+    instanceId: string;
+    /** evt-… (API id) or overlay id. */
+    eventId: string;
+    calendarId?: string;
+    title: string;
+    /** ISO instant. */
+    startUtc: string;
+    endUtc: string;
+    allDay: boolean;
+    /** YYYY-MM-DD for all-day (exclusive end in endDate). */
+    startDate?: string;
+    endDate?: string;
+    /** Hex colour. */
+    color: string;
+    /** Drag / resize allowed. */
+    editable: boolean;
+    layer: CalendarLayer;
+    status?: EventStatus;
+    myPartstat?: PartStat | null;
+    showAs?: ShowAs;
+    isRecurring?: boolean;
+    hasConference?: boolean;
+    location?: string | null;
+    restricted?: boolean;
+}
+export interface GridRange {
+    start: Date;
+    end: Date;
+    view: CalendarViewKind;
+    /** YYYY-MM-DD anchor. */
+    date: string;
+}
+export interface SlotSelection {
+    startUtc: string;
+    endUtc: string;
+    allDay: boolean;
+    startDate?: string;
+    endDate?: string;
+}
+export interface EventTimeChange {
+    instanceId: string;
+    eventId: string;
+    startUtc: string;
+    endUtc: string;
+    allDay: boolean;
+    startDate?: string;
+    endDate?: string;
+    revert: () => void;
+}
+export interface WorkingHoursSpec {
+    /** 0 = Monday … 6 = Sunday. */
+    day: number;
+    /** HH:MM */
+    start: string;
+    end: string;
+}
+export interface CalendarLabels {
+    today: string;
+    view: string;
+    previous: string;
+    next: string;
+    day: string;
+    week: string;
+    workWeek: string;
+    month: string;
+    agenda: string;
+    year: string;
+    allDay: string;
+    busy: string;
+    noTitle: string;
+    noEvents: string;
+    weekAbbrev: string;
+    more: string;
+    newEvent: string;
+    myCalendars: string;
+    sharedCalendars: string;
+    workspaceCalendars: string;
+    subscribedCalendars: string;
+    overlays: string;
+    facts: string;
+    workflows: string;
+    tasks: string;
+    createCalendar: string;
+    editCalendar: string;
+    importCalendar: string;
+    exportCalendar: string;
+    deleteCalendar: string;
+    locked: string;
+    showCalendar: string;
+    hideCalendar: string;
+    calendarColor: string;
+    title: string;
+    titlePlaceholder: string;
+    calendar: string;
+    start: string;
+    end: string;
+    startTime: string;
+    endTime: string;
+    arbiCall: string;
+    startTimeZone: string;
+    endTimeZone: string;
+    separateTimeZones: string;
+    repeat: string;
+    location: string;
+    description: string;
+    attendees: string;
+    addAttendee: string;
+    required: string;
+    optional: string;
+    showAs: string;
+    sensitivity: string;
+    categories: string;
+    addCategory: string;
+    color: string;
+    defaultColor: string;
+    reminders: string;
+    addReminder: string;
+    useDefaultReminders: string;
+    conference: string;
+    addArbiCall: string;
+    addMeetingLink: string;
+    meetingLinkPlaceholder: string;
+    removeConference: string;
+    attachments: string;
+    addAttachment: string;
+    attachmentUrlPlaceholder: string;
+    attachmentTitlePlaceholder: string;
+    status: string;
+    save: string;
+    saving: string;
+    cancel: string;
+    delete: string;
+    edit: string;
+    remove: string;
+    createTitle: string;
+    editTitle: string;
+    minutes: string;
+    hours: string;
+    days: string;
+    weeks: string;
+    beforeStart: string;
+    popup: string;
+    email: string;
+    atStart: string;
+    free: string;
+    tentative: string;
+    oof: string;
+    workingElsewhere: string;
+    normal: string;
+    private: string;
+    confidential: string;
+    confirmed: string;
+    cancelled: string;
+    join: string;
+    accept: string;
+    decline: string;
+    maybe: string;
+    going: string;
+    organizer: string;
+    needsAction: string;
+    accepted: string;
+    declined: string;
+    delegated: string;
+    recurring: string;
+    scopeEditTitle: string;
+    scopeDeleteTitle: string;
+    scopeThis: string;
+    scopeFollowing: string;
+    scopeAll: string;
+    settingsTitle: string;
+    timeZone: string;
+    secondaryTimeZone: string;
+    none: string;
+    weekStart: string;
+    workingHours: string;
+    defaultView: string;
+    defaultDuration: string;
+    defaultCalendar: string;
+    showDeclined: string;
+    showWeekNumbers: string;
+    autoAddInvitations: string;
+    autoAddAll: string;
+    autoAddKnown: string;
+    autoAddNone: string;
+    declineMessage: string;
+    searchTimeZones: string;
+    invalidRange: string;
+    titleRequired: string;
+    removeFromCalendar: string;
+    proposeNewTime: string;
+    scopeRespondTitle: string;
+    send: string;
+    focusTime: string;
+    autoDecline: string;
+    declineMessagePlaceholder: string;
+    schedulingAssistant: string;
+    findATime: string;
+    findingTimes: string;
+    noSuggestions: string;
+    everyoneFree: string;
+    unavailableCount: string;
+    unknownAvailability: string;
+    outsideWorkingHours: string;
+    rooms: string;
+    findRoom: string;
+    minCapacity: string;
+    featureFilter: string;
+    addRoom: string;
+    roomAdded: string;
+    roomFree: string;
+    roomBusy: string;
+    noRooms: string;
+    room: string;
+    you: string;
+    addCalendar: string;
+    subscribeFromUrl: string;
+    addHolidays: string;
+    importIcs: string;
+    shareCalendar: string;
+    refreshCalendar: string;
+    publishTo: string;
+    suggestions: string;
+}
+export interface CalendarGridProps {
+    events: GridEvent[];
+    view: CalendarViewKind;
+    /** YYYY-MM-DD anchor date in `timeZone`. */
+    date: string;
+    /** IANA zone every time is rendered in. */
+    timeZone: string;
+    secondaryTimeZone?: string | null;
+    /** 0 = Sunday … 6 = Saturday. */
+    weekStart: number;
+    workingHours?: WorkingHoursSpec[];
+    showWeekNumbers?: boolean;
+    nowIndicator?: boolean;
+    onRangeChange: (r: GridRange) => void;
+    onSelectSlot?: (s: SlotSelection) => void;
+    onEventClick?: (instanceId: string, eventId: string) => void;
+    onEventChange?: (c: EventTimeChange) => void;
+    onViewChange?: (v: CalendarViewKind) => void;
+    onDateChange?: (date: string) => void;
+    /** Global keyboard shortcuts (t, d/w/x/m/a/y, j/k/n/p/←/→, c). Default on. */
+    keyboardShortcuts?: boolean;
+    /** Keyboard `c`: the host opens the create editor. */
+    onCreateShortcut?: () => void;
+    height?: number | 'auto';
+    labels?: Partial<CalendarLabels>;
+    /** Hide the built-in toolbar (the host renders its own). */
+    hideToolbar?: boolean;
+    /** Extra content rendered at the end of the toolbar (e.g. a settings button). */
+    toolbarEnd?: ReactNode;
+    className?: string;
+}
+export interface CalendarListItem {
+    id: string;
+    name: string | null;
+    color: string;
+    hidden: boolean;
+    locked: boolean;
+    role: string;
+    isDefault: boolean;
+    group: 'mine' | 'shared' | 'workspace' | 'subscribed' | 'rooms';
+    canWrite: boolean;
+    /** Mirrored from a connected account: 'google' | 'microsoft' | 'caldav' | 'ics' (native: omitted). */
+    provider?: string | null;
+}
+/** Mirrors the API DateTimeSpec: `date` alone = all-day; `date_time` = wall time in `time_zone` (null = floating). */
+export interface DateTimeSpec {
+    date?: string | null;
+    date_time?: string | null;
+    time_zone?: string | null;
+}
+export interface ReminderDraft {
+    minutes_before: number;
+    action: 'display' | 'email';
+    relative_to?: 'start' | 'end';
+}
+export interface AttendeeDraft {
+    email?: string | null;
+    user_id?: string | null;
+    name?: string | null;
+    role?: AttendeeRole;
+    kind?: AttendeeKind;
+}
+export interface ConferenceDraft {
+    type: 'arbi' | 'external';
+    url: string;
+    call_id?: string | null;
+    label?: string | null;
+}
+export interface AttachmentDraft {
+    url: string;
+    title?: string | null;
+    doc_id?: string | null;
+}
+export interface EventDraft {
+    calendar_id?: string;
+    title: string;
+    description?: string | null;
+    location?: string | null;
+    start: DateTimeSpec;
+    end: DateTimeSpec;
+    recurrence?: {
+        rrule?: string | null;
+        rdates?: DateTimeSpec[];
+        exdates?: DateTimeSpec[];
+    } | null;
+    status?: EventStatus;
+    show_as?: GridEvent['showAs'];
+    sensitivity?: Sensitivity;
+    categories?: string[];
+    color?: string | null;
+    reminders?: ReminderDraft[];
+    use_default_reminders?: boolean;
+    attendees?: AttendeeDraft[];
+    conference?: ConferenceDraft | null;
+    attachments?: AttachmentDraft[];
+    url?: string | null;
+    conversation_id?: string | null;
+    /** Out of office / focus time: decline new invitations that overlap (with `decline_message`). */
+    auto_decline?: boolean;
+    decline_message?: string | null;
+}
+export interface MiniMonthProps {
+    /** YYYY-MM-DD selected date. */
+    date: string;
+    /** 0 = Sunday … 6 = Saturday. */
+    weekStart: number;
+    timeZone: string;
+    onSelect: (date: string) => void;
+    /** Inclusive YYYY-MM-DD range to highlight (e.g. the visible week). */
+    highlightRange?: {
+        start: string;
+        end: string;
+    } | null;
+    showWeekNumbers?: boolean;
+    labels?: Partial<CalendarLabels>;
+    className?: string;
+}
+export interface CalendarOverlaysState {
+    facts: boolean;
+    workflows: boolean;
+    tasks: boolean;
+}
+export interface CalendarListProps {
+    calendars: CalendarListItem[];
+    overlays: CalendarOverlaysState;
+    onToggleHidden: (id: string) => void;
+    onColorChange: (id: string, color: string) => void;
+    onToggleOverlay: (layer: OverlayLayer) => void;
+    onCreate: () => void;
+    onEdit: (id: string) => void;
+    onImport: (id: string) => void;
+    onExport: (id: string) => void;
+    onDelete: (id: string) => void;
+    /** Sharing dialog for a calendar the caller owns. */
+    onShare?: (id: string) => void;
+    /** Re-fetch a subscription / holiday calendar. */
+    onRefresh?: (id: string) => void;
+    /** "Publish to…" a connected account (own native calendars only). */
+    onPublish?: (id: string) => void;
+    /** With any of these the "+" opens an "Add calendar" menu (new / subscribe / holidays / import). */
+    onSubscribe?: () => void;
+    onAddHolidays?: () => void;
+    onImportFile?: () => void;
+    labels?: Partial<CalendarLabels>;
+    className?: string;
+}
+export interface EventEditorProps {
+    value: EventDraft;
+    onChange: (draft: EventDraft) => void;
+    onSave: () => void;
+    onCancel: () => void;
+    onDelete?: () => void;
+    calendars: CalendarListItem[];
+    mode: 'create' | 'edit';
+    canAddCall: boolean;
+    onAddCall?: () => Promise<{
+        call_id: string;
+        url: string;
+    } | null>;
+    defaultTimeZone: string;
+    /** Extra section rendered under the guests (the host's scheduling assistant / room finder). */
+    schedulingSlot?: ReactNode;
+    /** Autocomplete for the guest input (contacts / people); the host searches on `onAttendeeQueryChange`. */
+    attendeeSuggestions?: {
+        email: string;
+        name?: string | null;
+        detail?: string | null;
+    }[];
+    onAttendeeQueryChange?: (query: string) => void;
+    saving?: boolean;
+    error?: string | null;
+    labels?: Partial<CalendarLabels>;
+    /** Optional IANA zone list for the pickers (defaults to Intl.supportedValuesOf). */
+    zones?: string[];
+    className?: string;
+}
+/** Read-side event shape for EventDetails (a subset of the API CalendarEvent, snake_case kept). */
+export interface CalendarEventView {
+    id: string;
+    instance_id: string;
+    calendar_id: string;
+    title: string;
+    description?: string | null;
+    location?: string | null;
+    start: DateTimeSpec;
+    end: DateTimeSpec;
+    all_day: boolean;
+    start_utc: string;
+    end_utc: string;
+    is_recurring?: boolean;
+    status?: EventStatus;
+    show_as?: ShowAs;
+    sensitivity?: Sensitivity;
+    categories?: string[];
+    color?: string | null;
+    reminders?: ReminderDraft[];
+    organizer?: {
+        email?: string | null;
+        name?: string | null;
+        user_id?: string | null;
+    } | null;
+    attendees?: (AttendeeDraft & {
+        partstat?: PartStat;
+        is_organizer?: boolean;
+    })[];
+    my_partstat?: PartStat | null;
+    is_organizer?: boolean;
+    conference?: {
+        type: 'arbi' | 'external';
+        url?: string | null;
+        label?: string | null;
+        call_id?: string | null;
+    } | null;
+    attachments?: AttachmentDraft[];
+    url?: string | null;
+    can_edit?: boolean;
+    restricted?: boolean;
+}
+export interface EventDetailsProps {
+    event: CalendarEventView;
+    /** Zone the times are rendered in (user settings zone). */
+    timeZone: string;
+    calendarName?: string | null;
+    calendarColor?: string | null;
+    onEdit?: () => void;
+    onDelete?: () => void;
+    onRespond?: (partstat: 'accepted' | 'declined' | 'tentative') => void;
+    /** "Propose new time" for an invitation (shown next to the RSVP buttons). */
+    onProposeTime?: () => void;
+    onJoin?: () => void;
+    onClose?: () => void;
+    /** Render the Join button as enabled (the host decides the join window). */
+    canJoin?: boolean;
+    labels?: Partial<CalendarLabels>;
+    className?: string;
+}
+export interface ScopeDialogProps {
+    open: boolean;
+    action: 'edit' | 'delete' | 'respond';
+    onChoose: (scope: EditScope) => void;
+    onCancel: () => void;
+    /** Hide "this and following" (e.g. for a single exception). */
+    allowFollowing?: boolean;
+    labels?: Partial<CalendarLabels>;
+}
+export interface TimeZonePickerProps {
+    value: string | null;
+    onChange: (zone: string) => void;
+    zones?: string[];
+    /** Offer an empty "none" option (for the secondary zone). */
+    allowNone?: boolean;
+    onClear?: () => void;
+    id?: string;
+    ariaLabel?: string;
+    disabled?: boolean;
+    labels?: Partial<CalendarLabels>;
+    className?: string;
+}
+export interface CalendarWorkingHours extends WorkingHoursSpec {
+    location?: 'office' | 'home' | 'other' | null;
+}
+/** Mirrors the API CalendarSettings. */
+export interface CalendarSettingsValue {
+    time_zone: string;
+    secondary_time_zone?: string | null;
+    week_start: number;
+    working_hours: CalendarWorkingHours[];
+    default_view: CalendarViewKind;
+    default_duration_minutes: number;
+    default_calendar_id?: string | null;
+    show_declined: boolean;
+    show_week_numbers: boolean;
+    auto_add_invitations?: 'all' | 'known' | 'none';
+    decline_message?: string | null;
+    overlays?: OverlayLayer[];
+}
+export interface CalendarSettingsFormProps {
+    value: CalendarSettingsValue;
+    onChange: (value: CalendarSettingsValue) => void;
+    onSave: () => void;
+    onCancel?: () => void;
+    calendars?: CalendarListItem[];
+    zones?: string[];
+    saving?: boolean;
+    error?: string | null;
+    labels?: Partial<CalendarLabels>;
+    className?: string;
+}
+export interface BusyInterval {
+    startUtc: string;
+    endUtc: string;
+    showAs?: ShowAs;
+    title?: string | null;
+}
+export interface SchedulingRow {
+    /** Address or id the row stands for. */
+    id: string;
+    label: string;
+    /** false: the attendee's availability is not visible to the caller. */
+    known: boolean;
+    busy: BusyInterval[];
+    /** Working intervals (UTC) within the shown day; outside them is shaded. Undefined = unknown. */
+    working?: {
+        startUtc: string;
+        endUtc: string;
+    }[];
+    kind?: 'person' | 'room';
+}
+export interface TimeSuggestionView {
+    startUtc: string;
+    endUtc: string;
+    available: string[];
+    unavailable: string[];
+}
+export interface SchedulingAssistantProps {
+    /** YYYY-MM-DD day shown, in `timeZone`. */
+    date: string;
+    timeZone: string;
+    rows: SchedulingRow[];
+    /** The event's current slot (highlighted). */
+    selection?: {
+        startUtc: string;
+        endUtc: string;
+    } | null;
+    /** First and last hour shown (default 7 and 20). */
+    dayStartHour?: number;
+    dayEndHour?: number;
+    loading?: boolean;
+    suggestions?: TimeSuggestionView[] | null;
+    finding?: boolean;
+    onFindTime?: () => void;
+    onPickSuggestion?: (s: TimeSuggestionView) => void;
+    onDateChange?: (date: string) => void;
+    labels?: Partial<CalendarLabels>;
+    className?: string;
+}
+export interface RoomOption {
+    id: string;
+    name: string;
+    email: string;
+    capacity?: number | null;
+    building?: string | null;
+    floor?: string | null;
+    features?: string[];
+    /** Free for the whole event slot (null: unknown). */
+    free?: boolean | null;
+}
+export interface RoomFinderProps {
+    rooms: RoomOption[];
+    loading?: boolean;
+    minCapacity: number | null;
+    feature: string;
+    onFiltersChange: (f: {
+        minCapacity: number | null;
+        feature: string;
+    }) => void;
+    /** Emails already on the event. */
+    addedEmails: string[];
+    onAdd: (room: RoomOption) => void;
+    labels?: Partial<CalendarLabels>;
+    className?: string;
+}

package/dist/calendar/ui.d.ts

@@ -0,0 +1,16 @@
+/** Small form primitives shared by the calendar forms (native controls: work on phones, easy to test). */
+import { type ReactNode, type SelectHTMLAttributes } from 'react';
+export declare const NativeSelect: import("react").ForwardRefExoticComponent<SelectHTMLAttributes<HTMLSelectElement> & import("react").RefAttributes<HTMLSelectElement>>;
+export declare function FieldRow({ icon, label, children, className, }: {
+    icon?: ReactNode;
+    label?: ReactNode;
+    children: ReactNode;
+    className?: string;
+}): import("react").JSX.Element;
+export declare function ColorSwatches({ value, onChange, allowNone, noneLabel, testIdPrefix, }: {
+    value: string | null | undefined;
+    onChange: (color: string | null) => void;
+    allowNone?: boolean;
+    noneLabel?: string;
+    testIdPrefix?: string;
+}): import("react").JSX.Element;

package/dist/calendar/zone.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Zone math for the calendar. Every conversion between a wall time in a named IANA zone and a UTC
+ * instant goes through Temporal (the polyfill, imported as a module: nothing global is patched),
+ * so DST gaps/overlaps resolve the way RFC 5545 says (`compatible`: a skipped time moves forward,
+ * a repeated time takes the earlier instant). Nothing here reads the browser's local zone.
+ */
+import { Temporal } from 'temporal-polyfill';
+/** True when `zone` is a time zone the runtime can resolve. */
+export declare function isValidTimeZone(zone: string | null | undefined): zone is string;
+/** `zone` when valid, else `fallback` (else UTC). */
+export declare function safeZone(zone: string | null | undefined, fallback?: string): string;
+/** The instant a wall time in `zone` names, as an ISO string ending in `Z` (no milliseconds unless set). */
+export declare function wallToUtc(wall: string, zone: string): string;
+/** Epoch milliseconds of a wall time in `zone`. */
+export declare function wallToEpochMs(wall: string, zone: string): number;
+/** The zoned date-time of an instant. */
+export declare function zoned(utc: string | Date | number, zone: string): Temporal.ZonedDateTime;
+/** `YYYY-MM-DDTHH:MM` wall time of an instant in `zone`. */
+export declare function utcToWall(utc: string | Date | number, zone: string): string;
+/** `YYYY-MM-DD` date of an instant in `zone`. */
+export declare function utcToDate(utc: string | Date | number, zone: string): string;
+/** `HH:MM` of an instant in `zone`. */
+export declare function utcToTime(utc: string | Date | number, zone: string): string;
+/** Convert a wall time from one zone to the same instant's wall time in another. */
+export declare function convertWall(wall: string, fromZone: string, toZone: string): string;
+/** Today's date in `zone`. */
+export declare function todayInZone(zone: string, now?: Date | number): string;
+/** Calendar arithmetic on a `YYYY-MM-DD` date. */
+export declare function addDays(date: string, days: number): string;
+export declare function addMonths(date: string, months: number): string;
+/** Whole days from `a` to `b` (both `YYYY-MM-DD`). */
+export declare function diffDays(a: string, b: string): number;
+/** 0 = Sunday … 6 = Saturday, for a `YYYY-MM-DD` date. */
+export declare function dayOfWeekSun0(date: string): number;
+/** The first day of the week containing `date`, for a week starting on `weekStart` (0 = Sunday). */
+export declare function startOfWeek(date: string, weekStart: number): string;
+/** ISO-8601 week number of a `YYYY-MM-DD` date. */
+export declare function isoWeekNumber(date: string): number;
+/** Offset of `zone` at an instant, in minutes east of UTC. */
+export declare function zoneOffsetMinutes(zone: string, at?: string | Date | number): number;
+/** `GMT+5:30` / `GMT-4` / `GMT` label for `zone` at an instant. */
+export declare function zoneOffsetLabel(zone: string, at?: string | Date | number): string;
+/** Short city-ish label for a zone: `America/New_York` → `New York`. */
+export declare function zoneCity(zone: string): string;
+/** Every IANA zone the runtime knows (falls back to a short list on old engines). */
+export declare function listTimeZones(): string[];
+/** The viewer's zone (only as a default for a new user; rendering always uses an explicit zone). */
+export declare function detectTimeZone(): string;
+/** Format an instant in `zone` with Intl (never the browser zone). */
+export declare function formatInZone(utc: string | Date | number, zone: string, options: Intl.DateTimeFormatOptions, locale?: string): string;
+/** Format a `YYYY-MM-DD` date (zone-free: rendered at UTC noon so no zone can shift the day). */
+export declare function formatPlainDate(date: string, options: Intl.DateTimeFormatOptions, locale?: string): string;
+/** Wall-clock array FullCalendar's NamedTimeZoneImpl speaks: [y, m0, d, h, min, s, ms]. */
+export declare function epochToWallArray(ms: number, zone: string): number[];
+/** Offset (minutes east of UTC) for a wall-clock array in `zone`, resolving gaps `compatible`. */
+export declare function wallArrayOffset(a: number[], zone: string): number;