@recursica/mantine-adapter 0.9.4 → 0.11.0

package/.storybook/commonArgTypes.ts

@@ -0,0 +1,148 @@
+/**
+ * commonArgTypes.ts
+ *
+ * This file centralizes the standard Storybook Controls (ArgTypes) for all UI Kit
+ * components that natively wrap or extend the `FormControlWrapper`.
+ *
+ * PHILOSOPHY:
+ * Recursica ensures strict unified design boundaries across all form inputs (TextField,
+ * CheckboxGroup, Dropdown, etc.). Because they all share the exact same label structures,
+ * layout variants (stacked vs side-by-side), and assistive text bindings natively supplied
+ * by the `FormControlWrapper`, their Storybook experiences should be exactly identical.
+ *
+ * USAGE:
+ * Rather than recreating these controls inside every `Component.stories.tsx` file,
+ * developers must spread this object directly into the `argTypes` of their story default block:
+ *
+ * ```tsx
+ * import { formControlArgTypes } from "../../.storybook/commonArgTypes";
+ *
+ * export default {
+ *   component: TextField,
+ *   argTypes: {
+ *     ...formControlArgTypes,
+ *     // Component-specific argTypes below...
+ *   }
+ * }
+ * ```
+ */
+import type { ArgTypes } from "@storybook/react";
+
+export const formControlArgTypes: Partial<ArgTypes> = {
+  formLayout: {
+    control: "inline-radio",
+    options: ["stacked", "side-by-side"],
+    description:
+      "Determines the structural flow layout of the Label relative to the Input.",
+    table: {
+      category: "Form Layout",
+    },
+  },
+  labelSize: {
+    control: "inline-radio",
+    options: ["default", "small"],
+    description:
+      "Adjusts the typographical boundaries bounding the Label section.",
+    table: {
+      category: "Form Layout",
+    },
+  },
+  labelAlignment: {
+    control: "inline-radio",
+    options: ["left", "right"],
+    description:
+      "Adjusts the explicit text alignment axis exclusively evaluating side-by-side structures.",
+    table: {
+      category: "Form Layout",
+    },
+  },
+  labelOptionalText: {
+    control: "text",
+    description:
+      "Optional secondary stylistic text injected alongside the primary Label node.",
+    table: {
+      category: "Form Layout",
+    },
+  },
+  labelWithEditIcon: {
+    control: "boolean",
+    description:
+      "Dynamically toggles interactivity hooks revealing the Edit context icon.",
+    table: {
+      category: "Form Layout",
+    },
+  },
+  description: {
+    table: {
+      disable: true,
+    },
+  },
+  assistiveText: {
+    control: "text",
+    description:
+      "Helper instructions safely dynamically anchored below the input box natively outperforming description.",
+    table: {
+      category: "Form Layout",
+    },
+  },
+  assistiveWithIcon: {
+    control: "boolean",
+    description:
+      "Toggles native Recursica Info-styling rendering universally alongside the assistive block.",
+    table: {
+      category: "Form Layout",
+    },
+  },
+  error: {
+    control: "text",
+    description:
+      "Dynamically maps error feedback validation strings rendering explicit error states.",
+    table: {
+      category: "Form State",
+    },
+  },
+  required: {
+    control: "boolean",
+    description:
+      "Native DOM compliance flag explicitly marking the field as required natively.",
+    table: {
+      category: "Form State",
+    },
+  },
+  disabled: {
+    control: "boolean",
+    description:
+      "Globally disables interactive components bounding all click and focus logic natively.",
+    table: {
+      category: "Form State",
+    },
+  },
+  withAsterisk: {
+    control: "boolean",
+    description:
+      "Visually forces the mandatory asterisk presence completely independent of logical 'required' attribute properties.",
+    table: {
+      category: "Form State",
+    },
+  },
+  labelActionArea: {
+    table: {
+      disable: true,
+    },
+  },
+  onLabelEditClick: {
+    table: {
+      disable: true,
+    },
+  },
+  controlMaxWidth: {
+    table: {
+      disable: true,
+    },
+  },
+  controlMinWidth: {
+    table: {
+      disable: true,
+    },
+  },
+};

package/CHANGELOG.md

