@recursica/mantine-adapter 0.7.0 → 0.8.0

package/src/components/Dropdown/Dropdown.stories.tsx

@@ -1,22 +1,94 @@
+import React from "react";
 import type { Meta, StoryObj } from "@storybook/react";
 import { Dropdown } from "./Dropdown";
-import { ComingSoon } from "@recursica/storybook-template";
+import { formControlArgTypes } from "../../../.storybook/commonArgTypes";
 
-const meta: Meta<typeof Dropdown> = {
-  title: "UI-Kit/🚧 Dropdown",
+type DropdownStoryProps = React.ComponentProps<typeof Dropdown>;
+
+const meta: Meta<DropdownStoryProps> = {
+  title: "UI-Kit/Dropdown",
   component: Dropdown,
   tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Dropdown provides a selectable list of options, mapping natively over Mantine's Select component encapsulated within the standardized FormControlWrapper.",
+      },
+    },
+  },
+  args: {
+    label: "Country Selection",
+    assistiveText: "Select your country of origin.",
+    placeholder: "Pick value",
+    data: ["United States", "Canada", "Mexico", "United Kingdom", "France"],
+    disabled: false,
+    required: false,
+    readOnly: false,
+    searchable: false,
+    clearable: false,
+  },
   argTypes: {
+    ...formControlArgTypes,
     disabled: {
       control: "boolean",
     },
+    readOnly: {
+      control: "boolean",
+    },
+    searchable: {
+      control: "boolean",
+    },
+    clearable: {
+      control: "boolean",
+    },
+    checked: {
+      table: { disable: true },
+    },
+    defaultChecked: {
+      table: { disable: true },
+    },
+    containerWidth: {
+      table: { disable: true },
+    },
   },
 };
 
 export default meta;
 
-type Story = StoryObj<typeof Dropdown>;
+type Story = StoryObj<DropdownStoryProps>;
 
 export const Default: Story = {
-  render: () => <ComingSoon componentName="Dropdown" />,
+  args: {},
+};
+
+export const SearchableClearable: Story = {
+  args: {
+    label: "Search & Clear Options",
+    searchable: true,
+    clearable: true,
+    placeholder: "Start typing...",
+  },
+};
+
+export const StaticError: Story = {
+  args: {
+    error: "You must choose a valid destination.",
+    value: "Invalid Island",
+  },
+};
+
+export const StaticDisabled: Story = {
+  args: {
+    disabled: true,
+    value: "United States",
+  },
+};
+
+export const StaticReadOnly: Story = {
+  args: {
+    label: "Read Only View",
+    readOnly: true,
+    value: "Canada",
+  },
 };

package/src/components/Dropdown/Dropdown.tsx

@@ -1,7 +1,186 @@
-import React from "react";
+import React, { forwardRef } from "react";
+import {
+  Select as MantineSelect,
+  type SelectProps as MantineSelectProps,
+} 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 "./Dropdown.module.css";
 
-export type DropdownProps = React.HTMLAttributes<HTMLDivElement>;
+export interface RecursicaDropdownProps
+  extends Omit<
+      MantineSelectProps,
+      | "size"
+      | "variant"
+      | "radius"
+      | "wrapperProps"
+      | "label"
+      | "description"
+      | "error"
+      | "required"
+      | "withAsterisk"
+    >,
+    Pick<
+      RecursicaFormControlWrapperProps,
+      | "label"
+      | "error"
+      | "required"
+      | "withAsterisk"
+      | "id"
+      | "assistiveText"
+      | "assistiveWithIcon"
+      | "formLayout"
+      | "labelSize"
+      | "labelAlignment"
+      | "labelOptionalText"
+      | "labelWithEditIcon"
+      | "onLabelEditClick"
+    >,
+    ReadOnlyControlProps {
+  /** Internal hook for Selects to override raw layout width properties when necessary */
+  containerWidth?: React.CSSProperties["width"];
+}
 
