@recursica/mantine-adapter 0.36.0 → 0.38.0

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

@@ -1,12 +1,61 @@
 import type { Meta, StoryObj } from "@storybook/react";
 import { TimePicker } from "./TimePicker";
-import { ComingSoon } from "@recursica/storybook-template";
+import { formControlArgTypes } from "../../../.storybook/commonArgTypes";
 
 const meta: Meta<typeof TimePicker> = {
-  title: "UI-Kit/🚧 TimePicker",
+  title: "UI-Kit/TimePicker",
   component: TimePicker,
   tags: ["autodocs"],
-  argTypes: {},
+  parameters: {
+    docs: {
+      description: {
+        component: `
+The \`TimePicker\` primitive provides a segmented hour/minute (optionally seconds) time entry input, paired with a dedicated AM/PM \`Dropdown\`-style selector, integrated directly into the \`FormControlWrapper\` architecture. This 12-hour + AM/PM composite is the only way this component operates — a Recursica-specific design, not a user-configurable option.
+
+### Examples
+Always structure horizontal architectures via the generic \`formLayout\` parameter.
+\`\`\`tsx
+<TimePicker
+  label="Start Time"
+  assistiveText="Select the deployment kick-off time."
+  formLayout="stacked"
+/>
+\`\`\`
+`,
+      },
+    },
+  },
+  argTypes: {
+    ...formControlArgTypes,
+    disabled: {
+      control: "boolean",
+      description:
+        "Maps the formal disabled variable states structurally to the input core.",
+    },
+    error: {
+      control: "text",
+      description:
+        "Applies the strict error string boundary rendering invalid structures seamlessly.",
+    },
+    required: {
+      control: "boolean",
+    },
+    label: {
+      control: "text",
+    },
+    assistiveText: {
+      control: "text",
+    },
+    readOnly: {
+      control: "boolean",
+      description:
+        "Toggles structural read-only data presentation explicitly blocking standard component bindings.",
+    },
+    withSeconds: {
+      control: "boolean",
+      description: "Shows and allows editing the seconds segment.",
+    },
+  },
 };
 
 export default meta;
@@ -14,5 +63,57 @@ export default meta;
 type Story = StoryObj<typeof TimePicker>;
 
 export const Default: Story = {
-  render: () => <ComingSoon componentName="TimePicker" />,
+  args: {
+    disabled: false,
+    label: "Meeting Time",
+    assistiveText: "Choose the start time in your local timezone.",
+  },
+};
+
+export const FormsSideBySide: Story = {
+  args: {
+    label: "Incident Start Time",
+    assistiveText: "When did the incident originally occur?",
+    formLayout: "side-by-side",
+  },
+};
+
+export const WithSeconds: Story = {
+  args: {
+    label: "Precise Execution Time",
+    assistiveText: "Includes a seconds segment for exact scheduling.",
+    withSeconds: true,
+  },
+};
+
+export const Disabled: Story = {
+  args: {
+    label: "Disabled Time Slot",
+    disabled: true,
+  },
+};
+
+export const ErrorState: Story = {
+  args: {
+    label: "Deployment Window",
+    error: "The chosen time falls outside the allowed deployment window.",
+    required: true,
+  },
+};
+
+export const StaticReadOnly: Story = {
+  args: {
+    label: "Static ReadOnly Review",
+    value: "14:30",
+    readOnly: true,
+  },
+};
+
+export const EditableReadOnly: Story = {
+  args: {
+    label: "Editable ReadOnly Review",
+    defaultValue: "09:00",
+    readOnly: true,
+    labelWithEditIcon: true,
+  },
 };

package/src/components/TimePicker/TimePicker.tsx

@@ -1,9 +1,289 @@
-import React from "react";
-import { type RecursicaTimePickerProps } from "@recursica/adapter-common";
+import React, { forwardRef, useEffect, useRef, useState } from "react";
+import {
+  TimePicker as MantineTimePicker,
+  type TimePickerProps as MantineTimePickerProps,
+} from "@mantine/dates";
+import { type InputWrapperProps } from "@mantine/core";
+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";
 
