@canonical/react-components 1.3.0 → 1.3.1

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

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

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

@@ -0,0 +1,108 @@
+import React from "react";
+import type { InputHTMLAttributes, ReactNode } from "react";
+import type { ClassName, PropsWithSpread } from "../../types";
+export declare enum Label {
+    Hide = "Hide",
+    Show = "Show"
+}
+/**
+ * The props for the Password Toggle 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.
+     */
+    error?: ReactNode;
+    /**
+     * Help text to show below the field.
+     */
+    help?: ReactNode;
+    /**
+     * The id of the input.
+     */
+    id: string;
+    /**
+     * The label for the field.
+     */
+    label?: ReactNode;
+    /**
+     * Whether the field is read only.
+     */
+    readOnly?: boolean;
+    /**
+     * Whether the field is required.
+     */
+    required?: boolean;
+    /**
+     * The content for success validation.
+     */
+    success?: ReactNode;
+    /**
+     * The content for success validation.
+     */
+    type?: "submit" | "reset" | "button";
+    /**
+     * 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 [Password Toggle](https://docs.vanillaframework.io/base/forms/#password-toggle).
+ *
+ * It can be used when an input needs to obscure its value, whilst giving the user a way to reveal it if needed.
+ */
+declare const PasswordToggle: React.ForwardRefExoticComponent<{
+    /**
+     * The content for caution validation.
+     */
+    caution?: ReactNode;
+    /**
+     * Optional class(es) to pass to the input element.
+     */
+    className?: ClassName;
+    /**
+     * The content for error validation.
+     */
+    error?: ReactNode;
+    /**
+     * Help text to show below the field.
+     */
+    help?: ReactNode;
+    /**
+     * The id of the input.
+     */
+    id: string;
+    /**
+     * The label for the field.
+     */
+    label?: ReactNode;
+    /**
+     * Whether the field is read only.
+     */
+    readOnly?: boolean;
+    /**
+     * Whether the field is required.
+     */
+    required?: boolean;
+    /**
+     * The content for success validation.
+     */
+    success?: ReactNode;
+    /**
+     * The content for success validation.
+     */
+    type?: "submit" | "reset" | "button";
+    /**
+     * Optional class(es) to pass to the wrapping Field component
+     */
+    wrapperClassName?: string;
+} & Omit<React.InputHTMLAttributes<HTMLInputElement>, "className" | "error" | "label" | "id" | "type" | "readOnly" | "required" | "help" | "success" | "caution" | "wrapperClassName"> & React.RefAttributes<HTMLInputElement>>;
+export default PasswordToggle;

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

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

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

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

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

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

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

@@ -0,0 +1,19 @@
+import type { HTMLProps, ReactNode } from "react";
+import type { ClassName, PropsWithSpread } from "../../types";
+export type Props = PropsWithSpread<{
+    /**
+     * The content of the row.
+     */
+    children: ReactNode;
+    /**
+     * Optional class(es) to pass to the wrapping div element.
+     */
+    className?: ClassName;
+}, HTMLProps<HTMLDivElement>>;
+/**
+ * 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 Row: ({ children, className, ...props }: Props) => JSX.Element;
+export default Row;

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

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

package/dist-types/components/SearchAndFilter/FilterPanelSection/FilterPanelSection.d.ts

@@ -0,0 +1,25 @@
+import type { SearchAndFilterChip, SearchAndFilterData } from "../types";
+export type Props = {
+    /**
+     * The chip data to display in the panel.
+     */
+    data: SearchAndFilterData;
+    /**
+     * The current search chips.
+     */
+    searchData: SearchAndFilterChip[];
+    /**
+     * A search string.
+     */
+    searchTerm: string;
+    /**
+     * Whether the chips should be hidden.
+     */
+    sectionHidden?: boolean;
+    /**
+     * A function to toggle whether a chip is selected.
+     */
+    toggleSelected: (chip: SearchAndFilterChip) => void;
+};
+declare const FilterPanelSection: ({ data, searchData, searchTerm, sectionHidden, toggleSelected, }: Props) => JSX.Element;
+export default FilterPanelSection;

package/dist-types/components/SearchAndFilter/FilterPanelSection/index.d.ts

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

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

