Migrate Component

Migrate Component to Core Architecture

Migrate a React-only component to the core/React/Vue architecture pattern.

Usage

/migrate-component <ComponentName>

Example:

/migrate-component Switch
/migrate-component Table

Description

This skill migrates a component (or component family) from React-only implementation to a shared core architecture where:

• Core package (@lumx/core): Contains framework-agnostic UI logic, tests (plain data only, no JSX), and stories (JSX renders using injected framework components)
• React package (@lumx/react): Thin wrapper that delegates to core
• Vue package (@lumx/vue): Thin wrapper that delegates to core

Component Families:

• A component name may refer to a family of components (e.g., "Table" includes Table, TableRow, TableCell, TableBody, TableHeader)
• When migrating a component family, the skill will:
  1. Discover all components in the family by scanning the React folder
  2. Analyze dependencies between components and external dependencies
  3. Determine migration order based on dependencies
  4. Migrate each component in the correct order through all phases

Component Organization:

• Sub-components go in the same folder as their parent component
• Example: Badge and BadgeWrapper both live in the badge/ folder
  • Core: /packages/lumx-core/src/js/components/Badge/ contains both Badge and BadgeWrapper
  • React: /packages/lumx-react/src/components/badge/ contains both Badge.tsx and BadgeWrapper.tsx
  • Vue: /packages/lumx-vue/src/components/badge/ contains both Badge.tsx and BadgeWrapper.tsx
• Example: Table family in the table/ folder
  • Core: /packages/lumx-core/src/js/components/Table/ contains index.tsx (Table), TableRow.tsx, TableCell.tsx, etc.
  • React: /packages/lumx-react/src/components/table/ contains Table.tsx, TableRow.tsx, TableCell.tsx, etc.
  • Vue: /packages/lumx-vue/src/components/table/ contains Table.tsx, TableRow.tsx, TableCell.tsx, etc.
• The folder name uses lowercase-with-dashes (e.g., badge/, table/), while the component names use PascalCase (e.g., Badge, BadgeWrapper, Table, TableRow)

Prerequisites

Before running this skill, ensure:

1. The component exists in @lumx/react and is fully functional
2. The component has existing tests and stories
3. A reference component (like Checkbox) has already been migrated and can serve as a pattern

Phase 0: Discovery & Dependency Analysis

Goal: Discover all components in the family and determine the correct migration order.

IMPORTANT: This phase MUST be completed before starting any migration work.

1. Check for existing core implementation:

   • BEFORE starting migration, check if the component already exists in @lumx/core
   • Read /packages/lumx-core/src/js/components/<ComponentName>/ to see if any files exist
   • Check for existing artifacts:
     • UI files: index.tsx, <SubComponent>.tsx, constants.ts
     • Stories: Stories.tsx (or Stories.ts)
     • Tests: Tests.ts
   • Document what already exists:
     • If core UI implementation exists → Plan to reuse and skip Phase 1 (UI extraction)
     • If core Stories exist → Plan to reuse and skip Phase 2 Step 1 (Core stories creation)
     • If core Tests exist → Plan to reuse and skip Phase 3 Step 2 (Core tests creation)
   • If ANY existing core code is found:
     • Review the existing code to understand its structure
     • USE AskUserQuestion tool to inform the developer about what exists
     • Ask if any changes to the existing core implementation are needed
     • If changes are needed, document them and get approval before proceeding
   • If no core implementation exists, proceed with full migration

2. Discover component family:

   • Read /packages/lumx-react/src/components/<component-name>/index.ts to find all exported components
   • List all .tsx files in the component folder
   • Identify which component is the parent and which are sub-components

3. Analyze dependencies:

   • For each component, check if it imports:
     • Constants from a shared constants.ts file (dependency on parent)
     • Other components from the same folder (dependency on siblings)
     • Components from @lumx/react or @lumx/core (external dependencies)
   • Verify external component dependencies are available in @lumx/core
   • Document any blocking dependencies (components not yet migrated to core)

4. Determine migration order:

   • If there's a constants.ts file, migrate the parent component first (it will create the constants in core)
   • If sub-components import the parent component, migrate the parent first
   • Otherwise, components can be migrated in any order
   • Create a numbered list of components in migration order

