feat(many): add margin prop

Author: git-nandor

CHECKBOX_MARGIN_SOLUTION.md

@@ -0,0 +1,232 @@
+# Checkbox Margin Prop - Solution Using mapSpacingToShorthand
+
+## Problem
+
+The Checkbox component's `margin` prop worked with theme values like `"large"` but NOT with custom CSS values like `"40px"`.
+
+## Root Cause
+
+The Checkbox was using the `View` component wrapper, which calls `getShorthandPropValue()` without the `matchCSSUnits` parameter. This function requires an explicit flag to accept custom CSS units.
+
+## Why CheckboxGroup Worked
+
+CheckboxGroup → FormFieldGroup → FormFieldLayout uses `mapSpacingToShorthand()` instead, which is more permissive:
+
+```typescript
+// mapSpacingToShorthand - more permissive
+splitMargin.map((m: string) => spacingMap[m] || m)
+//                              ^^^^^^^^^^^^^^
+// Returns original value if not found in theme!
+```
+
+## Solution
+
+Instead of modifying the View component (which would affect the entire system), we:
+
+1. **Removed the View wrapper** from Checkbox
+2. **Used `mapSpacingToShorthand` directly** in the render method
+3. **Applied margin as inline style** to the root div
+
+## Implementation
+
+### Files Changed
+
+#### 1. packages/ui-checkbox/src/Checkbox/index.tsx
+
+**Import added:**
+
+```typescript
+import { withStyle, mapSpacingToShorthand } from '@instructure/emotion'
+```
+
+**Render method updated:**
+
+```typescript
+render() {
+  const { margin, /* ...other props */ } = this.props
+
+  // Calculate margin using mapSpacingToShorthand
+  const cssMargin = margin
+    ? mapSpacingToShorthand(margin, this.theme?.spacing || {})
+    : undefined
+
+  return (
+    <div
+      css={styles?.checkbox}
+      style={{ margin: cssMargin }}  // Apply inline
+      // ... rest of props
+    >
+      {/* children */}
+    </div>
+  )
+}
+```
+
+#### 2. packages/ui-checkbox/src/Checkbox/styles.ts
+
+**Import added:**
+
+```typescript
+import { mapSpacingToShorthand } from '@instructure/emotion'
+```
+
+**generateStyle updated:**
+
+```typescript
+const generateStyle = (
+  componentTheme: ComponentTheme,
+  props: CheckboxProps
+): CheckboxStyle => {
+  const { inline, disabled, margin } = props // Added margin
+  // ... rest of function
+}
+```
+
+#### 3. packages/ui-view/src/View/styles.ts
+
+**Reverted changes** - removed `matchCSSUnits: true` parameters to keep View unchanged.
+
+## How It Works
+
+### With Theme Values
+
+```tsx
+<Checkbox label="Test" value="1" margin="large" />
+```
+
+1. `mapSpacingToShorthand("large", theme.spacing)`
+2. Looks up `large` in `theme.spacing`
+3. Finds `"1.5rem"` (or whatever the theme defines)
+4. Returns `"1.5rem"`
+5. Applied as `style={{ margin: "1.5rem" }}`
+
+### With Custom CSS Values
+
+```tsx
+<Checkbox label="Test" value="1" margin="40px" />
+```
+
+1. `mapSpacingToShorthand("40px", theme.spacing)`
+2. Looks up `40px` in `theme.spacing`
+3. **NOT FOUND** - returns original value `"40px"`
+4. Returns `"40px"`
+5. Applied as `style={{ margin: "40px" }}`
+
+### With Multiple Values
+
+```tsx
+<Checkbox label="Test" value="1" margin="large 40px" />
+```
+
+1. Splits into `["large", "40px"]`
+2. Maps each:
+   - `"large"` → theme value → `"1.5rem"`
+   - `"40px"` → not in theme → `"40px"`
+3. Joins back → `"1.5rem 40px"`
+4. Applied as `style={{ margin: "1.5rem 40px" }}`
+
+## Testing
+
+```bash
+# Rebuild the package
+npm run build
+
+# Or watch mode
+npm run build:watch
+```
+
+### Test Cases
+
+```tsx
+import { Checkbox } from '@instructure/ui-checkbox'
+
+function TestCheckboxMargin() {
+  return (
+    <div style={{ border: '1px solid red', padding: '20px' }}>
+      {/* Theme value */}
+      <Checkbox label="margin='large'" value="1" margin="large" />
+
+      {/* Custom pixel value */}
+      <Checkbox label="margin='40px'" value="2" margin="40px" />
+
+      {/* Custom rem value */}
+      <Checkbox label="margin='2rem'" value="3" margin="2rem" />
+
+      {/* Mixed values */}
+      <Checkbox label="margin='large 40px'" value="4" margin="large 40px" />
+
+      {/* Shorthand */}
+      <Checkbox label="margin='10px 20px'" value="5" margin="10px 20px" />
+
+      {/* All four sides */}
+      <Checkbox
+        label="margin='5px 10px 15px 20px'"
+        value="6"
+        margin="5px 10px 15px 20px"
+      />
+    </div>
+  )
+}
+```
+
+## Advantages of This Approach
+
+✅ **No system-wide changes** - View component remains unchanged
+✅ **Consistent with FormFieldLayout** - Uses same `mapSpacingToShorthand` function
+✅ **Supports both theme and custom values** - Automatic fallback behavior
+✅ **Simple implementation** - Just inline styles, no complex wrapper logic
+✅ **Type-safe** - Uses existing `Spacing` type
+
+## Apply to Other Components
+
+This same pattern should be applied to:
+
+- RadioInput
+- RangeInput
+- Text (if not already using View properly)
+- ToggleButton
+- Any other individual form controls
+
+### Template for Other Components:
+
+```typescript
+// 1. Import mapSpacingToShorthand
+import { mapSpacingToShorthand } from '@instructure/emotion'
+
+// 2. In render method
+render() {
+  const { margin } = this.props
+
+  const cssMargin = margin
+    ? mapSpacingToShorthand(margin, this.theme?.spacing || {})
+    : undefined
+
+  return (
+    <div
+      css={styles?.rootElement}
+      style={{ margin: cssMargin }}
+      // ... rest of props
+    >
+      {/* children */}
+    </div>
+  )
+}
+```
+
+## Summary
+
+**Before:**
+
+- Checkbox wrapped with View → used `getShorthandPropValue` → required `matchCSSUnits: true` → didn't work with custom values
+
+**After:**
+
+- Checkbox uses `mapSpacingToShorthand` directly → permissive fallback → works with both theme and custom values ✅
+
+**Result:**
+
+```tsx
+// Both work now!
+<Checkbox label="Theme" value="1" margin="large" />   // ✅ Works
+<Checkbox label="Custom" value="2" margin="40px" />   // ✅ Works
+```