@canonical/react-components 1.3.0 → 1.3.2

package/dist/components/Accordion/Accordion.d.ts

@@ -0,0 +1,46 @@
+import { HTMLProps } from "react";
+import type { AccordionHeadings, AccordionSectionProps } from "./AccordionSection";
+import type { ClassName, PropsWithSpread } from "../../types";
+export type Section = AccordionSectionProps & {
+    /**
+     * An optional key for the section component. It will also be
+     * used to track which section is selected.
+     */
+    key?: string | number;
+};
+export type Props = PropsWithSpread<{
+    /**
+     * Optional classes applied to the parent element.
+     */
+    className?: ClassName;
+    /**
+     * An optional value to set the expanded section. The value must match a
+     * section key. This value will only set the expanded section on first render
+     * if externallyControlled is not set to `true`.
+     */
+    expanded?: string;
+    /**
+     * Whether the expanded section will be controlled via external state.
+     */
+    externallyControlled?: boolean;
+    /**
+     * Optional function that is called when the expanded section is changed.
+     * The function is provided the section title or null.
+     */
+    onExpandedChange?: (id: string, title: string) => void;
+    /**
+     * An array of sections and content.
+     */
+    sections: Section[];
+    /**
+     * Optional string describing heading element that should be used for the section titles.
+     */
+    titleElement?: AccordionHeadings;
+}, HTMLProps<HTMLElement>>;
+/**
+ * This is a [React](https://reactjs.org/) component for the Vanilla [Accordion](https://docs.vanillaframework.io/patterns/accordion/).
+ *
+ * The sidebar accordion, used in listing pages or as navigation, can hold multiple navigation items or to be used as a filter for content.
+ */
+declare const Accordion: ({ className, expanded, externallyControlled, onExpandedChange, sections, titleElement, ...asideProps }: Props) => JSX.Element;
+export default Accordion;

package/dist/components/Accordion/AccordionSection/AccordionSection.d.ts

@@ -0,0 +1,34 @@
+import type { ReactNode } from "react";
+import type { Headings } from "../../../types";
+export type AccordionHeadings = Exclude<Headings, "h1">;
+export type Props = {
+    /**
+     * The content of the section.
+     */
+    content?: ReactNode;
+    /**
+     * An optional value to set the expanded section. The value must match a
+     * section key.
+     */
+    expanded?: string | null;
+    headingLevel?: number;
+    /**
+     * An optional click event when the title is clicked.
+     */
+    onTitleClick?: (expanded: boolean, key: string) => void;
+    /**
+     * An optional key to be used to track which section is selected.
+     */
+    sectionKey?: string;
+    setExpanded?: (key: string | null, title: ReactNode | null) => void;
+    /**
+     * The title of the section.
+     */
+    title?: ReactNode;
+    /**
+     * Optional string describing heading element that should be used for the section titles.
+     */
+    titleElement?: AccordionHeadings;
+};
+declare const AccordionSection: ({ content, expanded, onTitleClick, sectionKey, setExpanded, title, titleElement, headingLevel, }: Props) => JSX.Element;
+export default AccordionSection;

package/dist/components/Accordion/AccordionSection/index.d.ts

@@ -0,0 +1,2 @@
+export { default } from "./AccordionSection";
+export type { Props as AccordionSectionProps, AccordionHeadings, } from "./AccordionSection";

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

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

package/dist/components/ActionButton/ActionButton.d.ts

