sdaia-ui 1.0.1

package/src/components/NavBar/NavBar.variants.ts

@@ -0,0 +1,139 @@
+/**
+ * NavBar.variants.ts
+ *
+ * Token mapping from Figma node 4950-53598 (Nav Bar).
+ *
+ * ── Styles ───────────────────────────────────────────────────────────────────
+ *   default       — white bg, dark text; MenuButtonItem variant="transparent"
+ *   gray          — neutral-100 bg, dark text; MenuButtonItem variant="filled"
+ *   brand         — green bg (#1b8354), white text; all sub-components brand
+ *
+ * ── States ───────────────────────────────────────────────────────────────────
+ *   expanded   — full sidebar (255 px desktop, 320 px mobile overlay)
+ *   collapsed  — icon-only strip (64 px desktop, full-width 68 px mobile bar)
+ */
+
+import type { NavBarVariant } from './NavBar.types';
+import type { MenuButtonItemVariant } from '../MenuButtonItem/MenuButtonItem.types';
+import type { HeaderItemVariant } from '../HeaderItem/HeaderItem.types';
+import type { FooterItemVariant } from '../FooterItem/FooterItem.types';
+import type { NavLabelStyle } from '../NavLabel/NavLabel.types';
+
+/* ── Sidebar background ───────────────────────────────────────────────────── */
+
+/**
+ * Background color applied to the `<nav>` root.
+ *
+ * Token mapping:
+ *   default → Background/background-white  #ffffff
+ *   gray    → Background/background-neutral-100  #f3f4f6
+ *   brand   → Background/background-primary  #1b8354
+ */
+export const SIDEBAR_BG: Record<NavBarVariant, string> = {
+  default: 'bg-white dark:bg-[rgba(17,24,39,1)]',
+  gray: 'bg-[rgba(249,250,251,1)] dark:bg-[rgba(17,24,39,1)]',
+  brand: 'bg-[rgba(27,131,84,1)] dark:bg-[rgba(27,131,84,1)]',
+};
+
+/* ── Sub-component variant derivation ────────────────────────────────────── */
+
+/**
+ * Maps NavBar style → MenuButtonItem variant.
+ *
+ *   default → 'transparent' (items have no bg, hover = subtle tint)
+ *   gray    → 'filled'      (items have white card bg on gray sidebar)
+ *   brand   → 'brand-background' (items white text on green sidebar)
+ */
+export const ITEM_VARIANT: Record<NavBarVariant, MenuButtonItemVariant> = {
+  default: 'transparent',
+  gray: 'filled', 
+  brand: 'brand-background',
+};
+
+/**
+ * Maps NavBar style → HeaderItem / FooterItem variant.
+ *
+ *   default / gray → 'default' (dark text)
+ *   brand          → 'brand'   (white text)
+ */
+export const HEADER_FOOTER_VARIANT: Record<NavBarVariant, HeaderItemVariant> = {
+  default: 'default',
+  gray: 'default',
+  brand: 'brand',
+};
+
+export const FOOTER_VARIANT: Record<NavBarVariant, FooterItemVariant> = {
+  default: 'default',
+  gray: 'default',
+  brand: 'brand',
+};
+
+/**
+ * Maps NavBar style → NavLabel style (section headings inside groups).
+ *
+ *   default / gray → 'default' (dark text, 70 % opacity)
+ *   brand          → 'brand'   (white text, 70 % opacity)
+ */
+export const LABEL_STYLE: Record<NavBarVariant, NavLabelStyle> = {
+  default: 'default',
+  gray: 'default',
+  brand: 'brand',
+};
+
+/* ── Layout helpers ───────────────────────────────────────────────────────── */
+
+/**
+ * Shared base for the `<nav>` element in all states.
+ * `flex flex-col` stacks header → content → footer.
+ * `transition-[width]` animates the collapse/expand.
+ */
+export const NAV_BASE =
+  'flex flex-col overflow-hidden transition-[width] duration-200 ease-in-out';
+
+/** Expanded desktop sidebar — 255 px wide. */
+export const NAV_EXPANDED_DESKTOP = 'w-[255px] h-full';
+
+/** Collapsed desktop sidebar — 64 px wide, items centered. */
+export const NAV_COLLAPSED_DESKTOP = 'w-[64px] h-full items-center';
+
+/** Mobile expanded drawer — fixed 320 px overlay from the inline-start edge. */
+export const NAV_MOBILE_EXPANDED =
+  'fixed inset-y-0 start-0 z-50 w-[320px] h-full';
+
+/** Mobile collapsed — full-width 68 px header strip only. */
+export const NAV_MOBILE_COLLAPSED = 'w-full';
+
+/**
+ * Semi-transparent backdrop shown behind the mobile expanded drawer.
+ * Figma: Colors/Alpha/alpha-black-40 → rgba(22,22,22,0.4)
+ */
+export const MOBILE_BACKDROP =
+  'fixed inset-0 z-40 bg-[rgba(22,22,22,0.4)]';
+
+/* ── Content / scroll area ────────────────────────────────────────────────── */
+
+/**
+ * Scrollable nav-groups area in the expanded desktop / mobile expanded states.
+ * `flex-1 min-h-0` makes it grow to fill remaining height.
+ * `overflow-y-auto` enables scrolling when there are many groups.
+ * `px-spacing-xl` matches Figma's 16 px horizontal padding inside the sidebar.
+ */
+export const CONTENT_AREA_EXPANDED =
+  'flex-1 min-h-0 overflow-y-auto px-spacing-xl py-spacing-none flex flex-col';
+
+/**
+ * Content area in collapsed desktop mode.
+ * No horizontal padding — items are centered via the `items-center` on `<nav>`.
+ */
+export const CONTENT_AREA_COLLAPSED =
+  'flex-1 min-h-0 overflow-y-auto w-full flex flex-col items-center';
+
+/* ── Toggle button (hamburger / close on mobile) ─────────────────────────── */
+
+/**
+ * Shared base for the hamburger and close toggle buttons.
+ * Used as `actionIcon` inside `HeaderItem`.
+ * Sizing is inherited from the HeaderItem's icon slot (`size-icon-md`).
+ */
+export const TOGGLE_BTN_BASE =
+  'inline-flex items-center justify-center w-full h-full focus:outline-none';

