Migrate to v2.x

@toss/tds-mobile v1.x에서 v2.x로 마이그레이션을 하는 방법을 설명해요.

이 가이드가 끝나면

1. major 버전업
   @toss/tds-mobile@^2.0.0이 설치돼요.
2. BREAKING CHANGE를 마이그레이션해요
   컴포넌트 이름 변경, prop 이름 변경 등의 변경사항을 자동으로 처리해요.
3. 일관성 있는 API
   더욱 직관적이고 일관성 있는 컴포넌트 API를 사용할 수 있어요.

변경사항 요약

CLI를 활용한 마이그레이션

이번 마이그레이션에서는 직접 v2로 버전업을 해주셔야 해요.
upgrade 명령어가 아닌^2 버전으로 설치하셔도 괜찮아요.

pnpm up "@toss/tds-mobile*"

기존에 사용했던 TDSMobileBedrockProvider를 TDSMobileAITProvider로 변경할 수 있도록 패키지를 다시 설치해주세요.

pnpm install @toss/tds-mobile-ait
pnpm remove @toss/tds-mobile-bedrock

pnpm exec @toss/tds-mobile-migration tds-v2 --glob="{src,pages}/**/*{tsx,ts}"

glob 옵션에는 마이그레이션할 파일 경로를 glob pattern으로 입력해주세요. 기본 값은 '{src,pages}/**/*.{ts,tsx}'예요.

CLI 마이그레이션 제한사항

예시: 자동 마이그레이션되지 않는 케이스

import type { ComponentProps } from 'react';
import { Button } from '@toss/tds-mobile';
 
// 로컬 래핑 컴포넌트
export const MyButton = (props: ComponentProps<typeof Button>) => {
  return <Button {...props} />;
};
 
// 사용하는 곳 - ❌ 이런 케이스는 CLI에서 변환되지 않아요
function SomeComponent() {
  return (
    <MyButton
      type="primary"            {/* ❌ color로 변환되지 않음 */}
      style="filled"            {/* ❌ variant로 변환되지 않음 */}
      htmlStyle={{ margin: 4 }} {/* ❌ style로 변환되지 않음 */}
    >
      버튼
    </MyButton>
  );
}

수동 처리 방법

로컬 래핑 컴포넌트를 사용하는 경우, 해당 컴포넌트의 변경사항을 참고해서 수동으로 처리해주세요:

// 수동으로 prop 이름을 변경해주세요
function SomeComponent() {
  return (
    <MyButton
      color="primary"          {/* ✅ type → color */}
      variant="filled"         {/* ✅ style → variant */}
      style={{ margin: 4 }}    {/* ✅ htmlStyle → style */}
    >
      버튼
    </MyButton>
  );
}

수동 마이그레이션 가이드

이 아래부터는 수동으로 마이그레이션을 하시는 분을 위해 제공되는 문서예요.

패키지 업데이트

다음 커맨드로 패키지를 업데이트해주세요.

pnpm up "@toss/tds-mobile*"

Badge

속성명이 변경되었어요.

1. type → color

   -<Badge type="blue" style="filled">배지</Badge>
   +<Badge color="blue" variant="filled">배지</Badge>
    
   -<Badge type="teal" style="outlined">배지</Badge>
   +<Badge color="teal" variant="outlined">배지</Badge>

2. style → variant

   -<Badge style="fill">배지</Badge>
   +<Badge variant="fill">배지</Badge>
    
   -<Badge style="weak">배지</Badge>
   +<Badge variant="weak">배지</Badge>

3. htmlStyle → style

   이제 style prop이 variant로 바뀌었으므로, HTML style을 위한 htmlStyle을 다시 style로 변경해야해요.

   -<Badge htmlStyle={{ backgroundColor: 'red' }}>HTML 스타일 배지</Badge>
   +<Badge style={{ backgroundColor: 'red' }}>HTML 스타일 배지</Badge>

4. Paragraph.Badge, Top.SubtitleBadges에도 동일하게 적용

   -<Paragraph.Badge type="yellow" style="fill">경고</Paragraph.Badge>
   +<Paragraph.Badge color="yellow" variant="fill">경고</Paragraph.Badge>
    
   -<Top.SubtitleBadges type="elephant" style="weak">정보</Top.SubtitleBadges>
   +<Top.SubtitleBadges color="elephant" variant="weak">정보</Top.SubtitleBadges>

