@nordmanai/nif 0.2.4 → 0.2.8

package/registry/ui/components/nm-sidebar/nm-sidebar.tsx

@@ -0,0 +1,532 @@
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ComponentProps,
+  type CSSProperties,
+  type ReactElement,
+  type ReactNode,
+} from 'react';
+import { useRender } from '@base-ui/react/use-render';
+import { nmClass } from '../../lib/nm-class.ts';
+import {
+  NM_SIDEBAR_MOBILE_QUERY,
+  NM_SIDEBAR_PEEK_LEAVE_MS,
+  NM_SIDEBAR_SHORTCUT,
+  type NmSidebarButtonSize,
+  type NmSidebarButtonVariant,
+  type NmSidebarCollapsible,
+  type NmSidebarSide,
+  type NmSidebarState,
+  type NmSidebarVariant,
+} from '../../config/nm-sidebar.ts';
+import type { NmIconId } from '../../config/nm-icons.ts';
+import { NmChip } from '../nm-chip/nm-chip.tsx';
+import { NmDrawer, NmDrawerContent } from '../nm-drawer/nm-drawer.tsx';
+import { NmIcon } from '../nm-icon/nm-icon.tsx';
+import { NmInput } from '../nm-input/nm-input.tsx';
+import { NmKbd } from '../nm-kbd/nm-kbd.tsx';
+import { NmSeparator } from '../nm-separator/nm-separator.tsx';
+import { NmSkeleton } from '../nm-skeleton/nm-skeleton.tsx';
+import { NmSmallIconButton } from '../nm-small-icon-button/nm-small-icon-button.tsx';
+import { NordmanIconButton } from '../nordman-icon-button/nordman-icon-button.tsx';
+import { NmTooltip, NmTooltipContent, NmTooltipTrigger } from '../nm-tooltip/nm-tooltip.tsx';
+
+/** Replace the element a part renders, as Base UI does: give it an `<a>` and the part is a link. */
+type RenderProp = ReactElement | undefined;
+
+type SidebarContextValue = {
+  state: NmSidebarState;
+  open: boolean;
+  setOpen: (open: boolean) => void;
+  openMobile: boolean;
+  setOpenMobile: (open: boolean) => void;
+  isMobile: boolean;
+  toggleSidebar: () => void;
+  /** The collapsed sidebar shown in full over the page while the pointer is on it or on the toggle. */
+  peek: boolean;
+  /** Starts a peek. Nothing happens when the sidebar is open, on a phone, or when peeking is off. */
+  peekIn: (event?: { clientX: number; clientY: number }) => void;
+  /** Ends a peek after a short grace, so the pointer can travel from the toggle into the sidebar. */
+  peekOut: () => void;
+  collapsible: NmSidebarCollapsible;
+  setCollapsible: (mode: NmSidebarCollapsible) => void;
+};
+
+const SidebarContext = createContext<SidebarContextValue | null>(null);
+
+/** Where the pointer may rest without ending a peek: the sidebar, its toggle, a tooltip, or a menu opened from a row. */
+const PEEK_KEEPS = '[data-slot="sidebar"], [data-slot="sidebar-trigger"], [data-slot="tooltip-content"], [role="menu"], [role="dialog"]';
+
+/** The sidebar's state: expanded or collapsed, peeking, on a desktop or a phone, and the function that toggles it. */
+export function useSidebar(): SidebarContextValue {
+  const context = useContext(SidebarContext);
+  if (!context) {
+    throw new Error('useSidebar must be used within a NmSidebarProvider.');
+  }
+  return context;
+}
+
+function useMediaQuery(query: string): boolean {
+  const [matches, setMatches] = useState(() => (typeof window === 'undefined' ? false : window.matchMedia(query).matches));
+  useEffect(() => {
+    const list = window.matchMedia(query);
+    const on = () => setMatches(list.matches);
+    on();
+    list.addEventListener('change', on);
+    return () => list.removeEventListener('change', on);
+  }, [query]);
+  return matches;
+}
+
+export type NmSidebarProviderProps = ComponentProps<'div'> & {
+  defaultOpen?: boolean;
+  open?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  /** ⌘B / Ctrl+B toggles the sidebar. Off when several sidebars share a page. */
+  shortcut?: boolean;
+  /** On by default: resting the pointer on the toggle or on the collapsed sidebar shows it in full, over the page, until the pointer leaves. */
+  peek?: boolean;
+  /** `fill` takes the room it is given. `sm` and `lg` are fixed heights, for a sidebar shown inside a page. */
+  height?: 'fill' | 'sm' | 'lg';
+};
+
+/**
+ * Holds the open state and hands it to every part inside. Wrap the sidebar and the main area in it.
+ * The shadcn Sidebar composition, built from NIF primitives and styled by NIF tokens.
+ */
+export function NmSidebarProvider({
+  defaultOpen = true,
+  open: openProp,
+  onOpenChange,
+  shortcut = true,
+  peek: peekEnabled = true,
+  height = 'fill',
+  className,
+  style,
+  children,
+  ...props
+}: NmSidebarProviderProps): ReactNode {
+  const isMobile = useMediaQuery(NM_SIDEBAR_MOBILE_QUERY);
+  const [openMobile, setOpenMobile] = useState(false);
+  const [openState, setOpenState] = useState(defaultOpen);
+  const [peek, setPeek] = useState(false);
+  const [collapsible, setCollapsible] = useState<NmSidebarCollapsible>('offcanvas');
+  const leaveTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const pointer = useRef<{ x: number; y: number } | null>(null);
+  const open = openProp ?? openState;
+  const setOpen = useCallback(
+    (next: boolean) => {
+      onOpenChange?.(next);
+      if (openProp == null) {
+        setOpenState(next);
+      }
+      setPeek(false);
+    },
+    [onOpenChange, openProp],
+  );
+  const toggleSidebar = useCallback(() => {
+    if (isMobile) {
+      setOpenMobile((value) => !value);
+    } else {
+      setOpen(!open);
+    }
+  }, [isMobile, open, setOpen]);
+  const clearLeave = () => {
+    if (leaveTimer.current != null) {
+      clearTimeout(leaveTimer.current);
+      leaveTimer.current = null;
+    }
+  };
+  const peekIn = useCallback(
+    (event?: { clientX: number; clientY: number }) => {
+      clearLeave();
+      if (event) {
+        pointer.current = { x: event.clientX, y: event.clientY };
+      }
+      if (peekEnabled && !open && !isMobile && collapsible !== 'none') {
+        setPeek(true);
+      }
+    },
+    [peekEnabled, open, isMobile, collapsible],
+  );
+  const pointerInside = () => {
+    const at = pointer.current;
+    if (at == null) {
+      return false;
+    }
+    return document.elementFromPoint(at.x, at.y)?.closest(PEEK_KEEPS) != null;
+  };
+  const peekOut = useCallback(() => {
+    clearLeave();
+    leaveTimer.current = setTimeout(() => {
+      leaveTimer.current = null;
+      if (!pointerInside()) {
+        setPeek(false);
+      }
+    }, NM_SIDEBAR_PEEK_LEAVE_MS);
+  }, []);
+  useEffect(() => clearLeave, []);
+  // While peeking, the pointer's position decides, not boundary events: the panel opening under a still pointer
+  // moves the toggle out from under it, and a menu opened from a row is portaled outside the sidebar.
+  useEffect(() => {
+    if (!peek) {
+      return;
+    }
+    const onMove = (event: PointerEvent) => {
+      pointer.current = { x: event.clientX, y: event.clientY };
+      if (pointerInside()) {
+        clearLeave();
+      } else if (leaveTimer.current == null) {
+        peekOut();
+      }
+    };
+    document.addEventListener('pointermove', onMove);
+    return () => document.removeEventListener('pointermove', onMove);
+  }, [peek, peekOut]);
+
+  useEffect(() => {
+    if (!shortcut) {
+      return;
+    }
+    const onKey = (event: KeyboardEvent) => {
+      if (event.key === NM_SIDEBAR_SHORTCUT && (event.metaKey || event.ctrlKey)) {
+        event.preventDefault();
+        toggleSidebar();
+      }
+    };
+    window.addEventListener('keydown', onKey);
+    return () => window.removeEventListener('keydown', onKey);
+  }, [shortcut, toggleSidebar]);
+
+  const state: NmSidebarState = open ? 'expanded' : 'collapsed';
+  const value = useMemo<SidebarContextValue>(
+    () => ({ state, open, setOpen, openMobile, setOpenMobile, isMobile, toggleSidebar, peek: peek && !open, peekIn, peekOut, collapsible, setCollapsible }),
+    [state, open, setOpen, openMobile, isMobile, toggleSidebar, peek, peekIn, peekOut, collapsible],
+  );
+  return (
+    <SidebarContext.Provider value={value}>
+      <div data-slot="sidebar-wrapper" data-height={height} className={nmClass('nm-sidebar-provider', className)} style={style} {...props}>
+        {children}
+      </div>
+    </SidebarContext.Provider>
+  );
+}
+
+export type NmSidebarProps = ComponentProps<'div'> & {
+  side?: NmSidebarSide;
+  variant?: NmSidebarVariant;
+  collapsible?: NmSidebarCollapsible;
+  /** The accessible name of the sidebar on a phone, where it opens over the page. */
+  label?: string;
+};
+
+/**
+ * The sidebar itself. Beside the main area on a desktop, where it slides out of view, collapses to a column
+ * of icons, or collapses to its toggle alone. Over the page on a phone, in a drawer.
+ */
+export function NmSidebar({
+  side = 'left',
+  variant = 'sidebar',
+  collapsible = 'offcanvas',
+  label = 'Sidebar',
+  className,
+  children,
+  ...props
+}: NmSidebarProps): ReactNode {
+  const { isMobile, state, openMobile, setOpenMobile, peek, peekIn, peekOut, setCollapsible } = useSidebar();
+  useEffect(() => setCollapsible(collapsible), [collapsible, setCollapsible]);
+
+  if (collapsible === 'none') {
+    return (
+      <div data-slot="sidebar" data-side={side} data-variant={variant} data-collapsible="none" className={nmClass('nm-sidebar', className)} {...props}>
+        <div data-slot="sidebar-inner" className="nm-sidebar__inner">{children}</div>
+      </div>
+    );
+  }
+
+  if (isMobile) {
+    return (
+      <NmDrawer open={openMobile} onOpenChange={setOpenMobile}>
+        <NmDrawerContent data-slot="sidebar" data-mobile="" side={side} aria-label={label} className={nmClass('nm-sidebar nm-sidebar__sheet', className)}>
+          <div data-slot="sidebar-inner" className="nm-sidebar__inner">{children}</div>
+        </NmDrawerContent>
+      </NmDrawer>
+    );
+  }
+
+  const collapsed = state === 'collapsed';
+  return (
+    <div
+      data-slot="sidebar"
+      data-state={state}
+      data-collapsible={collapsed && !peek ? collapsible : ''}
+      data-mode={collapsible}
+      data-peek={collapsed && peek ? '' : undefined}
+      data-variant={variant}
+      data-side={side}
+      className={nmClass('nm-sidebar', className)}
+      onPointerEnter={collapsed ? peekIn : undefined}
+      onPointerLeave={collapsed ? peekOut : undefined}
+      {...props}
+    >
+      <div data-slot="sidebar-inner" className="nm-sidebar__inner">{children}</div>
+    </div>
+  );
+}
+
+export type NmSidebarTriggerProps = Omit<ComponentProps<'button'>, 'aria-label'> & {
+  /** The accessible name. The tooltip says Open or Close by state. */
+  label?: string;
+  icon?: NmIconId;
+  /** On by default: a tooltip with the name and the ⌘B shortcut. */
+  tooltip?: boolean;
+};
+
+/** The button that opens and closes the sidebar. In the main area's bar, or in the sidebar's own header. Resting on it peeks the sidebar. */
+export function NmSidebarTrigger({ className, label, icon = 'panel-left', tooltip = true, onClick, onPointerEnter, onPointerLeave, ...props }: NmSidebarTriggerProps): ReactNode {
+  const { open, isMobile, toggleSidebar, peekIn, peekOut } = useSidebar();
+  const name = label ?? (open || isMobile ? 'Close sidebar' : 'Open sidebar');
+  const button = (
+    <NordmanIconButton
+      data-slot="sidebar-trigger"
+      glyph={icon}
+      label={name}
+      tone="quiet"
+      className={nmClass('nm-sidebar__trigger', className)}
+      onClick={(event) => {
+        onClick?.(event);
+        toggleSidebar();
+      }}
+      onPointerEnter={(event) => {
+        onPointerEnter?.(event);
+        peekIn(event);
+      }}
+      onPointerLeave={(event) => {
+        onPointerLeave?.(event);
+        peekOut();
+      }}
+      {...props}
+    />
+  );
+  if (!tooltip) {
+    return button;
+  }
+  return (
+    <NmTooltip>
+      <NmTooltipTrigger render={button} />
+      <NmTooltipContent side="bottom">
+        {name}
+        <NmKbd>⌘B</NmKbd>
+      </NmTooltipContent>
+    </NmTooltip>
+  );
+}
+
+/** A thin strip on the sidebar's edge. Clicking it toggles the sidebar. */
+export function NmSidebarRail({ className, label = 'Toggle sidebar', ...props }: ComponentProps<'button'> & { label?: string }): ReactNode {
+  const { toggleSidebar } = useSidebar();
+  return (
+    <button
+      type="button"
+      data-slot="sidebar-rail"
+      aria-label={label}
+      tabIndex={-1}
+      title={label}
+      className={nmClass('nm-sidebar__rail', className)}
+      onClick={toggleSidebar}
+      {...props}
+    />
+  );
+}
+
+/** The main area beside the sidebar. With the inset variant it is the raised card. */
+export function NmSidebarInset({ className, ...props }: ComponentProps<'main'>): ReactNode {
+  return <main data-slot="sidebar-inset" className={nmClass('nm-sidebar__inset', className)} {...props} />;
+}
+
+/** A search field in the sidebar. The NIF Input. */
+export function NmSidebarInput({ className, ...props }: ComponentProps<typeof NmInput>): ReactNode {
+  return <NmInput data-slot="sidebar-input" className={nmClass('nm-sidebar__input', className as string)} {...props} />;
+}
+
+/** Sticky at the top: a brand, a title or a workspace switcher, and the toggle when the sidebar collapses to it. */
+export function NmSidebarHeader({ className, ...props }: ComponentProps<'div'>): ReactNode {
+  return <div data-slot="sidebar-header" className={nmClass('nm-sidebar__header', className)} {...props} />;
+}
+
+/** Sticky at the bottom: the person, settings or actions. */
+export function NmSidebarFooter({ className, ...props }: ComponentProps<'div'>): ReactNode {
+  return <div data-slot="sidebar-footer" className={nmClass('nm-sidebar__footer', className)} {...props} />;
+}
+
+/** The NIF Separator, fitted to the sidebar's padding. */
+export function NmSidebarSeparator({ className, ...props }: ComponentProps<typeof NmSeparator>): ReactNode {
+  return <NmSeparator data-slot="sidebar-separator" className={nmClass('nm-sidebar__separator', className as string)} {...props} />;
+}
+
+/** The region between the header and the footer. It scrolls. */
+export function NmSidebarContent({ className, ...props }: ComponentProps<'div'>): ReactNode {
+  return <div data-slot="sidebar-content" className={nmClass('nm-sidebar__content', className)} {...props} />;
+}
+
+/** Related navigation, with a label, an action and content. */
+export function NmSidebarGroup({ className, ...props }: ComponentProps<'div'>): ReactNode {
+  return <div data-slot="sidebar-group" className={nmClass('nm-sidebar__group', className)} {...props} />;
+}
+
+export function NmSidebarGroupLabel({ className, render, ref, ...props }: ComponentProps<'div'> & { render?: RenderProp }): ReactNode {
+  return useRender({
+    render,
+    ref,
+    defaultTagName: 'div',
+    props: { 'data-slot': 'sidebar-group-label', className: nmClass('nm-sidebar__group-label', className), ...props },
+  });
+}
+
+/** An icon button at the end of a group label, such as add. The NIF small icon button, quiet. */
+export function NmSidebarGroupAction({ className, ...props }: ComponentProps<typeof NmSmallIconButton>): ReactNode {
+  return <NmSmallIconButton data-slot="sidebar-group-action" tone="quiet" className={nmClass('nm-sidebar__group-action', className)} {...props} />;
+}
+
+export function NmSidebarGroupContent({ className, ...props }: ComponentProps<'div'>): ReactNode {
+  return <div data-slot="sidebar-group-content" className={nmClass('nm-sidebar__group-content', className)} {...props} />;
+}
+
+export function NmSidebarMenu({ className, ...props }: ComponentProps<'ul'>): ReactNode {
+  return <ul data-slot="sidebar-menu" className={nmClass('nm-sidebar__menu', className)} {...props} />;
+}
+
+export function NmSidebarMenuItem({ className, ...props }: ComponentProps<'li'>): ReactNode {
+  return <li data-slot="sidebar-menu-item" className={nmClass('nm-sidebar__menu-item', className)} {...props} />;
+}
+
+export type NmSidebarMenuButtonProps = ComponentProps<'button'> & {
+  render?: RenderProp;
+  isActive?: boolean;
+  variant?: NmSidebarButtonVariant;
+  size?: NmSidebarButtonSize;
+  /** Shown beside the icon when the sidebar is collapsed to icons. A string, or the props of the tooltip content. */
+  tooltip?: string | ComponentProps<typeof NmTooltipContent>;
+};
+
+/** A row in the menu: an icon and a label, as a button or a link. Active, disabled, three sizes and two variants. */
+export function NmSidebarMenuButton({
+  render,
+  isActive = false,
+  variant = 'default',
+  size = 'default',
+  tooltip,
+  className,
+  ref,
+  ...props
+}: NmSidebarMenuButtonProps): ReactNode {
+  const { isMobile, state, peek } = useSidebar();
+  const button = useRender({
+    render,
+    ref,
+    defaultTagName: 'button',
+    props: {
+      type: render ? undefined : 'button',
+      'data-slot': 'sidebar-menu-button',
+      'data-size': size,
+      'data-active': isActive ? '' : undefined,
+      'data-variant': variant,
+      'aria-current': isActive ? 'page' : undefined,
+      className: nmClass('nm-sidebar__menu-button', className),
+      ...props,
+    },
+  });
+  if (tooltip == null) {
+    return button;
+  }
+  const content = typeof tooltip === 'string' ? { children: tooltip } : tooltip;
+  // The tooltip exists only while the label is out of view: collapsed to icons, not peeking, not on a phone.
+  const shows = state === 'collapsed' && !peek && !isMobile;
+  return (
+    <NmTooltip>
+      <NmTooltipTrigger render={button} />
+      {shows ? <NmTooltipContent side="right" align="center" {...content} /> : null}
+    </NmTooltip>
+  );
+}
+
+/** An icon button at the end of a row, such as more. The NIF small icon button, quiet. `showOnHover` keeps it hidden until the row is hovered or focused. */
+export function NmSidebarMenuAction({ className, showOnHover = false, ...props }: ComponentProps<typeof NmSmallIconButton> & { showOnHover?: boolean }): ReactNode {
+  return (
+    <NmSmallIconButton
+      data-slot="sidebar-menu-action"
+      data-show-on-hover={showOnHover ? '' : undefined}
+      tone="quiet"
+      className={nmClass('nm-sidebar__menu-action', className)}
+      {...props}
+    />
+  );
+}
+
+/** A count or a short word at the end of a row. The NIF Chip, small. */
+export function NmSidebarMenuBadge({ className, ...props }: ComponentProps<typeof NmChip>): ReactNode {
+  return <NmChip data-slot="sidebar-menu-badge" size="sm" className={nmClass('nm-sidebar__menu-badge', className)} {...props} />;
+}
+
+/** Two lines in a row, such as a name and a plan in the footer. For a large menu button. */
+export function NmSidebarMenuText({ title, description, className, ...props }: ComponentProps<'span'> & { title: string; description?: string }): ReactNode {
+  return (
+    <span data-slot="sidebar-menu-text" className={nmClass('nm-sidebar__text', className)} {...props}>
+      <span>{title}</span>
+      {description != null ? <span>{description}</span> : null}
+    </span>
+  );
+}
+
+/** A row's shape while its content loads. The icon and the text are random widths, so a list of them reads as a list. */
+export function NmSidebarMenuSkeleton({ className, showIcon = false, ...props }: ComponentProps<'div'> & { showIcon?: boolean }): ReactNode {
+  const [width] = useState(() => `${Math.floor(Math.random() * 40) + 50}%`);
+  return (
+    <div data-slot="sidebar-menu-skeleton" className={nmClass('nm-sidebar__menu-skeleton', className)} {...props}>
+      {showIcon ? <NmSkeleton className="nm-sidebar__menu-skeleton-icon" /> : null}
+      <NmSkeleton className="nm-sidebar__menu-skeleton-text" style={{ ['--nm-sidebar-skeleton-width' as string]: width } as CSSProperties} />
+    </div>
+  );
+}
+
+/** Rows under a row, indented by a line. */
+export function NmSidebarMenuSub({ className, ...props }: ComponentProps<'ul'>): ReactNode {
+  return <ul data-slot="sidebar-menu-sub" className={nmClass('nm-sidebar__menu-sub', className)} {...props} />;
+}
+
+export function NmSidebarMenuSubItem({ className, ...props }: ComponentProps<'li'>): ReactNode {
+  return <li data-slot="sidebar-menu-sub-item" className={nmClass('nm-sidebar__menu-sub-item', className)} {...props} />;
+}
+
+export function NmSidebarMenuSubButton({
+  render,
+  size = 'default',
+  isActive = false,
+  className,
+  ref,
+  ...props
+}: ComponentProps<'a'> & { render?: RenderProp; size?: Exclude<NmSidebarButtonSize, 'lg'>; isActive?: boolean }): ReactNode {
+  return useRender({
+    render,
+    ref,
+    defaultTagName: 'a',
+    props: {
+      'data-slot': 'sidebar-menu-sub-button',
+      'data-size': size,
+      'data-active': isActive ? '' : undefined,
+      'aria-current': isActive ? 'page' : undefined,
+      className: nmClass('nm-sidebar__menu-sub-button', className),
+      ...props,
+    },
+  });
+}
+
+/** A chevron at the end of a row. In a collapsible row it points right and turns down when the row is open. With `menu` it points down, for a row that opens a menu. */
+export function NmSidebarChevron({ className, menu = false, ...props }: Omit<ComponentProps<typeof NmIcon>, 'id'> & { menu?: boolean }): ReactNode {
+  return <NmIcon id="chevron" data-menu={menu ? '' : undefined} className={nmClass('nm-sidebar__chevron', className)} {...props} />;
+}