package/src/components/NavBar/index.ts

@@ -0,0 +1,2 @@
+export { NavBar } from './NavBar';
+export type { NavBarProps, NavBarVariant, NavBarGroup } from './NavBar.types';

package/src/components/NavHeader/NavHeader.tsx

@@ -0,0 +1,292 @@
+'use client';
+
+import { forwardRef, Fragment, isValidElement, cloneElement } from 'react';
+import type { Key, ReactElement, ReactNode } from 'react';
+import { cn } from '../../lib/cn';
+import { NavLogoPlaceholder } from '../NavLogoPlaceholder';
+import { NavHeaderMenuButton } from '../NavHeaderMenuButton';
+import { Divider } from '../Divider';
+import type { NavHeaderProps } from './NavHeader.types';
+import {
+  ACTIONS_DESKTOP,
+  BAR_DESKTOP,
+  BAR_MOBILE,
+  DRAWER_BODY,
+  DRAWER_FOOTER,
+  DRAWER_MOBILE,
+  ITEMS_ROW,
+  MENU_PANEL_COLUMN,
+  MENU_PANEL_DESKTOP,
+  ROOT,
+  SEARCH_DESKTOP,
+} from './NavHeader.variants';
+
+/**
+ * NavHeader — the top-of-page navigation shell.
+ *
+ * A pure composition of existing `sdaia-ui` building blocks:
+ *   - `NavLogoPlaceholder`   — brand / logo slot
+ *   - `NavHeaderMenuItem`    — inline menu items (desktop + mobile drawer)
+ *   - `NavHeaderMenuButton`  — mobile hamburger / × toggle
+ *   - `NavHeaderActions`     — Log in / Sign Up / Avatar cluster
+ *   - `TextInput`            — search field (consumer passes a fully
+ *                              configured instance)
+ *   - `NavHeaderDropdownItemList` / `NavHeaderDropdownItem` /
+ *     `NavHeaderMenuCard`    — optional dropdown / drawer content
+ *   - `Divider`              — separators between stacked mobile rows
+ *
+ * The shell itself owns only *layout* — spacing, positioning, and the
+ * plumbing between `menuOpen` and the mobile toggle button. Every
+ * interactive state (hover, focus, disabled, open) lives inside the
+ * composed child components and flows through naturally. RTL is
+ * automatic because every spacing class uses logical properties
+ * (`ps-*`/`pe-*`, `inset-x-*`) and the child components already handle
+ * direction-sensitive content themselves.
+ */
+export const NavHeader = forwardRef<HTMLElement, NavHeaderProps>(
+  function NavHeader(
+    {
+      type = 'default',
+      mobile,
+      menuOpen = false,
+      onOpenChange,
+      logo,
+      items,
+      search,
+      actions,
+      menuContent,
+      mobileFooter,
+      className,
+      ...rest
+    },
+    ref,
+  ) {
+    const logoNode =
+      logo ?? <NavLogoPlaceholder size="medium" text="SDAIA" />;
+
+    /* Visibility model:
+     *   mobile === undefined → render BOTH branches; CSS switches at `lg`
+     *   mobile === true      → mobile branch only (forced)
+     *   mobile === false     → desktop branch only (forced)
+     */
+    const renderDesktop = mobile !== true;
+    const renderMobile = mobile !== false;
+    const responsive = mobile === undefined;
+
+    const showDesktopDropdown =
+      renderDesktop && type !== 'default' && menuContent != null;
+    const showMobileDrawer = renderMobile && menuOpen;
+
+    return (
+      <nav
+        ref={ref}
+        data-slot="nav-header"
+        data-type={type}
+        data-mobile={
+          mobile === true ? 'true' : mobile === false ? 'false' : 'auto'
+        }
+        data-open={menuOpen || undefined}
+        className={cn(ROOT, className)}
+        {...rest}
+      >
+        {/* ── Desktop branch ───────────────────────────────────────── */}
+        {renderDesktop ? (
+          <div
+            data-slot="nav-header-desktop"
+            className={responsive ? 'hidden lg:block' : undefined}
+          >
+            <div data-slot="nav-header-bar" className={BAR_DESKTOP}>
+              {logoNode}
+
+              {items && items.length > 0 ? (
+                <div data-slot="nav-header-items" className={ITEMS_ROW}>
+                  {keyedItems(items)}
+                </div>
+              ) : null}
+
+              {search ? (
+                <div data-slot="nav-header-search" className={SEARCH_DESKTOP}>
+                  {search}
+                </div>
+              ) : null}
+
+              {actions ? (
+                <div data-slot="nav-header-actions" className={ACTIONS_DESKTOP}>
+                  {actions}
+                </div>
+              ) : null}
+            </div>
+
+            {showDesktopDropdown ? (
+              <div
+                data-slot="nav-header-dropdown"
+                data-density={type === 'menu-compact' ? 'compact' : 'full'}
+                className={MENU_PANEL_DESKTOP}
+              >
+                {renderDropdownColumns(menuContent)}
+              </div>
+            ) : null}
+          </div>
+        ) : null}
+
+        {/* ── Mobile branch ────────────────────────────────────────── */}
+        {renderMobile ? (
+          <div
+            data-slot="nav-header-mobile"
+            className={responsive ? 'lg:hidden' : undefined}
+          >
+            <div data-slot="nav-header-bar" className={BAR_MOBILE}>
+              {logoNode}
+              <NavHeaderMenuButton
+                data-slot="nav-header-toggle"
+                opened={menuOpen}
+                onClick={() => onOpenChange?.(!menuOpen)}
+                aria-label={menuOpen ? 'Close menu' : 'Open menu'}
+                aria-expanded={menuOpen}
+              />
+            </div>
+
+            {showMobileDrawer ? (
+              <div data-slot="nav-header-drawer" className={DRAWER_MOBILE}>
+                {search ? (
+                  <div data-slot="nav-header-search">{search}</div>
+                ) : null}
+
+                <div data-slot="nav-header-drawer-body" className={DRAWER_BODY}>
+                  {renderMobileBody(items, menuContent)}
+                </div>
+
+                {(mobileFooter || actions) && (
+                  <div
+                    data-slot="nav-header-drawer-footer"
+                    className={DRAWER_FOOTER}
+                  >
+                    {mobileFooter}
+                    {actions}
+                  </div>
+                )}
+              </div>
+            ) : null}
+          </div>
+        ) : null}
+      </nav>
+    );
+  },
+);
+
+NavHeader.displayName = 'NavHeader';
+
+/* ───────────────────────────────────────────────────────────────
+ * Helpers
+ * ─────────────────────────────────────────────────────────────── */
+
+/**
+ * Render the mobile drawer body: menu items with any dropdown content
+ * injected *inline* directly after the item that has `open={true}`,
+ * with a `<Divider />` between every adjacent row.
+ *
+ * `items` holds `<NavHeaderMenuItem mobile />` nodes. When one of them
+ * has `open={true}` and `menuContent` is provided, `menuContent` is
+ * inserted immediately after that item so it expands accordion-style
+ * rather than appearing at the bottom of the list.
+ *
+ * If no item is open (or `menuContent` is null/undefined) the drawer
+ * renders only the items, with no trailing content block.
+ */
+function renderMobileBody(
+  items: ReadonlyArray<ReactNode> | undefined,
+  menuContent: ReactNode,
+): ReactNode {
+  const rows: ReactNode[] = [];
+
+  if (items) {
+    for (const item of items) {
+      rows.push(item);
+      // Inject content immediately after the open item (accordion style)
+      if (
+        menuContent != null &&
+        isValidElement(item) &&
+        (item as ReactElement<{ open?: boolean }>).props?.open === true
+      ) {
+        rows.push(menuContent);
+      }
+    }
+  }
+
+  return rows.map((row, idx) => {
+    const key = keyOf(row, idx);
+    return (
+      <Fragment key={key}>
+        {idx > 0 ? (
+          <Divider
+            lineType="horizontal"
+            color="neutral"
+            thickness="hairline"
+          />
+        ) : null}
+        {reKey(row, key)}
+      </Fragment>
+    );
+  });
+}
+
+/**
+ * Wrap each top-level dropdown node in a column wrapper so the panel
+ * distributes any number of columns evenly. If the consumer passes a
+ * single `NavHeaderDropdownItemList`, it becomes a single column; two
+ * lists become two columns; and so on.
+ *
+ * If `menuContent` is a fragment-like array we unwrap it; if it's a
+ * single element we render it as a one-column panel.
+ */
+function renderDropdownColumns(menuContent: ReactNode): ReactNode {
+  const nodes = Array.isArray(menuContent) ? menuContent : [menuContent];
+
+  return nodes.map((node, idx) => {
+    const key = keyOf(node, idx);
+    return (
+      <div
+        key={key}
+        data-slot="nav-header-dropdown-column"
+        className={MENU_PANEL_COLUMN}
+      >
+        {reKey(node, key)}
+      </div>
+    );
+  });
+}
+
+/** Preserve an explicit `key` if the consumer set one, else use a
+ * namespaced index so it cannot collide with a sibling's explicit key
+ * (e.g. items keyed "1", "2" plus an unkeyed menuContent at idx 2). */
+function keyOf(node: ReactNode, fallback: number): Key {
+  if (isValidElement(node)) {
+    const el = node as ReactElement<{ key?: Key }>;
+    if (el.key != null) return el.key;
+  }
+  return `__nh-${fallback}`;
+}
+
+/**
+ * Stamp a key onto a React element without replacing the original
+ * (cloneElement preserves refs and props). Non-element children are
+ * returned unchanged — the Fragment / wrapper around them already
+ * carries the key.
+ */
+function reKey(node: ReactNode, key: Key): ReactNode {
+  if (isValidElement(node)) {
+    return cloneElement(node as ReactElement, { key });
+  }
+  return node;
+}
+
+/**
+ * Apply stable keys to the desktop item array so React stops warning
+ * about missing keys on list children the consumer passed in.
+ */
+function keyedItems(items: ReadonlyArray<ReactNode>): ReactNode {
+  return items.map((item, idx) => {
+    const key = keyOf(item, idx);
+    return reKey(item, key);
+  });
+}

