@recursica/adapter-mantine-v8 1.3.4 → 1.3.5

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

@@ -1,5 +1,11 @@
 # @recursica/adapter-mantine-v8
 
+## 1.3.5
+
+### Patch Changes
+
+- 712f86a: Publish the component stories and `.storybook/commonArgTypes.ts` again. adapter-tester boots the source-of-truth Storybook from the published package's stories, so without them it only showed the storybook-template stories.
+
 ## 1.3.4
 
 ### Patch Changes

package/package.json

@@ -12,7 +12,7 @@
     "type": "git",
     "url": "git+https://github.com/borderux/recursica-adapter-mantine-v8.git"
   },
-  "version": "1.3.4",
+  "version": "1.3.5",
   "publishConfig": {
     "access": "public"
   },
@@ -31,7 +31,7 @@
   "files": [
     "dist",
     "src",
-    "!src/**/*.stories.tsx",
+    ".storybook/commonArgTypes.ts",
     "CHANGELOG.md",
     "llms.txt",
     "USAGE.md",

package/src/Introduction.stories.tsx

@@ -0,0 +1,149 @@
+import type { Meta } from "@storybook/react-vite";
+import { AdaptersContent, MantineLogo } from "@recursica/storybook-template";
+import { VersionInfo } from "./Version";
+import {
+  Container,
+  Stack,
+  Group,
+  Heading,
+  Text,
+  Link,
+  Button,
+} from "./components";
+
+const DOCS_URL = "https://recursica.com";
+const FORGE_URL = "https://forge.recursica.com";
+
+function IntroductionContent() {
+  return (
+    <Container size="md" style={{ padding: "32px 0", maxWidth: 640 }}>
+      <Group gap="rec-md" mb="rec-xl" align="flex-start" wrap="nowrap">
+        <MantineLogo width={80} height={80} />
+        <Stack gap={0}>
+          <Heading order={1} m={0}>
+            Recursica Design System (Mantine Adapter)
+          </Heading>
+          <Link href="https://mantine.dev" target="_blank" rel="noreferrer">
+            mantine.dev
+          </Link>
+        </Stack>
+      </Group>
+      <Text mb="rec-xl">
+        This Storybook showcases the Recursica design system implemented for the{" "}
+        <strong>Mantine UI Kit</strong>. It provides reusable components that
+        map our design tokens to Mantine's robust component layer.
+      </Text>
+
+      <Stack mb="rec-xl">
+        <Heading order={2} mb="rec-md">
+          Looking for another UI Kit?
+        </Heading>
+        <Text mb="rec-md">
+          Are you using a different UI Kit (like Material UI)? Recursica
+          provides multiple adapters for different frameworks.
+        </Text>
+        <Group mt="rec-md">
+          <Button
+            component="a"
+            href="./?path=/story/introduction--adapters"
+            target="_parent"
+            variant="solid"
+          >
+            View Supported Adapters
+          </Button>
+        </Group>
+      </Stack>
+
+      <Stack mb="rec-xl">
+        <Heading order={2} mb="rec-md">
+          Installation
+        </Heading>
+        <Text mb="rec-md">
+          To install the Mantine adapter in your project, run:
+        </Text>
+        <Stack
+          style={{
+            padding: 12,
+            backgroundColor: "#f5f5f5",
+            borderRadius: 6,
+            fontSize: 13,
+            marginTop: 8,
+          }}
+        >
+          <code>
+            npm install @recursica/adapter-mantine-v8 @mantine/core
+            @mantine/hooks
+          </code>
+        </Stack>
+      </Stack>
+
+      <Stack mb="rec-xl">
+        <Heading order={2} mb="rec-md">
+          Tokens
+        </Heading>
+        <Text mb="rec-md">
+          Raw design tokens (colors, sizes, font weights, opacities, etc.) that
+          feed the theme and components. These are the primitive values defined
+          in your token set and exposed as CSS custom properties.
+        </Text>
+      </Stack>
+
+      <Stack mb="rec-xl">
+        <Heading order={2} mb="rec-md">
+          Theme
+        </Heading>
+        <Text mb="rec-md">
+          Brand and theme layer built on top of tokens. Typography types,
+          dimensions, and layout grids are defined here. Theme uses the tokens
+          and exposes both CSS variables and helper classes (e.g. typography
+          classes) for consistent styling across the product.
+        </Text>
+      </Stack>
+
+      <Stack mb="rec-xl">
+        <Heading order={2} mb="rec-md">
+          Configuring Recursica
+        </Heading>
+        <Text mb="rec-md">
+          To modify the Recursica configuration (tokens, brand, theme), go to{" "}
+          <Link href={FORGE_URL} target="_blank" rel="noopener noreferrer">
+            {FORGE_URL}
+          </Link>
+          . Changes there drive the tokens and theme you see in this Storybook.
+        </Text>
+      </Stack>
+
+      <Stack mb="rec-xl">
+        <Heading order={2} mb="rec-md">
+          Documentation
+        </Heading>
+        <Text mb="rec-md">
+          For full documentation, guides, and API reference, visit{" "}
+          <Link href={DOCS_URL} target="_blank" rel="noopener noreferrer">
+            {DOCS_URL}
+          </Link>
+          .
+        </Text>
+      </Stack>
+    </Container>
+  );
+}
+
+const meta = {
+  title: "Introduction",
+} satisfies Meta;
+
+export default meta;
+
+export const Welcome = {
+  render: () => <IntroductionContent />,
+};
+
+export const Adapters = {
+  render: () => <AdaptersContent />,
+};
+
+export const VersionInfoStory = {
+  name: "Version Info",
+  render: () => <VersionInfo />,
+};

package/src/components/Accordion/Accordion.stories.tsx

@@ -0,0 +1,189 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Accordion } from "./Accordion";
+
+const SVGIcon = () => (
+  <svg
+    xmlns="http://www.w3.org/2000/svg"
+    width="24"
+    height="24"
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    strokeWidth="2"
+    strokeLinecap="round"
+    strokeLinejoin="round"
+  >
+    <path d="M12 2v20M17 5H9.5a3.5 3.5 0 0 0 0 7h5a3.5 3.5 0 0 1 0 7H6" />
+  </svg>
+);
+
+const ChevronIcon = () => (
+  <svg
+    width="24"
+    height="24"
+    viewBox="0 0 24 24"
+    fill="none"
+    xmlns="http://www.w3.org/2000/svg"
+  >
+    <path
+      d="M20.0306 9.53062L12.5306 17.0306C12.461 17.1003 12.3783 17.1557 12.2872 17.1934C12.1962 17.2312 12.0986 17.2506 12 17.2506C11.9014 17.2506 11.8038 17.2312 11.7128 17.1934C11.6218 17.1557 11.539 17.1003 11.4694 17.0306L3.96938 9.53062C3.82865 9.38988 3.74959 9.19901 3.74959 8.99999C3.74959 8.80097 3.82865 8.61009 3.96938 8.46936C4.11011 8.32863 4.30098 8.24957 4.50001 8.24957C4.69903 8.24957 4.8899 8.32863 5.03063 8.46936L12 15.4397L18.9694 8.46936C19.0391 8.39968 19.1218 8.34441 19.2128 8.30669C19.3039 8.26898 19.4015 8.24957 19.5 8.24957C19.5986 8.24957 19.6961 8.26898 19.7872 8.30669C19.8782 8.34441 19.9609 8.39968 20.0306 8.46936C20.1003 8.53905 20.1556 8.62177 20.1933 8.71282C20.231 8.80386 20.2504 8.90144 20.2504 8.99999C20.2504 9.09854 20.231 9.19612 20.1933 9.28716C20.1556 9.37821 20.1003 9.46093 20.0306 9.53062Z"
+      fill="currentColor"
+    />
+  </svg>
+);
+
+const meta: Meta<typeof Accordion> = {
+  title: "UI-Kit/Accordion",
+  component: Accordion,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+The \`Accordion\` component intelligently wraps \`@mantine/core\`'s underlying Accordion layers while applying strict native design system mapping via \`recursica_variables_scoped.css\`.
+
+### Hybrid Composition API (Smart-Rendering)
+To maximize flexibility while strictly aligning with the explicit Recursica design logic, the \`AccordionItem\` operates utilizing a **Hybrid Smart-Rendering Flow**:
+
+1. **Auto-Construction (Explicit Mapping)**:
+If you supply the explicitly outlined Recursica properties (\`title\`, \`leftIcon\`) directly onto \`<Accordion.Item>\`, the component auto-generates the necessary \`<Accordion.Control>\` DOM layer inherently bridging the icons and titles visually while leaving the raw \`children\` wrapped neatly as the \`<Accordion.Panel>\`.
+
+2. **Graceful Falldown (Raw Composability)**:
+If you deliberately omit the \`title\` property, the entire mapping system gracefully falls backward yielding exactly to the raw \`@mantine/core\` composition model. Under this context, you must inject your localized \`<Accordion.Control>\` and \`<Accordion.Panel>\` configurations completely manually.
+
+### Architecture Warning (\`open\`)
+To structurally protect the parent wrapper's core transitions tracking architecture (\`<Accordion value="...">\`), this configuration explicitly rejects mapping isolated \`open={true}\` object states natively on specific configurations. Use Mantine's inherent sibling arrays matching the corresponding active value map!
+        `,
+      },
+    },
+  },
+};
+
+export default meta;
+
+export const Default: StoryObj<typeof Accordion> = {
+  render: () => {
+    return (
+      <Accordion defaultValue="item-1" chevron={<ChevronIcon />}>
+        <Accordion.Item value="item-1">
+          <Accordion.Control>Billing and Membership</Accordion.Control>
+          <Accordion.Panel>
+            You can manage your billing directly from the dashboard tab. All
+            payments are processed automatically.
+          </Accordion.Panel>
+        </Accordion.Item>
+
+        <Accordion.Item value="item-2">
+          <Accordion.Control>Refund Policy</Accordion.Control>
+          <Accordion.Panel>
+            We offer a 30-day money-back guarantee for all new subscriptions.
+          </Accordion.Panel>
+        </Accordion.Item>
+
+        <Accordion.Item value="item-3">
+          <Accordion.Control>Technical Support</Accordion.Control>
+          <Accordion.Panel>
+            Our support team is available 24/7 via live chat or email.
+          </Accordion.Panel>
+        </Accordion.Item>
+      </Accordion>
+    );
+  },
+};
+
+export const WithIcons: StoryObj<typeof Accordion> = {
+  render: () => {
+    return (
+      <Accordion defaultValue="security" chevron={<ChevronIcon />}>
+        <Accordion.Item value="security">
+          <Accordion.Control leftIcon={<SVGIcon />}>
+            Security Settings
+          </Accordion.Control>
+          <Accordion.Panel>
+            Enable two-factor authentication (2FA) and monitor active sessions
+            below.
+          </Accordion.Panel>
+        </Accordion.Item>
+
+        <Accordion.Item value="privacy">
+          <Accordion.Control leftIcon={<SVGIcon />}>
+            Privacy Configuration
+          </Accordion.Control>
+          <Accordion.Panel>
+            Choose what data is shared with our analytics partners.
+          </Accordion.Panel>
+        </Accordion.Item>
+      </Accordion>
+    );
+  },
+};
+
+export const LongTitleTruncation: StoryObj<typeof Accordion> = {
+  render: () => {
+    return (
+      // `style` is stripped from Accordion itself (only passes through with overStyled);
+      // constrain width on a plain wrapper div instead to force truncation.
+      <div style={{ maxWidth: 320 }}>
+        <Accordion defaultValue="long-title" chevron={<ChevronIcon />}>
+          <Accordion.Item value="long-title">
+            <Accordion.Control leftIcon={<SVGIcon />}>
+              This is a deliberately very long accordion item title used to
+              verify that overflowing text truncates with a CSS ellipsis instead
+              of wrapping or overflowing the header
+            </Accordion.Control>
+            <Accordion.Panel>
+              The header label above should truncate to a single line with a
+              trailing ellipsis (…) rather than wrapping onto multiple lines or
+              pushing the chevron out of view.
+            </Accordion.Panel>
+          </Accordion.Item>
+
+          <Accordion.Item value="short-title">
+            <Accordion.Control leftIcon={<SVGIcon />}>
+              Short Title
+            </Accordion.Control>
+            <Accordion.Panel>
+              A short title in the same accordion for visual comparison.
+            </Accordion.Panel>
+          </Accordion.Item>
+        </Accordion>
+      </div>
+    );
+  },
+};
+
+export const Disabled: StoryObj<typeof Accordion> = {
+  render: () => {
+    return (
+      <Accordion defaultValue="expanded-disabled" chevron={<ChevronIcon />}>
+        <Accordion.Item value="expanded-disabled" disabled>
+          <Accordion.Control leftIcon={<SVGIcon />}>
+            Expanded and Disabled
+          </Accordion.Control>
+          <Accordion.Panel>
+            This item starts expanded so the panel content's dimming can be
+            verified alongside the control's, not just the collapsed header.
+          </Accordion.Panel>
+        </Accordion.Item>
+
+        <Accordion.Item value="collapsed-disabled" disabled>
+          <Accordion.Control leftIcon={<SVGIcon />}>
+            Collapsed and Disabled
+          </Accordion.Control>
+          <Accordion.Panel>
+            Clicking or tabbing to this control should have no effect.
+          </Accordion.Panel>
+        </Accordion.Item>
+
+        <Accordion.Item value="enabled">
+          <Accordion.Control leftIcon={<SVGIcon />}>
+            Enabled, for Comparison
+          </Accordion.Control>
+          <Accordion.Panel>
+            A normal, interactive item alongside the disabled ones above.
+          </Accordion.Panel>
+        </Accordion.Item>
+      </Accordion>
+    );
+  },
+};

