@recursica/adapter-mantine-v8 1.0.0

package/src/components/AutoComplete/AutoComplete.stories.tsx

@@ -0,0 +1,336 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { AutoComplete } from "./AutoComplete";
+import { formControlArgTypes } from "../../../.storybook/commonArgTypes";
+import { renderRichOption } from "../../utils/renderRichOption";
+import styles from "./AutoComplete.module.css";
+
+const meta: Meta<typeof AutoComplete> = {
+  title: "UI-Kit/AutoComplete",
+  component: AutoComplete,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+The \`AutoComplete\` primitive provides a text input with a dropdown menu for displaying suggestions as the user types.
+
+### Architectural Decoupling
+Recursica wraps the internal Mantine \`<Autocomplete>\` component inside the \`WithReadOnlyWrapper\`, ensuring it integrates perfectly with the strict design system form architecture.
+
+### Examples
+Always structure horizontal architectures via the generic \`formLayout\` parameter.
+\`\`\`tsx
+<AutoComplete 
+  label="Country" 
+  assistiveText="Select your country of residence." 
+  data={["United States", "Canada", "Mexico", "United Kingdom", "France"]}
+  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.",
+    },
+    wrapItemText: {
+      control: "boolean",
+      description:
+        "Wraps option label/supportingText onto additional lines instead of truncating with an ellipsis.",
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof AutoComplete>;
+
+export const Default: Story = {
+  args: {
+    disabled: false,
+    readOnly: false,
+    label: "Country Selection",
+    placeholder: "Start typing...",
+    data: [
+      "United States",
+      "Canada",
+      "Mexico",
+      "United Kingdom",
+      "France",
+      "Germany",
+      "Japan",
+      "Brazil",
+      "India",
+      "Australia",
+    ],
+    assistiveText: "Search from a predefined list of countries.",
+  },
+};
+
+export const FormsSideBySide: Story = {
+  args: {
+    label: "Primary Region",
+    placeholder: "Select region...",
+    data: ["US-East", "US-West", "EU-Central", "AP-South", "SA-East"],
+    assistiveText:
+      "Select the primary region for the deployment. This violently long string tests native textual wrapping safely mapping alongside inputs.",
+    formLayout: "side-by-side",
+  },
+};
+
+export const WithLeadingIcon: Story = {
+  args: {
+    label: "Search Projects",
+    placeholder: "Project name...",
+    data: ["Alpha", "Beta", "Gamma", "Delta", "Epsilon"],
+    leftSection: (
+      <svg
+        width="24"
+        height="24"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="2"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      >
+        <circle cx="11" cy="11" r="8"></circle>
+        <line x1="21" y1="21" x2="16.65" y2="16.65"></line>
+      </svg>
+    ),
+  },
+};
+
+export const WithTrailingIcon: Story = {
+  args: {
+    label: "Validation URL",
+    placeholder: "https://recursica.dev",
+    data: [
+      "https://recursica.dev",
+      "https://beta.recursica.dev",
+      "https://api.recursica.dev",
+    ],
+    rightSection: (
+      <svg
+        width="24"
+        height="24"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="2"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      >
+        <polyline points="20 6 9 17 4 12"></polyline>
+      </svg>
+    ),
+  },
+};
+
+const UserIcon = (
+  <svg
+    width="16"
+    height="16"
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    strokeWidth="2"
+    strokeLinecap="round"
+    strokeLinejoin="round"
+  >
+    <path d="M20 21v-2a4 4 0 0 0-4-4H8a4 4 0 0 0-4 4v2"></path>
+    <circle cx="12" cy="7" r="4"></circle>
+  </svg>
+);
+
+export const WithRichOptions: Story = {
+  args: {
+    label: "Assignee",
+    placeholder: "Search team members...",
+    data: [
+      {
+        value: "jdoe",
+        label: "Jane Doe",
+        leadingIcon: UserIcon,
+        supportingText: "jane.doe@example.com",
+      },
+      {
+        value: "asmith",
+        label: "Alex Smith",
+        leadingIcon: UserIcon,
+        supportingText: "alex.smith@example.com",
+      },
+      { value: "unassigned", label: "Unassigned" },
+    ],
+    assistiveText:
+      "Each option can show a leading icon and supporting text — see MANTINE_ADAPTER_RICH_OPTION_DATA.md.",
+  },
+};
+
+export const WithRichOptionsWrapped: Story = {
+  args: {
+    label: "Assignee",
+    placeholder: "Search team members...",
+    wrapItemText: true,
+    data: [
+      {
+        value: "jdoe",
+        label: "Jane Doe, Senior Staff Engineer, Platform Infrastructure",
+        leadingIcon: UserIcon,
+        supportingText:
+          "jane.doe@example.com — Platform Infrastructure team, on-call rotation lead",
+      },
+      { value: "unassigned", label: "Unassigned" },
+    ],
+    assistiveText:
+      "wrapItemText=true — long label/supportingText wrap instead of truncating.",
+  },
+};
+
+const optionRowPreviewClassNames = {
+  optionContent: styles.optionContent,
+  optionIcon: styles.optionIcon,
+  optionText: styles.optionText,
+  optionTextWrap: styles.optionTextWrap,
+  optionSupportingText: styles.optionSupportingText,
+};
+
+const OPTION_ROW_PREVIEW_ITEMS = [
+  {
+    value: "icon-and-supporting",
+    label: "Jane Doe",
+    leadingIcon: UserIcon,
+    supportingText: "jane.doe@example.com",
+  },
+  {
+    value: "no-icon",
+    label: "Alex Smith",
+    supportingText:
+      "No leadingIcon — label/supportingText shift left, no reserved icon space",
+  },
+  {
+    value: "no-supporting-text",
+    label: "Taylor Rivera",
+    leadingIcon: UserIcon,
+  },
+  {
+    value: "plain",
+    label: "Plain option — no leadingIcon, no supportingText",
+  },
+  {
+    value: "long-text",
+    label:
+      "A very long option label that, with wrapItemText, wraps onto a second line instead of overflowing the fixed-width dropdown — otherwise it truncates with an ellipsis",
+    leadingIcon: UserIcon,
+    supportingText:
+      "A similarly long supporting text string, to confirm the same wrap-or-truncate behavior applies to it too",
+  },
+];
+
+// Renders the option row content directly — outside the floating/portal menu — inside a
+// container sized to AutoComplete's own max-width token. Spacing between rows, icon/
+// supportingText presence-or-absence alignment, and long-text wrapping/truncation are all much
+// easier to inspect this way than by opening the real (portal-rendered) combobox dropdown. See
+// MANTINE_ADAPTER_RICH_OPTION_DATA.md.
+const renderOptionRowPreview = (wrapItemText: boolean) => (
+  <div
+    className={styles.dropdown}
+    style={{
+      width:
+        "var(--recursica_ui-kit_components_autocomplete_variants_layouts_stacked_properties_max-width)",
+    }}
+  >
+    {OPTION_ROW_PREVIEW_ITEMS.map((item) => (
+      <div key={item.value} className={styles.option}>
+        {renderRichOption(
+          { option: item },
+          optionRowPreviewClassNames,
+          wrapItemText,
+        )}
+      </div>
+    ))}
+  </div>
+);
+
+// Default: `wrapItemText` is false — label/supportingText truncate to a single line with an
+// ellipsis instead of wrapping.
+export const RichOptionRowPreview: Story = {
+  parameters: {
+    controls: { disable: true },
+  },
+  render: () => renderOptionRowPreview(false),
+};
+
+// `wrapItemText: true` — label/supportingText wrap onto additional lines instead of truncating.
+export const RichOptionRowPreviewWrapped: Story = {
+  parameters: {
+    controls: { disable: true },
+  },
+  render: () => renderOptionRowPreview(true),
+};
+
+export const Disabled: Story = {
+  args: {
+    label: "Disabled Deployment Node",
+    placeholder: "Disabled primitive map...",
+    data: ["Node 1", "Node 2", "Node 3"],
+    disabled: true,
+  },
+};
+
+export const ErrorState: Story = {
+  args: {
+    label: "Cluster Failure",
+    placeholder: "Failing component instance...",
+    data: ["Cluster A", "Cluster B", "Cluster C"],
+    defaultValue: "Invalid Cluster",
+    error:
+      "Critical runtime node disconnect detected traversing DOM architecture.",
+    required: true,
+  },
+};
+
+export const StaticReadOnly: Story = {
+  args: {
+    label: "Static ReadOnly Review",
+    placeholder: "Ignored...",
+    data: ["Option 1", "Option 2"],
+    value: "Explicitly Uneditable Bound Output",
+    readOnly: true,
+  },
+};
+
+export const EditableReadOnly: Story = {
+  args: {
+    label: "Editable ReadOnly Review",
+    placeholder: "Ignored until active...",
+    data: ["Option 1", "Option 2"],
+    defaultValue: "Waiting for Edit Execution",
+    readOnly: true,
+    labelWithEditIcon: true,
+  },
+};

package/src/components/AutoComplete/AutoComplete.test.tsx

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

package/src/components/AutoComplete/AutoComplete.tsx

@@ -0,0 +1,179 @@
+import React, { forwardRef } from "react";
+import {
+  Autocomplete as MantineAutocomplete,
+  type AutocompleteProps as MantineAutocompleteProps,
+  type InputWrapperProps,
+} from "@mantine/core";
+import {
+  type ReadOnlyControlProps,
+  normalizeComboboxData,
+} from "@recursica/adapter-common";
+import {
+  filterStylingProps,
+  omitUnsupportedProps,
+  mergeClassNames,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import { type RecursicaFormControlWrapperProps } from "../FormControlWrapper/FormControlWrapper";
+import { WithReadOnlyWrapper } from "../ReadOnlyField/WithReadOnlyWrapper";
+import { renderRichOption } from "../../utils/renderRichOption";
+import styles from "./AutoComplete.module.css";
+
+import { type RecursicaAutocompleteProps as BaseRecursicaAutocompleteProps } from "@recursica/adapter-common";
+
+export interface RecursicaAutoCompleteProps
+  extends Omit<
+      MantineAutocompleteProps,
+      | "size"
+      | "variant"
+      | "radius"
+      | "wrapperProps"
+      | "data"
+      | "defaultValue"
+      | "value"
+    >,
+    Pick<
+      InputWrapperProps,
+      "label" | "error" | "required" | "withAsterisk" | "id"
+    >,
+    Omit<
+      RecursicaFormControlWrapperProps,
+      "controlMaxWidth" | "controlMinWidth"
+    >,
+    ReadOnlyControlProps,
+    BaseRecursicaAutocompleteProps {
+  /** Current input value */
+  value?: string;
+}
+
+export type AutoCompleteProps = RecursicaOverStyled<RecursicaAutoCompleteProps>;
+
+// Props this component intentionally doesn't support — deleted at runtime so they can't leak
+// through even if a caller forces them via plain JavaScript, bypassing the `Omit<>` above.
+const UNSUPPORTED_PROPS = [
+  "size", // Recursica controls sizing via the `size` variant + design tokens, not raw dimensions.
+  "variant", // Colors/variants are token-driven; the library's native palette isn't exposed.
+  "radius", // Recursica does not expose the library's native corner-radius system.
+] as const satisfies readonly (keyof MantineAutocompleteProps)[];
+
+export const AutoComplete = forwardRef<HTMLInputElement, AutoCompleteProps>(
+  function AutoComplete(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,
+      data,
+      renderOption,
+      wrapItemText = false,
+      ...rest
+    } = props;
+
+    const sanitizedProps = omitUnsupportedProps(
+      filterStylingProps(rest, overStyled) as Record<string, unknown>,
+      UNSUPPORTED_PROPS,
+    );
+    const restRecord = sanitizedProps as Record<string, unknown>;
+
+    // Mantine's own data parser only preserves extra fields (`leadingIcon`/`supportingText`) when
+    // an item already has both `value` and `label` — an item with `value` only is rebuilt into a
+    // bare `{value, label: value, disabled}` object, silently dropping them (see
+    // get-parsed-combobox-data.mjs). `normalizeComboboxData` backfills `label` so the rich fields
+    // always survive regardless of whether the caller set it.
+    const normalizedData = normalizeComboboxData(data);
+
+    // Securely map core native blocks down ensuring nested CSS modules map precisely
+    const mergedClassNames = mergeClassNames(
+      {
+        wrapper: styles.root, // The nested Input internal relative wrapper bounding box
+        input: styles.input,
+        section: styles.section,
+        dropdown: styles.dropdown,
+        option: styles.option,
+      },
+      restRecord.classNames as Partial<Record<string, string>> | undefined,
+    );
+
+    const optionClassNames = {
+      optionContent: styles.optionContent,
+      optionIcon: styles.optionIcon,
+      optionText: styles.optionText,
+      optionTextWrap: styles.optionTextWrap,
+      optionSupportingText: styles.optionSupportingText,
+    };
+
+    const wrapperClass = className
+      ? `${styles.layoutOverride} ${className}`
+      : styles.layoutOverride;
+
+    return (
+      <WithReadOnlyWrapper
+        className={wrapperClass}
+        style={style as React.CSSProperties}
+        controlMaxWidth="var(--autocomplete-control-max-width)"
+        controlMinWidth="var(--autocomplete-control-min-width)"
+        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={value !== undefined ? value : defaultValue}
+        readOnlyNativeProps={props}
+        activeComponent={
+          /* Naked Input execution safely decoupled from Mantine's macro Input.Wrapper DOM hooks */
+          <MantineAutocomplete
+            ref={ref}
+            {...(sanitizedProps as unknown as MantineAutocompleteProps)}
+            classNames={mergedClassNames}
+            disabled={disabled}
+            value={value as string | undefined}
+            defaultValue={defaultValue as string | undefined}
+            error={!!error}
+            data={normalizedData as unknown as MantineAutocompleteProps["data"]}
+            renderOption={
+              renderOption ??
+              ((input) =>
+                renderRichOption(input, optionClassNames, wrapItemText))
+            }
+          />
+        }
+      />
+    );
+  },
+);
+
+AutoComplete.displayName = "AutoComplete";

package/src/components/AutoComplete/USAGE.md

@@ -0,0 +1,80 @@
+# AutoComplete - Usage Guide
+
+This document describes how to integrate and use the `AutoComplete` component in your projects using `@recursica/adapter-mantine-v8`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { AutoComplete } from "@recursica/adapter-mantine-v8";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { AutoComplete } from "@recursica/adapter-mantine-v8";
+
+export default function Demo() {
+  return (
+    <AutoComplete
+      label="Country"
+      placeholder="Type a country name..."
+      data={["USA", "Canada", "Mexico"]}
+    />
+  );
+}
+```
+
+---
+
+## 3. Design System Integration
+
+All Recursica components in the `@recursica/adapter-mantine-v8` package adhere strictly to design system spacing, scaling, and behavior patterns.
+
+> [!IMPORTANT]
+>
+> - **Anti-override protection**: Rogues style injections (like inline `style` or arbitrary `className`) are automatically blocked by our prop layer unless `overStyled={true}` is explicitly provided.
+> - **No Direct Layers**: Do not pass a `layer` prop to this component. To place it on a specific visual layer, wrap it in a `<Layer layer={0|1|2|3}>` component natively.
+> - **Variables and Theming**: Styling is entirely determined by local CSS variables defined in `recursica_variables_scoped.css` and mapped in the component's CSS module.
+
+---
+
+## 4. Key Integration Features & Constraints
+
+### Rich option content: `leadingIcon` / `supportingText`
+
+`data` items can carry an icon and a secondary line of text, rendered inside each option row:
+
+```tsx
+<AutoComplete
+  label="Assignee"
+  data={[
+    {
+      value: "jdoe",
+      label: "Jane Doe",
+      leadingIcon: <UserIcon />,
+      supportingText: "jane.doe@example.com",
+    },
+    { value: "asmith", label: "Alex Smith" },
+  ]}
+/>
+```
+
+- `label` is optional, same as always — items with `value` only still work, falling back to
+  `value` as the displayed/matched text.
+- Pass your own `renderOption` to opt out of this default rendering entirely for a given
+  component instance.
+- By default `label`/`supportingText` truncate to a single line with an ellipsis. Set
+  `wrapItemText` to wrap them onto additional lines instead:
+
+```tsx
+<AutoComplete data={data} wrapItemText />
+```
+
+### Known Limitation: Selected Option Highlight
+
+Hover works (see `.option:hover`/`.option[data-hovered="true"]`), but there's no distinct "this option matches the current value" background — unlike `Dropdown`, which has one. This isn't a styling gap: Mantine's `Autocomplete` never passes a `value` prop into its internal `OptionsDropdown` (only `search`, for filtering — see `Autocomplete.mjs`), so `checked`/`data-combobox-active` (the attribute that drives `Dropdown`'s equivalent highlight) never gets set on any option, regardless of what's typed into the field. There's no other DOM signal to key a CSS rule off. Would need either an upstream Mantine change or reimplementing option rendering ourselves with a value comparison.

