@recursica/mantine-adapter 0.7.0 → 0.9.0

package/src/components/Dropdown/Dropdown.module.css

@@ -0,0 +1,272 @@
+/* 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.
+   - placeholder opacity: 0.5. The dropdown parameters currently lack a dedicated placeholder-opacity variable.
+*/
+
+.root {
+  display: flex;
+  position: relative;
+  width: 100%;
+  min-height: var(--recursica_ui-kit_components_dropdown_properties_min-height);
+
+  /* Override Mantine native Input variables governing section spacing padding mathematics safely */
+  --input-left-section-size: calc(
+    var(--recursica_ui-kit_components_dropdown_properties_icon-size) +
+      (
+        var(
+            --recursica_ui-kit_components_dropdown_properties_horizontal-padding
+          ) *
+          2
+      )
+  );
+  --input-right-section-size: calc(
+    var(--recursica_ui-kit_components_dropdown_properties_icon-size) +
+      (
+        var(
+            --recursica_ui-kit_components_dropdown_properties_horizontal-padding
+          ) *
+          2
+      )
+  );
+}
+
+.input {
+  /* Structural Overrides */
+  width: 100%;
+  box-sizing: border-box;
+  margin: 0;
+
+  /* Box Geometry */
+  min-height: var(--recursica_ui-kit_components_dropdown_properties_min-height);
+  padding-top: var(
+    --recursica_ui-kit_components_dropdown_properties_vertical-padding
+  );
+  padding-bottom: var(
+    --recursica_ui-kit_components_dropdown_properties_vertical-padding
+  );
+  padding-left: var(
+    --recursica_ui-kit_components_dropdown_properties_horizontal-padding
+  );
+  padding-right: var(
+    --recursica_ui-kit_components_dropdown_properties_horizontal-padding
+  );
+  border-radius: var(
+    --recursica_ui-kit_components_dropdown_properties_border-radius
+  );
+  border-width: 1px;
+  border-style: solid;
+
+  /* Strict Typography Unification */
+  font-family: var(
+    --recursica_ui-kit_components_dropdown_properties_text_font-family
+  );
+  font-size: var(
+    --recursica_ui-kit_components_dropdown_properties_text_font-size
+  );
+  font-style: var(
+    --recursica_ui-kit_components_dropdown_properties_text_font-style
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_dropdown_properties_text_font-weight
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_dropdown_properties_text_letter-spacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_dropdown_properties_text_line-height
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_dropdown_properties_text_text-decoration
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_dropdown_properties_text_text-transform
+  );
+
+  /* Base State Default Execution */
+  background-color: var(
+    --recursica_ui-kit_components_dropdown_variants_states_default_properties_colors_background
+  );
+  border-color: var(
+    --recursica_ui-kit_components_dropdown_variants_states_default_properties_colors_border-color
+  );
+  color: var(
+    --recursica_ui-kit_components_dropdown_variants_states_default_properties_colors_text
+  );
+
+  outline: none;
+  transition:
+    border-color 0.15s ease,
+    background-color 0.15s ease;
+}
+
+.input::placeholder {
+  /* HARDCODE: Dropdown properties currently missing placeholder-opacity tokens from Figma JSON */
+  opacity: 0.5;
+  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_dropdown_properties_icon-size);
+  height: var(--recursica_ui-kit_components_dropdown_properties_icon-size);
+  color: var(
+    --recursica_ui-kit_components_dropdown_variants_states_default_properties_colors_leading-icon
+  );
+}
+
+.section[data-position="right"] :global(svg) {
+  color: var(
+    --recursica_ui-kit_components_dropdown_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_dropdown_variants_states_focus_properties_colors_border-color
+  );
+  background-color: var(
+    --recursica_ui-kit_components_dropdown_variants_states_focus_properties_colors_background
+  );
+  color: var(
+    --recursica_ui-kit_components_dropdown_variants_states_focus_properties_colors_text
+  );
+}
+
+.root:focus-within .section[data-position="left"] :global(svg) {
+  color: var(
+    --recursica_ui-kit_components_dropdown_variants_states_focus_properties_colors_leading-icon
+  );
+}
+
+.root:focus-within .section[data-position="right"] :global(svg) {
+  color: var(
+    --recursica_ui-kit_components_dropdown_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_dropdown_variants_states_error_properties_colors_border-color
+  ) !important;
+  background-color: var(
+    --recursica_ui-kit_components_dropdown_variants_states_error_properties_colors_background
+  ) !important;
+  color: var(
+    --recursica_ui-kit_components_dropdown_variants_states_error_properties_colors_text
+  ) !important;
+}
+
+.root[data-error] .section[data-position="left"] :global(svg) {
+  color: var(
+    --recursica_ui-kit_components_dropdown_variants_states_error_properties_colors_leading-icon
+  ) !important;
+}
+
+.root[data-error] .section[data-position="right"] :global(svg) {
+  color: var(
+    --recursica_ui-kit_components_dropdown_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_dropdown_variants_states_disabled_properties_colors_border-color
+  ) !important;
+  background-color: var(
+    --recursica_ui-kit_components_dropdown_variants_states_disabled_properties_colors_background
+  ) !important;
+  color: var(
+    --recursica_ui-kit_components_dropdown_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_dropdown_variants_states_disabled_properties_colors_leading-icon
+  ) !important;
+}
+
+.root[data-disabled] .section[data-position="right"] :global(svg) {
+  color: var(
+    --recursica_ui-kit_components_dropdown_variants_states_disabled_properties_colors_trailing-icon
+  ) !important;
+}
+
+/* -------------------------------------
+   DROPDOWN & OPTIONS ARCHITECTURE
+-------------------------------------- */
+
+.dropdown {
+  background-color: var(
+    --recursica_ui-kit_components_dropdown_variants_states_default_properties_colors_background
+  );
+  border: 1px solid
+    var(
+      --recursica_ui-kit_components_dropdown_variants_states_default_properties_colors_border-color
+    );
+  border-radius: var(
+    --recursica_ui-kit_components_dropdown_properties_border-radius
+  );
+  overflow: hidden;
+}
+
+.option {
+  font-family: var(
+    --recursica_ui-kit_components_dropdown_properties_text_font-family
+  );
+  font-size: var(
+    --recursica_ui-kit_components_dropdown_properties_text_font-size
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_dropdown_properties_text_font-weight
+  );
+  color: var(
+    --recursica_ui-kit_components_dropdown_variants_states_default_properties_colors_text
+  );
+  padding: calc(
+      var(--recursica_ui-kit_components_dropdown_properties_vertical-padding) *
+        0.75
+    )
+    var(--recursica_ui-kit_components_dropdown_properties_horizontal-padding);
+  cursor: pointer;
+}
+
+.option[data-selected="true"],
+.option[data-combobox-selected="true"],
+.option[data-hovered="true"],
+.option:hover {
+  background-color: var(
+    --recursica_ui-kit_components_dropdown_variants_states_focus_properties_colors_background
+  );
+  color: var(
+    --recursica_ui-kit_components_dropdown_variants_states_focus_properties_colors_text
+  );
+}

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,173 @@
-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"
+    >,
+    Pick<
+      RecursicaFormControlWrapperProps,
+      | "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>
+  ),
+};