@canonical/react-components 1.3.0 → 1.3.2

package/dist/components/Chip/Chip.d.ts

@@ -0,0 +1,56 @@
+import type { MouseEvent, HTMLProps } from "react";
+import { ValueOf, PropsWithSpread } from "../../types";
+export declare enum Label {
+    Dismiss = "Dismiss"
+}
+export declare const ChipType: {
+    readonly CAUTION: "caution";
+    readonly INFORMATION: "information";
+    readonly NEGATIVE: "negative";
+    readonly POSITIVE: "positive";
+};
+export type Props = PropsWithSpread<{
+    /**
+     * The appearance of the chip.
+     */
+    appearance?: ValueOf<typeof ChipType>;
+    /**
+     * The lead for the chip.
+     */
+    lead?: string;
+    /**
+     * Function for handling chip div click event.
+     */
+    onClick?: (event: MouseEvent<HTMLButtonElement> | {
+        lead: string;
+        value: string;
+    }) => void;
+    /**
+     * Function for handling dismissing a chip.
+     */
+    onDismiss?: (event: MouseEvent<HTMLButtonElement>) => void;
+    /**
+     * Whether the chip is selected.
+     */
+    selected?: boolean;
+    /**
+     * A substring to emphasise if it is part of the chip's value,
+     * e.g. "sit" => poSITive
+     */
+    subString?: string;
+    /**
+     * Whether to wrap the value in quotation marks.
+     */
+    quoteValue?: boolean;
+    /**
+     * The value of the chip.
+     */
+    value: string;
+}, HTMLProps<HTMLButtonElement>>;
+/**
+ * This is a [React](https://reactjs.org/) component for the Vanilla [Chip](https://vanillaframework.io/docs/patterns/chip).
+ *
+ * It can be used to display a small value attached to a component.
+ */
+declare const Chip: ({ appearance, lead, onClick, onDismiss, quoteValue, selected, subString, value, ...props }: Props) => JSX.Element;
+export default Chip;

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

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

package/dist/components/Code/Code.d.ts

@@ -0,0 +1,13 @@
+import type { ClassName } from "../../types";
+export type Props = {
+    children: string;
+    className?: ClassName;
+    inline?: boolean;
+    copyable?: boolean;
+    numbered?: boolean;
+};
+/**
+ * @deprecated Code component is deprecated. Use CodeSnippet component or inline `<code>` instead.
+ */
+declare const Code: ({ children, className, inline, copyable, numbered, ...props }: Props) => JSX.Element;
+export default Code;

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

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

package/dist/components/CodeSnippet/CodeSnippet.d.ts

@@ -0,0 +1,21 @@
+import { HTMLProps } from "react";
+import type { Props as CodeSnippetBlockProps } from "./CodeSnippetBlock";
+import type { ClassName, PropsWithSpread } from "../../types";
+export type Props = PropsWithSpread<{
+    /**
+     * Optional class(es) to pass to the wrapping div element.
+     */
+    className?: ClassName;
+    /**
+     * A list of code blocks to display.
+     */
+    blocks: CodeSnippetBlockProps[];
+}, HTMLProps<HTMLDivElement>>;
+/**
+ * This is a [React](https://reactjs.org/) component for the Vanilla [Code snippet](https://docs.vanillaframework.io/base/code#code-snippet).
+ *
+ * #### Blocks
+ *
+ * A single `CodeSnippet` component can render multiple separate code blocks. Blocks are provided as an array via the `blocks` prop. Each block object defines values of props for each code block of the snippet.
+ */
+export default function CodeSnippet({ className, blocks, ...props }: Props): JSX.Element;

package/dist/components/CodeSnippet/CodeSnippetBlock.d.ts

