@recursica/mui-adapter 0.37.0 → 0.39.0

package/src/components/TimePicker/TIMEPICKER_IMPLEMENTATION_NOTES.md

@@ -32,7 +32,8 @@ Lowercase `hh` renders 12-hour digits (1–12) with no `a` (meridiem) token, so
 ## Design tokens
 
 - No dedicated `min-height` token exists for `time-picker` (unlike `text-field`/`date-picker`) — the field's height is derived from its own padding + line-height instead of a fixed token.
-- `icon-size`/`icon-color`/`icon-text-gap`/`placeholder-opacity` are exempted (`recursica-ignore`) — the time field has no icon slot and MUI X's field renders empty sections via its own internal placeholder styling, not a native `::placeholder` pseudo-element.
+- `icon-size`/`icon-color`/`icon-text-gap` (plus the disabled/error `icon-color` variants) are wired via `leftSection` — see "Leading icon" below.
+- `placeholder-opacity` remains exempted (`recursica-ignore`) — MUI X's field renders its empty-state "hh"/"mm" placeholder via its own internal `isFieldValueEmpty` styled-component variant (an inline opacity applied through emotion), not a native `::placeholder` pseudo-element this CSS module can target. Unlike mantine-adapter's `SpinInput` (a real `<input placeholder="--">`), there's no stable selector here to hook a token to without depending on MUI X's internal class names.
 - The AM/PM `BareDropdown` draws its own border/background/padding from `Dropdown`'s own tokens via `Dropdown.module.css` — it does not reuse any `time-picker` tokens.
 
 ## Known limitation — the popup clock/list view is unstyled
@@ -43,6 +44,12 @@ This pass covers the closed-state field and the AM/PM `BareDropdown` only. The o
 
 `readOnlyType="text"`, matching `DatePicker`'s convention.
 
+## Leading icon (Matt Massey, 2026-08-30)
+
+Added `leftSection` (`RecursicaTimePickerProps`), matching `TextField`'s naming/convention: purely decorative, consumer-supplied, no default (unlike `DatePicker`'s fixed `CalendarIcon` — there's no single icon that fits every `TimePicker` use).
+
+MUI X's `TimePicker` has no `leftSection` concept — wired via `slotProps.textField.slotProps.input.startAdornment` (the `textField`/`input` slots are exposed at the top level of `TimePicker`'s own `slotProps`, sibling to `field`, via `PickerFieldUISlotPropsFromContext` — confirmed by reading `useDesktopPicker.types.d.ts`/`PickerFieldUI.d.ts` directly, not just the top-level `TimePickerProps` surface). `startAdornment` renders as a plain sibling of `.MuiPickersInputBase-sectionsContainer` inside `PickersInputBase` (confirmed via `PickersInputBase.js`), so it's wrapped in the same `<div className={styles.section} data-position="left">` shape `TextField.tsx` already uses, rather than depending on MUI's own adornment styling. Also added `data-with-left-section` on `.root` so `.MuiPickersInputBase-sectionsContainer`'s own hardcoded `padding-left` (previously always the field's full `horizontal-padding`, structured for the no-icon case) collapses to just `icon-text-gap` once the icon itself is doing the border-inset job instead.
+
 ## Visual review fix (Matt Massey, 2026-08-07)
 
 **`BareDropdown`'s border color didn't match Mantine's version, despite both reading the same `Dropdown` tokens**: a real bug in `BareDropdown.tsx` — `className={styles.root}` was set explicitly on `<MuiSelect>`, then `{...sanitizedProps}` was spread _after_ it. Any caller passing its own `className` (like `TimePicker.tsx`'s `styles.amPmSelect`) silently overwrote `styles.root` entirely via that later spread, so `Dropdown.module.css`'s border-color/background/`width: 100%` never actually applied — MUI's own default border rendered instead. Fixed by extracting `className` explicitly and merging it (`` `${styles.root} ${className}` ``) before it reaches `<MuiSelect>`, the same pattern mantine-adapter's `BareDropdown` already used. This also explains why the AM/PM box's width had looked accidentally "correct" before: the competing `width: 100%` rule from `.root` was never actually being applied either.

package/src/components/TimePicker/TimePicker.module.css

@@ -128,6 +128,37 @@
   color: inherit;
 }
 
