@ssa-ui-kit/core 3.26.3 → 3.27.0

package/dist/components/Calendar/types.d.ts

@@ -99,10 +99,33 @@ export type CalendarDayHighlight = {
     /** Makes the badge row clickable. */
     onClick?: () => void;
 };
+/**
+ * A day's working time on the day view's timeline, in hours from midnight —
+ * `{ start: 8, end: 20 }` is 08:00–20:00, `17.5` is 17:30. The hours
+ * outside it are shaded grey, but stay open for adding entries.
+ */
+export type CalendarWorkingHours = {
+    /** Hour the working time starts, 0–24. */
+    start: number;
+    /** Hour the working time ends, 0–24; after `start`. */
+    end: number;
+};
+/** A weekday, as keyed in {@link CalendarWorkingHoursByWeekday}. */
+export type CalendarWeekday = 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat' | 'sun';
+/**
+ * Working time per weekday. A weekday left out, or set to `null`, has no
+ * working time — the whole day is shaded.
+ */
+export type CalendarWorkingHoursByWeekday = Partial<Record<CalendarWeekday, CalendarWorkingHours | null>>;
 /**
  * Per-day options returned by `getDayProps`.
  */
 export type CalendarDayProps = {
+    /**
+     * The day's working time, over `workingHours` — e.g. a short day before a
+     * holiday. `null` shades the whole day.
+     */
+    workingHours?: CalendarWorkingHours | null;
     /** Turns the day into a highlighted, whole-day cell. */
     highlight?: CalendarDayHighlight;
     /**
@@ -189,13 +212,16 @@ export type CalendarEventDetailsControls = {
     close: () => void;
 };
 /**
- * The days a view shows, handed to `onRangeChange`.
+ * The days a view shows, handed to `onRangeChange`. Unlike the calendar's
+ * other day values, `start` and `end` are moments — the span to fetch timed
+ * entries for — so with a `timeZone` they're that zone's midnights, not
+ * local ones.
  */
 export type CalendarRange = {
     view: CalendarView;
-    /** Start of the first day shown. */
+    /** Start of the first day shown, in the calendar's time zone. */
     start: Date;
-    /** End of the last day shown (23:59:59.999). */
+    /** End of the last day shown (23:59:59.999), in the calendar's time zone. */
     end: Date;
 };
 /**
@@ -302,7 +328,9 @@ export type CalendarProps<TData = unknown> = {
     getDayProps?: (date: Date) => CalendarDayProps | undefined;
     /**
      * Shows an add button on each day (on hover in the month grid) and in the
-     * day view header. Receives the day clicked.
+     * day view header. Receives the day clicked (its start, in local time
+     * like every day value), or the hour clicked on the day view's timeline
+     * — a moment, which in another `timeZone` reads differently locally.
      */
     onAddEvent?: (date: Date) => void;
     /**
@@ -373,9 +401,69 @@ export type CalendarProps<TData = unknown> = {
     locale?: string;
     /**
      * Hour the day view scrolls to when it opens. Defaults to an hour before
-     * the current time on today, and to 8:00 on other days.
+     * the current time on today, and to the start of the working time (see
+     * `workingHours`) or 8:00 on other days.
      */
     scrollToHour?: number;
+    /**
+     * Working time of the day view: the hours outside it get a grey
+     * background. They stay open for adding entries — the shading is only a
+     * hint. One range for every day, or a range per weekday; for one-off days
+     * use `getDayProps(date).workingHours`.
+     *
+     * Unset, no hours are shaded.
+     */
+    workingHours?: CalendarWorkingHours | CalendarWorkingHoursByWeekday;
+    /**
+     * Height of one hour on the day view's timeline, in px. Passing it makes
+     * it controlled: change it from `onHourHeightChange`.
+     */
+    hourHeight?: number;
+    /**
+     * Hour height to start with when `hourHeight` isn't controlled, and the
+     * one a double click on the hour labels goes back to.
+     * @default 68
+     */
+    defaultHourHeight?: number;
+    /** Called as the user resizes the hours — see `resizableHours`. */
+    onHourHeightChange?: (hourHeight: number) => void;
+    /**
+     * Lets the user make the day view's hours taller or shorter by dragging
+     * the hour labels column up or down, or with the arrow keys when it's
+     * focused — from the whole day fitting the view to a single hour filling
+     * it. A double click on the column goes back to `defaultHourHeight`.
+     * @default false
+     */
+    resizableHours?: boolean;
+    /**
+     * IANA time zone the calendar shows times in, e.g. `'Europe/Kyiv'` or
+     * `'UTC'`. Passing it makes it controlled: change it from
+     * `onTimeZoneChange`.
+     *
+     * Timed entries are moved into the zone — an entry at 09:00 in Kyiv shows
+     * at 07:00 in `'UTC'`. Untimed entries, `date` and the other day values
+     * are calendar days and stay on their day. "Today" and the now line follow
+     * the zone.
+     *
+     * @default the browser's time zone
+     */
+    timeZone?: string;
+    /** Time zone to start in when `timeZone` isn't controlled. */
+    defaultTimeZone?: string;
+    /** Called when the user picks a time zone — see `timeZoneSelector`. */
+    onTimeZoneChange?: (timeZone: string) => void;
+    /**
+     * Shows a time zone button that opens a searchable list of zones. It sits
+     * in the toolbar next to the Month/Day toggle; without `toolbar`, in the
+     * day view's header.
+     * @default false
+     */
+    timeZoneSelector?: boolean;
+    /**
+     * Zones the selector offers.
+     * @default every zone the browser knows
+     */
+    timeZones?: string[];
     /** Accessible name of the calendar region. */
     'aria-label'?: string;
     className?: string;

package/dist/components/Calendar/utils.d.ts

@@ -1,6 +1,6 @@
 import { ReactNode } from 'react';
 import { DateTime } from 'luxon';
-import { CalendarDateInput, CalendarEvent } from './types';
+import { CalendarDateInput, CalendarEvent, CalendarWorkingHours, CalendarWorkingHoursByWeekday } from './types';
 /** Length given to a timed event that has no `end`. */
 export declare const DEFAULT_EVENT_MINUTES = 30;
 /**
@@ -8,8 +8,23 @@ export declare const DEFAULT_EVENT_MINUTES = 30;
  * otherwise fill every cell up to it.
  */
 export declare const MAX_SPAN_DAYS = 366;
-/** `Date` or ISO string → luxon, in local time. */
-export declare const toDateTime: (value: CalendarDateInput) => DateTime;
+/**
+ * `Date` or ISO string → luxon. A string without an offset is read in local
+ * time. With a `zone`, the moment is then shown in that zone.
+ */
+export declare const toDateTime: (value: CalendarDateInput, zone?: string) => DateTime;
+/**
+ * A day value (`date`, an untimed entry, an add limit): its local calendar
+ * date, as the start of that day in `zone`. Days stay on their date whatever
+ * the zone — only moments move.
+ */
+export declare const toZonedDay: (value: CalendarDateInput, zone?: string) => DateTime;
+/** The reverse of `toZonedDay`: the same calendar day, as local midnight. */
+export declare const toLocalDayDate: (day: DateTime) => Date;
+/** The current moment, in `zone` when given. */
+export declare const nowIn: (zone?: string) => DateTime<true> | DateTime<false>;
+/** The browser's IANA time zone. */
+export declare const getLocalTimeZone: () => string;
 /** `yyyy-MM-dd` of a date — the key events are grouped by. */
 export declare const toDayKey: (value: DateTime) => string;
 /**
@@ -26,7 +41,7 @@ export type NormalizedEvent<TData = unknown> = {
     /** Which of those days this copy is on, from 1. */
     dayOfSpan: number;
 };
