stml

internal/stml/generator

STML(Structured Template Markup Language) 파싱 결과를 React TSX 페이지 컴포넌트로 변환. useQuery / useMutation / useForm 훅과 JSX 렌더 트리를 모두 생성한다.

역할 경계

이 패키지가 페이지 .tsx를 먼저 생성하면, react 패키지가 디스크에서 스캔해 라우팅/글루를 조립한다.

진입점

시그니처

func Generate(pages []parser.PageSpec, specsDir, outDir string, opts ...GenerateOptions) (*GenerateResult, error)

• pages — STML 파서가 만든 페이지 스펙.
• specsDir — 원본 STML 파일 경로.
• outDir — 산출 .tsx 출력 경로 (orchestrator가 frontend/src/pages 전달).
• opts — APIImportPath, UseClient 등.

GenerateResult

generate_result.go:6-9

type GenerateResult struct {
    Pages        int                 // 생성된 페이지 수
    Dependencies map[string]string   // npm 패키지 → 버전 범위
}

orchestrator gen_stml.go:45-52 가 이 결과 + pageName 목록 + pageOps(page → 대표 operationID) 를 genapi.STMLGenOutput으로 반환.

호출 경로

orchestrator.genSTML (orchestrator/gen_stml.go:16-58)
  └─ stmlgenerator.GenerateWith(profile.Frontend, pages, specsDir, outDir, opt)
      ├─ os.MkdirAll(outDir)
      ├─ for page in pages:
      │    ├─ code := target.GeneratePage(page, specsDir, opt)
      │    └─ os.WriteFile(outDir/{page.Name}.tsx, code)
      └─ return GenerateResult{Pages, Dependencies: target.Dependencies(pages)}

orchestrator는 APIImportPath: "../api", UseClient: false 를 지정.

Target 추상

target_type.go:9-13

type Target interface {
    GeneratePage(page parser.PageSpec, specsDir string, opts GenerateOptions) string
    FileExtension() string
    Dependencies(pages []parser.PageSpec) map[string]string
}

구현: ReactTarget (react_target_type.go:6-7) — 현재 유일.

페이지 생성 파이프라인

ReactTarget.GeneratePage (react_target_generate_page.go:12-54):

1. collectImports(page, specsDir)               → importSet
2. collectFetchOps(page.Fetches)                 → fetch operationID[] (invalidation용)
3. collectAllActions(page.Children) + dedup      → 중첩 Action 전부 수집
4. renderImports(is, opt)                        → 'use client'?, import 블록
5. export default function <PascalName>() {
6.   renderPageHooks(page, is)                   → useParams, useQueryClient, useQuery들
7.   renderPageMutations(actions, fetchOps)      → useForm + useMutation들 (onSuccess에 invalidation)
8.   renderPageJSX(page)                         → return ( … )
9. }

STML DSL → React 매핑

data-fetch → useQuery

queryKey 조립:

• 'OperationID' + route 파라미터들 + (있으면) page, limit, sortBy, sortDir, filters.

data-action → useMutation

mutationFn:

• 폼 데이터 data + route 파라미터 병합해 api.Op({...data, id}) 호출.

onSuccess:

• fetchOps 각각에 대해 queryClient.invalidateQueries({ queryKey: [op] }) 를 생성.

data-bind → JSX

render_bind_jsx.go:12-17:

{dataVar}.{fieldName} → <span>{dataVar.fieldName}</span>

• dataVar 는 컨텍스트별로 다름:
  • Fetch 자식 내부 → "xxxData" (예: listReservationsData)
  • Each 내부 → "item"
  • Action 폼 내부 → 폼 데이터/정적

data-each → map

render_each_jsx.go:13-38:

{dataVar.items?.map((item: any, index: number) => (
  <div key={index}>
    {/* Children: bind, static, each(중첩) … */}
  </div>
))}

null-safe chaining(?.) + 재귀 처리.

data-state → 조건부 렌더

render_state_jsx.go — 상태값 기반 분기 렌더 (구체는 관련 파일 확인).

중첩 ChildNode 처리

render_child_nodes.go:8-29 가 dispatcher:

Kind → 렌더 함수
──────────────────
bind      → renderBindJSX
each      → renderEachJSX
state     → renderStateJSX
component → renderComponentJSX
static    → renderStaticJSX
action    → renderActionJSX
fetch     → renderFetchJSX (재귀)

훅 렌더링 상세

renderPageHooks (render_page_hooks.go:27)

1. renderUseParams(is)                — const { id, name } = useParams()
2. const queryClient = useQueryClient() (if mutation)
3. renderFetchHooks(page.Fetches)     — useState + useQuery 각각

renderPageMutations (render_page_mutations.go:12-19)

for each action in allActions:
    const xForm = useForm()          (if fields)
    const xMut  = useMutation({ mutationFn, onSuccess })

