{"id":29084896,"url":"https://github.com/workleap/orbiter-to-hopper-codemods","last_synced_at":"2025-06-27T22:11:37.758Z","repository":{"id":294526950,"uuid":"984784845","full_name":"workleap/orbiter-to-hopper-codemods","owner":"workleap","description":"Codemods to assist Orbiter to Hopper design system migrations","archived":false,"fork":false,"pushed_at":"2025-06-26T13:22:44.000Z","size":2158,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-06-26T14:28:12.491Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/workleap.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-16T13:58:29.000Z","updated_at":"2025-06-26T13:22:49.000Z","dependencies_parsed_at":"2025-05-20T21:58:06.985Z","dependency_job_id":"740a8f2f-d790-41ca-a778-776e16a60a34","html_url":"https://github.com/workleap/orbiter-to-hopper-codemods","commit_stats":null,"previous_names":["workleap/orbiter-to-hopper-codemods"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/workleap/orbiter-to-hopper-codemods","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/workleap%2Forbiter-to-hopper-codemods","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/workleap%2Forbiter-to-hopper-codemods/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/workleap%2Forbiter-to-hopper-codemods/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/workleap%2Forbiter-to-hopper-codemods/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/workleap","download_url":"https://codeload.github.com/workleap/orbiter-to-hopper-codemods/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/workleap%2Forbiter-to-hopper-codemods/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262341643,"owners_count":23296072,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-27T22:11:36.904Z","updated_at":"2025-06-27T22:11:37.747Z","avatar_url":"https://github.com/workleap.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Orbiter to Hopper Codemod \u003c!-- omit in toc --\u003e\n\nThis codemod automates the migration of components from [Orbiter](https://github.com/workleap/wl-orbiter) to the [Hopper](https://github.com/workleap/wl-hopper) design system.\n\nThe codemod handles various migration scenarios including:\n\n- ✅ **Component migrations** - Automatically updates import statements and component names\n- ✅ **Property transformations** - Maps old properties to new equivalents (e.g., `disabled` → `isDisabled`)\n- ✅ **Deprecated component handling** - Keeps deprecated components in original package with todo comments for manual migration\n- ✅ **Todo comment generation** - Adds contextual migration guidance directly in your code\n- ✅ **Migration notes collection** - Generates comprehensive notes about important changes that require manual review\n\n## Table of contents \u003c!-- omit in toc --\u003e\n\n- [Before Migration](#before-migration)\n- [After Migration](#after-migration)\n- [Usage Guide](#usage-guide)\n  - [Running Migrations](#running-migrations)\n    - [Migrate All Components](#migrate-all-components)\n    - [Migrate Component Categories](#migrate-component-categories)\n    - [Migrate Specific Components](#migrate-specific-components)\n    - [Target a Specific Path](#target-a-specific-path)\n    - [Additional Options](#additional-options)\n  - [Migration Notes](#migration-notes)\n  - [Analyzing Component, Function, and Type Usage](#analyzing-component-function-and-type-usage)\n    - [Project-Specific Analysis](#project-specific-analysis)\n    - [Deep Analysis](#deep-analysis)\n    - [Specifying Mapping Table](#specifying-mapping-table)\n    - [Filtering Analysis Results](#filtering-analysis-results)\n- [Allowed Parameters](#allowed-parameters)\n- [Shimmed components](#shimmed-components)\n  - [Card](#card)\n  - [Transition](#transition)\n- [Contributing](#contributing)\n\n## Before Migration\n\n```tsx\nimport { Div } from \"@workleap/orbiter-ui\";\n\nexport function App() {\n  return \u003cDiv width=\"100px\"/\u003e;\n}\n```\n\n## After Migration\n\n```tsx\nimport { Div } from \"@hopper-ui/components\";\n\nexport function App() {\n  return \u003cDiv UNSAFE_width=\"100px\"/\u003e;\n}\n```\n\n## Usage Guide\n\n### Running Migrations\n\n#### Migrate All Components\n\n```bash\npnpx codemod workleap/orbiter-to-hopper\n```\n\n#### Migrate Component Categories\n\n| Category | Description | Command | Mapping File |\n|----------|-------------|---------|--------------|\n| **Layout** | Layout containers, HTML wrappers, content elements (Flex, Grid, Div, Span, Article, Nav, ...) | `pnpx codemod workleap/orbiter-to-hopper -c layout` | [layout-components-mappings.ts](/src/mappings/orbiter/layout-components-mappings.ts) |\n| **Buttons** | Button components and variants | `pnpx codemod workleap/orbiter-to-hopper -c buttons` | [button-components-mappings.ts](/src/mappings/orbiter/button-components-mappings.ts) |\n| **Visual** | Visual elements and feedback components (Avatar, Image, Illustration, Spinner, ...) | `pnpx codemod workleap/orbiter-to-hopper -c visual` | [visual-components-mappings.ts](/src/mappings/orbiter/visual-components-mappings.ts) |\n| **Menu** | Menu and navigation components (Menu, MenuItem, ListBox, ListBoxItem, ...) | `pnpx codemod workleap/orbiter-to-hopper -c menu` | [menu-components-mappings.ts](/src/mappings/orbiter/menu-components-mappings.ts) |\n| **Overlay** | Overlay and dialog components (Modal, Popover, Tooltip, ...) | `pnpx codemod workleap/orbiter-to-hopper -c overlay` | [overlay-components-mappings.ts](/src/mappings/orbiter/overlay-components-mappings.ts) |\n| **Tags** | Tag and labeling components (Tag, TagGroup, Lozenge, ...) | `pnpx codemod workleap/orbiter-to-hopper -c tags` | [tags-components-mappings.ts](/src/mappings/orbiter/tags-components-mappings.ts) |\n| **Disclosure** | Disclosure and expandable content components (Accordion, Disclosure, Tab, ...) | `pnpx codemod workleap/orbiter-to-hopper -c disclosure` | [disclosure-components-mappings.ts](/src/mappings/orbiter/disclosure-components-mappings.ts) |\n\n#### Migrate Specific Components\n\nMigrate a single component:\n\n```bash\npnpx codemod workleap/orbiter-to-hopper -c Div\n```\n\nMigrate multiple specific components:\n\n```bash\npnpx codemod workleap/orbiter-to-hopper -c Div,Text,Button\n```\n\n#### Target a Specific Path\n\nRun the command in the desire path or pass the target path with the `-t` argument.\n\n```bash\npnpx codemod workleap/orbiter-to-hopper -t /app/users\n```\n\n#### Additional Options\n\nFor more configuration options, refer to the [Codemod CLI options documentation](https://docs.codemod.com/deploying-codemods/cli#options).\n\n### Migration Notes\n\nThe codemod automatically generates migration notes to help track important changes that require manual review. These notes are collected during the transformation process and aggregated into a `migration-notes.md` file.\n\n### Analyzing Component, Function, and Type Usage\n\nTo generate a comprehensive report of Orbiter component, function, and type usage patterns, use the following command:\n\n```bash\npnpx codemod workleap/orbiter-to-hopper -a orbiter-usage.json -n 1\n```\n\n⚠️ **Important**: The `-n 1` flag limits execution to a single thread, which ensures accurate output collection.\n\n#### Project-Specific Analysis\n\nYou can track component usage across different projects or teams using the `--project` parameter:\n\n```bash\npnpx codemod workleap/orbiter-to-hopper -a orbiter-usage.json --project frontend-team -n 1\npnpx codemod workleap/orbiter-to-hopper -a orbiter-usage.json --project mobile-app -n 1\n```\n\nThe analysis automatically accumulates results across multiple project runs, providing both project-specific counts and overall totals in the output.\n\n#### Deep Analysis\n\nTo include detailed file location information for each property value, use the `--deep` parameter:\n\n```bash\npnpx codemod workleap/orbiter-to-hopper -a orbiter-usage.json --deep true --project frontend-team -n 1\n```\n\nWhen deep analysis is enabled, each property value will include a `files` array containing repository URLs (GitHub or Azure DevOps) with line numbers where that specific value is used. For repositories that are not supported, file paths are used as fallback.\n\n#### Specifying Mapping Table\n\nBy default, analysis is performed using Orbiter mappings. You can specify which mapping table to use with the `--mappings` parameter:\n\n```bash\n# Default (orbiter mappings)\npnpx codemod workleap/orbiter-to-hopper -a orbiter-usage.json --deep true -n 1\n\n# Using hopper mappings\npnpx codemod workleap/orbiter-to-hopper -a hopper-usage.json --mappings hopper --deep true -n 1\n```\n\nThe output file name will automatically reflect the mapping type used.\n\n#### Filtering Analysis Results\n\nYou can filter the analysis to focus on specific areas that need attention:\n\n**Analyze only unmapped components:**\n\n```bash\npnpx codemod workleap/orbiter-to-hopper -a orbiter-usage-not-mapped-components.json --filter-unmapped components -n 1\n```\n\n**Analyze only unmapped properties for mapped components:**\n\n```bash\npnpx codemod workleap/orbiter-to-hopper -a orbiter-usage-not-mapped-props.json --filter-unmapped props -n 1\n```\n\n**Include ignored properties in analysis:**\n\nBy default, the analysis excludes standard React/DOM properties like `aria-*`, `data-*`, `className`, `style`, etc. to focus on component-specific migration needs. To include these properties in the analysis, use the `--include-ignoreList` flag:\n\n```bash\npnpx codemod workleap/orbiter-to-hopper -a orbiter-usage-complete.json --include-ignoreList -n 1\n```\n\nThis can be combined with other filters for comprehensive analysis:\n\n```bash\npnpx codemod workleap/orbiter-to-hopper -a orbiter-usage-all-unmapped.json --filter-unmapped props --include-ignoreList -n 1\n```\n\nThis command generates a JSON file (`orbiter-usage.json`) containing usage statistics for components, functions, and types, ordered by frequency. The output format prioritizes frequently used items with their properties:\n\n```json\n{\n  \"overall\": {\n    \"usage\": {\n      \"components\": 20,\n      \"componentProps\": 80,\n      \"functions\": 5,\n      \"types\": 12\n    }\n  },\n  \"components\": {\n    \"Text\": {\n      \"usage\": {\n        \"total\": 15,\n        \"projects\": {\n          \"frontend-team\": 10,\n          \"mobile-app\": 5\n        }\n      },\n      \"props\": {\n        \"size\": {\n          \"usage\": 75,\n          \"values\": {\n            \"lg\": {\n              \"usage\": {\n                \"total\": 50,\n                \"projects\": {\n                  \"frontend-team\": 30,\n                  \"mobile-app\": 20\n                }\n              },\n              \"files\": [ //if --deep true is passed\n                \"https://github.com/myorg/myrepo/blob/main/src/components/Header.tsx#L15\",\n                \"https://dev.azure.com/myorg/myproject/_git/myrepo?path=%2Fsrc%2Fcomponents%2FHero.tsx\u0026version=GBmain\u0026line=23\",\n                \"/src/pages/Dashboard.tsx\"]\n            },\n            \"md\": {\n              \"usage\": {\n                \"total\": 25,\n                \"projects\": {\n                  \"frontend-team\": 15,\n                  \"mobile-app\": 10\n                }\n              }\n            }\n          }\n        }\n      }\n    },\n    \"Div\": {\n      \"usage\": {\n        \"total\": 5,\n        \"projects\": {\n          \"frontend-team\": 3,\n          \"mobile-app\": 2\n        }\n      },\n      ...\n    }\n  },\n  \"functions\": {\n    \"useResponsive\": {\n      \"usage\": {\n        \"total\": 12,\n        \"projects\": {\n          \"frontend-team\": 8,\n          \"mobile-app\": 4\n        }\n      },\n      \"values\": {\n        \"useResponsive()\": {\n          \"usage\": {\n            \"total\": 12,\n            \"projects\": {\n              \"frontend-team\": 8,\n              \"mobile-app\": 4\n            }\n          },\n          \"files\": [\n            \"https://github.com/myorg/myrepo/blob/main/src/hooks/responsive.tsx#L10\",\n            \"/src/components/Layout.tsx\"\n          ]\n        }\n      }\n    }\n  },\n  \"types\": {\n    \"ComponentProps\": {\n      \"usage\": {\n        \"total\": 8,\n        \"projects\": {\n          \"frontend-team\": 5,\n          \"mobile-app\": 3\n        }\n      },\n      \"files\": [\n        \"https://github.com/myorg/myrepo/blob/main/src/types/components.ts#L5\",\n        \"/src/utils/props.ts\"\n      ]\n    }\n  }\n}\n```\n\n## Allowed Parameters\n\n| Parameter                  | Description                                                                         | Example                           |\n| -------------------------- | ----------------------------------------------------------------------------------- | --------------------------------- |\n| `-a \u003cfilename\u003e`            | Output analysis results to a JSON file                                              | `-a orbiter-usage.json`           |\n| `-c \u003ccomponents\u003e`          | Specify which components to migrate (`all`, category name, or comma-separated list) | `-c layout`, `-c Div,Text,Button` |\n| `-t \u003cpath\u003e`                | Target path for migration (use current directory if not specified)                  | `-t /app/users`                   |\n| `--project \u003cname\u003e`         | Track usage by project/team (accumulates across runs)                               | `--project frontend-team`         |\n| `--deep true`              | Include file paths for each property value                                          | `--deep true`                     |\n| `--filter-unmapped \u003ctype\u003e` | Filter to show only unmapped items (`components` or `props`)                        | `--filter-unmapped props`         |\n| `--include-ignoreList`     | Include ignored properties (aria-*, data-*, etc.) in analysis                       | `--include-ignoreList`            |\n| `--mappings \u003ctype\u003e`        | Specify which mapping to use for analysis or migration (`orbiter` or `hopper`)      | `--mappings hopper`               |\n| `-n 1`                     | Use single thread for accurate output collection                                    | `-n 1`                            |\n\n**⚠️ Important Notes:**\n\n- Always use `-n 1` when generating analysis output to ensure accuracy\n- Project-specific analysis accumulates results across multiple runs\n- Deep analysis provides detailed file location tracking but may increase processing time\n- Results are automatically sorted by usage frequency (most used first)\n\n## Shimmed components\n\nShimmed components are compatibility layers that bridge the gap between Orbiter and Hopper component implementations.\nThey're designed to ease the migration process by preserving the expected behavior and API of Orbiter components while using Hopper's underlying implementation.\n\nWhen a component's implementation differs significantly between the two design systems, a shim can provide a transitional solution that:\n\n- Maintains backward compatibility with existing Orbiter component usage patterns\n- Preserves complex layout structures and child component relationships\n- Handles prop transformations that can't be handled by simple one-to-one mappings\n- Reduces the need for extensive manual refactoring\n\nShims are particularly useful for complex components where the mental model or component architecture has changed between design systems.\nThey allow you to migrate your codebase incrementally while maintaining functionality.\n\n### Card\n\nOrbiter previously implemented a Card component that handled layout and styling for its children (e.g., Image, Illustration, Heading, Header, Content, Button, ButtonGroup). Hopper’s Card, in contrast, is a simpler styled div.\n\nThis shim bridges the gap between the two implementations, making Hopper’s Card behave like Orbiter’s. It’s intended to ease the migration process by preserving the expected structure and usage from Orbiter.\n\n- [Hopper's Card](https://hopper.workleap.design/components/Card)\n- [Orbiter's Card](https://wl-orbiter-website.netlify.app/?path=/docs/card--docs)\n\nSee the [implementation](src/shims/OrbiterCard.tsx)\nSee the [Stackblitz](https://stackblitz.com/edit/hopper-sandbox-qs8euohl?file=src%2FOrbiterCard.tsx) for examples.\n\n### Transition\n\nOrbiter's Transition component dynamically applies CSS classes to its children based on transition states. Since Hopper doesn't include a transition utility, this shim provides a lightweight implementation that applies the `transition` class to child elements.\n\nThis component serves as a bridge between the two design systems, maintaining compatibility with existing Orbiter code patterns while facilitating a smoother migration to Hopper.\n\n- [Orbiter's Transition](https://wl-orbiter-website.netlify.app/?path=/docs/transition--docs)\n\nSee the [TSX implementation](src/shims/Transition.tsx)\nSee the [CSS implementation](src/shims/Transition.css)\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines on how to contribute to this project.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fworkleap%2Forbiter-to-hopper-codemods","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fworkleap%2Forbiter-to-hopper-codemods","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fworkleap%2Forbiter-to-hopper-codemods/lists"}