sdaia-ui 1.0.1

package/src/components/HelpIcon/HelpIcon.tsx

@@ -0,0 +1,173 @@
+'use client';
+
+import { forwardRef, useState, useRef, useCallback, useEffect, type CSSProperties } from 'react';
+import { createPortal } from 'react-dom';
+import { cn } from '../../lib/cn';
+import { Tooltip } from '../Tooltip';
+import type { HelpIconProps, HelpIconPlacement } from './HelpIcon.types';
+import {
+  PLACEMENT_TO_BEAK,
+  ALIGN_TO_BEAK,
+  TOOLTIP_MAX_WIDTH,
+  TRIGGER_BASE,
+} from './HelpIcon.variants';
+import { QuestionMarkIcon } from '../../icons/IconFactory';
+
+const GAP = 6; // px gap between trigger edge and tooltip
+const MOBILE_BREAKPOINT = 768; // px — below this the tooltip centers in the viewport
+
+function getTooltipStyle(
+  rect: DOMRect,
+  placement: HelpIconPlacement,
+  align: string,
+): CSSProperties {
+  // On narrow viewports there isn't enough room to anchor the tooltip near the
+  // trigger — center it in the viewport instead so it never overflows.
+  if (window.innerWidth < MOBILE_BREAKPOINT) {
+    return {
+      position: 'fixed',
+      zIndex: 9999,
+      top: '50%',
+      left: '50%',
+      transform: 'translate(-50%, -50%)',
+    };
+  }
+
+  const style: CSSProperties = { position: 'fixed', zIndex: 9999 };
+  const { top, bottom, left, right, width, height } = rect;
+
+  if (placement === 'top') {
+    style.bottom = window.innerHeight - top + GAP;
+    if (align === 'start') style.left = left;
+    else if (align === 'end') style.right = window.innerWidth - right;
+    else { style.left = left + width / 2; style.transform = 'translateX(-50%)'; }
+  } else if (placement === 'bottom') {
+    style.top = bottom + GAP;
+    if (align === 'start') style.left = left;
+    else if (align === 'end') style.right = window.innerWidth - right;
+    else { style.left = left + width / 2; style.transform = 'translateX(-50%)'; }
+  } else if (placement === 'left') {
+    style.right = window.innerWidth - left + GAP;
+    if (align === 'start') style.top = top;
+    else if (align === 'end') style.bottom = window.innerHeight - bottom;
+    else { style.top = top + height / 2; style.transform = 'translateY(-50%)'; }
+  } else {
+    // right
+    style.left = right + GAP;
+    if (align === 'start') style.top = top;
+    else if (align === 'end') style.bottom = window.innerHeight - bottom;
+    else { style.top = top + height / 2; style.transform = 'translateY(-50%)'; }
+  }
+
+  return style;
+}
+
+export const HelpIcon = forwardRef<HTMLDivElement, HelpIconProps>(function HelpIcon(
+  {
+    placement = 'top',
+    align = 'start',
+    open: openProp,
+    onOpenChange,
+    title,
+    description,
+    rtl = false,
+    className,
+    ...rest
+  },
+  ref,
+) {
+  const [internalOpen, setInternalOpen] = useState(false);
+  const isControlled = openProp !== undefined;
+  const open = isControlled ? openProp : internalOpen;
+  const [tooltipStyle, setTooltipStyle] = useState<CSSProperties>({});
+  const [mounted, setMounted] = useState(false);
+  const triggerRef = useRef<HTMLButtonElement>(null);
+  const closeTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  useEffect(() => { setMounted(true); }, []);
+  useEffect(() => () => { if (closeTimer.current) clearTimeout(closeTimer.current); }, []);
+
+  const effectivePlacement: HelpIconPlacement =
+    rtl && placement === 'left' ? 'right'
+    : rtl && placement === 'right' ? 'left'
+    : placement;
+
+  const beakPlacement = PLACEMENT_TO_BEAK[effectivePlacement];
+  const beakAlignment = ALIGN_TO_BEAK[align];
+
+  const doOpen = useCallback(() => {
+    if (closeTimer.current) { clearTimeout(closeTimer.current); closeTimer.current = null; }
+    if (triggerRef.current) {
+      setTooltipStyle(getTooltipStyle(
+        triggerRef.current.getBoundingClientRect(),
+        effectivePlacement,
+        align,
+      ));
+    }
+    if (!isControlled) setInternalOpen(true);
+    onOpenChange?.(true);
+  }, [effectivePlacement, align, isControlled, onOpenChange]);
+
+  const scheduleClose = useCallback(() => {
+    closeTimer.current = setTimeout(() => {
+      if (!isControlled) setInternalOpen(false);
+      onOpenChange?.(false);
+    }, 80);
+  }, [isControlled, onOpenChange]);
+
+  const cancelClose = useCallback(() => {
+    if (closeTimer.current) { clearTimeout(closeTimer.current); closeTimer.current = null; }
+  }, []);
+
+  const tooltipPortal = open && mounted
+    ? createPortal(
+        <div
+          style={tooltipStyle}
+          onMouseEnter={cancelClose}
+          onMouseLeave={scheduleClose}
+        >
+          <Tooltip
+            type="neutral"
+            beakPlacement={beakPlacement}
+            beakAlignment={beakAlignment}
+            icon
+            title={title}
+            description={description}
+            className={TOOLTIP_MAX_WIDTH}
+          />
+        </div>,
+        document.body,
+      )
+    : null;
+
+  return (
+    <div
+      ref={ref}
+      data-slot="help-icon"
+      data-placement={placement}
+      data-align={align}
+      data-open={open}
+      className={cn('relative inline-flex', className)}
+      {...rest}
+    >
+      <button
+        ref={triggerRef}
+        type="button"
+        data-slot="help-icon-trigger"
+        aria-expanded={open}
+        aria-label="Help"
+        className={TRIGGER_BASE}
+        onMouseEnter={doOpen}
+        onMouseLeave={scheduleClose}
+        onFocus={doOpen}
+        onBlur={scheduleClose}
+      >
+        <span className="inline-flex items-center justify-center size-[20px]">
+          <QuestionMarkIcon />
+        </span>
+      </button>
+
+      {tooltipPortal}
+    </div>
+  );
+});