+/* Leading icon (leftSection), rendered via slotProps.textField.slotProps.input.startAdornment —
+   a sibling of .MuiPickersInputBase-sectionsContainer inside .field, same shape as TextField's own
+   startAdornment wrapping. Only one icon-color token exists for time-picker (unlike text-field's
+   separate leading/trailing) — this field has no right-side icon slot. */
+.section {
+  display: flex;
+  align-items: center;
+  padding-left: var(
+    --recursica_ui-kit_components_time-picker_properties_horizontal-padding
+  );
+}
+
+.section :global(svg) {
+  width: var(--recursica_ui-kit_components_time-picker_properties_icon-size);
+  height: var(--recursica_ui-kit_components_time-picker_properties_icon-size);
+  color: var(
+    --recursica_ui-kit_components_time-picker_properties_colors_icon-color
+  );
+}
+
+/* With a leftSection present, the icon (not .field's own border) now owns the inset from the left
+   edge — sectionsContainer's own padding-left collapses to just the icon-text-gap between icon and
+   digits. */
+.root[data-with-left-section="true"]
+  .field
+  :global(.MuiPickersInputBase-sectionsContainer) {
+  padding-left: var(
+    --recursica_ui-kit_components_time-picker_properties_icon-text-gap
+  ) !important;
+}
+
 /* The AM/PM BareDropdown reuses Dropdown.module.css's own border/background/padding entirely —
    this only controls its size/alignment within the flex row. */
 .amPmSelect {
@@ -191,6 +222,12 @@
   ) !important;
 }
 
+.root[data-error="true"] .section :global(svg) {
+  color: var(
+    --recursica_ui-kit_components_time-picker_variants_states_error_properties_colors_icon-color
+  ) !important;
+}
+
 /* Disabled State Mapping */
 .field:has(:global(.Mui-disabled)) {
   border-color: var(
@@ -207,3 +244,9 @@
   ) !important;
   cursor: not-allowed;
 }
+
+.field:has(:global(.Mui-disabled)) .section :global(svg) {
+  color: var(
+    --recursica_ui-kit_components_time-picker_variants_states_disabled_properties_colors_icon-color
+  ) !important;
+}

package/src/components/TimePicker/TimePicker.stories.tsx

@@ -115,6 +115,28 @@ export const ErrorState: Story = {
   },
 };
 
