@bug-on/md3-react 2.0.3 → 3.0.0

package/src/ui/loading-indicator.tsx

@@ -0,0 +1,312 @@
+"use client";
+
+import * as React from "react";
+import { cn } from "../lib/utils";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// MD3 Expressive Loading Indicator
+//
+// Spec references:
+//   • Loading Indicator Overview  (190326 PDF)
+//   • Loading Indicator Specs     (190326 PDF)
+//   • Loading Indicator Accessibility (190326 PDF)
+//   • LoadingIndicator.kt (Android reference)
+//
+// Two operational modes:
+//   1. Indeterminate  — no `progress` prop → 7-shape morph + SMIL rotation loop
+//   2. Determinate    — `progress` (0-1)  → Circle→SoftBurst morph + counterclockwise rotation
+//
+// Responsive sizing: strictly [24dp, 240dp]. Container/indicator ratio is preserved.
+// ─────────────────────────────────────────────────────────────────────────────
+
+// ─── Indeterminate: Shape & Rotation Keyframe Data (from official MD3 SVG) ──
+const SHAPE_KEY_TIMES =
+	"0; 0.14; 0.14; 0.29; 0.29; 0.43; 0.43; 0.57; 0.57; 0.71; 0.71; 0.86; 0.86; 1";
+
+const SHAPE_KEY_SPLINES = [
+	"0.5 0.2 0 0.8",
+	"0.5 0.2 0 0.8",
+	"0.5 0.2 0 0.8",
+	"0.5 0.2 0 0.8",
+	"0.5 0.2 0 0.8",
+	"0.5 0.2 0 0.8",
+	"0.5 0.2 0 0.8",
+	"0.5 0.2 0 0.8",
+	"0.5 0.2 0 0.8",
+	"0.5 0.2 0 0.8",
+	"0.5 0.2 0 0.8",
+	"0.5 0.2 0 0.8",
+	"0.5 0.2 0 0.8",
+].join("; ");
+
+// 7 MD3 morphing shapes, each repeated twice for a smooth hold-and-morph
+const SHAPE_VALUES = [
+	"M20.9 10.4 21.4 9.5 21.9 8.7 22.5 7.8 23.2 7.2 24.2 7 25.1 7.4 25.7 8.1 26.2 9 26.8 9.8 27.3 10.6 28.1 11.2 29 11.3 30 11 30.9 10.6 31.8 10.3 32.8 9.9 33.7 10 34.5 10.6 34.9 11.5 34.8 12.5 34.8 13.5 34.7 14.5 34.7 15.5 35.2 16.3 36 16.8 37 17.1 37.9 17.3 38.9 17.5 39.8 17.9 40.4 18.7 40.5 19.7 40 20.5 39.4 21.3 38.7 22 38.1 22.8 37.6 23.7 37.7 24.6 38.3 25.5 38.9 26.2 39.6 27 40.2 27.7 40.5 28.7 40.3 29.6 39.5 30.3 38.6 30.6 37.6 30.8 36.7 31 35.7 31.3 35 31.9 34.6 32.8 34.7 33.8 34.8 34.8 34.9 35.8 34.8 36.8 34.3 37.6 33.4 38.1 32.4 38 31.5 37.6 30.6 37.2 29.7 36.9 28.7 36.6 27.8 36.9 27.1 37.6 26.6 38.5 26.1 39.3 25.5 40.2 24.8 40.8 23.8 41 22.9 40.6 22.3 39.9 21.8 39 21.2 38.2 20.7 37.4 19.9 36.8 19 36.7 18 37 17.1 37.4 16.2 37.7 15.2 38.1 14.3 38 13.5 37.4 13.1 36.5 13.2 35.5 13.2 34.5 13.3 33.5 13.3 32.5 12.8 31.7 12 31.2 11 31 10.1 30.7 9.1 30.5 8.2 30.1 7.6 29.3 7.5 28.3 8 27.5 8.7 26.7 9.3 26 9.9 25.2 10.4 24.3 10.3 23.4 9.7 22.5 9.1 21.8 8.4 21 7.8 20.3 7.5 19.3 7.7 18.4 8.5 17.7 9.4 17.4 10.4 17.2 11.3 17 12.3 16.7 13 16.1 13.4 15.2 13.3 14.2 13.2 13.2 13.1 12.2 13.2 11.2 13.7 10.4 14.6 9.9 15.6 10 16.5 10.4 17.4 10.8 18.3 11.1 19.3 11.4 20.2 11.1Z",
+	"M20.3 8.6 21.1 8 22 7.6 23 7.3 23 7.3 24 7.2 25 7.3 25.9 7.5 26.8 8 27.6 8.6 28.4 9.1 28.4 9.1 29.3 9.6 30.3 9.8 31.3 9.9 32.3 10 33.3 10.2 34.2 10.6 34.2 10.6 35 11.2 35.7 11.9 36.3 12.7 36.7 13.6 36.9 14.6 37.2 15.5 37.2 15.5 37.6 16.5 38.2 17.3 38.9 18 39.6 18.7 40.2 19.5 40.6 20.4 40.6 20.4 40.9 21.3 41 22.3 40.9 23.3 40.6 24.3 40.2 25.2 39.8 26.1 39.8 26.1 39.5 27 39.4 28 39.5 29 39.6 30 39.5 31 39.3 32 39.3 32 38.9 32.9 38.3 33.7 37.6 34.4 36.8 35 35.9 35.4 35 35.8 35 35.8 34.1 36.3 33.4 37 32.9 37.9 32.3 38.7 31.6 39.4 30.8 40 30.8 40 29.9 40.4 28.9 40.7 27.9 40.8 27 40.7 26 40.4 25 40.1 25 40.1 24 40 23 40.1 22.1 40.4 21.1 40.7 20.1 40.8 19.1 40.7 19.1 40.7 18.2 40.5 17.3 40 16.4 39.5 15.7 38.8 15.2 37.9 14.6 37.1 14.6 37.1 13.9 36.4 13.1 35.8 12.2 35.4 11.3 35 10.5 34.4 9.7 33.8 9.7 33.8 9.1 32.9 8.7 32 8.5 31.1 8.4 30.1 8.5 29.1 8.6 28.1 8.6 28.1 8.5 27.1 8.3 26.1 7.8 25.2 7.4 24.3 7.1 23.4 7 22.4 7 22.4 7.1 21.4 7.3 20.4 7.8 19.5 8.3 18.7 9.1 18 9.8 17.3 9.8 17.3 10.4 16.5 10.8 15.6 11 14.6 11.3 13.7 11.7 12.8 12.2 11.9 12.2 11.9 12.9 11.2 13.8 10.7 14.7 10.2 15.6 10 16.6 9.9 17.6 9.8 17.6 9.8 18.6 9.6 19.5 9.2Z",
+	"M18.6 9.6 19.5 9.2 20.3 8.6 21.1 8 22 7.6 23 7.3 24 7.2 25 7.3 25.9 7.5 26.8 8 27.6 8.6 28.4 9.1 29.3 9.6 30.3 9.8 31.3 9.9 32.3 10 33.3 10.2 34.2 10.6 35 11.2 35.7 11.9 36.3 12.7 36.7 13.6 36.9 14.6 37.2 15.5 37.6 16.4 38.2 17.3 38.9 18 39.6 18.7 40.2 19.5 40.6 20.4 40.9 21.3 41 22.3 40.9 23.3 40.6 24.3 40.2 25.2 39.8 26.1 39.5 27 39.4 28 39.5 29 39.6 30 39.5 31 39.3 32 38.9 32.9 38.3 33.7 37.6 34.4 36.8 35 35.9 35.4 35 35.8 34.1 36.3 33.4 37 32.9 37.9 32.3 38.7 31.6 39.4 30.8 40 29.9 40.4 28.9 40.7 27.9 40.8 27 40.7 26 40.4 25 40.1 24 40 23 40.1 22.1 40.4 21.1 40.7 20.1 40.8 19.1 40.7 18.2 40.5 17.3 40 16.4 39.5 15.7 38.8 15.2 37.9 14.6 37.1 13.9 36.4 13.1 35.8 12.2 35.4 11.3 35 10.5 34.4 9.7 33.8 9.1 32.9 8.7 32 8.5 31.1 8.4 30.1 8.5 29.1 8.6 28.1 8.5 27.1 8.3 26.1 7.8 25.2 7.4 24.3 7.1 23.4 7 22.4 7.1 21.4 7.3 20.4 7.8 19.5 8.3 18.7 9.1 18 9.8 17.3 10.4 16.5 10.8 15.6 11 14.6 11.3 13.7 11.7 12.8 12.2 11.9 12.9 11.2 13.8 10.7 14.7 10.2 15.6 10 16.6 9.9 17.6 9.8Z",
+	"M18.6 9.9 19.5 9.4 20.3 8.8 21.1 8.2 22 7.8 23 7.6 23.9 7.5 24.9 7.6 25.9 7.8 26.8 8.2 27.6 8.7 28.5 9.3 29.3 9.9 30.1 10.5 30.9 11 31.7 11.6 32.5 12.2 33.3 12.8 33.7 13.1 34.1 13.3 34.9 13.9 35.7 14.5 36.6 15 37.4 15.6 38.2 16.2 39 16.8 39.7 17.5 40.2 18.3 40.7 19.2 40.9 20.1 41 21.1 40.9 22.1 40.7 23.1 40.3 24 40 24.9 39.7 25.9 39.4 26.8 39 27.8 38.7 28.7 38.4 29.6 38.1 30.6 37.8 31.5 37.5 32.5 37.2 33.4 36.9 34.4 36.6 35.3 36.2 36.2 35.7 37.1 35 37.8 34.3 38.4 33.4 38.9 32.5 39.3 31.5 39.5 30.5 39.5 30 39.5 29.5 39.5 28.5 39.5 27.5 39.5 26.5 39.5 25.5 39.4 24.5 39.4 23.6 39.4 22.6 39.4 21.6 39.5 20.6 39.5 19.6 39.5 18.6 39.5 17.6 39.5 16.6 39.5 15.6 39.3 14.7 39 13.8 38.5 13.1 37.9 12.4 37.2 11.9 36.3 11.5 35.4 11.2 34.5 10.9 33.5 10.6 32.6 10.3 31.6 10 30.7 9.7 29.7 9.3 28.8 9 27.9 8.7 26.9 8.4 26 8 25 7.7 24.1 7.4 23.2 7.1 22.2 7.1 21.7 7 21.2 7.1 20.2 7.3 19.3 7.7 18.4 8.3 17.5 8.9 16.8 9.7 16.2 10.5 15.6 11.4 15.1 12.2 14.5 13 14 13.8 13.4 14.6 12.8 15.4 12.3 16.2 11.7 17 11.1 17.8 10.5Z",
+	"M15.4 12.3 16.2 11.7 17 11.1 17.8 10.5 18.6 9.9 19.5 9.4 20.3 8.8 21.1 8.3 22 7.8 23 7.6 23.9 7.5 24.9 7.6 25.9 7.8 26.8 8.2 27.6 8.7 28.5 9.3 29.3 9.9 30.1 10.5 30.9 11 31.7 11.6 32.5 12.2 33.3 12.8 34.1 13.3 34.9 13.9 35.7 14.5 36.6 15 37.4 15.6 38.2 16.2 39 16.8 39.7 17.5 40.2 18.3 40.7 19.2 40.9 20.1 41 21.1 40.9 22.1 40.7 23.1 40.3 24 40 24.9 39.7 25.9 39.4 26.8 39 27.8 38.7 28.7 38.4 29.6 38.1 30.6 37.8 31.5 37.5 32.5 37.2 33.4 36.9 34.4 36.6 35.3 36.2 36.2 35.7 37.1 35 37.8 34.3 38.4 33.4 38.9 32.5 39.3 31.5 39.4 30.5 39.5 29.5 39.5 28.5 39.5 27.5 39.5 26.5 39.5 25.5 39.4 24.5 39.4 23.6 39.4 22.6 39.4 21.6 39.5 20.6 39.5 19.6 39.5 18.6 39.5 17.6 39.5 16.6 39.5 15.6 39.3 14.7 39 13.8 38.5 13.1 37.9 12.4 37.2 11.9 36.3 11.5 35.4 11.2 34.5 10.9 33.5 10.6 32.6 10.3 31.6 10 30.7 9.7 29.7 9.3 28.8 9 27.9 8.7 26.9 8.4 26 8 25 7.7 24.1 7.4 23.2 7.1 22.2 7 21.2 7.1 20.2 7.3 19.3 7.7 18.4 8.3 17.5 8.9 16.8 9.7 16.2 10.5 15.6 11.4 15.1 12.2 14.5 13 14 13.8 13.4 14.6 12.8Z",
+	"M17 12.8 17.7 12.1 18.5 11.5 19.3 10.9 20.1 10.5 20.2 10.4 21.1 10 22 9.7 23 9.4 24 9.2 25 9 26 9 27 9 27.6 9.1 28 9.1 28.9 9.3 29.9 9.6 30.9 9.9 31.8 10.3 32.6 10.8 33.5 11.3 34.3 11.9 34.6 12.2 35 12.6 35.7 13.3 36.4 14.1 36.9 14.9 37.4 15.8 37.9 16.6 38.3 17.6 38.6 18.5 38.6 18.7 38.8 19.5 38.9 20.5 39 21.5 39 22.5 38.9 23.5 38.7 24.5 38.5 25.4 38.2 26.3 38.2 26.4 37.8 27.3 37.4 28.2 36.8 29.1 36.2 29.9 35.6 30.6 34.9 31.3 34.2 32 33.8 32.5 33.5 32.8 32.8 33.5 32.1 34.2 31.4 34.9 30.7 35.6 29.9 36.2 29.1 36.8 28.2 37.3 27.9 37.5 27.4 37.8 26.4 38.2 25.5 38.5 24.5 38.7 23.5 38.9 22.5 39 21.5 39 20.5 38.9 20.4 38.9 19.5 38.8 18.6 38.6 17.6 38.3 16.7 37.9 15.8 37.5 14.9 37 14.1 36.4 13.4 35.8 13.3 35.8 12.6 35.1 12 34.3 11.3 33.5 10.8 32.7 10.3 31.8 9.9 30.9 9.6 30 9.4 29.3 9.3 29 9.1 28 9 27 9 26 9 25 9.2 24 9.4 23 9.6 22.1 9.8 21.7 10 21.1 10.4 20.2 10.9 19.4 11.4 18.5 12.1 17.8 12.7 17 13.4 16.3 14.2 15.6 14.2 15.5 14.9 14.9 15.6 14.2 16.3 13.5Z",
+	"M33.5 11.3 34.3 11.9 35 12.6 35.3 12.8 35.7 13.3 36.4 14.1 36.9 14.9 37.4 15.8 37.9 16.6 38.3 17.6 38.3 17.7 38.6 18.5 38.8 19.5 38.9 20.5 39 21.5 39 22.5 38.9 23.5 38.9 23.5 38.7 24.5 38.5 25.4 38.2 26.4 37.8 27.3 37.4 28.2 36.9 28.9 36.8 29.1 36.2 29.9 35.6 30.6 34.9 31.3 34.2 32 33.5 32.8 33.1 33.2 32.8 33.5 32.1 34.2 31.4 34.9 30.7 35.6 29.9 36.2 29.1 36.8 28.7 37 28.2 37.3 27.4 37.8 26.4 38.2 25.5 38.5 24.5 38.7 23.5 38.9 23.3 38.9 22.5 39 21.5 39 20.5 38.9 19.5 38.8 18.6 38.6 17.6 38.3 17.6 38.3 16.7 37.9 15.8 37.5 14.9 37 14.1 36.4 13.3 35.8 12.7 35.2 12.6 35.1 12 34.3 11.3 33.5 10.8 32.7 10.3 31.8 9.9 30.9 9.7 30.3 9.6 29.9 9.3 29 9.1 28 9 27 9 26 9 25 9.1 24.5 9.2 24 9.4 23 9.6 22.1 10 21.1 10.4 20.2 10.9 19.4 11.1 19.1 11.5 18.5 12.1 17.7 12.7 17 13.5 16.3 14.2 15.6 14.9 14.9 14.9 14.8 15.6 14.2 16.3 13.5 17 12.8 17.7 12.1 18.5 11.5 19.3 11 19.3 10.9 20.2 10.4 21.1 10 22 9.7 23 9.4 24 9.2 24.7 9.1 25 9 26 9 27 9 28 9.1 28.9 9.3 29.9 9.6 30.4 9.7 30.9 9.9 31.8 10.3 32.6 10.8Z",
+	"M33.2 11.1 34.2 11.2 35.1 11.4 36 11.9 36.6 12.7 36.8 13.7 36.9 14.7 36.9 15.7 37 16.7 37.1 17.7 37.3 18.6 37.9 19.4 38.5 20.2 39.2 20.9 39.8 21.7 40.5 22.4 40.9 23.3 41 24.3 40.7 25.2 40.1 26 39.4 26.8 38.8 27.5 38.1 28.3 37.5 29.1 37.1 30 37 31 37 31.9 36.9 32.9 36.8 33.9 36.7 34.9 36.2 35.8 35.5 36.4 34.5 36.8 33.6 36.8 32.6 36.9 31.6 37 30.6 37.1 29.6 37.2 28.8 37.7 28 38.4 27.3 39 26.5 39.7 25.8 40.3 24.9 40.8 23.9 41 23 40.8 22.1 40.2 21.4 39.6 20.6 38.9 19.9 38.3 19.1 37.6 18.3 37.2 17.3 37 16.3 37 15.3 36.9 14.3 36.8 13.3 36.7 12.4 36.4 11.7 35.7 11.3 34.8 11.2 33.8 11.1 32.8 11 31.8 11 30.8 10.9 29.9 10.4 29 9.8 28.2 9.1 27.5 8.5 26.7 7.8 26 7.3 25.1 7 24.2 7.1 23.2 7.6 22.3 8.2 21.6 8.9 20.8 9.5 20.1 10.2 19.3 10.7 18.5 10.9 17.5 11 16.6 11.1 15.6 11.1 14.6 11.2 13.6 11.5 12.6 12.1 11.9 13 11.4 13.9 11.2 14.9 11.1 15.9 11 16.9 11 17.9 10.9 18.8 10.6 19.6 10 20.4 9.3 21.1 8.6 21.9 8 22.6 7.4 23.6 7 24.6 7.1 25.5 7.5 26.2 8.1 27 8.7 27.7 9.4 28.5 10 29.3 10.6 30.2 10.9 31.2 11 32.2 11.1Z",
+	"M27.7 9.4 28.5 10 29.3 10.6 30.2 10.9 31.2 11 32.2 11.1 33.2 11.1 34.2 11.2 35.1 11.4 36 11.9 36.6 12.7 36.8 13.7 36.9 14.7 36.9 15.7 37 16.7 37.1 17.7 37.3 18.6 37.9 19.4 38.5 20.2 39.2 20.9 39.8 21.7 40.5 22.4 40.9 23.3 41 24.3 40.7 25.2 40.1 26 39.4 26.8 38.8 27.5 38.1 28.3 37.5 29.1 37.1 30 37 31 37 31.9 36.9 32.9 36.8 33.9 36.7 34.9 36.2 35.8 35.5 36.4 34.5 36.8 33.6 36.9 32.6 36.9 31.6 37 30.6 37.1 29.6 37.2 28.8 37.7 28 38.4 27.3 39 26.5 39.7 25.8 40.3 24.9 40.8 23.9 41 23 40.8 22.1 40.2 21.4 39.6 20.6 38.9 19.9 38.3 19.1 37.6 18.3 37.2 17.3 37 16.3 37 15.3 36.9 14.3 36.8 13.3 36.7 12.4 36.4 11.7 35.7 11.3 34.8 11.2 33.8 11.1 32.8 11 31.8 11 30.8 10.9 29.9 10.4 29 9.8 28.2 9.1 27.5 8.5 26.7 7.8 26 7.3 25.1 7 24.2 7.1 23.2 7.6 22.3 8.2 21.6 8.9 20.8 9.5 20.1 10.2 19.3 10.7 18.5 10.9 17.5 11 16.5 11.1 15.6 11.1 14.6 11.2 13.6 11.5 12.6 12.1 11.9 13 11.4 13.9 11.2 14.9 11.1 15.9 11 16.9 11 17.9 10.9 18.8 10.6 19.6 10 20.4 9.3 21.1 8.6 21.9 8 22.6 7.4 23.6 7 24.6 7.1 25.5 7.5 26.2 8.1 27 8.7Z",
+	"M27.9 10.6 28.8 10.3 29.8 10.1 30.8 10 31.8 10.1 32.7 10.3 33.7 10.6 34.6 11.1 34.8 11.3 35.4 11.7 36.1 12.4 36.7 13.1 37.2 14 37.6 14.9 37.9 15.9 38 16.9 38 17.9 37.8 18.8 37.5 19.8 37.1 20.7 36.8 21.6 36.5 22.6 36.4 23.6 36.4 24.4 36.4 24.6 36.5 25.5 36.8 26.5 37.2 27.4 37.6 28.3 37.8 29.3 38 30.3 38 31.3 37.8 32.3 37.6 33.2 37.2 34.1 36.6 35 36 35.7 35.3 36.4 34.4 37 34.1 37.2 33.6 37.4 32.6 37.8 31.6 37.9 30.6 38 29.7 37.9 28.7 37.7 27.8 37.3 26.8 36.9 25.9 36.6 24.9 36.4 23.9 36.4 22.9 36.4 22 36.6 21 37 20.1 37.4 20.1 37.4 19.2 37.7 18.2 37.9 17.2 38 16.2 37.9 15.3 37.7 14.3 37.4 13.4 36.9 12.6 36.3 11.9 35.6 11.3 34.9 10.8 34 10.4 33.1 10.1 32.1 10 31.1 10 30.6 10 30.1 10.2 29.2 10.5 28.2 10.9 27.3 11.2 26.4 11.5 25.4 11.6 24.4 11.6 23.4 11.5 22.5 11.2 21.5 10.8 20.6 10.4 19.7 10.2 18.7 10 17.7 10 16.7 10 16.6 10.2 15.7 10.4 14.8 10.8 13.9 11.4 13 12 12.3 12.7 11.6 13.6 11 14.4 10.6 15.4 10.2 16.4 10.1 17.4 10 18.3 10.1 19.3 10.3 20.2 10.7 20.9 11 21.2 11.1 22.1 11.4 23.1 11.6 24.1 11.6 25.1 11.6 26 11.4 27 11Z",
+	"M36 35.7 35.3 36.4 34.4 37 33.6 37.4 32.6 37.8 31.6 37.9 30.6 38 29.7 37.9 28.7 37.7 27.8 37.3 26.8 36.9 25.9 36.6 24.9 36.4 23.9 36.4 22.9 36.4 22 36.6 21 37 20.1 37.4 19.2 37.7 18.2 37.9 17.2 38 16.2 37.9 15.3 37.7 14.3 37.4 13.4 36.9 12.6 36.3 11.9 35.6 11.3 34.9 10.8 34 10.4 33.1 10.1 32.1 10 31.1 10 30.2 10.2 29.2 10.5 28.2 10.9 27.3 11.2 26.4 11.5 25.4 11.6 24.4 11.6 23.4 11.5 22.5 11.2 21.5 10.8 20.6 10.4 19.7 10.2 18.7 10 17.7 10 16.7 10.2 15.7 10.4 14.8 10.8 13.9 11.4 13 12 12.3 12.7 11.6 13.6 11 14.4 10.6 15.4 10.2 16.4 10.1 17.4 10 18.3 10.1 19.3 10.3 20.2 10.7 21.2 11.1 22.1 11.4 23.1 11.6 24.1 11.6 25.1 11.6 26 11.4 27 11 27.9 10.6 28.8 10.3 29.8 10.1 30.8 10 31.8 10.1 32.7 10.3 33.7 10.6 34.6 11.1 35.4 11.7 36.1 12.4 36.7 13.1 37.2 14 37.6 14.9 37.9 15.9 38 16.9 38 17.8 37.8 18.8 37.5 19.8 37.1 20.7 36.8 21.6 36.5 22.6 36.4 23.6 36.4 24.6 36.5 25.5 36.8 26.5 37.2 27.4 37.6 28.3 37.8 29.3 38 30.3 38 31.3 37.8 32.3 37.6 33.2 37.2 34.1 36.6 35Z",
+	"M32.1 32.1 31.4 32.8 30.7 33.5 29.9 34.1 29.1 34.7 28.3 35.3 27.6 35.8 27.5 35.8 26.6 36.4 25.8 36.8 24.9 37.3 24 37.7 23.1 38 22.1 38.3 21.2 38.6 20.2 38.8 19.2 38.9 18.2 39 17.2 39 16.6 38.9 16.3 38.9 15.3 38.7 14.3 38.4 13.4 38 12.5 37.5 11.7 36.9 11.1 36.3 10.5 35.5 10 34.6 9.6 33.7 9.3 32.7 9.1 31.7 9.1 31.4 9 30.8 9 29.8 9.1 28.8 9.2 27.8 9.4 26.8 9.7 25.9 10 24.9 10.3 24 10.7 23.1 11.2 22.2 11.6 21.4 12.2 20.5 12.2 20.4 12.7 19.7 13.3 18.9 13.9 18.1 14.5 17.3 15.2 16.6 15.9 15.9 16.6 15.2 17.3 14.5 18.1 13.9 18.9 13.3 19.7 12.7 20.4 12.2 20.5 12.2 21.4 11.6 22.2 11.2 23.1 10.7 24 10.3 24.9 10 25.9 9.7 26.8 9.4 27.8 9.2 28.8 9.1 29.8 9 30.8 9 31.4 9.1 31.7 9.1 32.7 9.3 33.7 9.6 34.6 10 35.5 10.5 36.3 11.1 36.9 11.7 37.5 12.5 38 13.4 38.4 14.3 38.7 15.3 38.9 16.3 38.9 16.6 39 17.2 39 18.2 38.9 19.2 38.8 20.2 38.6 21.2 38.3 22.1 38 23.1 37.7 24 37.3 24.9 36.8 25.8 36.4 26.6 35.8 27.5 35.8 27.6 35.3 28.3 34.7 29.1 34.1 29.9 33.5 30.7 32.8 31.4Z",
+	"M24.3 10.2 24.9 10 25.9 9.7 26.8 9.4 27.1 9.4 27.8 9.2 28.8 9.1 29.8 9 29.9 9 30.8 9 31.7 9.1 32.7 9.3 32.8 9.3 33.7 9.6 34.6 10 35.5 10.5 35.5 10.5 36.3 11.1 36.9 11.7 37.5 12.5 37.5 12.5 38 13.4 38.4 14.3 38.7 15.2 38.7 15.3 38.9 16.3 39 17.2 39 18.1 39 18.2 38.9 19.2 38.8 20.2 38.6 20.9 38.6 21.2 38.3 22.1 38 23.1 37.8 23.7 37.7 24 37.3 24.9 36.8 25.8 36.5 26.4 36.4 26.6 35.8 27.5 35.3 28.3 35 28.8 34.7 29.1 34.1 29.9 33.5 30.7 33.1 31.1 32.8 31.4 32.1 32.1 31.4 32.8 31.1 33.1 30.7 33.5 29.9 34.1 29.1 34.7 28.8 35 28.3 35.3 27.5 35.8 26.6 36.4 26.4 36.5 25.8 36.8 24.9 37.3 24 37.7 23.7 37.8 23.1 38 22.1 38.3 21.2 38.6 20.9 38.6 20.2 38.8 19.2 38.9 18.2 39 18.1 39 17.2 39 16.3 38.9 15.3 38.7 15.2 38.7 14.3 38.4 13.4 38 12.5 37.5 12.5 37.5 11.7 36.9 11.1 36.3 10.5 35.5 10.5 35.5 10 34.6 9.6 33.7 9.3 32.8 9.3 32.7 9.1 31.7 9 30.8 9 29.9 9 29.8 9.1 28.8 9.2 27.8 9.4 27.1 9.4 26.8 9.7 25.9 10 24.9 10.2 24.3 10.3 24 10.7 23.1 11.2 22.2 11.5 21.6 11.6 21.4 12.2 20.5 12.7 19.7 13 19.2 13.3 18.9 13.9 18.1 14.5 17.3 14.9 16.9 15.2 16.6 15.9 15.9 16.6 15.2 16.9 14.9 17.3 14.5 18.1 13.9 18.9 13.3 19.2 13 19.7 12.7 20.5 12.2 21.4 11.6 21.6 11.5 22.2 11.2 23.1 10.7 24 10.3Z",
+	"M22.5 7.8 23.2 7.2 24.2 7 25.1 7.4 25.7 8.1 26.2 9 26.8 9.8 27.3 10.6 28.1 11.2 29 11.3 30 11 30.9 10.6 31.8 10.3 32.8 9.9 33.7 10 34.5 10.6 34.9 11.5 34.8 12.5 34.8 13.5 34.7 14.5 34.7 15.5 35.2 16.3 36 16.8 37 17 37.9 17.3 38.9 17.5 39.8 17.9 40.4 18.7 40.5 19.7 40 20.5 39.3 21.3 38.7 22 38.1 22.8 37.6 23.7 37.7 24.6 38.3 25.4 38.9 26.2 39.6 27 40.2 27.7 40.5 28.6 40.3 29.6 39.5 30.3 38.6 30.6 37.6 30.8 36.7 31 35.7 31.3 35 31.9 34.6 32.8 34.7 33.8 34.8 34.8 34.8 35.8 34.8 36.8 34.3 37.6 33.4 38.1 32.4 38 31.5 37.6 30.6 37.2 29.7 36.9 28.7 36.6 27.8 36.9 27.1 37.6 26.6 38.5 26.1 39.3 25.5 40.2 24.8 40.8 23.8 41 22.9 40.6 22.3 39.9 21.8 39 21.2 38.2 20.7 37.4 19.9 36.8 19 36.7 18 37 17.1 37.4 16.2 37.7 15.2 38.1 14.3 38 13.5 37.4 13.1 36.5 13.2 35.5 13.2 34.5 13.3 33.5 13.3 32.5 12.8 31.7 12 31.2 11 31 10.1 30.7 9.1 30.5 8.2 30.1 7.6 29.3 7.5 28.3 8 27.5 8.7 26.7 9.3 26 9.9 25.2 10.4 24.3 10.3 23.4 9.7 22.6 9.1 21.8 8.4 21 7.8 20.3 7.5 19.4 7.7 18.4 8.5 17.7 9.4 17.4 10.4 17.2 11.3 17 12.3 16.7 13 16.1 13.4 15.2 13.3 14.2 13.2 13.2 13.2 12.2 13.2 11.2 13.7 10.4 14.6 9.9 15.6 10 16.5 10.4 17.4 10.8 18.3 11.1 19.3 11.4 20.2 11.1 20.9 10.4 21.4 9.5 21.9 8.7Z",
+].join(";");
+
+const ROTATE_KEY_TIMES = "0; 0.14; 0.29; 0.43; 0.57; 0.71; 0.86; 1";
+const ROTATE_KEY_SPLINES = [
+	"0.5 0.2 0 0.8",
+	"0.5 0.2 0 0.8",
+	"0.5 0.2 0 0.8",
+	"0.5 0.2 0 0.8",
+	"0.5 0.2 0 0.8",
+	"0.5 0.2 0 0.8",
+	"0.5 0.2 0 0.8",
+].join("; ");
+const ROTATE_VALUES =
+	"0 24 24; 154 24 24; 309 24 24; 463 24 24; 617 24 24; 771 24 24; 926 24 24; 1080 24 24";
+
+// ─── Determinate: Circle → SoftBurst path data (viewBox 4 4 40 40, cx=24, cy=24) ─
+// Circle: perfect circle, r≈17 → matches the contained indicator's visual weight
+const DETERMINATE_CIRCLE =
+	"M24 7 C34.49 7 41 13.51 41 24 C41 34.49 34.49 41 24 41 C13.51 41 7 34.49 7 24 C7 13.51 13.51 7 24 7 Z";
+
+// SoftBurst: shape 1 from the indeterminate sequence (same visual as the spec)
+const DETERMINATE_SOFT_BURST =
+	"M20.9 10.4 21.4 9.5 21.9 8.7 22.5 7.8 23.2 7.2 24.2 7 25.1 7.4 25.7 8.1 26.2 9 26.8 9.8 27.3 10.6 28.1 11.2 29 11.3 30 11 30.9 10.6 31.8 10.3 32.8 9.9 33.7 10 34.5 10.6 34.9 11.5 34.8 12.5 34.8 13.5 34.7 14.5 34.7 15.5 35.2 16.3 36 16.8 37 17.1 37.9 17.3 38.9 17.5 39.8 17.9 40.4 18.7 40.5 19.7 40 20.5 39.4 21.3 38.7 22 38.1 22.8 37.6 23.7 37.7 24.6 38.3 25.5 38.9 26.2 39.6 27 40.2 27.7 40.5 28.7 40.3 29.6 39.5 30.3 38.6 30.6 37.6 30.8 36.7 31 35.7 31.3 35 31.9 34.6 32.8 34.7 33.8 34.8 34.8 34.9 35.8 34.8 36.8 34.3 37.6 33.4 38.1 32.4 38 31.5 37.6 30.6 37.2 29.7 36.9 28.7 36.6 27.8 36.9 27.1 37.6 26.6 38.5 26.1 39.3 25.5 40.2 24.8 40.8 23.8 41 22.9 40.6 22.3 39.9 21.8 39 21.2 38.2 20.7 37.4 19.9 36.8 19 36.7 18 37 17.1 37.4 16.2 37.7 15.2 38.1 14.3 38 13.5 37.4 13.1 36.5 13.2 35.5 13.2 34.5 13.3 33.5 13.3 32.5 12.8 31.7 12 31.2 11 31 10.1 30.7 9.1 30.5 8.2 30.1 7.6 29.3 7.5 28.3 8 27.5 8.7 26.7 9.3 26 9.9 25.2 10.4 24.3 10.3 23.4 9.7 22.5 9.1 21.8 8.4 21 7.8 20.3 7.5 19.3 7.7 18.4 8.5 17.7 9.4 17.4 10.4 17.2 11.3 17 12.3 16.7 13 16.1 13.4 15.2 13.3 14.2 13.2 13.2 13.1 12.2 13.2 11.2 13.7 10.4 14.6 9.9 15.6 10 16.5 10.4 17.4 10.8 18.3 11.1 19.3 11.4 20.2 11.1Z";
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+export interface LoadingIndicatorProps
+	extends Omit<React.HTMLAttributes<HTMLDivElement>, "children"> {
+	/**
+	 * Visual style variant.
+	 * - `uncontained` (default): bare indicator, no container background
+	 * - `contained`: indicator inside a circular container
+	 *   (MD3 spec: 38dp container / 24dp active indicator)
+	 */
+	variant?: "uncontained" | "contained";
+
+	/**
+	 * Indicator size in dp (pixels). Clamped to the MD3 spec range [24dp, 240dp].
+	 * Defaults to 48dp.
+	 *
+	 * Size guidelines:
+	 * - Small displays: 24–48dp
+	 * - Medium displays: 48–80dp
+	 * - Large/XL displays (desktop): up to 240dp
+	 *
+	 * @default 48
+	 */
+	size?: number;
+
+	/**
+	 * Determinate progress value between 0 and 1.
+	 * - **Omit** (default) for indeterminate mode: continuous morphing loop.
+	 * - **Provide** for determinate mode: Circle→SoftBurst morph + counterclockwise rotation.
+	 *
+	 * @example `progress={0.7}` shows 70% progress
+	 */
+	progress?: number;
+
+	/**
+	 * Active indicator color override. Falls back to MD3 system color tokens.
+	 * Supports any valid CSS color value or CSS variable.
+	 * @example "#ff5722" | "var(--brand-color)"
+	 */
+	color?: string;
+
+	/**
+	 * Required accessible label describing what is loading.
+	 * @example "Loading news article"
+	 */
+	"aria-label": string;
+}
+
+// ─── Indeterminate SVG (pure SMIL, zero JS overhead) ─────────────────────────
+const IndeterminateSvg = React.memo(function IndeterminateSvg({
+	size,
+}: {
+	size: number;
+}) {
+	// Trì hoãn chèn <animate> 1 frame bằng RequestAnimationFrame
+	// giúp bypass hoàn toàn lỗi Chromium đóng băng SMIL khi parent container đang thực hiện CSS transform/animation.
+	const [ready, setReady] = React.useState(false);
+	React.useEffect(() => {
+		const raf = requestAnimationFrame(() => setReady(true));
+		return () => cancelAnimationFrame(raf);
+	}, []);
+
+	return (
+		<svg
+			viewBox="4 4 40 40"
+			width={size}
+			height={size}
+			fill="currentColor"
+			xmlns="http://www.w3.org/2000/svg"
+			aria-hidden="true"
+			focusable="false"
+		>
+			<path d={SHAPE_VALUES.split(";")[0]}>
+				{ready && (
+					<>
+						<animate
+							attributeName="d"
+							dur="5s"
+							repeatCount="indefinite"
+							calcMode="spline"
+							keySplines={SHAPE_KEY_SPLINES}
+							keyTimes={SHAPE_KEY_TIMES}
+							values={SHAPE_VALUES}
+						/>
+						<animateTransform
+							attributeName="transform"
+							attributeType="XML"
+							type="rotate"
+							dur="5s"
+							repeatCount="indefinite"
+							calcMode="spline"
+							keySplines={ROTATE_KEY_SPLINES}
+							keyTimes={ROTATE_KEY_TIMES}
+							values={ROTATE_VALUES}
+						/>
+					</>
+				)}
+			</path>
+		</svg>
+	);
+});
+
+// ─── Determinate SVG (React-controlled morph + counterclockwise rotation) ────
+// Uses CSS transition for smooth d attribute changes where supported (Chromium),
+// with a style-based transform fallback for rotation.
+const DeterminateSvg = React.memo(function DeterminateSvg({
+	size,
+	progress,
+}: {
+	size: number;
+	progress: number;
+}) {
+	// Clamp and interpolate progress between 0 (circle) and 1 (soft burst)
+	const p = Math.min(1, Math.max(0, progress));
+
+	// Counterclockwise rotation: 0° at 0% → -180° at 100% (per Android spec)
+	const rotation = -180 * p;
+
+	// The path morphs from circle (p=0) to soft-burst (p=1).
+	// We use a SMIL animate with begin="indefinite" that we snap to progress.
+	// For maximum compatibility, render the correct endpoint shape based on progress,
+	// relying on the CSS `d` property transition for smooth animation.
+	const pathD = p < 0.5 ? DETERMINATE_CIRCLE : DETERMINATE_SOFT_BURST;
+
+	return (
+		<svg
+			viewBox="4 4 40 40"
+			width={size}
+			height={size}
+			fill="currentColor"
+			xmlns="http://www.w3.org/2000/svg"
+			aria-hidden="true"
+			focusable="false"
+			style={{
+				transform: `rotate(${rotation}deg)`,
+				transition: "transform 0.3s ease",
+			}}
+		>
+			<path d={pathD} style={{ transition: "d 0.3s ease" }} />
+		</svg>
+	);
+});
+
+// ─── Main Component ───────────────────────────────────────────────────────────
+export const LoadingIndicator = React.forwardRef<
+	HTMLDivElement,
+	LoadingIndicatorProps
+>(
+	(
+		{
+			variant = "uncontained",
+			size = 48,
+			progress,
+			color,
+			className,
+			"aria-label": ariaLabel,
+			style,
+			...restProps
+		},
+		ref,
+	) => {
+		const isContained = variant === "contained";
+		const isDeterminate = progress !== undefined;
+
+		// MD3 spec: strict size range [24dp, 240dp]
+		const clampedSize = Math.min(240, Math.max(24, size));
+
+		// Proportional scaling based on the default 48dp spec size
+		const scaleFactor = clampedSize / 48;
+
+		// MD3 spec: contained → 38dp container, 24dp active indicator
+		// Ratio: 38/24 = 1.583 — preserved at all sizes
+		const containerSize = isContained ? 38 * scaleFactor : undefined;
+		const indicatorSize = isContained ? 24 * scaleFactor : clampedSize;
+
+		// MD3 color tokens (with per-variant defaults)
+		const activeColor = isContained
+			? (color ?? "var(--md-sys-color-indicator-contained-active)")
+			: (color ?? "var(--md-sys-color-indicator-active)");
+
+		// aria-valuenow is only set in determinate mode (per ARIA spec)
+		const ariaNow = isDeterminate
+			? Math.round(Math.min(1, Math.max(0, progress)) * 100)
+			: undefined;
+
+		return (
+			<div
+				ref={ref}
+				role="progressbar"
+				aria-label={ariaLabel}
+				aria-valuemin={0}
+				aria-valuemax={100}
+				aria-valuenow={ariaNow}
+				className={cn(
+					"inline-flex items-center justify-center shrink-0",
+					className,
+				)}
+				style={{
+					width: clampedSize,
+					height: clampedSize,
+					color: activeColor,
+					...style,
+				}}
+				{...restProps}
+			>
+				{isContained ? (
+					<div
+						className="flex items-center justify-center rounded-full"
+						style={{
+							width: containerSize,
+							height: containerSize,
+							backgroundColor:
+								"var(--md-sys-color-indicator-contained-container)",
+						}}
+					>
+						{isDeterminate ? (
+							<DeterminateSvg size={indicatorSize} progress={progress} />
+						) : (
+							<IndeterminateSvg size={indicatorSize} />
+						)}
+					</div>
+				) : isDeterminate ? (
+					<DeterminateSvg size={indicatorSize} progress={progress} />
+				) : (
+					<IndeterminateSvg size={indicatorSize} />
+				)}
+			</div>
+		);
+	},
+);
+
+LoadingIndicator.displayName = "LoadingIndicator";