package/src/components/Avatar/AVATAR_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,34 @@
+# Avatar Component Implementation Notes
+
+## Architecture Decisions
+
+The `Avatar` component is an adapter over Mantine's `Avatar`. To ensure adherence to the `COMPONENT_GUIDE_WALKTHROUGH.md`:
+
+- We do not wrap `MantineAvatar` in any custom standard `div` elements, preserving DOM structure.
+- All styles strictly pull from explicit `--recursica_ui-kit_components_avatar_*` CSS tokens.
+
+## Structural Workarounds
+
+### Implicit `data-style`
+
+Mantine's Avatar implicitly renders an image, an icon, or a text node based on the properties passed (`src`, `var`, `children`).
+Recursica Tokens split Avatar styling distinctly across three separate categories: `image`, `icon`, and `text`.
+To correctly map these variables, our React component observes standard prop states and manually injects a `data-style="image|icon|text"` onto the root. The `Avatar.module.css` explicitly gates padding and generic sizing modifiers under these `data-style` attributes.
+
+### Flex Layout & Internal Spans
+
+Since Avatar children (icons or initials) require robust centering that might differ heavily across Recursica size mappings, all child content defaults to being wrapped in `span` elements (either `.textWrapper` or `.iconWrapper`). These spans enforce 100% height and flex formatting independent of the Mantine container constraints.
+
+### CSS Reset Hacks
+
+Noticeable `/* HARDCODE: ... */` hacks are deployed within `.root` to completely zero-out Mantine's `--avatar-bg` and internal variables statically since Recursica handles background-colors inherently via the CSS variants cascade.
+
+### `variant` mapping is a genuine match here (unlike MUI's)
+
+Mantine's native `Avatar.variant` (`'filled'|'light'|'gradient'|'outline'|'transparent'|...`)
+really is the same color-treatment concept Recursica's own `variant` is, so `mapVariant`
+(`solid→filled, outline→outline, ghost→transparent`) is a correct, meaningful mapping — even
+though the CSS reset hack above means it's visually inert either way. Worth noting only because
+the MUI adapter's `Avatar.variant` means something completely different (shape) and had a real
+bug from assuming the same word meant the same thing there; see mui-adapter's own
+`AVATAR_IMPLEMENTATION_NOTES.md`.