sdaia-ui 1.0.1

package/src/components/NavHeaderDropdownItem/NavHeaderDropdownItem.tsx

@@ -0,0 +1,243 @@
+'use client';
+
+import { forwardRef } from 'react';
+import { cn } from '../../lib/cn';
+import type { NavHeaderDropdownItemProps } from './NavHeaderDropdownItem.types';
+import {
+  CONTAINER_BASE,
+  CONTAINER_INLINE,
+  CONTAINER_STACKED,
+  ICON_WRAPPER,
+  CONTENT_INLINE,
+  LABEL_DESCRIPTION_WRAPPER,
+  STACKED_HEADER_ROW,
+  STACKED_LEADING,
+  CONTENT_WRAPPER,
+  LABEL_ROW,
+  TITLE_CLASSES,
+  DESCRIPTION_CLASSES,
+} from './NavHeaderDropdownItem.variants';
+import { PlayIconTwotone, LearnMoreArrowIcon } from '../../icons/IconFactory';
+import { Button } from '../Button';
+import { Tag } from '../Tag';
+
+/**
+ * NavHeaderDropdownItem — a rich dropdown menu item for use inside navigation
+ * header dropdowns / mega-menus.
+ *
+ * Pixel-perfect match to Figma node 5092-58173 ("_Nav Header Dropdown Item")
+ * across all 8 variants (2 layouts × 2 states × LTR + RTL auto).
+ *
+ * ── Layouts ───────────────────────────────────────────────────────────────────
+ *   `inline`  — Play icon at the inline-start edge.  Content (title + tag +
+ *               description + button) stacks vertically in the remaining space.
+ *               Best for a single-column dropdown where the icon anchors context.
+ *
+ *   `stacked` — Full-width header row: play icon at inline-start, action button
+ *               at inline-end.  Title, tag, and description render below.
+ *               Best for a wider multi-column mega-menu card.
+ *
+ * ── Hover state ───────────────────────────────────────────────────────────────
+ *   Container background transitions from transparent to `background-body`
+ *   (#f9fafb) on `:hover`.  Handled via CSS — no JS state needed.
+ *
+ * ── Composed from existing design-system components ───────────────────────────
+ *   Button  — `variant="secondary-outline" size="md"` with optional trailing
+ *             `ArrowRight01Icon`.  All button interactions (hover, focus, active)
+ *             are delegated to the Button component.
+ *   Tag     — `size="sm"` text-only chip.  Static/display only.
+ *   PlayIconTwotone — from IconFactory, wrapped in `size-icon-lg` span.
+ *   ArrowRight01Icon — from IconFactory, chevron pointing inline-end.
+ *
+ * ── RTL ───────────────────────────────────────────────────────────────────────
+ *   Fully automatic via `dir="rtl"` on any ancestor element.  Flex row order
+ *   reverses so the play icon moves to the trailing (right) edge, the button
+ *   moves to the leading (left) edge in stacked layout, and tag / title order
+ *   reverses in the label row — all without a single explicit RTL class.
+ *
+ * @example
+ * // Inline (default)
+ * <NavHeaderDropdownItem
+ *   title="Products"
+ *   description="Browse the full product catalogue."
+ *   actionLabel="Learn more"
+ * />
+ *
+ * // Stacked (mega-menu card style)
+ * <NavHeaderDropdownItem
+ *   layout="stacked"
+ *   title="Solutions"
+ *   description="Enterprise-grade solutions for every team."
+ *   actionLabel="Explore"
+ *   showActionIcon={false}
+ * />
+ *
+ * // RTL
+ * <div dir="rtl">
+ *   <NavHeaderDropdownItem title="المنتجات" description="تصفّح الكتالوج الكامل." />
+ * </div>
+ */
+export const NavHeaderDropdownItem = forwardRef<HTMLDivElement, NavHeaderDropdownItemProps>(
+  function NavHeaderDropdownItem(
+    {
+      layout = 'inline',
+      title = 'Menu Item',
+      description = 'Menu Item description here!',
+      showDescription = true,
+      actionLabel = 'Learn more',
+      showAction = true,
+      showActionIcon = true,
+      tagLabel = 'New',
+      showTag = true,
+      showIcon = true,
+      icon,
+      className,
+      ...rest
+    },
+    ref,
+  ) {
+    const isInline = layout === 'inline';
+
+    /* ── Shared sub-elements ──────────────────────────────────────────────── */
+
+    /** Leading play icon wrapped in a size-icon-lg box */
+    const leadingIconEl = showIcon ? (
+      <span
+        data-slot="nav-header-dropdown-item-icon"
+        className={ICON_WRAPPER}
+      >
+        {icon ?? <PlayIconTwotone aria-hidden="true" />}
+      </span>
+    ) : null;
+
+    /**
+     * Action button.
+     * Composed from the existing Button component.
+     * variant="secondary-outline" → border + transparent bg + neutral text
+     * size="md"                   → px-spacing-lg py-spacing-sm text-text-sm
+     * stopPropagation ensures the item's own click handler is not swallowed.
+     */
+    const actionButtonEl = showAction ? (
+      <Button
+        data-slot="nav-header-dropdown-item-action"
+        variant="secondary-outline"
+        size="md"
+        trailingIcon={
+          showActionIcon ? (
+            <LearnMoreArrowIcon aria-hidden="true" />
+          ) : undefined
+        }
+        onClick={(e) => e.stopPropagation()}
+      >
+        {actionLabel}
+      </Button>
+    ) : null;
+
+    /**
+     * Label row — title + optional tag chip.
+     * In RTL: flex reverses DOM order so Tag visually moves to inline-start
+     * and Title to inline-end — exactly matching Figma RTL frames.
+     */
+    const labelRowEl = (
+      <div data-slot="nav-header-dropdown-item-label-row" className={LABEL_ROW}>
+        <span
+          data-slot="nav-header-dropdown-item-title"
+          className={TITLE_CLASSES}
+        >
+          {title}
+        </span>
+        {showTag && (
+          <Tag
+            data-slot="nav-header-dropdown-item-tag"
+            label={tagLabel}
+            size="sm"
+          />
+        )}
+      </div>
+    );
+
+    /** Helper description paragraph */
+    const descriptionEl =
+      showDescription && description ? (
+        <p
+          data-slot="nav-header-dropdown-item-description"
+          className={DESCRIPTION_CLASSES}
+        >
+          {description}
+        </p>
+      ) : null;
+
+    /* ═══════════════════════════════════════════════════════════════════════
+       INLINE LAYOUT
+       [Play Icon] [Content: [Label+Description Wrapper] [Button]]
+    ═══════════════════════════════════════════════════════════════════════ */
+    if (isInline) {
+      return (
+        <div
+          ref={ref}
+          data-slot="nav-header-dropdown-item"
+          data-layout="inline"
+          className={cn(CONTAINER_BASE, CONTAINER_INLINE, className)}
+          {...rest}
+        >
+          {/* Leading play icon */}
+          {leadingIconEl}
+
+          {/* Content: label row + description + action button */}
+          <div
+            data-slot="nav-header-dropdown-item-content"
+            className={CONTENT_INLINE}
+          >
+            {/* Label row + description grouped together */}
+            <div className={LABEL_DESCRIPTION_WRAPPER}>
+              {labelRowEl}
+              {descriptionEl}
+            </div>
+
+            {/* Action button below the text block */}
+            {actionButtonEl}
+          </div>
+        </div>
+      );
+    }
+
+    /* ═══════════════════════════════════════════════════════════════════════
+       STACKED LAYOUT
+       [Header row: Play Icon (flex-1) | Button (shrink-0)]
+       [Content: Label row + Description]
+    ═══════════════════════════════════════════════════════════════════════ */
+    return (
+      <div
+        ref={ref}
+        data-slot="nav-header-dropdown-item"
+        data-layout="stacked"
+        className={cn(CONTAINER_BASE, CONTAINER_STACKED, className)}
+        {...rest}
+      >
+        {/* Header row: icon at start, button at end */}
+        <div
+          data-slot="nav-header-dropdown-item-header"
+          className={STACKED_HEADER_ROW}
+        >
+          {/* Leading container (flex-1) — pushes button to inline-end */}
+          <div className={STACKED_LEADING}>
+            {leadingIconEl}
+          </div>
+          {/* Action button sits at the inline-end of the header row */}
+          {actionButtonEl}
+        </div>
+
+        {/* Content: title/tag row + description */}
+        <div
+          data-slot="nav-header-dropdown-item-content"
+          className={CONTENT_WRAPPER}
+        >
+          {labelRowEl}
+          {descriptionEl}
+        </div>
+      </div>
+    );
+  },
+);
+
+NavHeaderDropdownItem.displayName = 'NavHeaderDropdownItem';

