sdaia-ui 1.0.1

package/src/components/AreaChart/AreaChart.variants.ts

@@ -0,0 +1,202 @@
+/**
+ * AreaChart.variants.ts
+ *
+ * All constants for the AreaChart component.
+ *
+ * ── Color tokens ──────────────────────────────────────────────────────────────
+ *   Series 1  →  rgba(27,131,84,1)    Colors/Primary-SA-Flag/600-primary (green)
+ *   Series 2  →  rgba(165,123,186,1)  Colors/Tertiary-Lavendar/400 (lavender)
+ *   Grid      →  #d2d6db (light) / #374151 (dark) — Border/border-neutral-primary
+ *
+ * ── Spacing (follows BarChart/LineChart pattern) ───────────────────────────────
+ *   gap-spacing-lg  — default root column gap (Detailed Comparison)
+ *   gap-spacing-2xl — root column gap for Insight card
+ *   gap-spacing-md  — y-axis ↔ chart area
+ *   gap-spacing-xs  — chart body items
+ */
+
+import type { XAxisDataType } from '../XAxis/XAxis.types';
+import type { AreaChartInsightRow } from './AreaChart.types';
+
+// ─── Data-viz colours ─────────────────────────────────────────────────────────
+export const SERIES_1_COLOR = 'rgba(27,131,84,1)';
+export const SERIES_2_COLOR = 'rgba(165,123,186,1)';
+
+// ─── Chart heights ─────────────────────────────────────────────────────────────
+export const DEFAULT_HEIGHTS: Record<XAxisDataType, number> = {
+  '3 Days':      260,
+  '5 Work Days': 280,
+  '7 Week Days': 320,
+  '12 Months':   390,
+} as const;
+
+/** Default root height for `type="Insight"` — Figma: 600 × 440 px. */
+export const INSIGHT_DEFAULT_HEIGHT = 440;
+
+// ─── Shared full-chart layout ──────────────────────────────────────────────────
+export const CHART_BODY      = 'flex flex-col gap-spacing-xs flex-1 min-h-0 w-full';
+export const Y_AND_AREA_ROW  = 'flex gap-spacing-md flex-1 min-h-0 w-full';
+export const AREA_WRAPPER    =
+  'relative flex flex-col justify-between pt-spacing-md pb-0 flex-1 min-h-0 min-w-0';
+
+// ─── Grid line (match LineChart: dashed mid/top, solid baseline) ───────────────
+/** 5px dash, 4px gap (9px period) */
+export const GRID_LINE =
+  'w-full h-px shrink-0 bg-[repeating-linear-gradient(to_right,#d2d6db_0_5px,transparent_5px_9px)] dark:bg-[repeating-linear-gradient(to_right,#374151_0_5px,transparent_5px_9px)]';
+
+/** Bottom horizontal baseline — solid; `pb-0` on AREA_WRAPPER aligns SVG fill to this edge */
+export const GRID_LINE_BASELINE =
+  'w-full h-0 shrink-0 border-t border-solid border-[#d2d6db] dark:border-[#374151]';
+
+// ─── SVG overlay ──────────────────────────────────────────────────────────────
+export const SVG_OVERLAY = 'absolute inset-0 w-full h-full overflow-visible';
+
+// ─── Detailed Comparison root ─────────────────────────────────────────────────
+/** Flex column used for the full-chart types (Detailed Comparison). */
+export const COMPARISON_ROOT = 'flex flex-col gap-spacing-lg items-end w-full';
+
+// ─── Card base (shared by Metric, Summary, Insight) ───────────────────────────
+/** White card background + 8 px radius — same as Figma `background-card` / `radius-8`. */
+export const CARD_BASE =
+  'bg-white dark:bg-[rgba(31,42,55,1)] rounded-[8px]';
+
+// ─── Metric layout ────────────────────────────────────────────────────────────
+// Figma node 5975:83019 — 240 × 96 px KPI card.
+// Root: flex row, items-end (text left, sparkline right, bottom-aligned).
+
+export const METRIC_ROOT = 'flex items-end w-full p-spacing-xl';
+export const METRIC_TEXT_COL = 'flex flex-col gap-spacing-xs shrink-0';
+
+// ─── Summary layout ───────────────────────────────────────────────────────────
+// Figma node 5975:83029 — 240 × 92 px KPI card.
+// Root: flex column, two rows stacked.
+
+export const SUMMARY_ROOT   = 'flex flex-col w-full p-spacing-xl';
+export const SUMMARY_TOP    = 'flex items-center justify-between w-full shrink-0';
+export const SUMMARY_BOTTOM = 'flex flex-1 gap-spacing-3xl items-end min-h-px w-full';
+
+// ─── KPI text classes (Metric + Summary) ──────────────────────────────────────
+// Figma: Text lg/Regular (typo-size-text-Ig = 18px desktop) for the label.
+export const KPI_LABEL =
+  'shrink-0 text-text-lg font-[400] leading-[28px] whitespace-nowrap ' +
+  'text-[rgba(108,115,127,1)] dark:text-[rgba(156,163,175,1)]';
+
+// Figma: Display xs/Bold (typo-size-display-xs = 24px desktop) for the value.
+export const KPI_VALUE =
+  'shrink-0 text-display-xs font-[700] leading-[32px] ' +
+  'text-[rgba(22,22,22,1)] dark:text-[rgba(242,244,247,1)]';
+
+// ─── Insight root ─────────────────────────────────────────────────────────────
+// Figma node 5975:82879 — 600 × 440 px full card.
+// gap-spacing-2xl = 20 px between tabs / content wrapper / chart / legend.
+export const INSIGHT_ROOT =
+  'flex flex-col gap-spacing-2xl items-end p-spacing-xl rounded-[8px] w-full ' +
+  'bg-white dark:bg-[rgba(31,42,55,1)]';
+
+// ─── Insight content wrapper (two metric rows) ─────────────────────────────────
+// Figma: flex-wrap row, gap-y = 20 px, justify-between.
+export const INSIGHT_WRAPPER =
+  'flex flex-wrap gap-y-5 items-center justify-between w-full shrink-0';
+
+// Each row: label on start edge, [value + badge] on end — gap-spacing-4xl (32 px).
+export const INSIGHT_CONTENT_ROW =
+  'flex flex-1 gap-spacing-4xl items-center min-w-[200px] px-spacing-xl';
+
+// Figma: Text lg/Medium (18 px, weight 500) in secondary-paragraph colour.
+export const INSIGHT_ROW_LABEL =
+  'shrink-0 text-text-lg font-[500] leading-[28px] whitespace-nowrap ' +
+  'text-[rgba(108,115,127,1)] dark:text-[rgba(156,163,175,1)]';
+
+// Inline group: value + ChartBadge, 8 px gap.
+export const INSIGHT_VALUE_BADGE = 'flex gap-spacing-md items-center shrink-0';
+
+// Figma: Text md/Bold (16 px, weight 700) in text-default colour.
+export const INSIGHT_ROW_VALUE =
+  'shrink-0 text-text-md font-[700] leading-[24px] whitespace-nowrap ' +
+  'text-[rgba(22,22,22,1)] dark:text-[rgba(242,244,247,1)]';
+
+// ─── Insight bottom legend ────────────────────────────────────────────────────
+// Figma: centered row, gap-spacing-2xl (20 px) between legend items.
+export const INSIGHT_LEGEND =
+  'flex gap-spacing-2xl items-center justify-center w-full shrink-0';
+
+export const INSIGHT_LEGEND_ITEM = 'flex gap-spacing-md items-center shrink-0';
+
+// 16 × 16 px icon wrapper — Figma: size-[16px] minus-sign icon.
+export const INSIGHT_LEGEND_ICON =
+  'shrink-0 size-[16px] inline-flex items-center justify-center ' +
+  '[&>svg]:w-full [&>svg]:h-full';
+
+// Figma: Text md/Regular (16 px, weight 400) in text-default colour.
+export const INSIGHT_LEGEND_LABEL =
+  'shrink-0 text-text-md font-[400] leading-[24px] whitespace-nowrap ' +
+  'text-[rgba(22,22,22,1)] dark:text-[rgba(242,244,247,1)]';
+
+// ─── Default data (values in 0–100 normalised range) ──────────────────────────
+
+export const DEFAULT_DATA = {
+  /** Insight — dual-series, 12 data points to match the 12-month X-axis. */
+  Insight: {
+    series1: [38, 55, 46, 64, 56, 74, 68, 80, 62, 76, 58, 88],
+    series2: [20, 48, 72, 32, 58, 22, 82, 38, 66, 28, 55, 44],
+  },
+  'Detailed Comparison': {
+    series1: [38, 55, 46, 64, 56, 74, 68],
+    series2: [22, 30, 44, 34, 50, 42, 54],
+  },
+  Metric: {
+    series1: [40, 52, 48, 66, 60, 76, 72],
+  },
+  Summary: {
+    series1: [35, 52, 44, 62, 55],
+  },
+} as const;
+
+/** Default insight rows shown when `insightRows` prop is not provided. */
+export const DEFAULT_INSIGHT_ROWS: AreaChartInsightRow[] = [
+  { label: 'Text', value: '422.61', badgeType: 'increase', badgeValue: '12%' },
+  { label: 'Text', value: '422.61', badgeType: 'increase', badgeValue: '12%' },
+];
+
+// ─── SVG helpers ──────────────────────────────────────────────────────────────
+
+/**
+ * Convert normalised values (0=bottom, 100=top) to an SVG polyline `points`
+ * string for a viewBox of "0 0 100 100".
+ */
+export function toPolylinePoints(
+  values: readonly number[],
+  totalPoints: number,
+  startIndex = 0,
+): string {
+  return values
+    .map((val, i) => {
+      const x = ((startIndex + i) / (totalPoints - 1)) * 100;
+      const y = 100 - val;
+      return `${x.toFixed(2)},${y.toFixed(2)}`;
+    })
+    .join(' ');
+}
+
+/**
+ * Build an SVG polygon that fills the area under a line.
+ * Closes along y=100 (bottom edge of the viewBox).
+ */
+export function toAreaFillPoints(
+  values: readonly number[],
+  totalPoints: number,
+): string {
+  const topEdge = toPolylinePoints(values, totalPoints);
+  const rightX  = ((values.length - 1) / (totalPoints - 1)) * 100;
+  return `${topEdge} ${rightX.toFixed(2)},100 0.00,100`;
+}
+
+/** SVG x for point at `index` of `totalPoints` (0–100 space). */
+export function getPointX(index: number, totalPoints: number): number {
+  return (index / (totalPoints - 1)) * 100;
+}
+
+/** SVG y for a normalised value (0=bottom → 100, 100=top → 0). */
+export function getPointY(value: number): number {
+  return 100 - value;
+}