@@ -0,0 +1,48 @@
+import type { ButtonHTMLAttributes, ReactNode } from "react";
+import type { ButtonProps } from "../Button";
+import type { ClassName, PropsWithSpread } from "../../types";
+export declare const LOADER_MIN_DURATION = 400;
+export declare const SUCCESS_DURATION = 2000;
+export declare enum Label {
+    WAITING = "Waiting for action to complete",
+    SUCCESS = "Action completed"
+}
+export type Props = PropsWithSpread<{
+    /**
+     * The appearance of the button.
+     */
+    appearance?: ButtonProps["appearance"];
+    /**
+     * The content of the button.
+     */
+    children?: ReactNode;
+    /**
+     * Optional class(es) to pass to the button element.
+     */
+    className?: ClassName;
+    /**
+     * Whether the button should be disabled.
+     */
+    disabled?: boolean;
+    /**
+     * Whether the button should display inline.
+     */
+    inline?: boolean;
+    /**
+     * Whether the button should be in the loading state.
+     */
+    loading?: boolean;
+    /**
+     * Whether the button should be in the success state.
+     */
+    success?: boolean;
+}, ButtonHTMLAttributes<HTMLButtonElement>>;
+/**
+ * This is a not an existing Vanilla component. It can be used to display submitting states for forms or other actions.
+ *
+ * ActionButton accepts the props from
+ * [Button](?path=/docs/components-button--docs) in addition to those in the
+ * props table:
+ */
+declare const ActionButton: ({ appearance, children, className, disabled, inline, loading, success, ...buttonProps }: Props) => JSX.Element;
+export default ActionButton;

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

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

package/dist/components/ApplicationLayout/AppAside/AppAside.d.ts

@@ -0,0 +1,33 @@
+import React from "react";
+import type { PropsWithSpread } from "../../../types";
+import { type HTMLProps, type PropsWithChildren } from "react";
+export type Props = PropsWithSpread<{
+    /**
+     * Whether the aside panel should be collapsed. Toggling this state will animate
+     * the panel open or closed.
+     */
+    collapsed?: boolean;
+    /**
+     * The panel content.
+     */
+    children?: PropsWithChildren["children"];
+    /**
+     * A ref that will be passed to the wrapping `<aside>` element.
+     */
+    forwardRef?: React.Ref<HTMLElement> | null;
+    /**
+     * Whether the aside panel should be narrow.
+     */
+    narrow?: boolean;
+    /**
+     * Whether the aside panel should be pinned. When pinned the panel will appear
+     * beside the main content, instead of above it.
+     */
+    pinned?: boolean;
+    /**
+     * Whether the aside panel should be wide.
+     */
+    wide?: boolean;
+}, HTMLProps<HTMLElement>>;
+declare const AppAside: ({ children, className, collapsed, narrow, forwardRef, pinned, wide, ...props }: Props) => React.JSX.Element;
+export default AppAside;

package/dist/components/ApplicationLayout/AppAside/index.d.ts

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

package/dist/components/ApplicationLayout/AppMain/AppMain.d.ts

@@ -0,0 +1,14 @@
+import React from "react";
+import type { HTMLProps, PropsWithChildren } from "react";
+export type Props = {
+    /**
+     * The main content.
+     */
+    children?: PropsWithChildren["children"];
+} & HTMLProps<HTMLDivElement>;
+/**
+ * This is a [React](https://reactjs.org/) component for main content area in the Vanilla
+ * [Application Layout](https://vanillaframework.io/docs/layouts/application).
+ */
+declare const AppMain: ({ children, className, ...props }: Props) => React.JSX.Element;
+export default AppMain;

package/dist/components/ApplicationLayout/AppMain/index.d.ts

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

package/dist/components/ApplicationLayout/AppNavigation/AppNavigation.d.ts

@@ -0,0 +1,26 @@
+import React from "react";
+import type { PropsWithSpread } from "../../../types";
+import type { HTMLProps, PropsWithChildren } from "react";
+export type Props = PropsWithSpread<{
+    /**
+     * Whether the navigation panel should be collapsed.
+     */
+    collapsed?: boolean;
+    /**
+     * The navigation drawer content.
+     */
+    children?: PropsWithChildren["children"];
+    /**
+     * Whether the navigation panel should be pinned.
+     */
+    pinned?: boolean;
+}, HTMLProps<HTMLDivElement>>;
+/**
+ * This is a [React](https://reactjs.org/) component for the navigation panel in the Vanilla
+ * [Application Layout](https://vanillaframework.io/docs/layouts/application).
+ *
+ * This component is used to display the left navigation panel. It should be
+ * used alongside [`AppNavigationBar`](/docs/components-applicationlayout-appnavigationbar--docs).
+ */
+declare const AppNavigation: ({ children, className, collapsed, pinned, ...props }: Props) => React.JSX.Element;
+export default AppNavigation;

