@canonical/react-components 1.3.0 → 1.3.2

package/dist/components/StatusLabel/StatusLabel.d.ts

@@ -0,0 +1,33 @@
+import type { HTMLProps, ReactNode } from "react";
+import { ClassName, PropsWithSpread, ValueOf } from "../../types";
+export declare const StatusLabelAppearance: {
+    readonly CAUTION: "caution";
+    readonly DEFAULT: "";
+    readonly INFORMATION: "information";
+    readonly NEGATIVE: "negative";
+    readonly POSITIVE: "positive";
+};
+/**
+ * The type of the StatusLabel props.
+ */
+export type Props = PropsWithSpread<{
+    /**
+     * The appearance of the label.
+     */
+    appearance?: ValueOf<typeof StatusLabelAppearance> | string;
+    /**
+     * The content of the label.
+     */
+    children?: ReactNode;
+    /**
+     * Optional class(es) to pass to the wrapping element.
+     */
+    className?: ClassName;
+}, HTMLProps<HTMLDivElement>>;
+/**
+ * This is a [React](https://reactjs.org/) component for the Vanilla [Label](https://vanillaframework.io/docs/patterns/labels).
+ *
+ * Labels are static elements which you can apply to signify status, tags or any other information you find useful.
+ */
+declare const StatusLabel: ({ appearance, children, className, ...labelProps }: Props) => JSX.Element;
+export default StatusLabel;

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

@@ -0,0 +1,2 @@
+export { default, StatusLabelAppearance } from "./StatusLabel";
+export type { Props as StatusLabelProps } from "./StatusLabel";

package/dist/components/Strip/Strip.d.ts

@@ -0,0 +1,64 @@
+import type { ElementType, HTMLProps, ReactNode } from "react";
+import type { ColSize } from "../Col/Col";
+import type { ClassName, PropsWithSpread } from "../../types";
+export type Props = PropsWithSpread<{
+    /**
+     * The content of the strip.
+     */
+    children: ReactNode;
+    /**
+     * A background images for the strip.
+     */
+    background?: string;
+    /**
+     * Whether the strip should display borders.
+     */
+    bordered?: boolean;
+    /**
+     * Optional classes for the strip.
+     */
+    className?: ClassName;
+    /**
+     * The width of the column if `includeCol` has been set.
+     */
+    colSize?: ColSize;
+    /**
+     * Whether the strip should be dark.
+     */
+    dark?: boolean;
+    /**
+     * Whether the strip should be deep.
+     */
+    deep?: boolean;
+    /**
+     * The base HTML element of the strip.
+     */
+    element?: ElementType;
+    /**
+     * Whether the strip should wrap the content in a column.
+     */
+    includeCol?: boolean;
+    /**
+     * Whether the strip should be light.
+     */
+    light?: boolean;
+    /**
+     * Optional classes to apply to the row.
+     */
+    rowClassName?: string;
+    /**
+     * Whether the strip should be shallow.
+     */
+    shallow?: boolean;
+    /**
+     * The type of the strip (e.g. "accent" or "image").
+     */
+    type?: string;
+}, HTMLProps<HTMLElement>>;
+/**
+ * This is a [React](https://reactjs.org/) component for the Vanilla [Strip](https://docs.vanillaframework.io/patterns/strip/).
+ *
+ * The strip pattern provides a full width strip container in which to wrap a row.
+ */
+declare const Strip: ({ background, bordered, children, className, colSize, dark, deep, includeCol, element: Component, light, rowClassName, shallow, type, ...props }: Props) => JSX.Element;
+export default Strip;

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

@@ -0,0 +1,2 @@
+export { default } from "./Strip";
+export type { Props as StripProps } from "./Strip";

package/dist/components/SummaryButton/SummaryButton.d.ts