@@ -0,0 +1,94 @@
+# @recursica/mantine-adapter
+
+## 0.11.0
+
+### Minor Changes
+
+- 7898170: Updated read-only states for all components
+
+## 0.10.0
+
+### Minor Changes
+
+- 928f346: Added switch and radio
+- cb90751: Updated container and docs
+
+## 0.9.0
+
+### Minor Changes
+
+- 7d4af9c: Updated accordion
+
+## 0.8.0
+
+### Minor Changes
+
+- 6e6256b: Updated with latest components
+
+## 0.7.0
+
+### Minor Changes
+
+- bce74c3: Updated mantine storybook config
+- a4cf78b: Updates storybook controls and added chip
+
+## 0.6.0
+
+### Minor Changes
+
+- 9e31278: Added more mantine adapter components
+
+## 0.5.0
+
+### Minor Changes
+
+- a1067c9: Implemented stories in construction and over styling
+
+## 0.4.0
+
+### Minor Changes
+
+- eb5561b: Restructured and moved new adapter-common package
+- 6df88b7: Updated storybook layout and consolidated storybook release
+- eb5561b: Updated for latest CSS config and postcss processing
+
+## 0.3.0
+
+### Minor Changes
+
+- ea86688: Updated for latest CSS config and postcss processing
+
+## 0.2.0
+
+### Minor Changes
+
+- 5e0c31f: Fixed dependency so it will import correctly
+
+### Patch Changes
+
+- 5e0c31f: Updated link to readme in package.json
+
+## 0.1.0
+
+### Minor Changes
+
+- be88cfc: Updated README and structure and provided Storybook builds
+
+## 0.0.4
+
+### Patch Changes
+
+- cec0db5: Renamed ui-kit to mantine-adapter to signal proper peer reference to Mantine
+- cec0db5: Added peer dependency for mantine in the plugin
+
+## 0.0.3
+
+### Patch Changes
+
+- 9aab210: update docs
+
+## 0.0.2
+
+### Patch Changes
+
+- c6973c2: first publish

package/README.md

@@ -1,376 +1,92 @@
-# Recursica Mantine Adapter
+# @recursica/mantine-adapter
 
-A design token adapter that converts Figma design tokens exported via the Recursica Figma plugin into Mantine theme files, TypeScript types, and Vanilla Extract CSS-in-JS themes.
-
-## What is Recursica Mantine Adapter
-
-The Recursica Mantine Adapter processes design token JSON files and generates:
-
-- **Mantine Theme**: Complete Mantine theme configuration with colors, typography, spacing, and more
-- **Vanilla Extract Themes**: CSS-in-JS theme files with contract-based theme switching
-- **TypeScript Types**: Type-safe interfaces for colors, spacers, border radius, and other tokens
-- **React Components**: Ready-to-use Icon components with proper TypeScript definitions
-- **UI Kit Objects**: Structured objects containing all design system primitives
+A modern React component library built with TypeScript and **Mantine 8**. This package serves as the core UI kit for Recursica applications, providing reusable UI components, centralized theme configurations, and a comprehensive Storybook environment for development.
 
 ## Installation
 
 ```bash
 npm install @recursica/mantine-adapter
+# or
+yarn add @recursica/mantine-adapter
+# or
+pnpm add @recursica/mantine-adapter
 ```
 
-## Usage
-
-### Option 1: Using npx (Recommended)
-
-Run the adapter directly without installation:
-
-```bash
-npx @recursica/mantine-adapter
-```
-
-### Option 2: Adding a script to package.json
+## Peer Dependencies
 
-Add the recursica command to your package.json scripts:
-
-```json
-{
-  "scripts": {
-    "recursica": "recursica"
-  }
-}
-```
-
-Then run:
+This library requires the following peer dependencies to be installed in your project:
 
 ```bash
-npm run recursica
+npm install @mantine/core@>=8.0.0 @mantine/dates@>=8.0.0 @mantine/hooks@>=8.0.0 react@>=16.8.0 react-dom@>=16.8.0
 ```
 
-### Option 3: Programmatic Usage
+**Important**: Make sure you have these exact versions or higher installed, as the components rely on Mantine 8+ features and React 16.8+ hooks.
 