package/src/components/NavHeaderDropdownItem/NavHeaderDropdownItem.types.ts

@@ -0,0 +1,76 @@
+import type { HTMLAttributes, ReactNode } from 'react';
+
+/** Layout variant of the dropdown item. */
+export type NavHeaderDropdownItemLayout = 'inline' | 'stacked';
+
+/**
+ * NavHeaderDropdownItem props.
+ *
+ * Extends native `<div>` attributes for full DOM prop pass-through.
+ */
+export interface NavHeaderDropdownItemProps extends HTMLAttributes<HTMLDivElement> {
+  /**
+   * Layout structure.
+   *
+   * `'inline'`  — Leading play icon on the inline-start edge, content + button
+   *               stacked vertically in the remaining space.  Matches Figma
+   *               "Layout=Inline" (320×116 px).
+   *
+   * `'stacked'` — Full-width header row with the play icon at the start edge and
+   *               the action button at the end edge, then content below.  Matches
+   *               Figma "Layout=Stacked" (320×112 px).
+   *
+   * @default 'inline'
+   */
+  layout?: NavHeaderDropdownItemLayout;
+
+  /** Main title / label text.  @default 'Menu Item' */
+  title?: string;
+
+  /** Secondary helper / description text shown below the title. */
+  description?: string;
+
+  /**
+   * Show the description paragraph.
+   * @default true
+   */
+  showDescription?: boolean;
+
+  /** Label for the action button.  @default 'Learn more' */
+  actionLabel?: string;
+
+  /**
+   * Show the action `Button`.
+   * @default true
+   */
+  showAction?: boolean;
+
+  /**
+   * Show the trailing arrow icon on the action button.
+   * Set `false` for the stacked layout "text-only" button style.
+   * @default true
+   */
+  showActionIcon?: boolean;
+
+  /** Label for the tag chip next to the title.  @default 'New' */
+  tagLabel?: string;
+
+  /**
+   * Show the tag chip.
+   * @default true
+   */
+  showTag?: boolean;
+
+  /**
+   * Show the leading play icon.
+   * @default true
+   */
+  showIcon?: boolean;
+
+  /**
+   * Custom node to replace the default `PlayIconTwotone`.
+   * Must be a size-agnostic element — the wrapping `<span>` carries the
+   * `size-icon-lg` token class that controls dimensions.
+   */
+  icon?: ReactNode;
+}

