@ornikar/bumper 3.13.0 → 3.14.0

package/docs/migration/Avatar.md

@@ -0,0 +1,228 @@
+# Avatar → Avatar Migration Guide
+
+> Source: `@ornikar/kitt-universal/Avatar`
+> Target: `@ornikar/bumper/Avatar`
+> Generated: 2026-04-27
+
+## Import Change
+
+```tsx
+// Before
+import { Avatar } from '@ornikar/kitt-universal';
+import type { AvatarProps } from '@ornikar/kitt-universal';
+
+// After
+import { Avatar } from '@ornikar/bumper';
+import type { AvatarProps } from '@ornikar/bumper';
+```
+
+## Props Mapping
+
+| Source Prop                    | Target Prop            | Transform                     | Notes                                         |
+| ------------------------------ | ---------------------- | ----------------------------- | --------------------------------------------- |
+| `src`                          | `src`                  | Keep as-is                    | Same API                                      |
+| `firstname` (`string \| null`) | `firstname` (`string`) | Narrow `null` to `undefined`  | See [Null Name Handling](#null-name-handling) |
+| `lastname` (`string \| null`)  | `lastname` (`string`)  | Narrow `null` to `undefined`  | See [Null Name Handling](#null-name-handling) |
+| `disabled`                     | `disabled`             | Keep as-is                    | Same API                                      |
+| `width`                        | `width`                | Keep as-is                    | Used only when `size` is omitted              |
+| `height`                       | `height`               | Keep as-is                    | Used only when `size` is omitted              |
+| `size` (`number`)              | `size` (enum)          | Map number to nearest bucket  | See [Size Values](#size-values)               |
+| `round` (`boolean`)            | `shape` (enum)         | Convert boolean to enum value | See [Shape Mapping](#shape-mapping)           |
+| `alt`                          | —                      | Remove prop                   | Not exposed in bumper AvatarProps             |
+| `light`                        | —                      | Remove prop                   | No light/dark theme variant in bumper         |
+| `dark`                         | —                      | Remove prop                   | No light/dark theme variant in bumper         |
+| `sizeVariant`                  | —                      | Remove prop                   | Only ever `'large'`; merged into `size` enum  |
+
+Bumper adds new props with no kitt-universal equivalent:
+
+- `testID` — testing hook, optional
+- `shape` — explicit replacement for the `round` boolean
+
+## Value Mappings
+
+### Size Values
+
+Bumper sizes map to fixed pixel dimensions (square):
+
+```
+small  → 32×32
+medium → 40×40
+large  → 48×48   (default)
+xlarge → 64×64
+```
+
+Map a numeric `size` to the closest enum bucket:
+
+```
+size={32} → size="small"
+size={40} → size="medium"
+size={48} → (remove prop — large is the default)
+size={64} → size="xlarge"
+```
+
+For numeric values that do **not** match a bucket exactly, prefer preserving the literal pixel value via `width`/`height` to avoid silent visual regressions:
+
+```tsx
+// Before
+<Avatar size={36} firstname="Jane" />
+
+// After
+<Avatar width={36} height={36} firstname="Jane" />
+```
+
+For dynamic numeric values (`size={someNumber}`), flag for manual review.
+
+### Shape Mapping
+
+```
+round              → shape="circle"   (boolean shorthand)
+round={true}       → shape="circle"
+round={false}      → (remove prop — square is the default)
+round={expr}       → shape={expr ? 'circle' : 'square'}
+```
+
+### sizeVariant Mapping
+
+`sizeVariant` only accepted `'large'` and was redundant with `size`. Always remove it:
+
+```
+sizeVariant="large" → (remove prop entirely)
+```
+
+## Null Name Handling
+
+Bumper's `firstname` and `lastname` are `string | undefined`, not `string | null`. Convert literal `null` to an omitted prop, and runtime nullable values via `?? undefined`:
+
+```tsx
+// Before
+<Avatar firstname={null} lastname={null} />
+
+// After
+<Avatar />
+```
+
+```tsx
+// Before — user.firstname / user.lastname typed `string | null`
+<Avatar firstname={user.firstname} lastname={user.lastname} />
+
+// After
+<Avatar firstname={user.firstname ?? undefined} lastname={user.lastname ?? undefined} />
+```
+
+When both names resolve to falsy and no `src` is given, bumper falls back to the placeholder image automatically — same behavior as kitt-universal.
+
+## Behavioral Differences
+
+| Aspect                | kitt-universal               | bumper                                               | Notes                                   |
+| --------------------- | ---------------------------- | ---------------------------------------------------- | --------------------------------------- |
+| **Default shape**     | square (`round=false`)       | `square`                                             | Same                                    |
+| **Default size**      | implicit (no enum)           | `large` (48×48)                                      | Bumper enforces an explicit default     |
+| **Theme variants**    | `light` / `dark` props       | none                                                 | Removed; rely on surrounding theme      |
+| **Image alt text**    | `alt` prop                   | none                                                 | No accessibility alt at component level |
+| **Border radius**     | hardcoded                    | `$radius.m` (square) / `$radius.circle` (circle)     | Token-based, may differ visually        |
+| **Disabled state**    | swap to disabled placeholder | swap to disabled placeholder + `$bg.disabled.hi` bg  | Similar, with explicit token background |
+| **Initials fallback** | `firstname` + `lastname`     | `firstname` + `lastname`                             | Same                                    |
+| **Responsive props**  | not supported                | Tamagui media query props (`$small`, `$medium`, ...) | New capability                          |
+
+## Edge Cases
+
+### Conditional `round`
+
+```tsx
+// Before
+<Avatar round={isCircle} firstname="Jane" />
+
+// After
+<Avatar shape={isCircle ? 'circle' : 'square'} firstname="Jane" />
+```
+
+### Spread props from AvatarProps
+
+If components spread `AvatarProps`, destructure the removed props out and convert `round`:
+
+```tsx
+// Before
+const { alt, light, dark, sizeVariant, ...rest } = avatarProps;
+<Avatar {...rest} />;
+
+// After
+const { alt, light, dark, sizeVariant, round, ...rest } = avatarProps;
+<Avatar {...rest} shape={round ? 'circle' : 'square'} />;
+```
+
+### Wrapper / re-export migration
+
+Components that pick or extend `AvatarProps` need type updates:
+
+```tsx
+// Before
+import type { AvatarProps } from '@ornikar/kitt-universal';
+interface MyAvatarProps extends Pick<AvatarProps, 'src' | 'firstname' | 'lastname'> { ... }
+
+// After
+import type { AvatarProps } from '@ornikar/bumper';
+interface MyAvatarProps extends Pick<AvatarProps, 'src' | 'firstname' | 'lastname'> { ... }
+// firstname / lastname narrow from `string | null` to `string` — update callers if any pass null
+```
+
+For wrappers that pick removed props (`alt`, `light`, `dark`, `sizeVariant`, `round`):
+
+```tsx
+// Before
+interface MyProps extends Pick<AvatarProps, 'round' | 'alt'> { ... }
+
+// After — these props no longer exist on AvatarProps
+// round → expose `shape` instead
+// alt   → drop, or expose only if the wrapper handles it itself
+interface MyProps {
+  shape?: 'square' | 'circle';
+}
+```
+
+### Numeric `size` matching the default
+
+When the source explicitly sets `size={48}`, prefer removing the prop entirely over emitting `size="large"` — it is the default and reduces churn:
+
+```tsx
+// Before
+<Avatar size={48} firstname="Jane" />
+
+// After
+<Avatar firstname="Jane" />
+```
+
+## Migration Rules (machine-readable)
+
+Apply these rules in order for each `<Avatar>` usage:
+
+1. **Update import**: Replace `'@ornikar/kitt-universal'` with `'@ornikar/bumper'` for `Avatar` and `AvatarProps` imports.
+
+2. **Remove unsupported props**: Delete `alt`, `light`, `dark`, `sizeVariant`.
+
+3. **Convert `round`**:
+
+   - `round={true}` or bare `round` → `shape="circle"`
+   - `round={false}` → remove the prop
+   - `round={expr}` → `shape={expr ? 'circle' : 'square'}`
+
+4. **Convert `size`** (numeric literal):
+
+   - `size={32}` → `size="small"`
+   - `size={40}` → `size="medium"`
+   - `size={48}` → remove the prop (`large` is the default)
+   - `size={64}` → `size="xlarge"`
+   - Any other literal → replace with `width={n} height={n}` and remove `size`
+   - Variable / expression → flag for manual review
+
+5. **Narrow nullable names**:
+   - `firstname={null}` literal → remove prop
+   - `lastname={null}` literal → remove prop
+   - `firstname={value}` where `value` is typed `string | null` → `firstname={value ?? undefined}`
+   - Same for `lastname`
+
+## Not Migratable (requires human review)
+
+- **Dynamic numeric `size`**: When `size` receives a runtime variable (not a literal), the bucket cannot be inferred mechanically. Ask the user how to proceed, or fall back to `width`/`height` if the original value is preserved.
+- **`alt` prop usage**: If the call site relies on `alt` for accessibility, decide whether to wrap the Avatar in an aria-labeled element or accept the regression.
+- **`light` / `dark` props**: If the call site visibly depends on the inverted palette, the surrounding theme context may need to change. Review with design before stripping silently.
+- **Components extending `AvatarProps`**: 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.13.0",
+  "version": "3.14.0",
   "license": "MIT",
   "repository": {
     "directory": "@ornikar/bumper",

package/src/Bumper.mdx

@@ -34,6 +34,7 @@ spacing, color, radius, and typography.
 
 ## Data Displays
 
+- [Avatar](?path=/docs/bumper-data-displays-avatar--docs) — User representation with image, initials, or placeholder fallback.
 - [Badge](?path=/docs/bumper-data-displays-badge--docs) — Numeric count or dot indicator.
 
 ## Loading

package/src/index.ts

@@ -27,6 +27,8 @@ export type { TypographyIconProps } from './system/content/typography/Typography
 export type { TypographyLinkProps } from './system/content/typography/TypographyLink';
 
 // Data Displays
+export type { AvatarProps } from './system/dataDisplays/Avatar/Avatar';
+export { Avatar } from './system/dataDisplays/Avatar/Avatar';
 export type { BadgeProps } from './system/dataDisplays/Badge/Badge';
 export { Badge } from './system/dataDisplays/Badge/Badge';
 export { Sticker } from './system/dataDisplays/Sticker/Sticker';

package/src/system/core/themes/light/__snapshots__/light.stories.tsx.snap

@@ -5902,6 +5902,79 @@ exports[`Bumper/Core/Themes Light 1`] = `
           #FDE4E3
         </Text>
       </View>
+      <View
+        style={
+          {
+            "alignItems": "center",
+            "flexDirection": "row",
+            "gap": 16,
+          }
+        }
+      >
+        <View
+          style={
+            {
+              "alignItems": "center",
+              "backgroundColor": "#EAE3D6",
+              "borderBottomColor": "#F1ECE4",
+              "borderBottomLeftRadius": 4,
+              "borderBottomRightRadius": 4,
+              "borderBottomWidth": 1,
+              "borderLeftColor": "#F1ECE4",
+              "borderLeftWidth": 1,
+              "borderRightColor": "#F1ECE4",
+              "borderRightWidth": 1,
+              "borderStyle": "solid",
+              "borderTopColor": "#F1ECE4",
+              "borderTopLeftRadius": 4,
+              "borderTopRightRadius": 4,
+              "borderTopWidth": 1,
+              "height": 48,
+              "justifyContent": "center",
+              "width": 48,
+            }
+          }
+        />
+        <View
+          style={
+            {
+              "width": 280,
+            }
+          }
+        >
+          <Text
+            style={
+              {
+                "color": "#101010",
+                "fontFamily": "GTStandardBold",
+                "fontSize": 14,
+                "letterSpacing": 0.3,
+                "lineHeight": 20,
+                "textAlign": "left",
+              }
+            }
+            suppressHighlighting={true}
+          >
+            $
+            avatar.bg
+          </Text>
+        </View>
+        <Text
+          style={
+            {
+              "color": "#505050",
+              "fontFamily": "GTStandardRegular",
+              "fontSize": 14,
+              "letterSpacing": 0.3,
+              "lineHeight": 20,
+              "textAlign": "left",
+            }
+          }
+          suppressHighlighting={true}
+        >
+          #EAE3D6
+        </Text>
+      </View>
     </View>
   </View>
 </RNCSafeAreaProvider>

package/src/system/core/themes/light/__snapshots_web__/light.stories.tsx.snap

@@ -1713,6 +1713,27 @@ exports[`Bumper/Core/Themes Light 1`] = `
                   #FDE4E3
                 </span>
               </div>
+              <div
+                class="is_HStack _dsp-flex _fb-auto _bxs-border-box _pos-relative _minHeight-0px _minWidth-0px _flexShrink-0 _fd-row _gap-t-space-spa1366020313 _alignItems-center"
+              >
+                <div
+                  class="_dsp-flex _fd-column _fb-auto _bxs-border-box _pos-relative _minHeight-0px _minWidth-0px _flexShrink-0 _width-t-size-size1385508 _height-t-size-size1385508 _btlr-t-radius-ra1673638410 _btrr-t-radius-ra1673638410 _bbrr-t-radius-ra1673638410 _bblr-t-radius-ra1673638410 _backgroundColor-EAE3D635 _btw-1px _brw-1px _borderBottomWidth-1px _borderLeftWidth-1px _btc-border--bas1360416657 _brc-border--bas1360416657 _borderBottomColor-border--bas1360416657 _borderLeftColor-border--bas1360416657 _alignItems-center _justifyContent-center _borderBottomStyle-solid _borderTopStyle-solid _borderLeftStyle-solid _borderRightStyle-solid"
+                />
+                <div
+                  class="_dsp-flex _alignItems-stretch _fd-column _fb-auto _bxs-border-box _pos-relative _minHeight-0px _minWidth-0px _flexShrink-0 _width-280px"
+                >
+                  <span
+                    class="font_GTStandard _WebkitFontSmoothing-_platformweb_antialiased _dsp-inline _bxs-border-box _ww-break-word _ws-pre-wrap _marginTop-0px _marginRight-0px _marginBottom-0px _marginLeft-0px _ff-f-family _fs-f-size-body1510 _lh-f-lineHeigh201793153 _ls-f-letterSpa1099960310 _fw-f-weight-bo3448 _col-content--ba907952141 _textAlign-left"
+                  >
+                    $avatar.bg
+                  </span>
+                </div>
+                <span
+                  class="font_GTStandard _WebkitFontSmoothing-_platformweb_antialiased _dsp-inline _bxs-border-box _ww-break-word _ws-pre-wrap _marginTop-0px _marginRight-0px _marginBottom-0px _marginLeft-0px _ff-f-family _fs-f-size-body1510 _lh-f-lineHeigh201793153 _ls-f-letterSpa1099960310 _fw-f-weight-re98715119 _textAlign-left _col-content--ba1918259606"
+                >
+                  #EAE3D6
+                </span>
+              </div>
             </div>
           </div>
         </span>

package/src/system/core/themes/light/light.ts

@@ -92,4 +92,7 @@ export const light: Theme = {
   'button.bg.danger.pressed': deepPurpleColorPalette['palette.red.1'],
   'button.bg.danger.onContrasted.default': deepPurpleColorPalette['palette.white'],
   'button.bg.danger.onContrasted.pressed': deepPurpleColorPalette['palette.red.1'],
+
+  // Avatar
+  'avatar.bg': deepPurpleColorPalette['palette.beige.3'],
 };

package/src/system/core/themes/types.ts

@@ -102,4 +102,8 @@ export const THEME_BUTTON = [
   'button.bg.danger.onContrasted.pressed',
 ] as const;
 
-export type Theme = ThemeContent & ThemeBackground & ThemeBorder & ThemeDivider & ThemeButton;
+export type ThemeAvatar = Record<(typeof THEME_AVATAR)[number], string>;
+
+export const THEME_AVATAR = ['avatar.bg'] as const;
+
+export type Theme = ThemeContent & ThemeBackground & ThemeBorder & ThemeDivider & ThemeButton & ThemeAvatar;

package/src/system/dataDisplays/Avatar/Avatar.features.stories.tsx

@@ -0,0 +1,110 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { HStack, VStack } from '../../core/primitives/Stack';
+import { Avatar } from './Avatar';
+
+const meta: Meta<typeof Avatar> = {
+  title: 'Bumper/Data Displays/Avatar/Features',
+  component: Avatar,
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Placeholder: Story = {
+  args: {
+    size: 'large',
+    shape: 'square',
+  },
+};
+
+export const WithInitials: Story = {
+  args: {
+    size: 'large',
+    shape: 'square',
+    firstname: 'John',
+    lastname: 'Doe',
+  },
+};
+
+export const WithImage: Story = {
+  args: {
+    size: 'large',
+    shape: 'square',
+    src: 'https://i.pravatar.cc/150?img=5',
+  },
+};
+
+export const Sizes: Story = {
+  render: () => (
+    <HStack gap="$space.16" alignItems="center">
+      <Avatar size="small" shape="square" firstname="John" lastname="Doe" />
+      <Avatar size="medium" shape="square" firstname="John" lastname="Doe" />
+      <Avatar size="large" shape="square" firstname="John" lastname="Doe" />
+      <Avatar size="xlarge" shape="square" firstname="John" lastname="Doe" />
+    </HStack>
+  ),
+};
+
+export const CircleSizes: Story = {
+  render: () => (
+    <HStack gap="$space.16" alignItems="center">
+      <Avatar size="small" shape="circle" firstname="John" lastname="Doe" />
+      <Avatar size="medium" shape="circle" firstname="John" lastname="Doe" />
+      <Avatar size="large" shape="circle" firstname="John" lastname="Doe" />
+      <Avatar size="xlarge" shape="circle" firstname="John" lastname="Doe" />
+    </HStack>
+  ),
+};
+
+export const Shapes: Story = {
+  render: () => (
+    <HStack gap="$space.16" alignItems="center">
+      <Avatar size="large" shape="square" firstname="John" lastname="Doe" />
+      <Avatar size="large" shape="circle" firstname="John" lastname="Doe" />
+    </HStack>
+  ),
+};
+
+export const Disabled: Story = {
+  render: () => (
+    <HStack gap="$space.16" alignItems="center">
+      <Avatar disabled size="large" shape="square" />
+      <Avatar disabled size="large" shape="square" firstname="John" lastname="Doe" />
+      <Avatar disabled size="large" shape="square" src="https://i.pravatar.cc/150?img=5" />
+    </HStack>
+  ),
+};
+
+export const DisabledShapes: Story = {
+  render: () => (
+    <HStack gap="$space.16" alignItems="center">
+      <Avatar disabled size="large" shape="square" firstname="John" lastname="Doe" />
+      <Avatar disabled size="large" shape="circle" firstname="John" lastname="Doe" />
+    </HStack>
+  ),
+};
+
+export const Responsive: Story = {
+  render: () => (
+    <VStack gap="$space.16">
+      <Avatar
+        size="small"
+        shape="square"
+        firstname="John"
+        lastname="Doe"
+        $medium={{
+          size: 'large',
+        }}
+      />
+      <Avatar
+        size="large"
+        shape="square"
+        firstname="John"
+        lastname="Doe"
+        $medium={{
+          shape: 'circle',
+        }}
+      />
+    </VStack>
+  ),
+};

package/src/system/dataDisplays/Avatar/Avatar.mdx

@@ -0,0 +1,73 @@
+import { Meta, Title, Subtitle, Primary, Controls, Canvas } from '@storybook/blocks';
+import * as AvatarStories from './Avatar.stories';
+import * as AvatarFeatures from './Avatar.features.stories';
+
+<Meta of={AvatarStories} />
+<Title />
+<Subtitle />
+
+<Primary />
+<Controls />
+
+## Overview
+
+`Avatar` represents a user with an image, initials, or a placeholder fallback. It picks the right content based on which props are passed: `src` wins, then `firstname`/`lastname` fall back to initials, and an empty avatar renders the default placeholder image.
+
+## Placeholder
+
+When neither `src` nor `firstname`/`lastname` are provided, the avatar shows the default placeholder image. Use this for unknown or anonymous users.
+
+<Canvas of={AvatarFeatures.Placeholder} />
+
+## Initials
+
+Pass `firstname` and `lastname` to display the user's initials (e.g. "JD" for John Doe). Use this when no profile picture is available but the user identity is known.
+
+<Canvas of={AvatarFeatures.WithInitials} />
+
+## Image
+
+Pass `src` to display a user's profile picture. The image is rendered as a background image filling the entire avatar frame, with `overflow: hidden` clipping it to the avatar's shape.
+
+<Canvas of={AvatarFeatures.WithImage} />
+
+## Sizes
+
+The `size` prop controls the avatar's width and height. Defaults to `large`.
+
+| Size     | Dimensions |
+| -------- | ---------- |
+| `small`  | 32 × 32 px |
+| `medium` | 40 × 40 px |
+| `large`  | 48 × 48 px |
+| `xlarge` | 64 × 64 px |
+
+If you need a custom size, set `width` and `height` directly instead of `size`.
+
+<Canvas of={AvatarFeatures.Sizes} />
+
+<Canvas of={AvatarFeatures.CircleSizes} />
+
+## Shapes
+
+The `shape` prop controls the corner radius. Defaults to `square` (uses `$radius.m`). Use `circle` (uses `$radius.circle`) for profile pictures in social or chat contexts where a circular crop is the convention.
+
+<Canvas of={AvatarFeatures.Shapes} />
+
+## Disabled
+
+Set `disabled` to render the avatar in a muted state — the background switches to `$bg.disabled.hi` and content (initials or image) is dimmed. Use this to indicate inactive or unavailable users.
+
+<Canvas of={AvatarFeatures.Disabled} />
+
+<Canvas of={AvatarFeatures.DisabledShapes} />
+
+## Responsive
+
+All props accept Tamagui media query overrides (`$small`, `$medium`, `$large`, `$wide`). Use them to adapt size or shape per breakpoint without rendering multiple avatars.
+
+<Canvas of={AvatarFeatures.Responsive} />
+
+## Related
+
+- [Badge](?path=/docs/bumper-data-displays-badge--docs)

package/src/system/dataDisplays/Avatar/Avatar.stories.tsx

@@ -0,0 +1,47 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Avatar } from './Avatar';
+
+const meta: Meta<typeof Avatar> = {
+  title: 'Bumper/Data Displays/Avatar',
+  component: Avatar,
+  argTypes: {
+    size: {
+      control: 'select',
+      options: ['small', 'medium', 'large', 'xlarge'],
+      description: 'The size of the avatar.',
+    },
+    shape: {
+      control: 'select',
+      options: ['square', 'circle'],
+      description: 'The shape of the avatar.',
+    },
+    src: {
+      control: 'text',
+      description: 'URL of the image to display.',
+    },
+    firstname: {
+      control: 'text',
+      description: 'First name used to generate initials.',
+    },
+    lastname: {
+      control: 'text',
+      description: 'Last name used to generate initials.',
+    },
+    disabled: {
+      control: 'boolean',
+      description: 'Whether the avatar is disabled.',
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    size: 'large',
+    shape: 'square',
+    firstname: 'John',
+    lastname: 'Doe',
+  },
+};