5. Present migration plan to developer:

   • Show whether core implementation already exists
   • Show discovered components
   • Show dependency analysis
   • Show proposed migration order
   • List any blocking dependencies
   • If core exists, list any proposed changes to core implementation
   • Ask for confirmation before proceeding

Example for Table family:

Discovered components:
1. Table (parent - defines constants.ts)
2. TableBody (imports TABLE_CLASSNAME from constants)
3. TableCell (imports TABLE_CLASSNAME from constants, uses Icon)
4. TableHeader (imports TABLE_CLASSNAME from constants)
5. TableRow (imports TABLE_CLASSNAME from constants)

Dependencies:
- All sub-components depend on constants.ts (created by Table)
- TableCell uses Icon (already available in core ✓)

Migration order:
1. Table (parent, creates constants)
2. TableBody
3. TableCell
4. TableHeader
5. TableRow

Validation Checkpoint 0:

• Developer is informed about any existing core implementation (UI, Stories, Tests)
• Developer reviews and approves the migration plan
• Developer confirms all external dependencies are available or acceptable to skip
• If changes to existing core code are proposed, developer approves those changes

🛑 IMPORTANT: Validation Checkpoints

This skill has MANDATORY validation checkpoints where you MUST stop and wait for user approval:

• Checkpoint 1: After Phase 1 (UI Implementation) - Verify React/Vue components work
• Checkpoint 2a: After stories migration - Verify React stories in Storybook
• Checkpoint 2b: After Vue stories - Verify Vue stories in Storybook
• Checkpoint 3: After tests migration - Verify all tests pass

At each checkpoint:

1. STOP immediately - Do not continue to the next phase
2. USE the AskUserQuestion tool to present results and ask for approval
3. WAIT for user response - Only proceed when user explicitly approves
4. DO NOT skip or rush through checkpoints - Each validation is critical

Migration Steps

IMPORTANT: After Phase 0 approval, migrate each component in the determined order by going through Phases 1-6 for each component before moving to the next.

Phase 1: UI Extraction & Implementation

Goal: Extract the core UI logic and create thin wrappers for React and Vue.

IMPORTANT - Check for Existing Core Implementation:

• If Phase 0 discovered that core UI implementation already exists, skip steps 1-2 and proceed directly to step 3 (Update React wrapper)
• If any modifications to the existing core implementation are needed:
  • ALWAYS use AskUserQuestion tool BEFORE making any changes to core code
  • Present the proposed changes clearly with rationale
  • Wait for user approval before modifying any core files
• If no core implementation exists, proceed with steps 1-2 to create it

1. Create core component files:

   • If migrating the parent component first (has constants.ts in React):

     packages/lumx-core/src/js/components/<ComponentName>/
     ├── constants.ts (migrate from React)
     └── index.tsx (parent component)
     

   • For standalone components:

     packages/lumx-core/src/js/components/<ComponentName>/
     └── index.tsx
     

   • For sub-components being migrated after parent (e.g., TableRow after Table):

     packages/lumx-core/src/js/components/<ParentComponentName>/
     ├── index.tsx (parent component)
     └── <SubComponentName>.tsx (e.g., BadgeWrapper.tsx)
     

   • Sub-components use separate files (e.g., BadgeWrapper.tsx), not index.tsx

2. Extract UI logic:

   • For parent components with constants.ts:
     • First migrate constants.ts to core (keep exact same structure)
     • Update React imports to use @lumx/core/js/components/<Component>/constants
   • For sub-components:
     • Update imports: import { CLASSNAME as PARENT_CLASSNAME } from './constants' → import { CLASSNAME as PARENT_CLASSNAME } from '@lumx/core/js/components/<Parent>/constants'
   • For all components:
     • Change children prop to label: JSXElement (framework-agnostic)
     • Add required inputId: string prop if needed (generated by wrappers)
     • Use functional JSX calls: InputLabel({ ... }) instead of <InputLabel ... />
     • Remove React-specific code (Children.count, etc.)
     • Check for new callback props (e.g., onCustomEvent, onSpecialAction) defined in core UI
     • If new callbacks are introduced, update PropsToOverride in /packages/lumx-core/src/js/types/jsx/PropsToOverride.ts to include them
     • Export: Component, ComponentProps, COMPONENT_NAME, CLASSNAME, DEFAULT_PROPS (or import from constants if applicable)

