@arbor-education/design-system.components 0.23.1 → 0.24.0

package/src/components/sidebarNav/SidebarNav.tsx

@@ -0,0 +1,230 @@
+import { Icon } from 'Components/icon/Icon';
+import classNames from 'classnames';
+import { Tooltip as TooltipPrimitive } from 'radix-ui';
+import React, { useId, useMemo } from 'react';
+import { SidebarNavProvider } from './SidebarNavContext.js';
+import { SidebarNavGroup } from './SidebarNavGroup.js';
+import type { SidebarNavGroupProps } from './SidebarNavGroup.js';
+import { SidebarNavItem } from './SidebarNavItem.js';
+import type { SidebarNavItemProps } from './SidebarNavItem.js';
+import { SidebarNavPanelNav } from './SidebarNavPanelNav.js';
+import type { SidebarNavPanelNavProps } from './SidebarNavPanelNav.js';
+import { SidebarNavPanel } from './SidebarNavPanel.js';
+import type { SidebarNavPanelProps } from './SidebarNavPanel.js';
+import { SidebarNavRail } from './SidebarNavRail.js';
+import type { SidebarNavRailProps } from './SidebarNavRail.js';
+import { SidebarNavRailItem } from './SidebarNavRailItem.js';
+import type { SidebarNavRailItemProps } from './SidebarNavRailItem.js';
+import { SidebarNavRailList } from './SidebarNavRailList.js';
+import { SidebarNavRailSlot } from './SidebarNavRailSlot.js';
+import { SidebarNavSeparator } from './SidebarNavSeparator.js';
+import { SidebarNavTitle } from './SidebarNavTitle.js';
+import { SidebarNavTrigger } from './SidebarNavTrigger.js';
+import type { SidebarNavTriggerProps } from './SidebarNavTrigger.js';
+import type {
+  SidebarNavProps,
+  SidebarNavRailEntry,
+  SidebarNavRailItemConfig,
+} from './types.js';
+import { isSidebarNavRailSeparator } from './types.js';
+import { useControllableBoolean } from './useControllableBoolean.js';
+
+function renderRailListItem(item: SidebarNavRailItemConfig) {
+  if (item.renderItem) {
+    return (
+      <React.Fragment key={item.id}>
+        {item.renderItem(item)}
+      </React.Fragment>
+    );
+  }
+
+  return (
+    <SidebarNavRailItem
+      key={item.id}
+      data-testid={`sidebar-nav-rail-item-${item.id}`}
+      href={item.href}
+      onClick={item.onClick}
+      current={item.current}
+      aria-label={item.label}
+    >
+      <Icon name={item.iconName} size={24} color={item.iconColor} />
+      {item.badgeContent}
+    </SidebarNavRailItem>
+  );
+}
+
+function SidebarNavRailFromData(props: { items: SidebarNavRailEntry[] }) {
+  const { items } = props;
+  const nodes: React.ReactNode[] = [];
+  let currentGroup: SidebarNavRailItemConfig[] = [];
+  let groupKey = 'rail-list-leading';
+
+  const flushGroup = () => {
+    if (currentGroup.length === 0) {
+      return;
+    }
+
+    nodes.push(
+      <SidebarNavRailList key={groupKey}>
+        {currentGroup.map(renderRailListItem)}
+      </SidebarNavRailList>,
+    );
+    currentGroup = [];
+  };
+
+  for (const entry of items) {
+    if (isSidebarNavRailSeparator(entry)) {
+      flushGroup();
+      nodes.push(<SidebarNavSeparator key={entry.id} id={entry.id} />);
+      groupKey = `rail-list-after-${entry.id}`;
+      continue;
+    }
+
+    if (entry.opensPanel) {
+      flushGroup();
+      nodes.push(
+        <SidebarNavTrigger
+          key={entry.id}
+          data-testid={`sidebar-nav-panel-trigger-${entry.id}`}
+          tooltip={entry.label}
+          onClick={(e) => {
+            entry.onClick?.(e);
+          }}
+        >
+          <Icon name={entry.iconName} size={24} color={entry.iconColor} />
+        </SidebarNavTrigger>,
+      );
+      continue;
+    }
+
+    currentGroup.push(entry);
+  }
+
+  flushGroup();
+
+  return (
+    <SidebarNavRail>
+      {nodes}
+    </SidebarNavRail>
+  );
+}
+
+const SidebarNavImpl = (props: SidebarNavProps) => {
+  const {
+    expanded,
+    defaultExpanded = true,
+    onExpandedChange,
+    renderLink,
+    railItems,
+    panelTitle,
+    panelNavItems,
+    className,
+    children,
+    ...rest
+  } = props;
+
+  const panelId = useId();
+  const { value: isExpanded, set: setExpanded } = useControllableBoolean({
+    value: expanded,
+    defaultValue: defaultExpanded,
+    onChange: onExpandedChange,
+  });
+
+  const useDataRail = railItems !== undefined;
+  const useDataPanel = panelTitle !== undefined || panelNavItems !== undefined;
+  const childArray = React.Children.toArray(children) as React.ReactElement[];
+  const railChild = childArray.find(c => c.type === SidebarNavRail);
+  const panelChild = childArray.find(c => c.type === SidebarNavPanel);
+
+  if (process.env.NODE_ENV !== 'production') {
+    if (useDataPanel && !useDataRail && railChild == null && childArray.length > 0) {
+      console.warn(
+        'SidebarNav: composable SidebarNav.Rail was not found. In hybrid mode, SidebarNav.Rail must be a direct child of SidebarNav (not wrapped in Fragment or other wrappers).',
+      );
+    }
+  }
+
+  const content
+    = useDataRail || useDataPanel
+      ? (
+          <>
+            {useDataRail
+              ? <SidebarNavRailFromData items={railItems} />
+              : railChild}
+            {useDataPanel
+              ? (
+                  <SidebarNavPanel>
+                    {panelTitle !== undefined && (
+                      <SidebarNavTitle>{panelTitle}</SidebarNavTitle>
+                    )}
+                    <SidebarNavPanelNav items={panelNavItems ?? []} />
+                  </SidebarNavPanel>
+                )
+              : panelChild}
+          </>
+        )
+      : children;
+
+  const contextValue = useMemo(
+    () => ({
+      expanded: isExpanded,
+      setExpanded,
+      panelId,
+      renderLink,
+    }),
+    [isExpanded, setExpanded, panelId, renderLink],
+  );
+
+  return (
+    <TooltipPrimitive.Provider delayDuration={400}>
+      <SidebarNavProvider value={contextValue}>
+        <div
+          className={classNames('ds-sidebar-nav', className)}
+          data-testid="sidebar-nav"
+          {...rest}
+        >
+          {content}
+        </div>
+      </SidebarNavProvider>
+    </TooltipPrimitive.Provider>
+  );
+};
+
+type SidebarNavComponent = typeof SidebarNavImpl & {
+  Rail: typeof SidebarNavRail;
+  Separator: typeof SidebarNavSeparator;
+  RailList: typeof SidebarNavRailList;
+  RailItem: typeof SidebarNavRailItem;
+  RailSlot: typeof SidebarNavRailSlot;
+  Trigger: typeof SidebarNavTrigger;
+  Panel: typeof SidebarNavPanel;
+  Title: typeof SidebarNavTitle;
+  PanelNav: typeof SidebarNavPanelNav;
+  Group: typeof SidebarNavGroup;
+  Item: typeof SidebarNavItem;
+};
+
+export const SidebarNav = SidebarNavImpl as SidebarNavComponent;
+
+SidebarNav.Rail = SidebarNavRail;
+SidebarNav.Separator = SidebarNavSeparator;
+SidebarNav.RailList = SidebarNavRailList;
+SidebarNav.RailItem = SidebarNavRailItem;
+SidebarNav.RailSlot = SidebarNavRailSlot;
+SidebarNav.Trigger = SidebarNavTrigger;
+SidebarNav.Panel = SidebarNavPanel;
+SidebarNav.Title = SidebarNavTitle;
+SidebarNav.PanelNav = SidebarNavPanelNav;
+SidebarNav.Group = SidebarNavGroup;
+SidebarNav.Item = SidebarNavItem;
+
+export namespace SidebarNav {
+  export type Props = SidebarNavProps;
+  export type RailProps = SidebarNavRailProps;
+  export type RailItemProps = SidebarNavRailItemProps;
+  export type TriggerProps = SidebarNavTriggerProps;
+  export type PanelProps = SidebarNavPanelProps;
+  export type PanelNavProps = SidebarNavPanelNavProps;
+  export type GroupProps = SidebarNavGroupProps;
+  export type ItemProps = SidebarNavItemProps;
+}