@@ -0,0 +1,40 @@
+import type { ReactNode } from "react";
+import type { Props as CodeSnippetDropdownProps } from "./CodeSnippetDropdown";
+import type { ValueOf } from "../../types";
+export declare const CodeSnippetBlockAppearance: {
+    readonly LINUX_PROMPT: "linuxPrompt";
+    readonly NUMBERED: "numbered";
+    readonly URL: "url";
+    readonly WINDOWS_PROMPT: "windowsPrompt";
+};
+export type Props = {
+    /**
+     * The appearance of the code block.
+     */
+    appearance?: ValueOf<typeof CodeSnippetBlockAppearance>;
+    /**
+     * The code snippet to display.
+     */
+    code: ReactNode;
+    /**
+     * Content to show below the code snippet.
+     */
+    content?: ReactNode;
+    /**
+     * A list of dropdowns to display in the header.
+     */
+    dropdowns?: CodeSnippetDropdownProps[];
+    /**
+     * Whether the title should display stacked on top of the dropdowns.
+     */
+    stacked?: boolean;
+    /**
+     * The title of the code block.
+     */
+    title?: string;
+    /**
+     * Whether to enable line wrapping inside the code block.
+     */
+    wrapLines?: boolean;
+};
+export default function CodeSnippetBlock({ appearance, code, content, dropdowns, stacked, title, wrapLines, }: Props): JSX.Element;

package/dist/components/CodeSnippet/CodeSnippetDropdown.d.ts

@@ -0,0 +1,18 @@
+import type { ChangeEventHandler, HTMLProps } from "react";
+export type DropdownOptionProps = {
+    /**
+     * The label of the dropdown option.
+     */
+    label: string;
+} & HTMLProps<HTMLOptionElement>;
+export type Props = {
+    /**
+     * Function for handling the select value changing.
+     */
+    onChange: ChangeEventHandler<HTMLSelectElement>;
+    /**
+     * Options to pass to the select.
+     */
+    options: DropdownOptionProps[];
+} & HTMLProps<HTMLSelectElement>;
+export default function CodeSnippetDropdown({ options, onChange, ...props }: Props): JSX.Element;

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

@@ -0,0 +1,5 @@
+export { default } from "./CodeSnippet";
+export type { Props as CodeSnippetProps } from "./CodeSnippet";
+export { CodeSnippetBlockAppearance } from "./CodeSnippetBlock";
+export type { Props as CodeSnippetBlockProps } from "./CodeSnippetBlock";
+export type { Props as CodeSnippetDropdownProps } from "./CodeSnippetDropdown";

package/dist/components/Col/Col.d.ts

@@ -0,0 +1,53 @@
+import type { ElementType, HTMLProps, ReactNode } from "react";
+import type { ClassName, PropsWithSpread } from "../../types";
+export type ColSize = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12;
+export declare const colSizes: ColSize[];
+export type Props = PropsWithSpread<{
+    /**
+     * The content of the column.
+     */
+    children?: ReactNode;
+    /**
+     * Optional class(es) to pass to the wrapping element.
+     */
+    className?: ClassName;
+    /**
+     * Optional element type to give the wrapper if not "div".
+     */
+    element?: ElementType;
+    /**
+     * The number of columns to skip before starting on large screens.
+     */
+    emptyLarge?: ColSize;
+    /**
+     * The number of columns to skip before starting on medium screens.
+     */
+    emptyMedium?: ColSize;
+    /**
+     * The number of columns to skip before starting on small screens.
+     */
+    emptySmall?: ColSize;
+    /**
+     * Override for the number of columns the content occupies on large screens.
+     */
+    large?: ColSize;
+    /**
+     * Override for the number of columns the content occupies on medium screens.
+     */
+    medium?: ColSize;
+    /**
+     * The number of columns the content occupies.
+     */
+    size: ColSize;
+    /**
+     * Override for the number of columns the content occupies on small screens.
+     */
+    small?: ColSize;
+}, HTMLProps<HTMLElement>>;
+/**
+ * This is a [React](https://reactjs.org/) component for use within the Vanilla [Grid](https://docs.vanillaframework.io/patterns/grid/).
+ *
+ * Vanilla has a responsive grid using a combination of rows and columns.
+ */
+declare const Col: ({ children, className, element: Component, emptyLarge, emptyMedium, emptySmall, large, medium, size, small, ...props }: Props) => JSX.Element;
+export default Col;

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