@@ -0,0 +1,29 @@
+import type { MouseEventHandler } from "react";
+import type { ClassName } from "../../types";
+export type Props = {
+    /**
+     * Optional class(es) to pass to the wrapping element.
+     */
+    className?: ClassName;
+    /**
+     * Whether the summary button is loading.
+     */
+    isLoading?: boolean;
+    /**
+     * The label of the summary button.
+     */
+    label: string;
+    /**
+     * Function to handle clicking the summary button.
+     */
+    onClick: MouseEventHandler<HTMLButtonElement>;
+    /**
+     * The summary content.
+     */
+    summary?: string;
+};
+/**
+ * `SummaryButton` is a component to render a short summary with an action button. It's initial use case is a summary of table contents with action to load more items.
+ */
+declare const SummaryButton: ({ className, isLoading, summary, label, onClick, }: Props) => JSX.Element;
+export default SummaryButton;

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

@@ -0,0 +1,2 @@
+export { default } from "./SummaryButton";
+export type { Props as SummaryButtonProps } from "./SummaryButton";

package/dist/components/Switch/Switch.d.ts

@@ -0,0 +1,17 @@
+import type { HTMLProps, ReactNode } from "react";
+import type { PropsWithSpread } from "../../types";
+export type Props = PropsWithSpread<{
+    /**
+     * The label name for the switch
+     */
+    label: ReactNode;
+    /**
+     * Whether the switch is disabled or not
+     */
+    disabled?: boolean;
+}, HTMLProps<HTMLInputElement>>;
+/**
+ * This is a [React](https://reactjs.org/) component for the Vanilla [Switch](https://vanillaframework.io/docs/patterns/switch) component.
+ */
+export declare const Switch: ({ label, disabled, ...inputProps }: Props) => JSX.Element;
+export default Switch;

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

@@ -0,0 +1,2 @@
+export { default } from "./Switch";
+export type { Props as SwitchProps } from "./Switch";

package/dist/components/Table/Table.d.ts

@@ -0,0 +1,22 @@
+import { HTMLProps, ReactNode } from "react";
+import type { ClassName, PropsWithSpread } from "../../types";
+export type Props = PropsWithSpread<{
+    /**
+     * The content of the table.
+     */
+    children?: ReactNode;
+    /**
+     * Optional class(es) to pass to the wrapping table element.
+     */
+    className?: ClassName;
+    /**
+     * Whether the table can expand hidden cells.
+     */
+    expanding?: boolean;
+    /**
+     * Whether the table should show card styling on smaller screens.
+     */
+    responsive?: boolean;
+}, HTMLProps<HTMLTableElement>>;
+declare const Table: ({ children, className, expanding, responsive, ...props }: Props) => JSX.Element;
+export default Table;

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

@@ -0,0 +1,2 @@
+export { default } from "./Table";
+export type { Props as TableProps } from "./Table";

package/dist/components/TableCell/TableCell.d.ts

@@ -0,0 +1,26 @@
+import { HTMLProps, ReactNode } from "react";
+import type { ClassName, PropsWithSpread } from "../../types";
+export type Props = PropsWithSpread<{
+    /**
+     * The content of the table cell.
+     */
+    children?: ReactNode;
+    /**
+     * Optional class(es) to pass to the wrapping td element.
+     */
+    className?: ClassName;
+    /**
+     * Whether the cell is an expanded cell.
+     */
+    expanding?: boolean;
+    /**
+     * Whether content of the cell should be able to overflow, e.g. a dropdown.
+     */
+    hasOverflow?: boolean;
+    /**
+     * Whether the cell is currently hidden.
+     */
+    hidden?: boolean;
+}, HTMLProps<HTMLTableCellElement>>;
+declare const TableCell: ({ children, className, hasOverflow, expanding, hidden, role, ...props }: Props) => JSX.Element;
+export default TableCell;

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

@@ -0,0 +1,2 @@
+export { default } from "./TableCell";
+export type { Props as TableCellProps } from "./TableCell";

package/dist/components/TableHeader/TableHeader.d.ts

@@ -0,0 +1,14 @@
+import { HTMLProps, ReactNode } from "react";
+import { PropsWithSpread, SortDirection } from "../../types";
+export type Props = PropsWithSpread<{
+    /**
+     * The content of the table header.
+     */
+    children?: ReactNode;
+    /**
+     * The direction of sorting, if applicable.
+     */
+    sort?: SortDirection;
+}, HTMLProps<HTMLTableHeaderCellElement>>;
+declare const TableHeader: ({ children, sort, ...props }: Props) => JSX.Element;
+export default TableHeader;

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