package/src/components/sidebarNav/SidebarNavContext.tsx

@@ -0,0 +1,28 @@
+import { createContext, useContext } from 'react';
+import type { SidebarNavRenderLinkArgs } from './types.js';
+
+export type SidebarNavContextValue = {
+  expanded: boolean;
+  setExpanded: (expanded: boolean) => void;
+  panelId: string;
+  renderLink?: (args: SidebarNavRenderLinkArgs) => React.ReactElement;
+};
+
+const SidebarNavContext = createContext<SidebarNavContextValue | null>(null);
+
+export function SidebarNavProvider(props: { value: SidebarNavContextValue; children: React.ReactNode }) {
+  const { value, children } = props;
+  return (
+    <SidebarNavContext.Provider value={value}>
+      {children}
+    </SidebarNavContext.Provider>
+  );
+}
+
+export function useSidebarNavContext() {
+  const ctx = useContext(SidebarNavContext);
+  if (!ctx) {
+    throw new Error('SidebarNav components must be used within <SidebarNav>.');
+  }
+  return ctx;
+}

package/src/components/sidebarNav/SidebarNavGroup.tsx

@@ -0,0 +1,59 @@
+import { Icon } from 'Components/icon/Icon';
+import classNames from 'classnames';
+import type { HTMLAttributes } from 'react';
+import { useId } from 'react';
+import { useControllableBoolean } from './useControllableBoolean.js';
+
+export type SidebarNavGroupProps = {
+  label: string;
+  expanded?: boolean;
+  defaultExpanded?: boolean;
+  onExpandedChange?: (expanded: boolean) => void;
+  children: React.ReactNode;
+} & Omit<HTMLAttributes<HTMLLIElement>, 'children'>;
+
+export const SidebarNavGroup = (props: SidebarNavGroupProps) => {
+  const {
+    label,
+    expanded,
+    defaultExpanded = false,
+    onExpandedChange,
+    className,
+    children,
+    ...rest
+  } = props;
+
+  const ulId = useId();
+  const { value: isExpanded, set: setExpanded } = useControllableBoolean({
+    value: expanded,
+    defaultValue: defaultExpanded,
+    onChange: onExpandedChange,
+  });
+
+  return (
+    <li className={classNames('ds-sidebar-nav__list-item', 'ds-sidebar-nav__group', className)} {...rest}>
+      <button
+        type="button"
+        className="ds-sidebar-nav__group-link"
+        aria-expanded={isExpanded}
+        aria-controls={ulId}
+        onClick={() => setExpanded(!isExpanded)}
+      >
+        <Icon
+          name="chevron-right"
+          size={16}
+          className="ds-sidebar-nav__group-chevron"
+        />
+        <span className="ds-sidebar-nav__group-label">{label}</span>
+      </button>
+
+      <ul
+        id={ulId}
+        aria-hidden={!isExpanded}
+        className="ds-sidebar-nav__group-children"
+      >
+        {children}
+      </ul>
+    </li>
+  );
+};