@@ -0,0 +1,2 @@
+export { default, colSizes } from "./Col";
+export type { ColSize, Props as ColProps } from "./Col";

package/dist/components/ConfirmationButton/ConfirmationButton.d.ts

@@ -0,0 +1,28 @@
+import { ReactElement } from "react";
+import { PropsWithSpread, SubComponentProps } from "../../types";
+import { ActionButtonProps } from "../ActionButton";
+import { ConfirmationModalProps } from "../ConfirmationModal";
+export type Props = PropsWithSpread<{
+    /**
+     * Additional props to pass to the confirmation modal.
+     */
+    confirmationModalProps: SubComponentProps<ConfirmationModalProps>;
+    /**
+     * An optional text to be shown when hovering over the button.<br/>
+     * Defaults to the label of the confirm button in the modal.
+     */
+    onHoverText?: string;
+    /**
+     * Whether to enable the SHIFT+Click shortcut to skip the confirmation modal and perform the action.
+     */
+    shiftClickEnabled?: boolean;
+    /**
+     * Whether to show a hint about the SHIFT+Click shortcut to skip the confirmation modal.
+     */
+    showShiftClickHint?: boolean;
+}, ActionButtonProps>;
+/**
+ * `ConfirmationButton` is a specialised version of the [ActionButton](?path=/docs/actionbutton--default-story) component that uses a [ConfirmationModal](?path=/docs/confirmationmodal--default-story) to prompt a confirmation from the user before executing an action.
+ */
+export declare const ConfirmationButton: ({ confirmationModalProps, onHoverText, shiftClickEnabled, showShiftClickHint, ...actionButtonProps }: Props) => ReactElement;
+export default ConfirmationButton;

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

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

package/dist/components/ConfirmationModal/ConfirmationModal.d.ts

@@ -0,0 +1,53 @@
+import { MouseEvent, ReactElement } from "react";
+import type { ReactNode } from "react";
+import { PropsWithSpread, ValueOf } from "../../types";
+import { ButtonAppearance, ButtonProps } from "../Button";
+import { ModalProps } from "../Modal";
+import { ActionButtonProps } from "../ActionButton";
+export type Props = PropsWithSpread<{
+    /**
+     * Label for the cancel button.
+     */
+    cancelButtonLabel?: ReactNode;
+    /**
+     * Additional props to be spread on the cancel button.
+     */
+    cancelButtonProps?: Partial<ButtonProps>;
+    /**
+     * The content of the modal.
+     */
+    children: ReactNode;
+    /**
+     * Appearance of the confirm button.
+     */
+    confirmButtonAppearance?: ValueOf<typeof ButtonAppearance> | string;
+    /**
+     * Label for the confirm button.
+     */
+    confirmButtonLabel: ReactNode;
+    /**
+     * Additional props to be spread on the confirm button.
+     */
+    confirmButtonProps?: Partial<ActionButtonProps>;
+    /**
+     * Extra elements to be placed in the button row of the modal.
+     */
+    confirmExtra?: ReactNode;
+    /**
+     * Function to perform the action prompted by the modal.
+     */
+    onConfirm: (event: MouseEvent<HTMLElement>) => void;
+    /**
+     * Whether the confirm button should be in the loading state.
+     */
+    confirmButtonLoading?: boolean;
+    /**
+     * Whether the confirm button should be disabled.
+     */
+    confirmButtonDisabled?: boolean;
+}, Omit<ModalProps, "buttonRow">>;
+/**
+ * `ConfirmationModal` is a specialised version of the [Modal](?path=/docs/modal--default-story) component to prompt a confirmation from the user before executing an action.
+ */
+export declare const ConfirmationModal: ({ cancelButtonLabel, cancelButtonProps, children, confirmButtonAppearance, confirmButtonLabel, confirmExtra, onConfirm, confirmButtonLoading, confirmButtonDisabled, confirmButtonProps, ...props }: Props) => ReactElement;
+export default ConfirmationModal;

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

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