package/src/components/HelpIcon/HelpIcon.types.ts

@@ -0,0 +1,54 @@
+import type { HTMLAttributes, ReactNode } from 'react';
+
+/** Which side the tooltip appears on relative to the trigger icon. */
+export type HelpIconPlacement = 'top' | 'bottom' | 'left' | 'right';
+
+/** Where the beak (arrow) sits along the tooltip edge. */
+export type HelpIconAlign = 'start' | 'center' | 'end';
+
+export interface HelpIconProps extends Omit<HTMLAttributes<HTMLDivElement>, 'title'> {
+  /**
+   * Side on which the tooltip appears relative to the trigger icon.
+   * In RTL mode the left/right placements are mirrored automatically.
+   * @default 'top'
+   */
+  placement?: HelpIconPlacement;
+
+  /**
+   * Alignment of the beak (arrow) along the tooltip edge.
+   * For top/bottom placements this controls horizontal position;
+   * for left/right placements it controls vertical position.
+   * @default 'start'
+   */
+  align?: HelpIconAlign;
+
+  /**
+   * Whether the tooltip is currently visible.
+   * When provided the component operates in controlled mode.
+   * When omitted the component is uncontrolled and shows on hover/focus.
+   */
+  open?: boolean;
+
+  /**
+   * Callback fired when the tooltip open state should change.
+   * Use this together with `open` for controlled mode.
+   */
+  onOpenChange?: (open: boolean) => void;
+
+  /**
+   * Title text displayed at the top of the tooltip.
+   */
+  title?: ReactNode;
+
+  /**
+   * Description / body text displayed below the title.
+   */
+  description?: ReactNode;
+
+  /**
+   * Pass `true` when the component is rendered inside a `dir="rtl"` context
+   * and you need left/right placements to mirror correctly.
+   * @default false
+   */
+  rtl?: boolean;
+}

package/src/components/HelpIcon/HelpIcon.variants.ts