package/src/components/AreaChart/index.ts

@@ -0,0 +1,2 @@
+export { AreaChart } from './AreaChart';
+export type { AreaChartProps, AreaChartType, AreaChartInsightRow } from './AreaChart.types';

package/src/components/AspectRatio/AspectRatio.tsx

@@ -0,0 +1,36 @@
+'use client';
+
+import { forwardRef } from 'react';
+import { cn } from '../../lib/cn';
+import type { AspectRatioProps } from './AspectRatio.types';
+import { BASE, RATIO_CLASSES } from './AspectRatio.variants';
+
+/**
+ * AspectRatio
+ *
+ * A layout container that enforces a fixed aspect ratio on its children.
+ * Place any content (image, video, map, etc.) inside — it will be clipped
+ * to the chosen ratio with rounded corners matching the design system.
+ *
+ * Children are responsible for filling the slot:
+ *   - Use `className="absolute inset-0 w-full h-full object-cover"` on <img>.
+ *   - Use `fill` + `className="object-cover"` on Next.js <Image>.
+ *
+ * RTL: aspect-ratio is direction-agnostic — no RTL handling needed.
+ * Dark mode: the container itself has no background — children handle theming.
+ */
+export const AspectRatio = forwardRef<HTMLDivElement, AspectRatioProps>(
+  function AspectRatio({ ratio = '16:9', children, className, ...rest }, ref) {
+    return (
+      <div
+        ref={ref}
+        data-slot="aspect-ratio"
+        data-ratio={ratio}
+        className={cn(BASE, RATIO_CLASSES[ratio], className)}
+        {...rest}
+      >
+        {children}
+      </div>
+    );
+  },
+);