package/dist/components/ContextualMenu/ContextualMenu.d.ts

@@ -0,0 +1,110 @@
+import React from "react";
+import type { HTMLProps, ReactNode } from "react";
+import type { ButtonProps } from "../Button";
+import type { ContextualMenuDropdownProps } from "./ContextualMenuDropdown";
+import type { MenuLink, Position } from "./ContextualMenuDropdown";
+import { ClassName, ExclusiveProps, PropsWithSpread, SubComponentProps } from "../../types";
+export declare enum Label {
+    Toggle = "Toggle menu"
+}
+export type BaseProps<L> = PropsWithSpread<{
+    /**
+     * Whether the menu should adjust its horizontal position to fit on the screen.
+     */
+    autoAdjust?: boolean;
+    /**
+     * The menu content (if the links prop is not supplied).
+     */
+    children?: ContextualMenuDropdownProps["dropdownContent"];
+    /**
+     * An optional class to apply to the wrapping element.
+     */
+    className?: ClassName;
+    /**
+     * Whether the menu should close when the escape key is pressed.
+     */
+    closeOnEsc?: boolean;
+    /**
+     * Whether the menu should close when clicking outside the menu.
+     */
+    closeOnOutsideClick?: boolean;
+    /**
+     * Whether the menu's width should match the toggle's width.
+     */
+    constrainPanelWidth?: boolean;
+    /**
+     * An optional class to apply to the dropdown.
+     */
+    dropdownClassName?: string | null;
+    /**
+     * Additional props to pass to the dropdown.
+     */
+    dropdownProps?: SubComponentProps<ContextualMenuDropdownProps>;
+    /**
+     * A list of links to display in the menu (if the children prop is not supplied.)
+     */
+    links?: MenuLink<L>[] | null;
+    /**
+     * A function to call when the menu is toggled.
+     */
+    onToggleMenu?: (isOpen: boolean) => void | null;
+    /**
+     * The horizontal position of the menu.
+     */
+    position?: Position | null;
+    /**
+     * An element to make the menu relative to.
+     */
+    positionNode?: HTMLElement | null;
+    /**
+     * Whether the dropdown should scroll if it is too long to fit on the screen.
+     */
+    scrollOverflow?: boolean;
+    /**
+     * Whether the menu should be visible.
+     */
+    visible?: boolean;
+}, HTMLProps<HTMLSpanElement>>;
+/**
+ * The props for the ContextualMenu component.
+ * @template L - The type of the link props.
+ */
+export type Props<L> = BaseProps<L> & ExclusiveProps<{
+    /**
+     * Whether the toggle should display a chevron icon.
+     */
+    hasToggleIcon?: boolean;
+    /**
+     * The appearance of the toggle button.
+     */
+    toggleAppearance?: ButtonProps["appearance"] | null;
+    /**
+     * A class to apply to the toggle button.
+     */
+    toggleClassName?: string | null;
+    /**
+     * Whether the toggle button should be disabled.
+     */
+    toggleDisabled?: boolean;
+    /**
+     * The toggle button's label.
+     */
+    toggleLabel?: React.ReactNode | null;
+    /**
+     * Whether the toggle lable or icon should appear first.
+     */
+    toggleLabelFirst?: boolean;
+    /**
+     * Additional props to pass to the toggle button.
+     */
+    toggleProps?: SubComponentProps<ButtonProps>;
+}, {
+    toggle: ReactNode;
+}>;
+/**
+ * This is a [React](https://reactjs.org/) component for the Vanilla [Contextual menu](https://docs.vanillaframework.io/patterns//contextual-menu/).
+ *
+ * A contextual menu can be used in conjunction with any page element to provide a contextual menu.
+ */
+declare const ContextualMenu: <L>({ autoAdjust, children, className, closeOnEsc, closeOnOutsideClick, constrainPanelWidth, dropdownClassName, dropdownProps, hasToggleIcon, links, onToggleMenu, position, positionNode, scrollOverflow, toggle, toggleAppearance, toggleClassName, toggleDisabled, toggleLabel, toggleLabelFirst, toggleProps, visible, ...wrapperProps }: Props<L>) => JSX.Element;
+export default ContextualMenu;