3. Update React wrapper:

   • Import UI component from core
   • Import ReactToJSX type utility from @lumx/react/utils/type/ReactToJSX
   • Define props interface using ReactToJSX<UIProps, 'additionalPropsToOmit'> instead of manual Omit
   • Transform into thin wrapper using forwardRef
   • Use hooks: useId, useTheme, useDisableStateProps, useMergeRefs
   • Map children → label for core component
   • Call UI({ ... }) instead of rendering JSX
   • Maintain backward compatibility

4. Create Vue wrapper:

   • For standalone components, create directory structure:

     packages/lumx-vue/src/components/<component-name>/
     ├── <Component>.tsx
     └── index.ts
     

   • For sub-components (e.g., BadgeWrapper alongside Badge), add to existing parent folder:

     packages/lumx-vue/src/components/<parent-component-name>/
     ├── <ParentComponent>.tsx
     ├── <SubComponent>.tsx (e.g., BadgeWrapper.tsx)
     └── index.ts (update to export both components)
     

   • Use defineComponent with render function
   • Use composables: useTheme, useId, useDisableStateProps
   • Support both label prop and default slot
   • Emit events instead of onChange callbacks
   • Use JSX rendering: return (<ComponentUI ... />)
   • Add stop propagation: event.stopImmediatePropagation()
   • Define props using keysOf<ComponentProps>()
   • Set name: 'Lumx<Component>'
   • Set inheritAttrs: false
   • Create index.ts with exports for components and types only:
     • Read the React component's index.ts file for reference
     • Export components and types (props, enums, utilities)
     • Do NOT export CLASSNAME, COMPONENT_NAME, or DEFAULT_PROPS — these are internal constants
     • Vue uses default export for the component: export { default as Component }
     • React uses named export: export { Component }

5. Update Vue package index:

   export * from './components/<component-name>';
   

🛑 MANDATORY Validation Checkpoint 1 - STOP HERE:

• Run yarn test to ensure no regressions
• Run yarn type-check to verify TypeScript compilation
• STOP AND USE AskUserQuestion tool to ask developer for validation:
  • Present test and type-check results
  • Ask: "Phase 1 complete. Please verify React components work correctly and Vue components render basic UI. Should I proceed to Phase 2 (Stories Migration)?"
  • Options: "Yes, proceed" / "No, fix issues first"
• DO NOT PROCEED to Phase 2 until developer selects "Yes, proceed"
• If developer selects "No", fix issues and ask again

Phase 2: Stories Migration

Goal: Create shared core stories with JSX renders and thin framework-specific wrappers.

KEY ARCHITECTURE:

• Core stories use JSX (.tsx file) with framework components injected via a components parameter
• Both React and Vue story files are thin wrappers that pass components and decorators to core, then re-export stories
• No .vue template files for stories — all rendering is done via JSX in core
• No withRender utility — replaced by JSX render functions defined in core
• Keep the same stories — Don't add or remove stories; migrate existing ones only

HOW IT WORKS:

• Core .tsx files use "jsx": "preserve" — the JSX is NOT compiled by core
• When React's build imports the core .tsx file, React's toolchain compiles JSX to React.createElement
• When Vue's build imports it, Vue's toolchain compiles JSX to h() calls
• This means the same JSX code works for both frameworks, as long as it uses injected components (not hardcoded imports from @lumx/react or @lumx/vue)

Step 1: Analyze and Create Core Stories

IMPORTANT - Check for Existing Core Stories:

• If Phase 0 discovered that Stories.ts or Stories.tsx already exists in core, review it and plan changes
• If any modifications to existing core stories are needed:
  • ALWAYS use AskUserQuestion tool BEFORE making any changes
  • Present proposed changes with clear rationale
  • Wait for user approval before modifying core Stories

1. Read and analyze existing React stories:

   • Identify all components used in the stories (Icon, Text, FlexBox, etc.)
   • These components will be passed via the components parameter
   • Identify framework-only stories (e.g., React-only stories using GenericBlock) — these stay in the framework file