package/src/components/AssistiveElement/AssistiveElement.stories.tsx

@@ -0,0 +1,68 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { AssistiveElement } from "./AssistiveElement";
+
+const meta: Meta<typeof AssistiveElement> = {
+  title: "UI-Kit/AssistiveElement",
+  component: AssistiveElement,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "The `AssistiveElement` is a semantic structural primitive designed to standardize Helper and Error descriptive blocks natively beneath form components globally. By explicitly wiring to the `--recursica_ui-kit_components_assistive-element` layout tokens, this component safely injects custom SVGs (Alerts vs Info circles) alongside constrained flex-wrapping typography strings, preserving flawless line-height and alignment logic entirely decoupled from underlying input engine frameworks.",
+      },
+    },
+  },
+  argTypes: {
+    assistiveVariant: {
+      control: "radio",
+      options: ["help", "error"],
+    },
+    assistiveWithIcon: {
+      control: "boolean",
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof AssistiveElement>;
+
+export const DefaultHelp: Story = {
+  args: {
+    children:
+      "This is a standard assistive layout explaining specific configurations.",
+    assistiveVariant: "help",
+    assistiveWithIcon: true,
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => (
+    <AssistiveElement {...args} />
+  ),
+};
+
+export const ErrorState: Story = {
+  args: {
+    children:
+      "Invalid property. You must satisfy the constraints outlined above.",
+    assistiveVariant: "error",
+    assistiveWithIcon: true,
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => (
+    <AssistiveElement {...args} />
+  ),
+};
+
+export const NoIconHelp: Story = {
+  args: {
+    children:
+      "Fallback textual representation without visual injection targets.",
+    assistiveVariant: "help",
+    assistiveWithIcon: false,
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => (
+    <AssistiveElement {...args} />
+  ),
+};