@canonical/react-components 1.3.0 → 1.3.1

package/dist-types/components/Slider/Slider.d.ts

@@ -0,0 +1,62 @@
+import type { ChangeEventHandler, HTMLProps, ReactNode } from "react";
+import type { PropsWithSpread } from "../../types";
+export declare const FILLED_COLOR = "#0066CC";
+export declare const EMPTY_COLOR = "#D9D9D9";
+export type Props = PropsWithSpread<{
+    /**
+     * Field caution message.
+     */
+    caution?: ReactNode;
+    /**
+     * Whether to disable the slider and input (if showInput is true).
+     */
+    disabled?: boolean;
+    /**
+     * Field error message.
+     */
+    error?: ReactNode;
+    /**
+     * Field help message.
+     */
+    help?: ReactNode;
+    /**
+     * Field id. Only passed to range input, not to number input.
+     */
+    id?: string;
+    /**
+     * Whether to disable only the input, but not the slider.
+     */
+    inputDisabled?: boolean;
+    /**
+     * Field label.
+     */
+    label?: ReactNode;
+    /**
+     * Maximum value of the slider.
+     */
+    max: number;
+    /**
+     * Minimum value of the slider.
+     */
+    min: number;
+    /**
+     * Change event handler.
+     */
+    onChange: ChangeEventHandler<HTMLInputElement>;
+    /**
+     * Whether the field is required for the form to submit.
+     */
+    required?: boolean;
+    /**
+     * Whether to show a number input with the numerical value next to the slider.
+     */
+    showInput?: boolean;
+}, HTMLProps<HTMLInputElement>>;
+/**
+ * This is the [React](https://reactjs.org/) component for the Vanilla [Slider](https://vanillaframework.io/docs/patterns/slider).
+ *
+ * Sliders should be used to let a user specify a numeric value between a defined
+minimum and maximum value, however the precise value is not especially important.
+ */
+export declare const Slider: ({ caution, disabled, error, help, id, inputDisabled, label, max, min, onChange, required, showInput, ...inputProps }: Props) => JSX.Element;
+export default Slider;

package/dist-types/components/Slider/index.d.ts

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

package/dist-types/components/Spinner/Spinner.d.ts

@@ -0,0 +1,29 @@
+import { HTMLProps } from "react";
+import type { ClassName } from "../../types";
+export type Props = {
+    /**
+     * Optional class(es) to pass to the wrapping span element.
+     */
+    className?: ClassName;
+    /**
+     * Whether the spinner should have a light appearance.
+     */
+    isLight?: boolean;
+    /**
+     * Text to display next to the spinner.
+     */
+    text?: string;
+    /**
+     * What the role of the spinner should be.
+     */
+    role?: string;
+    /**
+     * The politeness setting of the spinner alert.
+     */
+    ariaLive?: "assertive" | "off" | "polite";
+} & HTMLProps<HTMLSpanElement>;
+/**
+ * This is a [React](https://reactjs.org/) component for the Vanilla [Spin](https://docs.vanillaframework.io/settings/animation-settings/#spin) animation.
+ */
+declare const Spinner: ({ className, text, isLight, ariaLive, role, ...props }: Props) => JSX.Element;
+export default Spinner;

package/dist-types/components/Spinner/index.d.ts

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

package/dist-types/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-types/components/StatusLabel/index.d.ts

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

package/dist-types/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-types/components/Strip/index.d.ts

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

package/dist-types/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-types/components/SummaryButton/index.d.ts

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

package/dist-types/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-types/components/Switch/index.d.ts

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

package/dist-types/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-types/components/Table/index.d.ts

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

package/dist-types/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-types/components/TableCell/index.d.ts

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

package/dist-types/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-types/components/TableHeader/index.d.ts

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

package/dist-types/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-types/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-types/components/TablePagination/TablePaginationControls/index.d.ts

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

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

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

package/dist-types/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-types/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-types/components/TableRow/index.d.ts

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

package/dist-types/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-types/components/Tabs/index.d.ts

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

package/dist-types/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-types/components/Textarea/index.d.ts

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