@ornikar/bumper 3.11.0 → 3.12.0

package/docs/migration/Sticker.md

@@ -0,0 +1,222 @@
+# Sticker → Sticker Migration Guide
+
+> Source: `@ornikar/kitt-universal/Sticker`
+> Target: `@ornikar/bumper/Sticker`
+> Generated: 2026-04-21 · Updated: 2026-04-29 (target prop reverted from `stickerColor` back to `color`)
+
+## Import Change
+
+```tsx
+// Before
+import { Sticker } from '@ornikar/kitt-universal';
+// Type imports (rare — kitt-universal only re-exports the value, not the types)
+import type { StickerProps, StickerColor, StickerSize } from '@ornikar/kitt-universal/Sticker/Sticker';
+
+// After
+import { Sticker } from '@ornikar/bumper';
+import type { StickerProps, StickerColor, StickerSize } from '@ornikar/bumper';
+```
+
+## Props Mapping
+
+| Source Prop         | Target Prop | Transform                   | Notes                                                                                         |
+| ------------------- | ----------- | --------------------------- | --------------------------------------------------------------------------------------------- |
+| `label`             | `label`     | Keep as-is                  | Same API (`ReactNode`, required)                                                              |
+| `color`             | `color`     | Remap values                | See [Color Value Mapping](#color-value-mapping). Default changed: `linen` → `green`           |
+| `color="disabled"`  | `disabled`  | Replace prop + drop value   | `disabled` is now a boolean state, not a color. See [Disabled Migration](#disabled-migration) |
+| `size`              | `size`      | Keep prop, values unchanged | Default changed: `medium` → `small`                                                           |
+| `stretch` (boolean) | —           | **Not migratable**          | Removed from bumper. See [Stretch Removal](#stretch-removal)                                  |
+
+## Value Mappings
+
+### Color Value Mapping
+
+```
+green          → green           (unchanged)
+darkGreen      → greenDark       (camelCase order flipped)
+blue           → blue            (unchanged)
+darkBlue       → blueDark        (camelCase order flipped)
+red            → red             (unchanged)
+orange         → orange          (unchanged)
+pink           → pink            (unchanged)
+gold           → gold            (unchanged)
+cream          → cream           (unchanged)
+linen          → linen           (unchanged)
+promo          → lightning       (renamed)
+darkPromo      → lightningDark   (renamed + order flipped)
+disabled       → (remove color) + add `disabled` prop   — see below
+```
+
+### Size Value Mapping
+
+Unchanged:
+
+```
+small  → small
+medium → medium
+large  → large
+```
+
+## Children & Composition
+
+No change — both components accept a single `label` prop (`ReactNode`). No compound components, no children slot.
+
+## Behavioral Differences
+
+### Default value changes
+
+| Prop (bumper) | kitt-universal default | bumper default | Action for migrating code                                                                                           |
+| ------------- | ---------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `color`       | `'linen'`              | `'green'`      | If source code relied on the default (`<Sticker label="x" />`), add explicit `color="linen"` to preserve appearance |
+| `size`        | `'medium'`             | `'small'`      | If source code relied on the default, add explicit `size="medium"` to preserve appearance                           |
+
+### Typography size per `size` variant
+
+Typography mapping is **identical** between source and target (both use the same content-caps scale):
+
+- `size="small"` → `content-caps-xs` (12px)
+- `size="medium"` → `content-caps-m` (16px)
+- `size="large"` → `content-caps-l` (18px)
+
+### Disabled visual
+
+In kitt-universal, `color="disabled"` paints a beige background (`beige.6`) with beige text (`beige.2`). In bumper, `disabled` prop paints the semantic disabled tokens (`$bg.disabled.hi` = grey `#bababa`, `$content.disabled.onContrasted` = white @ 90%). The visual is close but not pixel-identical. Flag for design QA.
+
+### Responsive props
+
+bumper `Sticker` accepts Tamagui media props (`$small`, `$medium`, `$large`, `$wide`) — kitt-universal does not. No migration action needed; this is a net gain, not a break.
+
+## Edge Cases
+
+### Disabled migration
+
+kitt-universal exposes `disabled` as a **color value**. bumper exposes it as a **boolean prop** — `disabled` is no longer part of the `StickerColor` union.
+
+```tsx
+// Before — static
+<Sticker label="Offline" color="disabled" />
+
+// After
+<Sticker label="Offline" disabled />
+```
+
+```tsx
+// Before — conditional disabled state based on a boolean
+<Sticker label="Item" color={isInactive ? 'disabled' : 'green'} />
+
+// After — split the condition into `disabled` + static `color`
+<Sticker label="Item" color="green" disabled={isInactive} />
+```
+
+```tsx
+// Before — multi-branch conditional color including 'disabled'
+<Sticker label="Item" color={state === 'off' ? 'disabled' : state === 'hot' ? 'red' : 'green'} />
+
+// After — extract the disabled branch into the `disabled` prop
+<Sticker
+  label="Item"
+  color={state === 'hot' ? 'red' : 'green'}
+  disabled={state === 'off'}
+/>
+```
+
+### Renamed color values in dynamic expressions
+
+When `color` is computed dynamically, remap the values inside the expression (the prop name is unchanged):
+
+```tsx
+// Before
+<Sticker label={x.label} color={x.theme === 'dark' ? 'darkGreen' : 'green'} />
+
+// After
+<Sticker label={x.label} color={x.theme === 'dark' ? 'greenDark' : 'green'} />
+```
+
+```tsx
+// Before — lookup table
+const colorMap = { success: 'green', warning: 'gold', error: 'red', paused: 'darkBlue', pro: 'promo' } as const;
+<Sticker label={status} color={colorMap[kind]} />;
+
+// After — rename values in the table
+const colorMap = { success: 'green', warning: 'gold', error: 'red', paused: 'blueDark', pro: 'lightning' } as const;
+<Sticker label={status} color={colorMap[kind]} />;
+```
+
+### Spread props
+
+```tsx
+// Before
+<Sticker {...stickerProps} />;
+
+// After — if stickerProps may contain `stretch`, filter it out (see Stretch Removal)
+const { stretch, ...rest } = stickerProps;
+<Sticker {...rest} />;
+```
+
+If `stickerProps.color` may be `'disabled'` at runtime, the spread will no longer type-check. Transform dynamically:
+
+```tsx
+// After — handle legacy 'disabled' color at call site, remap value
+const { color, stretch, ...rest } = stickerProps;
+<Sticker {...rest} {...(color === 'disabled' ? { disabled: true } : { color: remapColor(color) })} />;
+```
+
+### Stretch removal
+
+`stretch` has no bumper equivalent. The source component used it to make the sticker `width: 100%` and center-align the label. Options:
+
+1. **Default** — remove the prop. The sticker becomes `alignSelf: 'flex-start'` (shrink-to-content). Acceptable if the parent didn't rely on the stretch behavior.
+2. **Preserve full-width behavior manually**:
+
+   ```tsx
+   // Before
+   <Sticker label="x" stretch />
+
+   // After — manual wrapper
+   <View width="100%" alignItems="center">
+     <Sticker label="x" />
+   </View>
+   ```
+
+3. **If `stretch` was responsive** (e.g. `stretch={{ base: false, medium: true }}`), **not migratable mechanically** — flag for human review.
+
+Any call site using `stretch` must be reviewed: the sticker's layout will change otherwise.
+
+### Wrapper / re-export migration
+
+If a project wraps `Sticker` in a local component, update the wrapper's imports and forward-props first (same mapping as above), then the usages resolve automatically.
+
+If the wrapper forwards `stretch`, either drop it from the wrapper's own public API (breaking change for the wrapper) or implement the manual full-width pattern inside the wrapper.
+
+### Styled / extended components
+
+kitt-universal's `Sticker` uses native-base `HStack` internally and does not support being extended via `styled()`. bumper's `Sticker` is built with Tamagui but only the public `Sticker` function component is exported — **not** the underlying styled frame. If a consumer relied on `styled(Sticker)` patterns (rare), that is not migratable; use `View` + `Typography.Text` primitives to rebuild.
+
+## Migration Rules (machine-readable)
+
+1. Update import path: `@ornikar/kitt-universal` → `@ornikar/bumper`.
+2. Update type imports (if any): `@ornikar/kitt-universal/Sticker/Sticker` → `@ornikar/bumper`.
+3. Keep the component name as-is: `Sticker` → `Sticker`.
+4. For each prop on every `<Sticker />` usage:
+   1. `label` — keep unchanged.
+   2. `color="disabled"` — **remove the `color` prop** and **add `disabled`** (boolean, `true`).
+   3. `color="darkGreen"` — remap value to `color="greenDark"`.
+   4. `color="darkBlue"` — remap value to `color="blueDark"`.
+   5. `color="promo"` — remap value to `color="lightning"`.
+   6. `color="darkPromo"` — remap value to `color="lightningDark"`.
+   7. `color` with any other static value from the union (`green`, `blue`, `red`, `orange`, `pink`, `gold`, `cream`, `linen`) — keep as-is (values unchanged).
+   8. `color` with a **dynamic expression** (ternary, lookup, variable) — keep the prop name, then recursively apply rules 4.2–4.6 to every literal value inside that expression. If the expression can evaluate to `'disabled'`, split it: extract that branch into a `disabled={…}` prop and remove `'disabled'` from the `color` expression.
+   9. `size` — keep unchanged (values are identical).
+   10. `stretch={false}` — remove the prop.
+   11. `stretch` (bare, or `={true}`, or dynamic) — **flag for manual review**. Leave the prop in place with a `// TODO: bumper Sticker has no stretch prop` comment. Do not guess.
+5. If the call site relied on the default `color` (no `color` prop) and the visual must be preserved, add `color="linen"` explicitly.
+6. If the call site relied on the default `size` (no `size` prop) and the visual must be preserved, add `size="medium"` explicitly.
+7. For spread usages `<Sticker {...props} />`, do **not** rewrite the call site blindly — inspect the source type of `props` and transform the object creation site instead (or introduce a local destructure that filters `stretch` and remaps `'disabled'` to a `disabled={true}` prop, as shown in [Spread props](#spread-props)).
+8. Do not migrate `styled(Sticker)` wrappers; flag them for manual rewrite.
+
+## Not Migratable (requires human review)
+
+- **`stretch` prop** — no bumper equivalent. Manual decision needed per call site: drop the prop (accept layout change), or wrap in `<View width="100%" alignItems="center">`. Responsive `stretch` values (e.g. `stretch={{ base: false, medium: true }}`) always require manual review.
+- **`styled(Sticker)` / extended Sticker wrappers** — underlying styled component is not exported from bumper. Rebuild with primitives if needed.
+- **Default-value regressions** — when `color` or `size` default is relied upon, the visual will change (cream pill in `medium` becomes green pill in `small`). If the migration tool cannot determine whether the default is intentional, flag the call site for design review.
+- **Runtime-only `'disabled'` color values** — when `color` is passed as an untyped string from an external source (e.g. a CMS field), rule 4.8 cannot rewrite it statically. Add a defensive remap at the call site.

package/package.json

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

package/src/index.ts

@@ -29,6 +29,8 @@ export type { TypographyLinkProps } from './system/content/typography/Typography
 // Data Displays
 export type { BadgeProps } from './system/dataDisplays/Badge/Badge';
 export { Badge } from './system/dataDisplays/Badge/Badge';
+export { Sticker } from './system/dataDisplays/Sticker/Sticker';
+export type { StickerProps } from './system/dataDisplays/Sticker/types';
 
 // Breakpoints
 export { useBreakpointValue } from './system/core/breakpoints/hooks/useBreakpointValue';

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

@@ -0,0 +1,50 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { HStack, VStack } from '../../core/primitives/Stack';
+import { View } from '../../core/primitives/View';
+import { Sticker } from './Sticker';
+import { STICKER_COLORS_LIST } from './types';
+
+const meta: Meta<typeof Sticker> = {
+  title: 'Bumper/Data Displays/Sticker/Features',
+  component: Sticker,
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Sizes: Story = {
+  render: () => (
+    <HStack gap="$space.16" alignItems="center">
+      <Sticker label="Small" size="small" />
+      <Sticker label="Medium" size="medium" />
+      <Sticker label="Large" size="large" />
+    </HStack>
+  ),
+};
+
+export const Colors: Story = {
+  render: () => (
+    <VStack gap="$space.8" alignItems="flex-start">
+      {STICKER_COLORS_LIST.map((color) => (
+        <Sticker key={color} label={color} color={color} />
+      ))}
+    </VStack>
+  ),
+};
+
+export const Disabled: Story = {
+  render: () => (
+    <HStack gap="$space.16" alignItems="center">
+      <Sticker label="Enabled" color="lightning" />
+      <Sticker disabled label="Disabled" color="lightning" />
+    </HStack>
+  ),
+};
+
+export const LongLabel: Story = {
+  render: () => (
+    <View width={200}>
+      <Sticker label="A very long label that should be truncated with an ellipsis" color="linen" />
+    </View>
+  ),
+};

package/src/system/dataDisplays/Sticker/Sticker.mdx

@@ -0,0 +1,38 @@
+import { Meta, Title, Subtitle, Primary, Controls, Canvas } from '@storybook/blocks';
+import * as StickerStories from './Sticker.stories';
+import * as StickerFeatures from './Sticker.features.stories';
+
+<Meta of={StickerStories} />
+<Title />
+<Subtitle />
+
+<Primary />
+<Controls />
+
+## Overview
+
+`Sticker` is a pill-shaped label used to flag status, category, or highlight content. It renders a short `label` inside a rounded container with a paired background and text color. Twelve colors are available plus three sizes (`small`, `medium`, `large`). Pass `disabled` to force the disabled color variant.
+
+## Sizes
+
+Three sizes cover the most common usages. Typography scales along with the container: `small` uses `content-caps-xs`, `medium` uses `content-caps-m`, `large` uses `content-caps-l`.
+
+<Canvas of={StickerFeatures.Sizes} />
+
+## Colors
+
+Each color pairs a background tone with a matching text tone for legibility. Pick the color that best aligns with the surrounding context (e.g. `lightning` for promotional content, `red` for error states).
+
+<Canvas of={StickerFeatures.Colors} />
+
+## Disabled
+
+`disabled` forces the internal disabled color variant, overriding any `color` prop. Use it to visually signal that the sticker's content is inactive.
+
+<Canvas of={StickerFeatures.Disabled} />
+
+## Truncation
+
+Labels are truncated with an ellipsis when the sticker can't fit the full text. The sticker itself never grows beyond its parent.
+
+<Canvas of={StickerFeatures.LongLabel} />

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

@@ -0,0 +1,49 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Sticker } from './Sticker';
+import { STICKER_COLORS_LIST, STICKER_SIZES_LIST } from './types';
+
+const meta: Meta<typeof Sticker> = {
+  title: 'Bumper/Data Displays/Sticker',
+  component: Sticker,
+  argTypes: {
+    label: {
+      control: 'text',
+      description: 'Text content rendered inside the sticker.',
+    },
+    color: {
+      control: 'select',
+      options: STICKER_COLORS_LIST,
+      description: 'Color variant.',
+      table: {
+        defaultValue: { summary: 'green' },
+      },
+    },
+    size: {
+      control: 'select',
+      options: STICKER_SIZES_LIST,
+      description: 'Sticker size.',
+      table: {
+        defaultValue: { summary: 'small' },
+      },
+    },
+    disabled: {
+      control: 'boolean',
+      description: 'Forces the disabled color variant.',
+      table: {
+        defaultValue: { summary: 'false' },
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    label: 'Label',
+    color: 'green',
+    size: 'small',
+    disabled: false,
+  },
+};

package/src/system/dataDisplays/Sticker/Sticker.tsx

@@ -0,0 +1,52 @@
+import { styled } from '@tamagui/core';
+import type { ReactNode } from 'react';
+import { useProps } from '../../core/hooks/useProps';
+import type { ViewProps } from '../../core/primitives/View';
+import { View } from '../../core/primitives/View';
+import type { PropsToTamaguiVariants } from '../../types';
+import { InternalStickerLabel } from './components/StickerLabel';
+import { context } from './context';
+import type { InternalStickerWithoutMediaProps, StickerColor, StickerProps } from './types';
+import { STICKER_COLORS } from './types';
+
+export const InternalStickerFrame = styled(View, {
+  name: 'Sticker',
+  context,
+  alignSelf: 'flex-start',
+  maxWidth: '100%',
+  padding: '$space.4',
+  variants: {
+    label: {},
+    size: {
+      small: { borderRadius: '$radius.s' },
+      medium: { borderRadius: '$radius.m' },
+      large: { borderRadius: '$radius.m' },
+    },
+    color: (color: StickerColor): ViewProps => {
+      const { disabled } = context.useStyledContext();
+
+      return {
+        backgroundColor: STICKER_COLORS[disabled ? 'disabled' : color].background,
+      };
+    },
+  } as const satisfies PropsToTamaguiVariants<InternalStickerWithoutMediaProps, ViewProps>,
+
+  defaultVariants: {
+    size: 'small',
+    color: 'green',
+  },
+});
+
+export const InternalSticker = InternalStickerFrame.styleable<StickerProps>((props) => {
+  const { label, ...frameProps } = useProps(props);
+
+  return (
+    <InternalStickerFrame {...frameProps}>
+      <InternalStickerLabel>{label}</InternalStickerLabel>
+    </InternalStickerFrame>
+  );
+});
+
+export function Sticker(props: StickerProps): ReactNode {
+  return <InternalSticker {...props} />;
+}