ranui
네이티브 커스텀 엘리먼트 위에 만든 UI 라이브러리입니다. 모든 컴포넌트가 <r-*> 태그라서 React, Vue, Svelte, Solid, Astro, 혹은 순수 HTML 파일에서 똑같이 동작합니다. 어댑터도 없고 맞춰야 할 프레임워크 버전도 없습니다. TypeScript 타입, 디자인 토큰 기반 라이트/다크 테마, Shadow DOM 캡슐화, 서버 렌더링이 기본으로 들어 있습니다.
- npm:
ranui· 소스:packages/ranui - ranui 는 alpha입니다. 버전마다 호환성을 깨는 변경이 들어갑니다. 정확한 버전을 고정하고, 업그레이드 전에 변경 이력을 읽으세요.
설치
npm install ranui<!-- 또는 CDN 에서, 빌드 단계 없이 -->
<script src="https://unpkg.com/ranui/dist/umd/index.umd.cjs"></script>사용법
import 하면 엘리먼트가 등록됩니다. 그다음부터는 태그를 쓰면 됩니다.
import 'ranui'; // 모든 컴포넌트
import 'ranui/button'; // 또는 하나만<r-button type="primary">프로젝트 배포</r-button>태그는 어느 프레임워크에서나 같습니다. 다른 것은 값을 넘기고 이벤트를 묶는 방식뿐이며, 그 부분은 코딩 가이드에서 전부 다룹니다.
<script src="https://unpkg.com/ranui/dist/umd/index.umd.cjs"></script>
<body>
<r-button>Button</r-button>
</body>import 'ranui';
export const App = () => <r-button type="primary">Deploy</r-button>;
// 복잡한 값과 이벤트 리스너는 ref 를 통해 넘깁니다 — 코딩 가이드를 보세요.<template>
<r-button type="primary" @click="deploy">Deploy</r-button>
</template>
<script setup>
import 'ranui';
</script>
<!-- 빌드 설정의 compilerOptions.isCustomElement 에 `r-`를 추가하세요. -->import 'ranui';
const button = document.createElement('r-button');
button.textContent = 'Deploy';
document.body.appendChild(button);진입점
각 진입점은 이름이 말하는 것만 정확히 등록합니다. 그래서 테마만 필요한 페이지가 컴포넌트 라이브러리 값을 치를 일이 없습니다.
| import | 내용 |
|---|---|
ranui | 모든 컴포넌트 |
ranui/<component> | 컴포넌트 하나: ranui/button, ranui/select, … |
ranui/theme | 라이트/다크 테마와 토큰 덮어쓰기. 엘리먼트는 없음 |
ranui/i18n | 번역 엔진. 엘리먼트는 없음 |
ranui/fonts | 자체 호스팅한 Geist Sans + Geist Mono |
ranui/style | 스타일시트. 설정이 자동으로 집어 가지 않을 때 |
ranui/builder | 세밀한 반응성을 갖춘 유창한 DOM 빌더 |
ranui/ssr, ranui/ssr-stream | 서버 렌더링 |
ranui/testing | 테스트에서 닫힌 섀도 루트에 손을 뻗기 위한 도우미 |
ranui/typings | 앰비언트 JSX / TS 엘리먼트 타입 |
컴포넌트
엘리먼트 40 개. 어트리뷰트, 프로퍼티, 이벤트, 슬롯, ::part() 이름까지 전부 엘리먼트 API 레퍼런스에 있습니다.
데이터 입력: Input · CheckBox · Select · ColorPicker · Attachments · VoiceButton · Forms
데이터 표시: Card · Section · Tabs · Image · Progress · Radar · Player · Preview · Glass · Scratch · StateDot · DisclosureRow
콘텐츠 렌더링: Markdown · Math · Mermaid
AI 와 채팅: Conversation · Reasoning · ToolCard · TokenMeter
오버레이와 피드백: Modal · Popover · Dropdown · Message · Skeleton
기반: 테마 · ThemeSwitch · i18n
엘리먼트 다섯 개는 다른 엘리먼트 안에서만 존재하기 때문에 자기 페이지가 없습니다: <r-option> (Select), <r-tabs>(Tabs), <r-img>(Image), <r-dropdown-item>(Dropdown), <r-content> (Popover). 나머지와 마찬가지로 API 레퍼런스에는 실려 있습니다.
라이브
스타일
컴포넌트는 닫힌 섀도 루트에 그려집니다. 페이지 CSS 가 안으로 새지 않고, 선택자도 안까지 닿지 않습니다. 들어가는 길은 네 가지이며, 아래는 권장 순서입니다.
1. 디자인 토큰 (CSS 커스텀 프로퍼티): 경계를 넘어 상속되므로 :root에 두든, 바깥 컨테이너에 두든, 엘리먼트 자체에 두든 모두 통합니다.
<r-progress
percent="0.7"
type="drag"
style="--ran-progress-track-background: linear-gradient(to right, #f00, #ff0, #0f0, #0ff, #00f)"
></r-progress>2. ::part() — 토큰이 닿지 않는 구조적 조정에 · 3. sheet 어트리뷰트 — 섀도 루트에 CSS 를 주입 · 4. 슬롯에 넣은 콘텐츠 — 여러분의 문서에 남아 페이지 CSS 를 그대로 받습니다.
토큰 이름은 디자인 시스템에, 무엇을 고를지의 규칙은 디자인 가이드에, 작동 원리는 코딩 가이드에 있습니다.
이벤트
컴포넌트는 CustomEvent를 디스패치하고 데이터는 detail에 담습니다. 리스너는 엘리먼트에 다세요. 이벤트가 버블링되는지는 컴포넌트마다 다르며, API 레퍼런스가 모두 명시합니다.
<r-select id="env"></r-select>
<script>
document.getElementById('env').addEventListener('change', (event) => {
console.log(event.detail.value);
});
</script>이들은 평범한 DOM 엘리먼트라서 onchange="…" 어트리뷰트 형태와 el.onchange = … 프로퍼티 형태도 동작합니다. 다만 핸들러를 하나만 가질 수 있고 캡처 단계가 없으므로, 먼저 손이 가야 할 것은 addEventListener입니다.
다음에 볼 곳
| 하고 싶은 일 | 읽을 문서 |
|---|---|
| 엘리먼트의 정확한 API 찾기 | 엘리먼트 API |
| 어떤 토큰을 왜 써야 하는지 알기 | 디자인 시스템 |
| 하나의 체계로 보이는 화면 만들기 | 디자인 가이드 |
| ranui 를 앱에 제대로 붙이기 | 코딩 가이드 |
| 라이트/다크를 넣거나 전체를 다시 꾸미기 | 테마 |
| 인터페이스 번역하기 | i18n |
| 서버에서 렌더링하기 | 서버 렌더링 |
| 프레임워크 없이 반응형 뷰 만들기 | 빌더 |
| 업그레이드 전에 무엇이 바뀌었는지 보기 | 변경 이력 |
브라우저 지원
이 라이브러리는 모든 최신 브라우저에서 동작합니다. Custom Elements v1, Shadow DOM v1, CSS 커스텀 프로퍼티 위에 만들었습니다. Internet Explorer 는 지원하지 않습니다.
기여자
더 읽을거리
이 라이브러리가 딛고 선 표준: W3C · ECMA · RFC · Can I use
곁에 두면 좋은 디자인 참고 자료: Checklist Design · Laws of UX · Geist · Ant Design · Element UI · Animista · WebGradients