@@ -0,0 +1,33 @@
+import type { SearchAndFilterChip, SearchAndFilterData } from "./types";
+export declare enum Label {
+    AddFilter = "Add filter",
+    Clear = "Clear input",
+    SearchAndFilter = "Search and filter"
+}
+export type Props = {
+    /**
+     * A list of chips to initialise inside the input.
+     */
+    existingSearchData?: SearchAndFilterChip[];
+    /**
+     * The data for the filter panel.
+     */
+    filterPanelData: SearchAndFilterData[];
+    /**
+     * A function that is called when the search data changes.
+     */
+    returnSearchData: (searchData: SearchAndFilterChip[]) => void;
+    /**
+     * A function that is called when the filter panel is shown/hidden.
+     */
+    onPanelToggle?: () => void;
+    /**
+     * A function that is called when the height of the search container changes.
+     */
+    onExpandChange?: () => void;
+};
+/**
+ * This component allows searching and filtering of large datasets.
+ */
+declare const SearchAndFilter: ({ existingSearchData, filterPanelData, returnSearchData, onPanelToggle, onExpandChange, ...props }: Props) => JSX.Element;
+export default SearchAndFilter;

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

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

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

@@ -0,0 +1,11 @@
+export type SearchAndFilterChip = {
+    id?: number;
+    lead?: string;
+    quoteValue?: boolean;
+    value: string;
+};
+export type SearchAndFilterData = {
+    id: number;
+    chips?: SearchAndFilterChip[];
+    heading?: string;
+};

package/dist-types/components/SearchAndFilter/utils.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Return number of overflowing chips given a row threshold
+ * @param {array} chips - An array of chips
+ * @param {Integer} overflowRowLimit - Number of rows to show before counting
+ * overflow
+ */
+export declare const overflowingChipsCount: (chips: any, overflowRowLimit: any) => number;
+/**
+ * Check if supplied chip object already exists in searchData prop
+ * @param {Object} chip - A chip object {lead: 'foo', value: 'bar'}
+ * @param {Array} existingArr - An array of chip objects
+ */
+export declare const isChipInArray: (chip: any, existingArr: any) => any;

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

@@ -0,0 +1,63 @@
+import React, { HTMLProps } from "react";
+import type { ClassName, PropsWithSpread } from "../../types";
+export declare enum Label {
+    Clear = "Clear search field",
+    Search = "Search"
+}
+export type Props = PropsWithSpread<{
+    /**
+     * Whether autocomplete should be enabled for the search input.
+     */
+    autocomplete?: "on" | "off";
+    /**
+     * Optional classes to pass to the form element.
+     */
+    className?: ClassName;
+    /**
+     * Whether the input and buttons should be disabled.
+     */
+    disabled?: boolean;
+    /**
+     * Whether the input value will be controlled via external state.
+     */
+    externallyControlled?: boolean;
+    /**
+     * A function that will be called when the input value changes.
+     */
+    onChange?: (inputValue: string) => void;
+    /**
+     * A function that is called when the user clicks the search icon or presses enter
+     */
+    onSearch?: (inputValue: string) => void;
+    /**
+     * A function that is called when the user clicks the reset icon
+     */
+    onClear?: () => void;
+    /**
+     * A search input placeholder message.
+     */
+    placeholder?: string;
+    /**
+     * Whether the search input should lose focus when searching.
+     */
+    shouldBlurOnSearch?: boolean;
+    /**
+     * Whether the search input should receive focus after pressing the reset button
+     */
+    shouldRefocusAfterReset?: boolean;
+    /**
+     * A ref that is passed to the input element.
+     */
+    ref?: string;
+    /**
+     * The value of the search input when the state is externally controlled.
+     */
+    value?: string;
+}, HTMLProps<HTMLInputElement>>;
+/**
+ * This is a [React](https://reactjs.org/) component for the Vanilla [SearchBox](https://docs.vanillaframework.io/patterns/search-box/).
+ *
+ * Search boxes enable search functionality on a page and are typically used in a navigation bar. SearchBox elements should be wrapped within a form element that handles its own submit action.
+ */
+declare const SearchBox: React.ForwardRefExoticComponent<Omit<Props, "ref"> & React.RefAttributes<HTMLInputElement>>;
+export default SearchBox;

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

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

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