@@ -0,0 +1,79 @@
+import type { TooltipBeakPlacement, TooltipBeakAlignment } from '../Tooltip';
+import type { HelpIconPlacement, HelpIconAlign } from './HelpIcon.types';
+
+/* ── Placement → beak direction ──────────────────────────────────
+ * The beak always points FROM the tooltip TOWARD the trigger.
+ * This map is used after the caller has already applied the RTL
+ * left↔right swap on effectivePlacement.
+ */
+export const PLACEMENT_TO_BEAK: Record<HelpIconPlacement, TooltipBeakPlacement> = {
+  top: 'bottom',    // tooltip above → beak at bottom of tooltip
+  bottom: 'top',    // tooltip below → beak at top of tooltip
+  left: 'right',    // tooltip left  → beak at right of tooltip
+  right: 'left',    // tooltip right → beak at left of tooltip
+};
+
+/* ── Placement → absolute position of the tooltip wrapper ────────
+ * The tooltip floats outside the normal flow so the trigger never
+ * moves when the tooltip appears.
+ *
+ * Physical properties are safe here because effectivePlacement has
+ * already been RTL-corrected (left↔right swapped by the component).
+ */
+export const PLACEMENT_ABSOLUTE: Record<HelpIconPlacement, string> = {
+  top: 'absolute bottom-full',   // float above the trigger
+  bottom: 'absolute top-full',   // float below the trigger
+  left: 'absolute right-full',   // float to the left (right edge of tooltip = left edge of trigger)
+  right: 'absolute left-full',   // float to the right
+};
+
+/* ── Align → horizontal offset (top / bottom placements) ─────────
+ * Uses Tailwind logical "start-0" / "end-0" so RTL is handled automatically.
+ * center uses a physical translate because centering is direction-neutral.
+ */
+export const H_ALIGN: Record<HelpIconAlign, string> = {
+  start: 'start-0',
+  center: 'left-1/2 -translate-x-1/2',
+  end: 'end-0',
+};
+
+/* ── Align → vertical offset (left / right placements) ───────────
+ * Vertical alignment is always physical (top/bottom = same in any direction).
+ */
+export const V_ALIGN: Record<HelpIconAlign, string> = {
+  start: 'top-0',
+  center: 'top-1/2 -translate-y-1/2',
+  end: 'bottom-0',
+};
+
+/* ── Align → Tooltip beakAlignment ──────────────────────────────
+ * The Tooltip type spells "center" as "centre".
+ */
+export const ALIGN_TO_BEAK: Record<HelpIconAlign, TooltipBeakAlignment> = {
+  start: 'start',
+  center: 'centre',
+  end: 'end',
+};
+
+/* ── Tooltip max-width ───────────────────────────────────────────
+ * Figma specifies a 240 px max-width for the tooltip popup.
+ * No responsive token maps exactly to this; hardcoded per Figma.
+ */
+export const TOOLTIP_MAX_WIDTH = 'max-w-[240px]';
+
+/* ── Trigger button ──────────────────────────────────────────────
+ * The icon (QuestionMarkIcon) uses `currentColor` for its circle fill,
+ * so the text-* colour here drives the dark circle background:
+ *   light mode → rgba(56,66,80,1)    = Icon/icon-neutral   (#384250)
+ *   dark  mode → rgba(157,164,174,1) = Icon/icon-default-400 (#9DA4AE)
+ */
+export const TRIGGER_BASE = [
+  'inline-flex items-center justify-center shrink-0',
+  'size-[20px]',
+  'cursor-pointer',
+  'rounded-full',
+  'text-[rgba(56,66,80,1)] dark:text-[rgba(157,164,174,1)]',
+  'focus-visible:outline-none',
+  'focus-visible:ring-2 focus-visible:ring-offset-2',
+  'focus-visible:ring-[rgba(27,131,84,1)]',
+].join(' ');

package/src/components/HelpIcon/index.ts

@@ -0,0 +1,2 @@
+export { HelpIcon } from './HelpIcon';
+export type { HelpIconProps, HelpIconPlacement, HelpIconAlign } from './HelpIcon.types';

package/src/components/HorizontalTabs/HorizontalTabs.tsx

@@ -0,0 +1,87 @@
+'use client';
+
+import { forwardRef, useState, useCallback } from 'react';
+import { cn } from '../../lib/cn';
+import { Tab } from '../Tab';
+import type { HorizontalTabsProps } from './HorizontalTabs.types';
+import {
+  ROOT,
+  TYPE_ROOT_CLASSES,
+  TAB_TYPE_MAP,
+  TAB_FILL_MAP,
+} from './HorizontalTabs.variants';
+
+/**
+ * HorizontalTabs — full-width tab bar where every tab fills equally.
+ *
+ * Supports 5 container types (primary, neutral, underline, outline, shadow)
+ * and 3 sizes (sm, md, lg). Composes the shared `Tab` component for each
+ * item. RTL-aware via ambient `dir` — flex order mirrors automatically.
+ *
+ * - `shadow` wraps all tabs in a tinted, bordered container with rounded
+ *   corners and inner padding.
+ * - All other types render a flat container with only spacing between tabs.
+ */
+export const HorizontalTabs = forwardRef<HTMLDivElement, HorizontalTabsProps>(
+  function HorizontalTabs(
+    {
+      items,
+      type = 'primary',
+      size = 'md',
+      value,
+      defaultValue,
+      onValueChange,
+      disabled: groupDisabled = false,
+      className,
+      ...rest
+    },
+    ref,
+  ) {
+    /* ── Selection state (controlled / uncontrolled) ──────── */
+    const isControlled = value !== undefined;
+    const [internal, setInternal] = useState<string | undefined>(
+      defaultValue ?? items[0]?.value,
+    );
+    const selectedValue = isControlled ? value : internal;
+
+    const handleSelect = useCallback(
+      (next: string) => {
+        if (!isControlled) setInternal(next);
+        onValueChange?.(next);
+      },
+      [isControlled, onValueChange],
+    );
+
+    /* ── Resolve inner Tab type from container type ──────── */
+    const tabType = TAB_TYPE_MAP[type];
+
+    return (
+      <div
+        ref={ref}
+        role="tablist"
+        data-slot="horizontal-tabs"
+        data-type={type}
+        className={cn(ROOT, TYPE_ROOT_CLASSES[type], className)}
+        {...rest}
+      >
+        {items.map((item) => {
+          const isSelected = item.value === selectedValue;
+          return (
+            <Tab
+              key={item.value}
+              type={tabType}
+              size={size}
+              selected={isSelected}
+              disabled={groupDisabled || item.disabled}
+              label={item.label ?? item.value}
+              leadingIcon={item.leadingIcon}
+              count={item.count}
+              onClick={() => handleSelect(item.value)}
+              className={TAB_FILL_MAP[type]}
+            />
+          );
+        })}
+      </div>
+    );
+  },
+);

