@recursica/mantine-adapter 0.38.1 → 0.40.0

package/src/components/FileUpload/FileUpload.tsx

@@ -1,7 +1,354 @@
-import React from "react";
+import React, { forwardRef, useEffect, useRef, useState } from "react";
+import { type InputWrapperProps } from "@mantine/core";
+import {
+  filterStylingProps,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import { Button } from "../Button/Button";
+import { Chip } from "../Chip/Chip";
+import {
+  FormControlWrapper,
+  type RecursicaFormControlWrapperProps,
+} from "../FormControlWrapper/FormControlWrapper";
+import styles from "./FileUpload.module.css";
 
-export type FileUploadProps = React.HTMLAttributes<HTMLDivElement>;
+import {
+  fileMatchesAccept,
+  type RecursicaFileUploadItem,
+  type RecursicaFileUploadProps as BaseRecursicaFileUploadProps,
+} from "@recursica/adapter-common";
+export type { RecursicaFileUploadItem };
 
-export const FileUpload: React.FC<FileUploadProps> = (props) => {
-  return <div {...props}>FileUpload</div>;
-};
+export interface RecursicaFileUploadProps
+  extends Omit<
+      React.HTMLAttributes<HTMLDivElement>,
+      "children" | "onDrop" | "onChange"
+    >,
+    Pick<
+      InputWrapperProps,
+      "label" | "error" | "required" | "withAsterisk" | "id"
+    >,
+    Omit<
+      RecursicaFormControlWrapperProps,
+      "controlMaxWidth" | "controlMinWidth"
+    >,
+    BaseRecursicaFileUploadProps {}
+
+export type FileUploadProps = RecursicaOverStyled<RecursicaFileUploadProps>;
+
+function UploadIcon() {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden
+    >
+      <path d="M12 3v12" />
+      <path d="M7 8l5-5 5 5" />
+      <path d="M4 21h16" />
+    </svg>
+  );
+}
+
+/**
+ * A dropzone for uploading files, with a native browse-button fallback and a
+ * removable-chip list of the currently selected files.
+ *
+ * @example
+ * <FileUpload
+ *   label="Upload Files"
+ *   assistiveText="Max file size 5MB"
+ *   files={files}
+ *   onFilesAdded={(added) => setFiles((f) => [...f, ...added.map((file) => ({ file }))])}
+ *   onFileRemove={(id) => setFiles((f) => f.filter((item) => (item.id ?? item.file.name) !== id))}
+ * />
+ */
+export const FileUpload = forwardRef<HTMLDivElement, FileUploadProps>(
+  function FileUpload(props, ref) {
+    const {
+      overStyled = false,
+      formLayout = "stacked",
+
+      // Label & Wrapper Maps
+      labelSize,
+      labelAlignment,
+      labelOptionalText,
+      labelWithEditIcon,
+      labelActionArea,
+      onLabelEditClick,
+
+      label,
+      assistiveText,
+      assistiveWithIcon,
+      error,
+      required,
+      withAsterisk,
+      id,
+      className,
+      style,
+      disabled,
+      readOnly,
+
+      files,
+      onFilesAdded,
+      onFileRemove,
+      accept,
+      multiple = true,
+      maxSize,
+      maxFiles,
+      onFilesRejected,
+      invalidFileTypeMessage = "File type not accepted",
+      maxFilesMessage = `Maximum of ${maxFiles} files allowed`,
+      icon,
+      dropzoneLabel = "Drag and drop files here to upload",
+      browseButtonLabel = "Browse files",
+      removeFileLabel = "Remove",
+      ...rest
+    } = props;
+
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+    const restRecord = sanitizedProps as Record<string, unknown>;
+
+    const inputRef = useRef<HTMLInputElement>(null);
+
+    // Whether the most recent drop/pick attempt included a file that failed the `accept` check —
+    // surfaced as the control's error state (see `effectiveError` below) rather than left for the
+    // integrator to wire up themselves.
+    const [invalidTypeRejected, setInvalidTypeRejected] = useState(false);
+    // Whether the most recent drop/pick attempt included a file that would have pushed the total
+    // past `maxFiles` — surfaced the same way as `invalidTypeRejected` (see `effectiveError`).
+    const [tooManyFilesRejected, setTooManyFilesRejected] = useState(false);
+
+    const handleFiles = (incoming: FileList | File[]) => {
+      if (disabled) return;
+      const list = Array.from(incoming);
+      if (list.length === 0) return;
+
+      const currentCount = files?.length ?? 0;
+      const accepted: File[] = [];
+      const rejected: File[] = [];
+      let hasInvalidType = false;
+      let hasTooMany = false;
+      for (const file of list) {
+        const isInvalidType = !fileMatchesAccept(file, accept);
+        if (isInvalidType) hasInvalidType = true;
+        const isTooLarge = maxSize !== undefined && file.size > maxSize;
+        const wouldExceedMax =
+          maxFiles !== undefined && currentCount + accepted.length >= maxFiles;
+        if (wouldExceedMax) hasTooMany = true;
+        const isRejected = isInvalidType || isTooLarge || wouldExceedMax;
+        (isRejected ? rejected : accepted).push(file);
+      }
+      setInvalidTypeRejected(hasInvalidType);
+      setTooManyFilesRejected(hasTooMany);
+      if (accepted.length > 0) onFilesAdded?.(accepted);
+      if (rejected.length > 0) onFilesRejected?.(rejected);
+    };
+
+    // Counts nested dragenter/dragleave pairs (they fire for every child element the pointer
+    // crosses, not just the dropzone itself) so the drag-over visual state only clears once the
+    // pointer has actually left the dropzone, not just moved between its children.
+    const dragCounterRef = useRef(0);
+    const [isDragging, setIsDragging] = useState(false);
+
+    const handleDragEnter = (event: React.DragEvent<HTMLDivElement>) => {
+      event.preventDefault();
+      dragCounterRef.current += 1;
+      setIsDragging(true);
+    };
+
+    const handleDragLeave = (event: React.DragEvent<HTMLDivElement>) => {
+      event.preventDefault();
+      dragCounterRef.current -= 1;
+      if (dragCounterRef.current <= 0) {
+        dragCounterRef.current = 0;
+        setIsDragging(false);
+      }
+    };
+
+    const handleDragOver = (event: React.DragEvent<HTMLDivElement>) => {
+      // Required so the browser treats this element as a valid drop target.
+      event.preventDefault();
+    };
+
+    const handleDrop = (event: React.DragEvent<HTMLDivElement>) => {
+      event.preventDefault();
+      dragCounterRef.current = 0;
+      setIsDragging(false);
+      handleFiles(event.dataTransfer.files);
+    };
+
+    const openFilePicker = () => {
+      if (disabled) return;
+      inputRef.current?.click();
+    };
+
+    const handleInputChange = (event: React.ChangeEvent<HTMLInputElement>) => {
+      if (event.target.files) handleFiles(event.target.files);
+      // Reset so picking the same file again still fires a change event.
+      event.target.value = "";
+    };
+
+    // Roving tabindex across the file chip list: only the "active" chip's remove icon is a tab
+    // stop (Tab lands on the first chip), and Left/Right/Up/Down move it — see
+    // FILEUPLOAD_IMPLEMENTATION_NOTES.md.
+    const [activeChipIndex, setActiveChipIndex] = useState(0);
+    const removeIconRefs = useRef<Array<HTMLSpanElement | null>>([]);
+    const prevFileCountRef = useRef(files?.length ?? 0);
+
+    useEffect(() => {
+      const count = files?.length ?? 0;
+      // A chip was removed (via keyboard or otherwise) — keep focus in the list, clamped to the
+      // new length, rather than letting it fall back to the document body.
+      if (count > 0 && count < prevFileCountRef.current) {
+        const nextIndex = Math.min(activeChipIndex, count - 1);
+        setActiveChipIndex(nextIndex);
+        removeIconRefs.current[nextIndex]?.focus();
+      }
+      prevFileCountRef.current = count;
+      // Only react to the file list itself shrinking/growing, not to activeChipIndex changes.
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [files]);
+
+    const handleFileListKeyDown = (
+      event: React.KeyboardEvent<HTMLDivElement>,
+    ) => {
+      const count = files?.length ?? 0;
+      if (count === 0) return;
+      let nextIndex: number | undefined;
+      if (event.key === "ArrowRight" || event.key === "ArrowDown") {
+        nextIndex = (activeChipIndex + 1) % count;
+      } else if (event.key === "ArrowLeft" || event.key === "ArrowUp") {
+        nextIndex = (activeChipIndex - 1 + count) % count;
+      }
+      if (nextIndex === undefined) return;
+      event.preventDefault();
+      setActiveChipIndex(nextIndex);
+      removeIconRefs.current[nextIndex]?.focus();
+    };
+
+    // The built-in `accept`-mismatch message is only shown when the integrator hasn't supplied
+    // their own `error` — an explicit error always wins.
+    const effectiveError =
+      error ??
+      (invalidTypeRejected
+        ? invalidFileTypeMessage
+        : tooManyFilesRejected
+          ? maxFilesMessage
+          : undefined);
+
+    const wrapperClass = className
+      ? `${styles.layoutOverride} ${className}`
+      : styles.layoutOverride;
+
+    return (
+      <FormControlWrapper
+        overStyled={overStyled as true}
+        className={wrapperClass}
+        style={style}
+        formLayout={formLayout}
+        labelSize={labelSize}
+        labelAlignment={labelAlignment}
+        labelOptionalText={labelOptionalText}
+        labelWithEditIcon={labelWithEditIcon}
+        labelActionArea={labelActionArea}
+        onLabelEditClick={onLabelEditClick}
+        label={label}
+        assistiveText={assistiveText}
+        assistiveWithIcon={assistiveWithIcon}
+        error={effectiveError}
+        required={required}
+        withAsterisk={withAsterisk}
+        id={id}
+      >
+        <div
+          ref={ref}
+          className={styles.root}
+          data-disabled={disabled ? "true" : undefined}
+          data-error={effectiveError ? "true" : undefined}
+          {...restRecord}
+        >
+          {!readOnly && (
+            <div
+              className={styles.dropzone}
+              data-dragging={isDragging ? "true" : undefined}
+              onDragEnter={disabled ? undefined : handleDragEnter}
+              onDragLeave={disabled ? undefined : handleDragLeave}
+              onDragOver={disabled ? undefined : handleDragOver}
+              onDrop={disabled ? undefined : handleDrop}
+            >
+              <span className={styles.uploadIcon}>
+                {icon ?? <UploadIcon />}
+              </span>
+              <span className={styles.dropzoneText}>{dropzoneLabel}</span>
+              <Button
+                variant="outline"
+                disabled={disabled}
+                onClick={openFilePicker}
+              >
+                {browseButtonLabel}
+              </Button>
+              <input
+                ref={inputRef}
+                type="file"
+                hidden
+                accept={accept}
+                multiple={multiple}
+                disabled={disabled}
+                onChange={handleInputChange}
+              />
+            </div>
+          )}
+
+          {files &&
+            files.length > 0 &&
+            (readOnly ? (
+              <div className={styles.fileList}>
+                {files.map((item: RecursicaFileUploadItem) => {
+                  const itemId = item.id ?? item.file.name;
+                  return (
+                    <Chip key={itemId} checked={false} tabIndex={-1}>
+                      {item.file.name}
+                    </Chip>
+                  );
+                })}
+              </div>
+            ) : (
+              <div
+                className={styles.fileList}
+                onKeyDown={handleFileListKeyDown}
+              >
+                {files.map((item: RecursicaFileUploadItem, index) => {
+                  const itemId = item.id ?? item.file.name;
+                  return (
+                    <Chip
+                      key={itemId}
+                      checked={false}
+                      tabIndex={-1}
+                      removeLabel={removeFileLabel}
+                      removeTabIndex={index === activeChipIndex ? 0 : -1}
+                      removeIconRef={(el) => {
+                        removeIconRefs.current[index] = el;
+                      }}
+                      onRemove={
+                        disabled ? undefined : () => onFileRemove?.(itemId)
+                      }
+                    >
+                      {item.file.name}
+                    </Chip>
+                  );
+                })}
+              </div>
+            ))}
+        </div>
+      </FormControlWrapper>
+    );
+  },
+);
+
+FileUpload.displayName = "FileUpload";

package/src/components/FileUpload/USAGE.md

@@ -14,15 +14,29 @@ import { FileUpload } from "@recursica/mantine-adapter";
 
 ## 2. Basic Example
 
+`FileUpload` is a **controlled** component: it never stores the selected files itself. `onFilesAdded` reports newly dropped/picked files, `onFileRemove` reports which file was removed, and you own the `files` array in between.
+
 ```tsx
-import React from "react";
+import React, { useState } from "react";
 import { FileUpload } from "@recursica/mantine-adapter";
+import { type RecursicaFileUploadItem } from "@recursica/adapter-common";
 
 export default function Demo() {
+  const [files, setFiles] = useState<RecursicaFileUploadItem[]>([]);
+
   return (
     <FileUpload
-      label="Drop files here"
-      onDrop={(files) => console.log(files)}
+      label="Upload Files"
+      assistiveText="Max file size 5MB"
+      files={files}
+      onFilesAdded={(added) =>
+        setFiles((prev) => [...prev, ...added.map((file) => ({ file }))])
+      }
+      onFileRemove={(id) =>
+        setFiles((prev) =>
+          prev.filter((item) => (item.id ?? item.file.name) !== id),
+        )
+      }
     />
   );
 }
@@ -30,12 +44,156 @@ export default function Demo() {
 
 ---
 
-## 3. Design System Integration
+## 3. Props Reference
+
+| Prop                     | Type                        | Description                                                                                                                                                                                                                          |
+| ------------------------ | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `files`                  | `RecursicaFileUploadItem[]` | Files currently selected, rendered as removable chips below the dropzone. Each item is `{ file: File; id?: string }`.                                                                                                                |
+| `onFilesAdded`           | `(files: File[]) => void`   | Called with newly dropped/picked files. Only the new files — merge them into `files` yourself.                                                                                                                                       |
+| `onFileRemove`           | `(id: string) => void`      | Called with a file's `id` (or `file.name` if no `id` was given) when its remove (X) icon is activated.                                                                                                                               |
+| `accept`                 | `string`                    | Native `accept` attribute (e.g. `".pdf,.png"` or `"image/*"`) — constrains the picker dialog, and is also enforced against dropped files (via `onFilesRejected`), since the browser never applies `accept` to a `drop` event itself. |
+| `multiple`               | `boolean`                   | Whether more than one file can be selected/dropped at once. Defaults to `true`.                                                                                                                                                      |
+| `maxSize`                | `number`                    | Maximum size per file, in bytes. Oversized files go to `onFilesRejected` instead of `onFilesAdded`.                                                                                                                                  |
+| `maxFiles`               | `number`                    | Maximum total number of files allowed in `files`. Files that would exceed it go to `onFilesRejected` instead of `onFilesAdded`.                                                                                                      |
+| `onFilesRejected`        | `(files: File[]) => void`   | Called with files rejected for exceeding `maxSize`/`maxFiles` or not matching `accept`.                                                                                                                                              |
+| `invalidFileTypeMessage` | `React.ReactNode`           | Error message shown when a file is rejected for not matching `accept`. Defaults to `"File type not accepted"`. An explicit `error` prop always takes priority over this.                                                             |
+| `maxFilesMessage`        | `React.ReactNode`           | Error message shown when a file is rejected for exceeding `maxFiles`. Defaults to `"Maximum of {maxFiles} files allowed"`. An explicit `error` prop always takes priority over this.                                                 |
+| `icon`                   | `React.ReactNode`           | Icon shown above the dropzone label. Defaults to the built-in upload icon.                                                                                                                                                           |
+| `dropzoneLabel`          | `React.ReactNode`           | Text shown inside the dropzone. Defaults to `"Drag and drop files here to upload"`.                                                                                                                                                  |
+| `browseButtonLabel`      | `React.ReactNode`           | Label for the button that opens the native file picker. Defaults to `"Browse files"`.                                                                                                                                                |
+| `removeFileLabel`        | `string`                    | Screen-reader label for each file chip's remove button. Defaults to `"Remove"`.                                                                                                                                                      |
+| `disabled`               | `boolean`                   | Disables the dropzone, browse button, and every file chip's remove icon.                                                                                                                                                             |
+| `readOnly`               | `boolean`                   | Renders `files` as a static chip list with no remove icon, and omits the dropzone/browse button entirely.                                                                                                                            |
+
+`FileUpload` also accepts the standard Recursica form-control props (`label`, `assistiveText`, `error`, `required`, `withAsterisk`, `formLayout`, `labelSize`, `labelAlignment`, `labelOptionalText`, `labelWithEditIcon`, `onLabelEditClick`) — see [FormControlWrapper's USAGE.md](../FormControlWrapper/USAGE.md) for how these behave.
+
+---
+
+## 4. Rejecting Oversized Files
+
+```tsx
+<FileUpload
+  label="Upload Files"
+  assistiveText="Max file size 5MB"
+  maxSize={5 * 1024 * 1024}
+  files={files}
+  onFilesAdded={(added) =>
+    setFiles((prev) => [...prev, ...added.map((file) => ({ file }))])
+  }
+  onFilesRejected={(rejected) =>
+    setError(`${rejected.length} file(s) exceeded the 5MB limit.`)
+  }
+  onFileRemove={(id) =>
+    setFiles((prev) =>
+      prev.filter((item) => (item.id ?? item.file.name) !== id),
+    )
+  }
+/>
+```
+
+---
+
+## 5. Rejecting Files by Extension/MIME Type
+
+```tsx
+<FileUpload
+  label="Upload Files"
+  assistiveText="Only .pdf and .png files are accepted"
+  accept=".pdf,.png"
+  files={files}
+  onFilesAdded={(added) =>
+    setFiles((prev) => [...prev, ...added.map((file) => ({ file }))])
+  }
+  onFileRemove={(id) =>
+    setFiles((prev) =>
+      prev.filter((item) => (item.id ?? item.file.name) !== id),
+    )
+  }
+/>
+```
+
+This applies equally to a file picked via "Browse files" and one dragged directly onto the
+dropzone — the browser's own `accept` filtering never covers drag-and-drop, so `FileUpload`
+re-validates it itself before calling `onFilesAdded`/`onFilesRejected`.
+
+A mismatched file automatically puts the control into its error state with the message
+`"File type not accepted"` — no need to wire `onFilesRejected` into your own `error` prop just to
+show something. Override the message with `invalidFileTypeMessage`, or pass your own `error` prop
+to take over the error state entirely:
+
+```tsx
+<FileUpload
+  label="Upload Files"
+  accept=".pdf,.png"
+  invalidFileTypeMessage="Only PDF and PNG files are supported"
+  files={files}
+  onFilesAdded={(added) =>
+    setFiles((prev) => [...prev, ...added.map((file) => ({ file }))])
+  }
+  onFileRemove={(id) =>
+    setFiles((prev) =>
+      prev.filter((item) => (item.id ?? item.file.name) !== id),
+    )
+  }
+/>
+```
+
+---
+
+## 6. Limiting the Number of Files
+
+```tsx
+<FileUpload
+  label="Upload Files"
+  assistiveText="Up to 2 files allowed"
+  maxFiles={2}
+  files={files}
+  onFilesAdded={(added) =>
+    setFiles((prev) => [...prev, ...added.map((file) => ({ file }))])
+  }
+  onFileRemove={(id) =>
+    setFiles((prev) =>
+      prev.filter((item) => (item.id ?? item.file.name) !== id),
+    )
+  }
+/>
+```
+
+Once `files` reaches `maxFiles`, further dropped/picked files are rejected the same way an
+`accept` mismatch is — automatically switching the control into its error state with the default
+`maxFilesMessage` ("Maximum of 2 files allowed" for the example above). Override the message with
+`maxFilesMessage`, or pass your own `error` prop to take over the error state entirely.
+
+---
+
+## 7. Read-only Mode
+
+```tsx
+<FileUpload label="Uploaded Files" readOnly files={files} />
+```
+
+Renders `files` as a plain, non-removable chip list with no dropzone or Browse button — for
+displaying files that were already submitted and can no longer be changed. `onFilesAdded`/
+`onFileRemove` aren't called in this mode since there's nothing to add or remove.
+
+---
+
+## 8. Keyboard Navigation of the File List
+
+Once files are selected, their chips form a single roving-tabindex group, not one tab stop per
+chip: `Tab` lands on the first chip's remove icon, `Enter`/`Space` removes the focused chip, and
+`ArrowLeft`/`ArrowRight`/`ArrowUp`/`ArrowDown` move focus between chips (wrapping at both ends).
+This is a group-level pattern, not an option on `Chip` used standalone elsewhere. (Not applicable
+in `readOnly` mode, which has no remove icons to navigate to.)
+
+---
+
+## 9. Design System Integration
 
 All Recursica components in the `@recursica/mantine-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.
+> - **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.

package/src/components/Switch/SWITCH_IMPLEMENTATION_NOTES.md

@@ -26,3 +26,39 @@ Similar to `Checkbox`, the `Switch` component handles `readOnly` presentation by
 ## 4. Hover State Reset
 
 Mantine forcefully triggers track hover color states globally. Since Recursica currently does not map specific hover states to switch backgrounds across themes (falling back to standard unselected tokens or simply providing a cursor), we structurally wipe out Mantine's `.track:hover` class block inside `Switch.module.css`.
+
+## 5. `RecursicaSwitchGroupProps.value`/`onChange` shape
+
+Tightened to `string[]`/`(value: string[]) => void` to match Mantine's real `Switch.Group` value
+type exactly (previously `unknown[]`, which was accurate but forced `as any` casts everywhere
+this component's `value`/`defaultValue` were handed to `<MantineSwitch.Group>`). Now a genuine
+"Shared" prop — same name and shape as native, no reshaping needed.
+
+## 6. `onChange` shape mismatch (Forge's report) doesn't apply
+
+Neither `Switch` nor `SwitchGroup` reshapes native `onChange` — it flows straight through as
+Mantine's real event-based signature (`(event: ChangeEvent<HTMLInputElement>) => void` for
+`Switch`, `(value: string[]) => void` for `SwitchGroup`). Forge's report flagged an
+event-vs-boolean mismatch, but that's Forge's own dispatcher typing against the old deleted
+local components — our contract never claimed a boolean shape to begin with.
+
+## 7. Focus ring was Mantine's own default blue, not a Recursica color
+
+**Found 2026-08-14:** the hidden `<input>` was left with Mantine's own default focus outline
+(no override existed despite this file previously claiming "focus rings handled internally by
+Mantine" as an intentional decision — verified live, it renders Mantine's theme blue, not a
+Recursica token). Fixed: `.root input:focus-visible { outline: none }` suppresses the native
+outline on the input, and `.root input:focus-visible + .track { ... }` draws the real ring
+(same `--recursica_brand_states_focus_*` tokens used elsewhere) on the visible track instead —
+matching the fix made to `mui-adapter`'s Switch for parity.
+
+## `SwitchGroup` side-by-side layout always rendered as if stacked
+
+**Found 2026-08-14, reported by Matt (against mui-adapter, reproduced here too):** `SwitchGroup`
+passed the switch-item's own inline label max-width token (200px) as the group's
+`controlMaxWidth` — but the mandatory side-by-side label column is a fixed 224px, wider than
+that cap, so the label always overflowed onto its own line regardless of layout mode. Not a
+mui-only bug: same code pattern, same result, here. Fixed by not capping the group's control
+width at all — each switch's own label already wraps at 200px via `.labelWrapper`, so no
+group-level cap is needed. Verified live in both adapters: side-by-side now shows the label
+column at left with the switches beside it; stacked layout unaffected.

package/src/components/Switch/Switch.module.css

@@ -1,8 +1,10 @@
-/* HARDCODED VALUES 
+/* HARDCODED VALUES
  *
  * 1. track border: none; (we do not use border for the switch track)
  * 2. thumb border: none; (we do not use border for the thumb)
- * 3. outline: none; (focus rings handled internally by mantine)
+ * 3. input outline: none; (the real ring is drawn on .track instead, below, from Recursica
+ *    focus tokens — previously left to Mantine's own internal default outline, which renders
+ *    Mantine's theme blue, not a Recursica color)
  */
 
 .root {
@@ -93,6 +95,21 @@
   border-color: transparent;
 }
 
+/* HARDCODE #3: the input itself is visually hidden (Mantine's usual pattern) but still
+   receives real keyboard focus and Mantine's own default focus outline — suppressed here so
+   the ring below (drawn on .track, the visible pill) is the only one that shows. */
+.root input:focus-visible {
+  outline: none;
+}
+
+.root input:focus-visible + .track {
+  outline: var(--recursica_brand_states_focus_border-size) solid
+    var(--recursica_brand_states_focus_color);
+  outline-offset: var(--recursica_brand_states_focus_margin);
+  box-shadow: 0 0 var(--recursica_brand_states_focus_blur)
+    var(--recursica_brand_states_focus_color);
+}
+
 .thumb {
   width: var(--switch-thumb-width);
   height: var(--switch-thumb-height);

package/src/components/Switch/SwitchGroup.tsx

@@ -71,7 +71,10 @@ export const SwitchGroup = forwardRef<HTMLDivElement, SwitchGroupProps>(
       <WithReadOnlyWrapper
         className={className}
         style={style as React.CSSProperties}
-        controlMaxWidth="var(--recursica_ui-kit_components_switch-item_properties_label-max-width)"
+        // No group-level max-width: switch-item label-max-width (200px) caps a single switch's
+        // own label text, not the whole group — reusing it here made the side-by-side label
+        // column (fixed 224px) wider than its container, so it always wrapped onto its own line.
+        controlMaxWidth={undefined}
         controlMinWidth={undefined}
         overStyled={overStyled as true}
         labelElement="div" // Strictly override. ARIA grouping prohibits interactive switches nested natively inside <label>.
@@ -101,8 +104,8 @@ export const SwitchGroup = forwardRef<HTMLDivElement, SwitchGroupProps>(
             /* Natively bind local disabled lock dynamically */
             {...(sanitizedProps as unknown as MantineSwitchGroupProps)}
             disabled={readOnly || (restRecord as any).disabled}
-            value={value as any}
-            defaultValue={defaultValue as any}
+            value={value}
+            defaultValue={defaultValue}
           >
             <div className={styles.groupRoot} data-layout={formLayout}>
               {children}

package/src/components/TimePicker/TIMEPICKER_IMPLEMENTATION_NOTES.md

@@ -66,6 +66,16 @@ Previously flagged as a known limitation, now fixed: Mantine's own `TimePicker`
 
 Implementation: a `useEffect` on mount, gated to only run when there's no real initial `value`/`defaultValue` already (Mantine already derives the correct AM/PM from a real value on its own — this only fixes the genuinely-empty-start case). It sets the native select's `.value` via `Object.getOwnPropertyDescriptor(HTMLSelectElement.prototype, "value").set` (required to make a React-controlled element pick up a value set outside of React) and dispatches a `change` event — access to the native element comes via `amPmRef`, a prop omitted from this component's own public API but still usable internally when calling Mantine's `<TimePicker>` directly.
 
+## Visual review round 6 (Matt Massey, 2026-08-17) — AM/PM dropdown blank until an hour is typed
+
+Round 3 fixed Mantine's internal `amPm` state never becoming valid (the deadlock preventing `onChange` from ever firing). It did not fix a separate problem: the visible `BareDropdown`'s own `value` prop was computed as `hour === undefined ? null : isPM ? "PM" : "AM"` — explicitly `null` whenever no hour had been typed yet, so the control displayed empty on mount even though round 3's mount effect had already seeded Mantine's hidden native `<select>` to "AM". Those are two different pieces of state: the hidden native select (round 3's fix target) and `internalValue`/`hour` (what `BareDropdown` actually renders), and writing to one never touched the other.
+
+The MUI adapter's equivalent (`mui-adapter/src/components/TimePicker/TimePicker.tsx`) never had this problem — its `isPM` is a plain boolean (`internalValue ? internalValue.hour() >= 12 : false`) with no `null`/"unset" branch, so its dropdown always renders a concrete "AM"/"PM".
+
+**Fix**: dropped the `null` branch — `BareDropdown`'s `value` is now just `isPM ? "PM" : "AM"`, matching MUI. `isPM` already evaluates `false` when `hour` is `undefined`, so this alone makes the dropdown default to "AM" with no other changes.
+
+Note: selecting AM/PM before any hour is typed is still a no-op in both adapters (`handleMeridiemChange` bails out when `hour`/`internalValue` is undefined) — that's pre-existing, shared behavior in both adapters, not something this fix touches.
+
 ## Visual review round 5 (Matt Massey, 2026-08-08)
 
 - **AM/PM error-state border wasn't changing**: `BareDropdown` set `data-error`/`data-disabled` via Mantine's `wrapperProps` — which targets the _outer_ `Input.Wrapper` (the label/description/error stacking element), a different, ancestor element from the "wrapper" styles-api slot that actually carries `styles.root`'s border. `Dropdown.module.css`'s `.root[data-error]`/`[data-disabled]` rules never matched as a result. This is the exact same "two different things both called 'wrapper'" trap as the earlier `style` vs `styles.wrapper` bug. Fixed by using `attributes={{ wrapper: {...} }}` instead — the styles-api hook that actually targets the same slot as `classNames.wrapper`. **This is a shared, pre-existing bug** — the real `Dropdown.tsx` had the identical mistake, so its error/disabled states never applied a border color either; fixed there too (low-risk, purely-additive, same reasoning as the `data-selected` fix above).