2. Create core stories (packages/lumx-core/src/js/components/<ComponentName>/Stories.tsx):

   • File extension is .tsx — JSX is used for render functions
   • Export setup() function that takes { component, components, render, decorators } and returns story configurations
   • The components parameter receives framework-specific component implementations (e.g., { Badge, Icon })
   • Use overrides only when a story needs completely different structure per framework (rare)

   KEY RULES for core stories:

   • NEVER put JSX in args — all JSX must live in render functions. This includes args.children, args.before, args.after, args.badge, and any other prop. JSX in args causes errors in Vue storybook tests (vitest). Only serializable data (strings, numbers, booleans, enums, objects) should be in args.
   • NEVER put JSX in withCombinations rows/sections/cols — combination values are merged into args at runtime, so they have the same restriction. Use render functions to produce JSX for different variants instead.
   • Define each story and meta as individual const variables — this enables stories to reference each other (e.g., WithIcon.render reused by AllTypography). Return them as a flat object: return { meta, StoryA, StoryB, ... }.
   • Stories that need JSX content get their own render function — the render function receives args (serializable data) and returns JSX using the injected framework components.
   • Stories can reuse other stories' render — e.g., AllTypography can set render: WithIcon.render to reuse the same rendering.
   • Composite stories can call other renders — e.g., AllColors can compose {WithText.render(args)}, {WithIcon.render(args)} together.
   • ALWAYS destructure children out of args in render functions — when a render function provides its own inline JSX children, it must destructure children from the args to prevent the inherited children value (from meta.args) from leaking via {...args} onto the component. In Vue, spreading children as a prop on a DOM element causes a "Failed setting prop children" warning because children is a read-only DOM property. Use ({ children, ...args }: any) => instead of (args: any) =>.

   Pattern:

   ```tsx
   import type { SetupStoriesOptions } from '@lumx/core/stories/types';
   import { colorArgType } from '@lumx/core/stories/controls/color';
   import { withUndefined } from '@lumx/core/stories/controls/withUndefined';
   import { mdiHeart } from '@lumx/icons';
   import { ColorPalette } from '../../constants';
   import { DEFAULT_PROPS } from '.';
   
   export function setup({
       component: Badge,
       components: { Icon, Thumbnail, FlexBox },
       decorators: { withCombinations },
   }: SetupStoriesOptions<{
       decorators: 'withCombinations';
       components: { Icon: any; Thumbnail: any; FlexBox: any };
   }>) {
       // Define meta and each story as individual consts
       const meta = {
           component: Badge,
           render: (args: any) => <Badge {...args} />,
           argTypes: {
               color: colorArgType,
           },
           args: DEFAULT_PROPS,
       };
   
       /** Using badge with text children */
       const WithText = {
           // JSX in render, NOT in args
           render: (args: any) => (
               <Badge {...args}>
                   <span>30</span>
               </Badge>
           ),
       };
   
       /** With icon child — uses Icon from injected components */
       const WithIcon = {
           render: (args: any) => (
               <Badge {...args}>
                   <Icon icon={mdiHeart} />
               </Badge>
           ),
       };
   
       /** All color combinations — composes other stories' renders */
       const AllColors = {
           render: (args: any) => (
               <FlexBox orientation="vertical" gap="regular">
                   {WithText.render(args)}
                   {WithIcon.render(args)}
               </FlexBox>
           ),
           argTypes: { color: { control: false } },
           decorators: [
               withCombinations({
                   combinations: {
                       // Only serializable data in combinations — NO JSX
                       cols: { key: 'color', options: withUndefined(ColorPalette) },
                   },
               }),
           ],
       };
   
       // Return flat object with all consts
       return { meta, WithText, WithIcon, AllColors };
   }
   ```
   

   More examples of the pattern:

   When a story just needs different args (no JSX), it doesn't need a custom render:

   ```tsx
   /** Story with only serializable args — inherits meta render */
   const Disabled = {
       args: { isDisabled: true },
   };
   ```
   

   When multiple stories share the same render:

   ```tsx
   /** Text with inline icons — destructure children to prevent leaking from meta.args */
   const WithIcon = {
       render: ({ children, ...args }: any) => (
           <Text {...args}>
               Some text <Icon icon={mdiHeart} /> with icons <Icon icon={mdiEarth} />
           </Text>
       ),
   };
   
   /** All typographies — reuses WithIcon's render */
   const AllTypography = {
       render: WithIcon.render,
       argTypes: { typography: { control: false } },
       decorators: [
           withCombinations({
               combinations: {
                   rows: { key: 'typography', options: withUndefined(ALL_TYPOGRAPHY) },
               },
           }),
       ],
   };
   ```
   

   When a component has slot-like props (before, after, badge), put the JSX in render, not args:

   ```tsx
   const DefaultRender = render || ((args: any) => <Toolbar {...args} />);
   
   /** Toolbar with all content areas */
   const WithAll = {
       render: () => (
           <DefaultRender
               before={<Icon icon={mdiMenu} />}
               after={<Icon icon={mdiMagnify} />}
               label="Page title"
           />
       ),
   };
   ```
   

