@canonical/react-components 1.3.0 → 1.3.2

package/dist/components/Navigation/Navigation.d.ts

@@ -0,0 +1,66 @@
+import { ReactNode, HTMLProps } from "react";
+import type { GenerateLink, NavItem, LogoProps } from "./types";
+import { PropsWithSpread, SubComponentProps } from "../../types";
+import { SearchBoxProps } from "../SearchBox";
+import { Theme } from "../../enums";
+export type Props = PropsWithSpread<{
+    /**
+     * By default the header is constrained to the width of the grid. Use this
+     * option to make the header take the full width of the page.
+     */
+    fullWidth?: boolean;
+    /**
+     * This function can be used to generate link elements when you don't want to
+     * use a standard HTML anchor.
+     */
+    generateLink?: GenerateLink | null;
+    /**
+     * The main navigation items that appear on the left hand side next to the logo.
+     */
+    items?: NavItem[] | null;
+    /**
+     * Additional navigation items that appear on the right hand side of the
+     * navigation banner.
+     */
+    itemsRight?: NavItem[] | null;
+    /**
+     * Additional props to be applied to the nav element that wraps the main
+     * navigation items on the left hand side.
+     */
+    leftNavProps?: HTMLProps<HTMLUListElement> | null;
+    /**
+     * The logo can be defined either by providing props for the standard logo
+     * or the full logo markup when a custom logo is needed.
+     */
+    logo: LogoProps | ReactNode;
+    /**
+     * Additional props to be applied to the nav element that wraps the
+     * left and right nav items.
+     */
+    navProps?: HTMLProps<HTMLElement> | null;
+    /**
+     * Additional props to be applied to the nav element that wraps the
+     * navigation items on the right hand side.
+     */
+    rightNavProps?: HTMLProps<HTMLUListElement> | null;
+    /**
+     * Props to pass to the SearchBox component. When these props are provided the
+     * search box will appear.
+     */
+    searchProps?: SubComponentProps<SearchBoxProps> | null;
+    /**
+     * The header theme. When this is not provided the header will use the default
+     * theme defined in the Vanilla settings.
+     */
+    theme?: Theme | null;
+}, HTMLProps<HTMLElement>>;
+/**
+This is the [React](https://reactjs.org/) component for the Vanilla
+[Navigation](https://vanillaframework.io/docs/patterns/navigation) pattern. It
+is a simple navigation bar that you can add to the top of your site or app.
+
+The navigation items are collapsed behind a "Menu" link in small screens and
+displayed horizontally on larger screens.
+ */
+declare const Navigation: ({ fullWidth, generateLink, items, itemsRight, leftNavProps, logo, navProps, rightNavProps, searchProps, theme, ...headerProps }: Props) => JSX.Element;
+export default Navigation;

package/dist/components/Navigation/NavigationLink/NavigationLink.d.ts

@@ -0,0 +1,10 @@
+import type { GenerateLink, NavLink } from "../types";
+type Props = {
+    generateLink?: GenerateLink;
+    link: NavLink;
+};
+/**
+ * This component is used internally to display links inside the Navigation component.
+ */
+declare const NavigationLink: ({ generateLink, link }: Props) => JSX.Element | null;
+export default NavigationLink;

package/dist/components/Navigation/NavigationLink/index.d.ts

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

package/dist/components/Navigation/NavigationMenu/NavigationMenu.d.ts

@@ -0,0 +1,11 @@
+import type { HTMLProps } from "react";
+import type { GenerateLink, NavMenu } from "../types";
+import { PropsWithSpread } from "../../../types";
+type Props = PropsWithSpread<NavMenu & {
+    generateLink?: GenerateLink;
+}, HTMLProps<HTMLLIElement>>;
+/**
+ * This component is used internally to display menus inside the Navigation component.
+ */
+declare const NavigationMenu: ({ alignRight, generateLink, items, label, ...props }: Props) => JSX.Element;
+export default NavigationMenu;

package/dist/components/Navigation/NavigationMenu/index.d.ts

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

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

@@ -0,0 +1,3 @@
+export { default } from "./Navigation";
+export type { Props as NavigationProps } from "./Navigation";
+export type { GenerateLink, LogoProps, NavLink, NavLinkAnchor, NavLinkBase, NavLinkButton, NavMenu, NavItem, } from "./types";

package/dist/components/Navigation/types.d.ts