package/dist/components/ApplicationLayout/AppNavigation/index.d.ts

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

package/dist/components/ApplicationLayout/AppNavigationBar/AppNavigationBar.d.ts

@@ -0,0 +1,18 @@
+import React from "react";
+import type { PropsWithSpread } from "../../../types";
+import type { HTMLProps, PropsWithChildren } from "react";
+export type Props = PropsWithSpread<{
+    /**
+     * The navigation content.
+     */
+    children?: PropsWithChildren["children"];
+}, HTMLProps<HTMLElement>>;
+/**
+ * This is a [React](https://reactjs.org/) component for navigation bar in the Vanilla
+ * [Application Layout](https://vanillaframework.io/docs/layouts/application).
+ *
+ * This component is used to display the navigation panel on mobile or small
+ * screens. It should be used alongside [`AppNavigation`](/docs/components-applicationlayout-appnavigation--docs).
+ */
+declare const AppNavigationBar: ({ children, className, ...props }: Props) => React.JSX.Element;
+export default AppNavigationBar;

package/dist/components/ApplicationLayout/AppNavigationBar/index.d.ts

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

package/dist/components/ApplicationLayout/AppStatus/AppStatus.d.ts

@@ -0,0 +1,14 @@
+import React from "react";
+import type { HTMLProps, PropsWithChildren } from "react";
+export type Props = {
+    /**
+     * The status content.
+     */
+    children?: PropsWithChildren["children"];
+} & HTMLProps<HTMLDivElement>;
+/**
+ * This is a [React](https://reactjs.org/) component for status area in the Vanilla
+ * [Application Layout](https://vanillaframework.io/docs/layouts/application).
+ */
+declare const AppStatus: ({ children, className, ...props }: Props) => React.JSX.Element;
+export default AppStatus;

package/dist/components/ApplicationLayout/AppStatus/index.d.ts

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

package/dist/components/ApplicationLayout/Application/Application.d.ts

@@ -0,0 +1,15 @@
+import React from "react";
+import type { PropsWithSpread } from "../../../types";
+import type { HTMLProps, PropsWithChildren } from "react";
+export type Props = PropsWithSpread<{
+    /**
+     * The application content.
+     */
+    children?: PropsWithChildren["children"];
+}, HTMLProps<HTMLDivElement>>;
+/**
+ * This is a [React](https://reactjs.org/) component for the application wrapper in the Vanilla
+ * [Application Layout](https://vanillaframework.io/docs/layouts/application).
+ */
+declare const Application: ({ children, className, ...props }: Props) => React.JSX.Element;
+export default Application;

package/dist/components/ApplicationLayout/Application/index.d.ts

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

package/dist/components/ApplicationLayout/ApplicationLayout.d.ts