package/src/components/NavHeaderDropdownItem/NavHeaderDropdownItem.variants.ts

@@ -0,0 +1,133 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// Container
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Shared base for both layout variants.
+ *
+ * Token mapping:
+ *   p-spacing-lg  → Global/spacing-lg  (12 px)
+ *   gap-spacing-md → Global/spacing-md (8 px)
+ *   rounded-[8px] → Radius/radius-8    (8 px)
+ *   hover bg      → Background/background-body → rgba(249,250,251,1)
+ */
+export const CONTAINER_BASE = [
+  'relative flex gap-spacing-md items-start',
+  'p-spacing-lg rounded-[8px]',
+  'motion-feedback',
+  'hover:bg-[rgba(249,250,251,1)]',
+  'dark:hover:bg-[rgba(255,255,255,0.06)]',
+].join(' ');
+
+/** Inline — icon + content side by side in a row. */
+export const CONTAINER_INLINE = 'flex-row';
+
+/** Stacked — header row (icon + button) above content. */
+export const CONTAINER_STACKED = 'flex-col';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Leading icon slot
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Wrapper for the play icon.
+ * Figma: icon-xl = 24 px → size-icon-lg (20 px mobile → 24 px desktop)
+ * Token: Icon/icon-default → rgba(22,22,22,1)
+ */
+export const ICON_WRAPPER = [
+  'inline-flex items-center justify-center shrink-0',
+  'size-icon-lg',
+  'text-[rgba(22,22,22,1)] dark:text-[rgba(209,213,219,1)]',
+].join(' ');
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Inline content column
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Grows to fill remaining row width (beside the leading icon).
+ * Token: gap-spacing-lg = 12 px — vertical gap between the text wrapper and button.
+ */
+export const CONTENT_INLINE = 'flex flex-1 flex-col gap-spacing-lg items-start min-w-0';
+
+/**
+ * Wraps label row + description together in inline layout.
+ * Token: gap-spacing-xs = 4 px — gap between title line and description.
+ */
+export const LABEL_DESCRIPTION_WRAPPER = 'flex flex-col gap-spacing-xs w-full';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Stacked header row
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Full-width row with icon at leading edge and button at trailing edge.
+ * Token: gap-spacing-md = 8 px
+ */
+export const STACKED_HEADER_ROW = 'flex gap-spacing-md items-start w-full shrink-0';
+
+/**
+ * Flex-1 container that holds the play icon at the inline-start edge.
+ * Grows to push the button to the inline-end.
+ */
+export const STACKED_LEADING = 'flex flex-1 items-center';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Content wrapper (shared label row + description)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Wraps label row and description in both layouts.
+ * Token: gap-spacing-xs = 4 px
+ */
+export const CONTENT_WRAPPER = 'flex flex-col gap-spacing-xs w-full shrink-0';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Label row (title + tag)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Horizontal row that holds the title text and the tag chip.
+ * Items flow from inline-start to inline-end; in RTL the order auto-reverses
+ * via the ancestor `dir` attribute.
+ * Token: gap-spacing-md = 8 px
+ */
+export const LABEL_ROW = 'flex gap-spacing-md items-center w-full';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Title text
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Primary label / title of the dropdown item.
+ *
+ * Token mapping:
+ *   text-text-md    → typo-size-text-md  = 16 px
+ *   leading-[24px]  → line-heights-text-md = 24 px
+ *   font-[500]      → font-weight-medium
+ *   color           → Text/text-display  → rgba(31,42,55,1)
+ */
+export const TITLE_CLASSES = [
+  'text-text-md leading-[24px] font-[500]',
+  'text-[rgba(31,42,55,1)] dark:text-[rgba(229,231,235,1)]',
+  'shrink-0 whitespace-nowrap',
+].join(' ');
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Description text
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Helper / secondary description below the title.
+ *
+ * Token mapping:
+ *   text-text-sm    → typo-size-text-sm  = 14 px
+ *   leading-[20px]  → line-heights-text-sm = 20 px
+ *   font-[400]      → font-weight-regular
+ *   color           → Text/text-primary-paragraph → rgba(56,66,80,1)
+ */
+export const DESCRIPTION_CLASSES = [
+  'text-text-sm leading-[20px] font-[400]',
+  'text-[rgba(56,66,80,1)] dark:text-[rgba(156,163,175,1)]',
+  'w-full',
+].join(' ');