package/dist/components/ContextualMenu/ContextualMenuDropdown/ContextualMenuDropdown.d.ts

@@ -0,0 +1,43 @@
+import { ReactElement } from "react";
+import type { HTMLProps, ReactNode } from "react";
+import type { ButtonProps } from "../../Button";
+import type { WindowFitment } from "../../../hooks";
+export declare enum Label {
+    Dropdown = "submenu"
+}
+/**
+ * The type of the menu links.
+ * @template L - The type of the link props.
+ */
+export type MenuLink<L = null> = string | ButtonProps<L> | ButtonProps<L>[];
+export type Position = "left" | "center" | "right";
+/**
+ * The props for the ContextualMenuDropdown component.
+ * @template L - The type of the link props.
+ */
+export type Props<L = null> = {
+    adjustedPosition?: Position;
+    autoAdjust?: boolean;
+    handleClose?: (evt?: MouseEvent) => void;
+    constrainPanelWidth?: boolean;
+    dropdownClassName?: string;
+    dropdownContent?: ReactNode | ((close: () => void) => ReactElement);
+    id?: string;
+    isOpen?: boolean;
+    links?: MenuLink<L>[];
+    position?: Position;
+    positionCoords?: DOMRect;
+    positionNode?: HTMLElement;
+    scrollOverflow?: boolean;
+    setAdjustedPosition?: (position: Position) => void;
+    contextualMenuClassName?: string;
+} & HTMLProps<HTMLSpanElement>;
+/**
+ * Calculate the adjusted position in relation to the window.
+ * @param position - The requested position.
+ * @param fitsWindow - The window fitment info.
+ * @return The new position.
+ */
+export declare const adjustForWindow: (position: Position, fitsWindow: WindowFitment) => Position;
+declare const ContextualMenuDropdown: <L>({ adjustedPosition, autoAdjust, handleClose, constrainPanelWidth, dropdownClassName, dropdownContent, id, isOpen, links, position, positionCoords, positionNode, scrollOverflow, setAdjustedPosition, contextualMenuClassName, ...props }: Props<L>) => JSX.Element;
+export default ContextualMenuDropdown;

package/dist/components/ContextualMenu/ContextualMenuDropdown/index.d.ts

@@ -0,0 +1,2 @@
+export { default } from "./ContextualMenuDropdown";
+export type { MenuLink, Position, Props as ContextualMenuDropdownProps, } from "./ContextualMenuDropdown";

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

@@ -0,0 +1,3 @@
+export { default } from "./ContextualMenu";
+export type { Props as ContextualMenuProps } from "./ContextualMenu";
+export type { ContextualMenuDropdownProps, MenuLink, Position, } from "./ContextualMenuDropdown";

package/dist/components/EmptyState/EmptyState.d.ts

@@ -0,0 +1,25 @@
+import { ReactNode, HTMLProps, ReactElement } from "react";
+import { PropsWithSpread } from "../../types";
+export type Props = PropsWithSpread<{
+    /**
+     * The content of the empty state.
+     */
+    children?: ReactNode;
+    /**
+     * Optional class(es) to add to the wrapping element.
+     */
+    className?: string;
+    /**
+     * An image representing the empty state.
+     */
+    image: ReactNode;
+    /**
+     * The title of the empty state.
+     */
+    title: string;
+}, HTMLProps<HTMLDivElement>>;
+/**
+ * This is a [React](https://reactjs.org/) component to represent an empty state.
+ */
+export declare const EmptyState: ({ children, className, image, title, ...props }: Props) => ReactElement;
+export default EmptyState;

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

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

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

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

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

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

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

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