@@ -0,0 +1,64 @@
+import type { HTMLAttributes, HTMLProps, ReactNode } from "react";
+import { PropsWithSpread } from "../../types";
+export type NavLinkBase = {
+    /**
+     * Whether this nav item is currently selected.
+     */
+    isSelected?: boolean;
+    /**
+     * The label of the link.
+     */
+    label: ReactNode;
+    /**
+     * The URL of the link.
+     */
+    url?: string;
+};
+export type NavLinkAnchor = PropsWithSpread<NavLinkBase & {
+    url: string;
+}, HTMLAttributes<HTMLAnchorElement>>;
+export type NavLinkButton = PropsWithSpread<NavLinkBase & {
+    url?: never;
+}, HTMLAttributes<HTMLButtonElement>>;
+export type NavLink = NavLinkAnchor | NavLinkButton;
+export type NavMenu = {
+    /**
+     * Whether to align the dropdown to the right edge of the navigation item.
+     */
+    alignRight?: boolean;
+    /**
+     * The links to appear in the dropdown.
+     */
+    items: NavLink[];
+    /**
+     * The label of the navigation item that opens the menu.
+     */
+    label: string;
+};
+/**
+ * Navigation items which can be either a link or a menu containing links.
+ */
+export type NavItem = NavLink | NavMenu;
+/**
+ * A function that can be used to generate link elements when you don't want to
+ * use a standard HTML anchor.
+ */
+export type GenerateLink = (item: NavLink) => ReactNode;
+export type LogoProps = PropsWithSpread<{
+    /**
+     * An icon to display in the tag.
+     */
+    icon?: ReactNode;
+    /**
+     * The logo image source URL.
+     */
+    src?: string;
+    /**
+     * The site's title.
+     */
+    title: string;
+    /**
+     * The URL to navigate to when the logo is clicked.
+     */
+    url: string;
+}, HTMLProps<HTMLDivElement>>;

package/dist/components/Notification/Notification.d.ts

@@ -0,0 +1,110 @@
+import { ElementType } from "react";
+import type { HTMLProps, ReactNode } from "react";
+import type { ClassName, PropsWithSpread, ValueOf } from "../../types";
+export declare enum Label {
+    Close = "Close notification"
+}
+export declare const NotificationSeverity: {
+    readonly CAUTION: "caution";
+    readonly INFORMATION: "information";
+    readonly NEGATIVE: "negative";
+    readonly POSITIVE: "positive";
+};
+export declare const DefaultTitles: {
+    caution: string;
+    information: string;
+    negative: string;
+    positive: string;
+};
+type NotificationAction = {
+    label: string;
+    onClick: () => void;
+};
+/**
+ * The props for the Notification component.
+ */
+export type Props = PropsWithSpread<{
+    /**
+     * A list of up to two actions that the notification can perform.
+     */
+    actions?: NotificationAction[];
+    /**
+     * Whether the notification should not have a border.
+     */
+    borderless?: boolean;
+    /**
+     * The notification message content.
+     */
+    children?: ReactNode;
+    /**
+     * Optional class(es) to apply to the parent notification element.
+     */
+    className?: ClassName;
+    /**
+     * **Deprecated**. Use `onDismiss` instead.
+     */
+    close?: never;
+    /**
+     * Whether the title should display inline with the message.
+     */
+    inline?: boolean;
+    /**
+     * The function to run when dismissing/closing the notification.
+     */
+    onDismiss?: () => void;
+    /**
+     * The severity of the notification.
+     */
+    severity?: ValueOf<typeof NotificationSeverity>;
+    /**
+     * **Deprecated**. Use `title` instead.
+     */
+    status?: never;
+    /**
+     * The amount of time (in ms) until the notification is automatically dismissed.
+     */
+    timeout?: number;
+    /**
+     * A relevant timestamp for the notification, e.g. when it was created.
+     */
+    timestamp?: ReactNode;
+    /**
+     * The title of the notification.
+     */
+    title?: ReactNode;
+    /**
+     * Optional element or component to use for the title.
+     */
+    titleElement?: ElementType;
+    /**
+     * **Deprecated**. Use `severity` instead.
+     */
+    type?: never;
+}, HTMLProps<HTMLDivElement>>;
+/**
+This is a [React](https://reactjs.org/) component for the Vanilla [Notification](https://docs.vanillaframework.io/patterns/notification/).
+
+Notifications are used to display global information, our notification variants consist of default, caution, negative or positive.
+
+The `NotificationProvider` component can be used to manage the notification state globally. Wrap your application components with it and then in any child component you can get the helper with `const notify = useNotify()` to easily trigger notifications:
+
+* `notify.info("You should keep this in mind")`
+* `notify.failure("Error when fooing a bar", errorObjectFromCatch)`
+* `notify.success("The bar was foo'd", "Success")`
+
+The `NotificationConsumer` component can be used to display notifications. It will automatically display any notifications that are added to the `NotificationProvider` state.
+
+The Notification API has changed since v0.18 in order to support new variants
+and align with our component prop naming conventions.
+
+| Deprecated prop names | Replaced by |
+| --------------------- | ----------- |
+| `type`                | `severity`  |
+| `status`              | `title`     |
+| `close`               | `onDismiss` |
+
+The `notificationTypes` const has also been replaced with `NotificationSeverity`
+to reflect the new prop name.
+ */
+declare const Notification: ({ actions, borderless, children, className, close, inline, onDismiss, severity, status, timeout, timestamp, title, titleElement: TitleComponent, type, ...props }: Props) => JSX.Element;
+export default Notification;

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

