@recursica/mui-adapter 0.23.0 → 0.25.0

package/src/components/FileInput/FileInput.tsx

@@ -1,8 +1,414 @@
-import React from "react";
-import "./FileInput.module.css";
+import React, { forwardRef, useEffect, useRef, useState } from "react";
+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 "./FileInput.module.css";
 
-export type FileInputProps = React.HTMLAttributes<HTMLDivElement>;
+import {
+  fileMatchesAccept,
+  type RecursicaFileUploadItem,
+  type RecursicaFileInputProps as BaseRecursicaFileInputProps,
+} from "@recursica/adapter-common";
+export type { RecursicaFileUploadItem };
 
-export const FileInput: React.FC<FileInputProps> = (props) => {
-  return <div {...props}>FileInput</div>;
-};
+export interface RecursicaFileInputProps
+  extends Omit<
+      React.HTMLAttributes<HTMLDivElement>,
+      "children" | "onDrop" | "onChange"
+    >,
+    Omit<
+      RecursicaFormControlWrapperProps,
+      "controlMaxWidth" | "controlMinWidth"
+    >,
+    BaseRecursicaFileInputProps {
+  /** Visually forces the mandatory asterisk. Accepted for API parity with other adapters; MUI's own `required` already renders the asterisk, so this has no separate effect here. */
+  withAsterisk?: boolean;
+}
+
+export type FileInputProps = RecursicaOverStyled<RecursicaFileInputProps>;
+
+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>
+  );
+}
+
+function ClearIcon() {
+  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
+    >
+      <line x1="18" y1="6" x2="6" y2="18" />
+      <line x1="6" y1="6" x2="18" y2="18" />
+    </svg>
+  );
+}
+
+/**
+ * A single-line, `TextField`-shaped control for choosing one or more files, sharing
+ * `FileUpload`'s selection/validation interface (`accept`/`maxSize`/`maxFiles`, `readOnly`)
+ * behind a different presentation.
+ *
+ * @example
+ * <FileInput
+ *   label="Resume"
+ *   files={files}
+ *   onFilesAdded={(added) => setFiles(added.map((file) => ({ file })))}
+ *   onFileRemove={() => setFiles([])}
+ * />
+ */
+export const FileInput = forwardRef<HTMLDivElement, FileInputProps>(
+  function FileInput(props, ref) {
+    const {
+      overStyled = false,
+      formLayout = "stacked",
+
+      // Label & Wrapper Maps
+      labelSize,
+      labelAlignment,
+      labelOptionalText,
+      labelWithEditIcon,
+      labelActionArea,
+      onLabelEditClick,
+
+      label,
+      assistiveText,
+      assistiveWithIcon,
+      error,
+      required,
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      withAsterisk,
+      id,
+      className,
+      style,
+      disabled,
+      readOnly,
+
+      files,
+      onFilesAdded,
+      onFileRemove,
+      accept,
+      multiple = false,
+      maxSize,
+      maxFiles,
+      onFilesRejected,
+      invalidFileTypeMessage = "File type not accepted",
+      maxFilesMessage = multiple
+        ? `Maximum of ${maxFiles} files allowed`
+        : "Only one file is allowed",
+      icon,
+      placeholder = "Select a file...",
+      browseLabel = "Choose file",
+      removeFileLabel = "Remove",
+      clearLabel = "Clear",
+      ...rest
+    } = props;
+
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+    const restRecord = sanitizedProps as Record<string, unknown>;
+
+    const interactive = !disabled && !readOnly;
+    const hasFiles = !!files && files.length > 0;
+
+    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), same as FileUpload.
+    const [invalidTypeRejected, setInvalidTypeRejected] = useState(false);
+    // Whether the most recent drop/pick attempt included a file past the effective cap — 1 in
+    // single-file mode, `maxFiles` in multiple-file mode.
+    const [tooManyFilesRejected, setTooManyFilesRejected] = useState(false);
+
+    const handleFiles = (incoming: FileList | File[]) => {
+      if (!interactive) return;
+      const list = Array.from(incoming);
+      if (list.length === 0) return;
+
+      // Single-file mode always replaces the current selection rather than adding to it, so it
+      // never counts the existing file against the cap — the effective cap is just 1.
+      const effectiveMaxFiles = multiple ? maxFiles : 1;
+      const currentCount = multiple ? (files?.length ?? 0) : 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 =
+          effectiveMaxFiles !== undefined &&
+          currentCount + accepted.length >= effectiveMaxFiles;
+        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 root itself) so the drag-over visual state only clears once the
+    // pointer has actually left the control, not just moved between its children. Mirrors
+    // FileUpload's dropzone.
+    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 (!interactive) return;
+      inputRef.current?.click();
+    };
+
+    const handleRootKeyDown = (event: React.KeyboardEvent<HTMLDivElement>) => {
+      if (event.key !== "Enter" && event.key !== " ") return;
+      event.preventDefault();
+      openFilePicker();
+    };
+
+    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 = "";
+    };
+
+    const handleClearAll = () => {
+      if (!interactive || !files || files.length === 0) return;
+      files.forEach((item) => onFileRemove?.(item.id ?? item.file.name));
+    };
+
+    // Roving tabindex across the file chip list (single- or multiple-file mode): only the
+    // "active" chip's remove icon is a tab stop, and Left/Right/Up/Down move it — same pattern
+    // as FileUpload, see FILEINPUT_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;
+      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 handleChipRowKeyDown = (
+      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();
+      event.stopPropagation();
+      setActiveChipIndex(nextIndex);
+      removeIconRefs.current[nextIndex]?.focus();
+    };
+
+    // The built-in `accept`/cap-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}
+        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}
+        disabled={disabled}
+        id={id}
+        controlMaxWidth="var(--file-input-control-max-width)"
+        controlMinWidth="var(--file-input-control-min-width)"
+      >
+        <div
+          ref={ref}
+          className={styles.root}
+          role="button"
+          aria-label={browseLabel}
+          aria-disabled={disabled ? "true" : undefined}
+          tabIndex={interactive ? 0 : -1}
+          data-disabled={disabled ? "true" : undefined}
+          data-readonly={readOnly ? "true" : undefined}
+          data-error={effectiveError ? "true" : undefined}
+          data-dragging={isDragging ? "true" : undefined}
+          onClick={interactive ? openFilePicker : undefined}
+          onKeyDown={interactive ? handleRootKeyDown : undefined}
+          onDragEnter={interactive ? handleDragEnter : undefined}
+          onDragLeave={interactive ? handleDragLeave : undefined}
+          onDragOver={interactive ? handleDragOver : undefined}
+          onDrop={interactive ? handleDrop : undefined}
+          {...restRecord}
+        >
+          <span className={styles.leadingIcon} aria-hidden>
+            {icon ?? <UploadIcon />}
+          </span>
+
+          <div className={styles.content}>
+            {!hasFiles && (
+              <span className={styles.value} data-placeholder="true">
+                {placeholder}
+              </span>
+            )}
+
+            {hasFiles && (
+              <div
+                className={styles.chipRow}
+                onKeyDown={readOnly ? undefined : handleChipRowKeyDown}
+              >
+                {files!.map((item: RecursicaFileUploadItem, index) => {
+                  const itemId = item.id ?? item.file.name;
+                  return (
+                    <span
+                      key={itemId}
+                      className={styles.chipWrapper}
+                      onClick={(e) => e.stopPropagation()}
+                    >
+                      <Chip
+                        tabIndex={-1}
+                        removeLabel={readOnly ? undefined : removeFileLabel}
+                        removeTabIndex={
+                          !readOnly && index === activeChipIndex ? 0 : -1
+                        }
+                        removeIconRef={(el) => {
+                          removeIconRefs.current[index] = el;
+                        }}
+                        onRemove={
+                          readOnly || disabled
+                            ? undefined
+                            : () => onFileRemove?.(itemId)
+                        }
+                      >
+                        {item.file.name}
+                      </Chip>
+                    </span>
+                  );
+                })}
+              </div>
+            )}
+          </div>
+
+          {hasFiles && !readOnly && (
+            <Button
+              overStyled
+              variant="text"
+              size="small"
+              icon={<ClearIcon />}
+              aria-label={clearLabel}
+              className={styles.trailingIcon}
+              disabled={disabled}
+              onClick={(e) => {
+                e.preventDefault();
+                e.stopPropagation();
+                handleClearAll();
+              }}
+              onKeyDown={(e) => {
+                if (e.key !== "Enter" && e.key !== " ") return;
+                e.preventDefault();
+                e.stopPropagation();
+                handleClearAll();
+              }}
+            />
+          )}
+
+          <input
+            ref={inputRef}
+            type="file"
+            hidden
+            accept={accept}
+            multiple={multiple}
+            disabled={!interactive}
+            onChange={handleInputChange}
+          />
+        </div>
+      </FormControlWrapper>
+    );
+  },
+);
+
+FileInput.displayName = "FileInput";