Step 2: Implement React Stories

3. Update React stories to use core setup:

   • Import setup from core stories

   • Pass framework components via components and decorators via decorators

   • Export each story as a thin re-export: export const StoryName = { ...stories.StoryName };

   • Add framework-only stories (using components not available in core) as separate exports

   • Pattern:

     import { Badge, Icon } from '@lumx/react';
     import { withCombinations } from '@lumx/react/stories/decorators/withCombinations';
     import { setup } from '@lumx/core/js/components/Badge/Stories';
     
     const { meta, ...stories } = setup({
         component: Badge,
         components: { Icon },
         decorators: { withCombinations },
     });
     
     export default {
         title: 'LumX components/badge/Badge',
         ...meta,
     };
     
     export const WithText = { ...stories.WithText };
     export const WithIcon = { ...stories.WithIcon };
     export const AllColors = { ...stories.AllColors };
     
     // Framework-only story (uses components not in core setup)
     export const WithThumbnail = {
         args: {
             children: <Thumbnail ... />,
         },
     };
     

🛑 MANDATORY Validation Checkpoint 2a - STOP HERE:

• Run yarn type-check to verify TypeScript compilation
• STOP AND USE AskUserQuestion tool to ask developer for validation:
  • Present type-check status
  • Ask: "React stories migrated. Please verify ALL React stories render correctly in Storybook. Should I proceed to create Vue stories?"
  • Options: "Yes, proceed to Vue stories" / "No, fix issues first"
• DO NOT PROCEED to Vue stories until developer selects "Yes, proceed to Vue stories"
• If developer selects "No", fix issues and ask again

Step 3: Implement Vue Stories

4. Create Vue stories as thin wrapper (.tsx file):

   • Import setup from core stories
   • Pass Vue framework components via components and Vue decorators via decorators
   • Export each story as a thin re-export — identical structure to React
   • No .vue template files needed — all rendering handled by JSX in core
   • IMPORTANT: Provide a render override when the Vue component uses slots instead of props. Since core stories now put JSX in render functions (not args), the render override maps slot-like props to Vue slots when the core render passes them as JSX props/children.

   Pattern A — Default slot only (e.g., children or label prop → default slot):

   ```tsx
   import { Flag } from '@lumx/vue';
   import { setup } from '@lumx/core/js/components/Flag/Stories';
   
   const { meta, ...stories } = setup({
       component: Flag,
       // Destructure `label` out of args and pass it as default slot (JSX children)
       render: ({ label, ...args }: any) => <Flag {...args}>{label}</Flag>,
       decorators: { /* ... */ },
   });
   ```
   

   Pattern B — Named slots (e.g., before, after, label → named slots):

   ```tsx
   import { Toolbar, Icon } from '@lumx/vue';
   import { setup } from '@lumx/core/js/components/Toolbar/Stories';
   
   const { meta, ...stories } = setup({
       component: Toolbar,
       components: { Icon },
       // Map props to Vue named slots using Vue JSX slot object syntax
       render: ({ label, before, after, ...args }: any) => (
           <Toolbar {...args}>
               {{
                   default: label ? () => label : undefined,
                   before: before ? () => before : undefined,
                   after: after ? () => after : undefined,
               }}
           </Toolbar>
       ),
   });
   ```
   

   Pattern C — No slot mapping needed (core render handles everything):

   When the core stories already handle all JSX in their own render functions (the new default pattern), and the Vue component doesn't need slot mapping because the core render directly renders the component with children via JSX, no render override is needed:

   ```tsx
   import { Badge, FlexBox, Icon, Thumbnail } from '@lumx/vue';
   import { withCombinations } from '@lumx/vue/stories/decorators/withCombinations';
   import { setup } from '@lumx/core/js/components/Badge/Stories';
   
   const { meta, ...stories } = setup({
       component: Badge,
       components: { Icon, Thumbnail, FlexBox },
       decorators: { withCombinations },
       // No render override needed — core stories already define render per story
   });
   ```
   

   How to decide which pattern to use:

   1. Check the core Stories.tsx — if stories define their own render functions that directly render the component with JSX children (the new pattern), Vue usually doesn't need a render override (Pattern C)
   2. If the core stories use a shared meta.render that receives slot-like content via args (e.g., label, before, after), the Vue side needs to map those to slots (Pattern A or B)
   3. Read the Vue component's .tsx file and check if it accesses slots (e.g., slots.default?.(), slots.before?.())
   4. If it uses slots.default?.() only → use Pattern A
   5. If it uses named slots (e.g., slots.before?.(), slots.after?.()) → use Pattern B
   6. If core stories already handle rendering inline (each story has its own render) → use Pattern C

   Full example with re-exports:

   ```tsx
   import { Badge, FlexBox, Icon, Thumbnail } from '@lumx/vue';
   import { withCombinations } from '@lumx/vue/stories/decorators/withCombinations';
   import { setup } from '@lumx/core/js/components/Badge/Stories';
   
   const { meta, ...stories } = setup({
       component: Badge,
       components: { Icon, Thumbnail, FlexBox },
       decorators: { withCombinations },
   });
   
   export default {
       title: 'LumX components/badge/Badge',
       ...meta,
   };
   
   export const WithText = { ...stories.WithText };
   export const WithIcon = { ...stories.WithIcon };
   export const AllColors = { ...stories.AllColors };
   ```
   