@@ -0,0 +1,2 @@
+export { default, NotificationSeverity } from "./Notification";
+export type { Props as NotificationProps } from "./Notification";

package/dist/components/NotificationProvider/NotificationProvider.d.ts

@@ -0,0 +1,5 @@
+import { FC } from "react";
+import { NotificationHelper, NotifyProviderProps } from "./types";
+export declare const NotificationProvider: FC<NotifyProviderProps>;
+export declare function useNotify(): NotificationHelper;
+export declare const NotificationConsumer: FC;

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

@@ -0,0 +1,3 @@
+export { NotificationConsumer, NotificationProvider, useNotify, } from "./NotificationProvider";
+export { info, success, failure, queue } from "./messageBuilder";
+export type { NotificationAction, NotificationType, QueuedNotification, NotificationHelper, } from "./types";

package/dist/components/NotificationProvider/messageBuilder.d.ts

@@ -0,0 +1,6 @@
+import { NotificationAction, NotificationType, QueuedNotification } from "./types";
+import { ReactNode } from "react";
+export declare const queue: (notification: NotificationType) => QueuedNotification;
+export declare const info: (message: ReactNode, title?: string) => NotificationType;
+export declare const success: (message: ReactNode, title?: string) => NotificationType;
+export declare const failure: (title: string, error: unknown, message?: ReactNode, actions?: NotificationAction[]) => NotificationType;

package/dist/components/NotificationProvider/types.d.ts

@@ -0,0 +1,35 @@
+import { ReactNode } from "react";
+import { ValueOf } from "../../types";
+import { NotificationSeverity } from "../Notification";
+export interface NotifyProviderProps {
+    state?: {
+        queuedNotification: NotificationType | null;
+    };
+    pathname?: string;
+    children: ReactNode;
+}
+export interface NotificationAction {
+    label: string;
+    onClick: () => void;
+}
+export interface NotificationType {
+    actions?: NotificationAction[];
+    message: ReactNode;
+    title?: string;
+    type: ValueOf<typeof NotificationSeverity>;
+}
+export interface QueuedNotification {
+    state?: {
+        queuedNotification: NotificationType | null;
+    };
+    pathname?: string;
+}
+export interface NotificationHelper {
+    notification: NotificationType | null;
+    clear: () => void;
+    failure: (title: string, error: unknown, message?: ReactNode, actions?: NotificationAction[]) => NotificationType;
+    info: (message: ReactNode, title?: string) => NotificationType;
+    success: (message: ReactNode, title?: string) => NotificationType;
+    queue: (notification: NotificationType) => QueuedNotification;
+    setDeduplicated: (value: NotificationType) => NotificationType;
+}

package/dist/components/Pagination/Pagination.d.ts