+export const WithLeadingIcon: Story = {
+  args: {
+    label: "Meeting Time",
+    assistiveText: "Choose the start time in your local timezone.",
+    leftSection: (
+      <svg
+        width="24"
+        height="24"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="2"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      >
+        <circle cx="12" cy="12" r="10"></circle>
+        <polyline points="12 6 12 12 16 14"></polyline>
+      </svg>
+    ),
+  },
+};
+
 export const StaticReadOnly: Story = {
   args: {
     label: "Static ReadOnly Review",

package/src/components/TimePicker/TimePicker.tsx

@@ -124,6 +124,7 @@ export const TimePicker = forwardRef<HTMLDivElement, TimePickerProps>(
       withSeconds,
       minTime,
       maxTime,
+      leftSection,
       ...rest
     } = props;
 
@@ -148,6 +149,12 @@ export const TimePicker = forwardRef<HTMLDivElement, TimePickerProps>(
       ? `${styles.layoutOverride} ${className}`
       : styles.layoutOverride;
 
+    const startAdornment = leftSection ? (
+      <div className={styles.section} data-position="left">
+        {leftSection}
+      </div>
+    ) : undefined;
+
     const emitChange = (next: Dayjs | null) => {
       setInternalValue(next);
       onChange?.(
@@ -206,7 +213,11 @@ export const TimePicker = forwardRef<HTMLDivElement, TimePickerProps>(
              format="hh:mm" is always on (12-hour digits, no native meridiem section) — this is the
              only way this component operates, not a user choice. The AM/PM BareDropdown next to it
              is the only AM/PM control; see TIMEPICKER_IMPLEMENTATION_NOTES.md. */
-          <div className={styles.root} data-error={error ? "true" : undefined}>
+          <div
+            className={styles.root}
+            data-error={error ? "true" : undefined}
+            data-with-left-section={leftSection ? "true" : undefined}
+          >
             <LocalizationProvider dateAdapter={AdapterDayjs}>
               <MuiTimePicker
                 {...(sanitizedProps as unknown as Partial<MuiTimePickerProps>)}
@@ -221,16 +232,23 @@ export const TimePicker = forwardRef<HTMLDivElement, TimePickerProps>(
                 }
                 minTime={toDayjs(minTime)}
                 maxTime={toDayjs(maxTime)}
-                // No icon/open-picker button: time-picker's own token schema has no icon slot (see
-                // EXEMPTIONS above), and the popup clock/list view this button opens isn't styled
-                // to Recursica tokens anyway (see TIMEPICKER_IMPLEMENTATION_NOTES.md) — showing an
-                // affordance to open an unstyled popup would be worse than not showing one. Typing
-                // directly into the field's masked hour/minute segments is the only interaction.
+                // No open-picker button: the popup clock/list view it opens isn't styled to
+                // Recursica tokens (see TIMEPICKER_IMPLEMENTATION_NOTES.md) — showing an affordance
+                // to open an unstyled popup would be worse than not showing one. Typing directly
+                // into the field's masked hour/minute segments is the only interaction. leftSection
+                // (below) is purely decorative, unrelated to this button.
                 slots={{ openPickerButton: () => null }}
                 slotProps={{
                   field: {
                     className: styles.field,
                   },
+                  textField: {
+                    slotProps: {
+                      input: {
+                        startAdornment,
+                      },
+                    },
+                  },
                 }}
               />
             </LocalizationProvider>

package/src/components/index.ts

@@ -1,9 +1,8 @@
 export * from "./Accordion";
 export * from "./AssistiveElement";
-export * from "./Autocomplete";
+export * from "./AutoComplete";
 export * from "./Avatar";
 export * from "./Badge";
-export * from "./Box";
 export * from "./Breadcrumb";
 export * from "./Button";
 export * from "./Card";

package/src/index.ts

@@ -5,7 +5,6 @@ import { wrapComponent } from "@recursica/adapter-common";
 export * from "@recursica/adapter-common";
 
 // Expose unwrapped structural layout primitives to preserve their polymorphic types
-export const Box = rawComponents.Box;
 export const Flex = rawComponents.Flex;
 export const Grid = rawComponents.Grid;
 export const GridCol = rawComponents.GridCol;
@@ -30,9 +29,9 @@ export const AccordionPanel = wrapComponent(
 export const AssistiveElement = wrapComponent(
   rawComponents.AssistiveElement,
 ) as typeof rawComponents.AssistiveElement;
-export const Autocomplete = wrapComponent(
-  rawComponents.Autocomplete,
-) as typeof rawComponents.Autocomplete;
+export const AutoComplete = wrapComponent(
+  rawComponents.AutoComplete,
+) as typeof rawComponents.AutoComplete;
 export const Avatar = wrapComponent(
   rawComponents.Avatar,
 ) as typeof rawComponents.Avatar;

package/src/components/Autocomplete/index.ts

@@ -1 +0,0 @@
-export * from "./Autocomplete";

package/src/components/Box/Box.stories.tsx

@@ -1,68 +0,0 @@
-import type { Meta, StoryObj } from "@storybook/react";
-import { Box } from "./Box";
-
-const meta: Meta<typeof Box> = {
-  title: "UI-Kit/Box",
-  component: Box,
-  tags: ["autodocs"],
-  parameters: {
-    docs: {
-      description: {
-        component:
-          "The `Box` component is the foundational layout primitive. It accepts all standard MUI layout properties (like `m`, `mt`, `p`, `px`, etc.), but natively intercepts **Recursica Spacing Tokens** (e.g., `rec-none`, `rec-sm`, `rec-default`, `rec-md`, `rec-lg`, `rec-xl`, `rec-2xl`). This allows developers to use Recursica's strict design tokens seamlessly alongside standard MUI spacing.",
-      },
-    },
-    controls: {
-      include: [
-        "layer",
-        "withLayer",
-        "children",
-        "component",
-        "variant",
-        "size",
-        "icon",
-        "disabled",
-        "href",
-        "onClick",
-        "onChange",
-        "value",
-        "checked",
-      ],
-    },
-  },
-};
-
-export default meta;
-type Story = StoryObj<typeof Box>;
-
-export const Default: Story = {
-  args: {
-    children: "This is a standard Box",
-    m: "20px",
-  },
-  render: (args) => (
-    <Box {...args} style={{ border: "1px solid gray", padding: "10px" }} />
-  ),
-};
-
-export const WithRecursicaTokens: Story = {
-  args: {
-    children: "This Box uses Recursica layout tokens",
-    m: "rec-xl",
-    p: "rec-md",
-  },
-  render: (args) => (
-    <div style={{ border: "1px dashed #ccc", display: "inline-block" }}>
-      <Box {...args} style={{ backgroundColor: "rgba(0,0,0,0.1)" }} />
-    </div>
-  ),
-};
-
-export const Polymorphic: Story = {
-  args: {
-    component: "section",
-    children: "This Box is rendered as a <section> element",
-    m: "rec-default",
-    p: "rec-lg",
-  },
-};

package/src/components/Box/Box.test.tsx

@@ -1 +0,0 @@
-// Placeholder for future Box component tests. Add tests here if/when needed.

package/src/components/Box/Box.tsx

@@ -1,24 +0,0 @@
-/**
- * Box layout wrapper.
- *
- * NOTE: Box is the lowest-level primitive layout component. It explicitly ALLOWS
- * the `sx` prop as an escape hatch. It does not use the strict RecursicaOverStyled gatekeeper
- * or any style stripping utilities.
- */
-import React, { forwardRef } from "react";
-import { Box as MUIBox, type BoxProps as MUIBoxProps } from "@mui/material";
-
-export type BoxProps<C extends React.ElementType = "div"> = MUIBoxProps<
-  C,
-  { component?: C }
->;
-
-export const Box = forwardRef(function Box<C extends React.ElementType = "div">(
-  props: BoxProps<C>,
-  ref: React.Ref<Element>,
-) {
-  return <MUIBox ref={ref} {...props} />;
-}) as <C extends React.ElementType = "div">(
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  props: BoxProps<C> & { ref?: React.ForwardedRef<any> },
-) => React.ReactElement | null;

package/src/components/Box/IMPLEMENTATION_NOTES.md

@@ -1,5 +0,0 @@
-# Box Implementation Notes
-
-## `sx` Prop Exemption
-
-By design, the `Box` component is the most permissive primitive in the UI kit. It explicitly allows the `sx` prop to pass through to the underlying MUI `Box`. It does not use any strict styling gatekeepers (`RecursicaOverStyled`, `filterSxProp`). It is intended to be used as a final escape hatch when the standard layout primitives or design system tokens cannot fulfill a unique layout requirement.

package/src/components/Box/USAGE.md

@@ -1,48 +0,0 @@
-# Box - Usage Guide
-
-This document describes how to integrate and use the `Box` component in your projects using `@recursica/mui-adapter`.
-
----
-
-## 1. Import Reference
-
-```tsx
-import { Box } from "@recursica/mui-adapter";
-```
-
----
-
-## 2. Basic Example
-
-```tsx
-import React from "react";
-import { Box } from "@recursica/mui-adapter";
-
-export default function Demo() {
-  return (
-    <Box>
-      <Text>This is a basic layout container.</Text>
-    </Box>
-  );
-}
-```
-
----
-
-## 3. Design System Integration
-
-All Recursica components in the `@recursica/mui-adapter` package adhere strictly to design system spacing, scaling, and behavior patterns.
-
-> [!IMPORTANT]
->
-> - **Anti-override protection**: Rogues style injections (like inline `style` or arbitrary `className`) are automatically blocked by our prop layer unless `overStyled={true}` is explicitly provided.
-> - **No Direct Layers**: Do not pass a `layer` prop to this component. To place it on a specific visual layer, wrap it in a `<Layer layer={0|1|2|3}>` component natively.
-> - **Variables and Theming**: Styling is entirely determined by local CSS variables defined in `recursica_variables_scoped.css` and mapped in the component's CSS module.
-
----
-
-## 4. Key Integration Features & Constraints
-
-## `sx` Prop Exemption
-
-By design, the `Box` component is the most permissive primitive in the UI kit: it always allows the `sx` prop to pass through, without requiring `overStyled`. It is intended to be used as a final escape hatch when the standard layout primitives or design system tokens cannot fulfill a unique layout requirement.

package/src/components/Box/index.ts

@@ -1 +0,0 @@
-export * from "./Box";