-export const Dropdown: React.FC<DropdownProps> = (props) => {
-  return <div {...props}>Dropdown</div>;
-};
+export type DropdownProps = RecursicaOverStyled<RecursicaDropdownProps>;
+
+export const Dropdown = forwardRef<HTMLInputElement, DropdownProps>(
+  function Dropdown(
+    {
+      overStyled = false,
+      formLayout = "stacked",
+      containerWidth,
+
+      // Label & Wrapper Maps
+      labelSize,
+      labelAlignment,
+      labelOptionalText,
+      labelWithEditIcon,
+      onLabelEditClick,
+
+      label,
+      assistiveText,
+      assistiveWithIcon,
+      error,
+      required,
+      withAsterisk,
+      id,
+      className,
+      style,
+      disabled,
+      readOnly,
+      readOnlyComponent,
+      value,
+      defaultValue,
+      data,
+      ...rest
+    },
+    ref,
+  ) {
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+    const restRecord = sanitizedProps as Record<string, unknown>;
+
+    // Delete prohibited sizing hooks from bypassing variables natively
+    delete restRecord["size"];
+    delete restRecord["variant"];
+    delete restRecord["radius"];
+
+    // Securely map core native blocks down ensuring nested CSS modules map precisely
+    const mergedClassNames: Partial<Record<string, string>> = {
+      wrapper: styles.root, // The nested Input internal relative wrapper bounding box
+      input: styles.input,
+      section: styles.section,
+      dropdown: styles.dropdown,
+      option: styles.option,
+    };
+
+    const classNamesProp = restRecord.classNames;
+    if (
+      classNamesProp &&
+      typeof classNamesProp === "object" &&
+      !Array.isArray(classNamesProp)
+    ) {
+      const o = classNamesProp as Partial<Record<string, string>>;
+      mergedClassNames.wrapper = o.wrapper
+        ? `${styles.root} ${o.wrapper}`
+        : styles.root;
+      mergedClassNames.input = o.input
+        ? `${styles.input} ${o.input}`
+        : styles.input;
+      mergedClassNames.section = o.section
+        ? `${styles.section} ${o.section}`
+        : styles.section;
+      mergedClassNames.dropdown = o.dropdown
+        ? `${styles.dropdown} ${o.dropdown}`
+        : styles.dropdown;
+      mergedClassNames.option = o.option
+        ? `${styles.option} ${o.option}`
+        : styles.option;
+    }
+
+    const injectedStyles = {
+      ...((style as React.CSSProperties) || {}),
+      width: containerWidth || "100%",
+    };
+
+    return (
+      <WithReadOnlyWrapper
+        className={className}
+        style={injectedStyles}
+        controlMaxWidth="var(--recursica_ui-kit_components_dropdown_properties_max-width)"
+        controlMinWidth="var(--recursica_ui-kit_components_dropdown_properties_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}
+        readOnlyType="text"
+        readOnlyValue={
+          value !== undefined
+            ? String(value)
+            : defaultValue
+              ? String(defaultValue)
+              : undefined
+        }
+        activeComponent={
+          /* Naked Select execution safely decoupled from Mantine's macro Input.Wrapper DOM hooks */
+          <MantineSelect
+            ref={ref}
+            classNames={mergedClassNames}
+            disabled={disabled}
+            value={value}
+            defaultValue={defaultValue}
+            data={data || []}
+            label={undefined}
+            description={undefined}
+            error={undefined}
+            required={undefined}
+            withAsterisk={undefined}
+            wrapperProps={{
+              "data-disabled": disabled ? "true" : undefined,
+              "data-error": error ? "true" : undefined,
+            }}
+            {...(sanitizedProps as unknown as MantineSelectProps)}
+          />
+        }
+      />
+    );
+  },
+);
+
+Dropdown.displayName = "Dropdown";