JSX 구조 렌더링

임포트 수집

importSet (import_set.go:6-16)

type importSet struct {
    react, useQuery, useMutation, useQueryClient bool
    useParams, useForm, useState                 bool
    components []string   // 참조 컴포넌트 목록
    customFile string     // "page-name.custom" 또는 ""
}

Dependencies(pages) (react_target_dependencies.go:7-22) — 각 페이지 importSet을 돌아 npm 패키지 맵 생성:

• useQuery/useMutation/useQueryClient → @tanstack/react-query ^5
• useForm → react-hook-form ^7
• useParams → react-router-dom ^6

파라미터 처리

이름 변환

옵션

GenerateOptions (generate_options.go:6-9)

type GenerateOptions struct {
    APIImportPath string   // default: "@/lib/api"
    UseClient     bool     // default: true ('use client' 디렉티브)
}

DefaultOptions (default_options.go:6-11) / mergeOpt (merge_opt.go:5-11). orchestrator 은 APIImportPath: "../api", UseClient: false 로 오버라이드.

엣지 케이스

결과 예시

import { useState } from 'react'
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
import { useForm } from 'react-hook-form'
import { useParams } from 'react-router-dom'
import { api } from '../api'

export default function MyReservationsPage() {
  const { id } = useParams()
  const queryClient = useQueryClient()
  const [page, setPage] = useState(1)

  const { data: listReservationsData, isLoading, error } = useQuery({
    queryKey: ['ListReservations', id, page],
    queryFn: () => api.ListReservations({ reservationId: id, page, limit: 20 }),
  })

  const createReservationForm = useForm()
  const createReservationMutation = useMutation({
    mutationFn: (data: any) => api.CreateReservation({ ...data, id }),
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ['ListReservations'] })
    },
  })

  return (
    <div>
      {isLoading && <div>로딩 중...</div>}
      {error && <div>오류가 발생했습니다</div>}
      {listReservationsData && (
        <section>
          {listReservationsData.items?.map((item: any, index: number) => (
            <div key={index}>{/* bind/each/static 렌더 */}</div>
          ))}
        </section>
      )}
      <form onSubmit={createReservationForm.handleSubmit((data) =>
        createReservationMutation.mutate(data))}>
        <input {...createReservationForm.register('title')} />
        <button type="submit">제출</button>
      </form>
    </div>
  )
}

파일 맵 (카테고리별)

공개 API

generate.go, generate_page.go, generate_with.go

Target

target_type.go, react_target_type.go, react_target_generate_page.go, react_target_file_extension.go, react_target_dependencies.go, default_target.go

임포트

import_set.go, collect_imports.go, collect_fetch_imports.go, collect_action_imports.go, render_imports.go

훅 (Hook)

render_page_hooks.go, render_fetch_hooks.go, render_use_query.go, render_page_mutations.go, render_use_mutation.go, render_form_hook.go, render_use_params.go

Fetch JSX

render_fetch_jsx.go, render_fetch_jsx_body.go, render_fetch_jsx_flat_children.go, collect_fetch_ops.go

Action / Form JSX

render_action_jsx.go, render_action_form.go, render_action_button.go, render_action_child_nodes.go, render_field_jsx.go

JSX 구조

render_page_jsx.go, render_page_jsx_with_children.go, render_page_jsx_fallback.go, render_child_nodes.go, find_root_element.go

데이터 바인딩

render_bind_jsx.go, render_each_jsx.go, render_state_jsx.go, render_component_jsx.go, render_static_jsx.go, render_static_action_jsx.go

인프라 UI

render_filter_ui.go, render_sort_ui.go, render_pagination_ui.go

파라미터

render_param_args.go, render_infra_api_args.go, param_source_expr.go, extract_route_param_names.go, collect_all_params.go, collect_fetch_param_binds.go

이름 변환 / 유틸

to_component_name.go, to_lower_first.go, to_upper_first.go, cls_attr.go, indent_str.go, or_default.go

옵션

generate_options.go, default_options.go, merge_opt.go

수집 / 기타

collect_all_actions.go, deduplicate_actions.go

설계 메모

• 문자열 빌더 기반 — AST/fmt 사용 안 함. strings.Builder로 TSX 직접 조립.
• Target 확장 여지 — 인터페이스는 있으나 실제 구현은 React만. Vue/Svelte 추가하려면 VueTarget 같은 구현체만 붙이면 됨.
• 의존성 자동화 — importSet 분석이 Dependencies() 결과와 대칭이라 누락 없음.
• 재귀 분기 dispatcher — render_child_nodes.go 의 switch가 모든 DSL 노드 렌더링의 중앙 허브.
• invalidation 자동 배선 — action onSuccess가 모든 페이지 Fetch를 자동 무효화. 명시적 관계 선언 불필요.