@canonical/react-components 1.3.0 → 1.3.1

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

@@ -0,0 +1,77 @@
+import type { ReactNode } from "react";
+import type { ClassName } from "../../types";
+/**
+ * The props for the Field component.
+ */
+export type Props = {
+    /**
+     * The content for caution validation.
+     */
+    caution?: ReactNode;
+    /**
+     * The content of the Field component.
+     */
+    children?: ReactNode;
+    /**
+     * Optional class(es) to pass to the Field wrapper div.
+     */
+    className?: ClassName;
+    /**
+     * The content for error validation.
+     */
+    error?: ReactNode;
+    /**
+     * The id of the input this Field component is controlling.
+     */
+    forId?: string;
+    /**
+     * Help text to show below the field.
+     */
+    help?: ReactNode;
+    /**
+     * Optional class(es) to pass to the help text element.
+     */
+    helpClassName?: string;
+    /**
+     * An id to give to the help element.
+     */
+    helpId?: string;
+    /**
+     * Whether the component is wrapping a select element.
+     */
+    isSelect?: boolean;
+    /**
+     * Whether the component is wrapping a checkbox or radio element.
+     */
+    isTickElement?: boolean;
+    /**
+     * The label for the field.
+     */
+    label?: ReactNode;
+    /**
+     * Optional class(es) to pass to the label component.
+     */
+    labelClassName?: string | null;
+    /**
+     * Whether the label should show before the input.
+     */
+    labelFirst?: boolean;
+    /**
+     * 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;
+    /**
+     * An id to give to the caution, error or success element.
+     */
+    validationId?: string;
+};
+declare const Field: ({ caution, children, className, error, forId, help, helpClassName, helpId, isSelect, isTickElement, label, labelClassName, labelFirst, required, stacked, success, validationId, ...props }: Props) => JSX.Element;
+export default Field;

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

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

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

@@ -0,0 +1,21 @@
+import type { HTMLProps, ReactNode } from "react";
+import type { ClassName, PropsWithSpread } from "../../types";
+export type Props = PropsWithSpread<{
+    /**
+     * The content of the form.
+     */
+    children?: ReactNode;
+    /**
+     * Optional class(es) to pass to the form element.
+     */
+    className?: ClassName;
+    inline?: boolean;
+    stacked?: boolean;
+}, HTMLProps<HTMLFormElement>>;
+/**
+ * This is a [React](https://reactjs.org/) component for the Vanilla [Form](https://docs.vanillaframework.io/base/forms).
+ *
+ * Form controls have global styling defined at the HTML element level. Labels and most input types are 100% width of the `<form>` parent element.
+ */
+declare const Form: ({ children, className, inline, stacked, ...props }: Props) => JSX.Element;
+export default Form;

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

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

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

@@ -0,0 +1,25 @@
+import { type ComponentProps, type ComponentType, type ElementType, type HTMLProps } from "react";
+import Input from "../Input";
+export type Props<C extends ElementType | ComponentType = typeof Input> = {
+    /**
+     * The component to display.
+     * @default Input
+     */
+    component?: C;
+    /**
+     * This can be used to hide errors returned by Formik.
+     */
+    displayError?: boolean;
+    /**
+     * The name of the field as given to Formik.
+     */
+    name: string;
+    value?: HTMLProps<HTMLElement>["value"];
+} & ComponentProps<C>;
+/**
+ * This component makes it easier to use Vanilla form inputs with Formik. It
+ * makes use of Formik's context to automatically map errors, values, states
+ * etc. onto the provided field.
+ */
+declare const FormikField: <C extends ElementType | ComponentType = ({ caution, className, error, help, helpClassName, id, label, labelClassName, required, stacked, success, takeFocus, takeFocusDelay, type, wrapperClassName, ...inputProps }: import("../Input").InputProps) => JSX.Element>({ component: Component, displayError, name, value, label, ...props }: Props<C>) => JSX.Element;
+export default FormikField;

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

@@ -0,0 +1 @@
+export { default, type Props as FormikFieldProps } from "./FormikField";

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