@@ -0,0 +1,2 @@
+export { default } from "./TableHeader";
+export type { Props as TableHeaderProps } from "./TableHeader";

package/dist/components/TablePagination/TablePagination.d.ts

@@ -0,0 +1,98 @@
+import React, { HTMLAttributes, PropsWithChildren, ReactNode } from "react";
+import "./TablePagination.scss";
+export type BasePaginationProps = {
+    /**
+     * list of data elements to be paginated. This component is un-opinionated about
+     * the structure of the data but it should be identical to the data structure
+     * required by the child table component
+     */
+    data: unknown[];
+    /**
+     * prop name of the child table component that receives paginated data.
+     * default value is set to `rows`, which is the data prop for the `MainTable` component
+     */
+    dataForwardProp?: string;
+    /**
+     * the name of the item associated to each row within the table.
+     */
+    itemName?: string;
+    /**
+     * custom styling for the pagination container
+     */
+    className?: string;
+    /**
+     * custom description to be displayed by the pagination
+     */
+    description?: ReactNode;
+    /**
+     * custom per page limits express as an array of numbers.
+     */
+    pageLimits?: number[];
+    /**
+     * place the pagination component above or below the table?
+     */
+    position?: "above" | "below";
+};
+export type ExternalControlProps = BasePaginationProps & {
+    /**
+     * Whether the component will be controlled via external state.
+     */
+    externallyControlled?: true;
+    /**
+     * the total number of items available within the data. This prop is only relevant
+     * and will be required if `externallyControlled` is set to `true`.
+     */
+    totalItems: number;
+    /**
+     * the current page that's showing. This prop is only relevant and will be required
+     * if `externallyControlled` is set to `true`.
+     */
+    currentPage: number;
+    /**
+     * size per page. This prop is only relevant and will be required if
+     * `externallyControlled` is set to `true`.
+     */
+    pageSize: number;
+    /**
+     * callback indicating a page change event to the parent component.
+     * This prop is only relevant and will be required if `externallyControlled` is set
+     * to `true`.
+     */
+    onPageChange: (page: number) => void;
+    /**
+     * callback indicating a page size change event to the parent component.
+     * This prop is only relevant and will be required if `externallyControlled` is set
+     * to `true`.
+     */
+    onPageSizeChange: (pageSize: number) => void;
+};
+export type InternalControlProps = BasePaginationProps & {
+    /**
+     * Whether the component will be controlled via external state.
+     */
+    externallyControlled?: false;
+};
+export type Props = PropsWithChildren<ExternalControlProps | InternalControlProps> & HTMLAttributes<HTMLDivElement>;
+/**
+This is an HOC [React](https://reactjs.org/) component for applying pagination to direct children components. This component is un-opinionated about
+the structure of the input data and can be used with any child component that displays a list of data. However, the styling and behaviour of this component were designed
+to work nicely with the `MainTable` component. To use this component, simply wrap a child component with it and provide the data that you want
+to paginate to the `data` prop. This component will then pass the paged data to all <b>direct</b> child components via a child prop specified by `dataForwardProp`.
+The component may be externally controlled, see following sections for detailed explanation.
+
+#### Externally controlled pagination
+
+For externally controlled mode, you will be responsible for the pagination logic and therefore the component will be purely presentational.
+The pagination behaviour is controlled outside of this component. Note the data injection to child components is essentially a passthrough in this case.
+To enable externally controlled mode for this component, set the `externallyControlled` prop to `true`. From there, it is your responsibility
+to ensure that the following props `totalItems`, `currentPage`, `pageSize`, `onPageChange` and `onPageSizeChange` are set properly.
+You can refer to the props table below on how to set these props.
+
+#### Un-controlled pagination
+
+In this mode, the component assumes that the input data is not paginated. The component will implement the pagination logic and apply it to the input data
+then inject the paged data into direct child components. This is the default mode of operations for the component where `externallyControlled` prop is set
+to `false`.
+ */
+declare const TablePagination: (props: Props) => React.JSX.Element;
+export default TablePagination;