@@ -0,0 +1,71 @@
+import type { ChangeEventHandler, ReactNode, OptionHTMLAttributes, SelectHTMLAttributes } from "react";
+import type { ClassName, PropsWithSpread } from "../../types";
+type Option = OptionHTMLAttributes<HTMLOptionElement>;
+/**
+ * The props for the Select 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.
+     */
+    error?: ReactNode;
+    /**
+     * Help text to show below the field.
+     */
+    help?: ReactNode;
+    /**
+     * The id of the input.
+     */
+    id?: string | null;
+    /**
+     * The label for the field.
+     */
+    label?: ReactNode;
+    /**
+     * Optional class(es) to pass to the label component.
+     */
+    labelClassName?: string | null;
+    /**
+     * Function to run when select value changes.
+     */
+    onChange?: ChangeEventHandler<HTMLSelectElement> | null;
+    /**
+     * Array of options that the select can choose from.
+     */
+    options?: Option[] | null;
+    /**
+     * Whether the field is required.
+     */
+    required?: boolean;
+    /**
+     * Whether the form field should have a stacked appearance.
+     */
+    stacked?: boolean;
+    /**
+     * The content for success validation.
+     */
+    success?: ReactNode;
+    /**
+     * Whether to focus on the input on initial render.
+     */
+    takeFocus?: boolean;
+    /**
+     * Optional class(es) to pass to the wrapping Field component
+     */
+    wrapperClassName?: ClassName;
+}, SelectHTMLAttributes<HTMLSelectElement>>;
+/**
+ * This is a [React](https://reactjs.org/) component for the Vanilla [Select](https://docs.vanillaframework.io/base/forms/#select).
+ *
+ * Use the Select component to create a drop-down list.
+ */
+declare const Select: ({ caution, className, error, help, id, label, labelClassName, onChange, options, required, stacked, success, takeFocus, wrapperClassName, ...selectProps }: Props) => JSX.Element;
+export default Select;

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

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

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

@@ -0,0 +1,50 @@
+import React, { PropsWithChildren, ReactNode } from "react";
+import type { PropsWithSpread } from "../../types";
+import { type HTMLProps } from "react";
+import type { SideNavigationItemProps } from "./SideNavigationItem";
+import type { SideNavigationLinkDefaultElement, SideNavigationLinkProps } from "./SideNavigationLink";
+export type NavItem<L = SideNavigationLinkDefaultElement> = SideNavigationItemProps<L> | ReactNode | null;
+export type NavItemGroup<L = SideNavigationLinkDefaultElement> = NavItem<L>[];
+export type NavGroup<L = SideNavigationLinkDefaultElement> = PropsWithSpread<{
+    /**
+     * The navigation items.
+     */
+    items: NavItemGroup<L>;
+}, HTMLProps<HTMLUListElement>>;
+export type Props<L = SideNavigationLinkDefaultElement> = PropsWithSpread<{
+    /**
+     * The navigation content. This can be used instead of supplying `items`.
+     */
+    children?: PropsWithChildren["children"];
+    /**
+     * Whether to use the dark theme.
+     */
+    dark?: boolean;
+    /**
+     * Whether the navigation items contain icons.
+     */
+    hasIcons?: boolean;
+    /**
+     * The navigation items.
+     */
+    items?: (NavGroup<L> | null)[];
+    /**
+     * The component or element to use for the link elements e.g. `a` or `NavLink`.
+     * @default a
+     */
+    linkComponent?: SideNavigationLinkProps["component"];
+    /**
+     * Classes to apply to the navigation list(s).
+     */
+    listClassName?: string;
+    /**
+     * Classes to apply to the nav element.
+     */
+    navClassName?: string;
+}, HTMLProps<HTMLDivElement>>;
+/**
+ * This is a [React](https://reactjs.org/) component for side navigation, used
+ * in the [Vanilla](https://vanillaframework.io/docs/) layouts.
+ */
+declare const SideNavigation: <L = SideNavigationLinkDefaultElement>({ children, className, dark, hasIcons, items, linkComponent, listClassName, navClassName, ...props }: Props<L>) => React.JSX.Element;
+export default SideNavigation;

package/dist-types/components/SideNavigation/SideNavigationBase/SideNavigationBase.d.ts