@@ -0,0 +1,102 @@
+import type { HTMLProps } from "react";
+import type { PropsWithSpread } from "../../types";
+type BaseProps = {
+    /**
+     * Whether to scroll to the top of the list on page change.
+     */
+    scrollToTop?: boolean;
+    /**
+     * The number of pages at which to truncate the pagination items.
+     */
+    truncateThreshold?: number;
+    /**
+     * Whether the pagination is ceneterd on the page.
+     */
+    centered?: boolean;
+    /**
+     * Whether to show the labels for forward and back buttons.
+     */
+    showLabels?: boolean;
+    /**
+     * Whether forward button is disabled.
+     */
+    forwardDisabled?: boolean;
+    /**
+     * Whether back button is disabled.
+     */
+    backDisabled?: boolean;
+    /**
+     * Custom label for forward button.
+     */
+    forwardLabel?: string;
+    /**
+     * Custom label for back button.
+     */
+    backLabel?: string;
+};
+type NumberedPagination = BaseProps & {
+    /**
+     * The current page being viewed.<br>
+     * **Required for Numbered Pagination.**
+     */
+    currentPage: number;
+    /**
+     * The number of items to show per page.<br>
+     * **Required for numbered pagination.**
+     */
+    itemsPerPage: number;
+    /**
+     * Function to handle paginating the items.<br>
+     * **Required for numbered pagination.**
+     */
+    paginate: (page: number) => void;
+    /**
+     * The total number of items.<br>
+     * **Required for numbered pagination.**
+     */
+    totalItems: number;
+    /**
+     * Whether to hide the pagination items.
+     */
+    hideNumbers?: boolean;
+    /**
+     * Function to handle page transition to a higher-numbered page for
+     * numbered pagination and to next page for buttons-only pagination.<br>
+     * _Called with page parameter for numbered pagination and_
+     * _with no parameter for buttons-only pagination._<br>
+     * **Required for buttons-only pagination.**
+     */
+    onForward?: (page: number) => void;
+    /**
+     * Function to handle page transition to a lower-numbered page for
+     * numbered pagination and to next page for buttons-only pagination.<br>
+     * _Called with page parameter for numbered pagination and_
+     * _with no parameter for buttons-only pagination._<br>
+     * **Required for buttons-only pagination.**
+     */
+    onBack?: (page: number) => void;
+};
+type ButtonsOnlyPagination = BaseProps & {
+    itemsPerPage?: never;
+    totalItems?: never;
+    currentPage?: never;
+    paginate?: never;
+    hideNumbers?: never;
+    onForward: () => void;
+    onBack: () => void;
+};
+export type Props = PropsWithSpread<NumberedPagination | ButtonsOnlyPagination, HTMLProps<HTMLElement>>;
+/**
+This is a [React](https://reactjs.org/) component for the Vanilla [Pagination](https://docs.vanillaframework.io/patterns/pagination/).
+
+The pagination component should be used to navigate between pages of content. There are two types of pagination being provided:
+
+* **Numbered Pagination:** used when the total number of items is known.<br />
+  Depending on the length provided, the pagination component will automatically scale.<br />
+  **Required props:** itemsPerPage, totalItems, paginate, currentPage.
+
+* **Buttons-only Pagination:** used when the total number of items is unknown.<br />
+  **Required props:** onForward, onBack.
+ */
+declare const Pagination: ({ itemsPerPage, totalItems, paginate, currentPage, scrollToTop, truncateThreshold, centered, showLabels, hideNumbers, onForward, onBack, forwardDisabled, backDisabled, forwardLabel, backLabel, ...navProps }: Props) => JSX.Element;
+export default Pagination;

package/dist/components/Pagination/PaginationButton/PaginationButton.d.ts

@@ -0,0 +1,30 @@
+import type { MouseEventHandler } from "react";
+export declare enum Label {
+    Next = "Next page",
+    Previous = "Previous page"
+}
+export type PaginationDirection = "forward" | "back";
+export type Props = {
+    /**
+     * The direction of the pagination.
+     */
+    direction: PaginationDirection;
+    /**
+     * Whether the pagination button should be disabled.
+     */
+    disabled?: boolean;
+    /**
+     * Function to handle clicking the pagination button.
+     */
+    onClick: MouseEventHandler<HTMLButtonElement>;
+    /**
+     * Whether to show the label for button.
+     */
+    showLabel?: boolean;
+    /**
+     * Custom label for button.
+     */
+    label?: string;
+};
+declare const PaginationButton: ({ direction, onClick, disabled, showLabel, label, }: Props) => JSX.Element;
+export default PaginationButton;

package/dist/components/Pagination/PaginationButton/index.d.ts

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

package/dist/components/Pagination/PaginationItem/PaginationItem.d.ts

@@ -0,0 +1,17 @@
+import type { MouseEventHandler } from "react";
+export type Props = {
+    /**
+     * Whether the pagination item is active, i.e. the current page is this page.
+     */
+    isActive?: boolean;
+    /**
+     * The page number.
+     */
+    number: number;
+    /**
+     * Function to handle clicking the pagination item.
+     */
+    onClick: MouseEventHandler<HTMLButtonElement>;
+};
+declare const PaginationItem: ({ number, onClick, isActive, }: Props) => JSX.Element;
+export default PaginationItem;

