'use client';

import { Center, FlexRow, Space, TopAbsolute } from '@cp949/mui-react19';

export default function LayoutExample() {
  return (
    <Center sx={{ height: 200, position: 'relative' }}>
      <FlexRow.Between sx={{ width: '100%' }}>
        <span>왼쪽</span>
        <Space width={20} />
        <span>오른쪽</span>
      </FlexRow.Between>

      <TopAbsolute.Right top={10}>상단 오른쪽 요소</TopAbsolute.Right>
    </Center>
  );
}

상호작용 컴포넌트 사용

'use client';

import { Spoiler, FileButton, CooldownButton } from '@cp949/mui-react19';

export default function ClientComponent() {
  return (
    <div>
      <CooldownButton cooldownMs={3000} onClick={() => console.log('clicked')}>
        쿨다운 버튼
      </CooldownButton>

      <Spoiler maxHeight={100} showLabel="더보기" hideLabel="숨기기">
        긴 내용이 여기에...
      </Spoiler>
    </div>
  );
}

Next.js 서버 컴포넌트에서 사용

번들은 파일별로 출력되며 클라이언트 전용 모듈에는 'use client'가 유지됩니다.
Portlet 같은 점 표기 컴포넌트(Portlet.Header)는 서버 컴포넌트에서 속성 접근이 되지 않습니다. 서버에서는 PortletHeader, PortletContent, PortletLabel, PortletToolbar, PortletTitle, PortletFooter를 개별 import합니다.
훅(@cp949/mui-react19/hooks)은 클라이언트 컴포넌트에서만 호출할 수 있습니다.

LLM용 API 요약

배포 패키지에 llm.txt가 포함됩니다. AI 코딩 도구가 공개 API 시그니처와 사용 제약을 한 번에 읽을 수 있도록 빌드 시 dist/*.d.ts에서 생성한 영문 요약입니다. 경로는 node_modules/@cp949/mui-react19/llm.txt입니다.

컴포넌트 목록

레이아웃 컴포넌트

Center - 중앙 정렬 컨테이너
Space - 여백 생성
FlexRow / FlexColumn - Flex 레이아웃
- .Start, .End, .Center, .Between, .Around, .Evenly
TopAbsolute 계열 (4개) - TopAbsolute, .Left, .Right, .Center
CenterAbsolute 계열 (4개) - CenterAbsolute, .Left, .Right, .Center
BottomAbsolute 계열 (4개) - BottomAbsolute, .Left, .Right, .Center

상호작용 및 유틸리티 컴포넌트

CooldownButton, DebouncedButton - 쿨다운/디바운스 버튼
FileButton - 파일 업로드 버튼
PasswordTextField - 비밀번호 보기/숨기기 토글이 있는 TextField
CopyButtonWrapper - 복사 기능 래퍼
Spoiler - 스포일러/더보기 컴포넌트
Hide, Show - 조건부 렌더링 유틸리티
Paper - MUI Paper 래퍼
Mark - 하이라이트 마크
YmdTypography - YYYYMMDD/YYMMDD 숫자 날짜를 포맷해 표시하는 Typography
YmTypography - YYYYMM 숫자 연월을 포맷해 표시하는 Typography
YmdTextField - YYMMDD/YYYYMMDD 숫자 날짜 입력 TextField
SmOrUp, MdOrDown, LgOrUp 등 - 반응형 조건부 렌더링

고급 기능 컴포넌트

FloatingIndicator - 플로팅 인디케이터
DebouncedRender - 디바운스된 렌더링
SearchBoxDebouncer - 검색 조건 입력을 모아 한 번만 외부로 전달 (훅: useDebouncedParams)
DelayedRender - 지정한 시간이 지난 뒤에 자식을 렌더링
SegmentedControl - 세그먼트 컨트롤

훅 (Hooks)

Export 경로

import { useElementSize, useCenterInView } from '@cp949/mui-react19/hooks';

주요 훅들 (66개)

useCenterInView - 뷰포트 중앙 감지
useElementSize - 요소 크기 감지
useLocalStorage, useSessionStorage - 웹 스토리지
useDebouncedCallback, useThrottledCallback - 성능 최적화
useSmOrUp, useMdOrDown 등 - 반응형 훅들
기타 다수 (총 66개)

헬퍼 유틸리티

import { mediaQueries, cssVars } from '@cp949/mui-react19/helper';

mediaQueries - MUI 미디어 쿼리 헬퍼
cssVars - MUI CSS 변수 헬퍼

파일 드롭 핸들러

import { processFileTreeDrop, processFileTreeDropSafe } from '@cp949/mui-react19/file-drop';

React에서 파일과 폴더를 드래그앤드롭으로 처리하는 모듈입니다.

주요 기능:

폴더 구조 완전 탐색
파일 필터링 (크기, 타입, 개수)
실시간 진행률 추적
병렬 처리
에러 처리 및 복구
트리 구조 제공

상세한 사용법과 예제는 README.file-drop.md를 참고하세요.

API 예시

FlexRow/FlexColumn 사용법

// 기본 사용
<FlexRow center>
  <span>중앙 정렬</span>
</FlexRow>

// 네임스페이스 API
<FlexRow.Between sx={{ padding: 2 }}>
  <button>왼쪽</button>
  <button>오른쪽</button>
</FlexRow.Between>

// 세로 레이아웃
<FlexColumn.Center sx={{ height: 200 }}>
  <div>세로 중앙</div>
</FlexColumn.Center>

Absolute 위치 컴포넌트

<div style={{ position: 'relative', height: 300 }}>
  <TopAbsolute.Center top={20}>상단 중앙</TopAbsolute.Center>

  <CenterAbsolute.Left left={20}>세로 중앙, 왼쪽 고정</CenterAbsolute.Left>

  <BottomAbsolute.Right bottom={20} right={20}>
    하단 오른쪽
  </BottomAbsolute.Right>
</div>

sx prop 활용

<Center
  vertical
  sx={{
    height: 400,
    backgroundColor: 'primary.main',
    '&:hover': {
      backgroundColor: 'primary.dark',
    },
  }}
>
  커스텀 스타일 적용
</Center>

기술 스택

React 19.x
MUI 9.x
TypeScript 6.x
RxJS 7.x (일부 훅)

버전 정책 (React 19 전용)

2.x는 React 19 전용입니다. React 18은 지원하지 않습니다.
peerDependencies.react는 ^19로 제한됩니다. React 18 트리에는 설치되지 않습니다.
forwardRef를 제거하고 React 19 ref-as-prop 패턴으로 전환한 데 따른 의도된 breaking change입니다.
공개 컴포넌트의 ref 전달·id 생성 동작은 회귀 없이 유지됩니다.
useId 출력 포맷이 변경되었습니다(breaking): 생성 id에서 mantine- prefix를 제거했습니다. 생성 id 문자열에 의존하던 코드는 영향을 받습니다.

추가 정보

모든 컴포넌트는 ref를 일반 prop으로 직접 전달받습니다(React 19 ref-as-prop, forwardRef 불필요). <Center ref={...} /> 형태의 기존 사용 코드는 동일하게 동작합니다.
MUI의 sx prop과 완벽 호환
ESM과 CommonJS 모두 지원 (dual package)
Tree-shaking 최적화로 번들 크기 최소화