BoardRow

속성명이 변경되었어요.

1. BoardRow.RightArrow → BoardRow.ArrowIcon

   -<BoardRow.RightArrow />
   +<BoardRow.ArrowIcon />

   -import type { BoardRowRightArrowProps } from '@toss/tds-mobile';
   +import type { BoardRowArrowIconProps } from '@toss/tds-mobile';

BottomCTA / FixedBottomCTA

SubComponent 이름이 변경되었어요.

1. TypeA → Single

   -<BottomCTA.TypeA onClick={handleClick}>단일 버튼</BottomCTA.TypeA>
   +<BottomCTA.Single onClick={handleClick}>단일 버튼</BottomCTA.Single>
    
   -<FixedBottomCTA.TypeA onClick={handleClick}>고정 단일 버튼</FixedBottomCTA.TypeA>
   +<FixedBottomCTA.Single onClick={handleClick}>고정 단일 버튼</FixedBottomCTA.Single>

2. TypeB → Double

   -<BottomCTA.TypeB
   +<BottomCTA.Double
     leftButton={<CTAButton color="secondary">취소</CTAButton>}
     rightButton={<CTAButton color="primary">확인</CTAButton>}
   />
    
   -<FixedBottomCTA.TypeB
   +<FixedBottomCTA.Double
     leftButton={<CTAButton color="secondary">취소</CTAButton>}
     rightButton={<CTAButton color="primary">확인</CTAButton>}
   />

Button

속성명이 변경되었어요.

1. type → color

   -<Button type="primary">버튼</Button>
   +<Button color="primary">버튼</Button>
    
   -<Button type="secondary">버튼</Button>
   +<Button color="secondary">버튼</Button>

2. style → variant

   -<Button style="filled">버튼</Button>
   +<Button variant="filled">버튼</Button>
    
   -<Button style="outlined">버튼</Button>
   +<Button variant="outlined">버튼</Button>

3. htmlType → type

   -<Button htmlType="submit">폼 버튼</Button>
   +<Button type="submit">폼 버튼</Button>

4. htmlStyle → style

   -<Button htmlStyle={{ margin: '10px' }}>스타일 버튼</Button>
   +<Button style={{ margin: '10px' }}>스타일 버튼</Button>

5. size 값 매핑 변경

   T-Shirts 사이즈 prop value로 일관되게 변경했어요.

   1.x	2.x
   tiny	small
   big	xlarge

   -<Button size="tiny">작은 버튼</Button>
   +<Button size="small">작은 버튼</Button>
    
   -<Button size="big">큰 버튼</Button>
   +<Button size="xlarge">큰 버튼</Button>

6. Button 컴포넌트를 확장해 사용하는 다른 컴포넌트들에게도 동일하게 적용

   직접 Button을 확장하는 컴포넌트:

   • ResultButton
   • CTAButton
   • FixedBottomCTA
   • BottomCTA

   Button 기반 컴파운드 컴포넌트:

   • BottomCTA.Single
   • BottomCTA.Double
   • FixedBottomCTA.Double
   • BottomSheet.CTA
   • BottomSheet.DoubleCTA
   • ConfirmDialog.ConfirmButton
   • ConfirmDialog.CancelButton
   • Top.LowerButton
   • Top.RightButton
   • Top.LowerCTAButton

   -<AlertDialog.AlertButton type="primary" style="filled" size="tiny">작은 알럿 버튼</AlertDialog.AlertButton>
   +<AlertDialog.AlertButton color="primary" variant="filled" size="small">작은 알럿 버튼</AlertDialog.AlertButton>
    
   -<AlertDialog.AlertButton type="secondary" style="outlined" size="big">큰 알럿 버튼</AlertDialog.AlertButton>
   +<AlertDialog.AlertButton color="secondary" variant="outlined" size="xlarge">큰 알럿 버튼</AlertDialog.AlertButton>

IconButton

속성명이 변경되었어요.

1. label → aria-label

   ⚠️

   aria-label prop은 IconButton 컴포넌트에서 필수 값이에요. 사용자에게 전달되는 시각적 텍스트가 없는 IconButton의 경우 aria-label이 역할을 전달하는 역할이 됩니다. 마이그레이션 편의를 위해 이번 마이그레이션에서는 빈 값으로 마이그레이션 됩니다.

   -<IconButton label="닫기" />
   +<IconButton aria-label="닫기" />

   -<ListRow.IconButton label="설정" />
   +<ListRow.IconButton aria-label="설정" />

