Page Header Navigation is poorly documented

[lee-chase]

Without reading the source code it is hard to determine how the Navigation (Tabs) are added to the PageHeader.

Unfortunately the Storybook story code AddOn and the documentation page do not make this much clearer.

AddOn

({
  children,
  navigation,
  // eslint-disable-next-line no-unused-vars
  storyOptionWholePageScroll,
  title,
  ...props
}) => {
  const carbonPrefix = usePrefix();
  // eslint-disable-next-line react/prop-types
  const [titleText, setTitleText] = useState(title?.text ?? title);
  const handleTitleSave = title?.onSave ? () => {
    actionTitleSave(titleText);
  } : null;
  const handleTitleChange = title?.onChange ? val => {
    actionTitleChange(val);
    setTitleText(val);
  } : null;
  const handleTitleCancel = title?.onCancel ? val => {
    actionTitleCancel(val);
    setTitleText(val);
  } : null;

  // const [theTitle, setTheTitle] = useState({});

  // useEffect(() => {
  //   console.log('effect1', titleText);
  //   // eslint-disable-next-line react/prop-types
  //   if (title?.text) {
  //     setTheTitle({ ...title, text: titleText });
  //   } else {
  //     setTheTitle(title);
  //   }
  // }, [title, title.text]);

  // useEffect(() => {
  //   // only used if title property changes
  //   // eslint-disable-next-line react/prop-types
  //   if (title?.text) {
  //     setTheTitle({
  //       ...title,
  //       // eslint-disable-next-line react/prop-types
  //       onChange: title?.onChange && handleTitleChange,
  //     });
  //   } else {
  //     setTitleText(title);
  //   }
  // }, [title]);

  // console.log(theTitle);

  return <>
      <style>{`.${carbonPrefix}--modal { opacity: 0; }`};</style>
      <ContainerDivOrTabs className={`${storyClass}__content-container`} tabIndex={0} navigation={navigation}>
        <PageHeader {...props} {...getNavProps(navigation)} title={title?.onSave ? {
        ...title,
        text: titleText,
        onChange: handleTitleChange,
        onSave: handleTitleSave,
        onCancel: handleTitleCancel
      } : title}>
          {children}
        </PageHeader>
        <ChildrenMaybeTabPanels navigation={navigation}>
          {dummyPageContent}
        </ChildrenMaybeTabPanels>
      </ContainerDivOrTabs>
    </>;
}

Docs page

<>
  <style>
    {`.cds--modal { opacity: 0; };`}
  </style>
  <we
    className="page-header-stories__content-container"
    navigation={[
      'Tab 1',
      'Tab 2',
      'Tab 3',
      'Tab 4'
    ]}
    tabIndex={0}
  >
    <PageHeader
      actionBarItems={[
        {
          iconDescription: 'Action 1',
          key: 'a-key-1',
          label: 'Action 1',
          renderIcon: function Ua(){}
        },
        {
          iconDescription: 'Action 2',
          key: 'a-key-2',
          label: 'Action 2',
          renderIcon: function Ua(){}
        },
        {
          iconDescription: 'Action 3',
          key: 'a-key-3',
          label: 'Action 3',
          renderIcon: function Ua(){}
        },
        {
          iconDescription: 'Action 4',
          key: 'a-key-4',
          label: 'Action 4',
          renderIcon: function Ua(){}
        }
      ]}
      actionBarOverflowAriaLabel="Show further action bar items"
      allTagsModalSearchLabel="Search all tags"
      allTagsModalSearchPlaceholderText="Enter search string"
      allTagsModalTitle="All tags"
      breadcrumbOverflowAriaLabel="Open and close additional breadcrumb item list."
      breadcrumbs={[
        {
          href: '#',
          key: 'Breadcrumb 1',
          label: 'Home page'
        },
        {
          href: '#',
          key: 'Breadcrumb 2',
          label: 'Secondary page'
        }
      ]}
      collapseHeaderIconDescription="Collapse the page header"
      expandHeaderIconDescription="Expand the page header"
      navigation={<De><React.ForwardRef>Tab 1</React.ForwardRef><React.ForwardRef>Tab 2</React.ForwardRef><React.ForwardRef>Tab 3</React.ForwardRef><React.ForwardRef>Tab 4</React.ForwardRef></De>}
      pageActionsOverflowLabel="Page actions..."
      showAllTagsLabel="View all tags"
      title={{
        icon: function Ua(){},
        loading: false,
        text: 'Page title'
      }}
    />
    <Me
      navigation={[
        'Tab 1',
        'Tab 2',
        'Tab 3',
        'Tab 4'
      ]}
    >
      <G
        className="page-header-stories__dummy-content"
        narrow
      >
        <v
          className="page-header-stories__dummy-content-block"
          lg={4}
          md={2}
          sm={1}
        >
          <div className="page-header-stories__dummy-content-text">
            Column carbon-design-system/ibm-products#1
          </div>
        </v>
        <v
          className="page-header-stories__dummy-content-block"
          lg={4}
          md={2}
          sm={1}
        >
          <div className="page-header-stories__dummy-content-text">
            Column carbon-design-system/ibm-products#2
          </div>
        </v>
        <v
          className="page-header-stories__dummy-content-block"
          lg={8}
          md={4}
          sm={2}
        >
          <div className="page-header-stories__dummy-content-text">
            Column carbon-design-system/ibm-products#3
          </div>
        </v>
      </G>
    </Me>
  </we>
</>

It is much clearer to show non-constructed JSX e.g.

        <PageHeader
          title={title}
          subtitle={description}
          navigation={
            <Tabs selectedIndex={selectedTabIndex}>
              <TabList aria-label='Navigational tabs'>
                {routes
                  .filter((route) => route.path !== '/profile')
                  .map((route) => (
                    <Tab
                      key={route.path}
                      active={
                        route.path === location.pathname ? 'true' : undefined
                      }
                      onClick={() => nav(route.path)}
                    >
                      {route.label}
                    </Tab>
                  ))}
              </TabList>
            </Tabs>
          }
        ></PageHeader>

[ljcarot]

Hey @lee-chase we have just begun a Page Header 2.0 which will clean up the design, code and documentation and make PH more composable. I'm going to move this issue to backlog. Would you like to be an early adopter/evaluater of PageHeader in Q1 2025? Do you have product teams that are looking to use PH?

[mattrosno]

@lee-chase @ljcarot @elycheea we moved this from the backlog to next (not now) due to @kingtraceyj's current efforts on the v2 page header.

Epic: carbon-design-system/carbon#18530

Current issue: #6705