package/dist/components/TablePagination/TablePaginationControls/TablePaginationControls.d.ts

@@ -0,0 +1,24 @@
+import { ButtonProps } from "../../Button";
+import { HTMLAttributes } from "react";
+import { BasePaginationProps, ExternalControlProps, InternalControlProps } from "../TablePagination";
+export declare enum Label {
+    NEXT_PAGE = "Next page",
+    PREVIOUS_PAGE = "Previous page",
+    PAGE_NUMBER = "Page number"
+}
+export type AllProps = BasePaginationProps & InternalControlProps & ExternalControlProps;
+export type Props = Omit<AllProps, "currentPage" | "data" | "dataForwardProp" | "externallyControlled" | "onPageChange" | "position" | "totalItems"> & {
+    currentPage?: AllProps["currentPage"];
+    displayDescription?: boolean;
+    onInputPageChange?: (page: number) => void;
+    nextButtonProps?: Partial<ButtonProps>;
+    onNextPage?: (page: number) => void;
+    onPageChange?: AllProps["onPageChange"];
+    onPreviousPage?: (page: number) => void;
+    previousButtonProps?: Partial<ButtonProps>;
+    totalItems?: AllProps["totalItems"];
+    visibleCount?: number;
+    showPageInput?: boolean;
+} & HTMLAttributes<HTMLDivElement>;
+declare const TablePaginationControls: ({ className, currentPage, description, displayDescription, onInputPageChange, itemName, nextButtonProps, onNextPage, onPageChange, onPageSizeChange, onPreviousPage, pageLimits, pageSize, previousButtonProps, showPageInput, totalItems, visibleCount, ...divProps }: Props) => JSX.Element;
+export default TablePaginationControls;

package/dist/components/TablePagination/TablePaginationControls/index.d.ts

@@ -0,0 +1,2 @@
+export { default } from "./TablePaginationControls";
+export type { Props as TablePaginationControlsProps } from "./TablePaginationControls";

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

@@ -0,0 +1,2 @@
+export { default } from "./TablePagination";
+export type { Props as TablePaginationProps } from "./TablePagination";

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

@@ -0,0 +1,27 @@
+import { ReactElement, ReactNode } from "react";
+/**
+ * Determine if we are working with a small screen.
+ * 'small screen' in this case is relative to the width of the description div
+ */
+export declare const figureSmallScreen: () => boolean;
+/**
+ * Iterate direct react child components and override the value of the prop specified by @param dataForwardProp
+ * for those child components.
+ * @param children - react node children to iterate
+ * @param dataForwardProp - the name of the prop from the children components to override
+ * @param data - actual data to be passed to the prop specified by @param dataForwardProp
+ */
+export declare const renderChildren: (children: ReactNode, dataForwardProp: string, data: unknown[]) => ReactElement<any, string | import("react").JSXElementConstructor<any>>[];
+export declare const DEFAULT_PAGE_LIMITS: number[];
+export declare const generatePagingOptions: (pageLimits: number[]) => {
+    value: number;
+    label: string;
+}[];
+export declare const getDescription: ({ description, isSmallScreen, totalItems, itemName, visibleCount, }: {
+    description: ReactNode;
+    isSmallScreen: boolean;
+    totalItems: number;
+    itemName: string;
+    visibleCount: number;
+}) => string | number | true | ReactElement<any, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode>;
+export declare const useFigureSmallScreen: () => boolean;

package/dist/components/TableRow/TableRow.d.ts

@@ -0,0 +1,10 @@
+import type { HTMLProps, ReactNode } from "react";
+import type { PropsWithSpread } from "../../types";
+export type Props = PropsWithSpread<{
+    /**
+     * The content of the table row.
+     */
+    children: ReactNode;
+}, HTMLProps<HTMLTableRowElement>>;
+declare const TableRow: ({ children, ...trProps }: Props) => JSX.Element;
+export default TableRow;

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