🛑 MANDATORY Validation Checkpoint 2b - STOP HERE:

• Run yarn test to ensure no regressions
• Run yarn type-check to verify TypeScript compilation
• STOP AND USE AskUserQuestion tool to ask developer for validation:
  • Present test and type-check results
  • Ask: "All Vue stories complete. Please verify ALL Vue stories render correctly in Storybook. Should I proceed to Phase 3 (Tests Migration)?"
  • Options: "Yes, proceed to Phase 3" / "No, fix issues first"
• DO NOT PROCEED to Phase 3 until developer selects "Yes, proceed to Phase 3"
• If developer selects "No", fix issues and ask again

Phase 3: Tests Migration

Goal: Extract core tests and update framework-specific test suites.

IMPORTANT RULES:

• NO JSX ELEMENTS or component calls in core tests - Use plain data only
• NO interaction/event tests in core - Core tests should only test rendering, props, and DOM structure
• Event handler tests belong in React/Vue - Test onClick interactions in React tests, test emit('click') in Vue tests
• Tests that need component children must use framework-specific setup - Don't migrate those to core
• Vue tests should mimic React tests - Include the same structure: core tests import, framework-specific describe block, and commonTestsSuiteVTL (Vue) or commonTestsSuiteRTL (React)
• DO NOT add NOTE comments or explanatory comments in generated files - Keep code clean without meta-commentary

IMPORTANT - Check for Existing Core Tests:

• If Phase 0 discovered that Tests.ts already exists in core, skip step 2 and proceed to step 3 (React tests update)
• If any modifications to existing core tests are needed:
  • ALWAYS use AskUserQuestion tool BEFORE making any changes
  • Present proposed changes with clear rationale
  • Wait for user approval before modifying core Tests.ts

1. Read and analyze existing React tests:

   • Identify tests that use plain data (strings, numbers, etc.) - these can migrate to core
   • Identify tests that use JSX components (Icon, Thumbnail, etc.) - these stay in React/Vue only
   • Document which tests cannot be migrated due to component dependencies