-```typescript
-import { runMain } from "@recursica/mantine-adapter";
+## Quick Start
 
-await runMain();
-```
-
-## Configuration
-
-Create a `recursica.json` file in your project root:
-
-```json
-{
-  "$schema": "node_modules/@recursica/schemas/RecursicaConfiguration.json",
-  "project": "YourProjectName",
-  "srcPath": "./src",
-  "bundledJson": "./design-tokens.json",
-  "iconsJson": "./icons.json",
-  "overrides": {
-    "mantineTheme": {
-      "1-scale": "rem",
-      "background": "white"
-    },
-    "fontWeight": [
-      {
-        "fontFamily": "Inter",
-        "value": 400,
-        "alias": "regular"
-      }
-    ]
-  },
-  "iconsConfig": {
-    "include": {
-      "variants": ["Filled", "Outlined"]
-    },
-    "exclude": {
-      "names": ["deprecated_icon"]
-    }
-  }
-}
-```
-
-### Configuration Options
-
-- `project`: Must match the project name in your exported JSON files
-- `srcPath`: Output directory for generated files (default: `./src`)
-- `bundledJson`: Path to your design tokens JSON file
-- `iconsJson`: Path to your icons JSON file (optional)
-- `overrides`: Custom overrides for theme generation
-- `iconsConfig`: Configuration for icon filtering and processing
-
-## Generated Files
-
-The adapter generates the following file structure in `{srcPath}/recursica/`:
-
-```
-src/
-└── recursica/
-    ├── Recursica.ts                           # Main theme object
-    ├── RecursicaTokens.ts                     # Base design tokens
-    ├── RecursicaContractTheme.css.ts          # Vanilla Extract contract
-    ├── RecursicaThemes.css.ts                 # Theme implementations
-    ├── RecursicaMantineTheme.ts               # Mantine theme config
-    ├── RecursicaColorsType.ts                 # Color type definitions
-    ├── RecursicaSpacersType.ts                # Spacing type definitions
-    ├── RecursicaBorderRadiusType.ts           # Border radius types
-    ├── RecursicaUiKit.ts                      # UI Kit components object
-    └── components/
-        └── Icons/
-            ├── Icon.tsx                       # Main Icon component
-            ├── icon_exports.ts                # React icon components
-            ├── icon_resource_map.ts           # Icon name mappings
-            └── Svg/                           # SVG icon files
-                ├── icon1.svg
-                └── icon2.svg
-```
-
-## Icon Component Usage
-
-The generated Icon component provides type-safe icon usage:
+To use `@recursica/mantine-adapter` in your project, you **must** import its required CSS files in a specific order at the root of your application (e.g., in `App.tsx` or `main.tsx`). This ensures that Mantine styles load first, followed by the Recursica design tokens, and finally the adapter overrides.
 
 ```tsx
-import { Icon } from './recursica/components/Icons/Icon';
-import type { RecursicaColors } from './recursica/RecursicaColorsType';
-
-// Basic usage
-<Icon name="check_Filled" />
-
-// With custom size and color
-<Icon
-  name="arrow_back_ios_new_Outlined"
-  size={32}
-  color="primary-500"
-/>
-
-// Available props
-interface IconProps {
-  name: IconName;                              // Autocompleted icon names
-  size?: 16 | 20 | 24 | 32 | 40 | 48 | "100%"; // Predefined sizes
-  title?: string;                              // Accessibility title
-  color?: RecursicaColors;                     // Theme colors
-}
-```
-
-## Using with Webworker
-
-For browser-based token processing, use the webworker implementation:
-
-### 1. Setup the Worker
-
-```typescript
-// worker.ts
-import "@recursica/mantine-adapter/dist/webworker.js";
-```
-
-### 2. Process Tokens in Main Thread
-
-```typescript
-// main.ts
-interface WorkerMessage {
-  bundledJson: string; // JSON content as string
-  iconsJson?: string; // Icons JSON content as string
-  project: string; // Project name
-  srcPath: string; // Output path
-  rootPath: string; // Root project path
-  overrides?: any; // Theme overrides
-  iconsConfig?: any; // Icons configuration
-}
-
-// Create and use worker
-const worker = new Worker("./worker.js");
-
-worker.postMessage({
-  bundledJson: jsonFileContent,
-  iconsJson: iconsJsonContent,
-  project: "YourProject",
-  srcPath: "./src",
-  rootPath: "./",
-  overrides: undefined,
-  iconsConfig: undefined,
-});
-
-worker.onmessage = (event) => {
-  const files = event.data;
-  // Process generated files
-  console.log("Generated files:", files);
-
-  // Files structure matches the CLI output:
-  // - files.recursicaTokens
-  // - files.vanillaExtractThemes
-  // - files.mantineTheme
-  // - files.uiKitObject
-  // - files.recursicaObject
-  // - files.colorsType
-  // - files.iconsObject
-  // etc.
-};
-```
-
-### 3. Handle Worker Response
-
-```typescript
-interface WorkerResponse {
-  recursicaTokens: ExportingResult;
-  vanillaExtractThemes: VanillaExtractThemesOutput;
-  mantineTheme: GenerateMantineThemeOutput;
-  uiKitObject: ExportingResult;
-  recursicaObject: ExportingResult;
-  colorsType: ExportingResult;
-  spacersType: ExportingResult;
-  borderRadiusType: ExportingResult;
-  iconsObject?: GenerateIconsOutput;
-  recursicaThemes: ExportingResult;
-  prettierignore: ExportingResult;
-}
-
-interface ExportingResult {
-  content: string; // File content
-  path: string; // Full file path
-  filename: string; // Filename only
-}
-```
-
-## Creating Custom Adapters
-
-To create your own adapter, you need to implement the core generator functions. The adapter architecture is modular and extensible.
+import "@mantine/core/styles.css";
+import "../path/to/recursica_variables_scoped.css"; // Import your Recursica CSS variables
+import "@recursica/mantine-adapter/style.css";
 