@@ -0,0 +1,89 @@
+import React from "react";
+import type { PropsWithSpread } from "../../types";
+import type { ReactNode } from "react";
+import { type HTMLProps, type PropsWithChildren } from "react";
+import type { PanelProps } from "../Panel";
+import type { PanelLogoDefaultElement } from "../Panel";
+import type { ExclusiveProps } from "../../types";
+import type { SideNavigationProps } from "../SideNavigation";
+import type { SideNavigationLinkDefaultElement } from "../SideNavigation/SideNavigationLink/index";
+export type BaseProps<NI = SideNavigationLinkDefaultElement, PL = PanelLogoDefaultElement> = PropsWithSpread<{
+    /**
+     * The aside panel. This prop puts the panel in the correct position inside the
+     * application layout DOM structure, but does not wrap the content in an aside,
+     * so the content provided to this prop should include an `<AppAside>` or equivalent.
+     */
+    aside?: ReactNode;
+    /**
+     * The content for the main area.
+     */
+    children?: PropsWithChildren["children"];
+    /**
+     * Whether to use the dark theme.
+     * @default true
+     */
+    dark?: boolean;
+    /**
+     * The logo to appear in the navigation panels.
+     */
+    logo?: PanelProps<PL>["logo"];
+    /**
+     * The component to use to render links inside the navigation e.g. when
+     * using react-router you'd pass `Link` to this prop.
+     */
+    navLinkComponent?: SideNavigationProps<NI>["linkComponent"];
+    /**
+     * Whether the navigation menu should be collapsed.
+     */
+    menuCollapsed?: boolean;
+    /**
+     * Whether the navigation menu should be pinned.
+     */
+    menuPinned?: boolean;
+    /**
+     * A function that is called to collapse the navigation menu.
+     */
+    onCollapseMenu?: (menuCollapsed: boolean) => void;
+    /**
+     * A function that is called to pin the navigation menu.
+     */
+    onPinMenu?: (menuPinned: boolean) => void;
+    /**
+     * The content to appear inside the status area.
+     */
+    status?: ReactNode;
+    /**
+     * Classes to apply to the navigation bar.
+     */
+    navigationBarClassName?: string;
+    /**
+     * Classes to apply to the navigation menu.
+     */
+    navigationClassName?: string;
+    /**
+     * Classes to apply to the main area.
+     */
+    mainClassName?: string;
+    /**
+     * Classes to apply to the status area.
+     */
+    statusClassName?: string;
+}, HTMLProps<HTMLDivElement>>;
+export type Props<NI = SideNavigationLinkDefaultElement, PL = PanelLogoDefaultElement> = BaseProps<NI, PL> & ExclusiveProps<{
+    navItems?: SideNavigationProps<NI>["items"];
+}, {
+    sideNavigation?: ReactNode;
+}>;
+/**
+ * This is a [React](https://reactjs.org/) component for the Vanilla
+ * [Application Layout](https://vanillaframework.io/docs/layouts/application).
+ *
+ * This component combines the various sub-components that make up the
+ * Application Layout to make it easier to consume. For some applications this
+ * component maybe not be flexible enough, in which case you may choose to use
+ * the sub-components directly. Be aware that the application layout requires a
+ * specific structure and states to function correctly so there will be a
+ * trade-off when using the sub-components directly.
+ */
+declare const ApplicationLayout: <NI = SideNavigationLinkDefaultElement, PL = PanelLogoDefaultElement>({ aside, children, dark, logo, mainClassName, menuCollapsed, menuPinned, navigationBarClassName, navigationClassName, navItems, navLinkComponent, onCollapseMenu, onPinMenu, sideNavigation, status, statusClassName, ...props }: Props<NI, PL>) => React.JSX.Element;
+export default ApplicationLayout;

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

@@ -0,0 +1,7 @@
+export { default, type Props as ApplicationLayoutProps, } from "./ApplicationLayout";
+export { default as AppAside, type AppAsideProps } from "./AppAside";
+export { default as Application, type ApplicationProps } from "./Application";
+export { default as AppMain, type AppMainProps } from "./AppMain";
+export { default as AppNavigation, type AppNavigationProps, } from "./AppNavigation";
+export { default as AppNavigationBar, type AppNavigationBarProps, } from "./AppNavigationBar";
+export { default as AppStatus, type AppStatusProps } from "./AppStatus";

package/dist/components/ArticlePagination/ArticlePagination.d.ts

