widenarrow-ui 2.2.0 → 2.3.0

package/lib/index.d.ts

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import react__default, { CSSProperties, MouseEvent, RefObject, ReactNode, ChangeEvent, KeyboardEvent, FocusEvent, FC } from 'react';
+import react__default, { CSSProperties, MouseEvent, RefObject, ReactNode, ChangeEvent, KeyboardEvent, FocusEvent, FC, AriaAttributes } from 'react';
 import { Placement, PositioningStrategy } from '@popperjs/core';
 
 declare enum IconTypes {
@@ -280,6 +280,15 @@ declare enum HierarchyTypes {
     TERTIARY = "tertiary",
     QUATERNARY = "quaternary"
 }
+declare enum LinkTypes {
+    PRIMARY = "colorPrimary",
+    SECONDARY = "colorSecondary",
+    WHITE = "colorWhite"
+}
+declare enum TableTypes {
+    RULED = "ruled",
+    CARDS = "cards"
+}
 declare enum AspectRatioTypes {
     ar4_1 = "ar4_1",// 25 %
     ar3_1 = "ar3_1",// 33 %
@@ -502,13 +511,19 @@ interface ButtonProps {
     /** @default false */
     autoFocus?: boolean;
     ariaLabel?: string;
+    /** ARIA role for the rendered button, when it stands for something other than a plain button. */
+    role?: string;
+    /** Selected state, for roles that carry one such as 'tab'. */
+    ariaSelected?: boolean;
+    /** Id of the element this button controls, for roles such as 'tab' that own a panel. */
+    ariaControls?: string;
     children?: ReactNode;
     toolTip?: string;
     toolTipComponent?: ReactNode;
     tabIndex?: number;
 }
 
-declare const Button: react.MemoExoticComponent<({ className, id, style, type, size, sizeMd, sizeLg, sizeXl, text, toolTip, toolTipComponent, icon, buttonRef, iconSize, iconColor, leftIcon, rightIcon, withIconRight, rotateIconByDegree, withEllipsis, onClickCallback, loading, disabled, children, autoFocus, ariaLabel, tabIndex }: ButtonProps) => JSX.Element>;
+declare const Button: react.MemoExoticComponent<({ className, id, style, type, size, sizeMd, sizeLg, sizeXl, text, toolTip, toolTipComponent, icon, buttonRef, iconSize, iconColor, leftIcon, rightIcon, withIconRight, rotateIconByDegree, withEllipsis, onClickCallback, loading, disabled, children, autoFocus, ariaLabel, role, ariaSelected, ariaControls, tabIndex }: ButtonProps) => JSX.Element>;
 
 interface CheckboxProps {
     label: string;
@@ -1059,6 +1074,51 @@ interface InlineButtonProps {
 
 declare const InlineButton: react.MemoExoticComponent<({ className, id, loading, ariaLabel, text, buttonRef, style, size, sizeMd, sizeLg, sizeXl, type, textClassName, children, icon, withIconRight, withoutHoverEffect, withPrimaryHoverEffect, withSecondaryHoverEffect, withTertiaryHoverEffect, iconSize, autoFocus, iconClassName, tabIndex, rotateIcon, rotateIconByDegree, onClickCallback, withEllipsis, disabled, toolTip, toolTipComponent }: InlineButtonProps) => JSX.Element>;
 
+interface LinkProps {
+    href?: string;
+    /** Renders a react-router Link instead of an anchor. Requires a surrounding Router. */
+    to?: string;
+    text?: string;
+    icon?: Partial<IconTypes>;
+    /** @default ColorTypes.CURRENT */
+    iconColor?: Partial<ColorTypes>;
+    /** @default '_blank' */
+    target?: '_blank' | '_self';
+    children?: ReactNode;
+    onClickCallback?: (event: MouseEvent<HTMLAnchorElement>) => void;
+    /** The link leads to a site outside the domain */
+    external?: boolean;
+    /** @default LinkTypes.SECONDARY */
+    color?: LinkTypes.SECONDARY | LinkTypes.PRIMARY | LinkTypes.WHITE;
+    /** @default '600' */
+    fontWeight?: '300' | '400' | '600' | '700';
+    /** @default 'm' */
+    fontSize?: 's' | 'm' | 'l';
+    className?: string;
+    iconClassName?: string;
+    /** Applied to the element wrapping the link's text, for callers that need to style the label itself. */
+    textClassName?: string;
+    ariaLabel?: string;
+    /**
+     * Marks this link as the one matching the current view, e.g. 'page' for the open item in a
+     * navigation list. Set it yourself rather than relying on route matching, so callers that decide
+     * "current" their own way stay authoritative.
+     */
+    ariaCurrent?: AriaAttributes['aria-current'];
+    /** @default false */
+    disabled?: boolean;
+    /** @default true */
+    withIconRight?: boolean;
+    /** @default false */
+    displayAsButton?: boolean;
+    /** @default false */
+    withEllipsis?: boolean;
+    /** @default false */
+    withWordBreak?: boolean;
+}
+
+declare const Link: FC<LinkProps>;
+
 interface IconInterface {
     loading?: boolean;
     disabled?: boolean;
@@ -1108,6 +1168,65 @@ declare const TextAreaInput: {
     displayName: string;
 };
 
+interface ListButtonProps {
+    /** Label of the row. Fades out under a gradient when it is too long to fit. */
+    text: string;
+    /**
+     * Renders the row as a react-router link rather than a button, so that middle click and
+     * open-in-new-tab keep working. Requires a surrounding Router.
+     */
+    to?: string;
+    /** Applied to the row, for spacing and for restyling the row itself. */
+    className?: string;
+    /** Applied to the clickable area holding the icon and the label. */
+    buttonClassName?: string;
+    /**
+     * Applied to the label. A caller that gives the row its own background needs this to match the
+     * fadeout to it, since the gradient has to end in the colour behind the text.
+     */
+    labelClassName?: string;
+    iconClassName?: string;
+    icon?: Partial<IconTypes>;
+    /** Shown at the end of the row at all times, for badges, spinners or status dots. */
+    rightComponent?: ReactNode;
+    /**
+     * Shown at the end of the row on hover and on keyboard focus. Replaces `rightComponent` while
+     * visible; neither reserves space while hidden, so the label keeps the full width until then.
+     */
+    hoverComponent?: ReactNode;
+    /** Renders the row in its selected colours. */
+    selected?: boolean;
+    /** @default false */
+    disabled?: boolean;
+    /** @default SizeTypes.SMALL */
+    size?: SizeTypes.SMALL | SizeTypes.MEDIUM;
+    id?: string;
+    /** Use when `text` alone does not describe the action. */
+    ariaLabel?: string;
+    /** Button variant only. */
+    toolTip?: string;
+    /** Button variant only. */
+    tabIndex?: number;
+    /** Button variant only. @default false */
+    autoFocus?: boolean;
+    /** Button variant only. */
+    buttonRef?: RefObject<HTMLButtonElement>;
+    onClickCallback?: () => void;
+}
+
+/**
+ * A full width row that reads as a single button: an optional icon, a label that fades out rather
+ * than ellipsises when it overflows, and an end slot whose contents swap on hover.
+ *
+ * The row and the clickable area are separate elements so that `rightComponent` and `hoverComponent`
+ * can hold their own buttons without nesting them inside this one. Without `to` the clickable area
+ * is an InlineButton and its props carry through; with `to` it is a link.
+ */
+declare const ListButton: {
+    ({ text, to, className, buttonClassName, labelClassName, iconClassName, icon, rightComponent, hoverComponent, selected, disabled, size, id, ariaLabel, toolTip, tabIndex, autoFocus, buttonRef, onClickCallback }: ListButtonProps): JSX.Element;
+    displayName: string;
+};
+
 interface ListItemProps extends MarginInterface, PaddingInterface {
     id?: string;
     buttonsComponent?: ReactNode;
@@ -1263,58 +1382,78 @@ declare const SolidSpinner: {
     displayName: string;
 };
 
-interface CellInterface {
+interface SortableTableCellInterface {
+    /** Key on each `data` row whose value fills this column. Also the key handed to `onSortCallback` and matched against `sortBy`. */
     key: string;
+    /** Visible column heading. */
     title: string;
+    /** Column width, as a percentage (`'25%'`) or a fixed value (`'120px'`). Applied inline to both the header and body cells. */
     width: string;
-    icon?: Partial<IconTypes>;
+    /** Renders the heading as static text with no sort button. @default false */
     disableSort?: boolean;
+    /** Right-aligns the cell contents, and moves the sort chevron to the left of the heading. @default false */
     alignRight?: boolean;
+    /** Centres the cell contents. @default false */
     alignCenter?: boolean;
+    /** Truncates overflowing cell content with an ellipsis instead of wrapping. @default false */
     withEllipsis?: boolean;
+    /** Tooltip on the heading. Falls back to `title` when omitted. */
     toolTip?: string;
+    /** Applied to the content span inside every body cell of this column, not to the cell itself. */
     className?: string;
-    customHeaderCellComponent?: (cell: CellInterface) => ReactNode | JSX.Element;
+    /** Replaces the whole heading, including the sort button. Receives the cell config. */
+    customHeaderCellComponent?: (cell: SortableTableCellInterface) => ReactNode | JSX.Element;
+    /** Replaces the cell value. Receives the whole row, so it can read keys other than `key`. */
     customCellComponent?: (row: any) => ReactNode | JSX.Element;
 }
 interface SortableTableProps {
+    /** Applied to the outer container element. */
     id?: string;
-    cells: Array<{
-        key: string;
-        title: string;
-        width: string;
-        icon?: Partial<IconTypes>;
-        disableSort?: boolean;
-        alignRight?: boolean;
-        alignCenter?: boolean;
-        withEllipsis?: boolean;
-        toolTip?: string;
-        className?: string;
-        customHeaderCellComponent?: (cell: CellInterface) => ReactNode | JSX.Element;
-        customCellComponent?: (row: any) => ReactNode | JSX.Element;
-    }>;
+    /**
+     * Visual treatment. `RULED` separates rows with a hairline. `CARDS` gives each row a white
+     * background, rounded corners and a gap, which only reads as separate rows against a tinted
+     * page — put it on `$application-background`, not inside a white card.
+     * @default TableTypes.RULED
+     */
+    type?: TableTypes.RULED | TableTypes.CARDS;
+    /** Column configuration, in render order. */
+    cells: Array<SortableTableCellInterface>;
+    /** Row objects. Each is passed to `customCellComponent`, and indexed by `cell.key` otherwise. */
     data: Array<any>;
+    /**
+     * Active sort. Without `onSortCallback` the table sorts `data` itself and treats this as the initial
+     * state only; with `onSortCallback` the table is controlled and this must reflect the current sort.
+     * @default [{ keyName: 'name', ascending: true }]
+     */
     sortBy: Array<{
         keyName: string;
         ascending: boolean;
     }>;
+    /** Applied to the outer container element. */
     className?: string;
+    /** Applied to every body row. */
     rowClassName?: string;
+    /** Applied to the header row. */
     headerClassName?: string;
+    /** Applied to the `tbody`. */
     bodyClassName?: string;
+    /** Applied to the loading spinner. */
     spinnerClassName?: string;
+    /** Accessible table description. Visually hidden, so it is for screen readers only. */
     caption?: string;
-    /** @default false */
+    /** Replaces rows with skeleton placeholders and shows a spinner. Sorting is disabled while true. @default false */
     loading?: boolean;
-    /** @default 6 */
+    /** Number of skeleton rows to render while `loading`. @default 6 */
     skeletonRows?: number;
-    /** @default false */
+    /** Pins the header to the top of the nearest scroll container. @default false */
     withStickyHeader?: boolean;
-    /** @default false */
+    /** Defers rendering each row until it scrolls into view. For long lists. @default false */
     withIntersectionObserver?: boolean;
+    /** Minimum table width, e.g. `'900px'`. Makes the container scroll horizontally below it. */
     minWidth?: string;
+    /** Takes over sorting. When given, the table stops sorting `data` and becomes controlled by `sortBy`. */
     onSortCallback?: (keyName: string, ascending: boolean) => void;
-    pagination?: SearchResultInterface;
+    /** Shown in place of the rows when `data` is empty and `loading` is false. */
     noDataMessage?: {
         title?: string;
         icon?: Partial<IconTypes>;
@@ -1323,10 +1462,90 @@ interface SortableTableProps {
 }
 
 declare const SortableTable: {
-    ({ id, cells, data, sortBy, skeletonRows, loading, caption, className, headerClassName, rowClassName, bodyClassName, spinnerClassName, withStickyHeader, withIntersectionObserver, noDataMessage, minWidth, onSortCallback }: SortableTableProps): JSX.Element;
+    ({ id, cells, data, sortBy, skeletonRows, loading, caption, className, headerClassName, rowClassName, bodyClassName, spinnerClassName, withStickyHeader, withIntersectionObserver, noDataMessage, minWidth, onSortCallback, type }: SortableTableProps): JSX.Element;
     displayName: string;
 };
 
+interface TableAction {
+    icon: Partial<IconTypes>;
+    /** Tooltip, and the accessible name of the button. Required, because the button has no visible text. */
+    toolTip: string;
+    onClickCallback: (event: MouseEvent<HTMLButtonElement>) => void;
+    /** @default false */
+    disabled?: boolean;
+    id?: string;
+}
+interface TableActionsCellProps {
+    /** Buttons to render, in order. */
+    actions: Array<TableAction>;
+    /** Size of every button in the group. @default SizeTypes.SMALL */
+    size?: SizeTypes.SMALL | SizeTypes.MEDIUM | SizeTypes.LARGE;
+    /** Text shown before the buttons. For bulk headers, e.g. "3 selected". */
+    label?: string;
+    className?: string;
+}
+
+declare const TableActionsCell: FC<TableActionsCellProps>;
+
+interface TableSelectionCellProps {
+    /** Whether this row is selected. */
+    checked: boolean;
+    /** Fired with the next selected state. */
+    onChangeCallback: (checked: boolean) => void;
+    /** Accessible name for the checkbox, e.g. `Select ${row.name}`. Never rendered visibly. */
+    label: string;
+    /** @default false */
+    disabled?: boolean;
+    className?: string;
+}
+
+declare const TableSelectionCell: FC<TableSelectionCellProps>;
+
+interface TableSelectionHeaderCellProps {
+    /** How many rows are currently selected. Drives both the checked and indeterminate states. */
+    selectedCount: number;
+    /** How many rows are selectable in total. Usually the full result count, not just the loaded page. */
+    totalCount: number;
+    /** Fired with the next selected state: true to select every row, false to clear the selection. */
+    onChangeCallback: (selectAll: boolean) => void;
+    /** Accessible name for the checkbox. Never rendered visibly. */
+    label: string;
+    /**
+     * Bulk actions revealed once at least one row is selected. Supply already-translated tooltips.
+     * Omit to keep the header as a plain select-all checkbox.
+     */
+    actions?: Array<TableAction>;
+    /** Text beside the bulk actions, e.g. `${selectedCount} selected`. Only shown when `actions` are present. */
+    selectedLabel?: string;
+    /** @default false */
+    disabled?: boolean;
+    className?: string;
+}
+
+declare const TableSelectionHeaderCell: FC<TableSelectionHeaderCellProps>;
+
+interface TableTextCellProps {
+    /** Primary value. */
+    text: string | number;
+    /** Second line below `text`, rendered smaller and muted. For the common "name over email" cell. */
+    secondaryText?: string | number;
+    /** Colour of the primary line. Use for status values such as an inactive row. */
+    color?: Partial<ColorTypes>;
+    /** Weight of the primary line. @default '400' */
+    fontWeight?: TypographyFontWeight;
+    /**
+     * Truncates both lines with an ellipsis. A tooltip carrying the full text is added automatically,
+     * so truncated values stay readable.
+     * @default false
+     */
+    withEllipsis?: boolean;
+    /** Overrides the tooltip that `withEllipsis` derives from `text`. Set on its own to add a tooltip without truncating. */
+    toolTip?: string;
+    className?: string;
+}
+
+declare const TableTextCell: FC<TableTextCellProps>;
+
 interface SwitchButtonProps {
     checked: boolean;
     id?: string;
@@ -1359,6 +1578,115 @@ declare const SwitchButton: {
     displayName: string;
 };
 
+/**
+ * Identifies a tab within its group. Numbers and strings are both supported so a group can be driven
+ * by an index, an id or a route segment.
+ */
+type TabValue = string | number;
+interface TabProps {
+    /**
+     * Identifies the tab. Defaults to the tab's position within its TabGroup, so it only needs to be
+     * set when the group is driven by something other than an index.
+     */
+    value?: TabValue;
+    /** Label of the tab. Rendered after `children`. */
+    text?: string;
+    /** Rendered before `text`, for badges, avatars or icon lists alongside the label. */
+    children?: ReactNode;
+    className?: string;
+    id?: string;
+    /** @default false */
+    disabled?: boolean;
+    /** @default false */
+    autoFocus?: boolean;
+    /** @default SizeTypes.MEDIUM */
+    tabSize?: SizeTypes.SMALL | SizeTypes.MEDIUM | SizeTypes.LARGE;
+    /** Share the group's width equally with its siblings. Normally set by TabGroup. @default false */
+    fullWidth?: boolean;
+    /** Remove the tab's horizontal padding. Normally set by TabGroup. @default false */
+    noPadding?: boolean;
+    /**
+     * Ellipsis the label instead of wrapping it, shrinking the tab to fit rather than letting the group
+     * scroll. Normally set by TabGroup.
+     * @default false
+     */
+    truncateText?: boolean;
+    /** Normally set by TabGroup from its `value`. @default false */
+    selected?: boolean;
+    /** Render a chevron before the tab. Normally set by TabGroup's `withArrows`. @default false */
+    withArrow?: boolean;
+    /** Accessible name for the chevron rendered by `withArrow`. @default 'Arrow' */
+    arrowAriaLabel?: string;
+    /**
+     * Id of the panel this tab controls. Set it, give that panel `role="tabpanel"`, and point the
+     * panel's `aria-labelledby` back at this tab's `id`, and the two are announced as a pair.
+     */
+    ariaControls?: string;
+    /**
+     * Whether this tab is the one reachable with the Tab key. A tab list is a single stop in the tab
+     * order and the arrow keys move within it, so only one tab carries it. Set by TabGroup.
+     * @default false
+     */
+    tabbable?: boolean;
+    toolTip?: string;
+    /** Called with the tab's `value` when it is activated. Normally set by TabGroup. */
+    onChange?: (value: TabValue) => void;
+    /** Called with the tab's `value` when it is activated, after `onChange`. */
+    onClickCallback?: (value: TabValue) => void;
+}
+
+declare const Tab: {
+    ({ children, className, id, disabled, fullWidth, noPadding, truncateText, autoFocus, selected, withArrow, arrowAriaLabel, ariaControls, tabbable, text, toolTip, onChange, onClickCallback, value, tabSize }: TabProps): JSX.Element;
+    displayName: string;
+};
+
+interface TabIndicatorProps {
+    className?: string;
+    /** Renders the indicator in the disabled colour. @default false */
+    disabled?: boolean;
+    style?: CSSProperties;
+}
+interface TabGroupProps {
+    /**
+     * Value of the selected Tab, matched against each Tab's `value`. Pass `false` for no selection at
+     * all, which hides the indicator rather than animating it away.
+     */
+    value: TabValue | false;
+    /** Tab elements. Falsy entries are skipped, so tabs can be rendered conditionally. */
+    children: ReactNode;
+    /** Called with the selected Tab's `value`. Tabs may also carry their own `onClickCallback`. */
+    onChange?: (value: TabValue) => void;
+    className?: string;
+    id?: string;
+    /** Accessible name for the tab list. */
+    ariaLabel?: string;
+    /** Centre the tabs within the group. @default false */
+    centered?: boolean;
+    /** Let the tabs share the group's width equally. @default false */
+    fullWidth?: boolean;
+    /** Remove the tabs' horizontal padding. @default false */
+    noPadding?: boolean;
+    /**
+     * Ellipsis tab labels instead of wrapping them, shrinking the tabs to fit rather than letting the
+     * group scroll.
+     * @default false
+     */
+    truncateText?: boolean;
+    /** Render a chevron before every tab except the first, for wizard style navigation. @default false */
+    withArrows?: boolean;
+    /** Accessible name for the chevrons rendered by `withArrows`. @default 'Arrow' */
+    arrowAriaLabel?: string;
+    /** Applied to every Tab. @default SizeTypes.MEDIUM */
+    tabSize?: SizeTypes.SMALL | SizeTypes.MEDIUM | SizeTypes.LARGE;
+    /** Styling overrides for the underline that tracks the selected tab. */
+    tabIndicatorProps?: TabIndicatorProps;
+}
+
+declare const TabGroup: {
+    ({ children: childrenProp, className, id, ariaLabel, onChange, tabIndicatorProps, value, tabSize, noPadding, truncateText, centered, fullWidth, withArrows, arrowAriaLabel }: TabGroupProps): JSX.Element;
+    displayName: string;
+};
+
 interface OptionItem {
     text: string;
     value: string | number;
@@ -1510,4 +1838,4 @@ declare const NoDataMessage: {
     displayName: string;
 };
 
-export { AppColors, AspectRatioTypes, BorderInterface, Box, Button, Card, Checkbox, ColorStyleInterface, ColorTypes, DropDown, DropDownItem, DropDownRef, FacetButton, FlexStylingInterface, FontFamilyTypes, FormSkeleton, Grid, Heading, HierarchyInterface, HierarchyTypes, Icon, IconButton, IconStyleInterface, IconTypes, Image, InlineButton, Input, Label, ListItem, ListSkeleton, MarginInterface, MultiActionButton, NoDataMessage, PaddingInterface, Pagination, Paragraph, RadioButton, SelectInput, Separator, SizeStyleInterface, SizeTypes, SkeletonItem, SolidSpinner, SortableTable, Span, SwitchButton, TextAreaInput, ToolTip, borderClassNames, flexClassNames, marginClassNames, paddingClassNames };
+export { AppColors, AspectRatioTypes, BorderInterface, Box, Button, Card, Checkbox, ColorStyleInterface, ColorTypes, DropDown, DropDownItem, DropDownRef, FacetButton, FlexStylingInterface, FontFamilyTypes, FormSkeleton, Grid, Heading, HierarchyInterface, HierarchyTypes, Icon, IconButton, IconStyleInterface, IconTypes, Image, InlineButton, Input, Label, Link, LinkTypes, ListButton, ListButtonProps, ListItem, ListSkeleton, MarginInterface, MultiActionButton, NoDataMessage, PaddingInterface, Pagination, Paragraph, RadioButton, SelectInput, Separator, SizeStyleInterface, SizeTypes, SkeletonItem, SolidSpinner, SortableTable, SortableTableCellInterface, SortableTableProps, Span, SwitchButton, Tab, TabGroup, TabGroupProps, TabIndicatorProps, TabProps, TabValue, TableAction, TableActionsCell, TableActionsCellProps, TableSelectionCell, TableSelectionCellProps, TableSelectionHeaderCell, TableSelectionHeaderCellProps, TableTextCell, TableTextCellProps, TableTypes, TextAreaInput, ToolTip, borderClassNames, flexClassNames, marginClassNames, paddingClassNames };