package/src/components/FileInput/USAGE.md

@@ -14,23 +14,131 @@ import { FileInput } from "@recursica/mui-adapter";
 
 ## 2. Basic Example
 
+`FileInput` is a **controlled** component: it never stores the selected file(s) itself. `onFilesAdded` reports newly picked/dropped files, `onFileRemove` reports which file was removed (or cleared), and you own the `files` array in between.
+
+It shares `FileUpload`'s selection/validation interface, but is presented as a single-line, `TextField`-shaped control instead of a dropzone — every selected file renders as a removable chip in a horizontally scrollable row, whether `multiple` is set or not.
+
 ```tsx
-import React from "react";
+import React, { useState } from "react";
 import { FileInput } from "@recursica/mui-adapter";
+import { type RecursicaFileUploadItem } from "@recursica/adapter-common";
 
 export default function Demo() {
-  return <FileInput label="Upload Resume" placeholder="Choose a file..." />;
+  const [files, setFiles] = useState<RecursicaFileUploadItem[]>([]);
+
+  return (
+    <FileInput
+      label="Resume"
+      files={files}
+      onFilesAdded={(added) => setFiles(added.map((file) => ({ file })))}
+      onFileRemove={() => setFiles([])}
+    />
+  );
 }
 ```
 
+Note that a single-file `onFilesAdded` handler typically **replaces** `files` wholesale (as above)
+rather than appending — picking a new file in single-file mode always replaces the current one.
+
+---
+
+## 3. Props Reference
+
+| Prop                     | Type                        | Description                                                                                                                                                                                                                          |
+| ------------------------ | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `files`                  | `RecursicaFileUploadItem[]` | Files currently selected. Each item is `{ file: File; id?: string }`.                                                                                                                                                                |
+| `onFilesAdded`           | `(files: File[]) => void`   | Called with newly picked/dropped 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 it's removed via a chip's remove icon or the trailing clear button.                                                                                             |
+| `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 `false`, unlike `FileUpload` (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. Only meaningful when `multiple` is `true` — single-file mode always caps at 1 regardless of this prop.                                                                                        |
+| `onFilesRejected`        | `(files: File[]) => void`   | Called with files rejected for exceeding `maxSize`/`maxFiles` (or the single-file cap) 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 the cap. Defaults to `"Maximum of {maxFiles} files allowed"` when `multiple`, or `"Only one file is allowed"` otherwise. An explicit `error` prop always wins.             |
+| `icon`                   | `React.ReactNode`           | Leading icon shown inside the control. Defaults to the built-in upload icon.                                                                                                                                                         |
+| `placeholder`            | `React.ReactNode`           | Text shown when no file is selected. Defaults to `"Select a file..."`.                                                                                                                                                               |
+| `browseLabel`            | `string`                    | Screen-reader label for the control itself (it's the sole interactive/focusable surface, there being no separate "Browse" button). Defaults to `"Choose file"`.                                                                      |
+| `removeFileLabel`        | `string`                    | Screen-reader label for a file chip's remove button. Defaults to `"Remove"`.                                                                                                                                                         |
+| `clearLabel`             | `string`                    | Screen-reader label (`aria-label`) for the trailing clear-all `Button`. Defaults to `"Clear"`.                                                                                                                                       |
+| `disabled`               | `boolean`                   | Disables the control and its clear/remove icons.                                                                                                                                                                                     |
+| `readOnly`               | `boolean`                   | Renders `files` as a static, non-interactive display with no clear/remove icons, and disables picking or dropping new files.                                                                                                         |
+
+`FileInput` 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. Multiple Files
+
+```tsx
+<FileInput
+  label="Attachments"
+  assistiveText="Up to 5 files"
+  multiple
+  files={files}
+  onFilesAdded={(added) =>
+    setFiles((prev) => [...prev, ...added.map((file) => ({ file }))])
+  }
+  onFileRemove={(id) =>
+    setFiles((prev) =>
+      prev.filter((item) => (item.id ?? item.file.name) !== id),
+    )
+  }
+/>
+```
+
+With `multiple`, the same horizontally scrollable row of removable chips (the same `Chip`
+component `FileUpload` uses) can hold more than one file, and the trailing `Button` clears the
+entire selection at once rather than removing a single file.
+
+---
+
+## 5. Rejecting Oversized or Wrong-Type Files
+
+Works exactly like `FileUpload`:
+
+```tsx
+<FileInput
+  label="Resume"
+  assistiveText="PDF only, max 5MB"
+  accept=".pdf"
+  maxSize={5 * 1024 * 1024}
+  files={files}
+  onFilesAdded={(added) => setFiles(added.map((file) => ({ file })))}
+  onFileRemove={() => setFiles([])}
+/>
+```
+
+A mismatched or oversized file puts the control into its error state automatically — no need to
+wire `onFilesRejected` into your own `error` prop just to show something. Override the message
+with `invalidFileTypeMessage`/`maxFilesMessage`, or pass your own `error` prop to take over the
+error state entirely.
+
+---
+
+## 6. Read-Only Display
+
+```tsx
+<FileInput
+  label="Submitted Files"
+  assistiveText="Submitted files cannot be changed"
+  multiple
+  readOnly
+  files={files}
+/>
+```
+
+Renders `files` as a static display with no clear/remove icons, and the control is no longer
+focusable or clickable.
+
 ---
 
-## 3. Design System Integration
+## 7. 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.
+> - **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/Popover/IMPLEMENTATION_NOTES.md

@@ -0,0 +1,22 @@
+# Popover Implementation Notes
+
+- **Built on Mui's Tooltip, in click-controlled mode:** Rather than Mui's `Popover`/`Modal` primitives, this component reuses `@mui/material`'s `Tooltip` — the same base HoverCard and Tooltip already use in this adapter — with `disableHoverListener`/`disableFocusListener`/`disableTouchListener` all set, and `open` fully controlled by this component. This keeps the arrow/placement/token-namespace conventions identical to HoverCard and Tooltip instead of introducing a second, unrelated positioning primitive.
+- **Composable API preserved via child extraction:** Like HoverCard, `Popover.Target`/`Popover.Dropdown` are never rendered themselves — `PopoverBase` walks `children` looking for those `displayName`s and extracts their inner content, then renders the target as Tooltip's single child and the dropdown as Tooltip's `title`.
+- **Diverges from HoverCard on missing Target/Dropdown:** HoverCard silently falls back to an empty `<div />` if the expected child isn't found. Popover throws instead — a silent empty popover is a worse failure mode for a click-triggered disclosure than for a hover card, and the repo convention is to let structural misuse fail loudly rather than mask it.
+- **Click toggle + outside-click close is custom:** Mui's Tooltip has no notion of "click to open" or "click outside to close" once its native hover/focus/touch listeners are disabled — Mantine's Popover provides both natively. This component clones the target element to attach an `onClick` toggle handler and a ref, and closes on outside click via a `mousedown` listener on `document` that ignores clicks inside either the target (`targetRef`) or the dropdown content (`dropdownRef`, a wrapper `<div>` around the dropdown children solely for this hit-test — not a styling root). Escape-to-close comes for free from Tooltip's own internal Escape handling once `onClose` is wired up.
+- **`beak-size` token exemption:** Mui's Tooltip arrow is a fixed CSS shape (`1em`/`0.71em`, relative to the tooltip's own `font-size`) with no JS size prop, unlike Mantine's `arrowSize`. There's no hook to bind `--recursica_ui-kit_components_hover-card-popover_properties_beak-size` to, so it's `recursica-ignore`d here (same conceptual gap as HoverCard/Tooltip's existing exemptions for this token family, just for a different reason — those wrote a comment referencing Mantine's inline-pixel arrow calculations, which doesn't apply in this adapter; this file's comment describes the actual Mui-specific reason).
+- **Arrow fill uses `color`, not `border-color`:** HoverCard's and Tooltip's `.arrow` rules in this adapter set `border-color`, which has no visual effect — Mui's Tooltip arrow is a solid rotated-square filled via `background-color: currentColor` in its `::before`, not a bordered shape. This component's `.arrow` instead sets `color` to the panel's `background-color` token, which actually renders. Intentional deviation from the HoverCard/Tooltip precedent for correctness; not fixed there as it's out of scope for this change.
+- **Shared token namespace:** Same as HoverCard, this component's CSS module exclusively uses `--recursica_ui-kit_components_hover-card-popover_*` tokens (geometry, typography, elevation, layer-aware colors) — no Popover-specific token namespace exists in the schema.
+- **`width` and controlled `opened`/`onChange`:** Not present in the shared `RecursicaPopoverProps` (adapter-common only defines `withBeak`), these are defined locally in `PopoverOwnProps` to match Mantine's own `PopoverProps` surface, since there is no single Mui library type that already provides them.
+
+## Gap larger than Mantine's on `withBeak={false}` (Matt Massey, 2026-08-19)
+
+**Root cause:** Mui's `Tooltip` styled component ships its own hardcoded per-placement margin (`marginTop`/`marginBottom`: `14px`, or `24px` in touch mode) on the tooltip content div, applied whenever `arrow` is falsy (the `arrow` variant resets it to `margin: 0`). This stacked on top of the `offset` popper modifier already applied in `Popover.tsx` (which alone reproduces Mantine's own gap — Mantine's Popover defaults to an 8px `offset`, the same value used here), so the visible gap was `8 + 14 = 22px` instead of `8px` with `withBeak={false}`.
+
+**Fix:** neutralize Mui's built-in margin in `Popover.module.css` via `:global(.MuiTooltip-popper[data-popper-placement]) .dropdown { margin: 0; }`, matching Mui's own rule's specificity (class + attribute + class) so it wins on source order under `injectFirst`. The `offset` modifier is now the single source of truth for the gap, matching Mantine.
+
+## Beak had no visible edge against the dropdown body (Matt Massey, 2026-08-19)
+
+**Root cause:** Mantine's arrow is a bordered shape — `.arrow { border-color: ... }` — visible because Mantine's own arrow implementation sets `border-width` natively. Mui's arrow `::before` pseudo-element has no border at all by default (just `background-color: currentColor`), so setting only `color` (as this component already did, to fill the triangle) left it with zero visible edge against a similarly-colored panel.
+
+**Fix:** added `.arrow::before { border-style: solid; border-width: ...border-size; border-color: ...colors_border-color; }`, the same border tokens the `.dropdown` container itself uses — verified live (Playwright) that the arrow now shows a visible border matching Mantine's.