@@ -0,0 +1,31 @@
+import type { HTMLProps } from "react";
+import type { ClassName, PropsWithSpread } from "../../types";
+export type Props = PropsWithSpread<{
+    /**
+     * Optional classes to add to the wrapping element.
+     */
+    className?: ClassName;
+    /**
+     * The URL for the next link.
+     */
+    nextURL?: string;
+    /**
+     * The label for the next link.
+     */
+    nextLabel?: string;
+    /**
+     * The URL for the previous link.
+     */
+    previousURL?: string;
+    /**
+     * The label for the previous link.
+     */
+    previousLabel?: string;
+}, HTMLProps<HTMLElement>>;
+/**
+ * This is a [React](https://reactjs.org/) component for the Vanilla [Article pagination](https://docs.vanillaframework.io/patterns/article-pagination/).
+ *
+ * The article pagination component should be used to navigate from one article to the next, or previous, in chronological order.
+ */
+declare const ArticlePagination: ({ className, nextURL, nextLabel, previousURL, previousLabel, ...props }: Props) => JSX.Element;
+export default ArticlePagination;

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

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

package/dist/components/Badge/Badge.d.ts

@@ -0,0 +1,34 @@
+import { HTMLProps } from "react";
+import type { ClassName, PropsWithSpread, ValueOf } from "../../types";
+export declare const BadgeType: {
+    readonly ROUNDED_LARGE_NUMBER: "ROUNDED_LARGE_NUMBER";
+    readonly UNDEFINED_LARGE_NUMBER: "UNDEFINED_LARGE_NUMBER";
+};
+/**
+ * The props for the Badge component.
+ */
+export type Props = PropsWithSpread<{
+    /**
+     * Numeric value to be displayed.
+     */
+    value: number;
+    /**
+     * The type of the badge component.
+     */
+    badgeType?: ValueOf<typeof BadgeType>;
+    /**
+     * The appearance of the badge.
+     */
+    isNegative?: boolean;
+    /**
+     * Optional class(es) to give to the badge.
+     */
+    className?: ClassName;
+}, HTMLProps<HTMLSpanElement>>;
+/**
+ * This is a [React](https://reactjs.org/) component for the Vanilla [Badge](https://vanillaframework.io/docs/patterns/badge).
+ *
+ * It can be used to display a numeric values.
+ */
+declare const Badge: ({ value, badgeType, className, isNegative, ...spanProps }: Props) => JSX.Element;
+export default Badge;

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

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

package/dist/components/Button/Button.d.ts

@@ -0,0 +1,64 @@
+import type { ButtonHTMLAttributes, ComponentType, ElementType, MouseEventHandler, ReactNode } from "react";
+import type { ClassName, ValueOf } from "../../types";
+export declare const ButtonAppearance: {
+    readonly BASE: "base";
+    readonly BRAND: "brand";
+    readonly DEFAULT: "";
+    readonly LINK: "link";
+    readonly NEGATIVE: "negative";
+    readonly POSITIVE: "positive";
+};
+/**
+ * The type of the Button props.
+ * @template P - The type of the props if providing a component to `element`
+ */
+export type Props<P = null> = {
+    /**
+     * The appearance of the button.
+     */
+    appearance?: ValueOf<typeof ButtonAppearance> | string;
+    /**
+     * The content of the button.
+     */
+    children?: ReactNode;
+    /**
+     * Optional class(es) to pass to the button element.
+     */
+    className?: ClassName;
+    /**
+     * Whether the button should have dense padding.
+     */
+    dense?: boolean;
+    /**
+     * Whether the button should be disabled.
+     */
+    disabled?: boolean;
+    /**
+     * Optional element or component to use instead of `button`.
+     */
+    element?: ElementType | ComponentType<P>;
+    /**
+     * Whether the button has an icon in the content.
+     */
+    hasIcon?: boolean;
+    /**
+     * Whether the button should display inline.
+     */
+    inline?: boolean;
+    /**
+     * Function for handling button click event.
+     */
+    onClick?: MouseEventHandler<HTMLButtonElement>;
+    /**
+     * Whether the button should be small.
+     */
+    small?: boolean;
+} & (Omit<ButtonHTMLAttributes<HTMLButtonElement>, "onClick"> | P);
+/**
+ * This is a [React](https://reactjs.org/) component for the Vanilla [Button](https://docs.vanillaframework.io/patterns/buttons/).
+ *
+ * Buttons are clickable elements used to perform an action, they can be used for buttons and link elements.
+ * @template P - The type of the props if providing a component to `element`
+ */
+declare const Button: <P>({ appearance, children, className, dense, disabled, element: Component, hasIcon, inline, onClick, small, ...buttonProps }: Props<P>) => JSX.Element;
+export default Button;

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