package/src/components/NavHeaderDropdownItem/index.ts

@@ -0,0 +1,5 @@
+export { NavHeaderDropdownItem } from './NavHeaderDropdownItem';
+export type {
+  NavHeaderDropdownItemProps,
+  NavHeaderDropdownItemLayout,
+} from './NavHeaderDropdownItem.types';

package/src/components/NavHeaderDropdownItemList/NavHeaderDropdownItemList.tsx

@@ -0,0 +1,64 @@
+'use client';
+
+import { forwardRef, isValidElement, cloneElement } from 'react';
+import type { ReactElement, Key } from 'react';
+import { cn } from '../../lib/cn';
+import type { NavHeaderDropdownItemListProps } from './NavHeaderDropdownItemList.types';
+import { ROOT_BY_TYPE, TITLE } from './NavHeaderDropdownItemList.variants';
+
+/**
+ * NavHeaderDropdownItemList
+ *
+ * Vertical list wrapper for the Nav Header dropdown menu. It composes
+ * two existing design-system components — `NavHeaderDropdownItem`
+ * (type=`standard`) or `NavHeaderMenuCard` (type=`card`) — which the
+ * consumer instantiates and passes in via `items`.
+ *
+ * Layout is a simple `flex flex-col` with `gap-spacing-lg` between the
+ * optional header title and each item. RTL works automatically via the
+ * ambient `dir="rtl"` on `<html>` because only the child components
+ * contain direction-sensitive content, and they already use logical
+ * properties internally.
+ */
+export const NavHeaderDropdownItemList = forwardRef<
+  HTMLDivElement,
+  NavHeaderDropdownItemListProps
+>(function NavHeaderDropdownItemList(
+  { type = 'standard', title, items, className, ...rest },
+  ref,
+) {
+  return (
+    <div
+      ref={ref}
+      data-slot="nav-header-dropdown-item-list"
+      data-type={type}
+      className={cn(ROOT_BY_TYPE[type], className)}
+      {...rest}
+    >
+      {title ? (
+        <p data-slot="nav-header-dropdown-item-list-title" className={TITLE}>
+          {title}
+        </p>
+      ) : null}
+
+      {items.map((item, index) => {
+        // Preserve the consumer's own key if they set one; otherwise
+        // fall back to the positional index. Wrapping in a fragment
+        // would drop refs on the child, so we re-key the element
+        // itself when we can.
+        if (isValidElement(item)) {
+          const el = item as ReactElement<{ key?: Key }>;
+          const keyed: Key = el.key != null ? el.key : index;
+          return cloneElement(el, { key: keyed });
+        }
+        return (
+          <span key={index} data-slot="nav-header-dropdown-item-list-item">
+            {item}
+          </span>
+        );
+      })}
+    </div>
+  );
+});
+
+NavHeaderDropdownItemList.displayName = 'NavHeaderDropdownItemList';