package/src/components/HorizontalTabs/HorizontalTabs.types.ts

@@ -0,0 +1,41 @@
+import type { HTMLAttributes, ReactNode } from 'react';
+import type { TabSize } from '../Tab/Tab.types';
+
+/** Container-level type. Determines both the wrapper styling and the
+ *  inner `Tab` variant used for each item. */
+export type HorizontalTabsType =
+  | 'primary'
+  | 'neutral'
+  | 'underline'
+  | 'shadow'
+  | 'outline';
+
+export interface HorizontalTabItem {
+  /** Stable value used for selection. */
+  value: string;
+  /** Label — defaults to `value` when omitted. */
+  label?: ReactNode;
+  /** Optional leading icon (inline-start). */
+  leadingIcon?: ReactNode;
+  /** Optional count badge. */
+  count?: ReactNode;
+  /** Disable this tab only. */
+  disabled?: boolean;
+}
+
+export interface HorizontalTabsProps extends HTMLAttributes<HTMLDivElement> {
+  /** Tabs to render. */
+  items: HorizontalTabItem[];
+  /** Visual type. */
+  type?: HorizontalTabsType;
+  /** Size of every tab in the group. */
+  size?: TabSize;
+  /** Controlled selected value. */
+  value?: string;
+  /** Uncontrolled initial value. */
+  defaultValue?: string;
+  /** Selection change callback. */
+  onValueChange?: (value: string) => void;
+  /** Disable the entire tab group. */
+  disabled?: boolean;
+}

package/src/components/HorizontalTabs/HorizontalTabs.variants.ts

@@ -0,0 +1,54 @@
+import type { HorizontalTabsType } from './HorizontalTabs.types';
+import type { TabType } from '../Tab/Tab.types';
+
+/* ── Container root ──────────────────────────────────────────── */
+
+/** Base classes shared by all types. */
+export const ROOT = 'flex items-center w-full';
+
+/** Type-specific container wrapper classes.
+ *
+ *  - primary / neutral / underline / outline → flat, gap-xs only.
+ *  - shadow → padded container with bg, border, rounded-12. */
+export const TYPE_ROOT_CLASSES: Record<HorizontalTabsType, string> = {
+  primary: 'gap-spacing-xs',
+  neutral: 'gap-spacing-xs',
+  underline: 'gap-spacing-xs',
+  outline: 'gap-spacing-xs',
+  shadow: [
+    'gap-spacing-xs p-spacing-xs overflow-hidden rounded-[12px]',
+    'bg-[rgba(243,244,246,1)] border border-solid border-[rgba(210,214,219,1)]',
+    'dark:bg-[rgba(31,41,55,1)] dark:border-[rgba(55,65,81,1)]',
+  ].join(' '),
+};
+
+/* ── Tab type mapping ────────────────────────────────────────── */
+
+/** Maps the container-level type to the inner `Tab` component's `type` prop.
+ *  Shadow uses the same green-fill primary tab style inside a tinted container. */
+export const TAB_TYPE_MAP: Record<HorizontalTabsType, TabType> = {
+  primary: 'primary',
+  neutral: 'neutral',
+  underline: 'underline',
+  outline: 'outline',
+  shadow: 'primary',
+};
+
+/* ── Individual tab overrides ────────────────────────────────── */
+
+/**
+ * Tab fill classes per container type.
+ *
+ * - primary / neutral / outline / shadow → each tab grows equally to fill
+ *   the full container width (`flex-1 min-w-0`).
+ * - underline → tabs are content-width and start-aligned (`shrink-0`).
+ *   Stretching underline tabs is incorrect per design — the grey divider
+ *   line spans the full width independently.
+ */
+export const TAB_FILL_MAP: Record<HorizontalTabsType, string> = {
+  primary:  'flex-1 min-w-0',
+  neutral:  'flex-1 min-w-0',
+  underline: 'shrink-0',
+  outline:  'flex-1 min-w-0',
+  shadow:   'flex-1 min-w-0',
+};