package/src/ui/menu/context-menu.tsx

@@ -0,0 +1,275 @@
+// ─── MD3 Expressive Menu — ContextMenu (right-click / long-press) ─────────────
+// Wraps @radix-ui/react-context-menu and provides MenuContext with
+// menuPrimitive="context" so MenuItem automatically selects ContextMenu primitives.
+//
+// Visual styling is identical to Menu — baseline or expressive variant.
+// Positioning, scroll lock, and outside click are all handled by Radix.
+import * as RxContextMenu from "@radix-ui/react-context-menu";
+import { AnimatePresence, m } from "motion/react";
+import * as React from "react";
+import { cn } from "../../lib/utils";
+import { FAST_SPATIAL_SPRING } from "./menu-animations";
+import { MenuProvider, useMenuContext } from "./menu-context";
+import {
+	BASELINE_COLORS,
+	MENU_CONTAINER_SHAPE,
+	MENU_GROUP_GAP,
+	MENU_MAX_WIDTH,
+	MENU_MIN_WIDTH,
+	MENU_POPUP_PADDING_Y,
+	STANDARD_COLORS,
+	VIBRANT_COLORS,
+} from "./menu-tokens";
+import type {
+	ContextMenuContentProps,
+	ContextMenuProps,
+	ContextMenuTriggerProps,
+} from "./menu-types";
+
+// ─── ContextMenu (Root) ───────────────────────────────────────────────────────
+
+/**
+ * Root of a context menu (right-click / long-press triggered popup).
+ *
+ * Wraps `@radix-ui/react-context-menu` Root and provides `MenuContext` with
+ * `menuPrimitive="context"` so nested `MenuItem` components automatically use
+ * ContextMenu Radix primitives for correct accessibility and keyboard navigation.
+ *
+ * @example
+ * // Baseline context menu
+ * <ContextMenu variant="baseline">
+ *   <ContextMenuTrigger asChild>
+ *     <div>Right-click me</div>
+ *   </ContextMenuTrigger>
+ *   <ContextMenuContent>
+ *     <MenuItem>Copy</MenuItem>
+ *     <MenuItem>Paste</MenuItem>
+ *   </ContextMenuContent>
+ * </ContextMenu>
+ *
+ * @example
+ * // Expressive context menu with groups
+ * <ContextMenu variant="expressive">
+ *   <ContextMenuTrigger asChild><canvas /></ContextMenuTrigger>
+ *   <ContextMenuContent>
+ *     <MenuGroup>
+ *       <MenuItem>Cut</MenuItem>
+ *       <MenuItem>Copy</MenuItem>
+ *     </MenuGroup>
+ *     <MenuGroup>
+ *       <MenuItem>Paste</MenuItem>
+ *     </MenuGroup>
+ *   </ContextMenuContent>
+ * </ContextMenu>
+ */
+export function ContextMenu({
+	children,
+	variant = "baseline",
+	colorVariant = "standard",
+}: ContextMenuProps) {
+	const [open, setOpen] = React.useState(false);
+
+	return (
+		<MenuProvider
+			variant={variant}
+			colorVariant={colorVariant}
+			menuPrimitive="context"
+			open={open}
+			onOpenChange={setOpen}
+		>
+			<RxContextMenu.Root onOpenChange={setOpen}>{children}</RxContextMenu.Root>
+		</MenuProvider>
+	);
+}
+ContextMenu.displayName = "ContextMenu";
+
+// ─── ContextMenuTrigger ───────────────────────────────────────────────────────
+
+/**
+ * The trigger area for a ContextMenu. Right-click (or long-press on touch)
+ * within this area opens the context menu.
+ *
+ * Use `asChild` to apply trigger behavior to your own element without an
+ * extra wrapper `<span>`.
+ */
+export const ContextMenuTrigger = React.forwardRef<
+	React.ComponentRef<typeof RxContextMenu.Trigger>,
+	ContextMenuTriggerProps &
+		React.ComponentPropsWithoutRef<typeof RxContextMenu.Trigger>
+>(({ children, asChild = true, ...props }, ref) => (
+	<RxContextMenu.Trigger ref={ref} asChild={asChild} {...props}>
+		{children}
+	</RxContextMenu.Trigger>
+));
+ContextMenuTrigger.displayName = "ContextMenuTrigger";
+
+// ─── ContextMenuContent (popup panel) ─────────────────────────────────────────
+
+/**
+ * The popup container for the context menu's contents.
+ *
+ * Renders into a portal via Radix. Uses Framer Motion `AnimatePresence` for
+ * smooth enter/exit animations. Transform-origin is automatically set by
+ * Radix via `--radix-context-menu-content-transform-origin`.
+ *
+ * Visual styling follows `variant` from `ContextMenuContext`:
+ * - `baseline`   → CornerExtraSmall (4px), standard M3 styling
+ * - `expressive` → rounded-2xl, shape-morphing groups, elevation-2
+ *
+ * @param hasOverflow - Set true when using SubMenu to prevent clipping
+ */
+export const ContextMenuContent = React.forwardRef<
+	React.ComponentRef<typeof RxContextMenu.Content>,
+	ContextMenuContentProps &
+		Omit<
+			React.ComponentPropsWithoutRef<typeof RxContextMenu.Content>,
+			"asChild"
+		>
+>(
+	(
+		{
+			children,
+			hasOverflow = false,
+			colorVariant: propColorVariant,
+			separatorStyle = "gap",
+			className,
+			...props
+		},
+		ref,
+	) => {
+		const {
+			open,
+			variant,
+			colorVariant: contextColorVariant,
+		} = useMenuContext();
+		const colorVariant = propColorVariant ?? contextColorVariant;
+
+		const colors =
+			variant === "baseline"
+				? BASELINE_COLORS
+				: colorVariant === "vibrant"
+					? VIBRANT_COLORS
+					: STANDARD_COLORS;
+
+		const isExpressiveGap =
+			variant === "expressive" && separatorStyle === "gap";
+
+		const containerClassName =
+			variant === "expressive"
+				? cn(
+						"z-50 flex flex-col w-full",
+						MENU_MIN_WIDTH,
+						MENU_MAX_WIDTH,
+						isExpressiveGap ? MENU_GROUP_GAP : "",
+						isExpressiveGap ? "bg-transparent" : colors.containerBg,
+						isExpressiveGap ? "" : "rounded-2xl",
+						isExpressiveGap ? "" : "elevation-2",
+						hasOverflow || isExpressiveGap
+							? "overflow-visible"
+							: "overflow-hidden",
+						"outline-none",
+						className,
+					)
+				: cn(
+						"z-50 flex flex-col",
+						MENU_MIN_WIDTH,
+						MENU_MAX_WIDTH,
+						MENU_POPUP_PADDING_Y,
+						MENU_GROUP_GAP,
+						colors.containerBg,
+						MENU_CONTAINER_SHAPE,
+						"elevation-2",
+						hasOverflow ? "overflow-visible" : "overflow-hidden",
+						"outline-none",
+						className,
+					);
+
+		// Helper to recursively flatten fragments
+		const flattenChildren = (nodes: React.ReactNode): React.ReactElement[] => {
+			return React.Children.toArray(nodes).reduce(
+				(acc: React.ReactElement[], child) => {
+					if (React.isValidElement(child)) {
+						if (child.type === React.Fragment) {
+							return acc.concat(
+								flattenChildren(
+									(child as React.ReactElement<{ children?: React.ReactNode }>)
+										.props.children,
+								),
+							);
+						}
+						acc.push(child as React.ReactElement);
+					}
+					return acc;
+				},
+				[],
+			);
+		};
+
+		let renderedChildren: React.ReactNode = children;
+
+		if (variant === "expressive") {
+			const validChildren = flattenChildren(children);
+			const groupCount = validChildren.length;
+
+			const enhancedChildren = validChildren.map((child, i) =>
+				React.cloneElement(
+					child as React.ReactElement<{
+						index?: number;
+						count?: number;
+						isGapVariant?: boolean;
+						className?: string;
+					}>,
+					{
+						index: i,
+						count: groupCount,
+						isGapVariant: isExpressiveGap,
+					},
+				),
+			);
+
+			renderedChildren =
+				separatorStyle === "divider"
+					? enhancedChildren.reduce<React.ReactNode[]>((acc, child, i) => {
+							if (i > 0) {
+								acc.push(
+									<hr
+										key={`divider-${(child as React.ReactElement).key || i}`}
+										className={cn(
+											"mx-3 my-0.5 h-px border-0 bg-m3-outline-variant",
+										)}
+									/>,
+								);
+							}
+							acc.push(child);
+							return acc;
+						}, [])
+					: enhancedChildren;
+		}
+
+		return (
+			<AnimatePresence>
+				{open && (
+					<RxContextMenu.Portal forceMount>
+						<RxContextMenu.Content ref={ref} asChild forceMount {...props}>
+							<m.div
+								className={containerClassName}
+								initial={{ opacity: 0, scale: 0.95, y: -4 }}
+								animate={{ opacity: 1, scale: 1, y: 0 }}
+								exit={{ opacity: 0, scale: 0.95, y: -4 }}
+								transition={FAST_SPATIAL_SPRING}
+								style={{
+									...(props.style as React.CSSProperties),
+									transformOrigin:
+										"var(--radix-context-menu-content-transform-origin)",
+								}}
+							>
+								{renderedChildren}
+							</m.div>
+						</RxContextMenu.Content>
+					</RxContextMenu.Portal>
+				)}
+			</AnimatePresence>
+		);
+	},
+);
+ContextMenuContent.displayName = "ContextMenuContent";