@@ -0,0 +1,2 @@
+export { default } from "./TableRow";
+export type { Props as TableRowProps } from "./TableRow";

package/dist/components/Tabs/Tabs.d.ts

@@ -0,0 +1,45 @@
+import type { HTMLProps, ElementType, ReactNode, ComponentType } from "react";
+import type { ClassName } from "../../types";
+export type TabLink<P = null> = {
+    /**
+     * Whether the tab link should have active styling.
+     */
+    active?: boolean;
+    /**
+     * Optional classes applied to the link element.
+     */
+    className?: ClassName;
+    /**
+     * Optional component to be used instead of the default "a" element.
+     */
+    component?: ElementType | ComponentType<P>;
+    /**
+     * Label to be displayed inside the tab link.
+     */
+    label: ReactNode;
+    /**
+     * Optional classes applied to the "li" element.
+     */
+    listItemClassName?: string;
+} & (HTMLProps<HTMLElement> | P);
+export type Props<P = null> = {
+    /**
+     * Optional classes applied to the parent "nav" element.
+     */
+    className?: ClassName;
+    /**
+     * An array of tab link objects.
+     */
+    links: TabLink<P>[];
+    /**
+     * Optional classes applied to the "ul" element.
+     */
+    listClassName?: string;
+};
+/**
+ * This is the [React](https://reactjs.org/) component for Vanilla [Tabs](https://vanillaframework.io/docs/patterns/tabs).
+Tabs organise and allow navigation between groups of content that are related and at the same level
+of hierarchy.
+ */
+declare const Tabs: <P>({ className, links, listClassName, }: Props<P>) => JSX.Element;
+export default Tabs;

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

@@ -0,0 +1,2 @@
+export { default } from "./Tabs";
+export type { Props as TabsProps } from "./Tabs";

package/dist/components/Textarea/Textarea.d.ts

@@ -0,0 +1,70 @@
+import type { TextareaHTMLAttributes, ReactNode } from "react";
+import type { ClassName, PropsWithSpread } from "../../types";
+/**
+ * The props for the Textarea component.
+ */
+export type Props = PropsWithSpread<{
+    /**
+     * The content for caution validation.
+     */
+    caution?: ReactNode;
+    /**
+     * Optional class(es) to pass to the textarea element.
+     */
+    className?: ClassName;
+    /**
+     * The content for error validation.
+     */
+    error?: ReactNode;
+    /**
+     * Whether the textarea should grow to fit the content automatically.
+     */
+    grow?: boolean;
+    /**
+     * Help text to show below the field.
+     */
+    help?: ReactNode;
+    /**
+     * The id of the textarea.
+     */
+    id?: string;
+    /**
+     * The label for the field.
+     */
+    label?: ReactNode;
+    /**
+     * Optional class(es) to pass to the label component.
+     */
+    labelClassName?: string;
+    /**
+     * Whether the field is required.
+     */
+    required?: boolean;
+    /**
+     * Whether the form field should have a stacked appearance.
+     */
+    stacked?: boolean;
+    /**
+     * The content for success validation.
+     */
+    success?: ReactNode;
+    /**
+     * Whether to focus on the input on initial render.
+     */
+    takeFocus?: boolean;
+    /**
+     * Optional class(es) to pass to the wrapping Field component
+     */
+    wrapperClassName?: string;
+    /**
+     * Function to occur on keyboard event, 'CTRL + Enter'
+     */
+    onControlEnter?: () => void;
+}, TextareaHTMLAttributes<HTMLTextAreaElement>>;
+/**
+ * This is a [React](https://reactjs.org/) component for the Vanilla [Textarea](https://docs.vanillaframework.io/base/forms/#textarea).
+ *
+ * The Textarea component defines a multi-line text input control.
+ */
+declare const Textarea: ({ caution, className, error, grow, help, id, label, labelClassName, onKeyUp, onControlEnter, required, stacked, style, success, takeFocus, wrapperClassName, ...props }: Props) => JSX.Element;
+export default Textarea;

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