package/src/components/sidebarNav/SidebarNavItem.tsx

@@ -0,0 +1,160 @@
+import classNames from 'classnames';
+import type {
+  AnchorHTMLAttributes,
+  ButtonHTMLAttributes,
+  HTMLAttributes,
+  MouseEventHandler,
+} from 'react';
+import { useSidebarNavContext } from './SidebarNavContext.js';
+import { SidebarNavItemFavourite } from './SidebarNavItemFavourite.js';
+import type { SidebarNavLinkProps } from './types.js';
+
+type SidebarNavItemFavouriteVariant
+  = | { canFavourite?: false; favouriteTooltip?: never }
+    | { canFavourite: true; favouriteTooltip: string };
+
+type SidebarNavItemLinkVariant = {
+  linkElement?: 'link';
+  href: string;
+  linkElementProps?: Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'href' | 'className' | 'children'>;
+  linkProps?: SidebarNavLinkProps;
+};
+
+type SidebarNavItemButtonVariant = {
+  linkElement: 'button';
+  href?: never;
+  linkElementProps?: ButtonHTMLAttributes<HTMLButtonElement>;
+  linkProps?: never;
+};
+
+export type SidebarNavItemProps = {
+  current?: boolean;
+  itemId: string;
+  isPressed?: boolean;
+  onFavouriteClick?: MouseEventHandler<HTMLButtonElement>;
+  onClick?: MouseEventHandler<HTMLElement>;
+  children: React.ReactNode;
+} & Omit<HTMLAttributes<HTMLLIElement>, 'children' | 'onClick'>
+& SidebarNavItemFavouriteVariant
+& (SidebarNavItemLinkVariant | SidebarNavItemButtonVariant);
+
+function omitOnClick<T extends { onClick?: MouseEventHandler<HTMLElement> }>(
+  props: T | undefined,
+): Omit<T, 'onClick'> | undefined {
+  if (props == null) {
+    return undefined;
+  }
+
+  const rest = { ...props };
+  delete rest.onClick;
+  return rest;
+}
+
+export const SidebarNavItem = (props: SidebarNavItemProps) => {
+  const {
+    current,
+    itemId,
+    canFavourite,
+    favouriteTooltip,
+    isPressed = false,
+    onFavouriteClick,
+    children,
+    className,
+    linkElement = 'link',
+    href,
+    linkElementProps,
+    linkProps,
+    onClick,
+    ...rest
+  } = props;
+
+  const { renderLink } = useSidebarNavContext();
+
+  const linkClassName = classNames(
+    'ds-sidebar-nav__item-link',
+    { 'ds-sidebar-nav__item-link--current': Boolean(current) },
+  );
+
+  const linkChildren = <span className="ds-sidebar-nav__item-label">{children}</span>;
+
+  const linkElementOnClick = linkElementProps?.onClick;
+
+  const handleClick: MouseEventHandler<HTMLElement> = (event) => {
+    if (onClick) {
+      onClick(event);
+      return;
+    }
+
+    linkElementOnClick?.(
+      event as React.MouseEvent<HTMLButtonElement> & React.MouseEvent<HTMLAnchorElement>,
+    );
+  };
+
+  const buttonLinkElementProps = omitOnClick(
+    linkElementProps as ButtonHTMLAttributes<HTMLButtonElement> | undefined,
+  );
+  const anchorLinkElementProps = omitOnClick(
+    linkElementProps as AnchorHTMLAttributes<HTMLAnchorElement> | undefined,
+  );
+
+  const linkElementNode = linkElement === 'button'
+    ? (
+        <button
+          type="button"
+          className={linkClassName}
+          aria-current={current ? 'page' : undefined}
+          {...buttonLinkElementProps}
+          onClick={handleClick as MouseEventHandler<HTMLButtonElement>}
+        >
+          {linkChildren}
+        </button>
+      )
+    : renderLink
+      ? renderLink({
+          href: href!,
+          className: linkClassName,
+          ariaCurrent: current ? 'page' : undefined,
+          linkProps,
+          linkElementProps: anchorLinkElementProps as Omit<
+            AnchorHTMLAttributes<HTMLAnchorElement>,
+            'href' | 'className' | 'children'
+          > | undefined,
+          onClick: handleClick,
+          children: linkChildren,
+        })
+      : (
+          <a
+            href={href}
+            className={linkClassName}
+            aria-current={current ? 'page' : undefined}
+            {...linkProps}
+            {...anchorLinkElementProps}
+            onClick={handleClick as MouseEventHandler<HTMLAnchorElement>}
+          >
+            {linkChildren}
+          </a>
+        );
+
+  return (
+    <li
+      className={classNames(
+        'ds-sidebar-nav__list-item',
+        'ds-sidebar-nav__item',
+        { 'ds-sidebar-nav__item--has-favourite': canFavourite },
+        className,
+      )}
+      data-testid={`sidebar-nav-panel-item-${itemId}`}
+      {...rest}
+    >
+      {linkElementNode}
+      {canFavourite === true && (
+        <SidebarNavItemFavourite
+          isPressed={isPressed}
+          itemId={itemId}
+          favouriteTooltip={favouriteTooltip}
+          onClick={onFavouriteClick}
+        />
+      )}
+    </li>
+  );
+};

