@bitrise/bitkit-v2 0.3.210 → 0.3.211

package/docs/v1-to-v2-migration-guide.md

@@ -0,0 +1,295 @@
+# Bitkit v1 → v2 Migration Guide
+
+Practical learnings from migrating a React frontend from `@bitrise/bitkit` (Chakra UI v2) to `@bitrise/bitkit-v2` (Chakra UI v3).
+
+---
+
+## Strategy: coexistence first, cutover last
+
+Don't attempt a big-bang migration. Instead:
+
+1. Install `@bitrise/bitkit-v2` alongside v1
+2. Wrap `BitkitProvider` (v2) **inside** the existing v1 `<Provider>`. In practice, nesting them works without additional config.
+3. Migrate file by file, component by component
+4. Remove v1 `<Provider>` only when zero v1 imports remain
+5. Remove `@bitrise/bitkit` from `package.json` last
+
+```tsx
+// Transitional App.tsx
+<Provider theme={customTheme}>         {/* v1 — stays until all v1 imports gone */}
+  <BitkitProvider>                      {/* v2 */}
+    <App />
+  </BitkitProvider>
+</Provider>
+```
+
+> **Note on CSS conflicts**: If Chakra v3's preflight reset causes visual conflicts during coexistence, `BitkitProvider` can't help — it hardcodes its internal system with `preflight: true` and doesn't expose an override. The fallback is `ChakraProvider` with a custom system where `preflight: false`, but be aware that also drops Bitkit's bundled font imports and `BitkitToaster` — those would need to be re-added manually.
+
+---
+
+## Migration order
+
+Migrate in this order to minimize blockers:
+
+1. **Primitives**: `Box`, `Text`, `Divider` — these are used everywhere, get them out of the way first
+2. **Atomic components**: `Button`, `Badge`, `Tag`, `Spinner`, `Toast`
+3. **Form components**: `Input`, `Textarea`, `Select`, `Checkbox`, `Switch`
+4. **Layout & navigation**: `Sidebar`, `Breadcrumb`
+5. **Composite components**: `Dialog`, `Tabs`, `Table`, `Card`, `Alert`
+6. **Icons** (if migrating from `lucide-react` or similar)
+7. **Dependency cleanup**: remove v1 and all now-unused peer deps
+
+---
+
+## Component mapping
+
+### Primitives
+
+| v1 | v2 |
+|----|----|
+| `Box` from `@bitrise/bitkit` | `Box` from `@chakra-ui/react/box` |
+| `Text` from `@bitrise/bitkit` | `Text` from `@chakra-ui/react/text` |
+| `Divider` | `Separator` from `@chakra-ui/react/separator` |
+| `BoxProps`, `TextProps` | same, from `@chakra-ui/react/box` and `@chakra-ui/react/text` |
+
+Chakra v2 → v3 prop changes on primitives:
+- `noOfLines` → `lineClamp`
+- `Box as="a" href="..."` doesn't work → use `chakra.a` from `@chakra-ui/react/styled-system`
+- `Box as="button" onClick={...}` → use `chakra.button` from `@chakra-ui/react/styled-system`
+
+### Buttons
+
+| v1 | v2 |
+|----|----|
+| `Button` | `BitkitButton` |
+| `IconButton` | `BitkitIconButton` |
+| `leftIconName` | `icon` |
+| `isDisabled` | `state="disabled"` |
+| `isLoading` | `state="loading"` |
+
+**Gotcha**: `BitkitButton` requires `children` to be a `string`. If a button contains complex layout (icon + text, conditional content, custom JSX), use `chakra.button` from `@chakra-ui/react/styled-system` instead of forcing it into `BitkitButton`.
+
+### Badge / Tag
+
+| v1 | v2 |
+|----|----|
+| `Badge colorScheme="positive"` | `BitkitBadge colorPalette="green"` |
+| `Badge colorScheme="negative"` | `BitkitBadge colorPalette="red"` |
+| `Badge colorScheme="warning"` | `BitkitBadge colorPalette="yellow"` |
+| `Badge colorScheme="progress"` | `BitkitBadge colorPalette="purple"` |
+| `Tag` | `BitkitTag` |
+
+### Toast
+
+```tsx
+// v1
+const toast = useToast()
+toast({ status: 'error', title: 'Oops', description: 'Something failed' })
+
+// v2
+createBitkitToast({ variant: 'critical', titleText: 'Oops', messageText: 'Something failed' })
+```
+
+`status` → `variant`, and `'error'` → `'critical'`. Note: `createBitkitToast` is called directly with props — it's not a factory that returns a function.
+
+### Dialogs
+
+```tsx
+// v1
+<Dialog isOpen={open} onClose={() => setOpen(false)}>
+  <DialogBody>...</DialogBody>
+  <DialogFooter>...</DialogFooter>
+</Dialog>
+
+// v2
+<BitkitDialog open={open} onOpenChange={({ open }) => setOpen(open)}>
+  <BitkitDialog.Body>...</BitkitDialog.Body>
+  <BitkitDialog.Footer>
+    <BitkitDialog.Buttons>...</BitkitDialog.Buttons>
+  </BitkitDialog.Footer>
+</BitkitDialog>
+```
+
+Key changes: `isOpen` → `open`, `onClose` → `onOpenChange` (receives `{ open: boolean }`).
+
+### Tabs
+
+The API changed fundamentally — from index-based to value-based:
+
+```tsx
+// v1 (index-based)
+<Tabs>
+  <TabList>
+    <Tab>First</Tab>
+    <Tab>Second</Tab>
+  </TabList>
+  <TabPanels>
+    <TabPanel>...</TabPanel>
+    <TabPanel>...</TabPanel>
+  </TabPanels>
+</Tabs>
+
+// v2 (value-based)
+<BitkitTabs.Root defaultValue="first">
+  <BitkitTabs.List>
+    <BitkitTabs.Trigger value="first">First</BitkitTabs.Trigger>
+    <BitkitTabs.Trigger value="second">Second</BitkitTabs.Trigger>
+  </BitkitTabs.List>
+  <BitkitTabs.ContentGroup>
+    <BitkitTabs.Content value="first">...</BitkitTabs.Content>
+    <BitkitTabs.Content value="second">...</BitkitTabs.Content>
+  </BitkitTabs.ContentGroup>
+</BitkitTabs.Root>
+```
+
+This is one of the more involved migrations — every tab needs an explicit `value`.
+
+### Table
+
+```tsx
+// v1 — flat imports
+import { Table, Thead, Tbody, Tr, Th, Td, TableContainer } from '@bitrise/bitkit'
+
+// v2 — namespace
+import { Table } from '@chakra-ui/react/table'
+<Table.Root><Table.Header><Table.Row><Table.ColumnHeader>
+<Table.Body><Table.Row><Table.Cell>
+```
+
+### Forms
+
+| v1 | v2 |
+|----|----|
+| `Input` | `BitkitTextInput` |
+| `Textarea` | `BitkitTextArea` |
+| `Select` | `BitkitNativeSelect` |
+| `Checkbox` | `BitkitCheckbox` |
+| `Toggle` (`Switch` in v1) | `BitkitSwitch` |
+| `SearchInput` | `BitkitSearchInput` |
+
+For password fields with an eye-toggle: use `BitkitField` + Chakra v3 `InputGroup` with `endElement`.
+
+### Cards
+
+| v1 | v2 |
+|----|----|
+| `Card` | `BitkitCard` |
+| `ExpandableCard` | `BitkitExpandableCard` |
+
+`BitkitCard` accepts `paddingSize` and `elevation` (boolean). Common `BitkitExpandableCard` props: `title`, `secdText`, `size`; use `defaultExpanded` for uncontrolled or `expanded`/`onChange` for controlled usage. It also supports `icon`, `suffix`, and other options — see the component API for the full list.
+
+If your codebase has a local `card.tsx` wrapper around v1 Card (e.g. Shadcn-style `CardHeader`, `CardContent` etc.), remove the wrapper entirely and migrate to `BitkitCard` directly — keeping the wrapper layer just adds indirection you'll need to unwind later.
+
+### Notifications / Alert
+
+| v1 | v2 |
+|----|----|
+| `Notification` | `BitkitAlert` |
+
+### Sidebar & Breadcrumb
+
+```tsx
+// Sidebar v2
+<BitkitSidebar>
+  <BitkitSidebar.Title>Title</BitkitSidebar.Title>
+  <BitkitSidebar.GroupHeading>Group</BitkitSidebar.GroupHeading>
+  <BitkitSidebar.Item icon={IconName} selected={...}>Label</BitkitSidebar.Item>
+</BitkitSidebar>
+
+// Breadcrumb v2
+<BitkitBreadcrumb>
+  <BitkitBreadcrumb.Item href="#/path">Label</BitkitBreadcrumb.Item>
+  <BitkitBreadcrumb.CurrentItem>Current</BitkitBreadcrumb.CurrentItem>
+</BitkitBreadcrumb>
+```
+
+**HashRouter gotcha**: `BitkitBreadcrumb` uses plain `href`. With HashRouter all links need the `#/` prefix (e.g. `href="#/sessions"`), otherwise navigation breaks silently.
+
+**Version requirement**: `BitkitBreadcrumb` requires `@bitrise/bitkit-v2 >= 0.3.210`.
+
+### textStyle tokens
+
+Replace explicit `fontSize` / `fontWeight` / `lineHeight` props on `<Text>` with `textStyle` tokens:
+
+```tsx
+// Before
+<Text fontSize="14px" fontWeight="600" lineHeight="20px">...</Text>
+
+// After
+<Text textStyle="body/md/semibold">...</Text>
+```
+
+Common tokens: `body/sm/regular`, `body/md/regular`, `body/md/semibold`, `body/lg/semibold`, `heading/h3` … `heading/h1`. Do this alongside the component migration per file — don't leave it for a separate pass at the end, it accumulates quickly.
+
+---
+
+## Action menus
+
+If the codebase has a hand-rolled dropdown/action menu (state + ref + `useEffect` for click-outside), replace it with `BitkitActionMenu`:
+
+```tsx
+<BitkitActionMenu.Root trigger={<button>...</button>}>
+  <BitkitActionMenu.Item onClick={...}>Edit</BitkitActionMenu.Item>
+  <BitkitActionMenu.Separator />
+  <BitkitActionMenu.Item onClick={...} danger>Delete</BitkitActionMenu.Item>
+</BitkitActionMenu.Root>
+```
+
+---
+
+## Color tokens: `text/*` vs `icon/*`
+
+Use `text/*` tokens on `<Text>` (and other text elements), and `icon/*` tokens on `<Icon*>` components. Most pairs resolve to the same underlying color, so a mismatch won't be visible — but the semantics matter.
+
+| `text/*` token | `icon/*` equivalent | Same color? |
+|---|---|---|
+| `text/secondary` | `icon/secondary` | ✓ |
+| `text/tertiary` | `icon/tertiary` | ✓ |
+| `text/link` | `icon/interactive` | ✓ (both → `sys.interactive`) |
+
+**Gotcha**: `icon/link` does **not** exist. Use `icon/interactive` instead — it resolves to the same `sys.interactive` color as `text/link`.
+
+---
+
+## Dependency cleanup
+
+After the migration, audit `package.json` carefully — v1 pulled in transitive deps that may still be listed:
+
+- `@emotion/react` — you may no longer need to list it directly in your app's `package.json`; `@bitrise/bitkit-v2` brings it transitively
+- `lucide-react` — if icons are now from `@bitrise/bitkit-v2`
+- `zustand` — if Bitkit's sidebar hook was the only consumer
+- `@types/luxon`, `patch-package`, `postcss` — check if still used
+
+Also check `scripts` in `package.json` for any `postinstall` entries referencing removed packages (e.g. `"postinstall": "patch-package"`) — these will silently break CI.
+
+---
+
+## Working efficiently (token / context budget)
+
+Migrating a large repo component-by-component is token-intensive. What works well:
+
+- **Grep first, cheap**: `grep -r "@bitrise/bitkit" src --include="*.tsx" -l` gives you the full scope before touching anything
+- **You navigate, AI executes**: identify the interesting/complex files yourself, hand them over one at a time. Avoid "replace all X with Y across the entire repo" — it requires reading every file even for trivial changes
+- **Codemods for mechanical swaps**: simple renames across many files (`Box` → `chakra.Box`, import path changes) are better done with `sed` or a codemod script; use AI for the cases that need judgment
+- **Identify custom components early**: look for any local wrappers around v1 components or hand-rolled alternatives to v2 components (dropdowns, cards, dialogs). Plan to replace these, not wrap them again
+
+---
+
+## Pre-migration checklist
+
+- [ ] `grep -r "@bitrise/bitkit" src` — inventory of files and components
+- [ ] Identify local wrapper components around v1 Bitkit components
+- [ ] Identify hand-rolled alternatives to v2 components (dropdowns, modals, etc.)
+- [ ] Check `@bitrise/bitkit-v2` changelog for version requirements per component
+- [ ] Check if HashRouter is in use (affects Breadcrumb `href`)
+- [ ] Note any buttons with complex children (non-string) — these need `chakra.button`
+
+## Post-migration checklist
+
+- [ ] Zero `@bitrise/bitkit` imports in source
+- [ ] `npm run build` passes
+- [ ] `npm run lint` clean
+- [ ] Remove `@bitrise/bitkit` from `package.json`
+- [ ] Remove transitively-pulled peer deps that are no longer needed
+- [ ] Check all `scripts` entries in `package.json` for references to removed packages
+- [ ] Visual walkthrough: all pages, dialogs, tabs, forms, toasts, tables

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@bitrise/bitkit-v2",
   "private": false,
-  "version": "0.3.210",
+  "version": "0.3.211",
   "description": "Bitrise Design System Components built with Chakra UI V3",
   "keywords": [
     "react",
@@ -13,6 +13,7 @@
   "type": "module",
   "files": [
     "dist",
+    "docs",
     "scripts/postinstall.cjs",
     "README.md",
     "package.json"