package/src/components/AspectRatio/AspectRatio.types.ts

@@ -0,0 +1,33 @@
+import type { HTMLAttributes, ReactNode } from 'react';
+
+/**
+ * All aspect ratios supported by the design system.
+ * Derived from the Figma _aspectRatio reference frame (node 6691:96263).
+ */
+export type AspectRatioValue =
+  | '1:1'
+  | '5:4'
+  | '4:3'
+  | '3:2'
+  | '16:10'
+  | '2:1'
+  | '21:9'
+  | '5:2'
+  | '8:3'
+  | '8:5'
+  | '16:9'
+  | '4:5'
+  | '3:4'
+  | '2:3'
+  | '10:16'
+  | '9:16';
+
+export interface AspectRatioProps extends HTMLAttributes<HTMLDivElement> {
+  /**
+   * The aspect ratio to enforce on the container.
+   * Children are expected to use `object-cover` / `object-contain` and fill the slot.
+   * @default "16:9"
+   */
+  ratio?: AspectRatioValue;
+  children?: ReactNode;
+}

package/src/components/AspectRatio/AspectRatio.variants.ts

@@ -0,0 +1,42 @@
+/* ─────────────────────────────────────────────────────────────────
+   AspectRatio.variants.ts
+   Class-name constants for the AspectRatio container.
+   Derived from Figma node 6691:96263 (_aspectRatio reference frame).
+   No JSX / React imports — pure strings.
+──────────────────────────────────────────────────────────────────── */
+
+import type { AspectRatioValue } from './AspectRatio.types';
+
+/**
+ * Base classes applied to every AspectRatio container.
+ * - overflow-hidden: clips children that overflow (e.g. zoomed images).
+ * - rounded-[4px]:  Figma variable Radius/radius-4 = 4 px. No design-system
+ *                   token exists for this exact radius value, so it is
+ *                   hardcoded as a one-off per the build guide rule.
+ * - w-full:         Width is always controlled by the parent container.
+ */
+export const BASE = 'relative overflow-hidden rounded-[4px] w-full';
+
+/**
+ * CSS aspect-ratio class per ratio value.
+ * Uses Tailwind arbitrary-value syntax: aspect-[w/h].
+ * TypeScript Record<AspectRatioValue, string> guarantees every ratio has a class.
+ */
+export const RATIO_CLASSES: Record<AspectRatioValue, string> = {
+  '1:1':   'aspect-[1/1]',
+  '5:4':   'aspect-[5/4]',
+  '4:3':   'aspect-[4/3]',
+  '3:2':   'aspect-[3/2]',
+  '16:10': 'aspect-[16/10]',
+  '2:1':   'aspect-[2/1]',
+  '21:9':  'aspect-[21/9]',
+  '5:2':   'aspect-[5/2]',
+  '8:3':   'aspect-[8/3]',
+  '8:5':   'aspect-[8/5]',
+  '16:9':  'aspect-[16/9]',
+  '4:5':   'aspect-[4/5]',
+  '3:4':   'aspect-[3/4]',
+  '2:3':   'aspect-[2/3]',
+  '10:16': 'aspect-[10/16]',
+  '9:16':  'aspect-[9/16]',
+};