@@ -0,0 +1,59 @@
+import type { HTMLProps } from "react";
+import type { ClassName, PropsWithSpread, ValueOf } from "../../types";
+export declare const ICONS: {
+    readonly anchor: "anchor";
+    readonly chevronDown: "chevron-down";
+    readonly chevronUp: "chevron-up";
+    readonly close: "close";
+    readonly code: "code";
+    readonly collapse: "collapse";
+    readonly copy: "copy";
+    readonly delete: "delete";
+    readonly drag: "drag";
+    readonly error: "error";
+    readonly expand: "expand";
+    readonly externalLink: "external-link";
+    readonly help: "help";
+    readonly information: "information";
+    readonly menu: "menu";
+    readonly minus: "minus";
+    readonly plus: "plus";
+    readonly search: "search";
+    readonly share: "share";
+    readonly spinner: "spinner";
+    readonly success: "success";
+    readonly user: "user";
+    readonly warning: "warning";
+    readonly facebook: "facebook";
+    readonly twitter: "twitter";
+    readonly instagram: "instagram";
+    readonly linkedin: "linkedin";
+    readonly youtube: "youtube";
+    readonly github: "github";
+    readonly rss: "rss";
+    readonly email: "email";
+};
+export type Props = PropsWithSpread<{
+    /**
+     * Optional classes to add to the icon element.
+     */
+    className?: ClassName;
+    /**
+     * Whether to show the light variant of the icon.
+     */
+    light?: boolean;
+    /**
+     * The name of the icon.
+     */
+    name: ValueOf<typeof ICONS> | string;
+}, HTMLProps<HTMLElement>>;
+/**
+ * This is a [React](https://reactjs.org/) component for the Vanilla [Icon](https://docs.vanillaframework.io/patterns/icons/).
+ *
+ * Icons provide visual context and enhance usability.
+ *
+ * @param name One of built-in Vanilla icons or a name of a custom icon that follows `p-icon--{name}` convention.
+ * @returns Icon
+ */
+declare const Icon: ({ className, light, name, ...props }: Props) => JSX.Element;
+export default Icon;

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

@@ -0,0 +1,2 @@
+export { default, ICONS } from "./Icon";
+export type { Props as IconProps } from "./Icon";

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

@@ -0,0 +1,70 @@
+import type { InputHTMLAttributes, ReactNode } from "react";
+import type { ClassName, PropsWithSpread } from "../../types";
+/**
+ * The props for the Input component.
+ */
+export type Props = PropsWithSpread<{
+    /**
+     * The content for caution validation.
+     */
+    caution?: ReactNode;
+    /**
+     * Optional class(es) to pass to the input element.
+     */
+    className?: ClassName;
+    /**
+     * The content for error validation message. Controls the value of aria-invalid attribute.
+     */
+    error?: ReactNode;
+    /**
+     * Help text to show below the field.
+     */
+    help?: ReactNode;
+    /**
+     * Optional class(es) to pass to the help text element.
+     */
+    helpClassName?: ReactNode;
+    /**
+     * The id of the input.
+     */
+    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;
+    /**
+     * Delay takeFocus in milliseconds i.e. to let animations finish
+     */
+    takeFocusDelay?: number;
+    /**
+     * Optional class(es) to pass to the wrapping Field component
+     */
+    wrapperClassName?: string;
+}, InputHTMLAttributes<HTMLInputElement>>;
+/**
+ * This is a [React](https://reactjs.org/) component for the Vanilla [Input](https://docs.vanillaframework.io/base/forms/#input).
+ *
+ * An input field where the user can enter data, which can vary in many ways, depending on the type attribute.
+ */
+declare const Input: ({ caution, className, error, help, helpClassName, id, label, labelClassName, required, stacked, success, takeFocus, takeFocusDelay, type, wrapperClassName, ...inputProps }: Props) => JSX.Element;
+export default Input;

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

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

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

@@ -0,0 +1,25 @@
+import type { LabelHTMLAttributes, ReactNode } from "react";
+import type { ClassName, PropsWithSpread } from "../../types";
+/**
+ * The props for the Label component.
+ */
+export type Props = PropsWithSpread<{
+    /**
+     * The label content.
+     */
+    children?: ReactNode;
+    /**
+     * Optional class(es) to give to the label element.
+     */
+    className?: ClassName;
+    /**
+     * The id of the input this label is connected to.
+     */
+    forId?: string;
+    /**
+     * Whether to apply required styling to the label.
+     */
+    required?: boolean;
+}, LabelHTMLAttributes<HTMLLabelElement>>;
+declare const Label: ({ children, className, forId, required, ...props }: Props) => JSX.Element;
+export default Label;

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

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

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