package/src/components/NavHeader/NavHeader.types.ts

@@ -0,0 +1,145 @@
+import type { HTMLAttributes, ReactNode } from 'react';
+
+/**
+ * Layout tier — drives the structure of the header bar and, when a menu
+ * panel is present, the visual density of the dropdown.
+ *
+ *  - `default`       → header bar only, no menu panel
+ *  - `menu`          → header bar + full menu panel (large multi-column
+ *                      dropdown on desktop, full drawer on mobile)
+ *  - `menu-compact`  → header bar + compact menu panel (2 columns + card
+ *                      on desktop, smaller drawer on mobile)
+ *
+ * The difference between `menu` and `menu-compact` is purely editorial —
+ * it lets the consumer pick the density that matches their content. The
+ * component does not generate the content; the consumer passes it in via
+ * `menuContent`.
+ */
+export type NavHeaderType = 'default' | 'menu' | 'menu-compact';
+
+/**
+ * NavHeader props.
+ *
+ * Extends `HTMLAttributes<HTMLElement>` (minus `title`, which we shadow so
+ * consumers can pass a richer ReactNode label for the mobile footer block).
+ *
+ * The component is *pure composition* — every interactive sub-element
+ * is a separate `sdaia-ui` component that the consumer passes in:
+ *
+ *   - `logo`      → default: `<NavLogoPlaceholder size="medium" text="SDAIA" />`
+ *   - `items`     → array of `<NavHeaderMenuItem />` (desktop row / mobile stack)
+ *   - `search`    → a `<TextInput placeholder="Search" />`
+ *   - `actions`   → a `<NavHeaderActions />`
+ *   - `menuContent` → what to render inside the expanded dropdown/drawer.
+ *                     Typically `<NavHeaderDropdownItemList />`,
+ *                     `<NavHeaderMenuCard />`, or any combination.
+ *   - `mobileFooter` → optional footer block for the mobile drawer
+ *                      (links + NavHeaderActions).
+ *
+ * This keeps NavHeader agnostic to concrete content (labels, hrefs, copy,
+ * localisation) and prevents us from duplicating the public APIs of the
+ * reused components.
+ */
+export interface NavHeaderProps
+  extends Omit<HTMLAttributes<HTMLElement>, 'title'> {
+  /**
+   * Visual type — controls which menu-panel density is rendered when
+   * `menuOpen` is true. When `type='default'` the menu panel is never
+   * rendered regardless of `menuOpen`.
+   * @default 'default'
+   */
+  type?: NavHeaderType;
+
+  /**
+   * Layout override.
+   *
+   *   - `undefined` (default — recommended for app code)
+   *       Auto-responsive: renders BOTH branches and uses CSS to switch
+   *       at the `lg` breakpoint (≥1024 px → desktop bar, <1024 px →
+   *       mobile bar + drawer). The same `<NavHeader />` adapts to any
+   *       viewport without a JS resize listener.
+   *   - `true` → force the mobile layout regardless of viewport.
+   *       Useful for documentation demos that want to showcase the
+   *       mobile variant inside a desktop preview frame.
+   *   - `false` → force the desktop layout regardless of viewport.
+   *       Useful for documentation demos that want to showcase the
+   *       desktop variant inside a constrained preview frame.
+   */
+  mobile?: boolean;
+
+  /**
+   * Whether the menu panel (desktop dropdown or mobile drawer) is open.
+   * Controlled. The component toggles the hamburger glyph to match but
+   * never owns this state itself — the consumer passes the latest value
+   * via props and updates it in response to `onOpenChange`.
+   * @default false
+   */
+  menuOpen?: boolean;
+
+  /**
+   * Fires when the user clicks the mobile hamburger or × button. The
+   * consumer is expected to flip `menuOpen` in response. Ignored on
+   * desktop (where menu open/close is driven by individual
+   * `<NavHeaderMenuItem open>` buttons in the bar).
+   */
+  onOpenChange?: (open: boolean) => void;
+
+  /**
+   * Logo slot. Defaults to `<NavLogoPlaceholder size="medium" text="SDAIA" />`
+   * so the component is usable on a fresh project install with zero
+   * configuration. Pass your own node (typically a
+   * `<NavLogoPlaceholder />`) to customise.
+   */
+  logo?: ReactNode;
+
+  /**
+   * Main navigation items — one entry per `<NavHeaderMenuItem />`. On
+   * desktop they render as a horizontal row inside the bar; on mobile
+   * they render stacked inside the drawer, interleaved with any
+   * `menuContent` the consumer passes.
+   *
+   * When empty / omitted, the item row is hidden on desktop and the
+   * mobile drawer falls back to rendering only `search`, `menuContent`,
+   * `mobileFooter`, and `actions`.
+   */
+  items?: ReactNode[];
+
+  /**
+   * Search input. Rendered inline between the items and the actions on
+   * desktop; rendered at the top of the drawer on mobile. Omit to hide.
+   * Typically `<TextInput placeholder="Search" fullWidth />`.
+   */
+  search?: ReactNode;
+
+  /**
+   * Trailing cluster — Log in / Sign Up buttons (logged-out) or an
+   * avatar + identity (logged-in). Typically `<NavHeaderActions />`.
+   * Rendered inline on desktop; stacked at the bottom of the drawer
+   * on mobile.
+   */
+  actions?: ReactNode;
+
+  /**
+   * Content rendered inside the expanded menu panel. On desktop this
+   * renders as an absolutely-positioned dropdown below the bar; on
+   * mobile it renders inline inside the drawer, between `search` and
+   * the footer.
+   *
+   * Ignored when `type='default'`, or when `menuOpen` is false on
+   * mobile. On desktop the dropdown is only shown when `type !== 'default'`
+   * AND at least one `<NavHeaderMenuItem open>` is in `items` — i.e.
+   * the consumer controls open/close by flipping the `open` prop on the
+   * relevant item.
+   */
+  menuContent?: ReactNode;
+
+  /**
+   * Mobile-only footer block shown at the bottom of the drawer — typically
+   * a `<div>` with secondary-link columns. Omit to hide. Has no effect
+   * on desktop.
+   */
+  mobileFooter?: ReactNode;
+
+  /** Extra classes merged onto the root element. */
+  className?: string;
+}