@recursica/mantine-adapter 0.5.0 → 0.7.0

package/dist/src/components/ReadOnlyField/ReadOnlyField.d.ts

@@ -1,3 +1,20 @@
 import { default as React } from 'react';
-export type ReadOnlyFieldProps = React.HTMLAttributes<HTMLDivElement>;
-export declare const ReadOnlyField: React.FC<ReadOnlyFieldProps>;
+import { ReadOnlyFieldType } from '@recursica/adapter-common';
+import { RecursicaOverStyled } from '../../utils/filterStylingProps';
+import { FormControlWrapperProps } from '../FormControlWrapper/FormControlWrapper';
+export interface RecursicaReadOnlyFieldProps extends Omit<FormControlWrapperProps, "children" | "overStyled"> {
+    /** The specific value to be rendered in read-only mode explicitly matching the original field input */
+    value?: any;
+    /** The data type formatting rules bounding how the string is presented to the user */
+    type?: ReadOnlyFieldType;
+    /** Custom renderer explicitly responsible for formatting missing/empty value mappings (overriding default 'N/A') */
+    emptyValueComponent?: React.ElementType<{
+        value?: any;
+    }>;
+}
+export type ReadOnlyFieldProps = RecursicaOverStyled<RecursicaReadOnlyFieldProps>;
+/**
+ * A native generic form control wrapper exclusively responsible for displaying fixed data.
+ * Internally maps to structural ReadOnly primitive blocks bridging standard `FormControlWrapper` layouts natively.
+ */
+export declare const ReadOnlyField: React.ForwardRefExoticComponent<ReadOnlyFieldProps & React.RefAttributes<HTMLDivElement>>;

package/dist/src/components/ReadOnlyField/ReadOnlyTextField.d.ts

@@ -0,0 +1,8 @@
+import { default as React } from 'react';
+import { RecursicaOverStyled } from '../../utils/filterStylingProps';
+export interface RecursicaReadOnlyTextFieldProps {
+    /** The value strictly rendered as text output */
+    value?: any;
+}
+export type ReadOnlyTextFieldProps = RecursicaOverStyled<RecursicaReadOnlyTextFieldProps>;
+export declare const ReadOnlyTextField: React.FC<ReadOnlyTextFieldProps>;

package/dist/src/components/ReadOnlyField/WithReadOnlyWrapper.d.ts

@@ -0,0 +1,22 @@
+import { default as React } from 'react';
+import { ReadOnlyFieldType } from '@recursica/adapter-common';
+import { FormControlWrapperProps } from '../FormControlWrapper/FormControlWrapper';
+export interface WithReadOnlyWrapperProps extends Omit<FormControlWrapperProps, "children" | "overStyled"> {
+    /** Injects whether the field defaults to reading mode natively */
+    readOnly?: boolean;
+    /** Explicit React component directly overtaking the baseline text renderer when read-only mode is active */
+    readOnlyComponent?: React.ReactNode;
+    /** Instructs the underlying generic ReadOnlyField which raw visual structure to bridge automatically */
+    readOnlyType?: ReadOnlyFieldType;
+    /** The isolated raw data value intercepted explicitly into the ReadOnly formatters */
+    readOnlyValue?: any;
+    /** Safely enables deep Mantine overrides transparently bypassing block filters */
+    overStyled?: boolean;
+    /** The nested active node dynamically exposed exclusively when read-only bounds are disabled */
+    activeComponent: React.ReactNode;
+}
+/**
+ * Universal execution barrier trapping readOnly states globally.
+ * Natively delegates active logic down avoiding duplicative internal component bindings dynamically.
+ */
+export declare const WithReadOnlyWrapper: React.ForwardRefExoticComponent<WithReadOnlyWrapperProps & React.RefAttributes<HTMLDivElement>>;

package/dist/src/components/ReadOnlyField/index.d.ts

@@ -0,0 +1,3 @@
+export * from './ReadOnlyField';
+export * from './WithReadOnlyWrapper';
+export * from './ReadOnlyTextField';

package/dist/src/components/Text/Text.d.ts

