Add MD3 side sheet/carousel widgets

This introduce side sheet and carousel APIs with state structs, spec
constants, and headless coverage, plus a middle-inset divider helper.

It extends MD3 runtime tracking/validation across navigation, container,
input, list, dialog, menu, and search components, including generated
validator support for new DSL fields/components.

Fix integration issues uncovered during review, including side-sheet
modal/input-layer/layout lifecycle handling, scrim-dismiss timing,
carousel viewport sizing and scroll width accounting, and correct
tracking bounds for slider and bottom sheet validation.

Author: jserv

include/iui-spec.h

@@ -415,6 +415,25 @@
 #define IUI_NAV_DRAWER_ICON_GAP 12.f
 #endif
 
+/* MD3 Side Sheet */
+#ifndef IUI_SIDE_SHEET_WIDTH
+#define IUI_SIDE_SHEET_WIDTH 400.f /* Standard side sheet width */
+#endif
+#ifndef IUI_SIDE_SHEET_PADDING
+#define IUI_SIDE_SHEET_PADDING 24.f
+#endif
+
+/* MD3 Carousel */
+#ifndef IUI_CAROUSEL_ITEM_WIDTH
+#define IUI_CAROUSEL_ITEM_WIDTH 240.f
+#endif
+#ifndef IUI_CAROUSEL_ITEM_GAP
+#define IUI_CAROUSEL_ITEM_GAP 8.f
+#endif
+#ifndef IUI_CAROUSEL_CORNER_RADIUS
+#define IUI_CAROUSEL_CORNER_RADIUS 28.f
+#endif
+
 /* List - https://m3.material.io/components/lists/specs */
 #ifndef IUI_LIST_ONE_LINE_HEIGHT
 #define IUI_LIST_ONE_LINE_HEIGHT 56.f

include/iui.h

@@ -448,6 +448,27 @@ typedef struct {
     float anim_progress; /* 0.0 = closed, 1.0 = fully open */
 } iui_nav_drawer_state;
 