package/src/components/Flex/FLEX_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,4 @@
+# Flex Implementation Notes
+
+The `Flex` component is a generic unopinionated flex layout wrapper mapped directly to Mantine's `Flex`.
+It currently does not require any custom logical layouts or CSS workarounds since it serves only to provide absolute, raw manipulation of standard CSS flex properties. All spacing props (gap, align, justify, direction, wrap) pass safely through via the `filterStylingProps` layout-property allowance, with `rec-` dimension tokens scaling transparently mapped to standard gap limits.

package/src/components/Flex/Flex.module.css

@@ -0,0 +1,7 @@
+/* HARDCODED VALUES:
+ * None. This is a generic flex layout wrapper.
+ */
+
+.root {
+  /* Mantine handles flex, gap, align, justify. No intrinsic design-system styles required for pure layout wrappers. */
+}

package/src/components/Flex/Flex.stories.tsx

@@ -0,0 +1,125 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import { Flex } from "./Flex";
+import { Button } from "../Button";
+import { Text } from "../Text/Text";
+
+type FlexStoryProps = React.ComponentProps<typeof Flex>;
+
+const meta: Meta<FlexStoryProps> = {
+  title: "UI-Kit/Flex",
+  component: Flex,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Flex is a bare-metal flex container that maps directly to Mantine's Flex component, providing unopinionated control over direction, alignment, and wrapping.",
+      },
+    },
+  },
+  args: {
+    gap: "rec-default",
+    align: "center",
+    justify: "flex-start",
+    direction: "row",
+    wrap: "wrap",
+  },
+  argTypes: {
+    gap: {
+      control: "select",
+      options: [
+        "rec-none",
+        "rec-sm",
+        "rec-default",
+        "rec-md",
+        "rec-lg",
+        "rec-xl",
+        "rec-2xl",
+        "xs",
+        "sm",
+        "md",
+        "lg",
+        "xl",
+      ],
+      description: "Gap between elements",
+    },
+    direction: {
+      control: "select",
+      options: ["row", "column", "row-reverse", "column-reverse"],
+      description: "Flex-direction property",
+    },
+    align: {
+      control: "select",
+      options: ["flex-start", "center", "flex-end", "stretch"],
+      description: "Align-items property",
+    },
+    justify: {
+      control: "select",
+      options: [
+        "flex-start",
+        "center",
+        "flex-end",
+        "space-between",
+        "space-around",
+      ],
+      description: "Justify-content property",
+    },
+    wrap: {
+      control: "select",
+      options: ["wrap", "nowrap", "wrap-reverse"],
+      description: "Flex-wrap property",
+    },
+    defaultChecked: {
+      table: { disable: true },
+    },
+    rowGap: {
+      table: { disable: true },
+    },
+    columnGap: {
+      table: { disable: true },
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<FlexStoryProps>;
+
+export const Default: Story = {
+  render: (args) => (
+    <Flex {...args}>
+      <Button variant="solid">Block A</Button>
+      <Button variant="outline">Block B</Button>
+      <Text>Text inside Flex</Text>
+    </Flex>
+  ),
+};
+
+export const StaticGapSmallColumn: Story = {
+  args: {
+    gap: "rec-sm",
+    direction: "column",
+  },
+  render: (args) => (
+    <Flex {...args}>
+      <Button variant="solid">Item 1</Button>
+      <Button variant="solid">Item 2</Button>
+      <Button variant="solid">Item 3</Button>
+    </Flex>
+  ),
+};
+
+export const StaticGapLargeRow: Story = {
+  args: {
+    gap: "rec-xl",
+    direction: "row",
+  },
+  render: (args) => (
+    <Flex {...args}>
+      <Button variant="solid">Item 1</Button>
+      <Button variant="solid">Item 2</Button>
+      <Button variant="solid">Item 3</Button>
+    </Flex>
+  ),
+};

package/src/components/Flex/Flex.tsx

@@ -0,0 +1,68 @@
+import React, { forwardRef } from "react";
+import {
+  Flex as MantineFlex,
+  type FlexProps as MantineFlexProps,
+} from "@mantine/core";
+import {
+  filterStylingProps,
+  type RecursicaOverStyled,
+  type RecursicaSpacing,
+} from "../../utils/filterStylingProps";
+import styles from "./Flex.module.css";
+
+export interface RecursicaFlexProps {
+  /**
+   * Children components inside the Flex container
+   */
+  children?: React.ReactNode;
+  gap?: MantineFlexProps["gap"] | RecursicaSpacing;
+  rowGap?: MantineFlexProps["gap"] | RecursicaSpacing;
+  columnGap?: MantineFlexProps["gap"] | RecursicaSpacing;
+}
+
+/**
+ * Flex layout wrapper
+ */
+export type FlexProps = RecursicaOverStyled<
+  MantineFlexProps & RecursicaFlexProps
+>;
+
+export const Flex = forwardRef<HTMLDivElement, FlexProps>(function Flex(
+  { children, overStyled = false, gap = "rec-default", ...rest },
+  ref,
+) {
+  const sanitizedProps = filterStylingProps({ ...rest, gap }, overStyled);
+  const restRecord = sanitizedProps as Record<string, unknown>;
+
+  const mergedClassNames: Partial<Record<string, string>> = {
+    root: styles.root,
+  };
+
+  const classNamesProp = restRecord.classNames;
+  if (
+    classNamesProp &&
+    typeof classNamesProp === "object" &&
+    !Array.isArray(classNamesProp)
+  ) {
+    const o = classNamesProp as Partial<Record<string, string>>;
+    mergedClassNames.root = o.root ? `${styles.root} ${o.root}` : styles.root;
+  }
+
+  const classNameProp = restRecord.className as string | undefined;
+  const finalClass = classNameProp
+    ? `${styles.root} ${classNameProp}`
+    : styles.root;
+
+  return (
+    <MantineFlex
+      ref={ref}
+      className={finalClass}
+      classNames={mergedClassNames}
+      {...sanitizedProps}
+    >
+      {children}
+    </MantineFlex>
+  );
+});
+
+Flex.displayName = "Flex";

package/src/components/Group/GROUP_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,4 @@
+# Group Implementation Notes
+
+The `Group` component is a generic flex layout wrapper mapped directly to Mantine's `Group`.
+It currently does not require any custom logical layouts or CSS workarounds since it serves only to organize layout structure, and doesn't enforce any strict design-system token styling itself. All gap, align, wrap, and justify properties pass safely through via the `filterStylingProps` layout-property allowance.

package/src/components/Group/Group.module.css

@@ -0,0 +1,7 @@
+/* HARDCODED VALUES:
+ * None. This is a generic flex layout wrapper.
+ */
+
+.root {
+  /* Mantine handles flex, gap, align, justify. No intrinsic design-system styles required for pure layout wrappers. */
+}

package/src/components/Group/Group.stories.tsx

@@ -0,0 +1,117 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import { Group } from "./Group";
+import { Button } from "../Button";
+import { Text } from "../Text/Text";
+
+type GroupStoryProps = React.ComponentProps<typeof Group>;
+
+const meta: Meta<GroupStoryProps> = {
+  title: "UI-Kit/Group",
+  component: Group,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Group is a flex horizontal layout container that maps directly to Mantine's Group component allowing safe layout property passing.",
+      },
+    },
+  },
+  args: {
+    gap: "rec-default",
+    align: "center",
+    justify: "flex-start",
+    wrap: "wrap",
+  },
+  argTypes: {
+    gap: {
+      control: "select",
+      options: [
+        "rec-none",
+        "rec-sm",
+        "rec-default",
+        "rec-md",
+        "rec-lg",
+        "rec-xl",
+        "rec-2xl",
+        "xs",
+        "sm",
+        "md",
+        "lg",
+        "xl",
+      ],
+      description: "Gap between elements",
+    },
+    align: {
+      control: "select",
+      options: ["flex-start", "center", "flex-end", "stretch"],
+      description: "Align-items property",
+    },
+    justify: {
+      control: "select",
+      options: [
+        "flex-start",
+        "center",
+        "flex-end",
+        "space-between",
+        "space-around",
+      ],
+      description: "Justify-content property",
+    },
+    wrap: {
+      control: "select",
+      options: ["wrap", "nowrap", "wrap-reverse"],
+      description: "Flex-wrap property",
+    },
+    defaultChecked: {
+      table: { disable: true },
+    },
+    rowGap: {
+      table: { disable: true },
+    },
+    columnGap: {
+      table: { disable: true },
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<GroupStoryProps>;
+
+export const Default: Story = {
+  render: (args) => (
+    <Group {...args}>
+      <Button variant="solid">Primary</Button>
+      <Button variant="outline">Secondary</Button>
+      <Text>Text element within Group</Text>
+    </Group>
+  ),
+};
+
+export const StaticGapSmall: Story = {
+  args: {
+    gap: "rec-sm",
+  },
+  render: (args) => (
+    <Group {...args}>
+      <Button variant="solid">Item 1</Button>
+      <Button variant="solid">Item 2</Button>
+      <Button variant="solid">Item 3</Button>
+    </Group>
+  ),
+};
+
+export const StaticGapLarge: Story = {
+  args: {
+    gap: "rec-xl",
+  },
+  render: (args) => (
+    <Group {...args}>
+      <Button variant="solid">Item 1</Button>
+      <Button variant="solid">Item 2</Button>
+      <Button variant="solid">Item 3</Button>
+    </Group>
+  ),
+};

package/src/components/Group/Group.tsx

@@ -0,0 +1,68 @@
+import React, { forwardRef } from "react";
+import {
+  Group as MantineGroup,
+  type GroupProps as MantineGroupProps,
+} from "@mantine/core";
+import {
+  filterStylingProps,
+  type RecursicaOverStyled,
+  type RecursicaSpacing,
+} from "../../utils/filterStylingProps";
+import styles from "./Group.module.css";
+
+export interface RecursicaGroupProps {
+  /**
+   * Children components inside the group
+   */
+  children?: React.ReactNode;
+  gap?: MantineGroupProps["gap"] | RecursicaSpacing;
+  rowGap?: MantineGroupProps["gap"] | RecursicaSpacing;
+  columnGap?: MantineGroupProps["gap"] | RecursicaSpacing;
+}
+
+/**
+ * Group flex layout wrapper
+ */
+export type GroupProps = RecursicaOverStyled<
+  MantineGroupProps & RecursicaGroupProps
+>;
+
+export const Group = forwardRef<HTMLDivElement, GroupProps>(function Group(
+  { children, overStyled = false, gap = "rec-default", ...rest },
+  ref,
+) {
+  const sanitizedProps = filterStylingProps({ ...rest, gap }, overStyled);
+  const restRecord = sanitizedProps as Record<string, unknown>;
+
+  const mergedClassNames: Partial<Record<string, string>> = {
+    root: styles.root,
+  };
+
+  const classNamesProp = restRecord.classNames;
+  if (
+    classNamesProp &&
+    typeof classNamesProp === "object" &&
+    !Array.isArray(classNamesProp)
+  ) {
+    const o = classNamesProp as Partial<Record<string, string>>;
+    mergedClassNames.root = o.root ? `${styles.root} ${o.root}` : styles.root;
+  }
+
+  const classNameProp = restRecord.className as string | undefined;
+  const finalClass = classNameProp
+    ? `${styles.root} ${classNameProp}`
+    : styles.root;
+
+  return (
+    <MantineGroup
+      ref={ref}
+      className={finalClass}
+      classNames={mergedClassNames}
+      {...sanitizedProps}
+    >
+      {children}
+    </MantineGroup>
+  );
+});
+
+Group.displayName = "Group";