[OSCCA] 4. devUP UI : MDX 코드 블록이 모바일에서 넘칠 때, 반응형 그리드로 해결하기

👉 PR 바로가기 👈

Fix: Code block overflow on mobile in N/M Base docs using responsive grid by arty0928 · Pull Request #476 · dev-five-git/devup

들어가며

오픈소스 컨트리뷰션 아카데미에서 Table 반응형 좌우 스크롤 문제를 해결하는 도중, 반응형 환경에서의 다른 페이지는 어떤가 확인해보았습니다. 이 과정에서 다른 페이지의 반응형 환경에서 code 블럭이 계속 2열로 정렬되어 있어 화면 너비를 넘어가는 문제를 발견했습니다. 

---

기존 코드

### **Basic Class Names**

<div
  style={{
    display: 'grid',
    gridTemplateColumns: '1fr 1fr',
    gap: '2rem',
    marginBottom: '2rem',
    alignItems: 'start',
  }}
>
  <div>
    ```tsx // Input
    <div>
      <Box bg="red" />
      <Box bg="blue" />
      <Box color="white" />
    </div>
    ```
  </div>
  <div>
    ```tsx // Output (N/M base class names)
    <div>
      <Box className="a" /> {/* bg: red */}
      <Box className="b" /> {/* bg: blue */}
      <Box className="c" /> {/* color: white */}
    </div>
    ```
  </div>
</div>

 

 

원인

    gridTemplateColumns: '1fr 1fr',

 

이 부분에서 1fr 1fr로 되어 있어서 화면 크기에 상관없이 항상 동일한 너비 열을 생성하도록 되어 있어, 작은 화면에서 CodeBlock이 overflow 되는 문제였습니다.

 

✅1fr

fr = fraction (분수, 비율) 의 약자
사용 가능한 공간을 비율로 나누는 단위

1fr = 사용 가능한 공간의 1 비율
1fr 1fr = 공간을 1:1 비율로 나눠서 2개의 열 생성

 

해결 방법

먼저 제가 생각한 방법은

 

1. 미디어 쿼리

기존 웹 화면에서는 너비를 1:1 코드 블럭을 위치시키고, 반응형에서는 2열이 아니라 세로로 정렬되도록 하려고 했습니다. 

그런데 제가 기여하는 devup UI는 zero-tuntime CSS - in -JS 라이브러리인데 런타임에 미디어 쿼리 처리 방식 확인이 필요하다는 모순이 생겼습니다... 

그런데 파일을 계속 찾아보니 libs.extractor/src/css_utils.rs 파일에서 미디어 쿼리를 확인할 수 있었습니다. 즉, devupUI는 이미 미디어 쿼리를 지원하고 있었습니다.

 

2. CSS Grid의 함수인 repeat

2번째 방법은 기존 JS의 repeat이  아닌, CSS 전용 문법인 repeat 이었습니다.  

<Box css={{ gridTemplateColumns: 'repeat(auto-fit, minmax(300px, 1fr))' }}>

 

• auto-fit
  • 그리드 컨테이너의 너비에 맞춰 들어갈 수 있는 만큼 자동으로 칸을 채우고
• minmax(300px, 1fr)
  • 각 칸의 최소 너비를 300px, 최대는 남는 공간을 균등분배(1fr) 하도록 했습니다.

 

즉, 화면 크기에 따라 300px 이상의 카드가 들어갈 수 있는 만큼 자동으로 여러 칸으로 배치되도록 생각했습니다. 

 

 

그러나 Box 컴포넌트를 MDX 파일에서 사용할 수 없었습니다.

Box 컴포넌트가 @devup-ui/react에서 client component로만 동작하도록 작성되어 있었기 때문에 MDX 파일에서 Box 를 사용하기 위해 import 하면 , App Router 환경에서 기본적으로 서버 컴포넌트로 처리됩니다.

즉, 서버 컴포넌트에서는 client-only 코드를 실행할 수 없으므로 throw new Error("Cannot run on the runtime") 가 발생합니다.

 

3. 조건부 스타일

<Box css={{ gridTemplateColumns: window.innerWidth < 768 ? '1fr' : '1fr 1fr' }}>

 

이 코드는 런타임에 계산하고, 리사이즈 감지하는 추가 로직이 필요합니다.

+ 불필요한 리렌더링이 발생하기 때문에 조금 더 좋은 방법을 찾기로 했습니다.

 

 

4. 아예 Box 컴포넌트에 gridColoums 속성을 추가

기존에 있는 Box 컴포넌트에 반응형에서도 내부 속성이 화면 너비를 넘어가지 않게 정렬해주는 속성을 추가하는 방법입니다. 물론 학습 곡선이 있겠지만 확장성이나 유지보수성 측면에서 이것도 추가하면 더 좋을 것 같았습니다.

 

그럼 우선 Box 컴포넌트 속성을 확인해보겠습니다.

 

Box 컴포넌트에 ctrl 을 누른 후 클릭하면서 따라가다보니 아래 코드를 발견했습니다.

export type DevupCommonProps = Merge<
  {
    [K in keyof Properties]?: ResponsiveValue<Properties[K]>
  },
  DevupShortcutsProps