@@ -0,0 +1,31 @@
+import type { HTMLProps, ReactNode } from "react";
+import type { ClassName, PropsWithSpread } from "../../types";
+export type Props = PropsWithSpread<{
+    /**
+     * The content of the link.
+     */
+    children: ReactNode;
+    /**
+     * Optional class(es) to pass to the wrapping anchor element.
+     */
+    className?: ClassName;
+    /**
+     * Whether the link should have inverted styling.
+     */
+    inverted?: boolean;
+    /**
+     * Whether the link should have soft styling.
+     */
+    soft?: boolean;
+    /**
+     * Whether the link should have "back to top" styling.
+     */
+    top?: boolean;
+}, HTMLProps<HTMLAnchorElement>>;
+/**
+ * This is a [React](https://reactjs.org/) component for the Vanilla [Link](https://docs.vanillaframework.io/patterns/links/).
+ *
+ * Links are used to embed actions or pathways to more information, allowing users to click their way from page to page.
+ */
+declare const Link: ({ children, className, href, inverted, soft, top, ...props }: Props) => JSX.Element;
+export default Link;

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

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

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

@@ -0,0 +1,36 @@
+import type { HTMLProps, ReactNode } from "react";
+import { ClassName, Headings, PropsWithSpread } from "../../types";
+export type ListItem = ReactNode | PropsWithSpread<{
+    content: ReactNode;
+}, HTMLProps<HTMLLIElement>>;
+export type SteppedListItem = PropsWithSpread<{
+    content: ReactNode;
+    title: ReactNode;
+    titleElement?: Headings;
+}, HTMLProps<HTMLLIElement>>;
+export type Props = {
+    /**
+     * Optional class(es) to pass to the wrapping element.
+     */
+    className?: ClassName;
+    /**
+     * The list's items.
+     */
+    items: ListItem[] | SteppedListItem[];
+    detailed?: boolean;
+    divided?: boolean;
+    inline?: boolean;
+    isDark?: boolean;
+    middot?: boolean;
+    split?: boolean;
+    stepped?: boolean;
+    stretch?: boolean;
+    ticked?: boolean;
+} & Omit<HTMLProps<HTMLOListElement>, "type">;
+/**
+ * This is a [React](https://reactjs.org/) component for the Vanilla [List](https://docs.vanillaframework.io/patterns/lists/).
+ *
+ * If you want to display lists in a way that is more visually distinctive than the standard `<ol>` and `<ul>`, we have 7 list styles at your disposal.
+ */
+declare const List: ({ className, detailed, divided, inline, isDark, items, middot, stretch, split, stepped, ticked, ...props }: Props) => JSX.Element;
+export default List;

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

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

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

@@ -0,0 +1,6 @@
+import type { SpinnerProps } from "../Spinner";
+/**
+ * @deprecated Loader component is deprecated. Use Spinner component instead.
+ */
+declare const Loader: (props: SpinnerProps) => JSX.Element;
+export default Loader;

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

@@ -0,0 +1 @@
+export { default } from "./Loader";

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

@@ -0,0 +1,17 @@
+import { FC, ReactNode } from "react";
+import "./LoginPageLayout.scss";
+export type Props = {
+    title: string;
+    children?: ReactNode;
+    logo?: {
+        src: string;
+        title: string;
+        url: string;
+    };
+};
+/**
+ * This is a layout component that is used to display a page with a title and children.
+ * The LoginPageLayout recommended usages are in the login flow like registration, sign up and error pages.
+ */
+declare const LoginPageLayout: FC<Props>;
+export default LoginPageLayout;

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

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

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