@@ -0,0 +1,2 @@
+export { default } from "./Textarea";
+export type { Props as TextareaProps } from "./Textarea";

package/dist/components/Tooltip/Tooltip.d.ts

@@ -0,0 +1,75 @@
+import type { ReactNode } from "react";
+import type { WindowFitment } from "../../hooks";
+import type { ClassName, ValueOf } from "../../types";
+export type CSSPosition = "static" | "absolute" | "fixed" | "relative" | "sticky" | "initial" | "inherit";
+export type PositionStyle = {
+    left: number;
+    pointerEvents?: string;
+    position: CSSPosition;
+    top: number;
+};
+export declare const position: {
+    readonly btmCenter: "btm-center";
+    readonly btmLeft: "btm-left";
+    readonly btmRight: "btm-right";
+    readonly left: "left";
+    readonly right: "right";
+    readonly topCenter: "top-center";
+    readonly topLeft: "top-left";
+    readonly topRight: "top-right";
+};
+export type Position = ValueOf<typeof position>;
+export type Props = {
+    /**
+     * Whether the tooltip should adjust to fit in the screen.
+     */
+    autoAdjust?: boolean;
+    /**
+     * Element on which to apply the tooltip.
+     */
+    children: ReactNode;
+    /**
+     * An optional class to apply to the wrapping element.
+     */
+    className?: ClassName;
+    /**
+     * Whether the tooltip should follow the mouse.
+     */
+    followMouse?: boolean;
+    /**
+     * Message to display when the element is hovered.
+     */
+    message?: ReactNode;
+    /**
+     * Position of the tooltip relative to the element.
+     */
+    position?: Position;
+    /**
+     * An optional class to apply to the element that wraps the children.
+     */
+    positionElementClassName?: string;
+    /**
+     * An optional class to apply to the tooltip message element.
+     */
+    tooltipClassName?: string;
+    /**
+     * The z-index value of the tooltip message element.
+     */
+    zIndex?: number;
+    /**
+     * Delay in ms after which Tooltip will appear (defaults to 350ms).
+     */
+    delay?: number;
+};
+export declare const adjustForWindow: (position: Position, fitsWindow: WindowFitment) => Position;
+/**
+ * This is the [React](https://reactjs.org/) component for Vanilla [Tooltips](https://vanillaframework.io/docs/patterns/tooltips).
+ *
+ * Tooltips are text labels that appear when the user hovers over, focuses on, or touches an element on the screen.
+ *
+ * They can be used to provide information about concepts/terms/actions that are not self-explanatory or well known.
+ *
+ * An alternative use of tooltips is to provide information on a disabled actionable element, e.g. for disabled buttons, providing information about why they are disabled.
+ */
+declare const Tooltip: ({ autoAdjust, children, className, followMouse, message, position, positionElementClassName, tooltipClassName, zIndex, delay, }: Props) => JSX.Element;
+export default Tooltip;

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

@@ -0,0 +1,2 @@
+export { default, position } from "./Tooltip";
+export type { Props as TooltipProps } from "./Tooltip";

package/dist/enums.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The Vanilla theme types.
+ */
+export declare enum Theme {
+    /**
+     * The dark Vanilla theme.
+     */
+    DARK = "dark",
+    /**
+     * The light Vanilla theme.
+     */
+    LIGHT = "light"
+}

package/dist/hooks/index.d.ts

@@ -0,0 +1,9 @@
+export { useOnClickOutside, useClickOutside } from "./useOnClickOutside";
+export { useId } from "./useId";
+export { useListener } from "./useListener";
+export { useOnEscapePressed } from "./useOnEscapePressed";
+export { usePrevious } from "./usePrevious";
+export { useThrottle } from "./useThrottle";
+export { usePagination } from "./usePagination";
+export { useWindowFitment } from "./useWindowFitment";
+export type { WindowFitment } from "./useWindowFitment";

package/dist/hooks/useId.d.ts

@@ -0,0 +1,4 @@
+/**
+ * @deprecated Code component is deprecated. Use CodeSnippet component or inline `<code>` instead.
+ */
+export declare const useId: () => string;