@ornikar/bumper 3.7.0 → 3.7.1

package/CHANGELOG.md

@@ -3,6 +3,14 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [3.7.1](https://github.com/ornikar/kitt/compare/@ornikar/bumper@3.7.0...@ornikar/bumper@3.7.1) (2026-03-23)
+
+**Note:** Version bump only for package @ornikar/bumper
+
+
+
+
+
 ## [3.7.0](https://github.com/ornikar/kitt/compare/@ornikar/bumper@3.6.2...@ornikar/bumper@3.7.0) (2026-03-17)
 
 

package/docs/migration/Button.md

@@ -0,0 +1,502 @@
+# Button → Button Migration Guide
+
+> Source: `@ornikar/kitt-universal/Button`
+> Target: `@ornikar/bumper/Button`
+> Generated: 2026-03-20
+
+## Import Change
+
+```tsx
+// Before
+import { Button } from '@ornikar/kitt-universal';
+import type { ButtonProps } from '@ornikar/kitt-universal';
+
+// After
+import { Button } from '@ornikar/bumper';
+import type { ButtonProps } from '@ornikar/bumper';
+```
+
+Also remove any `LoaderIcon` import used solely for Button loading patterns — bumper has a native `isLoading` prop.
+
+## Props Mapping
+
+| Source Prop                                                             | Target Prop                             | Transform                              | Notes                                                             |
+| ----------------------------------------------------------------------- | --------------------------------------- | -------------------------------------- | ----------------------------------------------------------------- |
+| `children` (direct)                                                     | `<Button.Text>{children}</Button.Text>` | Wrap in compound component             | See [Children & Composition](#children--composition)              |
+| `type="primary"`                                                        | `type="primary"`                        | Keep as-is                             | Same value                                                        |
+| `type="secondary"`                                                      | `type="secondary"`                      | Keep as-is                             | Same value (also the default)                                     |
+| `type="tertiary"`                                                       | `type="tertiary"`                       | Keep as-is                             | Same value                                                        |
+| `type="tertiary-danger"`                                                | `type="danger"`                         | Rename value                           | Not used in learner-apps                                          |
+| `variant="default"`                                                     | —                                       | Remove prop                            | Default behavior, no equivalent needed                            |
+| `variant="revert"`                                                      | `isOnContrasted`                        | Replace prop + value with boolean prop | See [Variant Mapping](#variant-mapping)                           |
+| `size="default"`                                                        | —                                       | Remove prop                            | Maps to `large` which is the default                              |
+| `size="medium"`                                                         | —                                       | Remove prop                            | Maps to `large` which is the default                              |
+| `disabled`                                                              | `disabled`                              | Keep as-is                             | Same API                                                          |
+| `stretch` (boolean)                                                     | `stretch`                               | Keep as-is                             | Same API when static boolean                                      |
+| `stretch` (responsive object)                                           | `stretch` + `$medium`/`$small`/etc.     | Convert responsive syntax              | See [Responsive Stretch](#responsive-stretch)                     |
+| `icon={<Icon />}`                                                       | `<Button.Icon icon={<Icon />} />`       | Convert prop to compound child         | See [Icon Migration](#icon-migration)                             |
+| `iconPosition="left"`                                                   | —                                       | Remove prop                            | Icon position determined by child order (Icon before Text = left) |
+| `iconPosition="right"`                                                  | —                                       | Remove prop                            | Place `Button.Icon` after `Button.Text`                           |
+| `icon={isLoading ? <LoaderIcon /> : <Icon />}` + `disabled={isLoading}` | `isLoading`                             | Replace pattern with single prop       | See [Loading Pattern](#loading-pattern)                           |
+| `withBadge`                                                             | `<Button.Badge />`                      | Convert prop to compound child         | Not used in learner-apps                                          |
+| `badgeCount={n}`                                                        | `<Button.Badge count={n} />`            | Convert prop to compound child         | Not used in learner-apps                                          |
+| `timerAttrs`                                                            | —                                       | **Not migratable**                     | No bumper equivalent. Requires manual review                      |
+| `testID`                                                                | `testID`                                | Keep as-is                             | Same API                                                          |
+| `onPress`                                                               | `onPress`                               | Keep as-is                             | Same API                                                          |
+| `onFocus`                                                               | —                                       | Remove prop                            | Not exposed in bumper ButtonProps                                 |
+| `onBlur`                                                                | —                                       | Remove prop                            | Not exposed in bumper ButtonProps                                 |
+| `onHoverIn`                                                             | —                                       | Remove prop                            | Not exposed in bumper ButtonProps                                 |
+| `onHoverOut`                                                            | —                                       | Remove prop                            | Not exposed in bumper ButtonProps                                 |
+| `href`                                                                  | —                                       | Remove prop                            | Not used in learner-apps. Navigation uses InternalLink wrappers   |
+| `hrefAttrs`                                                             | —                                       | Remove prop                            | Not used in learner-apps                                          |
+| `accessibilityRole`                                                     | —                                       | Remove prop                            | Bumper sets `role="button"` automatically                         |
+| `innerSpacing`                                                          | —                                       | Remove prop                            | Not used in learner-apps                                          |
+| `style`                                                                 | —                                       | Remove prop                            | Not supported. Use Tamagui style props if needed                  |
+| `isHoveredInternal`                                                     | —                                       | Remove prop                            | Internal/storybook only                                           |
+| `isPressedInternal`                                                     | —                                       | Remove prop                            | Internal/storybook only                                           |
+| `isFocusedInternal`                                                     | —                                       | Remove prop                            | Internal/storybook only                                           |
+
+## Value Mappings
+
+### Type Values
+
+```
+primary         → primary
+secondary       → secondary       (default in both)
+tertiary        → tertiary
+tertiary-danger → danger           (not used in learner-apps)
+```
+
+### Size Values
+
+All sizes map to `large` (the default), so remove the `size` prop entirely:
+
+```
+default → (remove prop)   — large is the default
+medium  → (remove prop)   — large is the default
+```
+
+### Variant Mapping
+
+```
+variant="default" → (remove prop entirely)
+variant="revert"  → isOnContrasted
+```
+
+When `variant="revert"` also remove the `variant` prop itself:
+
+```tsx
+// Before
+<Button type="primary" variant="revert" onPress={onClose}>
+
+// After
+<Button type="primary" isOnContrasted onPress={onClose}>
+```
+
+## Children & Composition
+
+The biggest change: bumper Button uses a **compound component pattern**. All text children must be wrapped in `Button.Text`.
+
+### Basic text children
+
+```tsx
+// Before
+<Button type="primary" onPress={onPress}>
+  <FormattedMessage defaultMessage="Continue" />
+</Button>
+
+// After
+<Button type="primary" onPress={onPress}>
+  <Button.Text>
+    <FormattedMessage defaultMessage="Continue" />
+  </Button.Text>
+</Button>
+```
+
+### Multiple children / mixed content
+
+If the source Button has multiple children (e.g., text nodes), wrap them all in a single `Button.Text`:
+
+```tsx
+// Before
+<Button type="primary" onPress={onPress}>
+  {label}
+</Button>
+
+// After
+<Button type="primary" onPress={onPress}>
+  <Button.Text>{label}</Button.Text>
+</Button>
+```
+
+### Icon-only button (no text children)
+
+If the source Button has only an `icon` prop and no `children`, use only `Button.Icon`:
+
+```tsx
+// Before
+<Button icon={<ReplayIcon />} type="primary" onPress={onReplay} />
+
+// After
+<Button type="primary" onPress={onReplay}>
+  <Button.Icon icon={<ReplayIcon />} />
+</Button>
+```
+
+**Note**: Consider migrating icon-only buttons to `IconButton` from bumper instead, depending on design intent.
+
+## Icon Migration
+
+### Icon with text (left position — default)
+
+```tsx
+// Before
+<Button type="primary" icon={<ArrowRightIcon />} onPress={onNext}>
+  <FormattedMessage defaultMessage="Next" />
+</Button>
+
+// After
+<Button type="primary" onPress={onNext}>
+  <Button.Icon icon={<ArrowRightIcon />} />
+  <Button.Text>
+    <FormattedMessage defaultMessage="Next" />
+  </Button.Text>
+</Button>
+```
+
+### Icon with text (right position)
+
+Place `Button.Icon` **after** `Button.Text`:
+
+```tsx
+// Before
+<Button icon={<ArrowRightIcon />} iconPosition="right" onPress={onNext}>
+  <FormattedMessage defaultMessage="Next" />
+</Button>
+
+// After
+<Button onPress={onNext}>
+  <Button.Text>
+    <FormattedMessage defaultMessage="Next" />
+  </Button.Text>
+  <Button.Icon icon={<ArrowRightIcon />} />
+</Button>
+```
+
+## Loading Pattern
+
+The pervasive `LoaderIcon` + `disabled` pattern in kitt-universal maps to bumper's native `isLoading` prop:
+
+```tsx
+// Before
+<Button
+  type="primary"
+  icon={isLoading ? <LoaderIcon /> : <ArrowRightIcon />}
+  disabled={isLoading}
+  onPress={handleSubmit}
+>
+  <FormattedMessage defaultMessage="Submit" />
+</Button>
+
+// After
+<Button type="primary" isLoading={isLoading} onPress={handleSubmit}>
+  <Button.Icon icon={<ArrowRightIcon />} />
+  <Button.Text>
+    <FormattedMessage defaultMessage="Submit" />
+  </Button.Text>
+</Button>
+```
+
+**Important**: When `isLoading` is true, bumper hides all children (with `opacity: 0`) and shows a centered spinner. The button preserves its original dimensions. There is no need to conditionally swap icon elements.
+
+If the source only uses `LoaderIcon` without a fallback icon (icon-only loading):
+
+```tsx
+// Before
+<Button icon={isLoading ? <LoaderIcon /> : undefined} disabled={isLoading} onPress={onPress}>
+  <FormattedMessage defaultMessage="Action" />
+</Button>
+
+// After
+<Button isLoading={isLoading} onPress={onPress}>
+  <Button.Text>
+    <FormattedMessage defaultMessage="Action" />
+  </Button.Text>
+</Button>
+```
+
+If `disabled` is used for reasons **beyond** loading (e.g., form validation), keep it alongside `isLoading`:
+
+```tsx
+// Before
+<Button
+  disabled={isLoading || !isFormValid}
+  icon={isLoading ? <LoaderIcon /> : <CheckIcon />}
+  onPress={onSubmit}
+>
+  Submit
+</Button>
+
+// After
+<Button
+  isLoading={isLoading}
+  disabled={!isFormValid}
+  onPress={onSubmit}
+>
+  <Button.Icon icon={<CheckIcon />} />
+  <Button.Text>Submit</Button.Text>
+</Button>
+```
+
+## Responsive Stretch
+
+kitt-universal uses `ResponsiveValue<boolean>` objects. Bumper uses Tamagui media query props.
+
+### Breakpoint name mapping
+
+```
+base   → (base prop, no prefix)
+small  → $small
+medium → $medium
+large  → $large
+```
+
+### Conversion rules
+
+The base value becomes the direct prop. Override values become media query props.
+
+```tsx
+// Before: stretch={{ base: true, small: false }}
+// After:
+<Button stretch $small={{ stretch: false }}>
+
+// Before: stretch={{ base: true, large: false }}
+// After:
+<Button stretch $large={{ stretch: false }}>
+
+// Before: stretch={{ base: true, medium: false }}
+// After:
+<Button stretch $medium={{ stretch: false }}>
+
+// Before: stretch={true}
+// After:
+<Button stretch>
+
+// Before: stretch={false} or stretch={undefined}
+// After:
+// (remove the prop entirely)
+```
+
+### Dynamic responsive values
+
+If `stretch` receives a variable (not an object literal), it cannot be mechanically converted. Flag for manual review:
+
+```tsx
+// Before
+<Button stretch={responsiveStretch} onPress={onPress}>
+
+// After — MANUAL REVIEW NEEDED
+// Must convert ResponsiveValue<boolean> to Tamagui media query props
+```
+
+## Behavioral Differences
+
+| Aspect                        | kitt-universal                                | bumper                                        |
+| ----------------------------- | --------------------------------------------- | --------------------------------------------- | ----------------------------------------------- |
+| **Default type**              | `secondary`                                   | `secondary`                                   | Same                                            |
+| **Default size**              | `default` (40px min-height)                   | `large` (48px)                                | Slightly larger                                 |
+| **Border radius**             | 4px                                           | `$radius.m` token                             | May differ visually                             |
+| **Focus ring**                | 3px purple border via `FocusBorder` component | 3px outline via `outlineColor: $border.focus` | Similar but implemented differently             |
+| **Loading**                   | No built-in loading                           | `isLoading` prop with spinner                 | New capability                                  |
+| **Animation**                 | `react-native-reanimated` spring animations   | Tamagui built-in transitions                  | Different animation library                     |
+| **Gap between icon and text** | Theme-dependent spacing                       | Fixed `$space.8` (8px) gap                    | May differ slightly                             |
+| **Icon sizing**               | Size depends on button size (20px/24px)       | Fixed `$icon.m`                               | Consistent across sizes                         |
+| **Children required**         | Either `children` or `icon` required          | `children` is required                        | Must always have children (compound components) |
+
+## Edge Cases
+
+### Conditional type values
+
+Map each possible value:
+
+```tsx
+// Before
+<Button type={isPrimary ? "primary" : "tertiary"} onPress={onPress}>
+
+// After
+<Button type={isPrimary ? "primary" : "tertiary"} onPress={onPress}>
+// Same — these values map 1:1
+```
+
+### Conditional variant
+
+```tsx
+// Before
+<Button variant={isContrasted ? "revert" : "default"} onPress={onPress}>
+
+// After
+<Button isOnContrasted={isContrasted} onPress={onPress}>
+```
+
+### Spread props from ButtonProps
+
+If components spread ButtonProps, filter out removed props:
+
+```tsx
+// Before
+const { timerAttrs, icon, iconPosition, variant, size, ...rest } = buttonProps;
+
+// After — remap relevant props
+const {
+  timerAttrs,
+  icon,
+  iconPosition,
+  variant,
+  size,
+  onFocus,
+  onBlur,
+  onHoverIn,
+  onHoverOut,
+  style,
+  href,
+  hrefAttrs,
+  accessibilityRole,
+  innerSpacing,
+  withBadge,
+  badgeCount,
+  ...rest
+} = buttonProps;
+<Button {...rest} isOnContrasted={variant === 'revert'}>
+  {icon && <Button.Icon icon={icon} />}
+  {children && <Button.Text>{children}</Button.Text>}
+</Button>;
+```
+
+### Wrapper / re-export migration
+
+Components that extend or pick from `ButtonProps` need type updates:
+
+```tsx
+// Before
+import type { ButtonProps } from '@ornikar/kitt-universal';
+interface MyButtonProps extends Pick<ButtonProps, 'stretch' | 'type'> { ... }
+
+// After
+import type { ButtonProps } from '@ornikar/bumper';
+interface MyButtonProps extends Pick<ButtonProps, 'stretch' | 'type'> { ... }
+// stretch and type exist in both — no further changes needed
+```
+
+For wrappers that pick `icon`, `variant`, or `size`:
+
+```tsx
+// Before
+interface MyProps extends Pick<ButtonProps, 'icon' | 'variant' | 'size'> { ... }
+
+// After — these props no longer exist on ButtonProps
+// icon → render Button.Icon in the component body
+// variant → replace with isOnContrasted
+// size → remove (always large)
+interface MyProps {
+  icon?: ReactNode;
+  isOnContrasted?: boolean;
+}
+```
+
+### ActionButton wrapper (native)
+
+The `ActionButton` wrapper that auto-shows `LoaderIcon` during async `onPress` can be simplified:
+
+```tsx
+// Before (ActionButton pattern)
+<ActionButton type="primary" icon={<ArrowRightIcon />} onPress={asyncHandler}>
+  <FormattedMessage defaultMessage="Submit" />
+</ActionButton>;
+
+// After — use isLoading directly
+const [isLoading, setIsLoading] = useState(false);
+<Button type="primary" isLoading={isLoading} onPress={wrappedHandler}>
+  <Button.Icon icon={<ArrowRightIcon />} />
+  <Button.Text>
+    <FormattedMessage defaultMessage="Submit" />
+  </Button.Text>
+</Button>;
+```
+
+### InternalLink / InternalLinkButton wrappers
+
+These wrap Button for navigation. Update the Button props inside:
+
+```tsx
+// Before
+<InternalLink as={Button} to={route} type="tertiary" icon={<ArrowLeftIcon />}>
+  <FormattedMessage defaultMessage="Back" />
+</InternalLink>
+
+// After — Button props change but InternalLink pattern stays
+// NOTE: InternalLink's `as` prop may need updating if it expects specific ButtonProps shape.
+// Flag for manual review if the wrapper doesn't support compound children.
+```
+
+### Actions.Button usage
+
+`Actions.Button` from kitt-universal shares the same `ButtonProps` interface but lives inside the `Actions` compound component. These should be migrated **separately** as part of an `Actions` migration. Do not convert `Actions.Button` as part of this Button migration.
+
+## Migration Rules (machine-readable)
+
+Apply these rules in order for each `<Button>` usage:
+
+1. **Update import**: Replace `'@ornikar/kitt-universal'` with `'@ornikar/bumper'` for `Button` and `ButtonProps` imports. Remove `LoaderIcon` import if only used for Button loading patterns.
+
+2. **Remove `size` prop**: Delete any `size="default"` or `size="medium"` — bumper defaults to `large`.
+
+3. **Convert `variant`**:
+
+   - If `variant="default"` → remove the prop
+   - If `variant="revert"` → replace with `isOnContrasted`
+   - If `variant={expr}` → replace with `isOnContrasted={expr === 'revert'}`
+
+4. **Convert `type` values**:
+
+   - `"tertiary-danger"` → `"danger"`
+   - All others unchanged
+
+5. **Convert `stretch` responsive syntax**:
+
+   - If `stretch={true}` or `stretch` → keep as `stretch`
+   - If `stretch={{ base: X, breakpoint: Y }}` → convert base to prop, breakpoints to `$breakpoint={{ stretch: Y }}`
+   - If `stretch={variable}` → flag for manual review
+
+6. **Detect loading pattern**: If the JSX contains `icon={condition ? <LoaderIcon /> : <OtherIcon />}` paired with `disabled={sameCondition}`:
+
+   - Add `isLoading={condition}` prop
+   - Remove the `LoaderIcon` conditional from icon
+   - Remove `disabled={condition}` (keep `disabled` if it has additional conditions)
+   - Move the non-LoaderIcon icon to `<Button.Icon icon={...} />`
+
+7. **Convert `icon` prop to compound child**:
+
+   - Remove `icon` prop from `<Button>`
+   - If `iconPosition="right"` or `iconPosition` is absent/`"left"` → determines child order
+   - Add `<Button.Icon icon={iconValue} />` as child (before `Button.Text` for left, after for right)
+   - Remove `iconPosition` prop
+
+8. **Wrap text children in `Button.Text`**:
+
+   - Take all remaining children of `<Button>` (text, `<FormattedMessage>`, expressions)
+   - Wrap them in `<Button.Text>...</Button.Text>`
+   - If Button had no `children` (icon-only), skip this step
+
+9. **Remove unsupported props**: Delete `onFocus`, `onBlur`, `onHoverIn`, `onHoverOut`, `href`, `hrefAttrs`, `accessibilityRole`, `innerSpacing`, `style`, `isHoveredInternal`, `isPressedInternal`, `isFocusedInternal`, `withBadge`, `badgeCount`.
+
+10. **Self-closing to explicit children**: If the source was a self-closing `<Button ... />`, convert to `<Button ...>...</Button>` with compound children inside.
+
+## Not Migratable (requires human review)
+
+- **`timerAttrs` prop** (1 usage in `AnswerSection`): No bumper equivalent. The timer/gauge overlay feature does not exist in bumper Button. This usage needs a custom solution or feature request.
+- **Dynamic `stretch` variables**: When `stretch` receives a runtime variable (not an object literal), ask the user on how to proceed.
+- **`InternalLink as={Button}` wrappers**: The `as` polymorphic pattern may not be compatible with bumper's compound children model. Each InternalLink/InternalLinkButton wrapper needs manual verification.
+- **`Actions.Button`**: Shares ButtonProps but lives in a different component tree. Migrate separately as part of Actions component migration.
+- **Icon-only buttons**: Don't do anything. Migrate separatly as part of the IconButton component migration.
+- **`style` prop usage**: Any custom styles passed via `style` prop need manual conversion to Tamagui style props.
+- **Components extending `ButtonProps`**: Proceed with the changes, only ask for user input if the linting is failing.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ornikar/bumper",
-  "version": "3.7.0",
+  "version": "3.7.1",
   "license": "MIT",
   "repository": {
     "directory": "@ornikar/bumper",