ListRow

값이 최신화되었어요.

1. verticalPadding 값 매핑 변경

   -<ListRow verticalPadding="extraSmall">가장 작은 패딩</ListRow>
   +<ListRow verticalPadding="small">가장 작은 패딩</ListRow>
    
   -<ListRow verticalPadding="small">작은 패딩</ListRow>
   +<ListRow verticalPadding="medium">작은 패딩</ListRow>
    
   -<ListRow verticalPadding="medium">중간 패딩</ListRow>
   +<ListRow verticalPadding="large">중간 패딩</ListRow>
    
   -<ListRow verticalPadding="large">큰 패딩</ListRow>
   +<ListRow verticalPadding="xlarge">큰 패딩</ListRow>

2. 숫자 접미사가 있는 값들도 동일하게 매핑

   -<ListRow verticalPadding="extraSmall-8">8px 패딩</ListRow>
   +<ListRow verticalPadding="small">8px 패딩</ListRow>
    
   -<ListRow verticalPadding="small-16">16px 패딩</ListRow>
   +<ListRow verticalPadding="medium">16px 패딩</ListRow>
    
   -<ListRow verticalPadding="medium-24">24px 패딩</ListRow>
   +<ListRow verticalPadding="large">24px 패딩</ListRow>
    
   -<ListRow verticalPadding="large-32">32px 패딩</ListRow>
   +<ListRow verticalPadding="xlarge">32px 패딩</ListRow>

   숫자 접미사(-8, -16, -24, -32)가 있는 값들도 기본 값과 동일하게 매핑돼요.

TextButton

속성명이 변경되었어요.

1. typography → size

   1.x (typography)	2.x (size)
   t7	xsmall
   t6	small
   t5	medium
   t4	large
   t3	xlarge
   st2	xxlarge

   -<TextButton typography="t7">아주 작은 버튼</TextButton>
   +<TextButton size="xsmall">아주 작은 버튼</TextButton>
    
   -<TextButton typography="t6">작은 버튼</TextButton>
   +<TextButton size="small">작은 버튼</TextButton>
    
   -<TextButton typography="t5">중간 버튼</TextButton>
   +<TextButton size="medium">중간 버튼</TextButton>
    
   -<TextButton typography="t4">큰 버튼</TextButton>
   +<TextButton size="large">큰 버튼</TextButton>
    
   -<TextButton typography="t3">아주 큰 버튼</TextButton>
   +<TextButton size="xlarge">아주 큰 버튼</TextButton>
    
   -<TextButton typography="st2">엄청 큰 버튼</TextButton>
   +<TextButton size="xxlarge">엄청 큰 버튼</TextButton>

   typography prop이 size prop으로 변경되고, 값은 자동으로 매핑돼요.

2. ListHeader, Top, AlertDialog의 TextButton 관련 컴포넌트도 동일하게 적용

   -<ListHeader.TitleTextButton typography="t7">작은 헤더</ListHeader.TitleTextButton>
   +<ListHeader.TitleTextButton size="xsmall">작은 헤더</ListHeader.TitleTextButton>
    
   -<Top.SubtitleTextButton typography="t6">부제목 버튼</Top.SubtitleTextButton>
   +<Top.SubtitleTextButton size="small">부제목 버튼</Top.SubtitleTextButton>
    
   -<AlertDialog.AlertButton typography="t6">확인</AlertDialog.AlertButton>
   +<AlertDialog.AlertButton size="small">확인</AlertDialog.AlertButton>

Top

속성명이 변경되었어요.

1. subtitle1 → subtitleTop

   -<Top subtitle1="상단 부제목">메인 제목</Top>
   +<Top subtitleTop="상단 부제목">메인 제목</Top>

2. subtitle2 → subtitleBottom

   -<Top subtitle2="하단 부제목">메인 제목</Top>
   +<Top subtitleBottom="하단 부제목">메인 제목</Top>

3. 두 개의 subtitle을 함께 사용하는 경우

   -<Top subtitle1="상단 부제목" subtitle2="하단 부제목">메인 제목</Top>
   +<Top subtitleTop="상단 부제목" subtitleBottom="하단 부제목">메인 제목</Top>