@arbor-education/design-system.components 0.23.2 → 0.24.1

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/docs/Contributing.mdx

@@ -205,6 +205,13 @@ Never push directly to `main` — all work goes through a branch and PR.
 - **Under 400 lines** of meaningful code change — if it's bigger, split it.
 - **Fill in the PR template** — every section, no placeholders.
 
+### Changesets
+
+- **Every PR requires a changeset.** These should be generated by running `yarn changeset`, which takes you through a prompt to specify the change level and to give a brief description of your change
+- **Do not let an AI create a changeset file for you.** AI Agents have a propensity to directly write their own changeset files, which often hallucinate the structure of the files, or the name of the changeset project, which can result in stray changeset files not being added to the changelog on releases. Generate **all** changeset files via `yarn changeset`.
+- **Do not use backticks or quotes in your changeset description** - these break the release automation
+- Until we are on v1.0.0 as our first wide release, we are not using proper semver. For the time being, use minor version bumps for breaking changes and patch for all other changes, including new functionality.
+
 For the full details and the reasoning behind these rules, see [CONTRIBUTING.md](https://github.com/arbor-education/design-system.components/blob/main/CONTRIBUTING.md) on GitHub.
 
 ---

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);