@recursica/adapter-mui-v7 1.0.0

package/src/components/TimePicker/TimePicker.tsx

@@ -0,0 +1,277 @@
+import React, { forwardRef, useEffect, useState } from "react";
+import { LocalizationProvider } from "@mui/x-date-pickers/LocalizationProvider";
+import { AdapterDayjs } from "@mui/x-date-pickers/AdapterDayjs";
+import {
+  TimePicker as MuiTimePicker,
+  type TimePickerProps as MuiTimePickerProps,
+} from "@mui/x-date-pickers/TimePicker";
+import dayjs, { type Dayjs } from "dayjs";
+import customParseFormat from "dayjs/plugin/customParseFormat";
+import { type ReadOnlyControlProps } from "@recursica/adapter-common";
+import {
+  filterStylingProps,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import { type RecursicaFormControlWrapperProps } from "../FormControlWrapper/FormControlWrapper";
+import { WithReadOnlyWrapper } from "../ReadOnlyField/WithReadOnlyWrapper";
+import { BareDropdown } from "../Dropdown/BareDropdown";
+import styles from "./TimePicker.module.css";
+
+import { type RecursicaTimePickerProps as BaseRecursicaTimePickerProps } from "@recursica/adapter-common";
+
+// Required for dayjs's 2-arg `dayjs(value, format)` string-parsing signature used by `toDayjs`
+// below — without this, dayjs silently ignores the format string and falls back to native `Date`
+// parsing, which fails on a bare "HH:mm" time string (no date component) and returns an Invalid
+// Date. This went unnoticed until a real initial `value`/`defaultValue` needed parsing (every
+// interactive test before that produced Dayjs objects directly from the field's own onChange,
+// never exercising this path).
+dayjs.extend(customParseFormat);
+
+const TIME_FORMAT_SECONDS = "HH:mm:ss";
+const TIME_FORMAT_MINUTES = "HH:mm";
+const AM_PM_DATA = [
+  { value: "AM", label: "AM" },
+  { value: "PM", label: "PM" },
+];
+
+/** Parses a Recursica "HH:mm" / "HH:mm:ss" string into a Dayjs instance, or undefined if not set. */
+function toDayjs(value: string | undefined): Dayjs | undefined {
+  if (!value) return undefined;
+  const format = value.length > 5 ? TIME_FORMAT_SECONDS : TIME_FORMAT_MINUTES;
+  return dayjs(value, format);
+}
+
+/**
+ * Formats an "HH:mm"/"HH:mm:ss" 24-hour value as a 12-hour + AM/PM string for read-only display
+ * (e.g. "14:30" -> "2:30 PM") — the raw 24-hour string was being shown as-is in read-only mode,
+ * with no AM/PM, unlike the interactive composite. Returns undefined if not parseable.
+ */
+function formatReadOnlyTime(value: string | undefined): string | undefined {
+  const parsed = toDayjs(value);
+  if (!parsed) return value;
+  return parsed.format(value && value.length > 5 ? "h:mm:ss A" : "h:mm A");
+}
+
+export interface RecursicaTimePickerProps
+  extends Omit<
+      MuiTimePickerProps,
+      | "value"
+      | "defaultValue"
+      | "onChange"
+      | "minTime"
+      | "maxTime"
+      | "views"
+      | "format"
+      | "style"
+    >,
+    Pick<
+      RecursicaFormControlWrapperProps,
+      | "label"
+      | "error"
+      | "required"
+      | "id"
+      | "assistiveText"
+      | "assistiveWithIcon"
+      | "formLayout"
+      | "labelSize"
+      | "labelAlignment"
+      | "labelOptionalText"
+      | "labelWithEditIcon"
+      | "onLabelEditClick"
+    >,
+    ReadOnlyControlProps,
+    BaseRecursicaTimePickerProps {
+  /** Selected time as an "HH:mm" (or "HH:mm:ss" with `withSeconds`) string, matching the mantine-adapter convention. */
+  value?: string;
+  /** Uncontrolled initial time as an "HH:mm" (or "HH:mm:ss" with `withSeconds`) string. */
+  defaultValue?: string;
+  /** Fires with the new time as an "HH:mm" (or "HH:mm:ss" with `withSeconds`) string, or `null` if cleared. */
+  onChange?: (value: string | null) => void;
+  /** Caller-provided inline style, passed through to the FormControlWrapper root. */
+  style?: React.CSSProperties;
+}
+
+export type TimePickerProps = RecursicaOverStyled<RecursicaTimePickerProps>;
+
+export const TimePicker = forwardRef<HTMLDivElement, TimePickerProps>(
+  function TimePicker(props, ref) {
+    const {
+      overStyled = false,
+      formLayout = "stacked",
+
+      // Label & Wrapper Maps
+      labelSize,
+      labelAlignment,
+      labelOptionalText,
+      labelWithEditIcon,
+      onLabelEditClick,
+
+      label,
+      assistiveText,
+      assistiveWithIcon,
+      error,
+      required,
+      id,
+      className,
+      style,
+      disabled,
+      readOnly,
+      readOnlyComponent,
+      emptyValueComponent,
+      value,
+      defaultValue,
+      onChange,
+      withSeconds,
+      minTime,
+      maxTime,
+      leftSection,
+      ...rest
+    } = props;
+
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+
+    // Internal full 24-hour value. Needed (unlike every other component in this adapter) because
+    // the time field and the AM/PM BareDropdown both mutate the same conceptual value — see
+    // TIMEPICKER_IMPLEMENTATION_NOTES.md.
+    const [internalValue, setInternalValue] = useState<Dayjs | null>(
+      () => toDayjs(value) ?? toDayjs(defaultValue) ?? null,
+    );
+
+    useEffect(() => {
+      if (value !== undefined) {
+        setInternalValue(toDayjs(value) ?? null);
+      }
+    }, [value]);
+
+    const isPM = internalValue ? internalValue.hour() >= 12 : false;
+
+    const wrapperClass = className
+      ? `${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?.(
+        next
+          ? next.format(withSeconds ? TIME_FORMAT_SECONDS : TIME_FORMAT_MINUTES)
+          : null,
+      );
+    };
+
+    const handleFieldChange = (next: Dayjs | null) => {
+      emitChange(next);
+    };
+
+    const handleMeridiemChange = (next: string | null) => {
+      if (!internalValue || !next) return;
+      const wantsPM = next === "PM";
+      const currentHour = internalValue.hour();
+      const currentlyPM = currentHour >= 12;
+      if (wantsPM === currentlyPM) return;
+      const nextHour = wantsPM ? currentHour + 12 : currentHour - 12;
+      emitChange(internalValue.hour(nextHour));
+    };
+
+    return (
+      <WithReadOnlyWrapper
+        ref={ref}
+        className={wrapperClass}
+        style={style as React.CSSProperties}
+        controlMaxWidth={undefined}
+        controlMinWidth={undefined}
+        overStyled={overStyled as true}
+        formLayout={formLayout}
+        labelSize={labelSize}
+        labelAlignment={labelAlignment}
+        labelOptionalText={labelOptionalText}
+        labelWithEditIcon={labelWithEditIcon}
+        onLabelEditClick={onLabelEditClick}
+        label={label}
+        assistiveText={assistiveText}
+        assistiveWithIcon={assistiveWithIcon}
+        error={error}
+        required={required}
+        id={id}
+        readOnly={readOnly}
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        readOnlyComponent={readOnlyComponent as any}
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        emptyValueComponent={(emptyValueComponent as any) || undefined}
+        readOnlyType="text"
+        readOnlyValue={formatReadOnlyTime(
+          value !== undefined ? value : defaultValue,
+        )}
+        readOnlyNativeProps={props}
+        activeComponent={
+          /* Naked field execution safely decoupled from MUI X's own label/error macro handling.
+             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}
+            data-with-left-section={leftSection ? "true" : undefined}
+          >
+            <LocalizationProvider dateAdapter={AdapterDayjs}>
+              <MuiTimePicker
+                {...(sanitizedProps as unknown as Partial<MuiTimePickerProps>)}
+                value={internalValue}
+                onChange={handleFieldChange}
+                disabled={disabled}
+                format={`hh:${withSeconds ? "mm:ss" : "mm"}`}
+                views={
+                  withSeconds
+                    ? ["hours", "minutes", "seconds"]
+                    : ["hours", "minutes"]
+                }
+                minTime={toDayjs(minTime)}
+                maxTime={toDayjs(maxTime)}
+                // 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>
+            <BareDropdown
+              overStyled
+              className={styles.amPmSelect}
+              // Dropdown.module.css's own .root sets width: 100% (correct for a standalone
+              // Dropdown filling its form-control column) — overStyled lets us override just the
+              // width via inline style, keeping every other Recursica style (border, colors,
+              // padding) intact. See TIMEPICKER_IMPLEMENTATION_NOTES.md.
+              style={{ width: "fit-content" }}
+              data={AM_PM_DATA}
+              value={isPM ? "PM" : "AM"}
+              onChange={handleMeridiemChange}
+              disabled={disabled}
+              error={!!error}
+              aria-label="AM or PM"
+            />
+          </div>
+        }
+      />
+    );
+  },
+);
+
+TimePicker.displayName = "TimePicker";

package/src/components/TimePicker/USAGE.md

@@ -0,0 +1,61 @@
+# TimePicker - Usage Guide
+
+This document describes how to integrate and use the `TimePicker` component in your projects using `@recursica/adapter-mui-v7`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { TimePicker } from "@recursica/adapter-mui-v7";
+```
+
+`TimePicker` requires `@mui/x-date-pickers` (optional peer dependency) to be installed alongside `@mui/material`. See [SETUP.md](../../../SETUP.md).
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { TimePicker } from "@recursica/adapter-mui-v7";
+
+export default function Demo() {
+  return <TimePicker label="Select Time" />;
+}
+```
+
+`TimePicker`'s value is a plain `"HH:mm"` string (matching `@recursica/mantine-adapter`'s convention) — always 24-hour. Pass `withSeconds` to add a seconds segment (`"HH:mm:ss"`), and `minTime`/`maxTime` (in the same string format) to bound the allowed range.
+
+```tsx
+<TimePicker
+  label="Precise Time"
+  withSeconds
+  minTime="09:00:00"
+  maxTime="17:00:00"
+  onChange={(value) => console.log(value)} // "HH:mm:ss" | null
+/>
+```
+
+> [!IMPORTANT] > **Recursica-specific behavior:** `TimePicker` always renders a 12-hour field with a dedicated AM/PM `Dropdown`-style selector next to it — a deviation from `@mui/x-date-pickers`'s own default (24-hour, or a single field with an inline meridiem section) and **not configurable**. There is no prop to switch to a plain 24-hour field; this is the only way the component operates.
+
+The AM/PM control visually matches Recursica's `Dropdown` component exactly, rather than a plain native `<select>`.
+
+---
+
+## 3. Design System Integration
+
+All Recursica components in the `@recursica/adapter-mui-v7` package adhere strictly to design system spacing, scaling, and behavior patterns.
+
+> [!IMPORTANT]
+>
+> - **Anti-override protection**: Rogue 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.
+> - **Known limitation**: the closed field is fully token-driven; the open clock/list dropdown currently renders with MUI's default styling (no Figma token spec exists for it yet).
+
+---
+
+## 4. Read-Only Mode
+
+Pass `readOnly` to render the current value as static text, matching every other Recursica form control. The value is formatted as 12-hour + AM/PM (e.g. `"14:30"` displays as `"2:30 PM"`).

package/src/components/TimePicker/index.ts

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

package/src/components/Timeline/IMPLEMENTATION_NOTES.md

@@ -0,0 +1,42 @@
+# Timeline Implementation Notes
+
+## Architecture
+
+Unlike Mantine, `@mui/lab`'s `TimelineItem` has no built-in bullet/connector — it only
+composes whatever you nest inside it. `TimelineItem.tsx` renders `TimelineSeparator` >
+`TimelineDot` (`.itemBullet`) + `TimelineConnector` (`.itemConnector`), and `TimelineContent`
+(`.itemBody`) containing the `title`/description/`timestamp` nodes, to reproduce Mantine's
+single-component bullet + connecting-line structure.
+
+- `Timeline.tsx` computes `active`/`isLast` per item (Mui has no `active` concept at all) and
+  injects them into each `Timeline.Item` as internal `__active`/`__isLast` props, mirroring
+  Mantine's own `cloneElement` pattern for propagating active state down to children.
+- `data-active` / `data-variant` are set directly on `TimelineItem`'s real `li` root and
+  consumed via plain descendant selectors (`.item[data-active] .itemBullet`, etc.) in
+  `Timeline.module.css` — Mui's `TimelineItem` only defines a `root` classes slot, so (unlike
+  Mantine) passing a `classes` object with `item`/`itemBullet`/`itemBody`/... keys is a no-op;
+  those class names must be applied as plain `className`s on the elements we render ourselves.
+- The last item omits `TimelineConnector` entirely so no trailing line renders past it.
+- `Timeline.module.css` neutralizes Mui's `TimelineItem::before` opposite-content spacer
+  (`flex: 0; padding: 0`), which otherwise pushes the separator/content right since this
+  adapter never renders `TimelineOppositeContent`.
+
+## Limitations & Missing Tokens
+
+- **Avatar Bullet Size**: There is no specific pixel variable provided for the Avatar bullet size in the UI kit tokens (`avatar-size` evaluates to `"default"`). To maintain exact mathematical centering with the connector line, the CSS falls back to inheriting the `default` bullet size (`20px`) for avatar nodes natively. If users supply a custom sized `img` tag, it must adhere to inline structural constraints or flex mappings.
+
+## Connector fell short of the next bullet (source-of-truth audit, 2026-08-30)
+
+`.root` spaces items with a real flex `gap` (`item-gap`) instead of Mui's own zero-gap default,
+so each `<li>` sits with actual whitespace before the next one. `TimelineConnector` is Mui's own
+`flex: 1` element that only fills its _own_ `<li>`'s content height (bounded by `TimelineItem`'s
+row `align-items: stretch` matching `TimelineContent`'s height) — it always ended flush with its
+own item's bottom edge, `item-gap` short of the next item's bullet. Fixed with `margin-bottom:
+calc(-1 * item-gap)` on `.itemConnector`: flexbox's remaining-space distribution accounts for
+margins when growing a `flex: 1` item, so a negative margin here hands the connector that much
+extra grow height while pulling the _container's_ own computed size back in by the same amount —
+net effect, the rendered line's box is genuinely `item-gap` taller and visually reaches the next
+bullet, confirmed via `getBoundingClientRect()` (connector height 58.8px → 90.8px, exactly +32px
+== the `item-gap` token value). Mantine's equivalent isn't a flex gap at all — it overrides
+Mantine's own `--mantine-spacing-xl` (which natively drives both `.item`'s margin-top and the
+connector's negative-bottom bridging offset together) — but the net visual result matches.