@recursica/mantine-adapter 0.9.4 → 0.11.0

package/src/components/Switch/SwitchGroup.stories.tsx

@@ -0,0 +1,132 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Switch } from "./Switch";
+import { SwitchGroup } from "./SwitchGroup";
+import { useState } from "react";
+import { formControlArgTypes } from "../../../.storybook/commonArgTypes";
+
+const meta: Meta<typeof SwitchGroup> = {
+  title: "UI-Kit/SwitchGroup",
+  component: SwitchGroup,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+The \`SwitchGroup\` component is the mandatory organizational wrapper for orchestrating \`Switch\` primitives into macro form layouts. It inherently leverages the \`FormControlWrapper\`, granting native access to structural alignments, assistive descriptions, and strict flex arrays.
+
+### Supported Layout Vectors
+- **\`formLayout="stacked"\`**: Top-to-bottom layout cascading the Label bounding box down vertically into a standard stacked switch array.
+- **\`formLayout="side-by-side"\`**: Flow architecture pulling the grouping Label dynamically to the left while structurally organizing the internal switches cleanly alongside it horizontally.
+
+> [!IMPORTANT]  
+> If you require a solitary \`Switch\` field to natively accept an overarching form label, assistive text, or align with other side-by-side components in a form column, you must wrap it inside a \`Switch.Group\` to trigger the \`FormControlWrapper\` mapping.
+`,
+      },
+    },
+  },
+  argTypes: {
+    ...formControlArgTypes,
+    readOnly: {
+      control: "boolean",
+      description:
+        "Passes read-only lock natively down mapping inner switches into explicitly disabled states.",
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof SwitchGroup>;
+
+export const Default: Story = {
+  args: {
+    formLayout: "stacked",
+    label: "Standard Group",
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: function StoryRender({ withLayer, layer, ...args }: any) {
+    const [value, setValue] = useState<string[]>([]);
+    return (
+      <SwitchGroup {...args} value={value} onChange={setValue}>
+        <Switch value="1" label="Option 1" />
+        <Switch value="2" label="Option 2" />
+      </SwitchGroup>
+    );
+  },
+};
+
+export const StackedLayout: Story = {
+  args: {
+    formLayout: "stacked",
+    label: "Notification Settings",
+    description: "Manage your preferences.",
+    assistiveText: "We recommend turning these on.",
+    error: "",
+    required: true,
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: function StoryRender({ withLayer, layer, ...args }: any) {
+    const [value, setValue] = useState<string[]>(["email"]);
+    return (
+      <SwitchGroup {...args} value={value} onChange={setValue}>
+        <Switch value="email" label="Email Alerts" />
+        <Switch value="push" label="Push Notifications" />
+        <Switch value="sms" label="SMS Messages" />
+      </SwitchGroup>
+    );
+  },
+};
+
+export const SideBySideLayout: Story = {
+  args: {
+    ...StackedLayout.args,
+    formLayout: "side-by-side",
+    labelSize: "default",
+    labelAlignment: "left",
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: function StoryRender({ withLayer, layer, ...args }: any) {
+    const [value, setValue] = useState<string[]>([]);
+    return (
+      <SwitchGroup {...args} value={value} onChange={setValue}>
+        <Switch value="weekly" label="Weekly Digest" />
+        <Switch value="marketing" label="Marketing Emails" />
+      </SwitchGroup>
+    );
+  },
+};
+
+export const SolitaryFormControl: Story = {
+  args: {
+    formLayout: "side-by-side",
+    label: "Enable Backups",
+    description: "Automatically back up your data nightly.",
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: function StoryRender({ withLayer, layer, ...args }: any) {
+    const [value, setValue] = useState<string[]>(["auto"]);
+    return (
+      <SwitchGroup {...args} value={value} onChange={setValue}>
+        <Switch value="auto" label="Auto-backup" />
+      </SwitchGroup>
+    );
+  },
+};
+
+export const ReadOnly: Story = {
+  args: {
+    ...StackedLayout.args,
+    readOnly: true,
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: function StoryRender({ withLayer, layer, ...args }: any) {
+    const [value, setValue] = useState<string[]>(["email", "sms"]);
+    return (
+      <SwitchGroup {...args} value={value} onChange={setValue}>
+        <Switch value="email" label="Email Alerts" />
+        <Switch value="push" label="Push Notifications" />
+        <Switch value="sms" label="SMS Messages" />
+      </SwitchGroup>
+    );
+  },
+};

package/src/components/Switch/SwitchGroup.tsx

@@ -0,0 +1,118 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import React, { forwardRef } from "react";
+import {
+  Switch as MantineSwitch,
+  type SwitchGroupProps as MantineSwitchGroupProps,
+} 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 styles from "./Switch.module.css";
+
+export interface RecursicaSwitchGroupProps
+  extends Omit<MantineSwitchGroupProps, "size" | "labelProps">,
+    Omit<
+      RecursicaFormControlWrapperProps,
+      "controlMaxWidth" | "controlMinWidth"
+    >,
+    ReadOnlyControlProps {}
+
+export type SwitchGroupProps = RecursicaOverStyled<RecursicaSwitchGroupProps>;
+
+export const SwitchGroup = forwardRef<HTMLDivElement, SwitchGroupProps>(
+  function SwitchGroup(props, ref) {
+    const {
+      overStyled = false,
+      formLayout = "stacked",
+
+      // Label Wrappers
+      labelSize,
+      labelAlignment,
+      labelOptionalText,
+      labelWithEditIcon,
+      onLabelEditClick,
+
+      // Base Mantine Extracted Attributes
+      label,
+      description,
+      assistiveText,
+      assistiveWithIcon,
+      error,
+      required,
+      withAsterisk,
+      id,
+      className,
+      style,
+      children,
+      readOnly,
+      readOnlyComponent,
+      emptyValueComponent,
+      value,
+      defaultValue,
+      ...rest
+    } = props;
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+    const restRecord = sanitizedProps as Record<string, unknown>;
+
+    // Delete prohibited sizing hooks from bypassing the variables
+    delete restRecord["size"];
+
+    return (
+      <WithReadOnlyWrapper
+        className={className}
+        style={style as React.CSSProperties}
+        controlMaxWidth="var(--recursica_ui-kit_components_switch_properties_max-width)"
+        controlMinWidth={undefined}
+        overStyled={overStyled as true}
+        labelElement="div" // Strictly override. ARIA grouping prohibits interactive switches nested natively inside <label>.
+        formLayout={formLayout}
+        labelSize={labelSize}
+        labelAlignment={labelAlignment}
+        labelOptionalText={labelOptionalText}
+        labelWithEditIcon={labelWithEditIcon}
+        onLabelEditClick={onLabelEditClick}
+        label={label}
+        description={description}
+        assistiveText={assistiveText}
+        assistiveWithIcon={assistiveWithIcon}
+        error={error}
+        required={required}
+        withAsterisk={withAsterisk}
+        id={id}
+        readOnly={readOnly && !!readOnlyComponent}
+        readOnlyComponent={readOnlyComponent}
+        emptyValueComponent={emptyValueComponent}
+        readOnlyType="text"
+        readOnlyValue={value !== undefined ? value : defaultValue}
+        readOnlyNativeProps={props}
+        activeComponent={
+          <MantineSwitch.Group
+            ref={ref}
+            /* Natively bind local disabled lock dynamically */
+            {...(sanitizedProps as unknown as MantineSwitchGroupProps)}
+            disabled={readOnly || (restRecord as any).disabled}
+            value={value}
+            defaultValue={defaultValue}
+          >
+            <div className={styles.groupRoot}>
+              {React.Children.map(children, (child) => {
+                if (React.isValidElement(child)) {
+                  return React.cloneElement(child as React.ReactElement<any>, {
+                    disabled: readOnly || (child.props as any).disabled,
+                  });
+                }
+                return child;
+              })}
+            </div>
+          </MantineSwitch.Group>
+        }
+      />
+    );
+  },
+);
+
+SwitchGroup.displayName = "SwitchGroup";

package/src/components/Table/Table.stories.tsx

@@ -0,0 +1,17 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Table } from "./Table";
+import { ComingSoon } from "@recursica/storybook-template";
+
+const meta: Meta<typeof Table> = {
+  title: "UI-Kit/🚧 Table",
+  component: Table,
+  tags: ["autodocs"],
+};
+
+export default meta;
+
+type Story = StoryObj<typeof Table>;
+
+export const Default: Story = {
+  render: () => <ComingSoon componentName="Table" />,
+};

package/src/components/Table/Table.tsx

@@ -0,0 +1,7 @@
+import React from "react";
+
+export type TableProps = React.HTMLAttributes<HTMLDivElement>;
+
+export const Table: React.FC<TableProps> = (props) => {
+  return <div {...props}>Table</div>;
+};

package/src/components/Tabs/Tabs.stories.tsx

@@ -0,0 +1,17 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Tabs } from "./Tabs";
+import { ComingSoon } from "@recursica/storybook-template";
+
+const meta: Meta<typeof Tabs> = {
+  title: "UI-Kit/🚧 Tabs",
+  component: Tabs,
+  tags: ["autodocs"],
+};
+
+export default meta;
+
+type Story = StoryObj<typeof Tabs>;
+
+export const Default: Story = {
+  render: () => <ComingSoon componentName="Tabs" />,
+};

package/src/components/Tabs/Tabs.tsx

@@ -0,0 +1,7 @@
+import React from "react";
+
+export type TabsProps = React.HTMLAttributes<HTMLDivElement>;
+
+export const Tabs: React.FC<TabsProps> = (props) => {
+  return <div {...props}>Tabs</div>;
+};

package/src/components/Text/Text.stories.tsx

@@ -0,0 +1,88 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Text } from "./Text";
+import { Layer } from "@recursica/adapter-common";
+
+const meta: Meta<typeof Text> = {
+  title: "UI-Kit/Text",
+  component: Text,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "The standard `<Text>` component controls common body sizing scales and implicit paragraphs governed by the active theme layer. For semantic headings (`h1` through `h6`), use `<Title>` instead.",
+      },
+    },
+  },
+  argTypes: {
+    variant: {
+      control: "select",
+      options: [
+        "body",
+        "body-small",
+        "caption",
+        "overline",
+        "subtitle",
+        "subtitle-small",
+      ],
+      description:
+        "Controls the standard logical boundary definitions natively extracted from Figma.",
+    },
+    c: {
+      control: "text",
+      description:
+        "Standard Mantine color string mapped via internal boundaries. Example: `dimmed`",
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof Text>;
+
+export const Default: Story = {
+  args: {
+    variant: "body",
+    children:
+      "This is standard body typography controlled by the central UI-kit boundaries exclusively.",
+  },
+  render: ({ ...args }) => (
+    <Layer layer={0} style={{ padding: "48px" }}>
+      <Text {...args} />
+    </Layer>
+  ),
+};
+
+export const StaticVariations: Story = {
+  args: {},
+  render: () => (
+    <Layer
+      layer={0}
+      style={{
+        padding: "48px",
+        display: "flex",
+        flexDirection: "column",
+        gap: "16px",
+      }}
+    >
+      <Text variant="body">
+        Body (Base paragraph and generic information flow)
+      </Text>
+      <Text variant="body-small">
+        Body Small (Compacted list items and helper blocks)
+      </Text>
+      <Text variant="caption">
+        Caption (Data table descriptions or micro-labels)
+      </Text>
+      <Text variant="overline">
+        Overline (Card contextual pre-headers and categorical tags)
+      </Text>
+      <Text variant="subtitle">
+        Subtitle (Minor sub-headers avoiding heavy display weights)
+      </Text>
+      <Text variant="subtitle-small">
+        Subtitle Small (Section anchors deep in hierarchy)
+      </Text>
+    </Layer>
+  ),
+};

package/src/components/Text/Text.tsx

@@ -0,0 +1,54 @@
+import { forwardRef, type ReactNode } from "react";
+import {
+  Text as MantineText,
+  type TextProps as MantineTextProps,
+} from "@mantine/core";
+import {
+  filterStylingProps,
+  type 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 const Text = forwardRef<HTMLDivElement, TextProps>(function Text(
+  { overStyled = false, variant = "body", ...rest },
+  ref,
+) {
+  const sanitizedProps = filterStylingProps(rest, overStyled);
+  const classNameProp = (sanitizedProps as Record<string, unknown>)
+    .className as string | undefined;
+
+  const typographyClass = `recursica_brand_typography_${variant}`;
+  const mergedClassName = classNameProp
+    ? `${typographyClass} ${classNameProp}`
+    : typographyClass;
+
+  return (
+    <MantineText
+      ref={ref}
+      className={mergedClassName}
+      {...(sanitizedProps as unknown as MantineTextProps)}
+    />
+  );
+});
+Text.displayName = "Text";

package/src/components/TextArea/TEXTAREA_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,7 @@
+# TextArea Implementation Notes
+
+The `TextArea` component is mapped explicitly to Mantine's `<Textarea>` following the same strict encapsulation rules as `TextField`.
+
+1. **Naked Primitive Mapping:** Mantine's `Textarea` natively executes macro-label generation. To decouple it, we explicitly disable internal labels (`label={undefined}`) and inject it purely inside our generic `FormControlWrapper`.
+2. **Text Field Token Re-Use:** Because text areas fundamentally share the same box-geometry, text, and state definitions as single-line inputs, it strictly implements the `--recursica_ui-kit_components_text-field_...` variables natively.
+3. **Autosize Handling:** The component supports Mantine's raw `autosize`, `minRows`, and `maxRows` parameters out of the box dynamically via property passthrough.

package/src/components/TextArea/TextArea.module.css

@@ -0,0 +1,225 @@
+/* HARDCODED VALUES:
+   - border-width: 1px. Native geometric boundary for the input box.
+   - border-style: solid. Native structural rendering rule.
+   - outline: none. Bypassing browser focus rings to rely strictly on Recursica focus states natively.
+   - flex/layout: display: flex on the root wrapper safely encapsulating internal section rendering.
+*/
+
+.root {
+  display: flex;
+  position: relative;
+  width: 100%;
+  min-height: var(
+    --recursica_ui-kit_components_text-field_properties_min-height
+  );
+
+  /* Override Mantine native Input variables governing section spacing padding mathematics safely */
+  --input-left-section-size: calc(
+    var(--recursica_ui-kit_components_text-field_properties_icon-size) +
+      (
+        var(
+            --recursica_ui-kit_components_text-field_properties_horizontal-padding
+          ) *
+          2
+      )
+  );
+  --input-right-section-size: calc(
+    var(--recursica_ui-kit_components_text-field_properties_icon-size) +
+      (
+        var(
+            --recursica_ui-kit_components_text-field_properties_horizontal-padding
+          ) *
+          2
+      )
+  );
+}
+
+.input {
+  /* Structural Overrides */
+  width: 100%;
+  box-sizing: border-box;
+  margin: 0;
+
+  /* Box Geometry */
+  min-height: var(
+    --recursica_ui-kit_components_text-field_properties_min-height
+  );
+  padding-top: var(
+    --recursica_ui-kit_components_text-field_properties_vertical-padding
+  );
+  padding-bottom: var(
+    --recursica_ui-kit_components_text-field_properties_vertical-padding
+  );
+  padding-left: var(
+    --recursica_ui-kit_components_text-field_properties_horizontal-padding
+  );
+  padding-right: var(
+    --recursica_ui-kit_components_text-field_properties_horizontal-padding
+  );
+  border-radius: var(
+    --recursica_ui-kit_components_text-field_properties_border-radius
+  );
+  border-width: 1px;
+  border-style: solid;
+
+  /* Strict Typography Unification */
+  font-family: var(
+    --recursica_ui-kit_components_text-field_properties_text_font-family
+  );
+  font-size: var(
+    --recursica_ui-kit_components_text-field_properties_text_font-size
+  );
+  font-style: var(
+    --recursica_ui-kit_components_text-field_properties_text_font-style
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_text-field_properties_text_font-weight
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_text-field_properties_text_letter-spacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_text-field_properties_text_line-height
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_text-field_properties_text_text-decoration
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_text-field_properties_text_text-transform
+  );
+
+  /* Base State Default Execution */
+  background-color: var(
+    --recursica_ui-kit_components_text-field_variants_states_default_properties_colors_background
+  );
+  border-color: var(
+    --recursica_ui-kit_components_text-field_variants_states_default_properties_colors_border-color
+  );
+  color: var(
+    --recursica_ui-kit_components_text-field_variants_states_default_properties_colors_text
+  );
+
+  outline: none;
+  transition:
+    border-color 0.15s ease,
+    background-color 0.15s ease;
+}
+
+.input::placeholder {
+  opacity: var(
+    --recursica_ui-kit_components_text-field_properties_placeholder-opacity
+  );
+  color: inherit;
+}
+
+/* Dynamic Padding Overrides */
+.root[data-with-left-section] .input {
+  padding-left: var(--input-left-section-size);
+}
+
+.root[data-with-right-section] .input {
+  padding-right: var(--input-right-section-size);
+}
+
+/* Flexible End-Caps (Icons, actions) */
+.section {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  height: 100%;
+}
+
+.section :global(svg) {
+  width: var(--recursica_ui-kit_components_text-field_properties_icon-size);
+  height: var(--recursica_ui-kit_components_text-field_properties_icon-size);
+  color: var(
+    --recursica_ui-kit_components_text-field_variants_states_default_properties_colors_leading-icon
+  );
+}
+
+.section[data-position="right"] :global(svg) {
+  color: var(
+    --recursica_ui-kit_components_text-field_variants_states_default_properties_colors_trailing-icon
+  );
+}
+
+/* -------------------------------------
+   STATE CASCADE ARCHITECTURE
+-------------------------------------- */
+
+/* Focus State Mapping (Triggered internally via browser pseudo-pseudo-class) */
+.input:focus-within,
+.input:focus {
+  border-color: var(
+    --recursica_ui-kit_components_text-field_variants_states_focus_properties_colors_border-color
+  );
+  background-color: var(
+    --recursica_ui-kit_components_text-field_variants_states_focus_properties_colors_background
+  );
+  color: var(
+    --recursica_ui-kit_components_text-field_variants_states_focus_properties_colors_text
+  );
+}
+
+.root:focus-within .section[data-position="left"] :global(svg) {
+  color: var(
+    --recursica_ui-kit_components_text-field_variants_states_focus_properties_colors_leading-icon
+  );
+}
+
+.root:focus-within .section[data-position="right"] :global(svg) {
+  color: var(
+    --recursica_ui-kit_components_text-field_variants_states_focus_properties_colors_trailing-icon
+  );
+}
+
+/* Error State Mapping (Propagated strictly down from the wrapper DOM context) */
+.root[data-error] .input {
+  border-color: var(
+    --recursica_ui-kit_components_text-field_variants_states_error_properties_colors_border-color
+  ) !important;
+  background-color: var(
+    --recursica_ui-kit_components_text-field_variants_states_error_properties_colors_background
+  ) !important;
+  color: var(
+    --recursica_ui-kit_components_text-field_variants_states_error_properties_colors_text
+  ) !important;
+}
+
+.root[data-error] .section[data-position="left"] :global(svg) {
+  color: var(
+    --recursica_ui-kit_components_text-field_variants_states_error_properties_colors_leading-icon
+  ) !important;
+}
+
+.root[data-error] .section[data-position="right"] :global(svg) {
+  color: var(
+    --recursica_ui-kit_components_text-field_variants_states_error_properties_colors_trailing-icon
+  ) !important;
+}
+
+/* Disabled State Mapping (Propagated strictly down from the wrapper DOM context) */
+.root[data-disabled] .input {
+  border-color: var(
+    --recursica_ui-kit_components_text-field_variants_states_disabled_properties_colors_border-color
+  ) !important;
+  background-color: var(
+    --recursica_ui-kit_components_text-field_variants_states_disabled_properties_colors_background
+  ) !important;
+  color: var(
+    --recursica_ui-kit_components_text-field_variants_states_disabled_properties_colors_text
+  ) !important;
+  cursor: not-allowed;
+}
+
+.root[data-disabled] .section[data-position="left"] :global(svg) {
+  color: var(
+    --recursica_ui-kit_components_text-field_variants_states_disabled_properties_colors_leading-icon
+  ) !important;
+}
+
+.root[data-disabled] .section[data-position="right"] :global(svg) {
+  color: var(
+    --recursica_ui-kit_components_text-field_variants_states_disabled_properties_colors_trailing-icon
+  ) !important;
+}