-export type TimePickerProps = React.HTMLAttributes<HTMLDivElement> &
-  RecursicaTimePickerProps;
+import { type RecursicaTimePickerProps as BaseRecursicaTimePickerProps } from "@recursica/adapter-common";
 
-export const TimePicker: React.FC<TimePickerProps> = (props) => {
-  return <div {...props}>TimePicker</div>;
-};
+const AM_PM_DATA = [
+  { value: "AM", label: "AM" },
+  { value: "PM", label: "PM" },
+];
+
+/** Parses an "HH:mm"/"HH:mm:ss" string's hour, or undefined if not set/parseable. */
+function getHour(value: string | undefined): number | undefined {
+  if (!value) return undefined;
+  const hour = parseInt(value.slice(0, 2), 10);
+  return Number.isNaN(hour) ? undefined : hour;
+}
+
+/** Replaces the hour segment of an "HH:mm"/"HH:mm:ss" string, preserving minutes/seconds. */
+function withHour(value: string, hour: number): string {
+  return `${String(hour).padStart(2, "0")}${value.slice(2)}`;
+}
+
+/**
+ * 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 {
+  if (!value) return undefined;
+  const [hourStr, minute, second] = value.split(":");
+  const hour24 = parseInt(hourStr, 10);
+  if (Number.isNaN(hour24) || minute === undefined) return value;
+  const isPM = hour24 >= 12;
+  const hour12 = hour24 % 12 === 0 ? 12 : hour24 % 12;
+  const rest = second !== undefined ? `${minute}:${second}` : minute;
+  return `${hour12}:${rest} ${isPM ? "PM" : "AM"}`;
+}
+
+/**
+ * Simulates a real user interaction on Mantine's own (CSS-hidden) native AM/PM <select>, since it's
+ * a React-controlled element — setting `.value` directly and dispatching a plain DOM event doesn't
+ * trigger React's change handling; using the native property setter first does. See "Why AM/PM is
+ * seeded on mount" in TIMEPICKER_IMPLEMENTATION_NOTES.md.
+ */
+function setNativeSelectValue(el: HTMLSelectElement, value: string): void {
+  const nativeSetter = Object.getOwnPropertyDescriptor(
+    window.HTMLSelectElement.prototype,
+    "value",
+  )?.set;
+  nativeSetter?.call(el, value);
+  el.dispatchEvent(new Event("change", { bubbles: true }));
+}
+
+export interface RecursicaTimePickerProps
+  extends Omit<
+      MantineTimePickerProps,
+      | "size"
+      | "variant"
+      | "radius"
+      | "wrapperProps"
+      | "format"
+      | "min"
+      | "max"
+      // AM/PM is always shown via our own BareDropdown, driving a fixed 12h format — these all
+      // control Mantine's own native (now CSS-hidden) AM/PM select and would be misleading to
+      // expose, since they'd have no visible effect. See TIMEPICKER_IMPLEMENTATION_NOTES.md.
+      | "amPmInputLabel"
+      | "amPmLabels"
+      | "amPmSelectProps"
+      | "amPmRef"
+      // The optional time-presets dropdown isn't wired up; keep the public API to what's supported.
+      | "withDropdown"
+      | "presets"
+      | "maxDropdownContentHeight"
+      | "scrollAreaProps"
+      | "reverseTimeControlsList"
+      | "popoverProps"
+    >,
+    Pick<
+      InputWrapperProps,
+      "label" | "error" | "required" | "withAsterisk" | "id"
+    >,
+    Omit<
+      RecursicaFormControlWrapperProps,
+      "controlMaxWidth" | "controlMinWidth"
+    >,
+    ReadOnlyControlProps,
+    BaseRecursicaTimePickerProps {}
+
+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,
+      withAsterisk,
+      id,
+      className,
+      style,
+      disabled,
+      readOnly,
+      readOnlyComponent,
+      emptyValueComponent,
+      value,
+      defaultValue,
+      onChange,
+      withSeconds,
+      minTime,
+      maxTime,
+      ...rest
+    } = props;
+
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+    const restRecord = sanitizedProps as Record<string, unknown>;
+
+    delete restRecord["size"];
+    delete restRecord["variant"];
+    delete restRecord["radius"];
+
+    // Internal full 24-hour value. Needed because Mantine's TimePicker (hour/minute/second entry)
+    // and our own BareDropdown (AM/PM) both mutate the same conceptual value — see
+    // TIMEPICKER_IMPLEMENTATION_NOTES.md.
+    const [internalValue, setInternalValue] = useState<string | undefined>(
+      () => value ?? defaultValue,
+    );
+
+    useEffect(() => {
+      if (value !== undefined) {
+        setInternalValue(value);
+      }
+    }, [value]);
+
+    // Mantine's own internal amPm state starts `null` whenever there's no initial hour to derive it
+    // from (see convertTimeTo12HourFormat in @mantine/dates), and it stays null — meaning Mantine
+    // never reports a valid onChange, no matter what's typed — until something interacts with the
+    // (CSS-hidden) native AM/PM <select>. Simulating that interaction once on mount, defaulting to
+    // AM, breaks the deadlock: a freshly-typed time now resolves and reports immediately, and our
+    // own BareDropdown (which drives the same native select the same way, see handleMeridiemChange)
+    // correctly displays and changes it from there. Skipped whenever a real initial value/defaultValue
+    // is already present — Mantine already derives the correct AM/PM from that on its own. See
+    // TIMEPICKER_IMPLEMENTATION_NOTES.md.
+    const amPmRef = useRef<HTMLSelectElement>(null);
+    useEffect(() => {
+      if (getHour(value ?? defaultValue) === undefined && amPmRef.current) {
+        setNativeSelectValue(amPmRef.current, "AM");
+      }
+      // Intentionally mount-only — this seeds Mantine's internal state once; after that it's driven
+      // by real interaction (typing, or our own BareDropdown).
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+
+    const emitChange = (next: string) => {
+      setInternalValue(next);
+      onChange?.(next);
+    };
+
+    const hour = getHour(internalValue);
+    const isPM = hour !== undefined && hour >= 12;
+
+    const handleFieldChange = (next: string) => {
+      emitChange(next);
+    };
+
+    const handleMeridiemChange = (next: string | null) => {
+      if (hour === undefined || !internalValue || !next) return;
+      const wantsPM = next === "PM";
+      if (wantsPM === isPM) return;
+      const nextHour = wantsPM ? hour + 12 : hour - 12;
+      emitChange(withHour(internalValue, nextHour));
+    };
+
+    const wrapperClass = className
+      ? `${styles.layoutOverride} ${className}`
+      : styles.layoutOverride;
+
+    return (
+      <WithReadOnlyWrapper
+        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}
+        withAsterisk={withAsterisk}
+        id={id}
+        readOnly={readOnly}
+        readOnlyComponent={readOnlyComponent}
+        emptyValueComponent={emptyValueComponent}
+        readOnlyType="text"
+        readOnlyValue={formatReadOnlyTime(
+          value !== undefined ? value : defaultValue,
+        )}
+        readOnlyNativeProps={props}
+        activeComponent={
+          /* Naked field execution safely decoupled from Mantine's macro Input.Wrapper DOM hooks.
+             format="12h" is always on — this is the only way this component operates, not a user
+             choice (see TIMEPICKER_IMPLEMENTATION_NOTES.md). Mantine's own native AM/PM <select>
+             (bundled unconditionally with format="12h") is CSS-hidden; our own BareDropdown next to
+             it is the only AM/PM control the user interacts with. */
+          <div
+            className={styles.root}
+            data-disabled={disabled ? "true" : undefined}
+            data-error={error ? "true" : undefined}
+          >
+            <MantineTimePicker
+              ref={ref}
+              classNames={{
+                wrapper: styles.timeWrapper,
+                input: styles.timeInput,
+                fieldsGroup: styles.fieldsGroup,
+                field: styles.timeField,
+              }}
+              disabled={disabled}
+              value={internalValue}
+              onChange={handleFieldChange}
+              format="12h"
+              withSeconds={withSeconds}
+              min={minTime}
+              max={maxTime}
+              withDropdown={false}
+              // Internal-only — not part of the public API (see the Omit list above) — used solely
+              // to seed the mount-time AM default onto Mantine's own hidden native select. See
+              // TIMEPICKER_IMPLEMENTATION_NOTES.md.
+              amPmRef={amPmRef}
+              {...(sanitizedProps as unknown as MantineTimePickerProps)}
+            />
+            <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, keeping every other Recursica style (border, colors, padding) intact.
+              // A plain `style` prop won't do this: Mantine's Select/InputBase internals
+              // (useInputProps) route a top-level `style` prop to the *label* InputWrapper, not
+              // the bordered input box itself — `styles={{ wrapper: ... }}` is the styles-api hook
+              // that actually targets that box. See TIMEPICKER_IMPLEMENTATION_NOTES.md.
+              styles={{ wrapper: { width: "fit-content" } }}
+              data={AM_PM_DATA}
+              value={hour === undefined ? null : isPM ? "PM" : "AM"}
+              onChange={handleMeridiemChange}
+              disabled={disabled}
+              error={!!error}
+              aria-label="AM or PM"
+            />
+          </div>
+        }
+      />
+    );
+  },
+);
+
+TimePicker.displayName = "TimePicker";

