@recursica/mantine-adapter 0.5.0 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (160) hide show
  1. package/.storybook/commonArgTypes.ts +148 -0
  2. package/CHANGELOG.md +69 -0
  3. package/dist/mantine-adapter.cjs +1 -1
  4. package/dist/mantine-adapter.cjs.map +1 -1
  5. package/dist/mantine-adapter.css +1 -1
  6. package/dist/mantine-adapter.js +1076 -266
  7. package/dist/mantine-adapter.js.map +1 -1
  8. package/dist/src/components/Accordion/Accordion.d.ts +13 -28
  9. package/dist/src/components/AssistiveElement/AssistiveElement.d.ts +10 -0
  10. package/dist/src/components/Avatar/Avatar.d.ts +1 -1
  11. package/dist/src/components/Breadcrumb/Breadcrumb.d.ts +6 -3
  12. package/dist/src/components/Button/Button.d.ts +1 -1
  13. package/dist/src/components/Card/Card.d.ts +38 -3
  14. package/dist/src/components/Checkbox/Checkbox.d.ts +11 -3
  15. package/dist/src/components/Checkbox/CheckboxGroup.d.ts +9 -0
  16. package/dist/src/components/Chip/Chip.d.ts +14 -2
  17. package/dist/src/components/FormControlWrapper/FormControlWrapper.d.ts +18 -0
  18. package/dist/src/components/Label/Label.d.ts +21 -0
  19. package/dist/src/components/Label/index.d.ts +1 -0
  20. package/dist/src/components/ReadOnlyField/ReadOnlyField.d.ts +19 -2
  21. package/dist/src/components/ReadOnlyField/ReadOnlyTextField.d.ts +8 -0
  22. package/dist/src/components/ReadOnlyField/WithReadOnlyWrapper.d.ts +22 -0
  23. package/dist/src/components/ReadOnlyField/index.d.ts +3 -0
  24. package/dist/src/components/Text/Text.d.ts +17 -0
  25. package/dist/src/components/TextField/TextField.d.ts +8 -2
  26. package/dist/src/components/Title/Title.d.ts +13 -0
  27. package/dist/src/components/index.d.ts +3 -1
  28. package/dist/src/utils/ColorSchemeWrapper.d.ts +3 -0
  29. package/dist/src/utils/filterStylingProps.d.ts +6 -2
  30. package/package.json +9 -5
  31. package/src/OverStyling.stories.tsx +174 -0
  32. package/src/Version.stories.tsx +56 -0
  33. package/src/components/Accordion/ACCORDION_IMPLEMENTATION_NOTES.md +48 -0
  34. package/src/components/Accordion/Accordion.module.css +261 -0
  35. package/src/components/Accordion/Accordion.stories.tsx +145 -0
  36. package/src/components/Accordion/Accordion.tsx +200 -0
  37. package/src/components/Accordion/index.ts +1 -0
  38. package/src/components/AssistiveElement/AssistiveElement.module.css +111 -0
  39. package/src/components/AssistiveElement/AssistiveElement.stories.tsx +73 -0
  40. package/src/components/AssistiveElement/AssistiveElement.tsx +91 -0
  41. package/src/components/Avatar/AVATAR_IMPLEMENTATION_NOTES.md +24 -0
  42. package/src/components/Avatar/Avatar.module.css +340 -0
  43. package/src/components/Avatar/Avatar.stories.tsx +102 -0
  44. package/src/components/Avatar/Avatar.tsx +100 -0
  45. package/src/components/Avatar/index.ts +1 -0
  46. package/src/components/Badge/BADGE_IMPLEMENTATION_NOTES.md +18 -0
  47. package/src/components/Badge/Badge.module.css +124 -0
  48. package/src/components/Badge/Badge.stories.tsx +77 -0
  49. package/src/components/Badge/Badge.tsx +66 -0
  50. package/src/components/Breadcrumb/BREADCRUMB_IMPLEMENTATION_NOTES.md +14 -0
  51. package/src/components/Breadcrumb/Breadcrumb.module.css +26 -0
  52. package/src/components/Breadcrumb/Breadcrumb.stories.tsx +77 -0
  53. package/src/components/Breadcrumb/Breadcrumb.tsx +64 -0
  54. package/src/components/Button/Button.module.css +275 -0
  55. package/src/components/Button/Button.stories.tsx +105 -0
  56. package/src/components/Button/Button.tsx +122 -0
  57. package/src/components/Button/IMPLEMENTATION_NOTES.md +45 -0
  58. package/src/components/Button/index.ts +1 -0
  59. package/src/components/Card/CARD_IMPLEMENTATION_NOTES.md +10 -0
  60. package/src/components/Card/Card.module.css +60 -0
  61. package/src/components/Card/Card.stories.tsx +141 -0
  62. package/src/components/Card/Card.tsx +176 -0
  63. package/src/components/Checkbox/CHECKBOX_IMPLEMENTATION_NOTES.md +25 -0
  64. package/src/components/Checkbox/Checkbox.module.css +204 -0
  65. package/src/components/Checkbox/Checkbox.stories.tsx +73 -0
  66. package/src/components/Checkbox/Checkbox.tsx +111 -0
  67. package/src/components/Checkbox/CheckboxGroup.stories.tsx +138 -0
  68. package/src/components/Checkbox/CheckboxGroup.tsx +140 -0
  69. package/src/components/Chip/CHIP_IMPLEMENTATION_NOTES.md +35 -0
  70. package/src/components/Chip/Chip.module.css +218 -0
  71. package/src/components/Chip/Chip.stories.tsx +115 -0
  72. package/src/components/Chip/Chip.tsx +143 -0
  73. package/src/components/DatePicker/DatePicker.stories.tsx +22 -0
  74. package/src/components/DatePicker/DatePicker.tsx +7 -0
  75. package/src/components/Dropdown/Dropdown.stories.tsx +22 -0
  76. package/src/components/Dropdown/Dropdown.tsx +7 -0
  77. package/src/components/FileInput/FileInput.stories.tsx +22 -0
  78. package/src/components/FileInput/FileInput.tsx +7 -0
  79. package/src/components/FileUpload/FileUpload.stories.tsx +22 -0
  80. package/src/components/FileUpload/FileUpload.tsx +7 -0
  81. package/src/components/FormControlWrapper/FORMCONTROLWRAPPER_IMPLEMENTATION_NOTES.md +32 -0
  82. package/src/components/FormControlWrapper/FormControlWrapper.module.css +46 -0
  83. package/src/components/FormControlWrapper/FormControlWrapper.stories.tsx +116 -0
  84. package/src/components/FormControlWrapper/FormControlWrapper.tsx +170 -0
  85. package/src/components/HoverCard/HoverCard.stories.tsx +17 -0
  86. package/src/components/HoverCard/HoverCard.tsx +7 -0
  87. package/src/components/Label/LABEL_IMPLEMENTATION_NOTES.md +48 -0
  88. package/src/components/Label/Label.module.css +177 -0
  89. package/src/components/Label/Label.stories.tsx +123 -0
  90. package/src/components/Label/Label.tsx +132 -0
  91. package/src/components/Label/index.ts +1 -0
  92. package/src/components/Link/Link.stories.tsx +17 -0
  93. package/src/components/Link/Link.tsx +7 -0
  94. package/src/components/Loader/Loader.stories.tsx +17 -0
  95. package/src/components/Loader/Loader.tsx +7 -0
  96. package/src/components/Menu/Menu.stories.tsx +17 -0
  97. package/src/components/Menu/Menu.tsx +7 -0
  98. package/src/components/Modal/Modal.stories.tsx +17 -0
  99. package/src/components/Modal/Modal.tsx +7 -0
  100. package/src/components/NumberInput/NumberInput.stories.tsx +22 -0
  101. package/src/components/NumberInput/NumberInput.tsx +7 -0
  102. package/src/components/Pagination/Pagination.stories.tsx +17 -0
  103. package/src/components/Pagination/Pagination.tsx +7 -0
  104. package/src/components/Panel/Panel.stories.tsx +17 -0
  105. package/src/components/Panel/Panel.tsx +7 -0
  106. package/src/components/Popover/Popover.stories.tsx +17 -0
  107. package/src/components/Popover/Popover.tsx +7 -0
  108. package/src/components/Radio/Radio.stories.tsx +22 -0
  109. package/src/components/Radio/Radio.tsx +7 -0
  110. package/src/components/ReadOnlyField/READ_ONLY_FIELD_IMPLEMENTATION_NOTES.md +15 -0
  111. package/src/components/ReadOnlyField/ReadOnlyField.module.css +49 -0
  112. package/src/components/ReadOnlyField/ReadOnlyField.stories.tsx +120 -0
  113. package/src/components/ReadOnlyField/ReadOnlyField.tsx +75 -0
  114. package/src/components/ReadOnlyField/ReadOnlyTextField.tsx +46 -0
  115. package/src/components/ReadOnlyField/WithReadOnlyWrapper.tsx +85 -0
  116. package/src/components/ReadOnlyField/index.ts +3 -0
  117. package/src/components/Search/Search.stories.tsx +17 -0
  118. package/src/components/Search/Search.tsx +7 -0
  119. package/src/components/SegmentedControl/SegmentedControl.stories.tsx +22 -0
  120. package/src/components/SegmentedControl/SegmentedControl.tsx +7 -0
  121. package/src/components/Slider/Slider.stories.tsx +22 -0
  122. package/src/components/Slider/Slider.tsx +7 -0
  123. package/src/components/Stepper/Stepper.stories.tsx +17 -0
  124. package/src/components/Stepper/Stepper.tsx +7 -0
  125. package/src/components/Switch/Switch.stories.tsx +22 -0
  126. package/src/components/Switch/Switch.tsx +7 -0
  127. package/src/components/Table/Table.stories.tsx +17 -0
  128. package/src/components/Table/Table.tsx +7 -0
  129. package/src/components/Tabs/Tabs.stories.tsx +17 -0
  130. package/src/components/Tabs/Tabs.tsx +7 -0
  131. package/src/components/Text/Text.stories.tsx +88 -0
  132. package/src/components/Text/Text.tsx +54 -0
  133. package/src/components/TextArea/TextArea.stories.tsx +22 -0
  134. package/src/components/TextArea/TextArea.tsx +7 -0
  135. package/src/components/TextField/TEXTFIELD_IMPLEMENTATION_NOTES.md +19 -0
  136. package/src/components/TextField/TextField.module.css +225 -0
  137. package/src/components/TextField/TextField.stories.tsx +162 -0
  138. package/src/components/TextField/TextField.tsx +138 -0
  139. package/src/components/TimePicker/TimePicker.stories.tsx +22 -0
  140. package/src/components/TimePicker/TimePicker.tsx +7 -0
  141. package/src/components/Timeline/Timeline.stories.tsx +17 -0
  142. package/src/components/Timeline/Timeline.tsx +7 -0
  143. package/src/components/Title/Title.stories.tsx +63 -0
  144. package/src/components/Title/Title.tsx +45 -0
  145. package/src/components/Toast/Toast.stories.tsx +17 -0
  146. package/src/components/Toast/Toast.tsx +7 -0
  147. package/src/components/Tooltip/Tooltip.stories.tsx +17 -0
  148. package/src/components/Tooltip/Tooltip.tsx +7 -0
  149. package/src/components/TransferList/TransferList.stories.tsx +17 -0
  150. package/src/components/TransferList/TransferList.tsx +7 -0
  151. package/src/components/index.ts +39 -0
  152. package/src/env.d.ts +7 -0
  153. package/src/index.ts +3 -0
  154. package/src/types/index.ts +9 -0
  155. package/src/types/mantine.d.ts +7 -0
  156. package/src/types/scss-modules.d.ts +9 -0
  157. package/src/utils/ColorSchemeWrapper.tsx +27 -0
  158. package/src/utils/copyToClipboard.ts +36 -0
  159. package/src/utils/filterStylingProps.ts +139 -0
  160. package/src/utils/index.ts +1 -0