@@ -0,0 +1,102 @@
+import type { HTMLProps, ReactNode } from "react";
+import type { ClassName, PropsWithSpread, SortDirection } from "../../types";
+import type { TableProps } from "../Table";
+import type { TableCellProps } from "../TableCell";
+export type MainTableHeader = PropsWithSpread<{
+    /**
+     * The content of the table header.
+     */
+    content?: ReactNode;
+    /**
+     * Optional classes to apply to the table header.
+     */
+    className?: ClassName;
+    /**
+     * A key to sort the rows by. It should match a key given to the row `sortData`.
+     */
+    sortKey?: string | null;
+    /**
+     * Replacement value for data-heading if content is not a string.
+     */
+    heading?: string;
+}, HTMLProps<HTMLTableHeaderCellElement>>;
+export type MainTableCell = PropsWithSpread<{
+    /**
+     * The content of the table cell.
+     */
+    content?: ReactNode;
+}, Omit<TableCellProps, "children">>;
+export type MainTableRow = PropsWithSpread<{
+    /**
+     * Optional class(es) to apply to the row.
+     */
+    className?: ClassName;
+    /**
+     * The columns in this row.
+     */
+    columns?: MainTableCell[];
+    /**
+     * Whether this row should display as expanded.
+     */
+    expanded?: boolean;
+    /**
+     * The content to display when this column is expanded.
+     */
+    expandedContent?: ReactNode;
+    /**
+     * An optional key to identify this table row.
+     */
+    key?: number | string | null;
+    /**
+     * An object of data for use when sorting the rows. The keys of this object
+     * should match the header sort keys.
+     */
+    sortData?: Record<string, unknown>;
+}, HTMLProps<HTMLTableRowElement>>;
+export type Props = PropsWithSpread<{
+    /**
+     * The default key to sort the rows by.
+     */
+    defaultSort?: MainTableHeader["sortKey"];
+    /**
+     * The default direction the row data should be sorted by.
+     */
+    defaultSortDirection?: SortDirection;
+    /**
+     * A message to display when there are no table rows.
+     */
+    emptyStateMsg?: ReactNode;
+    /**
+     * The header columns for this table.
+     */
+    headers?: MainTableHeader[];
+    /**
+     * A function that is called when the sort key is changed.
+     */
+    onUpdateSort?: (sortKey: MainTableHeader["sortKey"]) => void;
+    /**
+     * A number of rows to paginate by.
+     */
+    paginate?: number | null;
+    /**
+     * The rows to display in the table.
+     */
+    rows?: MainTableRow[];
+    /**
+     * Whether this table should be sortable.
+     */
+    sortable?: boolean;
+    /**
+     * A function to be used when sorting.
+     */
+    sortFunction?: (a: MainTableRow, b: MainTableRow, currentSortDirection: SortDirection, currentSortKey: MainTableHeader["sortKey"]) => -1 | 0 | 1;
+    /**
+     * A hidden caption to display on the table for screen readers
+     */
+    hiddenCaption?: string | null;
+}, TableProps>;
+/**
+ * This is a [React](https://reactjs.org/) component to support many table use cases.
+ */
+declare const MainTable: ({ defaultSort, defaultSortDirection, emptyStateMsg, expanding, headers, onUpdateSort, paginate, rows, responsive, sortable, sortFunction, hiddenCaption, ...props }: Props) => JSX.Element;
+export default MainTable;

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

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

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

@@ -0,0 +1,36 @@
+import { ReactElement } from "react";
+import type { HTMLProps, ReactNode } from "react";
+import { ClassName, PropsWithSpread } from "../../types";
+export type Props = PropsWithSpread<{
+    /**
+     * Buttons to display underneath the main modal content.
+     */
+    buttonRow?: ReactNode | null;
+    /**
+     * Optional class(es) to apply to the wrapping element.
+     */
+    className?: ClassName;
+    /**
+     * The content of the modal.
+     */
+    children: ReactNode;
+    /**
+     * Function to handle closing the modal.
+     */
+    close?: () => void | null;
+    /**
+     * The title of the modal.
+     */
+    title?: ReactNode | null;
+    /**
+     * Whether the button click event should propagate.
+     */
+    shouldPropagateClickEvent?: boolean;
+}, HTMLProps<HTMLDivElement>>;
+/**
+ * This is a [React](https://reactjs.org/) component for the Vanilla [Modal](https://docs.vanillaframework.io/patterns/modal/).
+ *
+ * The modal component can be used to overlay an area of the screen which can contain a prompt, dialog or interaction.
+ */
+export declare const Modal: ({ buttonRow, children, className, close, title, shouldPropagateClickEvent, ...wrapperProps }: Props) => ReactElement;
+export default Modal;

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

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

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

