01
구현된 기능
02
시작하기
- Rust와 just를 준비하고 저장소를 가져옵니다.
- just storybook으로 컴포넌트를 확인하고 통합 시 필요한 기능만 활성화합니다.
Rust와 필요한 개발 도구를 준비하고, 도입 전에 링크된 README에서 환경 요구 사항을 확인하세요. 실행 예시는 기능의 시작점이며 모든 환경에서의 동작을 보장하지 않습니다.
근거git clone https://github.com/HiroyukiFuruno/katana-ui-core.git
cd katana-ui-core
just storybook01 / KUC
사용 장면
중립 UI 부품으로 화면 구성하기
KUC는 완성된 앱 화면이 아니라 atoms, molecules, layout, state, event, render model을 조합하기 위한 Rust 기반입니다. 호스트는 SplitPane이나 Toolbar 등을 선택하고 고유한 화면 구성과 framework 연결을 담당합니다.
필요한 렌더링 계층만 활성화하기
기본값은 framework-neutral core이며 egui, text-raster, svg-raster, raster-host를 feature 단위로 추가할 수 있습니다. 공통 계약을 유지한 채 UI 입력, 문자·SVG raster, UI-tree 렌더링을 호스트 구성에 맞춰 선택할 수 있습니다.
02 / KUC
입력부터 출력까지
부품과 설정 입력하기
호스트는 SplitPane을 만들고 axis, ratio_percent, min/max_percent, handle_width_px, resize_mode, 자식 노드를 설정합니다. 설정값은 builder로 연쇄할 수 있고 상태 ID도 부품별로 보관합니다.
조작을 계약화하기
pointer 또는 keyboard의 resize, ratio 변경, reset, clamp를 UiAction으로 적용합니다. SplitPane 내부는 비율을 범위 안으로 보정하고 조작 결과를 callback log와 interaction state로 변환합니다.
render model로 전달하기
부품은 UiNode로 변환되어 axis, 비율, handle, resize mode, 공통 상태를 포함한 render model이 됩니다. 최신 HEAD에서는 raster-host의 Canvas, TextRenderer, UI-tree renderer 등에 연결할 수 있지만 앱의 windowing이나 shell은 호스트 책임입니다.
03 / KUC
주요 API·CLI
SplitPaneAxis — 분할 방향- Horizontal과 Vertical을 나타내고 분할 방향을 결정합니다. 단순한 표시 라벨이 아니라 render model의 axis로 변환되는 레이아웃 계약입니다.
SplitPaneResizeMode — 크기 조정 입력- PointerOnly, KeyboardOnly, PointerAndKeyboard, Disabled를 나타냅니다. Disabled에서는 handle을 focus 가능하게 만들지 않아 호스트의 입력 경로를 명시적으로 제한할 수 있습니다.
비율·clamp 설정- ratio_percent는 현재 비율, min_percent와 max_percent는 허용 범위, reset_percent는 복귀값입니다. 입력값은 설정된 범위로 clamp되어 범위를 벗어난 요청을 그대로 렌더링하지 않습니다.
raster-host 공개 계약- raster-host feature에서는 Canvas, TextRenderer, UiTreeCanvasRenderer, UiTreeInteractionSurface 등이 공개됩니다. 렌더링과 hit/interaction 구현을 묶을 수 있지만 feature를 활성화하지 않은 core 사용자는 추가 의존성을 요구받지 않습니다.
04 / KUC
구체적인 예
SplitPane 조작 계약 통합하기
SplitPane을 수평 50%로 만들고 20~80%로 clamp한 뒤 UiAction으로 64%로 변경하고 keyboard resize와 reset을 적용합니다. 공개 crate의 조작 타입을 사용하므로 호스트는 UI framework 이벤트를 UiAction으로 변환하고 callback log 결과를 자신의 상태 관리에 반영할 수 있습니다.
use katana_ui_core::component::ComponentAction;
use katana_ui_core::interaction::UiAction;
use katana_ui_core::layout::{SplitPane, SplitPaneAxis, SplitPaneResizeSource, SplitPaneResizeMode};
fn main() {
let mut split = SplitPane::new()
.axis(SplitPaneAxis::Horizontal)
.ratio_percent(50)
.min_percent(20)
.max_percent(80)
.resize_mode(SplitPaneResizeMode::PointerAndKeyboard);
let target = split.state_id().clone();
let _ = split.apply_action(&UiAction::split_pane_set_ratio(target.clone(), 64));
let _ = split.apply_action(&UiAction::split_pane_resize_by(
target.clone(),
4,
SplitPaneResizeSource::Keyboard,
));
let _ = split.apply_action(&UiAction::split_pane_reset_ratio(target));
println!("ratio={}", split.ratio_percent_value());
}05 / KUC
통합 조건과 책임 경계
Rust workspace와 feature 준비하기
katana-ui-core를 의존성에 추가하고 framework-neutral하게 사용한다면 기본 feature 그대로 시작합니다. egui나 raster host가 필요할 때만 Cargo feature를 활성화해 feature 고유 의존성을 앱에 포함합니다.
호스트가 shell과 검증 담당하기
AppShell이나 페이지 템플릿을 포함한 완성 앱이 아닙니다. egui나 raster host 연결 계층을 사용하더라도 앱 고유 화면 구성과 창 관리는 호스트가 조립합니다. Storybook은 개발용 검증 환경이므로 실제 호스트에서도 입력·레이아웃·렌더링을 확인해야 합니다.
근거
조사 시점의 공개 저장소를 바탕으로 소개합니다. 링크된 고정 커밋에서 구현과 사용 방법을 확인할 수 있습니다.