package/src/components/NavHeaderDropdownItemList/NavHeaderDropdownItemList.types.ts

@@ -0,0 +1,55 @@
+import type { HTMLAttributes, ReactNode } from 'react';
+
+/**
+ * Visual type — controls both default width and the kind of items
+ * the consumer is expected to pass via `items`.
+ *
+ *  - `standard` → list of `NavHeaderDropdownItem`s (320 px column).
+ *                 Figma supports 1-4 items per list.
+ *  - `card`     → list of `NavHeaderMenuCard`s (420 px column).
+ *                 Figma supports 1-3 cards per list.
+ */
+export type NavHeaderDropdownItemListType = 'standard' | 'card';
+
+/**
+ * NavHeaderDropdownItemList props.
+ *
+ * Extends native `<div>` attributes for full DOM prop pass-through.
+ *
+ * This component is pure composition — the two list item kinds
+ * (`NavHeaderDropdownItem` and `NavHeaderMenuCard`) are already shipped
+ * in this package and the consumer instantiates them directly, then
+ * passes the resulting nodes in via `items`. Keeping the list agnostic
+ * of item props means we never duplicate configuration surface and the
+ * consumer always has full control over labels, actions, hrefs, etc.
+ */
+export interface NavHeaderDropdownItemListProps
+  extends Omit<HTMLAttributes<HTMLDivElement>, 'title'> {
+  /**
+   * Visual type — drives the container width.
+   *  - `standard` → 320 px wide, expects `NavHeaderDropdownItem` items.
+   *  - `card`     → 420 px wide, expects `NavHeaderMenuCard` items.
+   * @default 'standard'
+   */
+  type?: NavHeaderDropdownItemListType;
+
+  /**
+   * Optional header title shown above the list.
+   * Rendered as a `<p>` with Text md / Semibold styling per Figma.
+   * Omit to hide the header row entirely.
+   */
+  title?: ReactNode;
+
+  /**
+   * Pre-configured list item nodes. For `type='standard'` pass
+   * `<NavHeaderDropdownItem />` nodes; for `type='card'` pass
+   * `<NavHeaderMenuCard />` nodes.
+   *
+   * An array (rather than `children`) makes the expected shape explicit
+   * and lets the component stamp out stable keys for us.
+   */
+  items: ReactNode[];
+
+  /** Extra classes merged onto the root `<div>`. */
+  className?: string;
+}