package/src/components/sidebarNav/SidebarNavItemFavourite.tsx

@@ -0,0 +1,49 @@
+import { Icon } from 'Components/icon/Icon';
+import classNames from 'classnames';
+import type { ButtonHTMLAttributes } from 'react';
+import { SidebarNavTooltip } from './SidebarNavTooltip.js';
+
+export type SidebarNavItemFavouriteProps = {
+  isPressed: boolean;
+  itemId: string;
+  favouriteTooltip: string;
+} & ButtonHTMLAttributes<HTMLButtonElement>;
+
+export const SidebarNavItemFavourite = (props: SidebarNavItemFavouriteProps) => {
+  const {
+    isPressed,
+    itemId,
+    favouriteTooltip,
+    className,
+    onClick,
+    ...rest
+  } = props;
+
+  const button = (
+    <button
+      type="button"
+      className={classNames('ds-sidebar-nav__item-favourite', className)}
+      aria-pressed={isPressed}
+      aria-label={favouriteTooltip}
+      data-testid={`sidebar-nav-panel-item-favourite-${itemId}`}
+      onClick={(e) => {
+        e.preventDefault();
+        e.stopPropagation();
+        onClick?.(e);
+      }}
+      {...rest}
+    >
+      <Icon
+        name={isPressed ? 'favourite-filled' : 'favourite-outline'}
+        size={16}
+        color={isPressed ? 'var(--color-brand-600)' : 'currentColor'}
+      />
+    </button>
+  );
+
+  return (
+    <SidebarNavTooltip label={favouriteTooltip} side="left">
+      {button}
+    </SidebarNavTooltip>
+  );
+};

