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

package/src/components/sidebarNav/types.ts

@@ -0,0 +1,126 @@
+import type { IconName } from 'Components/icon/allowedIcons';
+import type { Icon } from 'Components/icon/Icon';
+import type { AnchorHTMLAttributes } from 'react';
+
+export type SidebarNavLinkProps = Omit<
+  AnchorHTMLAttributes<HTMLAnchorElement>,
+  'href' | 'children' | 'className'
+> & Record<`data-${string}`, string | number | boolean | undefined>;
+
+export type SidebarNavRenderLinkArgs = {
+  href: string;
+  className: string;
+  children: React.ReactNode;
+  ariaCurrent?: 'page';
+  ariaLabel?: string;
+  onClick?: React.MouseEventHandler;
+  linkProps?: SidebarNavLinkProps;
+  linkElementProps?: Omit<
+    AnchorHTMLAttributes<HTMLAnchorElement>,
+    'href' | 'className' | 'children'
+  >;
+};
+
+type SidebarNavItemNodeFavouriteFields
+  = | { canFavourite?: false; favouriteTooltip?: never }
+    | { canFavourite: true; favouriteTooltip: string };
+
+type SidebarNavItemNodeLinkFields = {
+  href: string;
+  onClick?: React.MouseEventHandler;
+};
+
+type SidebarNavItemNodeButtonFields = {
+  href?: never;
+  onClick: React.MouseEventHandler;
+};
+
+export type SidebarNavItemNode = {
+  type: 'item';
+  id: string;
+  label: string;
+  current?: boolean;
+  linkProps?: SidebarNavLinkProps;
+  isPressed?: boolean;
+  onFavouriteClick?: React.MouseEventHandler<HTMLButtonElement>;
+} & SidebarNavItemNodeFavouriteFields
+& (SidebarNavItemNodeLinkFields | SidebarNavItemNodeButtonFields);
+
+export type SidebarNavGroupNode = {
+  type: 'group';
+  id: string;
+  label: string;
+  children: SidebarNavNode[];
+  defaultExpanded?: boolean;
+  expanded?: boolean;
+  onExpandedChange?: (expanded: boolean) => void;
+};
+
+export type SidebarNavNode = SidebarNavItemNode | SidebarNavGroupNode;
+
+export type SidebarNavRailSeparatorConfig = {
+  type: 'separator';
+  id: string;
+};
+
+export type SidebarNavIconColor = Icon.Props['color'];
+
+type SidebarNavRailItemBase = {
+  type?: 'item';
+  id: string;
+  label: string;
+  onClick?: React.MouseEventHandler<HTMLButtonElement | HTMLAnchorElement>;
+};
+
+export type SidebarNavRailItemStandard = SidebarNavRailItemBase & {
+  iconName: IconName;
+  href?: string;
+  current?: boolean;
+  badgeContent?: React.ReactNode;
+  iconColor?: SidebarNavIconColor;
+  renderItem?: never;
+  opensPanel?: false;
+};
+
+export type SidebarNavRailItemPanelTrigger = SidebarNavRailItemBase & {
+  opensPanel: true;
+  iconName: IconName;
+  iconColor?: SidebarNavIconColor;
+  renderItem?: never;
+  href?: never;
+  badgeContent?: never;
+  current?: never;
+};
+
+export type SidebarNavRailItemCustom = SidebarNavRailItemBase & {
+  renderItem: (item: SidebarNavRailItemCustom) => React.ReactNode;
+  iconName?: never;
+  iconColor?: never;
+  href?: never;
+  opensPanel?: never;
+  badgeContent?: never;
+  current?: never;
+};
+
+export type SidebarNavRailItemConfig
+  = | SidebarNavRailItemStandard
+    | SidebarNavRailItemPanelTrigger
+    | SidebarNavRailItemCustom;
+
+export type SidebarNavRailEntry = SidebarNavRailItemConfig | SidebarNavRailSeparatorConfig;
+
+export function isSidebarNavRailSeparator(
+  entry: SidebarNavRailEntry,
+): entry is SidebarNavRailSeparatorConfig {
+  return 'type' in entry && entry.type === 'separator';
+}
+
+export type SidebarNavProps = {
+  expanded?: boolean;
+  defaultExpanded?: boolean;
+  onExpandedChange?: (expanded: boolean) => void;
+  renderLink?: (args: SidebarNavRenderLinkArgs) => React.ReactElement;
+  railItems?: SidebarNavRailEntry[];
+  panelTitle?: string;
+  panelNavItems?: SidebarNavNode[];
+} & React.HTMLAttributes<HTMLDivElement>;