2. Create core tests (packages/lumx-core/src/js/components/<ComponentName>/Tests.ts):

   • NO JSX ELEMENTS or component calls allowed - Use plain data only

   • Export setup() function that takes props and SetupOptions

   • Export default test suite function that receives SetupOptions and contains describe/it blocks

   • Only migrate tests that use plain data (strings, numbers, booleans)

   • Follow the Button pattern exactly

   • Example pattern:

     import { getByClassName } from '../../../testing/queries';
     import { SetupOptions } from '../../../testing';
     import { ColorPalette } from '../../constants';
     
     const CLASSNAME = 'lumx-badge';
     
     /**
      * Mounts the component and returns common DOM elements / data needed in multiple tests further down.
      */
     export const setup = (propsOverride: any = {}, { render, ...options }: SetupOptions<any>) => {
         const props = { ...propsOverride };
         const wrapper = render(props, options);
     
         const badge = getByClassName(document.body, CLASSNAME);
         return { props, badge, wrapper };
     };
     
     export default (renderOptions: SetupOptions<any>) => {
         const { screen } = renderOptions;
     
         describe('Badge core tests', () => {
             describe('Props', () => {
                 it('should use default props', () => {
                     const { badge } = setup({ children: '30' }, renderOptions);
     
                     expect(badge.className).toContain('lumx-badge');
                     expect(badge.className).toContain('lumx-badge--color-primary');
                     expect(badge).toHaveTextContent(/30/);
                 });
     
                 it('should render color', () => {
                     const { badge } = setup({ children: 'Badge', color: ColorPalette.red }, renderOptions);
                     expect(badge).toHaveClass('lumx-badge--color-red');
                 });
             });
         });
     };
     

3. Update React tests:

   • Import default export from core tests (the test suite)

   • Call the test suite with { render, screen } options

   • Keep React-specific tests (ref forwarding, theme context, JSX children)

   • Keep commonTestsSuiteRTL (React-specific)

   • Example pattern:

     import { commonTestsSuiteRTL } from '@lumx/react/testing/utils';
     import { getByClassName } from '@lumx/react/testing/utils/queries';
     import { render, screen } from '@testing-library/react';
     import { Badge, BadgeProps } from './Badge';
     import BaseBadgeTests from '@lumx/core/js/components/Badge/Tests';
     
     const CLASSNAME = Badge.className as string;
     
     const setup = (propsOverride: Partial<BadgeProps> = {}) => {
         const props: BadgeProps = {
             children: <span>30</span>,
             ...propsOverride,
         };
         render(<Badge {...props} />);
         const badge = getByClassName(document.body, CLASSNAME);
         return { badge, props };
     };
     
     describe(`<${Badge.displayName}>`, () => {
         // Run core tests
         BaseBadgeTests({
             render: (props: BadgeProps) => render(<Badge {...props} />),
             screen,
         });
     
         // React-specific tests
         describe('React', () => {
             it('should render empty children', () => {
                 const { badge } = setup({ children: null });
                 expect(badge).toBeInTheDocument();
                 expect(badge).toBeEmptyDOMElement();
             });
         });
     
         // Common tests suite
         commonTestsSuiteRTL(setup, {
             baseClassName: CLASSNAME,
             forwardClassName: 'badge',
             forwardAttributes: 'badge',
             forwardRef: 'badge',
         });
     });
     