package/src/components/sidebarNav/SidebarNavPanel.tsx

@@ -0,0 +1,20 @@
+import classNames from 'classnames';
+import type { HTMLAttributes } from 'react';
+import { useSidebarNavContext } from './SidebarNavContext.js';
+
+export type SidebarNavPanelProps = HTMLAttributes<HTMLDivElement>;
+
+export const SidebarNavPanel = (props: SidebarNavPanelProps) => {
+  const { className, ...rest } = props;
+  const { expanded, panelId } = useSidebarNavContext();
+
+  return (
+    <div
+      id={panelId}
+      aria-hidden={!expanded}
+      className={classNames('ds-sidebar-nav__panel', className)}
+      data-testid="sidebar-nav-panel"
+      {...rest}
+    />
+  );
+};

package/src/components/sidebarNav/SidebarNavPanelNav.tsx

@@ -0,0 +1,55 @@
+import classNames from 'classnames';
+import type { HTMLAttributes } from 'react';
+import { SidebarNavGroup } from './SidebarNavGroup.js';
+import { SidebarNavItem } from './SidebarNavItem.js';
+import { resolvePanelItemProps } from './resolvePanelItemProps.js';
+import type { SidebarNavItemNode, SidebarNavNode } from './types.js';
+
+export type SidebarNavPanelNavProps = {
+  ariaLabel?: string;
+  items?: SidebarNavNode[];
+} & Omit<HTMLAttributes<HTMLElement>, 'children'> & {
+  children?: React.ReactNode;
+};
+
+function renderItemNode(node: SidebarNavItemNode) {
+  return <SidebarNavItem key={node.id} {...resolvePanelItemProps(node)} />;
+}
+
+function renderNodes(nodes: SidebarNavNode[]) {
+  return nodes.map((node) => {
+    if (node.type === 'group') {
+      return (
+        <SidebarNavGroup
+          key={node.id}
+          label={node.label}
+          defaultExpanded={node.defaultExpanded}
+          expanded={node.expanded}
+          onExpandedChange={node.onExpandedChange}
+        >
+          {renderNodes(node.children ?? [])}
+        </SidebarNavGroup>
+      );
+    }
+
+    return renderItemNode(node);
+  });
+}
+
+export const SidebarNavPanelNav = (props: SidebarNavPanelNavProps) => {
+  const {
+    ariaLabel = 'Sidebar links',
+    items,
+    className,
+    children,
+    ...rest
+  } = props;
+
+  return (
+    <nav aria-label={ariaLabel} className={classNames('ds-sidebar-nav__nav', className)} {...rest}>
+      <ul className="ds-sidebar-nav__list">
+        {items ? renderNodes(items) : children}
+      </ul>
+    </nav>
+  );
+};

package/src/components/sidebarNav/SidebarNavRail.tsx

@@ -0,0 +1,20 @@
+import classNames from 'classnames';
+import type { HTMLAttributes } from 'react';
+
+export type SidebarNavRailProps = {
+  ariaLabel?: string;
+} & HTMLAttributes<HTMLElement>;
+
+export const SidebarNavRail = (props: SidebarNavRailProps) => {
+  const { className, children, ariaLabel = 'Sidebar rail', ...rest } = props;
+  return (
+    <nav
+      aria-label={ariaLabel}
+      className={classNames('ds-sidebar-nav__rail', className)}
+      data-testid="sidebar-nav-rail"
+      {...rest}
+    >
+      {children}
+    </nav>
+  );
+};