@@ -0,0 +1,105 @@
+import { ReactNode, HTMLProps } from "react";
+import { TableCellProps, TableHeaderProps, TableRowProps } from "react-table";
+import type { Column, UseTableOptions, Cell, Row, HeaderGroup } from "react-table";
+import { PropsWithSpread } from "../../types";
+export type Props<D extends Record<string, unknown>> = PropsWithSpread<{
+    /**
+     * The columns of the table.
+     */
+    columns: Column<D>[];
+    /**
+     * The data of the table.
+     */
+    data: D[];
+    /**
+     * A message to display if data is empty.
+     */
+    emptyMsg?: string;
+    /**
+     * Optional extra row to display underneath the main table content.
+     */
+    footer?: ReactNode;
+    /**
+     * Optional argument to make the tables be sortable and use the `useSortBy` plugin.
+     */
+    sortable?: boolean;
+    /**
+     * This function is used to resolve any props needed for a particular column's header cell.
+     */
+    getHeaderProps?: (header: HeaderGroup<D>) => Partial<TableHeaderProps & HTMLProps<HTMLTableHeaderCellElement>>;
+    /**
+     * This function is used to resolve any props needed for a particular row.
+     */
+    getRowProps?: (row: Row<D>) => Partial<TableRowProps & HTMLProps<HTMLTableRowElement>>;
+    /**
+     * This function is used to resolve any props needed for a particular cell.
+     */
+    getCellProps?: (cell: Cell<D>) => Partial<TableCellProps & HTMLProps<HTMLTableCellElement>>;
+    getRowId?: UseTableOptions<D>["getRowId"];
+    /**
+     * The column that the table will be sorted by (this should match a cell selector).
+     */
+    initialSortColumn?: string;
+    /**
+     * The direction of the initial sort.
+     */
+    initialSortDirection?: "ascending" | "descending";
+    /**
+     * Whether the sort by needs to be reset after each data change.
+     */
+    autoResetSortBy?: boolean;
+}, HTMLProps<HTMLTableElement>>;
+/**
+This is a [React](https://reactjs.org/) component to support many table use cases.
+ 
+ModularTable components accepts `columns` and `data` arguments in the same format as [`useTable`](https://react-table.tanstack.com/docs/api/useTable) hook of the ReactTable library.
+
+`columns` - The core columns configuration object for the entire table. https://react-table.tanstack.com/docs/api/useTable#column-options
+`data` - The data array that you want to display on the table.
+### Important note!
+Values passed to both of these params have to me memoized (for example via{" "}
+  <code>React.useMemo</code>). Memoization ensures that our data isn't recreated
+  on every render. If we didn't use <code>React.useMemo</code>, the table would
+  think it was receiving new data on every render and attempt to recalulate a
+  lot of logic every single time.
+
+#### Custom column options
+
+In addition to standard column propeties from [`useTable`](https://react-table.tanstack.com/docs/api/useTable) `ModularTable` accepts some custom properties.
+
+##### Class names
+
+Custom `className` can be used to provide a specific CSS class name that will be added to all cells in given column.
+You can also provide `getHeaderProps`, `getRowProps` and `getCellProps` to resolve additional custom props for a specific element. More on this in [`useTable - cell properties`](https://react-table.tanstack.com/docs/api/useTable#cell-properties).
+
+```js
+getCellProps={({ value, column }) => ({
+  className: `table__cell--${column.id} ${value ===  "1 minute" ? "p-heading--5" : ""}`,
+})}
+columns = {
+  Header: "Hidden on mobile",
+  accessor: "example",
+  className: "u-hide--small"
+}
+```
+
+##### Icons
+
+To show an icon in the cells of a column `getCellIcon` function should be defined. The function takes a cell data as an argument and should return one of built in icons (from the `ICONS` const), a string with a custom icon name, or `false` if no icon should be shown.
+
+The `ICONS` const contains all [the Vanilla built in icons](https://vanillaframework.io/docs/patterns/icons) such as "plus", "minus", "success", "error", etc.
+
+Product specific icons can be used as well, assuming that the product provides the necessary CSS styling and the icon follows the Vanilla naming convention `p-icon--{name}`.
+
+```js
+columns = {
+  Header: "With icons",
+  accessor: "status",
+  getCellIcon: ({ value }) => {
+    return value === "released" ? ICONS.success : false;
+  },
+};
+```
+ */
+declare function ModularTable<D extends Record<string, unknown>>({ data, columns, emptyMsg, footer, sortable, getHeaderProps, getRowProps, getCellProps, getRowId, initialSortColumn, initialSortDirection, autoResetSortBy, ...props }: Props<D>): JSX.Element;
+export default ModularTable;

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

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