@@ -0,0 +1,17 @@
+import { ReactNode } from 'react';
+import { TextProps as MantineTextProps } from '@mantine/core';
+import { RecursicaOverStyled } from '../../utils/filterStylingProps';
+export type TextVariant = "body" | "body-small" | "caption" | "overline" | "subtitle" | "subtitle-small";
+export type RecursicaTextProps = Omit<MantineTextProps, "variant"> & {
+    /**
+     * The explicit typography hierarchy dictated by Recursica's global design tokens.
+     */
+    variant?: TextVariant;
+    children?: ReactNode;
+};
+export type TextProps = RecursicaOverStyled<RecursicaTextProps>;
+/**
+ * A generalized typographical wrapper limiting text properties to bounded Recursica UI-kit tokens inherently.
+ * Do not use for semantic headings; use the explicit `<Title>` component for `<h1>` - `<h6>`.
+ */
+export declare const Text: import('react').ForwardRefExoticComponent<TextProps & import('react').RefAttributes<HTMLDivElement>>;

package/dist/src/components/TextField/TextField.d.ts

@@ -1,3 +1,9 @@
 import { default as React } from 'react';
-export type TextFieldProps = React.HTMLAttributes<HTMLDivElement>;
-export declare const TextField: React.FC<TextFieldProps>;
+import { InputProps, InputWrapperProps } from '@mantine/core';
+import { ReadOnlyControlProps } from '@recursica/adapter-common';
+import { RecursicaOverStyled } from '../../utils/filterStylingProps';
+import { RecursicaFormControlWrapperProps } from '../FormControlWrapper/FormControlWrapper';
+export interface RecursicaTextFieldProps extends Omit<InputProps, "size" | "variant" | "radius" | "wrapperProps">, Pick<InputWrapperProps, "label" | "error" | "required" | "withAsterisk" | "id">, Omit<React.ComponentPropsWithoutRef<"input">, "size" | "style" | "className" | "id">, Omit<RecursicaFormControlWrapperProps, "controlMaxWidth" | "controlMinWidth">, ReadOnlyControlProps {
+}
+export type TextFieldProps = RecursicaOverStyled<RecursicaTextFieldProps>;
+export declare const TextField: React.ForwardRefExoticComponent<TextFieldProps & React.RefAttributes<HTMLInputElement>>;

package/dist/src/components/Title/Title.d.ts

@@ -0,0 +1,13 @@
+import { TitleProps as MantineTitleProps } from '@mantine/core';
+import { RecursicaOverStyled } from '../../utils/filterStylingProps';
+export type RecursicaTitleProps = Omit<MantineTitleProps, "order"> & {
+    /**
+     * Enforces semantic HTML headers (h1-h6) cleanly bound to native typographic scaling variables in the design system.
+     */
+    order?: 1 | 2 | 3 | 4 | 5 | 6;
+};
+export type TitleProps = RecursicaOverStyled<RecursicaTitleProps>;
+/**
+ * Enforces highly accessible structural markup utilizing semantic `<h1>` through `<h6>` tags securely bound directly to Recursica typographic scales.
+ */
+export declare const Title: import('react').ForwardRefExoticComponent<TitleProps & import('react').RefAttributes<HTMLHeadingElement>>;

package/dist/src/components/index.d.ts

@@ -5,6 +5,7 @@ export * from './Breadcrumb/Breadcrumb';
 export * from './Button';
 export * from './Card/Card';
 export * from './Checkbox/Checkbox';
+export * from './Checkbox/CheckboxGroup';
 export * from './Chip/Chip';
 export * from './DatePicker/DatePicker';
 export * from './Dropdown/Dropdown';
@@ -13,6 +14,7 @@ export * from './FileUpload/FileUpload';
 export * from './HoverCard/HoverCard';
 export * from './Link/Link';
 export * from './Loader/Loader';
+export * from './Label';
 export * from './Menu/Menu';
 export * from './Modal/Modal';
 export * from './NumberInput/NumberInput';