+/* MD3 Side Sheet state */
+typedef struct {
+    bool is_open;
+    bool modal;
+    float x, y;          /* side sheet position */
+    float width;         /* current or target width */
+    float height;        /* side sheet height */
+    float anim_progress; /* 0.0 = closed, 1.0 = fully open */
+    float saved_layout_x, saved_layout_y;
+    float saved_layout_w, saved_layout_h;
+    int layer_id; /* input layer ID for standard sheets */
+} iui_side_sheet_state;
+
+/* MD3 Carousel State */
+typedef struct {
+    iui_scroll_state scroll;
+    int item_count;
+    float item_width;
+    float item_height;
+} iui_carousel_state;
+
 /* MD3 Button styles */
 typedef enum iui_button_style {
     IUI_BUTTON_TONAL,    /* current default (surface_container bg) */
@@ -867,6 +888,9 @@ void iui_divider(iui_context *ctx);
 /* MD3 Inset Divider - divider with left padding (16dp) */
 void iui_divider_inset(iui_context *ctx);
 
+/* MD3 Middle-Inset Divider - divider with left and right padding (16dp) */
+void iui_divider_middle_inset(iui_context *ctx);
+
 /* Displays a segmented control with mutually exclusive options
  * @ctx:         current UI context
  * @entries:     array of strings, must have a size of num_entries
@@ -2249,6 +2273,26 @@ void iui_nav_drawer_end(iui_context *ctx, iui_nav_drawer_state *state);
 void iui_nav_drawer_open(iui_nav_drawer_state *state);
 void iui_nav_drawer_close(iui_nav_drawer_state *state);
 
+/* MD3 Side Sheet */
+void iui_side_sheet_open(iui_side_sheet_state *state);
+void iui_side_sheet_close(iui_side_sheet_state *state);
+bool iui_side_sheet_begin(iui_context *ctx,
+                          iui_side_sheet_state *state,
+                          float screen_width,
+                          float screen_height);
+void iui_side_sheet_end(iui_context *ctx, iui_side_sheet_state *state);
+
+/* MD3 Carousel */
+void iui_carousel_begin(iui_context *ctx,
+                        iui_carousel_state *state,
+                        float width,
+                        float height);
+bool iui_carousel_item(iui_context *ctx,
+                       iui_carousel_state *state,
+                       const char *image_label,
+                       const char *title);
+void iui_carousel_end(iui_context *ctx, iui_carousel_state *state);
+
 /* Bottom Sheet
  * Surfaces containing supplementary content anchored to the bottom of screen
  * Reference: https://m3.material.io/components/bottom-sheets

scripts/gen-md3-validate.py

@@ -138,6 +138,7 @@ class Component:
     indicator_height: Optional[float] = None
     indicator_width: Optional[float] = None
     item_height: Optional[float] = None
+    item_width: Optional[float] = None
     icon_container: Optional[float] = None
     button_height: Optional[float] = None
     drag_handle_width: Optional[float] = None
@@ -245,6 +246,7 @@ class Spec:
     (r"indicator_height\s+(\d+(?:\.\d+)?)", "indicator_height", float),
     (r"indicator_width\s+(\d+(?:\.\d+)?)", "indicator_width", float),
     (r"item_height\s+(\d+(?:\.\d+)?)", "item_height", float),
+    (r"item_width\s+(\d+(?:\.\d+)?)", "item_width", float),
     (r"button_height\s+(\d+(?:\.\d+)?)", "button_height", float),
     (r"drag_handle_width\s+(\d+(?:\.\d+)?)", "drag_handle_width", float),
     (r"drag_handle_height\s+(\d+(?:\.\d+)?)", "drag_handle_height", float),
@@ -614,6 +616,16 @@ def generate_header(spec: Spec) -> str:
                 )
             )
 
+        # Item width (for carousel/lists)
+        if comp.item_width is not None:
+            lines.append(
+                emit_func(
+                    f"{fn}_item_width",
+                    "int width_px, float scale",
+                    f"    return md3_check_exact_dp(width_px, {comp.item_width:.1f}f, scale, MD3_SIZE_MISMATCH);",
+                )
+            )
+
         # Icon container (for bottom app bar)
         if comp.icon_container is not None:
             lines.append(
@@ -756,7 +768,7 @@ def generate_header(spec: Spec) -> str:
                 emit_func(
                     f"{fn}_expanded_width",
                     "int width_px, float scale",
-                    f"    return md3_check_exact_dp(width_px, {comp.expanded_width:.1f}f, scale, MD3_WIDTH_LOW);",
+                    f"    return md3_check_exact_dp(width_px, {comp.expanded_width:.1f}f, scale, MD3_SIZE_MISMATCH);",
                 )
             )
 
@@ -1111,6 +1123,19 @@ def emit_test(comment: str, *assertions: str):
                 )
             )
 
+        # Item width
+        if comp.item_width is not None:
+            dp = int(comp.item_width)
+            lines.extend(
+                emit_test(
+                    f"Item width {dp}dp",
+                    f"ASSERT_EQ({fn}_item_width({dp}, 1.f), MD3_OK);",
+                    f"ASSERT_TRUE({fn}_item_width({dp + 1}, 1.f) & MD3_SIZE_MISMATCH);",
+                    f"ASSERT_TRUE({fn}_item_width({dp - 1}, 1.f) & MD3_SIZE_MISMATCH);",
+                    f"ASSERT_EQ({fn}_item_width({dp * 2}, 2.f), MD3_OK);",
+                )
+            )
+
         # Icon container
         if comp.icon_container is not None:
             dp = int(comp.icon_container)
@@ -1292,8 +1317,8 @@ def emit_test(comment: str, *assertions: str):
                 emit_test(
                     f"Expanded width {dp}dp",
                     f"ASSERT_EQ({fn}_expanded_width({dp}, 1.f), MD3_OK);",
-                    f"ASSERT_TRUE({fn}_expanded_width({dp + 1}, 1.f) & MD3_WIDTH_LOW);",
-                    f"ASSERT_TRUE({fn}_expanded_width({dp - 1}, 1.f) & MD3_WIDTH_LOW);",
+                    f"ASSERT_TRUE({fn}_expanded_width({dp + 1}, 1.f) & MD3_SIZE_MISMATCH);",
+                    f"ASSERT_TRUE({fn}_expanded_width({dp - 1}, 1.f) & MD3_SIZE_MISMATCH);",
                 )
             )
 

scripts/headless-test.py

@@ -859,6 +859,25 @@ def run_md3_tests(verbose=False):
         iui_fab(ctx, 60.f, 420.f, "add");
         iui_fab_large(ctx, 160.f, 420.f, "edit");
 
+        static char search_buf[64] = "";
+        static size_t search_cur = 0;
+        iui_search_bar(ctx, search_buf, sizeof(search_buf), &search_cur, "Search...");
+
+        static iui_side_sheet_state side_sheet = { .is_open = true, .modal = false };
+        if (iui_side_sheet_begin(ctx, &side_sheet, 580.f, 580.f)) {
+            iui_side_sheet_end(ctx, &side_sheet);
+        }
+
+        static iui_carousel_state carousel;
+        iui_carousel_begin(ctx, &carousel, 0.f, 120.f);
+        iui_carousel_item(ctx, &carousel, "Image", "Item 1");
+        iui_carousel_end(ctx, &carousel);
+
+        static iui_nav_rail_state rail = {.expanded = false};
+        iui_nav_rail_begin(ctx, &rail, 0, 0, 580);
+        iui_nav_rail_item(ctx, &rail, "home", "Home", 0);
+        iui_nav_rail_end(ctx, &rail);
+
         iui_end_window(ctx);
         iui_end_frame(ctx);
         g_iui_port.end_frame(port);
@@ -873,15 +892,20 @@ def run_md3_tests(verbose=False):
         if (frame_violations > 0 && total_violations == frame_violations) {
             static const char *type_names[] = {
                 "BUTTON", "FAB", "FAB_LARGE", "CHIP", "TEXTFIELD",
-                "SWITCH", "SLIDER", "TAB", "CHECKBOX", "RADIO", "SEGMENTED"
+                "SWITCH", "SLIDER", "TAB", "CHECKBOX", "RADIO", "SEGMENTED",
+                "SEARCH_BAR", "SIDE_SHEET", "CAROUSEL", "NAV_RAIL",
+                "NAV_RAIL_INDICATOR", "NAV_DRAWER",
+                "NAV_BAR", "BOTTOM_APP_BAR", "MENU", "LIST_ITEM_ONE_LINE",
+                "LIST_ITEM_TWO_LINE", "LIST_ITEM_THREE_LINE", "SNACKBAR",
+                "CARD", "DIALOG", "BOTTOM_SHEET", "TOOLTIP", "BANNER"
             };
             static const char *viol_names[] = {
                 "HEIGHT", "WIDTH", "TOUCH_TARGET", "CORNER_RADIUS"
             };
             for (int i = 0; i < frame_tracked; i++) {
                 const iui_md3_tracked_t *t = iui_md3_get_tracked(i);
                 if (t && t->violations != 0) {
-                    const char *tname = (t->type < 11) ? type_names[t->type] : "UNKNOWN";
+                    const char *tname = (t->type < 29) ? type_names[t->type] : "UNKNOWN";
                     printf("  VIOLATION: %s size=%.0fx%.0f ", tname, t->bounds.width, t->bounds.height);
                     for (int v = 0; v < 4; v++) {
                         if (t->violations & (1 << v)) printf("[%s] ", viol_names[v]);
@@ -941,6 +965,7 @@ def run_md3_runtime_tests(verbose=False):
         out = subprocess.run([str(exe)], capture_output=True, text=True, timeout=10)
     except subprocess.TimeoutExpired:
         return False, {"error": "timeout"}
+        return False, {"error": "timeout"}
 
     tracked = 0
     violations = 0

src/basic.c

@@ -45,6 +45,11 @@ void iui_segmented(iui_context *ctx,
         (iui_rect_t) {seg_x_start, seg_y, ctx->layout.width, seg_height},
         pill_radius, ctx->colors.surface_container_highest, ctx->renderer.user);
 
+    /* Track component for MD3 validation */
+    IUI_MD3_TRACK_SEGMENTED(
+        ((iui_rect_t) {seg_x_start, seg_y, ctx->layout.width, seg_height}),
+        pill_radius);
+
     /* Selected segment highlight with animation */
     if (*selected < num_entries) {
         float sel_x = (ctx->animation.widget == selected)
@@ -359,6 +364,11 @@ float iui_slider_ex(iui_context *ctx,
     /* Update thumb rect with final position */
     thumb_rect.x = thumb_x - half_size;
 
+    /* Track component for MD3 validation using final thumb/touch bounds */
+    touch_rect = thumb_rect;
+    iui_expand_touch_target(&touch_rect, IUI_SLIDER_TOUCH_TARGET);
+    IUI_MD3_TRACK_SLIDER(touch_rect, touch_rect.height * .5f);
+
     /* MD3: State layer on hover/press/drag */
     if ((thumb_hovered || is_dragging) && !disabled) {
         float state_size = thumb_size * 1.5f;