Skip to main content

개요

BakeryVideKit 컴포넌트는 vide 기반 UI 레이어를 일관된 패턴으로 구성하기 위해 제공됩니다.
여기서는 새 컴포넌트를 작성할 때 유지해야 하는 기본 구조, 문서 주석, 상태 관리 규칙을 설명합니다.
기존 코드와 동일한 흐름을 따라야 하며, 아래 항목을 지키지 않으면 Moonwave 문서화나 런타임 동작이 깨질 수 있습니다.

공통 구조​

  • 모듈 최상단에는 --[=[ @class … ]=] 형태의 문서 주석을 두고, @tag vide 를 반드시 선언합니다.
    예시:

    --[=[
        @class Button
        @tag vide
        버튼 인터랙션을 처리하는 vide 컴포넌트입니다.
    ]=]

  • vide 런타임 관련 의존성은 항상 상단에 정리합니다: vide(런타임), TableUtil, Maid, DynamicTween 등.

  • local vide = require("@vide") 로 불러온 직후, 실제 사용할 API 만 local create = vide.create, local action = vide.action, local source = vide.source, local effect = vide.effect 처럼 지역 별칭으로 정의합니다. JSX 흉내를 위한 local e = ... 같은 헬퍼는 절대 만들지 않습니다.

  • Context, 다른 컴포넌트, 유틸리티는 블록을 나눠 require 하고, code-style.md 의 순서를 따릅니다.

Props 정의​

  • 모든 컴포넌트는 export type ComponentProps = { … } & BaseProps 형태로 외부에 프로퍼티 타입을 노출합니다.
  • 상위 컴포넌트의 Props 를 확장할 경우 Frame.FrameProps 와 같이 명시적으로 병합합니다.
  • 외부에서 전달받아야 하는 이벤트(OnClick, OnEnter 등)는 콜백 시그니처를 정확히 기록합니다.
  • 내부에서만 사용하는 필드는 컴포넌트 본문에서 frameProps.SomeField = nil 로 제거해 실제 인스턴스로 전달되지 않도록 합니다.

vide 패턴​

  1. 컴포넌트는 local function Component(props: ComponentProps) 처럼 일반 함수로 정의하고, 마지막에 return create("Frame")(frameProps) 혹은 BakeryVideKit 래퍼를 호출해 반환합니다. vide.component 는 사용하지 않습니다.
  2. table.clone(props) 로 원본을 복사해 수정 가능한 사본을 만든 뒤 가공합니다.
  3. TableUtil.merge 를 사용해 기본값, 테마 기반 속성, 사용자 지정 속성을 병합합니다.
  4. Context 접근은 local theme = ThemeContext() 처럼 BakeryVideKit 하위 Context 모듈을 통해 이루어집니다.
  5. Layout 전용 자식은 internalChildren 딕셔너리를 만들어 ListLayout, Padding 등 UIComponent 모듈을 배치합니다.
  6. props.children 은 항상 별도 변수로 분리한 뒤 숫자 인덱스 위치에 table.insert 하여 반환용 props 에 병합합니다. vide.fragment, JSX 스타일 헬퍼, e(...) 패턴은 허용하지 않습니다.
  7. create 호출에서 클래스가 문자열 리터럴이고 props 가 테이블 리터럴이라면 항상 create "Frame" { ... } 처럼 괄호를 생략합니다. 클래스나 props 가 변수/표현식일 때만 create(class)(props) 처럼 괄호를 사용합니다.

상태와 효과​

  • 시각 효과나 입력 상태는 vide.source, vide.effect, vide.action, vide.cleanup 조합으로 구현합니다. 필요한 경우 지역 헬퍼 함수를 만들어도, 내부에서는 이 API 만 사용해야 합니다.
  • Tween 이나 비동기 동작을 사용할 때는 Maid 를 통해 정리하거나, vide.effect 의 정리 함수를 활용합니다.
  • Tooltip 처럼 지연 표시가 필요한 경우 task.delay 호출 전에 guard 플래그(tooltipHovered)를 두어 취소 가능하게 작성합니다.

반환 패턴​

  • 최종 반환은 return create("Frame")(frameProps) 또는 return Frame(frameProps) 처럼 create 기반 호출로 통일합니다. JSX 대용 헬퍼나 e(Component) 패턴은 사용하지 않습니다.
  • UI 컴포넌트 모듈을 사용할 때는 BakeryVideKit 가 노출하는 래퍼(Components.Frame, Components.TextLabel, Components.UIComponent.Padding 등)를 우선 사용하며, 해당 래퍼 내부에서 이미 create 호출을 처리합니다.
  • 내부 children 구성은 internalChildren.SomeChild = create("UIListLayout")({ ... }) 혹은 숫자 인덱스 frameProps[#frameProps + 1] = create("TextLabel")({ ... }) 방식으로 작성합니다.

파일 및 배포 주의사항​

  • 새로운 컴포넌트를 추가하면 Components/init.lua 내에 require · export type 을 반드시 등록합니다.
  • Storybook 용 .story.lua 파일을 추가할 경우, 컴포넌트 폴더 내부에서 Button.story.lua 처럼 별도 파일로 둡니다.
  • Moonwave 문서화가 정상적으로 작동하려면 모든 BakeryVideKit 모듈에 문서 주석과 @tag vide 가 포함되어 있어야 합니다.
  • 변경 후에는 lune run CheckSyntax 와 lune run BuildDocs 를 순서대로 실행해 문법·문서 검사를 통과해야 합니다.