package/src/ui/menu/index.ts

@@ -0,0 +1,77 @@
+// ─── MD3 Expressive Menu — Barrel Export ─────────────────────────────────────
+
+// Components — ContextMenu (right-click / long-press popup)
+export {
+	ContextMenu,
+	ContextMenuContent,
+	ContextMenuTrigger,
+} from "./context-menu";
+// Components — Menu (dropdown popup)
+export { Menu, MenuContent, MenuTrigger } from "./menu";
+
+// Animation variants (for consumers extending animations)
+export {
+	CHECK_ICON_VARIANTS,
+	FAST_EFFECTS_TRANSITION,
+	FAST_SPATIAL_SPRING,
+	MENU_CHECK_ICON_SIZE,
+	MENU_CONTAINER_VARIANTS,
+	SUBMENU_CONTAINER_VARIANTS,
+} from "./menu-animations";
+
+// Context (for advanced usage / extending)
+export { MenuProvider, useMenuContext } from "./menu-context";
+export { MenuDivider } from "./menu-divider";
+export { MenuGroup } from "./menu-group";
+export { MenuItem } from "./menu-item";
+
+// Tokens (for consumers who need raw values)
+export {
+	DIVIDER_COLOR,
+	DIVIDER_PADDING,
+	GROUP_SHAPES,
+	ITEM_SHAPE_CLASSES,
+	MENU_GROUP_GAP,
+	MENU_ICON_SIZE,
+	MENU_ITEM_MIN_HEIGHT,
+	MENU_MAX_WIDTH,
+	MENU_MIN_WIDTH,
+	STANDARD_COLORS,
+	VIBRANT_COLORS,
+} from "./menu-tokens";
+
+// Types
+export type {
+	// ContextMenu
+	ContextMenuContentProps,
+	ContextMenuProps,
+	ContextMenuTriggerProps,
+	MenuColorVariant,
+	MenuContentProps,
+	MenuDividerProps,
+	MenuGroupPosition,
+	MenuGroupProps,
+	MenuItemPosition,
+	MenuItemProps,
+	MenuPrimitive,
+	MenuProps,
+	MenuTriggerProps,
+	MenuVariant,
+	SubMenuProps,
+	// Vertical Menu
+	VerticalMenuContentProps,
+	VerticalMenuDividerProps,
+	VerticalMenuGroupProps,
+	VerticalMenuProps,
+	VerticalMenuSeparatorStyle,
+} from "./menu-types";
+
+export { SubMenu } from "./sub-menu";
+
+// Vertical Menu components (static, always-visible — unchanged)
+export {
+	VerticalMenu,
+	VerticalMenuContent,
+	VerticalMenuDivider,
+	VerticalMenuGroup,
+} from "./vertical-menu";