-export declare const normalizeEvent: <TData>(event: CalendarEvent<TData>) => NormalizedEvent<TData> | undefined;
+export declare const normalizeEvent: <TData>(event: CalendarEvent<TData>, zone?: string) => NormalizedEvent<TData> | undefined;
 /**
  * Whether an entry fills a day: untimed, or timed and running from before
  * the day starts to after it ends. Such entries are listed above the day
@@ -38,7 +53,7 @@ export declare const isWholeDay: (item: NormalizedEvent, day: DateTime) => boole
  * spanning several days (see `NormalizedEvent.spanDays`) is repeated on
  * each, with its `dayOfSpan`. Events with an unparsable `start` are dropped.
  */
-export declare const groupEventsByDay: <TData>(events: CalendarEvent<TData>[]) => Map<string, NormalizedEvent<TData>[]>;
+export declare const groupEventsByDay: <TData>(events: CalendarEvent<TData>[], zone?: string) => Map<string, NormalizedEvent<TData>[]>;
 /** A cell of the month grid. */
 export type MonthDay = {
     date: DateTime;
@@ -98,6 +113,21 @@ export type PositionedEvent<TData = unknown> = {
  * past either midnight are clipped to the day; events not on it are skipped.
  */
 export declare const layoutDayEvents: <TData>(items: NormalizedEvent<TData>[], day: DateTime) => PositionedEvent<TData>[];
+/**
+ * A day's working time: the day's own override, else its weekday's entry or
+ * the single range. `null` — none, the whole day is shaded; `undefined` —
+ * working hours aren't set, nothing is shaded.
+ */
+export declare const resolveWorkingHours: (workingHours: CalendarWorkingHours | CalendarWorkingHoursByWeekday | undefined, day: DateTime, override?: CalendarWorkingHours | null) => CalendarWorkingHours | null | undefined;
+/**
+ * The stretches of a day outside its working time, in minutes from
+ * midnight. Hours are clamped to the day; a range that ends before it
+ * starts leaves the whole day outside.
+ */
+export declare const getNonWorkingRanges: (hours: CalendarWorkingHours | null) => {
+    start: number;
+    end: number;
+}[];
 /** Applies `locale` when given; otherwise keeps luxon's default. */
 export declare const withLocale: (value: DateTime, locale?: string) => DateTime<boolean>;
 /**

package/dist/components/DataTable/DataTable.d.ts

@@ -0,0 +1,79 @@
+import { DataTableProps } from './types';
+/**
+ * DataTable - A table driven by data: give it rows and column definitions
+ * and it renders, sorts and lays out the columns itself.
+ *
+ * Use it for interactive data tables. For a static table whose markup you
+ * want to write by hand, use `Table` and its row and cell components, which
+ * this is built from.
+ *
+ * ### Sorting
+ *
+ * Mark a column `sortable` and clicking its header reports a new sort through
+ * `onSortChange`: ascending first, then toggling. By default the table only
+ * reports it, expecting the server to send the rows back sorted, and passes
+ * the column's `sortKey` along for the request. Give the column a `sortFn` to
+ * sort the rows in the browser instead.
+ *
+ * ### Column layout
+ *
+ * Widths, frozen columns, order and hidden columns live in one
+ * `DataTableColumnState`, keyed by column id. Read it from
+ * `onColumnStateChange`, store it, and pass it back through
+ * `defaultColumnState` to remember a user's layout.
+ *
+ * With `reorderableColumns` the user can move columns, by dragging the grip
+ * in the header or from the header menu. A column only moves among columns
+ * frozen to the same edge, or among the unfrozen ones.
+ *
+ * ### Nested rows
+ *
+ * `getSubRows` nests rows under rows, to any depth, with an expand button
+ * per parent; `expandedRowIds` or `defaultExpanded` say which are open.
+ *
+ * ### Selection and hidden columns
+ *
+ * `selectionMode` adds a checkbox (or radio) column; the selection is a list
+ * of row ids, reported through `onSelectionChange`. `hideableColumns` adds
+ * "Hide column" to the header menu, and `DataTableColumnPicker` brings
+ * hidden columns back.
+ *
+ * @category Components
+ * @subcategory Data Display
+ *
+ * @example
+ * ```tsx
+ * const columns: DataTableColumn<Employee>[] = [
+ *   { id: 'name', header: 'Name', cell: (row) => row.name, sortable: true },
+ *   { id: 'role', header: 'Role', cell: (row) => row.role },
+ * ];
+ *
+ * <DataTable
+ *   data={employees}
+ *   columns={columns}
+ *   sort={sort}
+ *   onSortChange={(next, sortKey) => {
+ *     setSort(next);
+ *     refetch({ sortBy: sortKey, descending: next?.direction === 'desc' });
+ *   }}
+ *   isLoading={isFetching}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Resizable, freezable columns whose layout is remembered
+ * <DataTable
+ *   data={rows}
+ *   columns={columns}
+ *   resizableColumns
+ *   freezeControls
+ *   defaultColumnState={loadLayout()}
+ *   onColumnStateChange={saveLayout}
+ * />
+ * ```
+ *
+ * @see {@link Table} - the building blocks, for hand-written tables
+ */
+declare const DataTable: <Row>(props: DataTableProps<Row>) => import("@emotion/react/jsx-runtime").JSX.Element;
+export default DataTable;

package/dist/components/DataTable/DataTableColumnPicker.d.ts

@@ -0,0 +1,66 @@
+import { ReactNode } from 'react';
+import { DataTableColumn, DataTableColumnState } from './types';
+/**
+ * Props of {@link DataTableColumnPicker}.
+ *
+ * @example
+ * ```tsx
+ * <DataTableColumnPicker
+ *   columns={columns}
+ *   columnState={columnState}
+ *   onColumnStateChange={setColumnState}
+ * />
+ * ```
+ */
+export interface DataTableColumnPickerProps<Row> {
+    /** The same columns the table gets. */
+    columns: DataTableColumn<Row>[];
+    /** The table's column state, as passed to its `columnState`. */
+    columnState?: Partial<DataTableColumnState>;
+    /** Called with the whole new column state when a column is shown or hidden. */
+    onColumnStateChange: (columnState: DataTableColumnState) => void;
+    /**
+     * Text of the button that opens the list.
+     * @default 'Columns'
+     */
+    label?: ReactNode;
+    /** Class name of the button. */
+    className?: string;
+}
+/**
+ * DataTableColumnPicker - A button that opens a checklist of a
+ * {@link DataTable}'s columns, to show or hide each one.
+ *
+ * Place it wherever the page keeps its table controls, such as next to the
+ * filters, and share a controlled `columnState` between it and the table.
+ * Columns are listed in display order. Columns with `hideable: false` stay
+ * checked and cannot be cleared, and neither can the last one shown.
+ *
+ * @category Components
+ * @subcategory Data Display
+ *
+ * @example
+ * ```tsx
+ * const [columnState, setColumnState] = useState<Partial<DataTableColumnState>>({});
+ *
+ * <DataTableColumnPicker
+ *   columns={columns}
+ *   columnState={columnState}
+ *   onColumnStateChange={setColumnState}
+ * />
+ * <DataTable
+ *   data={rows}
+ *   columns={columns}
+ *   columnState={columnState}
+ *   onColumnStateChange={setColumnState}
+ * />
+ * ```
+ *
+ * @see {@link DataTable} - `hideableColumns` adds "Hide column" to its header menu
+ *
+ * @accessibility
+ * - The list is a multi-select listbox: arrows move, Space or Enter toggles
+ * - Escape closes it and returns focus to the button
+ */
+export declare const DataTableColumnPicker: <Row>({ columns, columnState, onColumnStateChange, label, className, }: DataTableColumnPickerProps<Row>) => import("@emotion/react/jsx-runtime").JSX.Element;
+export default DataTableColumnPicker;

package/dist/components/DataTable/ExpanderCell.d.ts

@@ -0,0 +1,10 @@
+/** The empty header above the expand buttons. */
+export declare const ExpanderHeaderCell: () => import("@emotion/react/jsx-runtime").JSX.Element;
+interface ExpanderCellProps {
+    hasChildren: boolean;
+    isExpanded: boolean;
+    onToggle: () => void;
+}
+/** A row's expand/collapse button, or nothing for a row without children. */
+export declare const ExpanderCell: ({ hasChildren, isExpanded, onToggle, }: ExpanderCellProps) => import("@emotion/react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/DataTable/SelectionCell.d.ts

@@ -0,0 +1,25 @@
+import { DataTableSelectionMode } from './types';
+interface SelectionHeaderCellProps {
+    mode: Exclude<DataTableSelectionMode, 'none'>;
+    checked: boolean;
+    indeterminate: boolean;
+    disabled: boolean;
+    onToggle: () => void;
+}
+/** The header of the selection column: select-all, or a label for radios. */
+export declare const SelectionHeaderCell: ({ mode, checked, indeterminate, disabled, onToggle, }: SelectionHeaderCellProps) => import("@emotion/react/jsx-runtime").JSX.Element;
+interface SelectionCellProps {
+    mode: Exclude<DataTableSelectionMode, 'none'>;
+    /** Groups the radios of one table. */
+    name: string;
+    rowId: string;
+    label: string;
+    checked: boolean;
+    /** Some of the rows below are selected, not all. */
+    indeterminate?: boolean;
+    disabled: boolean;
+    onChange: (checked: boolean) => void;
+}
+/** A row's checkbox or radio. */
+export declare const SelectionCell: ({ mode, name, rowId, label, checked, indeterminate, disabled, onChange, }: SelectionCellProps) => import("@emotion/react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/DataTable/index.d.ts

@@ -0,0 +1,4 @@
+export { default } from './DataTable';
+export { DataTableColumnPicker } from './DataTableColumnPicker';
+export type { DataTableColumnPickerProps } from './DataTableColumnPicker';
+export * from './types';

package/dist/components/DataTable/styles.d.ts

@@ -0,0 +1,47 @@
+import { Theme } from '@emotion/react';
+export declare const root: import("@emotion/react").SerializedStyles;
+/** A header button that looks like the header text it wraps. */
+export declare const sortButton: (theme: Theme) => import("@emotion/react").SerializedStyles;
+export declare const headerLabel: import("@emotion/react").SerializedStyles;
+/** Rows stay readable but plainly stale while a re-fetch is in flight. */
+export declare const busyBody: import("@emotion/react").SerializedStyles;
+export declare const clickableRow: (theme: Theme) => import("@emotion/react").SerializedStyles;
+export declare const stateCell: (theme: Theme) => import("@emotion/react").SerializedStyles;
+/**
+ * Every header cell. Relative so the grip, the menu and the drop line have
+ * something to sit against; a frozen header keeps its sticky position, whose
+ * rule in TableBase is the more specific one.
+ */
+export declare const header: (theme: Theme) => import("@emotion/react").SerializedStyles;
+/** Room on the right for the menu, so long header text never runs under it. */
+export declare const headerWithMenu: import("@emotion/react").SerializedStyles;
+/**
+ * Pinned to the right edge of the header, clear of the resize handle, so it
+ * lines up from column to column whatever the header text.
+ */
+export declare const headerMenu: import("@emotion/react").SerializedStyles;
+/**
+ * Sits in the cell's left padding, so showing it never moves the header
+ * text. Hidden until the header is hovered, like the column menu.
+ */
+export declare const grip: import("@emotion/react").SerializedStyles;
+/** The checkbox or radio column: narrow, its control centred. */
+export declare const selectionCell: import("@emotion/react").SerializedStyles;
+export declare const selectedRow: (theme: Theme) => import("@emotion/react").SerializedStyles;
+export declare const visuallyHidden: import("@emotion/react").SerializedStyles;
+/** The expand/collapse column. */
+export declare const expanderCell: import("@emotion/react").SerializedStyles;
+export declare const expanderButton: (theme: Theme) => import("@emotion/react").SerializedStyles;
+/**
+ * A row given a `background` by getRowProps. The colour arrives as a custom
+ * property, so every tinted row shares this one class whatever its colour.
+ * Layered over white: frozen cells must stay opaque. Hover and selection
+ * rules come later or weigh more, so they paint over it.
+ */
+export declare const tintedRow: import("@emotion/react").SerializedStyles;
+/** A row with children, as NestedTable draws its group rows. */
+export declare const parentRow: (theme: Theme) => import("@emotion/react").SerializedStyles;
+/** A tinted row with children: the row's tint over the parent grey. */
+export declare const tintedParentRow: (theme: Theme) => import("@emotion/react").SerializedStyles;
+/** A selected row with children: the selected tint over the parent grey. */
+export declare const selectedParentRow: (theme: Theme) => import("@emotion/react").SerializedStyles;