기반·도구

KatanA UI Core

특정 UI 프레임워크에 의존하지 않는 Rust UI 기반입니다. 컴포넌트 상태·이벤트·테마·렌더링 계약을 모아 필요한 연결 계층을 선택할 수 있습니다.

재사용 가능한 UI 컴포넌트와 앱 표시 기반을 만드는 Rust 개발자

01

구현된 기능

기본 컴포넌트와 SplitPane·Toolbar·StatusBar 같은 복합 컴포넌트

근거

테마·이벤트·렌더링 모델과 창 관련 중립 API

근거

선택적 egui 연결과 텍스트·SVG rasterization 기능

근거

02

시작하기

  1. Rust와 just를 준비하고 저장소를 가져옵니다.
  2. just storybook으로 컴포넌트를 확인하고 통합 시 필요한 기능만 활성화합니다.

Rust와 필요한 개발 도구를 준비하고, 도입 전에 링크된 README에서 환경 요구 사항을 확인하세요. 실행 예시는 기능의 시작점이며 모든 환경에서의 동작을 보장하지 않습니다.

근거
sh
git clone https://github.com/HiroyukiFuruno/katana-ui-core.git
cd katana-ui-core
just storybook

01 / 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

입력부터 출력까지

  1. 부품과 설정 입력하기

    호스트는 SplitPane을 만들고 axis, ratio_percent, min/max_percent, handle_width_px, resize_mode, 자식 노드를 설정합니다. 설정값은 builder로 연쇄할 수 있고 상태 ID도 부품별로 보관합니다.

  2. 조작을 계약화하기

    pointer 또는 keyboard의 resize, ratio 변경, reset, clamp를 UiAction으로 적용합니다. SplitPane 내부는 비율을 범위 안으로 보정하고 조작 결과를 callback log와 interaction state로 변환합니다.

  3. 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 결과를 자신의 상태 관리에 반영할 수 있습니다.

rust
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은 개발용 검증 환경이므로 실제 호스트에서도 입력·레이아웃·렌더링을 확인해야 합니다.

근거

조사 시점의 공개 저장소를 바탕으로 소개합니다. 링크된 고정 커밋에서 구현과 사용 방법을 확인할 수 있습니다.

저장소읽기 안내c3e80cb9098c
근거 · KUC
모든 제품