@carbon/ibm-products
Version:
Carbon for IBM Products
305 lines (304 loc) • 12.5 kB
TypeScript
import { Tag, ButtonProps, PopoverAlignment } from '@carbon/react';
import { TagProps } from '@carbon/react/lib/components/Tag/Tag';
import React, { JSX, PropsWithChildren, ReactNode } from 'react';
interface ActionBarItem extends ButtonProps<'button'> {
iconDescription: string;
onClick: () => void;
renderIcon: React.ElementType;
}
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<React.ElementType>[] | 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<React.ElementType> {
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;
tooltipAlignment?: 'top' | 'top-left' | 'top-right' | 'bottom' | 'bottom-left' | 'bottom-right' | 'left' | 'right';
}
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;
/**
* Label for the Breadcrumb component
*/
breadcrumbLabel?: string;
/**
* 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?: ReactNode;
/**
* 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
* - tooltipAlignment: position for tooltip displayed for large titles. Default to "bottom"
* - 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;
}
export 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 {};