@@ -0,0 +1,2 @@
+export { default, ButtonAppearance } from "./Button";
+export type { Props as ButtonProps } from "./Button";

package/dist/components/Card/Card.d.ts

@@ -0,0 +1,35 @@
+import type { HTMLProps, ReactNode } from "react";
+import type { ClassName, PropsWithSpread } from "../../types";
+export type Props = PropsWithSpread<{
+    /**
+     * The content of the card.
+     */
+    children?: ReactNode;
+    /**
+     * Optional class(es) to pass to the wrapping div element.
+     */
+    className?: ClassName;
+    /**
+     * Whether the card should have highlighted styling.
+     */
+    highlighted?: boolean;
+    /**
+     * Whether the card should have overlay styling.
+     */
+    overlay?: boolean;
+    /**
+     * The path to a thumbnail image.
+     */
+    thumbnail?: string;
+    /**
+     * The title of the card.
+     */
+    title?: ReactNode;
+}, HTMLProps<HTMLDivElement>>;
+/**
+ * This is a [React](https://reactjs.org/) component for the Vanilla [Card](https://docs.vanillaframework.io/patterns/card/).
+ *
+ * There are four card styles available to use in Vanilla: default, header, highlighted and overlay. Our card component will expand to fill the full width of its parent container.
+ */
+declare const Card: ({ children, className, highlighted, overlay, thumbnail, title, ...props }: Props) => JSX.Element;
+export default Card;

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

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

package/dist/components/CheckboxInput/CheckableInput/CheckableInput.d.ts

@@ -0,0 +1,27 @@
+import { HTMLProps } from "react";
+import type { ReactNode } from "react";
+import type { PropsWithSpread } from "../../../types";
+export type Props = PropsWithSpread<{
+    /**
+     * The type of the input element.
+     */
+    inputType: "radio" | "checkbox";
+    /**
+     * The label for the input element.
+     */
+    label: ReactNode;
+    /**
+     * Optional class(es) to pass to the label element.
+     */
+    labelClassName?: string;
+    /**
+     * Whether the input element should display in indeterminate state.
+     */
+    indeterminate?: boolean;
+    /**
+     * Ensures the input and the label text are properly aligned with other inline text.
+     */
+    inline?: boolean;
+}, Omit<HTMLProps<HTMLInputElement>, "type">>;
+declare const CheckableInput: ({ inputType, label, labelClassName, indeterminate, inline, ...checkboxProps }: Props) => JSX.Element;
+export default CheckableInput;

package/dist/components/CheckboxInput/CheckableInput/index.d.ts

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

package/dist/components/CheckboxInput/CheckboxInput.d.ts

@@ -0,0 +1,9 @@
+import type { CheckableInputProps } from "./CheckableInput";
+export type Props = Omit<CheckableInputProps, "inputType">;
+/**
+ * This is a [React](https://reactjs.org/) component for the Vanilla [Checkbox input](https://docs.vanillaframework.io/base/forms#checkbox).
+ *
+ * Use the checkbox component to select one or more options.
+ */
+declare const CheckboxInput: ({ label, indeterminate, ...checkboxProps }: Props) => JSX.Element;
+export default CheckboxInput;

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

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