>

 

모든 CSS 속성이 ResponsiveValue로 감싸지고 있습니다. 즉, Box 가 반응형 배열을 이미 지원하고 있었습니다.

 

ResponsiveValue 코드는 아래처럼 작성되어 있습니다.

type Value<T> = T | null | undefined | false
export type ResponsiveValue<T> = 0 extends T
  ? Value<number | T> | Value<number | T>[]
  : Value<T> | Value<T>[]

 

그러면 이미 기존 Box가 반응형 배열을 지원하고 있기 때문에 이것을 사용하되, 기존 div 태그들로 작성된 코드들을 Box로 변경하여 재사용성과 전체 코드 통일성을 높여보겠습니다.

 

이 과정에서 이런 에러가 발생했습니다

## Error Type
Runtime Error

## Error Message
Cannot run on the runtime


    at o (..\..\packages\react\dist\components\Box.js:2:9)

## Code Frame
  1 | function o(n) {
> 2 |   throw new Error("Cannot run on the runtime");
    |         ^
  3 | }
  4 | export {
  5 |   o as Box

Next.js version: 16.0.0 (Turbopack)

 

원인은 Box 컴포넌트는 빌드 타임 전용 컴포넌트인데, MDX 파일은 런타임에 실행되고 있기 때문입니다.

 

Box 컴포넌트에 대한 이해가 부족한 것 같아 devup UI 동작을 다시 찾아보았습니다.

1. devup UI 컴파일러가 빌드 타임에
2. Box 컴포넌트를 <div className = "a b c"> 형태로 변환
3. 런타임에는 일반 HTML만 존재

 

 그러니까 기존 아래 코드는

// src/components/MyComponent.tsx
import { Box } from '@devup-ui/react'

export function MyComponent() {
  return (
    <Box display="grid" gridTemplateColumns={['1fr', '1fr 1fr']}>
      <div>A</div>
      <div>B</div>
    </Box>
  )
}

 

빌드 후에 이렇게 처리됩니다.

// 컴파일 후
export function MyComponent() {
  return (
    <div className="a b c">  {/* Box가 사라짐! */}
      <div>A</div>
      <div>B</div>
    </div>
  )
}

 

그런데 이전 TableProps를 전달해서 Table 컴포넌트를 사용했던 mdx 파일에서는 문제가 없었습니다.

 

 

가능성은 2가지입니다.

 

1. PropsTable.tsx 도 devUP 컴파일러를 거친다.

✅PropsTable.tsx → DevupUI 컴파일러 → Box가 div로 변환 → 작동

 

2. PropsTable은 서버 컴포넌트라 빌드 타임에만 실행

✅빌드 타임에 실행 → DevupUI 컴파일 → HTML 생성 → 런타임에는 HTML만 → 작동

 

propsTable은 왜 되는지 정확하게 알아야 왜 Box 반응형이 안되는지 확인할 수 있기 때문에 위 2가지 이유 중 propsTable이 mdx에서 컴포넌트를 가져와서 사용할 수 있는 이유를 확인했습니다.

 

 

propsTable은 mdx파일에서 작동하는 이유 찾기

1. 테스트
   일반 .tsx 파일에서 Box 컴포넌트를 만들고 mdx 파일에서 해당 TestBox 컴포넌트를 import 했습니다.

// components/TestBox.tsx
import { Box } from '@devup-ui/react'

export function TestBox() {
  return (
    <Box display="grid" gridTemplateColumns={['1fr', '1fr 1fr']}>
      <div>Test 1</div>
      <div>Test 2</div>
    </Box>
  )
}

 

//mdx 파일
import { TestBox } from '@/components/TestBox'

<TestBox />

 

⇒  빌드 에러가 발생했습니다.

 

⇒ MDX 파서가 JSX 배열 문법을 파싱하지 못하는 에러

 

MDX는 js 코드를 파싱할 때 js 파서인 acorn을 사용하는데,

<TestBox />

 

TestBox 내부의:

gridTemplateColumns={['1fr', '1fr 1fr']}  // ← 이 배열 문법을 파싱 못 함!

 

⇒ 즉 반응형 배열 같은 특수 문법이 MDX 파서와 충돌하는 것이었습니다

  

⇒ PropsTable이 제대로 동작하는 이유는 단순 문자열 props 만 사용하여, 배열 객체 같은 복잡한 표현식이 없었기 때문입니다.

 

PropsTable.tsx 
  ↓
1. DevupUI 컴파일러가 빌드 타임에 처리
  ↓
2. Box → <div className="xxx"> 변환
  ↓
3. 서버 컴포넌트로 빌드 타임에 실행
  ↓
4. HTML 생성
  ↓
5. 런타임에는 순수 HTML만 전달

// 1단계: DevupUI 컴파일 (빌드 타임)
<Box maxWidth="100%">  // 단순 문자열만
  ↓
<div className="abc">

// 2단계: 서버 컴포넌트 실행 (빌드 타임)
async function PropsTable() { ... }
  ↓
HTML 생성

// 3단계: MDX에서 사용 (런타임)
<PropsTable />  // 이미 HTML이므로 문제없음

 

반면 TestBox가 안되는 이유는

// MDX에서
import { TestBox } from './TestBox'
<TestBox />

// MDX 파서 단계
  ↓
acorn이 TestBox 내부를 분석 시도
  ↓
{['1fr', '1fr 1fr']} 발견
  ↓
"이게 뭐야?" (SyntaxError) ❌
  ↓
중단

 

 

해결책 점검

그렇다면 지금까지 제가 생각한 방법 4가지 중

 

1. 미디어 쿼리 

devup UI는 빌드 타임에 미디어 쿼리를 지원하고 있으므로, 우리가 굳이 js로 화면 크기를 계산해서 적용할 필요가 없지만, MDX 파일 안에서 JS 배열 → 런타임 계산 으로 오류가 날 수 있었습니다.

 

2. repeat

이 방법은 가장 빠르게 적용할 수 있었지만, 클라이언트 컴포넌트인 Box 컴포넌트를 서버 컴포넌트로 실행되는 MDX 파일에서 사용하면 에러가 발생합니다.

 

3. 조건부 스타일

런타임에서 JS로 화면 너비를 읽어 스타일을 바꾸기 때문에 MDX/zero-runtime 철학과 완전 충돌하는 문제가 발생합니다.

 

4. Box 컴포넌트의 GridColumns 속성 추가 

즉 MDX 파서(acorn)가 배열 기반 반응형 표현식을 이해하지 못하기 때문에 런타임 에러가 발생했습니다. Box 자체는 빌드 타임 전용이지만 MDX에서 런타임에 JSX 배열/객체 props를 처리할 수 없습니다. 따라서 MDX 문서에서는 gridColumns 속성을 넣는 방법은 사용할 수 없었습니다.

 

즉, 모든 방법이 에러가 나고, 적합하지 않다고 파악했습니다.

---

MDX 레이아웃 없이 콘텐츠만 전달하고, 레이아웃 Box는 .tsx에서 처리해야 할까?

아예 다른 접근 방식을 생각했습니다. 문서 정리 카테고리가

1. devupUI 를 소개하는 페이지
2. devupUI의 컴포넌트 예시 페이지

가 있는데 2번의 경우 page를 렌더링하고 mdx 파일에서는 레이아웃 없이 콘텐츠만 page 파일로 넘기고 있습니다.

 

아키텍처 설계에 대한 고민…

1번도 2번처럼 할 까 고민이 되었습니다. 2번의 경우,

• Example 섹션
• API 섹션

등 공통 형식이 있고, 코드 블록이 각각 들어가므로 템플릿으로 작성하면 편했습니다.

하지만 1번의 경우 단순 글자만 있고 코드 블록이 없는 곳도 있어서 2번처럼 형식이 정해진 것이 아니었기 때문에 1번 docs 중 한개의 페이지만을 위해서 다 고치는 것이 맞을까? 하는 고민이 들었습니다.

button 문서에서는 아래 코드처럼 Grid 컴포넌트를 사용한 것을 확인했습니다. 따라서 이미 있는 Grid 컴포넌트를 활용해서 작성해보겠습니다.

import { Center, css, Flex, Grid, Text, VStack } from '@devup-ui/react'
...
export default function Page() {
  return (
    <VStack gap="16px">
    ...
        <Grid
          gap={['10px', null, null, null, '20px']}
          gridTemplateColumns={[
            'repeat(1, 1fr)',
            'repeat(3, 1fr)',
            null,
            'repeat(4, 1fr)',
            'repeat(5, 1fr)',
          ]}
        >
       ....
      </VStack>
    </VStack>
  )
}

ExampleGridProps

그럼 ExampleGridProps의 속성에서 열의 개수가 유연하게 변동될 수 있으니 cols로 속성값을 만들까? 처음에 고민했습니다.

interface ExampleGridProps {
  children: ReactNode
  cols?: number | number[]
}

 

이런식으로 고민했으나, children에 ReactNode 자체가 React가 렌더링할 수 있는 모든 것을 나타내므로 children에 단일 요소, 배열 같은 여러 요소, 텍스트나 요소들을 혼합해서도 모두 ReactNode로 표현이 가능하다는 것을 깨달았습니다.

type ReactNode = 
  | ReactElement        // <div>, <Component />
  | string              // "hello"
  | number              // 42
  | boolean             // true, false
  | null                // null
  | undefined           // undefined
  | ReactNode[]         // [<div />, "hello", 123]
  | ReactPortal
  | Iterable<ReactNode>

 

즉 ReactNode로만 넘겼을 때는 아래 그림처럼 3개가 와도 잘 표현되고 있는 것을 확인했습니다

 

 

최종 결과

 

최종 코드

MDX 용 ExampleGrid 컴포넌트 생성

import { Grid } from '@devup-ui/react'
import { ReactNode } from 'react'

interface ExampleGridProps {
  children: ReactNode
}

export function ExampleGrid({ children }: ExampleGridProps) {
  return (
    <Grid gap="16px" gridTemplateColumns={['repeat(1, 1fr)', 'repeat(2, 1fr)']}>
      {children}
    </Grid>
  )
}