@@ -0,0 +1,31 @@
+import React from "react";
+import type { PropsWithSpread } from "../../../types";
+import type { ComponentType, ElementType, ReactNode } from "react";
+export type Props<C> = PropsWithSpread<{
+    /**
+     * The component or element to use for the element e.g. `span` or `NavLink`.
+     */
+    component: ElementType | ComponentType<C>;
+    /**
+     * Whether to use the dark theme.
+     */
+    dark?: boolean;
+    /**
+     * The navigation item's icon.
+     */
+    icon?: string;
+    /**
+     * The navigation item's label.
+     */
+    label: ReactNode;
+    /**
+     * The navigation item's status.
+     */
+    status?: ReactNode;
+    /**
+     * A ref to pass to the element.
+     */
+    forwardRef?: React.Ref<C> | null;
+}, C>;
+declare const SideNavigationBase: <C>({ component: Component, dark, icon, label, status, forwardRef, ...props }: Props<C>) => React.JSX.Element;
+export default SideNavigationBase;

package/dist-types/components/SideNavigation/SideNavigationBase/index.d.ts

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

package/dist-types/components/SideNavigation/SideNavigationItem/SideNavigationItem.d.ts

@@ -0,0 +1,20 @@
+import React from "react";
+import type { HTMLProps, PropsWithChildren } from "react";
+import type { SideNavigationLinkProps } from "../SideNavigationLink";
+import type { SideNavigationLinkDefaultElement } from "../SideNavigationLink";
+import { SideNavigationTextProps } from "../SideNavigationText";
+type ItemProps = {
+    /**
+     * The item content.
+     */
+    children: NonNullable<PropsWithChildren["children"]>;
+} & HTMLProps<HTMLLIElement>;
+type ContentProps<L = SideNavigationLinkDefaultElement> = SideNavigationLinkProps<L> | (SideNavigationTextProps & {
+    /**
+     * Whether this should be a content-only item.
+     */
+    nonInteractive: true;
+});
+export type Props<L = SideNavigationLinkDefaultElement> = ItemProps | ContentProps<L>;
+declare const SideNavigationItem: <L = SideNavigationLinkDefaultElement>(props: Props<L>) => React.JSX.Element;
+export default SideNavigationItem;

package/dist-types/components/SideNavigation/SideNavigationItem/index.d.ts

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

package/dist-types/components/SideNavigation/SideNavigationLink/SideNavigationLink.d.ts

@@ -0,0 +1,18 @@
+import React from "react";
+import type { HTMLProps } from "react";
+import type { SideNavigationBaseProps } from "../SideNavigationBase";
+import { PropsWithSpread } from "../../../types";
+export type LinkDefaultElement = HTMLProps<HTMLAnchorElement>;
+export type Props<L = LinkDefaultElement, E = HTMLAnchorElement> = PropsWithSpread<{
+    /**
+     * The component or element to use for the link element e.g. `a` or `NavLink`.
+     * @default a
+     */
+    component?: SideNavigationBaseProps<L>["component"];
+    /**
+     * A ref to pass to the link element.
+     */
+    forwardRef?: React.Ref<E> | null;
+}, Omit<SideNavigationBaseProps<L>, "component">>;
+declare const SideNavigationLink: <L = LinkDefaultElement, E = HTMLAnchorElement>({ component, forwardRef, ...props }: Props<L, E>) => React.JSX.Element;
+export default SideNavigationLink;

package/dist-types/components/SideNavigation/SideNavigationLink/index.d.ts

@@ -0,0 +1 @@
+export { default, type LinkDefaultElement as SideNavigationLinkDefaultElement, type Props as SideNavigationLinkProps, } from "./SideNavigationLink";

package/dist-types/components/SideNavigation/SideNavigationText/SideNavigationText.d.ts

@@ -0,0 +1,7 @@
+import React from "react";
+import type { HTMLProps } from "react";
+import type { SideNavigationBaseProps } from "../SideNavigationBase";
+export type TextDefaultElement = HTMLProps<HTMLSpanElement>;
+export type Props = Omit<SideNavigationBaseProps<TextDefaultElement>, "component" | "label">;
+declare const SideNavigationText: ({ children, className, ...props }: Props) => React.JSX.Element;
+export default SideNavigationText;

package/dist-types/components/SideNavigation/SideNavigationText/index.d.ts

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

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

@@ -0,0 +1,5 @@
+export { default } from "./SideNavigation";
+export type { Props as SideNavigationProps } from "./SideNavigation";
+export { default as SideNavigationItem } from "./SideNavigationItem";
+export { default as SideNavigationText } from "./SideNavigationText";
+export { default as SideNavigationLink, type SideNavigationLinkDefaultElement, } from "./SideNavigationLink";