-### 1. Adapter Structure
-
-```typescript
-// your-adapter/index.ts
-import type {
-  RecursicaConfigOverrides,
-  RecursicaConfigIcons,
-  ExportingResult,
-} from "@recursica/mantine-adapter";
-
-interface CustomAdapterParams {
-  overrides: RecursicaConfigOverrides | undefined;
-  rootPath: string;
-  srcPath: string;
-  project: string;
-  icons: Record<string, string>;
-  iconsConfig: RecursicaConfigIcons | undefined;
-  processTokens: ProcessTokens;
-}
+import React from "react";
+import { Button } from "@recursica/mantine-adapter";
 
-export function runCustomAdapter(params: CustomAdapterParams) {
-  // Your custom generation logic here
-  return {
-    // Return ExportingResult objects for each file you want to generate
-    customTheme: generateCustomTheme(params),
-    customTypes: generateCustomTypes(params),
-    // ... other generators
-  };
+function App() {
+  return <Button variant="solid">Click Me</Button>;
 }
 ```
 
-### 2. Individual Generators
+## Philosophy
 
-Each generator should follow this pattern:
+The `@recursica/mantine-adapter` is designed to provide curated, strictly-typed UI components tailored specifically following the Recursica styling and behavior guidelines.
 
-```typescript
-// generateCustomTheme.ts
-import type {
-  ExportingResult,
-  ExportingProps,
-} from "@recursica/mantine-adapter";
+- **Override, Don't Corrupt**: Recursica components are built as wrappers around Mantine components to seamlessly override their default appearance with Recursica stylings. We deliberately **leave the base Mantine global styles and theme alone** so that it does not negatively impact the overall project or third-party libraries depending on standard Mantine.
+- **Strictly Curated Props**: We expose a complete set of Mantine props via our Recursica components, but **not all props are fully supported**. We restrict certain props if they do not fit the established UI definition, styles, or behaviors of the Recursica design system.
+- **Avoid Overstyling**: Developers are encouraged to use Recursica components precisely as they are provided. You should **not overstyle them** (e.g., injecting custom styles or class names that conflict with the adapter) as this risks breaking the carefully constructed styling connections and visual consistency.
+- **Need Something Different?**: If you need to build a UI element with completely different styling that deviates from the design system, you are encouraged to import the base component directly from `@mantine/core` and style it yourself to achieve your goal.
 
-export function generateCustomTheme(
-  tokens: Record<string, any>,
-  exportingProps: ExportingProps,
-): ExportingResult {
-  const { outputPath, project } = exportingProps;
+## Development and Architecture
 
-  const filename = `${project}CustomTheme.ts`;
-  const path = `${outputPath}/${filename}`;
+This project is built using:
 
-  const content = `
-// Auto-generated custom theme
-export const customTheme = ${JSON.stringify(tokens, null, 2)};
-  `.trim();
+- **Vite (Library Mode)**: For fast builds, producing optimized ES and CJS modules.
+- **Mantine 8**: Base components, hooks, and native standard styling architecture.
+- **Storybook**: Used heavily for interactive component development, documentation, and prototyping.
 
-  return {
-    content,
-    path,
-    filename,
-  };
-}
-```
-
-### 3. Available Generator Templates
+> **Note:** We relying completely on Mantine's built-in CSS styling and Vite's native CSS/CSS Modules capabilities. No complex CSS-in-JS overhead!
 