package/src/components/AspectRatio/index.ts

@@ -0,0 +1,2 @@
+export { AspectRatio } from './AspectRatio';
+export type { AspectRatioProps, AspectRatioValue } from './AspectRatio.types';

package/src/components/AudioPlayer/AudioPlayer.tsx

@@ -0,0 +1,294 @@
+'use client';
+
+import { forwardRef, useCallback, useState } from 'react';
+import { cn } from '../../lib/cn';
+import {
+  AUDIO_NAME,
+  BTN_HOVER,
+  CONTAINER_BG,
+  CONTAINER_COMPACT,
+  CONTAINER_DETAILED,
+  CONTROLS_ROW,
+  CTRL_BTN,
+  FILL_BG,
+  FOCUS_RING,
+  ICON_BTN_SIZE,
+  ICON_COLOR,
+  NAME_TEXT_COLOR,
+  PLAY_BTN_SIZE,
+  PLAY_BUTTONS_GROUP,
+  PROGRESS_CONTAINER_COMPACT,
+  PROGRESS_CONTAINER_DETAILED,
+  PROGRESS_FILL,
+  PROGRESS_TRACK,
+  RIGHT_BUTTONS_GROUP,
+  TIME_TEXT,
+  TIME_TEXT_COLOR,
+  TRACK_BG,
+} from './AudioPlayer.variants';
+import {
+  GoBackward10Icon,
+  GoForward10Icon,
+  PauseIcon,
+  PlayIcon,
+  SettingsIcon,
+  VolumeHighIcon,
+} from '../../icons/IconFactory';
+import type { AudioPlayerProps, AudioPlayerStyle } from './AudioPlayer.types';
+
+/* ── Internal sub-components ─────────────────────────────────────── */
+
+/** Icon button — inherits style-based color, hover, and focus ring. */
+function CtrlBtn({
+  label,
+  size,
+  styleKey,
+  onClick,
+  children,
+}: {
+  label: string;
+  size: string;
+  styleKey: AudioPlayerStyle;
+  onClick?: () => void;
+  children: React.ReactNode;
+}) {
+  return (
+    <button
+      type="button"
+      aria-label={label}
+      className={cn(CTRL_BTN, size, BTN_HOVER, FOCUS_RING[styleKey], ICON_COLOR[styleKey])}
+      onClick={onClick}
+    >
+      {children}
+    </button>
+  );
+}
+
+/** Scrubable progress bar — accepts a container class for compact vs detailed sizing. */
+function ProgressBar({
+  progress,
+  currentTime,
+  duration,
+  styleKey,
+  containerClass,
+  onProgressChange,
+}: {
+  progress: number;
+  currentTime: string;
+  duration: string;
+  styleKey: AudioPlayerStyle;
+  containerClass: string;
+  onProgressChange?: (value: number) => void;
+}) {
+  const clamped = Math.min(100, Math.max(0, progress));
+
+  return (
+    <div
+      data-slot="progress"
+      className={containerClass}
+      role="group"
+      aria-label="Playback progress"
+    >
+      <div className={cn(PROGRESS_TRACK, TRACK_BG[styleKey])} aria-hidden="true" />
+      <div
+        className={cn(PROGRESS_FILL, FILL_BG[styleKey])}
+        style={{ width: `${clamped}%` }}
+        aria-hidden="true"
+      />
+      {/* Transparent range input for accessible scrubbing */}
+      <input
+        type="range"
+        min={0}
+        max={100}
+        step={0.1}
+        value={clamped}
+        onChange={(e) => onProgressChange?.(Number(e.target.value))}
+        aria-label="Playback progress"
+        aria-valuetext={`${currentTime} of ${duration}`}
+        dir="ltr"
+        className="absolute inset-0 w-full opacity-0 cursor-pointer"
+      />
+    </div>
+  );
+}
+
+/* ── AudioPlayer ──────────────────────────────────────────────────── */
+export const AudioPlayer = forwardRef<HTMLDivElement, AudioPlayerProps>(
+  function AudioPlayer(
+    {
+      type = 'compact',
+      style = 'transparent',
+      playing: playingProp,
+      defaultPlaying = false,
+      progress: progressProp,
+      defaultProgress = 0,
+      currentTime = '0:00',
+      duration = '0:00',
+      audioName,
+      onPlay,
+      onPause,
+      onSkipBack,
+      onSkipForward,
+      onProgressChange,
+      onVolumeClick,
+      onSettingsClick,
+      className,
+      ...rest
+    },
+    ref,
+  ) {
+    /* ── Playing state (controlled / uncontrolled) ───────────────── */
+    const isPlayingControlled = playingProp !== undefined;
+    const [internalPlaying, setInternalPlaying] = useState(defaultPlaying);
+    const isPlaying = isPlayingControlled ? playingProp! : internalPlaying;
+
+    /* ── Progress state (controlled / uncontrolled) ──────────────── */
+    const isProgressControlled = progressProp !== undefined;
+    const [internalProgress, setInternalProgress] = useState(defaultProgress);
+    const currentProgress = isProgressControlled ? progressProp! : internalProgress;
+
+    /* ── Handlers ────────────────────────────────────────────────── */
+    const handlePlay = useCallback(() => {
+      if (!isPlayingControlled) setInternalPlaying(true);
+      onPlay?.();
+    }, [isPlayingControlled, onPlay]);
+
+    const handlePause = useCallback(() => {
+      if (!isPlayingControlled) setInternalPlaying(false);
+      onPause?.();
+    }, [isPlayingControlled, onPause]);
+
+    const handleProgressChange = useCallback(
+      (value: number) => {
+        if (!isProgressControlled) setInternalProgress(value);
+        onProgressChange?.(value);
+      },
+      [isProgressControlled, onProgressChange],
+    );
+
+    /* ── Play/Pause toggle ───────────────────────────────────────── */
+    const playPauseBtn = isPlaying ? (
+      <CtrlBtn label="Pause" size={PLAY_BTN_SIZE} styleKey={style} onClick={handlePause}>
+        <PauseIcon />
+      </CtrlBtn>
+    ) : (
+      <CtrlBtn label="Play" size={PLAY_BTN_SIZE} styleKey={style} onClick={handlePlay}>
+        <PlayIcon />
+      </CtrlBtn>
+    );
+
+    /* ── Left play buttons group ─────────────────────────────────── */
+    const playGroup = (
+      <div data-slot="play-buttons" className={PLAY_BUTTONS_GROUP}>
+        <CtrlBtn label="Go backward 10 seconds" size={ICON_BTN_SIZE} styleKey={style} onClick={onSkipBack}>
+          <GoBackward10Icon />
+        </CtrlBtn>
+        {playPauseBtn}
+        <CtrlBtn label="Go forward 10 seconds" size={ICON_BTN_SIZE} styleKey={style} onClick={onSkipForward}>
+          <GoForward10Icon />
+        </CtrlBtn>
+      </div>
+    );
+
+    /* ── Right buttons group ─────────────────────────────────────── */
+    const rightGroup = (
+      <div data-slot="right-buttons" className={RIGHT_BUTTONS_GROUP}>
+        <CtrlBtn label="Volume" size={ICON_BTN_SIZE} styleKey={style} onClick={onVolumeClick}>
+          <VolumeHighIcon />
+        </CtrlBtn>
+        <CtrlBtn label="Settings" size={ICON_BTN_SIZE} styleKey={style} onClick={onSettingsClick}>
+          <SettingsIcon />
+        </CtrlBtn>
+      </div>
+    );
+
+    /* ── Time display ────────────────────────────────────────────── */
+    const timeDisplay = (
+      <p
+        data-slot="time"
+        className={cn(TIME_TEXT, TIME_TEXT_COLOR[style])}
+        aria-live="off"
+      >
+        {currentTime}&nbsp;/&nbsp;{duration}
+      </p>
+    );
+
+    /* ─────────────────────────────────────────────────────────────
+       All controls share dir="ltr" — universal media-player convention.
+       Video player controls stay LTR even in RTL layouts, confirmed by
+       identical Figma RTL/LTR frames.
+    ──────────────────────────────────────────────────────────────── */
+
+    /* ── Compact layout ──────────────────────────────────────────── */
+    /* Single row: play-group | time | progress(flex-1) | right-group */
+    if (type === 'compact') {
+      return (
+        <div
+          ref={ref}
+          data-slot="audio-player"
+          data-type="compact"
+          data-style={style}
+          className={cn(CONTAINER_COMPACT, CONTAINER_BG[style], className)}
+          dir="ltr"
+          {...rest}
+        >
+          {playGroup}
+          {timeDisplay}
+          <ProgressBar
+            progress={currentProgress}
+            currentTime={currentTime}
+            duration={duration}
+            styleKey={style}
+            containerClass={PROGRESS_CONTAINER_COMPACT}
+            onProgressChange={handleProgressChange}
+          />
+          {rightGroup}
+        </div>
+      );
+    }
+
+    /* ── Detailed layout ─────────────────────────────────────────── */
+    /*
+      Row 1: play-group | time | audio-name(flex-1) | right-group
+      Row 2: full-width progress bar
+    */
+    return (
+      <div
+        ref={ref}
+        data-slot="audio-player"
+        data-type="detailed"
+        data-style={style}
+        className={cn(CONTAINER_DETAILED, CONTAINER_BG[style], className)}
+        dir="ltr"
+        {...rest}
+      >
+        {/* Row 1 — controls + audio name ──────────────────────────── */}
+        <div data-slot="controls-row" className={CONTROLS_ROW} dir="ltr">
+          {playGroup}
+          {timeDisplay}
+
+          {/* Audio name — dir="auto" lets Arabic text self-detect direction */}
+          <p
+            data-slot="audio-name"
+            dir="auto"
+            className={cn(AUDIO_NAME, NAME_TEXT_COLOR[style])}
+          >
+            {audioName ?? ''}
+          </p>
+
+          {rightGroup}
+        </div>
+
+        {/* Row 2 — full-width progress bar ────────────────────────── */}
+        <ProgressBar
+          progress={currentProgress}
+          currentTime={currentTime}
+          duration={duration}
+          styleKey={style}
+          containerClass={PROGRESS_CONTAINER_DETAILED}
+          onProgressChange={handleProgressChange}
+        />
+      </div>
+    );
+  },
+);