package/src/components/TimePicker/USAGE.md

@@ -19,10 +19,25 @@ import React from "react";
 import { TimePicker } from "@recursica/mantine-adapter";
 
 export default function Demo() {
-  return <TimePicker label="Select Time" placeholder="Pick a time" />;
+  return <TimePicker label="Select Time" />;
 }
 ```
 
+> [!IMPORTANT] > **Recursica-specific behavior:** `TimePicker` always renders in **12-hour format with a dedicated AM/PM `Dropdown`-style selector** next to the hour/minute input — this deviates from the underlying Mantine library's own default (24-hour, no AM/PM control) and is **not configurable**. There is no prop to switch to a plain 24-hour input; this is the only way the component operates.
+
+Pass `withSeconds` to add a seconds segment, and `minTime`/`maxTime` (`"HH:mm"` or `"HH:mm:ss"` with `withSeconds`) to bound the allowed range — these always describe 24-hour boundaries.
+
+```tsx
+<TimePicker
+  label="Precise Time"
+  withSeconds
+  minTime="09:00:00"
+  maxTime="17:00:00"
+/>
+```
+
+The AM/PM control visually matches Recursica's `Dropdown` component exactly, rather than a native `<select>`.
+
 ---
 
 ## 3. Design System Integration
@@ -31,6 +46,12 @@ All Recursica components in the `@recursica/mantine-adapter` package adhere stri
 
 > [!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.
+
+---
+
+## 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/Timeline/USAGE.md

@@ -44,14 +44,6 @@ All Recursica components in the `@recursica/mantine-adapter` package adhere stri
 
 ## 4. Key Integration Features & Constraints
 
-## Architecture
+`Timeline.Item` accepts a `timestamp` prop that renders below the item's content, and a `bulletVariant` prop (`"default" | "avatar" | "icon" | "icon-alternative"`) to control the bullet's appearance. The `lineWidth` and `bulletSize` props are not configurable, since geometry is controlled by the design system tokens.
 
-The `Timeline` component is a strict structural wrapper around Mantine's `<Timeline>` and `<Timeline.Item>` components.
-
-- `Timeline.tsx` intercepts overarching properties like `lineWidth` and `bulletSize` to strip them out via `overStyled`, strictly adhering to the CSS token mapping in `.item` rules instead.
-- `TimelineItem.tsx` implements a custom `timestamp` React node rendering slot to match the design system, positioning the text directly below the item's `children`.
-- `TimelineItem.tsx` supports a custom `bulletVariant` prop (`"default" | "avatar" | "icon" | "icon-alternative"`) mapped onto `data-variant` to handle CSS variations dynamically.
-
-## 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 Mantine's connector line `calc()` equations, 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.
+A known limitation: when using `bulletVariant="avatar"`, the avatar bullet always renders at the default bullet size rather than a custom size.

package/src/components/Toast/USAGE.md

@@ -23,7 +23,7 @@ export default function Demo() {
     <Toast
       title="Success"
       message="Your action completed successfully"
-      state="success"
+      variant="success"
     />
   );
 }
@@ -45,36 +45,6 @@ All Recursica components in the `@recursica/mantine-adapter` package adhere stri
 
 ## 4. Key Integration Features & Constraints
 
-## 1. Standalone Visual Wrapper
+`Toast` can be used directly for a static or inline message, or wired up to `@mantine/notifications` for dynamic popups. The `variant` prop (`"default" | "error" | "success"`) controls the toast's color treatment.
 
-**Decision:** We wrap `@mantine/core`'s standalone `Notification` component instead of wrapping the `@mantine/notifications` provider.
-
-**Implementation:** The UI Kit provides variables for the `Toast` component itself (e.g., `--recursica_ui-kit_components_toast_*`). We use these variables to style the standard Mantine `Notification` element. This allows developers to use `<Toast>` manually if they want a static or inline message.
-
-If dynamic popups are required, developers can configure `@mantine/notifications` to utilize this component or use its classes.
-
----
-
-## 2. Variant Mapping via `data-variant`
-
-**Decision:** `variant` props (`"default" | "error" | "success"`) are mapped directly to `data-variant` on the Mantine root `Box`.
-
-**Implementation:** Mantine's `Notification` doesn't inherently support our custom variants out of the box in the way we want them styled. By passing `data-variant` directly to the `Box`, we can explicitly target the root element in our `Toast.module.css` (e.g., `.root[data-variant="success"]`) and pipe in the corresponding UI Kit layer colors.
-
----
-
-## 3. Minimal CSS Override Philosophy
-
-**Decision:** The CSS module only overrides visual design tokens (colors, typography, padding, borders, shadows).
-
-**Implementation:** We defer layout structure, icon rendering, loader transitions, and close button mechanics to Mantine. The `border-style: none;` is hardcoded to reset any underlying styles from Mantine's defaults, ensuring a clean mapping of elevation and shadows.
-
----
-
-## 4. Unsupported `loading` State
-
-**Decision:** The native `loading` state is explicitly stripped and bypassed from the `<Toast />` component wrapper.
-
-**Implementation:** Mantine's `Notification` inherently supports a `loading={true}` state that natively spins up a loader instead of an icon. However, Recursica's UI Kit strictly does not define structural tokens for loader states inside toasts.
-Instead of attempting to tightly couple the internal `Loader` abstraction or mapping variables incorrectly, the `loading` property is explicitly omitted and `false`-enforced from the public API.
-If consumers explicitly require a loading toast, they must manually inject a `<Loader />` component into the `icon` slot.
+The `loading` state is not supported. If a loading toast is needed, pass a `<Loader />` component into the `icon` slot instead.

package/src/components/Tooltip/USAGE.md

@@ -53,63 +53,21 @@ All Recursica components in the `@recursica/mantine-adapter` package adhere stri
 
 ---
 
-## 2. Token Namespace: `tooltip`
+## 2. Behavior Notes
 
-**Decision:** The CSS module exclusively uses variables from the `--recursica_ui-kit_components_tooltip_*` namespace.
-
-**Implementation:** The Recursica token system defines the `tooltip` namespace covering:
-
-- Geometry: border-radius, border-size, min-width, min-height, max-width, padding
-- Typography: text_font-\* (family, size, style, weight, letter-spacing, line-height, text-decoration, text-transform)
-- Colors (layer-aware): background, border-color, text
-- Elevation: box-shadow
-- Beak: beak-size (16px), beak-inset (8px)
-
-No tokens from other component namespaces are referenced.
-
----
-
-## 3. Hardcoded Values
-
-### `border-style: solid` (CSS module)
-
-Mantine renders the tooltip using its `Box` component, which does not set `border-style` natively. Without this hardcoded value, the border-width and border-color tokens would have no visible effect. Same pattern as Menu and HoverCard dropdowns.
-
-### `arrowSize` defaulted to `16` (Tooltip.tsx)
-
-Mantine's `arrowSize` prop is a JavaScript number used for inline style calculations: it sets `width`, `height`, and a positioning offset (`-arrowSize/2`) directly on the arrow `<div>` element. These inline styles cannot be overridden via CSS without `!important`, and the positioning offset has no CSS equivalent. The beak size cannot be fully CSS-driven.
-
-The default value `16` matches the Recursica `beak-size` token (`--recursica_ui-kit_components_tooltip_properties_beak-size: 16px`). Developers can override `arrowSize` if needed. This is documented as an open issue in `docs/COMPONENT_ISSUES.md`.
-
-**Note:** Mantine calls this the "arrow"; Recursica calls it the "beak". The Recursica prop `withBeak` (defaulting to `true`) maps to Mantine's `withArrow`. Both are accepted; `withBeak` takes precedence.
-
-### `multiline={true}` (Tooltip.tsx)
-
-Mantine's `multiline` prop controls whether tooltip text wraps (`white-space: nowrap` when false). Recursica always enables multiline because the design system defines a `max-width` token (300px) — text should wrap naturally within that constraint rather than overflowing. The `multiline` prop is not exposed to developers.
-
-### Flexbox centering (CSS module)
-
-`display: flex; align-items: center; justify-content: center;` is applied to the `.tooltip` class. This ensures text is vertically and horizontally centered within the `min-height: 48px` container defined by the design token. Without this, text sits at the top of the tooltip.
+Tooltip text always wraps to fit within the token-defined max width, rather than staying on a single line or overflowing. The `multiline` prop is not exposed, since this behavior is always on.
 
 ---
 
-## 4. Recursica `withBeak` Prop
+## 3. Recursica `withBeak` Prop
 
 **Decision:** `withBeak` is the official Recursica prop for controlling beak visibility, defaulting to `true`.
 
-**Implementation:** Both `withBeak` and Mantine's `withArrow` are accepted. Resolution order: `withBeak ?? withArrow`. When both are provided, `withBeak` takes precedence. The default of `true` means tooltips show the beak by default, matching the Recursica design intent.
+**Implementation:** Both `withBeak` and Mantine's `withArrow` are accepted. When both are provided, `withBeak` takes precedence. The beak's size can be adjusted via the `arrowSize` prop (default `16`).
 
 ---
 
-## 5. ClassNames Binding
-
-**Decision:** CSS module classes are bound via the `classNames` prop on Mantine's Tooltip root.
-
-**Implementation:** The stylesNames for Tooltip are `tooltip` (the container) and `arrow` (the beak). Both are mapped to their respective CSS module classes: `{ tooltip: styles.tooltip, arrow: styles.arrow }`. Consumer-provided `classNames` are merged additively when `overStyled` is true.
-
----
-
-## 6. Tooltip.Floating and Tooltip.Group
+## 4. Tooltip.Floating and Tooltip.Group
 
 **Decision:** These static sub-components are direct pass-throughs to Mantine with no Recursica styling.
 
@@ -117,8 +75,6 @@ Mantine's `multiline` prop controls whether tooltip text wraps (`white-space: no
 
 ---
 
-## 7. Default Position Override
-
-**Decision:** Recursica defaults `position` to `"top"`. Mantine defaults to `"bottom"`.
+## 5. Default Position
 
-**Implementation:** The `position="top"` default is set on the Mantine root element before the prop spread, so developer-provided `position` values still take precedence. This aligns with Recursica's design intent for overlay components to appear above their trigger by default.
+Recursica defaults `position` to `"top"` instead of Mantine's default of `"bottom"`. Pass your own `position` value to override it.