-The mantine-adapter provides several generator templates you can extend:
+## Storybook Documentation
 
-- `generateRecursicaTokens`: Base token generation
-- `generateVanillaExtractThemes`: CSS-in-JS theme generation
-- `generateMantineTheme`: Mantine-specific theme generation
-- `generateColorTypes`: TypeScript color type generation
-- `generateIcons`: React icon component generation
-- `generateUiKit`: UI component object generation
+This library includes Storybook for all components. You can:
 
-### 4. Token Processing
+- **View live examples** of components.
+- **Test component interactions** and accessibility.
+- **Explore UI tokens** and layout utilities.
 
-Use the `ProcessTokens` class to handle token transformation:
+### Accessing Storybook Locally
 
-```typescript
-import { ProcessTokens } from "@recursica/mantine-adapter";
+If you're contributing or developing locally, clone the repository and run:
 
-const processTokens = new ProcessTokens(overrides);
-processTokens.processTokens(jsonContent.tokens);
-
-// Access processed tokens
-const colors = processTokens.colors;
-const spacers = processTokens.spacers;
-const typography = processTokens.typography;
-const themes = processTokens.themes;
+```bash
+npm run storybook
 ```
 
-### 5. Integration
-
-Replace the default adapter by modifying the `runAdapter` function or create a separate CLI that uses your custom adapter:
-
-```typescript
-// custom-cli.ts
-import { processJsonContent, processIcons } from "@recursica/mantine-adapter";
-import { runCustomAdapter } from "./your-adapter";
-
-// Use the same processing logic but with your custom adapter
-const processTokens = processJsonContent(bundledJsonContent, {
-  project,
-  overrides,
-});
-const icons = processIcons(iconsJsonContent);
-
-const files = runCustomAdapter({
-  rootPath,
-  overrides,
-  srcPath,
-  icons,
-  processTokens,
-  project,
-  iconsConfig,
-});
-```
+This will spin up a local server (typically at `http://localhost:6006`) with a hot-reloading environment for component prototyping.
 
-## API Reference
+## TypeScript Support
 
-### Core Functions
+All newly built components will include full TypeScript support with comprehensive prop types exported.
 
-- `runMain()`: Main CLI execution function
-- `processJsonContent()`: Process design token JSON
-- `processIcons()`: Process icons JSON
-- `processAdapter()`: Core adapter processing logic
-- `runAdapter()`: Execute the Mantine adapter
+## Developer & AI Guidelines
 
-### Types
+This repository provides dedicated routing documents for both human developers and AI Agents to ensure strict adherence to our design system constraints.
 
-- `ExportingResult`: File output interface
-- `RecursicaConfigOverrides`: Theme override configuration
-- `RecursicaConfigIcons`: Icon processing configuration
-- `ThemeTokens`: Theme token structure
-- `Themes`: Multi-theme structure
+- **For Human Developers:** This `README.md` acts as your primary routing document. If you are integrating this library into an application, please read [USAGE.md](./USAGE.md). If you are building or modifying components inside this library, please read [CONTRIBUTING.md](./CONTRIBUTING.md).
+- **For AI Agents:** All AI Agents operating in this repository must start by reading [AGENT.md](./AGENT.md), which serves as the primary routing document for AI workflows.
 
 ## License
 
-MIT
+This project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.

package/dist/index.d.ts

@@ -1,8 +1,2 @@
-export { runAdapter } from "./adapter";
-export type { Themes, ThemeTokens, RecursicaConfigOverrides, RecursicaConfigIcons, ExportingResult, JsonContentIcons, } from "./types";
-export { loadConfig } from "./utils/loadConfig";
-export { isFontFamilyToken, isEffectToken, isColorOrFloatToken, capitalize, } from "@recursica/common";
-export { ProcessTokens } from "./shared/processTokens";
-export { processJsonContent } from "./shared/common";
-export { runMain } from "./cli";
-//# sourceMappingURL=index.d.ts.map
+export * from './src/index'
+export {}