package/src/components/HorizontalTabs/index.ts

@@ -0,0 +1,6 @@
+export { HorizontalTabs } from './HorizontalTabs';
+export type {
+  HorizontalTabsProps,
+  HorizontalTabsType,
+  HorizontalTabItem,
+} from './HorizontalTabs.types';

package/src/components/IllustrationInstance/IllustrationInstance.tsx

@@ -0,0 +1,46 @@
+"use client";
+
+import { forwardRef } from "react";
+import { cn } from "../../lib/cn";
+import type { IllustrationInstanceProps } from "./IllustrationInstance.types";
+import { ROOT, TEXT } from "./IllustrationInstance.variants";
+
+const DEFAULT_WIDTH = 215;
+const DEFAULT_HEIGHT = 118;
+
+export const IllustrationInstance = forwardRef<
+  HTMLDivElement,
+  IllustrationInstanceProps
+>(function IllustrationInstance(
+  { width, height, children, className, style, ...rest },
+  ref,
+) {
+  const w = width ?? DEFAULT_WIDTH;
+  const h = height ?? DEFAULT_HEIGHT;
+
+  return (
+    <div
+      ref={ref}
+      data-slot="illustration-instance"
+      className={cn(ROOT, className)}
+      style={{
+        ...style,
+        width: w,
+        /*
+         * Keep the Figma aspect ratio but allow the box to shrink inside
+         * constrained preview containers.
+         */
+        aspectRatio: `${w} / ${h}`,
+        height: "auto",
+        maxWidth: "100%",
+      }}
+      {...rest}
+    >
+      {children ?? (
+        <div data-slot="illustration-instance-text" className={TEXT}>
+          {"Replace with your \nIllustration"}
+        </div>
+      )}
+    </div>
+  );
+});

package/src/components/IllustrationInstance/IllustrationInstance.types.ts

@@ -0,0 +1,25 @@
+import type { CSSProperties, HTMLAttributes, ReactNode } from 'react';
+
+export interface IllustrationInstanceProps extends HTMLAttributes<HTMLDivElement> {
+  /**
+   * Width of the illustration container (in px).
+   * If omitted, falls back to the Figma node default (215 px).
+   */
+  width?: number;
+  /**
+   * Height of the illustration container (in px).
+   * If omitted, falls back to the Figma node default (118 px).
+   */
+  height?: number;
+  /**
+   * Override styles for the root element. Prefer `className` when possible.
+   * Width/height props win over `style.width` / `style.height`.
+   */
+  style?: CSSProperties;
+  /**
+   * Content shown inside the placeholder. When omitted, renders the default
+   * "Replace with your Illustration" message from Figma.
+   */
+  children?: ReactNode;
+}
+

package/src/components/IllustrationInstance/IllustrationInstance.variants.ts

@@ -0,0 +1,19 @@
+/* All class-name constants mapped from Figma node 6503:96064 (_Illustration Instance). */
+
+export const ROOT = [
+  'flex items-center justify-center',
+  'border border-dashed',
+  'border-[rgba(27,131,84,1)]',
+  'bg-[rgba(243,252,246,1)] dark:bg-[rgba(6,118,71,0.1)]',
+  'p-spacing-none',
+  'overflow-hidden',
+].join(' ');
+
+export const TEXT = [
+  /* Figma uses a tiny placeholder style to fit all sizes (e.g. 80×80). */
+  'text-text-2xs font-[400]',
+  'text-center whitespace-pre-line',
+  'max-w-full break-words',
+  'text-[rgba(27,131,84,1)] dark:text-[rgba(52,211,153,1)]',
+].join(' ');
+

package/src/components/IllustrationInstance/index.ts

@@ -0,0 +1,3 @@
+export { IllustrationInstance } from './IllustrationInstance';
+export type { IllustrationInstanceProps } from './IllustrationInstance.types';
+