package/src/components/NavHeaderDropdownItemList/NavHeaderDropdownItemList.variants.ts

@@ -0,0 +1,47 @@
+import type { NavHeaderDropdownItemListType } from './NavHeaderDropdownItemList.types';
+
+/*
+ * NavHeaderDropdownItemList — class constants
+ *
+ * Figma: node 5101:62686 "_Nav Header Dropdown Item List". Matrix:
+ *   type      × value (item count) × rtl
+ *   standard  × 1-4                 × 2
+ *   card      × 1-3                 × 2
+ *
+ * State model:
+ *   No intrinsic states. Interaction lives inside the child items
+ *   (NavHeaderDropdownItem / NavHeaderMenuCard) — this component is a
+ *   pure presentational wrapper.
+ *
+ * Token mapping (values come from globals.css — no raw pixels):
+ *   flex flex-col    → vertical stack
+ *   gap-spacing-lg   → 12 px gap between header + items and between items
+ *   text-text-md     → 16 px title size
+ *   font-[600]       → Semibold weight (Figma Text md/Semibold)
+ *   leading-[24px]   → Text md line-height (only literal value — no token)
+ *   text-color-display → Figma Text/text-display (#1f2a37)
+ *
+ * Container widths (320 / 420) come straight from the Figma spec; no
+ * global token covers those so they stay as literal pixels with
+ * `max-w-full` for safe shrinking inside narrow parents.
+ */
+
+/** Root container per type — only width differs. */
+export const ROOT_BY_TYPE: Record<NavHeaderDropdownItemListType, string> = {
+  standard: [
+    'flex flex-col gap-spacing-lg items-stretch',
+    'w-[320px] max-w-full',
+  ].join(' '),
+  card: [
+    'flex flex-col gap-spacing-lg items-stretch',
+    'w-[420px] max-w-full',
+  ].join(' '),
+};
+
+/**
+ * Header title — Figma Text md/Semibold, #1f2a37.
+ * Dark-mode color follows the display token already in use by the rest
+ * of the Nav Header family (white).
+ */
+export const TITLE =
+  'text-text-md font-[600] leading-[24px] text-color-display dark:text-white';

package/src/components/NavHeaderDropdownItemList/index.ts

@@ -0,0 +1,5 @@
+export { NavHeaderDropdownItemList } from './NavHeaderDropdownItemList';
+export type {
+  NavHeaderDropdownItemListProps,
+  NavHeaderDropdownItemListType,
+} from './NavHeaderDropdownItemList.types';