package/src/components/AudioPlayer/AudioPlayer.types.ts

@@ -0,0 +1,64 @@
+import type { HTMLAttributes } from 'react';
+
+/** Visual style of the audio player shell. */
+export type AudioPlayerStyle = 'transparent' | 'neutral' | 'brand';
+
+/**
+ * Layout variant.
+ * - compact  — single row; controls + progress inline (616×56 Figma frame)
+ * - detailed — two rows; audio name on top, progress + controls below (504×72 Figma frame)
+ */
+export type AudioPlayerType = 'compact' | 'detailed';
+
+export interface AudioPlayerProps extends Omit<HTMLAttributes<HTMLDivElement>, 'style'> {
+  /** Layout variant. Default: 'compact'. */
+  type?: AudioPlayerType;
+  /** Visual style. Default: 'transparent'. */
+  style?: AudioPlayerStyle;
+
+  /**
+   * Whether the player is playing (controlled).
+   * Omit to let the component manage its own state.
+   */
+  playing?: boolean;
+  /** Initial playing state when uncontrolled. Default: false. */
+  defaultPlaying?: boolean;
+
+  /**
+   * Playback progress 0–100 (controlled).
+   * Omit to let the component manage its own progress.
+   */
+  progress?: number;
+  /** Initial progress value when uncontrolled. Default: 0. */
+  defaultProgress?: number;
+
+  /** Current-time display string, e.g. "0:12". */
+  currentTime?: string;
+  /** Total-duration display string, e.g. "2:32". */
+  duration?: string;
+
+  /**
+   * Audio track / episode name.
+   * Shown in the detailed variant only.
+   * Uses dir="auto" so Arabic text self-detects direction.
+   */
+  audioName?: string;
+
+  /** Called when the user requests playback to start. */
+  onPlay?: () => void;
+  /** Called when the user requests playback to pause. */
+  onPause?: () => void;
+  /** Called when the skip-back button is clicked. */
+  onSkipBack?: () => void;
+  /** Called when the skip-forward button is clicked. */
+  onSkipForward?: () => void;
+  /**
+   * Called when the user scrubs the progress bar.
+   * Receives the new value in the range 0–100.
+   */
+  onProgressChange?: (value: number) => void;
+  /** Called when the volume button is clicked. */
+  onVolumeClick?: () => void;
+  /** Called when the settings button is clicked. */
+  onSettingsClick?: () => void;
+}