@carbon/ibm-products 2.39.0 → 2.40.0

package/lib/components/PageHeader/PageHeader.d.ts

@@ -1,6 +1,299 @@
-export let PageHeader: React.ForwardRefExoticComponent<React.RefAttributes<any>>;
-export namespace deprecatedProps {
-    let disableBreadcrumbScroll: (props: any, propName: any, comp: any, loc: any, propFullName: any, secret: any) => any;
-    let hasBackgroundAlways: (props: any, propName: any, comp: any, loc: any, propFullName: any, secret: any) => any;
+/// <reference path="../../../src/custom-typings/index.d.ts" />
+import React, { PropsWithChildren, ReactNode } from 'react';
+import { Tag } from '@carbon/react';
+import { ButtonProps, PopoverAlignment, TagProps } from '@carbon/type';
+interface ActionBarItem extends ButtonProps {
+    iconDescription: string;
+    onClick: () => void;
+    renderIcon: ReactNode;
 }
-import React from 'react';
+type Size = 'xl';
+type ActionBarOverflowAriaLabelProps = {
+    /**
+     * Specifies the action bar items which are the final items in the row top of the PageHeader.
+     * Each item is specified as an object with the properties of a Carbon Button in icon only form.
+     * Button kind, size, tooltipPosition, tooltipAlignment and type are ignored.
+     */
+    actionBarItems: ActionBarItem[];
+    /**
+     * When there is insufficient space for all actionBarItems to be displayed this
+     * aria label is used for the action bar overflow menu
+     *
+     * NOTE: This prop is required if actionBarItems are supplied
+     */
+    actionBarOverflowAriaLabel: string;
+} | {
+    actionBarItems?: never;
+    actionBarOverflowAriaLabel?: string;
+};
+type BreadcrumbLabelProps = {
+    label?: string;
+    title?: string;
+} | {
+    /**
+     * Pass in content that will be inside of the BreadcrumbItem
+     */
+    label: ReactNode | JSX.Element | (() => JSX.Element) | JSX.Element[] | ReactNode[];
+    /**
+     * A text version of the `label` for display, required if `label` is not a string.
+     */
+    title: string;
+};
+interface BreadcrumbBase {
+    /**
+     * Optional string representing the link location for the BreadcrumbItem
+     */
+    href?: string;
+    /**
+     * Provide if this breadcrumb item represents the current page
+     */
+    isCurrentPage?: boolean;
+    /**
+     * Key required to render array efficiently
+     */
+    key: string;
+}
+type Breadcrumb = BreadcrumbBase & BreadcrumbLabelProps;
+type BreadcrumbProps = {
+    /**
+     * Specifies the breadcrumb components to be shown in the breadcrumb area of
+     * the page header. Each item is specified as an object with optional fields
+     * 'label' to supply the breadcrumb label, 'href' to supply the link location,
+     * and 'isCurrentPage' to specify whether this breadcrumb component represents
+     * the current page. Each item should also include a unique 'key' field to
+     * enable efficient rendering, and if the label is not a string then a 'title'
+     * field is required to provide a text alternative for display. Any other
+     * fields in the object will be passed through to the breadcrumb element as
+     * HTML attributes.
+     */
+    breadcrumbs: Breadcrumb[];
+    /**
+     * If the user supplies breadcrumbs then this property is required.
+     * It is used in an overflow menu when there is insufficient space to display all breadcrumbs inline.
+     */
+    breadcrumbOverflowAriaLabel: string;
+} | {
+    breadcrumbs?: never;
+    breadcrumbOverflowAriaLabel?: string;
+};
+type CollapseHeaderProps = {
+    hasCollapseHeaderToggle?: false;
+    withoutBackground?: boolean;
+    collapseHeaderIconDescription?: string;
+    expandHeaderIconDescription?: string;
+} | {
+    /**
+     * Adds a button as the last element of the bottom row which collapses and expands the header.
+     *
+     * NOTE: The header is collapsed by setting the scroll position to hide part of the header.
+     * Collapsing has no effect if there is insufficient content to scroll.
+     */
+    hasCollapseHeaderToggle: true;
+    /**
+     * Specifies if the PageHeader should appear without a background color, and defaults to the preferred `false` (a background color is shown).
+     * Note that when `true` some parts of the header still gain a background if and when they stick to the top of the PageHeader on scroll.
+     */
+    withoutBackground?: false;
+    /**
+     * If `hasCollapseHeaderToggle` is set and `withoutBackground` is unset/falsy then assistive text is
+     * required for both the expend and collapse states of the button component used.
+     */
+    collapseHeaderIconDescription: string;
+    expandHeaderIconDescription: string;
+};
+interface PageAction {
+    content: ReactNode;
+    minWidth: number;
+    maxWidth: number;
+}
+type PageActionProps = {
+    /**
+     * Specifies the primary page actions which are placed at the same level in the page as the title.
+     *
+     * Either a set of actions, each specified as an object with the properties of a Carbon Button plus:
+     *
+     * - label: node
+     *
+     * Or a single object
+     *
+     * - content: content to be rendered. NOTE: must be capable of restricting itself to the space provided. This 2.5rem height ($spacing-08)
+     * and the width not used by action bar items when scrolled into toolbar.
+     * - minWidth: smallest number of pixel width the content would like. NOTE: This is not guaranteed and may be less on small viewports.
+     * - maxWidth: maximum number of pixels the content will grow to
+     * Carbon Button API https://react.carbondesignsystem.com/?path=/docs/components-button--default#component-api
+     */
+    pageActions: ButtonProps[] | PageAction;
+    /**
+     * When there is insufficient space to display all of hte page actions inline a dropdown button menu is shown,
+     * containing the page actions. This label is used as the display content of the dropdown button menu.
+     *
+     * NOTE: This prop is required if pageActions are supplied
+     */
+    pageActionsOverflowLabel: ReactNode;
+} | {
+    pageActions?: never;
+    pageActionsOverflowLabel?: ReactNode;
+};
+interface Tag extends TagProps {
+    label: string;
+}
+interface TitleIcon {
+    text: string;
+    icon?: object | (() => void);
+    loading?: boolean;
+    editableLabel?: string;
+    id?: string;
+    onCancel?: () => void;
+    onChange?: () => void;
+    onSave?: () => void;
+    cancelDescription?: string;
+    editDescription?: string;
+    saveDescription?: string;
+}
+interface TitleContent {
+    content: ReactNode;
+    breadcrumbContent?: ReactNode;
+    asText: string;
+}
+interface PageHeaderBaseProps extends PropsWithChildren {
+    /**
+     * class name applied to the action bar overflow options
+     */
+    actionBarMenuOptionsClass?: string;
+    /**
+     * When tags are supplied there may not be sufficient space to display all of the tags. This results in an overflow
+     * menu being shown. If in the overflow menu there is still insufficient space this label is used in a dialog showing
+     * all tags.
+     *
+     * **Note: Required if more than 10 tags**
+     */
+    allTagsModalSearchLabel?: string;
+    /**
+     * When tags are supplied there may not be sufficient space to display all of the tags. This results in an overflow
+     * menu being shown. If in the overflow menu there is still insufficient space this placeholder is used in a dialog
+     * showing all tags.
+     *
+     * **Note: Required if more than 10 tags**
+     */
+    allTagsModalSearchPlaceholderText?: string;
+    /**
+     * When tags are supplied there may not be sufficient space to display all of the tags. This results in an overflow
+     * menu being shown. If in the overflow menu there is still insufficient space this title is used in a dialog showing
+     * all tags.
+     *
+     * **Note: Required if more than 10 tags**
+     */
+    allTagsModalTitle?: string;
+    /**
+     * align breadcrumb overflow tooltip
+     */
+    breadcrumbOverflowTooltipAlign?: PopoverAlignment;
+    /**
+     * Specifies class(es) to be applied to the top-level PageHeader node.
+     * Optional.
+     */
+    className?: string;
+    /**
+     * The header can as a whole be collapsed, expanded or somewhere in between.
+     * This setting controls the initial value, but also takes effect on change
+     *
+     * NOTE: The header is collapsed by setting the scroll position to hide part of the header.
+     * Collapsing has no effect if there is insufficient content to scroll.
+     */
+    collapseHeader?: boolean;
+    /**
+     * The title row typically starts below the breadcrumb row. This option
+     * preCollapses it into the breadcrumb row.
+     */
+    collapseTitle?: boolean;
+    /**
+     * Standard keeps the breadcrumb on the page. This option allows the breadcrumb
+     * to scroll off
+     */
+    enableBreadcrumbScroll?: boolean;
+    /**
+     * The PageHeader is hosted in a Carbon grid, this value is passed through to the Carbon grid fullWidth prop.
+     * 'xl' is used to override the grid width setting. Can be used with narrowGrid: true to get the largest size.
+     */
+    fullWidthGrid?: boolean | Size;
+    /**
+     * The PageHeader is hosted in a Carbon grid, this value is passed through to the Carbon grid narrow prop
+     */
+    narrowGrid?: boolean;
+    /**
+     * Content for the navigation area in the PageHeader. Should
+     * be a React element that is normally a Carbon Tabs component. Optional.
+     */
+    navigation?: object;
+    /**
+     * class name applied to the page actions overflow options
+     */
+    pageActionsMenuOptionsClass?: string;
+    /**
+     * When tags are supplied there may not be sufficient space to display all of the tags. This results in an overflow
+     * menu being shown. If in the overflow menu there is still insufficient space this label is used to offer a
+     * "View all tags" option.
+     *
+     * **Note: Required if more than 10 tags**
+     */
+    showAllTagsLabel?: string;
+    /**
+     * Sitting just below the title is this optional subtitle that provides additional context to
+     * identify the current page.
+     */
+    subtitle?: ReactNode;
+    /**
+     * An array of tags to be shown as the final content in the PageHeader.
+     *
+     * Each tag is specified as an object with the following properties
+     * **label**\* (required) to supply the tag content, and properties of the the Carbon Tag component,
+     * such as **type**, **disabled**, **ref**, **className** , and any other Tag props.
+     *
+     * NOTE: **filter** is not supported. Any remaining fields in the object will be passed through to the HTML element
+     * as HTML attributes.
+     *
+     * See https://react.carbondesignsystem.com/?path=/docs/components-tag--default
+     */
+    tags?: Tag[];
+    /**
+     * An optional page title supplied as a string or object with the following attributes: text, icon, loading
+     *
+     * Can be supplied either as:
+     * - String
+     * - Object containing
+     *    - text: title string
+     *    - icon: optional icon
+     *    - loading: boolean shows loading indicator if true
+     *    - onChange: function to process the live value (React change === HTML Input)
+     *    - onSave: function to process a confirmed change
+     *    - editableLabel: label for edit required if onChange supplied
+     *    - cancelDescription: label for edit cancel button
+     *    - saveDescription: label for edit save button
+     * - Object containing user defined contents. These must fit within the area defined for the title in both main part of the header and the breadcrumb.
+     *    - content: title or name of current location shown in main part of page header
+     *    - breadcrumbContent: version of content used in the breadcrumb on scroll. If not supplied
+     *    - asText: String based representation of the title
+     */
+    title: string | TitleIcon | TitleContent;
+    /**
+     * @deprecated Property replaced by `enableBreadcrumbScroll
+     */
+    disableBreadcrumbScroll?: boolean;
+    /**
+     * @deprecated Property replaced by `withoutBackground`
+     */
+    hasBackgroundAlways?: boolean;
+}
+type PageHeaderProps = PageHeaderBaseProps & PageActionProps & CollapseHeaderProps & BreadcrumbProps & ActionBarOverflowAriaLabelProps;
+export declare let PageHeader: React.ForwardRefExoticComponent<PageHeaderProps & React.RefAttributes<HTMLDivElement>>;
+export declare const deprecatedProps: {
+    /**
+     * **Deprecated** see property `enableBreadcrumbScroll`
+     */
+    disableBreadcrumbScroll: (props: any, propName: any, comp: any, loc: any, propFullName: any, secret: any) => any;
+    /**
+     * **Deprecated** see property `withoutBackground`
+     */
+    hasBackgroundAlways: (props: any, propName: any, comp: any, loc: any, propFullName: any, secret: any) => any;
+};
+export {};