@@ -20,7 +22,7 @@ export * from './Pagination/Pagination';
 export * from './Panel/Panel';
 export * from './Popover/Popover';
 export * from './Radio/Radio';
-export * from './ReadOnlyField/ReadOnlyField';
+export * from './ReadOnlyField';
 export * from './Search/Search';
 export * from './SegmentedControl/SegmentedControl';
 export * from './Slider/Slider';

package/dist/src/utils/ColorSchemeWrapper.d.ts

@@ -0,0 +1,3 @@
+export declare function ColorSchemeWrapper({ children, }: {
+    children: React.ReactNode;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/src/utils/filterStylingProps.d.ts

@@ -21,9 +21,13 @@
  * @param overStyled - Boolean toggle to allow raw external styling. Defaults to false.
  * @returns Sanitized component props safe for internal styling merging
  */
-export declare const BLOCKED_STYLING_KEYS: readonly ["className", "classNames", "style", "styles", "vars", "p", "px", "py", "pt", "pb", "pl", "pr", "bg", "c", "opacity", "ff", "fz", "fw", "lts", "ta", "lh", "fs", "tt", "td", "bd", "bdw", "bds", "bdc", "bdr", "shadow"];
+export declare const BLOCKED_STYLING_KEYS: readonly ["className", "classNames", "style", "styles", "vars", "p", "px", "py", "pt", "pb", "pl", "pr", "bg", "c", "opacity", "ff", "fz", "fw", "lts", "ta", "lh", "fs", "tt", "td", "bd", "bdw", "bds", "bdc", "bdr", "shadow", "w", "miw", "maw", "h", "mih", "mah"];
 export type BlockedStylingKeys = (typeof BLOCKED_STYLING_KEYS)[number];
-export type RecursicaOverStyled<T> = (Omit<T, BlockedStylingKeys> & {
+export type RecursicaSpacing = "rec-none" | "rec-sm" | "rec-default" | "rec-md" | "rec-lg" | "rec-xl" | "rec-2xl";
+export type ForbiddenStyles = {
+    [K in BlockedStylingKeys]?: never;
+};
+export type RecursicaOverStyled<T> = (Omit<T, BlockedStylingKeys> & ForbiddenStyles & {
     overStyled?: false | undefined;
 }) | (T & {
     overStyled: true;

package/package.json

@@ -11,7 +11,7 @@
     "type": "git",
     "url": "git+https://github.com/borderux/recursica.git"
   },
-  "version": "0.5.0",
+  "version": "0.7.0",
   "type": "module",
   "main": "./dist/mantine-adapter.cjs",
   "module": "./dist/mantine-adapter.js",
@@ -25,7 +25,10 @@
     "./style.css": "./dist/mantine-adapter.css"
   },
   "files": [
-    "dist"
+    "dist",
+    "src",
+    "CHANGELOG.md",
+    ".storybook/commonArgTypes.ts"
   ],
   "keywords": [
     "react",
@@ -72,6 +75,7 @@
     "sass": "^1.89.2",
     "sirv": "^3.0.2",
     "storybook": "^10.3.3",
+    "storybook-dark-mode": "^5.0.0",
     "strip-literal": "^3.0.0",
     "typescript": "~5.8.3",
     "typescript-eslint": "^8.30.1",
@@ -81,9 +85,9 @@
     "vitest": "^3.2.4"
   },
   "peerDependencies": {
-    "@mantine/core": ">=8.0.0",
-    "@mantine/dates": ">=8.0.0",
-    "@mantine/hooks": ">=8.0.0",
+    "@mantine/core": "^8.0.0",
+    "@mantine/dates": "^8.0.0",
+    "@mantine/hooks": "^8.0.0",
     "react": ">=16.8.0",
     "react-dom": ">=16.8.0"
   }

package/src/OverStyling.stories.tsx

@@ -0,0 +1,174 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import {
+  Container,
+  Paper,
+  Title,
+  Text,
+  List,
+  Divider,
+  Group,
+  Code,
+} from "@mantine/core";
+import { Button } from "./components/Button/Button";
+
+const OverStylingInfo = () => {
+  return (
+    <Container size="md" py="xl">
+      <Paper withBorder p="xl" radius="md">
+        <Title order={1} mb="md">
+          Over Styling (<Code>overStyled</Code>)
+        </Title>
+        <Text mb="md">
+          By default, all Recursica components are strictly sandboxed. This
+          means they are protected against arbitrary styling configurations
+          (like passing generic React <Code>style</Code> objects, custom{" "}
+          <Code>classNames</Code> injections, or using deep Mantine layout hooks
+          like <Code>bg</Code> and <Code>c</Code>). This strict compile-time and
+          run-time enforcement guarantees that your design system tokens remain
+          true across your application.
+        </Text>
+        <Text mb="md">
+          However, there may be edge cases where a developer absolutely must
+          modify a component beyond what the design tokens natively allow. For
+          this, we provide the <strong>escape hatch</strong> property:{" "}
+          <Code>overStyled={`{true}`}</Code>.
+        </Text>
+
+        <Title order={3} mb="sm">
+          The Core Philosophy
+        </Title>
+        <Text mb="sm">
+          **You should not over-style components.** Using{" "}
+          <Code>overStyled</Code> explicitly signifies that you are breaking
+          design system rules.
+        </Text>
+        <List mb="xl" type="ordered">
+          <List.Item>
+            <strong>Technical Debt:</strong> If over-styling is required, it
+            should be treated as a short-term workaround. Ideally, the component
+            will be refactored once the required layouts or variants are
+            officially integrated into the core Recursica component library.
+          </List.Item>
+          <List.Item>
+            <strong>Auditing & Searching:</strong> Because this pattern creates
+            technical debt, we enforce the explicit <Code>overStyled</Code>{" "}
+            boolean. This provides a highly auditable, easily searchable string.
+            Product managers and engineers can quickly grep the codebase for{" "}
+            <Code>overStyled</Code> (or the <Code>RecursicaOverStyled</Code>{" "}
+            typings) to hunt down components that don't match standard patterns.
+          </List.Item>
+          <List.Item>
+            <strong>Highly Custom Components:</strong> If your application
+            genuinely requires massive custom layouts that the UI kit cannot
+            support, <strong>do not hack the Recursica component</strong>.
+            Instead, it is highly encouraged that you import the underlying
+            primitive component directly from <Code>@mantine/core</Code> and
+            construct your independent feature there. While you can utilize raw
+            Recursica CSS variables on these custom components, note that they
+            are not guaranteed to be accurately maintained as Recursica evolves.
+            Keep strict components strict!
+          </List.Item>
+        </List>
+
+        <Divider mb="xl" />
+
+        <Title order={3} mb="sm">
+          Permitted Layout Properties
+        </Title>
+        <Text mb="sm">
+          Unlike deep styling bounds (colors, typography, padding, dimensions),
+          external <strong>layout spacing properties</strong> like Margins (
+          <Code>m</Code>, <Code>mt</Code>, <Code>mb</Code>, <Code>mx</Code>) are
+          safely <strong>permitted by default</strong>. This allows integrators
+          to structurally compose components alongside siblings without
+          breaching internal token boundaries.
+        </Text>
+        <Text mb="xl">
+          When using layout properties, you have the flexibility to use either
+          ecosystem seamlessly:
+        </Text>
+        <List mb="md" type="ordered">
+          <List.Item>
+            <strong>Mantine Core Values:</strong> Passing standard Mantine sizes
+            (like <Code>mt="md"</Code>) passes straight through to Mantine
+            natively, allowing you to interface completely normally with a
+            parent application's existing Mantine Theme setup that might fall
+            outside Recursica's scope.
+          </List.Item>
+          <List.Item>
+            <strong>Recursica Strict Tokens:</strong> Passing our custom
+            prefixed tokens (like <Code>mt="rec-md"</Code>) signals our internal
+            layout interceptor to securely translate the value directly to our
+            native <Code>recursica_brand_dimensions</Code> CSS variables. This
+            ensures strict design token measurements while sharing the exact
+            same prop interface!
+          </List.Item>
+        </List>
+        <Text mb="sm" fw={500}>
+          Available Recursica Layout Tokens:
+        </Text>
+        <List mb="xl" type="unordered">
+          <List.Item>
+            <Code>rec-none</Code> (0px limit)
+          </List.Item>
+          <List.Item>
+            <Code>rec-sm</Code> (0.5x scaling)
+          </List.Item>
+          <List.Item>
+            <Code>rec-default</Code> (1.0x scaling)
+          </List.Item>
+          <List.Item>
+            <Code>rec-md</Code> (1.5x scaling)
+          </List.Item>
+          <List.Item>
+            <Code>rec-lg</Code> (2.0x scaling)
+          </List.Item>
+          <List.Item>
+            <Code>rec-xl</Code> (3.0x scaling)
+          </List.Item>
+          <List.Item>
+            <Code>rec-2xl</Code> (4.0x scaling)
+          </List.Item>
+        </List>
+
+        <Divider mb="xl" />
+
+        <Title order={3} mb="md">
+          Live Example
+        </Title>
+        <Text mb="xl">
+          Below is a side-by-side comparison. The first is a standard Recursica
+          Button protected by the design tokens mapping. The second flagrantly
+          forces <Code>overStyled={`{true}`}</Code>, allowing Mantine's native
+          styling generics to punch right through the sandbox layout.
+        </Text>
+
+        <Group gap="xl">
+          <div>
+            <Text size="sm" c="dimmed" mb="xs">
+              Strict Baseline (Default)
+            </Text>
+            <Button variant="solid">Standard UI Kit Button</Button>
+          </div>
+          <div>
+            <Text size="sm" c="dimmed" mb="xs">
+              overStyled={`{true}`}
+            </Text>
+            <Button overStyled={true} bg="pink" c="black" radius="xl">
+              Unsafe Pink Marketing Button
+            </Button>
+          </div>
+        </Group>
+      </Paper>
+    </Container>
+  );
+};
+
+const meta: Meta<typeof OverStylingInfo> = {
+  title: "Introduction/Over Styling",
+  component: OverStylingInfo,
+};
+
+export default meta;
+
+export const Default: StoryObj<typeof OverStylingInfo> = {};

package/src/Version.stories.tsx

@@ -0,0 +1,56 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import ReactMarkdown from "react-markdown";
+import {
+  Container,
+  Paper,
+  Title,
+  TypographyStylesProvider,
+  Group,
+  Anchor,
+  Divider,
+} from "@mantine/core";
+import pkg from "../package.json";
+import changelog from "../CHANGELOG.md?raw";
+
+const VersionInfo = () => {
+  return (
+    <Container size="md" py="xl">
+      <Paper withBorder p="xl" radius="md">
+        <Title order={1} mb="xs">
+          Mantine Adapter v{pkg.version}
+        </Title>
+        <Group mb="xl" gap="md">
+          <Anchor
+            href="https://github.com/borderux/recursica"
+            target="_blank"
+            rel="noopener noreferrer"
+          >
+            GitHub Repository
+          </Anchor>
+          <Anchor
+            href="https://recursica.com"
+            target="_blank"
+            rel="noopener noreferrer"
+          >
+            Documentation & Website
+          </Anchor>
+        </Group>
+        <Divider mb="xl" />
+        <TypographyStylesProvider>
+          <ReactMarkdown>{changelog}</ReactMarkdown>
+        </TypographyStylesProvider>
+      </Paper>
+    </Container>
+  );
+};
+
+const meta: Meta<typeof VersionInfo> = {
+  title: "Introduction/Version Info",
+  component: VersionInfo,
+};
+
+export default meta;
+
+type Story = StoryObj<typeof VersionInfo>;
+
+export const Default: Story = {};

package/src/components/Accordion/ACCORDION_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,48 @@
+# Accordion – implementation notes
+
+Decisions and design tweaks strictly tailored for the UI Kit's Accordion wrapped against `@mantine/core`. Use this when managing components possessing deeply nested state logic (e.g., active toggles, nested headers mapping external design properties).
+
+---
+
+## 1. Hybrid Composition API (Smart Rendering Flow)
+
+**Decision:** We fundamentally maintain the exact library composition API structure (`<Accordion>`, `<Accordion.Item>`, `<Accordion.Control>`, `<Accordion.Panel>`) while actively supporting an auto-completing flattened prop schema matching the unified Recursica API (`title`, `leftIcon`, `divider`).
+**Implementation:** Avoid rigid raw parameter dumps. Mantine dynamically injects explicit `id` logic, keyboard ARIA mapping, and focus tracking correctly across `Control` to `Panel` DOM connections natively. By exposing the hierarchical mapping 1:1, Recursica safely adopts these capabilities. However, to strictly support Recursica's unified prop mapping interface:
+
+- **Auto-Construction:** If integrators natively pass `title` and/or `leftIcon` props into `<AccordionItem>`, the component structurally auto-generates the internal `AccordionControl` sub-wrappers mapping the text and SVG natively, whilst treating `children` implicitly as the Panel contents.
+- **Graceful Falldown:** If `title` is heavily omitted, the node immediately falls backward into raw Mantine composability expecting integrators mapped `<Accordion.Control>` entirely manually.
+
+---
+
+## 2. Default Configuration Reset (`unstyled`)
+
+**Decision:** We strip Mantine's inner styles away completely from Accordion mappings by leveraging React's default `variant="unstyled"`.
+**Implementation:** In `Accordion.tsx`, `<MantineAccordion>` binds `variant="unstyled"`. This effectively deletes Mantine's precomputed padding, borders, and shadow mappings allowing our targeted `classNames` inside `Accordion.module.css` to become the exact source of foundational truth without "fighting" `!important` tags or unpredictable flex-layouts inherited globally.
+
+---
+
+## 3. Strict SVG Icons Wrapper (`.iconLeftWrapper`)
+
+**Decision:** Identical logic enforced as seen within Buttons: SVG scales dynamically inside `.mantine-leftSection` based on SVGs internal definition boundaries potentially corrupting header gaps.
+**Implementation:** `AccordionControl` captures `<span className={styles.iconLeftWrapper} aria-hidden>` forcing `object-fit: contain` mapped exactly to the `properties_icon-left-size` Recursica dimension token forcing integrator SVG overrides inline perfectly.
+
+---
+
+## 4. Transparent Global Hover Fixes
+
+**Decision:** We nullify internal Mantine button hover actions and exclusively utilize Recursica's hover structure natively.
+**Implementation:** We construct `.control::after` pseudo-objects dynamically pulling our `hover-color` & `hover-opacity` bindings. Mantine's native action sets `.control:hover { background-color: var(...) }` dynamically causing internal layer overlaps. We enforce `background-color: transparent` strictly overriding it, preserving our pseudo-overlay layer-cascade cleanly.
+
+---
+
+## 5. Active Target Hooks (`[data-active]`)
+
+**Decision:** Collapsed and expanded state tracking requires separate background maps across `AccordionItem`.
+**Implementation:** Rather than syncing React `useState` hooks matching `Accordion.value`, we defer to Mantine's inherent DOM mapping: `.item[data-active]` implicitly triggers exactly when Mantine registers an expansion state swap changing values down dynamically on the element layer, perfectly binding to `--recursica_..._background-expanded`.
+
+---
+
+## 6. Nullifying Isolated State Bounds (`open` boolean)
+
+**Decision:** We do not bind isolated `open={true}` state properties natively on individual `<AccordionItem>` configurations.
+**Implementation:** Recursica natively dictates an item-level `open` tracking mapping. However, internally mapping boolean flags structurally across specific tree nodes heavily corrupts Mantine's DOM layout algorithms mapping parent-driven transition listeners. Mantine forces all expanded-height logic to run symmetrically off the `<Accordion value="...">` string matching array to accurately bind ARIA transitions. We explicitly ignore isolated item `<AccordionItem open={...}>` booleans to shield the rendering sequence cleanly.