package/dist/components/Pagination/PaginationItem/index.d.ts

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

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

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

package/dist/components/Panel/Panel.d.ts

@@ -0,0 +1,123 @@
+import React from "react";
+import type { PropsWithSpread } from "../../types";
+import type { ComponentType, ElementType, HTMLProps, PropsWithChildren, ReactNode } from "react";
+import type { ExclusiveProps } from "../../types";
+export type LogoDefaultElement = HTMLProps<HTMLAnchorElement>;
+type PanelLogo<L = LogoDefaultElement> = ReactNode | PropsWithSpread<{
+    /**
+     * The url of the icon image.
+     */
+    icon: string;
+    /**
+     * The alt text for the icon image.
+     */
+    iconAlt?: string;
+    /**
+     * The url of the name image.
+     */
+    name: string;
+    /**
+     * The alt text for the name image.
+     */
+    nameAlt?: string;
+    /**
+     * The element or component to use for displaying the logo e.g. `a` or `NavLink`.
+     * @default a
+     */
+    component?: ElementType | ComponentType<L>;
+}, L>;
+type PanelToggle = {
+    /**
+     * The panel toggle label.
+     */
+    label: string;
+    /**
+     * The function to call when clicking the panel toggle.
+     */
+    onClick: () => void;
+};
+type LogoProps<L = LogoDefaultElement> = {
+    /**
+     * The panel logo content or attributes.
+     */
+    logo?: PanelLogo<L>;
+};
+type TitleProps = {
+    /**
+     * The panel title.
+     */
+    title: ReactNode;
+    /**
+     * Classes to apply to the title element.
+     */
+    titleClassName?: string;
+    /**
+     * The element to use for the panel title e.g. `h1`.
+     * @default h4
+     */
+    titleComponent?: ElementType;
+    /**
+     * An ID for the title element.
+     */
+    titleId?: string;
+};
+type HeaderProps<L = LogoDefaultElement> = ExclusiveProps<{
+    /**
+     * This prop can be used to replace the header area of the panel when the default implementation is not sufficient.
+     */
+    header: ReactNode;
+}, {
+    /**
+     * Content that will be displayed in the controls area.
+     */
+    controls?: ReactNode;
+    /**
+     * Classes that will be applied to the controls element.
+     */
+    controlsClassName?: string;
+    /**
+     * Whether the header should be sticky.
+     */
+    stickyHeader?: boolean;
+    /**
+     * The panel toggle attributes.
+     */
+    toggle?: PanelToggle;
+} & ExclusiveProps<LogoProps<L>, TitleProps>>;
+export type Props<L = LogoDefaultElement> = {
+    /**
+     * The panel content.
+     */
+    children?: PropsWithChildren["children"];
+    /**
+     * Classes that are applied to the content container (when using `wrapContent`).
+     */
+    contentClassName?: string | null;
+    /**
+     * Classes that are applied to the top level panel element.
+     */
+    className?: string | null;
+    /**
+     * Whether to use the dark theme.
+     */
+    dark?: boolean;
+    /**
+     * Whether the panel should wrap the content in the `p-panel__content` element.
+     * @default true
+     */
+    wrapContent?: boolean;
+    /**
+     * A ref to pass to the top level panel element.
+     */
+    forwardRef?: React.Ref<HTMLDivElement> | null;
+} & HeaderProps<L>;
+/**
+ * This is a [React](https://reactjs.org/) component for panels in the
+ * [Vanilla](https://vanillaframework.io/docs/) layouts.
+ *
+ * The Panel component can be used in many areas of the application layout. It
+ * can be the child element of `AppAside`, `AppMain`, `AppNavigation`, `AppNavigationBar`
+ * and `AppStatus`.
+ */
+declare const Panel: <L = LogoDefaultElement>({ forwardRef, children, className, contentClassName, controlsClassName, controls, dark, header, logo, stickyHeader, title, titleClassName, titleComponent: TitleComponent, titleId, toggle, wrapContent, ...props }: Props<L>) => React.JSX.Element;
+export default Panel;

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

@@ -0,0 +1 @@
+export { default, type Props as PanelProps, type LogoDefaultElement as PanelLogoDefaultElement, } from "./Panel";