4. Create Vue tests (packages/lumx-vue/src/components/<component-name>/<Component>.test.ts):

   • IMPORTANT: Vue tests should mimic React tests exactly - Same structure with core tests, framework describe, and commonTestsSuite

   • Import default export from core tests (the test suite)

   • Import and use the core setup function

   • Call the test suite with render function that converts children to slots

   • Create a local setup function that wraps the core setup

   • Add commonTestsSuiteVTL (Vue equivalent of React's commonTestsSuiteRTL)

   • Add Vue-specific tests (emit events, disabled states) if needed

   • Use @testing-library/vue

   • Example pattern:

     import { render, screen } from '@testing-library/vue';
     import BaseBadgeTests, { setup } from '@lumx/core/js/components/Badge/Tests';
     import { CLASSNAME } from '@lumx/core/js/components/Badge';
     import { commonTestsSuiteVTL, SetupRenderOptions } from '@lumx/vue/testing';
     
     import { Badge } from '.';
     
     describe('<Badge />', () => {
         const renderBadge = ({ children, ...props }: any, options?: SetupRenderOptions<any>) =>
             render(Badge, {
                 ...options,
                 props,
                 slots: children ? { default: children } : undefined,
             });
     
         // Run core tests
         BaseBadgeTests({
             render: renderBadge,
             screen,
         });
     
         const setupBadge = (props: any = {}, options: SetupRenderOptions<any> = {}) =>
             setup(props, { ...options, render: renderBadge, screen });
     
         // Common tests suite
         commonTestsSuiteVTL(setupBadge, {
             baseClassName: CLASSNAME,
             forwardClassName: 'div',
             forwardAttributes: 'div',
             forwardRef: 'div',
         });
     });
     

🛑 MANDATORY Validation Checkpoint 3 (Tests) - STOP HERE:

• Run yarn test to ensure all tests pass
• Run yarn type-check to verify TypeScript compilation
• Verify core tests use only plain data (no JSX)
• Verify framework-specific tests remain in React/Vue
• STOP AND USE AskUserQuestion tool to ask developer for validation:
  • Present test results (number of tests passing)
  • Ask: "Phase 3 complete. All tests migrated and passing. Should I proceed to Phase 4 (Update CHANGELOG and verify builds)?"
  • Options: "Yes, proceed to finalization" / "No, fix issues first"
• DO NOT PROCEED to Phase 4 until developer selects "Yes, proceed to finalization"
• If developer selects "No", fix issues and ask again

Important Notes:

• Tests with framework-specific rendering behavior (e.g., empty children) should stay in framework test files
• Vue uses slots for children, so the render helper must convert children prop to slots.default
• React renders empty for null children, Vue renders comment nodes <!---->
• Vue tests should include commonTestsSuiteVTL to match React's commonTestsSuiteRTL structure
• Core setup() function should return aliases if needed (e.g., const div = badge;) for commonTestsSuite compatibility

Phase 4: Update Package Exports

Verify React package already exports component

Phase 5: Update CHANGELOG

IMPORTANT: Complete this phase ONCE for the entire component family after all components are migrated.

Add entry under [Unreleased]:

For single component:

### Added

-   `@lumx/vue`:
    -   Create the `<Component>` component

### Changed

-   `@lumx/core`:
    -   Moved `<Component>` from `@lumx/react`

For component family:

### Added

-   `@lumx/vue`:
    -   Create the `<Component>` component family (`<Component>`, `<SubComponent1>`, `<SubComponent2>`, etc.)

### Changed

-   `@lumx/core`:
    -   Moved `<Component>` component family from `@lumx/react` (`<Component>`, `<SubComponent1>`, `<SubComponent2>`, etc.)

Example for Table:

### Added

-   `@lumx/vue`:
    -   Create the `Table` component family (`Table`, `TableBody`, `TableCell`, `TableHeader`, `TableRow`)

### Changed

-   `@lumx/core`:
    -   Moved `Table` component family from `@lumx/react` (`Table`, `TableBody`, `TableCell`, `TableHeader`, `TableRow`)

Phase 6: Final Build Verification

IMPORTANT: After completing Phases 1-5 for ALL components in the family, perform final verification.

1. Build packages:

   yarn build:core
   yarn build:react
   yarn build:vue
   

2. Final smoke test:

   • Run full test suite: yarn test
   • Verify all builds succeed
   • Check Storybook for any console errors
   • Verify all components in the family work together correctly

3. Validate React/Vue parity:

   • CRITICAL: Check that all tests and stories are properly matched between React and Vue

   • For each component in the family:

     Stories validation:

     • Verify every .stories.tsx file in React has a corresponding .stories.tsx file in Vue
     • Read both story files and compare exported story names
     • Ensure all React stories have Vue equivalents (e.g., Default, WithHeader, AllStates)
     • Both should be thin wrappers calling the same core setup() with identical structure
     • Example check:

       # React stories
       ls packages/lumx-react/src/components/<component-name>/*.stories.tsx
       # Vue stories
       ls packages/lumx-vue/src/components/<component-name>/*.stories.tsx
       

     Tests validation:

     • Verify every .test.tsx file in React has a corresponding .test.ts file in Vue
     • Read test files and compare test structure:
       • Core tests are imported and run in both React and Vue
       • Framework-specific describe blocks exist in both (React/Vue)
       • commonTestsSuiteRTL (React) has equivalent commonTestsSuiteVTL (Vue)
       • React-specific tests have Vue-specific equivalents where appropriate
     • Check `commonTests

…(truncated)