package/src/components/sidebarNav/useControllableBoolean.ts

@@ -0,0 +1,20 @@
+import { useCallback, useMemo, useState } from 'react';
+
+export function useControllableBoolean(args: {
+  value?: boolean;
+  defaultValue: boolean;
+  onChange?: (next: boolean) => void;
+}) {
+  const { value, defaultValue, onChange } = args;
+  const [uncontrolled, setUncontrolled] = useState(defaultValue);
+  const isControlled = typeof value === 'boolean';
+
+  const current = isControlled ? (value as boolean) : uncontrolled;
+
+  const set = useCallback((next: boolean) => {
+    if (!isControlled) setUncontrolled(next);
+    onChange?.(next);
+  }, [isControlled, onChange]);
+
+  return useMemo(() => ({ value: current, set }), [current, set]);
+}

package/src/index.scss

@@ -55,6 +55,7 @@
 @use "components/toggle/toggle.scss";
 @use "components/dataViewCard/dataViewCard.scss";
 @use "components/treeRow/treeRow.scss";
+@use "components/sidebarNav/sidebarNav.scss";
 
 // stylelint-disable-next-line at-rule-disallowed-list -- plain CSS import (font face), exempt from Sass @import deprecation
 @import "https://fonts.googleapis.com/css2?family=Inter:ital,opsz,wght@0,14..32,100..900;1,14..32,100..900&display=swap";

package/src/index.ts

@@ -46,6 +46,18 @@ export { Row } from 'Components/row/Row';
 export { SearchBar } from 'Components/searchBar/SearchBar';
 export { Section } from 'Components/section/Section';
 export { Separator } from 'Components/separator/Separator';
+export { SidebarNav } from 'Components/sidebarNav/SidebarNav';
+export type {
+  SidebarNavProps,
+  SidebarNavNode,
+  SidebarNavGroupNode,
+  SidebarNavItemNode,
+  SidebarNavRailItemConfig,
+  SidebarNavRailEntry,
+  SidebarNavRailSeparatorConfig,
+  SidebarNavRenderLinkArgs,
+} from 'Components/sidebarNav/types';
+export { isSidebarNavRailSeparator } from 'Components/sidebarNav/types';
 export { SingleUser } from 'Components/singleUser/SingleUser';
 export { Slideover } from 'Components/slideover/Slideover';
 export { SlideoverManager } from 'Components/slideoverManager/SlideoverManager';

package/src/tokens.scss

@@ -966,6 +966,20 @@
   --section-subsection-heading-spacing-horizontal: var(--spacing-small);
   --section-subsection-spacing-vertical: var(--spacing-small);
   --sidebar-bg: var(--color-mono-white);
+  --sidebar-nav-rail-width: 3.625rem;
+  --sidebar-nav-rail-item-size: 2.625rem;
+  --sidebar-nav-rail-item-color-icon: var(--color-grey-600);
+  --sidebar-nav-rail-item-color-icon-hover: var(--color-grey-900);
+  --sidebar-nav-rail-item-color-background-hover: var(--color-grey-050);
+  --sidebar-nav-rail-item-color-icon-selected: var(--color-brand-600);
+  --sidebar-nav-rail-item-color-background-selected: var(--color-brand-050);
+  --sidebar-nav-panel-width: 14.375rem;
+  --sidebar-nav-panel-gap: 0.125rem;
+  --sidebar-nav-title-min-height: 3.875rem;
+  --sidebar-nav-title-padding-block: var(--spacing-xsmall);
+  --sidebar-nav-title-padding-inline-end: var(--spacing-large);
+  --sidebar-nav-title-padding-inline-start: 1.25rem;
+  --sidebar-nav-help-menu-min-width: 17.5rem;
   --tooltip-color-text: var(--color-mono-white);
   --tooltip-color-background: var(--color-grey-900);
   --tooltip-spacing-vertical: var(--spacing-medium);