@@ -0,0 +1,170 @@
1
+ import React, { forwardRef, useId } from "react";
2
+ import { type InputWrapperProps, Box } from "@mantine/core";
3
+ import {
4
+ filterStylingProps,
5
+ type RecursicaOverStyled,
6
+ } from "../../utils/filterStylingProps";
7
+ import { Label, type RecursicaLabelProps } from "../Label/Label";
8
+ import { AssistiveElement } from "../AssistiveElement/AssistiveElement";
9
+ import styles from "./FormControlWrapper.module.css";
10
+
11
+ export interface RecursicaFormControlWrapperProps extends RecursicaLabelProps {
12
+ /** Securely replaces standard Mantine descriptions safely providing standard Assistive properties. */
13
+ assistiveText?: React.ReactNode;
14
+ /** Explicit toggle to suppress the Info icon rendering natively alongside the assistiveText. Defaults to true. */
15
+ assistiveWithIcon?: boolean;
16
+ /** Custom action area to render alongside the label instead of the default edit icon. */
17
+ labelActionArea?: React.ReactNode;
18
+ /** Pass the native maximum width design variable dynamically bounding the specific wrapper width exclusively. */
19
+ controlMaxWidth: string | undefined;
20
+ /** Pass the native minimum width design variable dynamically bounding the specific wrapper width exclusively. */
21
+ controlMinWidth: string | undefined;
22
+ }
23
+
24
+ export type FormControlWrapperProps = RecursicaOverStyled<
25
+ Omit<InputWrapperProps, "labelProps" | "inputWrapperOrder"> &
26
+ RecursicaFormControlWrapperProps
27
+ >;
28
+
29
+ export const FormControlWrapper = forwardRef<
30
+ HTMLDivElement,
31
+ FormControlWrapperProps
32
+ >(function FormControlWrapper(
33
+ {
34
+ formLayout,
35
+ labelSize,
36
+ labelAlignment,
37
+ labelOptionalText,
38
+ labelWithEditIcon,
39
+ labelActionArea,
40
+ onLabelEditClick,
41
+
42
+ label,
43
+ description,
44
+ assistiveText,
45
+ assistiveWithIcon = true,
46
+ controlMaxWidth,
47
+ controlMinWidth,
48
+ error,
49
+ required,
50
+ withAsterisk,
51
+ id: userProvidedId,
52
+ children,
53
+ className,
54
+ overStyled = false,
55
+ labelElement, // Extracted safely preventing bleeding into HTML domains
56
+ ...rest
57
+ },
58
+ ref,
59
+ ) {
60
+ // Generate a reliable ID to map the Label's HTML context down to the component array natively.
61
+ const generatedId = useId();
62
+ const id = userProvidedId || `recursica-fc-${generatedId}`;
63
+
64
+ // Evaluate explicit assistive fallbacks ensuring assistiveText correctly prioritizes natively over underlying Mantine configurations!
65
+ const resolvedAssistive = assistiveText || description;
66
+ const assistiveId = resolvedAssistive ? `${id}-assistive` : undefined;
67
+ const errorId = error ? `${id}-error` : undefined;
68
+
69
+ const sanitizedProps = filterStylingProps(rest, overStyled);
70
+ const restRecord = sanitizedProps as Record<string, unknown>;
71
+
72
+ const classNameProp =
73
+ className || (restRecord.className as string | undefined);
74
+ const rootClass = styles.root;
75
+ const finalClass = classNameProp
76
+ ? `${rootClass} ${classNameProp}`
77
+ : rootClass;
78
+
79
+ // Clone ARIA identifiers directly back down into the nested children wrapper so screen-readers natively hook the external strings
80
+ const content = React.isValidElement(children)
81
+ ? React.cloneElement(
82
+ children as React.ReactElement<Record<string, unknown>>,
83
+ {
84
+ ...(resolvedAssistive &&
85
+ !(children.props as Record<string, unknown>)["aria-describedby"]
86
+ ? { "aria-describedby": assistiveId }
87
+ : {}),
88
+ ...(error &&
89
+ !(children.props as Record<string, unknown>)["aria-errormessage"]
90
+ ? { "aria-errormessage": errorId }
91
+ : {}),
92
+ },
93
+ )
94
+ : children;
95
+
96
+ return (
97
+ <Box
98
+ ref={ref}
99
+ className={finalClass}
100
+ data-form-layout={formLayout || "stacked"}
101
+ data-form-alignment={labelAlignment || "left"}
102
+ style={
103
+ {
104
+ ...((restRecord.style as React.CSSProperties) || {}),
105
+ ...(controlMaxWidth
106
+ ? { "--form-control-max-width": controlMaxWidth }
107
+ : {}),
108
+ ...(controlMinWidth
109
+ ? { "--form-control-min-width": controlMinWidth }
110
+ : {}),
111
+ } as React.CSSProperties
112
+ }
113
+ {...restRecord}
114
+ >
115
+ {/*
116
+ Section 1: The Native Custom Label
117
+ Bypasses Mantine's built-in Input.Wrapper Label entirely in favor of explicit Recursica formatting.
118
+ */}
119
+ {label && (
120
+ <div className={styles.labelSection}>
121
+ <Label
122
+ id={id} // Directly binds ARIA references down
123
+ formLayout={formLayout}
124
+ labelSize={labelSize}
125
+ labelAlignment={labelAlignment}
126
+ labelOptionalText={labelOptionalText}
127
+ labelWithEditIcon={labelWithEditIcon}
128
+ labelActionArea={labelActionArea}
129
+ onLabelEditClick={onLabelEditClick}
130
+ required={withAsterisk ?? required}
131
+ // Manually propagate relevant structural logic if underlying groups dictate Label to act as generic wrapper
132
+ {...(labelElement === "div" ? { as: "div" } : {})}
133
+ >
134
+ {label}
135
+ </Label>
136
+ </div>
137
+ )}
138
+
139
+ {/*
140
+ Section 2: The Core Input Wrapper & Controls
141
+ Nakedly inject the actual field elements alongside natively bridged Assistive components mapped dynamically.
142
+ */}
143
+ <div className={styles.inputSection}>
144
+ {content}
145
+
146
+ {error && (
147
+ <AssistiveElement
148
+ id={errorId}
149
+ assistiveVariant="error"
150
+ assistiveWithIcon={assistiveWithIcon}
151
+ >
152
+ {error}
153
+ </AssistiveElement>
154
+ )}
155
+
156
+ {!error && resolvedAssistive && (
157
+ <AssistiveElement
158
+ id={assistiveId}
159
+ assistiveVariant="help"
160
+ assistiveWithIcon={assistiveWithIcon}
161
+ >
162
+ {resolvedAssistive}
163
+ </AssistiveElement>
164
+ )}
165
+ </div>
166
+ </Box>
167
+ );
168
+ });
169
+
170
+ FormControlWrapper.displayName = "FormControlWrapper";
@@ -0,0 +1,17 @@
1
+ import type { Meta, StoryObj } from "@storybook/react";
2
+ import { HoverCard } from "./HoverCard";
3
+ import { ComingSoon } from "@recursica/storybook-template";
4
+
5
+ const meta: Meta<typeof HoverCard> = {
6
+ title: "UI-Kit/🚧 HoverCard",
7
+ component: HoverCard,
8
+ tags: ["autodocs"],
9
+ };
10
+
11
+ export default meta;
12
+
13
+ type Story = StoryObj<typeof HoverCard>;
14
+
15
+ export const Default: Story = {
16
+ render: () => <ComingSoon componentName="HoverCard" />,
17
+ };
@@ -0,0 +1,7 @@
1
+ import React from "react";
2
+
3
+ export type HoverCardProps = React.HTMLAttributes<HTMLDivElement>;
4
+
5
+ export const HoverCard: React.FC<HoverCardProps> = (props) => {
6
+ return <div {...props}>HoverCard</div>;
7
+ };
@@ -0,0 +1,48 @@
1
+ # Label Implementation Notes
2
+
3
+ ## Architecture Overview
4
+
5
+ The `Label` component is fundamentally built as a strict, localized wrapper around Mantine's native `Input.Label`. The core goal is to preserve context, ref-forwarding, and native accessibility links, while completely overriding visual behaviors via Recursica design variables in scoped CSS.
6
+
7
+ ## Key Design Decisions
8
+
9
+ ### **Layout Architecture**
10
+
11
+ - Because Recursica dictates complex alignments between primary label text, asterisks, edit icons, and optional strings, Mantine's rigid form label flow could not be used out-of-the-box.
12
+ - Implemented `display: flex; flex-wrap: wrap;` directly on `.root`.
13
+ - Injected strict integer-based flex `order` properties (e.g. `order: 1` for text, `order: 2` for `required`, `order: 5` for `optionalText`) to physically decouple DOM rendering from markup flow.
14
+ - Because `optionalText` often acts as secondary contextual detail, it forces `flex-basis: 100%`, securely wrapping to a secondary line underneath the primary label properties and transforming the horizontal gap spacing seamlessly into a `margin-top` vector.
15
+
16
+ ### **Optional Text & Required Mutually Exclusive Parsing**
17
+
18
+ - By design standards, a component cannot logically be both "Required" and mapped as "Optional".
19
+ - To bulletproof implementations natively, the adapter forcibly suppresses rendering of the `resolvedOptionalText` strings if the parent wrapper invokes `required={true}`.
20
+ - `optionalText` can operate as dynamic data or specifically as a boolean `true`, which forces the adapter to natively render the formal `(Optional)` string map.
21
+
22
+ ### **The "Edit Icon" Replacer Logic**
23
+
24
+ - Passing `withEditIcon={true}` evaluates it as fundamentally mutually exclusive to the standard required indicator asterisk.
25
+ - `required={required && !withEditIcon}` is passed to the underlying Mantine structure so the native `*` is entirely suppressed.
26
+ - Added localized styling via `data-replaces-asterisk={required ? "true" : undefined}` onto the `.editIconWrapper` element. If an editable instance is simultaneously designated as required, the edit icon functionally assumes the indicator role natively, overriding its default icon metrics explicitly to match `--recursica_ui-kit_components_label_properties_colors_asterisk`.
27
+
28
+ ### **Bypassing `Input.Wrapper` Integrations**
29
+
30
+ - By decoupling from Mantine's standard `Input.Wrapper`, the `Label` component is exclusively mapped manually through `FormControlWrapper`. This grants us exact visual sync regarding where the label renders based on `formLayout="stacked"` or `formLayout="side-by-side"`, without fighting internal Mantine positional hooks that assume vertical stacking by default.
31
+
32
+ ### **Label Size Container Constraints**
33
+
34
+ - The `labelSize` parameter (mapping values like `"small"`) internally **does not scale typographic font metrics**. Instead, it dynamically defines the explicit horizontal bounding width limit of the block container itself.
35
+ - **Architectural Rule:** `labelSize` modifications are strictly designed to execute exclusively when `formLayout="side-by-side"` is active. It acts as an optical grid threshold ensuring left-aligned string wrappers constrain correctly uniformly down a column without bleeding into the physical input arrays alongside them.
36
+
37
+ ## Outstanding Technical Debt / Issues
38
+
39
+ ### **Description Property Omission**
40
+
41
+ - **Issue:** Currently, the adapter `Label` does not natively parse or support a structured `description` node directly attached beneath it.
42
+ - **Context:** Standard forms often attach subtext beneath inputs, but mapping a description purely within the `<Label>` (distinct from an overall form-control description) is omitted structurally until subsequent UI Kit requirements mandate dedicated `description` styles locally on the label component itself.
43
+
44
+ ### **Global Interactive Hover Mappings**
45
+
46
+ - **Issue:** Currently, the `editIconWrapper` lacks a dedicated hover background layer.
47
+ - **Context:** While the global theme abstracts interactive hover environments deeply using layered variable syntax (e.g., `--recursica_brand_layer_1_elements_interactive_hover-color`), Recursica's token generation framework natively fails to expose a universally generic placeholder token (e.g., `--recursica_elements_interactive_hover-color`) which downstream wrappers can map their `<Layer>` injections directly into safely.
48
+ - **Resolution Path:** We are explicitly ignoring the `.editIconWrapper:hover` background color assignment until the raw Figma token exports directly scaffold a generic token placeholder that we can interface cleanly with across arbitrary `<Layer>` contexts, avoiding manually mapping statically hardcoded depths (`layer-0`, `layer-1`).
@@ -0,0 +1,177 @@
1
+ /* HARDCODED VALUES:
2
+ - display: flex helps us leverage flex 'order' to perfectly position Mantine's injected asterisk.
3
+ - align-items: baseline ensures text logic lines up nicely if font sizes differ slightly.
4
+ - margin/padding resets.
5
+ */
6
+
7
+ .root {
8
+ display: flex;
9
+ flex-wrap: wrap;
10
+ align-items: baseline;
11
+ box-sizing: border-box;
12
+ margin: 0;
13
+ color: var(--recursica_ui-kit_components_label_properties_colors_text);
14
+ }
15
+
16
+ .root[data-alignment="left"] {
17
+ justify-content: flex-start;
18
+ text-align: left;
19
+ }
20
+
21
+ .root[data-alignment="right"] {
22
+ justify-content: flex-end;
23
+ text-align: right;
24
+ }
25
+
26
+ .root[data-layout="stacked"] {
27
+ padding-bottom: var(
28
+ --recursica_ui-kit_components_label_variants_layouts_stacked_properties_bottom-padding
29
+ );
30
+ min-height: var(
31
+ --recursica_ui-kit_components_label_variants_layouts_stacked_properties_min-height
32
+ );
33
+ }
34
+
35
+ .root[data-layout="side-by-side"] {
36
+ padding-top: var(
37
+ --recursica_ui-kit_components_label_variants_layouts_side-by-side_properties_vertical-padding
38
+ );
39
+ padding-bottom: var(
40
+ --recursica_ui-kit_components_label_variants_layouts_side-by-side_properties_vertical-padding
41
+ );
42
+ min-height: var(
43
+ --recursica_ui-kit_components_label_variants_layouts_side-by-side_properties_min-height
44
+ );
45
+ /* In side-by-side, the label exists to the left of its input, so we use the gutter gap here. */
46
+ margin-right: var(
47
+ --recursica_ui-kit_components_label_variants_layouts_side-by-side_properties_gutter
48
+ );
49
+ }
50
+
51
+ .root[data-layout="side-by-side"][data-size="default"] {
52
+ width: var(
53
+ --recursica_ui-kit_components_label_variants_layouts_side-by-side_variants_sizes_default_properties_width
54
+ );
55
+ }
56
+
57
+ .root[data-layout="side-by-side"][data-size="small"] {
58
+ width: var(
59
+ --recursica_ui-kit_components_label_variants_layouts_side-by-side_variants_sizes_small_properties_width
60
+ );
61
+ }
62
+
63
+ .labelText {
64
+ order: 1;
65
+ font-family: var(
66
+ --recursica_ui-kit_components_label_properties_label-text_font-family
67
+ );
68
+ font-size: var(
69
+ --recursica_ui-kit_components_label_properties_label-text_font-size
70
+ );
71
+ font-weight: var(
72
+ --recursica_ui-kit_components_label_properties_label-text_font-weight
73
+ );
74
+ letter-spacing: var(
75
+ --recursica_ui-kit_components_label_properties_label-text_letter-spacing
76
+ );
77
+ line-height: var(
78
+ --recursica_ui-kit_components_label_properties_label-text_line-height
79
+ );
80
+ font-style: var(
81
+ --recursica_ui-kit_components_label_properties_label-text_font-style,
82
+ normal
83
+ );
84
+ text-decoration: var(
85
+ --recursica_ui-kit_components_label_properties_label-text_text-decoration,
86
+ none
87
+ );
88
+ text-transform: var(
89
+ --recursica_ui-kit_components_label_properties_label-text_text-transform,
90
+ none
91
+ );
92
+ }
93
+
94
+ .required {
95
+ order: 2;
96
+ margin-left: var(
97
+ --recursica_ui-kit_components_label_properties_required-indicator-gap
98
+ );
99
+ color: var(--recursica_ui-kit_components_label_properties_colors_asterisk);
100
+
101
+ /* Inherit identical typography bounds to prevent flex row line-height stretching */
102
+ font-family: var(
103
+ --recursica_ui-kit_components_label_properties_label-text_font-family
104
+ );
105
+ font-size: var(
106
+ --recursica_ui-kit_components_label_properties_label-text_font-size
107
+ );
108
+ line-height: var(
109
+ --recursica_ui-kit_components_label_properties_label-text_line-height
110
+ );
111
+ }
112
+
113
+ .optionalText {
114
+ order: 5;
115
+ flex-basis: 100%;
116
+ margin-top: var(
117
+ --recursica_ui-kit_components_label_properties_label-optional-text-gap
118
+ );
119
+ margin-left: 0;
120
+ font-family: var(
121
+ --recursica_ui-kit_components_label_properties_optional-text_font-family
122
+ );
123
+ font-size: var(
124
+ --recursica_ui-kit_components_label_properties_optional-text_font-size
125
+ );
126
+ font-weight: var(
127
+ --recursica_ui-kit_components_label_properties_optional-text_font-weight
128
+ );
129
+ letter-spacing: var(
130
+ --recursica_ui-kit_components_label_properties_optional-text_letter-spacing
131
+ );
132
+ line-height: var(
133
+ --recursica_ui-kit_components_label_properties_optional-text_line-height
134
+ );
135
+ font-style: normal;
136
+ text-decoration: var(
137
+ --recursica_ui-kit_components_label_properties_optional-text_text-decoration,
138
+ none
139
+ );
140
+ text-transform: var(
141
+ --recursica_ui-kit_components_label_properties_optional-text_text-transform,
142
+ none
143
+ );
144
+ color: inherit;
145
+ opacity: var(
146
+ --recursica_ui-kit_components_label_properties_colors_optional-text-opacity
147
+ );
148
+ }
149
+
150
+ .actionAreaWrapper {
151
+ order: 4;
152
+ margin-left: var(
153
+ --recursica_ui-kit_components_label_properties_edit-icon-gap
154
+ );
155
+ display: inline-flex;
156
+ align-items: center;
157
+ justify-content: center;
158
+ }
159
+
160
+ .editIconWrapper {
161
+ order: 4;
162
+ margin-left: var(
163
+ --recursica_ui-kit_components_label_properties_edit-icon-gap
164
+ );
165
+ background: none;
166
+ border: none;
167
+ padding: 0;
168
+ cursor: pointer;
169
+ display: inline-flex;
170
+ align-items: center;
171
+ justify-content: center;
172
+ color: inherit;
173
+ }
174
+
175
+ .editIconWrapper[data-replaces-asterisk="true"] {
176
+ color: var(--recursica_ui-kit_components_label_properties_colors_asterisk);
177
+ }
@@ -0,0 +1,123 @@
1
+ /* eslint-disable @typescript-eslint/no-explicit-any */
2
+ import React from "react";
3
+ import type { Meta, StoryObj } from "@storybook/react";
4
+ import { Label } from "./Label";
5
+ import { TextField } from "../TextField/TextField";
6
+ import { formControlArgTypes } from "../../../.storybook/commonArgTypes";
7
+
8
+ type LabelStoryProps = React.ComponentProps<typeof Label>;
9
+
10
+ const meta: Meta<LabelStoryProps> = {
11
+ title: "UI-Kit/Label",
12
+ component: Label,
13
+ tags: ["autodocs"],
14
+ parameters: {
15
+ docs: {
16
+ description: {
17
+ component:
18
+ "The `Label` component is a strict Recursica-styled wrapper around Mantine's native `Input.Label`. It serves as the primary compositional primitive for all form fields, preserving Mantine's accessibility associations and context while strictly enforcing the Recursica atomic design system.\n\n### Usage with Form Inputs\nWhen working with form structures, render this `Label` component directly above your inputs or supply it to a component's overriding properties. The component automatically maps structural layout dimensions, dynamic alignment (`left` vs `right`), custom indicator gaps, and integrates a customized `optionalText` and `withEditIcon` flow that safely bypasses Mantine's native required asterisk mechanisms.",
19
+ },
20
+ },
21
+ },
22
+ argTypes: {
23
+ ...formControlArgTypes,
24
+ },
25
+ };
26
+
27
+ export default meta;
28
+
29
+ type Story = StoryObj<LabelStoryProps>;
30
+
31
+ // Utility mapping to pipe raw Label args structurally into TextField accurately
32
+ const renderWithTextField = ({ children, ...args }: LabelStoryProps) => (
33
+ <TextField
34
+ label={children as React.ReactNode}
35
+ placeholder="Form Control primitive mapped..."
36
+ {...(args as any)}
37
+ />
38
+ );
39
+
40
+ export const Default: Story = {
41
+ args: {
42
+ children: "Dynamic Label (Controls)",
43
+ formLayout: "stacked",
44
+ labelSize: "default",
45
+ labelAlignment: "left",
46
+ required: false,
47
+ labelOptionalText: "",
48
+ labelWithEditIcon: false,
49
+ },
50
+ render: renderWithTextField,
51
+ };
52
+
53
+ export const StackedDefault: Story = {
54
+ args: {
55
+ children: "Email Address",
56
+ formLayout: "stacked",
57
+ },
58
+ render: renderWithTextField,
59
+ };
60
+
61
+ export const StackedRequired: Story = {
62
+ args: {
63
+ children: "Primary Network Node",
64
+ formLayout: "stacked",
65
+ required: true,
66
+ },
67
+ render: renderWithTextField,
68
+ };
69
+
70
+ export const StackedWithEditIcon: Story = {
71
+ args: {
72
+ children: "Environment Variables",
73
+ formLayout: "stacked",
74
+ labelWithEditIcon: true,
75
+ },
76
+ render: renderWithTextField,
77
+ };
78
+
79
+ export const SideBySideDefault: Story = {
80
+ args: {
81
+ children: "Status",
82
+ formLayout: "side-by-side",
83
+ labelSize: "default",
84
+ },
85
+ render: renderWithTextField,
86
+ };
87
+
88
+ export const RequiredSuppressesOptionalText: Story = {
89
+ args: {
90
+ children: "Full Name",
91
+ formLayout: "stacked",
92
+ required: true,
93
+ labelOptionalText: "This should not render",
94
+ },
95
+ render: renderWithTextField,
96
+ };
97
+
98
+ export const BooleanOptionalText: Story = {
99
+ args: {
100
+ children: "Middle Initial",
101
+ formLayout: "side-by-side",
102
+ labelOptionalText: true,
103
+ },
104
+ render: renderWithTextField,
105
+ };
106
+
107
+ export const WithEditIcon: Story = {
108
+ args: {
109
+ children: "Shipping Address",
110
+ formLayout: "side-by-side",
111
+ labelWithEditIcon: true,
112
+ },
113
+ render: renderWithTextField,
114
+ };
115
+
116
+ export const LayerOneSideBySide: Story = {
117
+ args: {
118
+ children: "Configuration",
119
+ formLayout: "side-by-side",
120
+ labelWithEditIcon: true,
121
+ },
122
+ render: renderWithTextField,
123
+ };
@@ -0,0 +1,132 @@
1
+ import React, { forwardRef } from "react";
2
+ import { Input, type InputLabelProps } from "@mantine/core";
3
+ import {
4
+ filterStylingProps,
5
+ type RecursicaOverStyled,
6
+ } from "../../utils/filterStylingProps";
7
+ import styles from "./Label.module.css";
8
+
9
+ export interface RecursicaLabelProps {
10
+ /** Overall structural flow mapping the Form Control natively cascading down to Label and Input logic. */
11
+ formLayout?: "stacked" | "side-by-side";
12
+ /** Specifies the sizing metrics natively mapping the Label boundaries. */
13
+ labelSize?: "default" | "small";
14
+ /** Overall alignment directive for the label strings natively forcing Left/Right justification. */
15
+ labelAlignment?: "left" | "right";
16
+ /** Injects an indicator text block alongside the label. Can be boolean (`true` maps to '(Optional)') or custom React nodes. */
17
+ labelOptionalText?: boolean | React.ReactNode;
18
+ /** When true, forces the native Edit Icon to replace the standard asterisk visually. */
19
+ labelWithEditIcon?: boolean;
20
+ /** Custom action area to render alongside the label instead of the default edit icon. */
21
+ labelActionArea?: React.ReactNode;
22
+ /** Interaction hook invoked whenever a generated edit icon block natively triggers a click event. */
23
+ onLabelEditClick?: React.MouseEventHandler<HTMLButtonElement>;
24
+ }
25
+
26
+ export type LabelProps = RecursicaOverStyled<
27
+ Omit<InputLabelProps, "size"> & RecursicaLabelProps
28
+ >;
29
+
30
+ export const Label = forwardRef<HTMLLabelElement, LabelProps>(function Label(
31
+ {
32
+ formLayout = "stacked",
33
+ labelSize = "default",
34
+ labelAlignment,
35
+ required = false,
36
+ labelOptionalText,
37
+ labelWithEditIcon,
38
+ labelActionArea,
39
+ onLabelEditClick,
40
+ children,
41
+ overStyled = false,
42
+ ...rest
43
+ },
44
+ ref,
45
+ ) {
46
+ const resolvedAlignment =
47
+ labelAlignment || (formLayout === "side-by-side" ? "right" : "left");
48
+
49
+ let resolvedOptionalText: React.ReactNode | undefined;
50
+ if (!required) {
51
+ if (labelOptionalText === true) resolvedOptionalText = "optional";
52
+ else if (labelOptionalText) resolvedOptionalText = labelOptionalText;
53
+ }
54
+
55
+ const sanitizedProps = filterStylingProps(rest, overStyled);
56
+ const restRecord = sanitizedProps as Record<string, unknown>;
57
+
58
+ const mergedClassNames: Partial<Record<string, string>> = {
59
+ label: styles.root,
60
+ required: styles.required,
61
+ };
62
+
63
+ const classNamesProp = restRecord.classNames;
64
+ if (
65
+ classNamesProp &&
66
+ typeof classNamesProp === "object" &&
67
+ !Array.isArray(classNamesProp)
68
+ ) {
69
+ const o = classNamesProp as Partial<Record<string, string>>;
70
+ mergedClassNames.label = o.label
71
+ ? `${styles.root} ${o.label}`
72
+ : styles.root;
73
+ mergedClassNames.required = o.required
74
+ ? `${styles.required} ${o.required}`
75
+ : styles.required;
76
+ }
77
+
78
+ const classNameProp = restRecord.className as string | undefined;
79
+ const finalClass = classNameProp
80
+ ? `${styles.root} ${classNameProp}`
81
+ : styles.root;
82
+
83
+ return (
84
+ <Input.Label
85
+ ref={ref}
86
+ className={finalClass}
87
+ classNames={mergedClassNames}
88
+ data-layout={formLayout}
89
+ data-size={labelSize}
90
+ data-alignment={resolvedAlignment}
91
+ required={required && !labelWithEditIcon}
92
+ {...sanitizedProps}
93
+ >
94
+ <span className={styles.labelText}>{children}</span>
95
+ {resolvedOptionalText && (
96
+ <span className={styles.optionalText}>
97
+ {typeof resolvedOptionalText === "string"
98
+ ? `(${resolvedOptionalText})`
99
+ : resolvedOptionalText}
100
+ </span>
101
+ )}
102
+ {labelActionArea ? (
103
+ <span className={styles.actionAreaWrapper}>{labelActionArea}</span>
104
+ ) : labelWithEditIcon ? (
105
+ <button
106
+ type="button"
107
+ className={styles.editIconWrapper}
108
+ data-replaces-asterisk={required ? "true" : undefined}
109
+ onClick={onLabelEditClick}
110
+ aria-label="Edit"
111
+ >
112
+ <svg
113
+ width="16"
114
+ height="16"
115
+ viewBox="0 0 16 16"
116
+ fill="none"
117
+ xmlns="http://www.w3.org/2000/svg"
118
+ >
119
+ <path
120
+ d="M11.5303 2.46967C11.8232 2.17678 12.2981 2.17678 12.591 2.46967L13.5303 3.40898C13.8232 3.70188 13.8232 4.17675 13.5303 4.46964L5.61288 12.3871C5.45268 12.5473 5.24434 12.6483 5.01809 12.6766L2.39534 13.0044C2.10091 13.0412 1.83856 12.7789 1.87538 12.4845L2.2032 9.86175C2.23147 9.63551 2.3325 9.42716 2.4927 9.26696L11.5303 2.46967Z"
121
+ stroke="currentColor"
122
+ strokeLinecap="round"
123
+ strokeLinejoin="round"
124
+ />
125
+ </svg>
126
+ </button>
127
+ ) : null}
128
+ </Input.Label>
129
+ );
130
+ });
131
+
132
+ Label.displayName = "Label";
@@ -0,0 +1 @@
1
+ export * from "./Label";