JunkBox libs/shared-ui 가이드
1. 라이브러리 역할
shared-ui는 JunkBox 전역 UI 자산 라이브러리임.- 공통 Tailwind preset, 공통 스타일 산출물, 공용 폰트 자산, 공통 템플릿, 공통 프런트 헬퍼 자산, 공통 React 유틸 계층을 제공함.
- 모든 앱과 화면이 동일한 공통 UI 자산을 재사용할 수 있도록 설계됨.
2. 설계 목표
- 앱별 CSS나 화면별 CSS 없이 공통 자산만으로 화면을 조합할 수 있게 함.
- 서버 렌더링 화면과 프런트 번들이 같은 스타일 자산과 설계 토큰을 공유하도록 함.
- 시각 원칙과 상호작용 원칙 자체는
docs/junkbox/common/guide-jb-common-ui.md를 단일 기준으로 따름.
3. 자산 구조
3.1 주요 파일
빌드와 설정
package.json은 스타일 빌드 의존성과 스크립트를 정의함.tailwind.config.cjs는 로컬 빌드 진입점임.src/junkbox_shared_ui/tailwind.preset.cjs는 앱 공통 preset임.src/junkbox_shared_ui/breakpoints.json은 반응형 전환 폭의 단일 정의 파일임.pc(1440px)는 PC/모바일 공통 전환점이고,chessSplit(900px)·chessWide(1500px)는 Chess 전용 예외 단계임.src/junkbox_shared_ui/status-colors.json은 웹 상태 색 표준(진행 파랑·성공 초록·실패 빨강·판정 불가 회색)의 단일 정의 파일임.- 상태별
solid·text·tint·border·soft와 중립색(track·marker)을 두며 preset이colors.status.*,colors.progress-track,colors.progress-marker로 노출함. scripts/check-status-colors.mjs는shared-ui/src와apps/*/src에서 상태 색 hex를 직접 쓴 경우 실패하는 검사이며npm run build·build:dev앞에서 실행됨(npm run check:status-colors로 단독 실행 가능). 규칙은 공통 UI 가이드 7.10을 따름.
- 상태별
스타일 소스
src/styles/hub-ui-base.css는 앱 셸, 패널, 폼, 버튼, 토스트, 공통 컴포넌트, 공통 SPA 전환 효과, skeleton, 터치 피드백, 공통 sortable/드래그 시각 규칙, 공통 시각 토큰의 소스 파일임.jb-markdown-preview는 Hub 도구의 생성 문서 미리보기에서 제목, 문단, 목록, 코드 블록, 인용문, 링크를 공통 CSS로 렌더링함.src/styles/hub-ui-mobile.css는 모바일 바텀 액션바, 모바일 시트, 모바일 로그인 레이아웃처럼 실제 모바일 레이아웃에 종속된 규칙의 소스 파일임. 모바일 본문 폭과 외부 좌우 여백은hub-ui-base.css의 공통jb-main규칙과 토큰에서 관리함.src/styles/hub-ui-desktop.css는 데스크탑 관리자 레이아웃, 작업형 워크스페이스, 모달, 폼 그리드, no-scroll 화면 구조 소스 파일임.src/styles/junkbox-tabulator.css는 Tabulator 전용 공통 소스 파일임.scripts/build-styles.mjs는 분리된 CSS 소스를 각각 빌드하는 스타일 빌드 진입점임.
스크립트와 React
-
src/scripts/app-shell.ts는 공통 앱 셸 TypeScript 소스임. -
src/react/는 공통 React 컴포넌트, 공통 유틸, 전역 타입 선언을 제공함. -
src/react/components/SortableDragHandle.tsx는 Sortable 기반 정렬 UI에서 사용하는 6점 드래그 핸들 공통 컴포넌트임. -
src/react/components/WorkspaceDetailOverlay.tsx는 목록을 유지한 채 오른쪽 상세 편집 패널을 열고 접는 공통 컴포넌트임. -
src/react/components/SegmentedTabs.tsx는 탭, 필터, 보기 전환처럼 같은 옵션 집합 중 하나를 고르는 공통 segmented tab 컴포넌트임. -
src/react/components/BottomOptionPicker.tsx는 모바일 하단 선택 시트 공통 컴포넌트임. 목록 헤더에는 선택 개수 표시만 두고, 하단 버튼 영역은 아이콘 버튼(닫기, 다중 선택 시 전체 해제·전체 선택, 확인)으로 구성하며 접근성 이름으로 라벨을 제공함. 헤더의 별도 취소 버튼은 두지 않음. -
src/react/components/FormModal.tsx는 모바일 화면의 짧은 입력·결과 모달임.onConfirm을 생략하면 닫기 버튼만 표시함.- 제목, 입력 children,
취소와 확인 버튼(confirmLabel,confirmVariant,confirmDisabled)을 가진 폼을 화면 중앙에 표시하고 Escape로 닫음. - 선택 prop
middleAction(label·onClick·variant·disabled)은취소와 확인 버튼 사이에 보조 버튼을 추가하며 생략하면 두 버튼만 표시함. - 내부 스크롤 영역은
overscroll-contain을 사용함. hub-ui-desktop.css를 로드하지 않는 모바일 화면에서도 동작하도록 CSS 파일 없이 Tailwind 유틸리티만 사용하며 최대 높이는dvh기준임.
- 제목, 입력 children,
-
src/react/components/StatusBadge.tsx는StatusTone(IN_PROGRESS·SUCCESS·FAIL·UNDETERMINED) 배지StatusBadge(dot옵션을 켜면 글자 앞에 상태 색 작은 원jb-status-badge-dot을 붙여 사용 중·꺼짐 같은 켜짐 상태를 표시)와 CSS 수식어를 만드는statusToneSuffix를 제공함.- 배지(
jb-status-badge--*)와 선택한 상태 버튼(jb-choice-accent--*)의 색은hub-ui-base.css에서 같은 규칙으로 정의함. ProgressBar와SemicircleGauge의tone도 같은StatusTone을 사용하며 색 값은 받지 않음.
- 배지(
-
src/react/components/icons.tsx는 Lucide 아이콘의 공통 크기·선 굵기와IconFileSpreadsheet,IconListChecks,IconListX,IconCheck를 포함한 아이콘 wrapper를 제공함. -
src/react/components/Button.tsx는 버튼 4색 체계의 단일 진입점임.Button(variant="primary|danger|warning|ghost",compact), 아이콘 전용IconButton(aria-label필수), 링크용buttonClassName을 제공하며 기본type="button"임. 색 의미와 판단 순서는 공통 UI 가이드 7.1을 따름. -
jb-button-warning은 비가역·광범위·외부 부작용 버튼의 노랑 변형이고,jb-button-compact는 좁은 영역용 작은 크기 수정자임. 빨강·노랑·검정 비활성 상태는 공통 CSS가 낮은 채도로 표시함. 버튼의 화면 전용 크기·색 CSS는 두지 않으며just check-buttons로 검증함. -
src/react/components/SpreadsheetDownloadButton.tsx는 모바일 하단 액션바의 스프레드시트 아이콘 다운로드 버튼임. 텍스트 버튼과 함께 있을 때만 고정 정사각형 폭을 사용하고, 아이콘 버튼만 있으면 다른 아이콘 버튼과 폭을 균등 분할함.jb-button-ghost,jb-mobile-bottom-bar-button,jb-mobile-bottom-bar-icon을 조합하고 기본 접근성 이름기록 다운로드를 제공함. 클릭 핸들러는 사용하는 화면에서 전달함. -
src/react/components/BottomNumberPicker.tsx는 숫자 배열을BottomOptionPicker옵션 계약으로 변환하는 숫자 선택 wrapper임. -
src/react/utils/sortable.ts는 Sortable 공통 옵션을 제공하며, 1초 지연 드래그와 공통 ghost/chosen/fallback 클래스 계약을 중앙화함.
선택 컨트롤
src/react/components/ChoiceControls.tsx는 액션이 아닌 선택·탐색 컨트롤을 제공함.SelectTrigger(jb-select),CardButton(jb-mobile-card jb-mobile-list-card),ToggleButton(pressed,variant:chip·pill·segment·choice·icon)이며aria-pressed와is-active를 자동 적용함.Switch는jb-switch외형과role="switch",aria-checked를 제공함.Checkbox는jb-checkbox외형의 네이티브 체크박스임. 두 컴포넌트에는aria-label을 지정함.CheckboxField는 같은 네이티브 체크박스에 표시 라벨을 붙인 폼용 컴포넌트임.jb-checkbox-field가 라벨의 높이·정렬·간격을 관리함. 별도 표시 라벨 없는 목록 항목 선택에는Checkbox를 사용함.
빌드 산출물
src/junkbox_shared_ui/assets/hub-ui-base.css는 공통 CSS 빌드 산출물임.src/junkbox_shared_ui/assets/hub-ui-mobile.css는 모바일 전용 CSS 빌드 산출물임.src/junkbox_shared_ui/assets/hub-ui-desktop.css는 데스크탑 전용 CSS 빌드 산출물임.src/junkbox_shared_ui/assets/junkbox-tabulator.css는 빌드 산출 Tabulator CSS임.src/junkbox_shared_ui/assets/junkbox-tabulator.js는 Tabulator 공통 헬퍼임.src/junkbox_shared_ui/assets/app-shell.js는 TypeScript 소스에서 생성된 공통 앱 셸 동작 산출물임.src/junkbox_shared_ui/assets/app-icons/{app}/icon.svg는 앱별 미니멀 플랫 SVG 아이콘 원본임.src/junkbox_shared_ui/assets/app-icons/{app}/icon-180.png,icon-192.png,icon-512.png는 favicon, apple touch icon, PWA manifest에서 사용할 수 있는 앱 아이콘 PNG 산출물임.
템플릿
src/junkbox_shared_ui/templates/base.html은 공통 베이스 템플릿임.src/junkbox_shared_ui/templates/_stylesheets.html은 공통 CSS와 Tabulator vendor CSS 링크를 선언하는 stylesheet 매크로 템플릿임.src/junkbox_shared_ui/templates/_grid_head.html은 공통 그리드 헤더 템플릿임.
3.2 폰트 자산
PretendardVariable.woff2를 공용 폰트로 제공함.- 한글, 영문, 숫자, 코드/JSON/메타 라벨을 포함한 화면 텍스트 전부 동일 폰트로 처리함.
- 폰트 파일은
assets/fonts/아래에 유지함. @font-face와 루트 폰트 변수는hub-ui-base.css소스에서 중앙 관리함.- 앱별 CSS, 화면별 CSS, 특정 컴포넌트 클래스에서
font-family를 중복 선언하지 않음. - Tabulator 전용 CSS는 자체 폰트명을 고정하지 않고 공통 루트 폰트를 상속함.
4. 시각 자산 기준
- 기본 sans는
Pretendard Variable폰트 자산을 사용함. - Tailwind preset의
sans와mono폰트 토큰은 모두Pretendard Variable을 사용함. - 일반 본문 텍스트, JSON 뷰어, 상세 텍스트 뷰어, 브랜드 마크, eyebrow, 필드 라벨, 통계 라벨, 테이블 헤더는 모두 Pretendard 기준을 사용함.
- JetBrains Mono, Fira Code, IBM Plex Mono, 브라우저 기본
monospace폰트는 JunkBox 화면 스타일 기준으로 사용하지 않음. - 폰트 적용 경로는 공통 base CSS의
body와 상속 규칙을 기준으로 하며, 개별 화면이 자체 폰트 스택을 만들지 않음. - 상세 색상, 레이아웃, 버튼, 토스트, 그리드, 모바일 예외 규칙은 이 문서에서 중복 정의하지 않고
docs/junkbox/common/guide-jb-common-ui.md를 기준으로 구현함. - 공통 다크 톤은 저대비 레이어 중심 규칙을 구현함.
- 패널, 카드, 입력창, 칩, 상태 배지, 바텀시트는 같은 톤 체계 안에서 구현함.
5. Tailwind 사용 방식
5.1 preset 중심 구조
- 각 앱은 공용 preset을 가져와 동일한 토큰을 사용함.
- 색상, 폰트, spacing, radius, component layer 규칙은 preset 기준으로 통일함.
- 반응형 폭은 preset이
breakpoints.json을 읽어theme.extend.screens의pc,chess-split,chess-wide로 노출함. CSS 소스는theme('screens.pc')처럼 이 이름으로만 폭을 참조하고 숫자를 직접 쓰지 않음. - 새 반응형 조건은 PC/모바일 공통 전환점
pc하나를 사용함. 새@media폭 숫자, Tailwind 기본sm:·md:·lg:접두어, 스크립트의 폭 숫자 비교는 추가하지 않음. 규칙 전체는 공통 UI 가이드의 반응형 전환 기준을 따름.
5.2 빌드 방식
shared-ui는 Node 기반 Tailwind 빌드 파이프라인을 사용함.- 프런트엔드 의존성은 JunkBox 루트의 npm workspace와 단일
package-lock.json에서 설치함.shared-ui와 UI 앱의 React·React DOM·타입 선언은 같은 설치 트리에서 해석하며, 로컬·Docker 빌드는 루트 lockfile을 기준으로npm ci를 사용함. - 앱 셸 동작은 TypeScript 소스를 빌드하여 배포 가능한 자산으로 생성함.
assets/vendor/tabulator의 벤더 파일은 저장소에 커밋된 산출물임.scripts/copy-tabulator-assets.mjs는 설치된tabulator-tables버전이 커밋된 파일의 버전과 같을 때만 복사하고 다르면 경고만 출력해 빌드가 무관한 벤더 diff를 만들지 않음. 버전을 올릴 때만TABULATOR_SYNC=1 npm run build로 동기화함.- 빌드 결과물은 앱이 정적 자산으로 직접 서빙할 수 있어야 함.
- Python 앱은 빌드 산출 CSS와 JS를 링크하여 사용함.
- 스타일 빌드는
hub-ui-base.css,hub-ui-mobile.css,hub-ui-desktop.css를 각각 생성하는 구조를 사용함. tailwind.config.cjs의 content 범위에는 공통 자산과 UI 앱의 TypeScript/TSX 소스를 포함해야 함. 앱 화면이 새 Tailwind 유틸리티 클래스를 사용하면 해당 클래스가 content 범위에 포함되었는지 확인한 뒤 shared-ui 스타일 빌드에서 공통 산출물로 생성함.- Tailwind utility layer는
hub-ui-base.css산출물에 포함됨. UI 앱의 Vite 빌드는 앱 JavaScript 산출물만 갱신하므로, 새 Tailwind 유틸리티를 실제 브라우저 CSS에 반영하려면shared-ui빌드를 함께 실행해야 함. - 화면 크기와 무관한 상호작용 효과는
hub-ui-base.css에 두고, 모바일 고정 폭이나 safe-area처럼 모바일 화면 구조에 직접 종속된 규칙만hub-ui-mobile.css에 둠. - 데스크탑 화면도
hub-ui-base.css를 로드하므로 SPA 전환, skeleton, 안정 로딩, 터치 피드백 같은 공통 장치를 필요 시 동일한 React 계층과 CSS 클래스로 사용할 수 있음.
5.3 앱 연동 방식
- 서버 렌더링 화면도 동일 산출 CSS를 링크함.
- 프런트 앱도 같은 preset과 자산을 공유함.
- 앱과 화면은 스타일 결정을 직접 하지 않고
jb-*공통 클래스를 조합함. - 공통 정적 자산 링크는 서버 템플릿이 버전 쿼리 파라미터를 붙여 생성함.
5.4 apps/hub-ui, apps/chess-ui, apps/health-ui, apps/message-ui, apps/wow-ui 연동 구조
apps/hub-ui,apps/chess-ui,apps/health-ui,apps/message-ui,apps/wow-ui는shared-ui자산을 소비하는 대표 프런트엔드 앱임.- 번들러는 Vite 6 계열을 사용함.
- React + TypeScript strict 기준으로 페이지 엔트리 또는 앱 단위 SPA 엔트리와 공통 타입 계약을 관리함.
hub-api는apps/hub-ui/dist를/hub-ui경로로 직접 마운트함.chess-api는apps/chess-ui/dist를/chess-ui경로로 직접 마운트함.health-api는apps/health-ui/dist를/health-ui경로로 직접 마운트함.message-api는apps/message-ui/dist를/message-ui경로로 직접 마운트함.wow-api는apps/wow-ui/dist를/wow-ui경로로 직접 마운트함.- 서버 템플릿은 React 마운트 지점과 초기 props만 제공하고, 실제 화면 자산 로딩은 Vite manifest 기준으로 수행함.
- 템플릿은 해시된 정적 파일명을 직접 참조하지 않고
dist/.vite/manifest.json을 통해 최신 자산 경로를 해석함. - 각 UI 앱의 타입 계약은 앱 자체
src/types/models.ts, 브라우저 전역 타입과import.meta.env타입은 각 앱src/global.d.ts를 기준으로 관리함. - 운영 자산은 백엔드가 빌드된 자산을 직접 서빙하는 구조를 사용함.
- 개발 자산은
hub15001,chess15002,health15003,message15004,wow15009Vite 개발 서버를 통해 제공할 수 있음.
5.5 apps/rename-ui 연동 구조
apps/rename-ui는shared-ui자산을 소비하는 데스크톱 운영 화면 앱임.- 번들러는 Vite 6 계열을 사용함.
- React + TypeScript strict 기준으로 단일 엔트리와 화면 분기 구조를 관리함.
rename-api는apps/rename-ui/dist를/rename-ui경로로 직접 마운트함.- 개발 자산은
15006Vite 개발 서버를 통해 제공할 수 있음. - 서버 템플릿은 React 마운트 지점과 초기 props만 제공하고, 실제 화면 자산 로딩은 Vite manifest 기준으로 수행함.
- Rename 화면은
hub-ui-base.css + hub-ui-desktop.css + junkbox-tabulator.css조합을 기본으로 사용함.
5.6 공통 React 계층
공통 컴포넌트
src/react/components는 공통 아이콘, 하단 선택 시트, 숫자 선택 시트, 단순 피드백 블록 같은 재사용 컴포넌트를 제공함.- 공통 아이콘 모듈은
IconCircleCheck,IconCircleX를 제공함. 상태 아이콘은 화면별 SVG를 만들지 않고 이 모듈을 사용함. hub-ui-base.css는 상태 아이콘용jb-status-icon-success,jb-status-icon-failure클래스를 제공함. 각각 녹색·적색 색상과 제목 앞 간격을 함께 보장함.WorkspaceDetailOverlay는open,title,list,actions,children,onClose를 받아 비모달 목록·상세 구조를 렌더링함.SortableDragHandle은 포털 카드, 대시보드 큰 카드, 대시보드 투자 항목처럼 Sortable 정렬을 사용하는 화면의 표준 핸들 컴포넌트임.SortableDragHandle은 2열 3행 6점 핸들 외형을 제공하며, 화면은aria-label과 배치용 className만 전달함.
로딩과 모달
NoticeCard는 안내 코멘트(note)·빈 상태(empty)·오류(error)를 표기하는 공통 카드임. 앱 화면은 안내·빈 상태·오류 문구를 이 컴포넌트로만 표기하며 규칙은 공통 UI 가이드 2.9를 따름.LoadingBlock은 인라인 블록과 오버레이 두 모드를 제공하는 공통 로딩 컴포넌트임.useModalLock(rootRef, { lockScroll, focusTarget })는 body portal 모달의 공통 동작임.- 모달 밖 body 자식의 기존
inert상태를 보존해 잠그고 종료 시 복원하며, 선택적으로 본문 스크롤을 잠그고(body.jb-body-modal-lock과hub-ui-base.css의html:has(> body.jb-body-modal-lock)규칙이body와 실제 스크롤 주체인html을 함께 잠금) 표시 시 포커스를 옮겼다가 종료 시 복원함. LoadingModal과FormModal이 공유하며 새 body portal 모달도 사용함.
- 모달 밖 body 자식의 기존
LoadingModal은message를 받아LoadingBlock오버레이를 body portal의 고정 모달로 표시함. 배경 body 자식의 기존inert상태를 보존·복원하고(useModalLock), 모달 표시 시 포커스를 옮긴 뒤 종료 시 복원함. 사용자 조작으로 실행한 비동기 작업은 버튼 이름을 유지하며 이 컴포넌트로 진행 상태를 표시함. 성공·실패·취소 후 컴포넌트를 해제하고 관련 입력·버튼을 작업 중 비활성화함.SkeletonBlock은 앱 화면의 최상위 데이터 로딩 체감을 유지하기 위한 공통 skeleton 컴포넌트임.MobileSkeleton은SkeletonBlock과 같은 props 계약을 제공하는 모바일 명명 wrapper임.
SPA 전환
SpaRouteTransition은 SPA 라우트 전환 시 페이지 컨텐츠가 부드럽게 진입하도록 감싸는 공통 컴포넌트이며, 지원 브라우저에서는 View Transition snapshot 대상이 됨.src/react/hooks는 SPA 라우트 변경 후 스크롤 초기화·복원과 화면 안착 상태를 관리하는useSpaRouteSettling, 빠른 요청의 로딩 UI 깜빡임을 줄이는useStableLoading같은 공통 훅을 제공함.- 모바일 본문에서
ListReturnButton은 이전 목록의 스크롤을 복원함.href에 쿼리가 있으면 해당 주소를 사용하며, 경로만 지정하면 같은 경로의 마지막 방문 쿼리를 복원함. SPA는onNavigate로 앱 라우터를 연결하고 그 외에는 앵커 링크로 동작함. bootstrap은 모바일 본문의 스크롤을 경로·쿼리별로 탭 세션에 기억함. 목록 복귀 시 로딩 플레이스홀더가 사라지고 스크롤을 복원할 수 있을 때 적용하며, 기록된 위치가 없으면 기본 위치에서 목록을 엶.
탭과 선택 시트
SegmentedTabs는value,label, 선택적icon,disabled를 갖는 옵션 목록을 받아role=tablist와role=tab접근성 계약으로 렌더링함.SegmentedTabs는 대시보드 PC 탭의 약간 네모난rounded-jb-sm외형을 표준으로 사용하며,fill옵션으로 컨테이너 폭을 균등 분할하고scrollable옵션으로 항목 수가 많은 필터 탭을 가로 스크롤할 수 있음.- 화면은 APP/SERVICE, 페이지 크기, 필터형 운동 부위, 대시보드 보기처럼 인라인 탭이 적합한 옵션 선택 UI를 직접 마크업하지 않고
SegmentedTabs를 우선 사용함. BottomOptionPicker는value,label, 선택적description,detail,icon,disabled를 갖는 문자열 옵션 목록을 받아 모바일 하단 선택 시트를 렌더링함.description과detail은 각각 별도 줄이며 값이 없으면 해당 줄을 만들지 않음.searchScope=label-and-description은 두 보조 문구도 검색함.- 선택적
tabs와 옵션별tabValue로 공용 선택 시트 안의 탭을 구성함. 탭 외형은 공통SegmentedTabs를 재사용하며 옵션 값은 탭을 통틀어 고유해야 함.tabValue·onTabChange로 현재 탭을 제어할 수 있고, 탭을 생략한 기존 화면의 동작은 유지됨. 다중 선택은 탭 간 선택을 유지하고 전체 선택·해제는 현재 탭에 적용함. 검색어는 탭별로 유지함. - 호출 화면이
onSearch를 전달하면 시트의 로컬 필터 대신 검색 버튼이나 Enter로 조회를 요청함.searchQuery·onSearchQueryChange,loading·loadingMessage,error·onRetry,hasMore·onLoadMore,emptyMessage,toolbar는 선택적 화면 연결점임. 실제 API 호출과 도메인 상태는 호출 앱이 소유함. automaticServerSearch모드는 조회 중에도 검색 입력을 허용함. 로딩 문구는 목록 스크롤 영역의role=status로 표시해 시트 크기를 유지함. 일반 조회의 로딩 오버레이와 관련 조작 비활성화는 공용 컴포넌트가 처리함.BottomOptionPicker는onFavoriteChange를 전달한 화면에서 옵션의favorite·favoritePending상태를 받아 별표 버튼과 즐겨찾기 그룹을 표시함. 즐겨찾기 옵션을 앞에 한 번만 배치하고 나머지 원래 순서를 유지하며, 별표 클릭은 선택과 독립적으로 호출 앱에 전달함. 저장·인증·DB 갱신은 호출 앱이 소유함. 즐겨찾기 모드에서도 선택된 항목을 열림 시점에 목록 중앙 근처로 맞추며, 검색 및 임시 선택값을 별표 갱신 중에도 유지함.BottomOptionPicker의searchable은 기본적으로false이며, 활성화하면 목록 위에searchPlaceholder로 문구를 지정할 수 있는 검색 입력을 표시함.- 검색어는 시트를 열 때 초기화하고, 공백을 제거한 뒤 대소문자 구분 없는 일부 포함 검색으로 후보를 좁힘.
searchScope기본값label은 보기 이름만 검색하며,label-and-description은 이름과 설명을 함께 검색함.- 검색 결과가 없으면 안내 문구를 표시하고 확인 버튼을 비활성화하며, 현재 선택 항목이 필터 결과에 없을 때도 확인할 수 없음.
- 검색을 사용하면 목록 스크롤 영역은
42vh높이를 유지해 결과 수에 따라 시트 높이가 달라지지 않음. - 검색을 사용하지 않으면 기존 내용 기준 높이와
42vh최대 높이를 사용함.
- 모바일 화면은 루틴 모드, 운동 부위, 단계 유형처럼 현재 선택값을 먼저 보여주는 선택 UI에
jb-select외형의 버튼과BottomOptionPicker를 조합할 수 있음. BottomOptionPicker는 열림 첫 렌더에서 호출 화면의 현재 선택값을 사용하고, 선택 항목을 내부 scroll container 기준으로 중앙 근처에 보이도록 정렬함. 이전 임시값으로 먼저 이동하지 않으며 문서 전체 스크롤 위치를 변경하지 않음. 다중 선택은 표시 순서에서 처음 선택된 항목을 기준으로 함. 검색 중에는 결과 목록 맨 위를 표시함.BottomOptionPicker는optionAlign으로 옵션 본문 정렬을 제어할 수 있으며, 텍스트형 목록은 좌측 정렬, 숫자형 목록은 중앙 정렬을 사용함.BottomOptionPicker는 불투명한 다크 패널 배경과 저대비 옵션 카드 톤을 자체적으로 포함하여,hub-ui-mobile.css를 로드하지 않는 PC/모바일 겸용 화면에서도 배경 컨텐츠와 겹쳐 읽기 어려운 상태를 만들지 않음.BottomNumberPicker는 숫자 선택 전용 공개 API를 유지하는 얇은 wrapper이며, 실제 시트 외형과 스크롤 동작은BottomOptionPicker를 재사용하고 옵션 텍스트는 중앙 정렬함.
유틸
src/react/utils는 토스트, HTTP 요청, 페이지 props 파서, SPA navigation 보조 유틸, Tabulator 점진 로딩 유틸, 포맷터, HTTP 오류 판정 유틸을 제공함.requestJson은 본문이 없는 HTTP 204·205 성공 응답을 빈 객체로 처리하며, JSON 응답과 오류 응답은 기존 내용에 따라 해석함.src/react/utils/unique-id.ts의createUuid()는crypto.getRandomValues()로 UUID v4를 만들며,http.ts의createRequestKey()와 행 키 생성이 이를 사용함.crypto.randomUUID()는 HTTPS·localhost 같은 보안 컨텍스트에서만 존재해 LAN HTTP 개발 접속에서 예외가 나므로 앱 코드는 직접 호출하지 않음.getRandomValues()는 모든 컨텍스트에서 동작해 접속 방식에 따른 분기가 없음.just check-browser-apis(scripts/check_browser_api_rules.py)가apps와libs/shared-ui/src의crypto.randomUUID직접 호출을 검사함.
src/react/utils/authed-api.ts의createAuthedApi({ module, basePath, timeoutMs })는 앱 모듈의api(path, method, body)호출 함수와redirectForAuth(error)를 만듦.redirectForAuth는 401·403이면 Hub 공통 로그인으로required_module(403은permission_denied=1)과 현재 주소를 전달해 이동하고true를 돌려줌.errorMessage(error, fallback)은 서버 오류 문구를 쓰고 일반 문구면 화면별 기본 문구로 대체함.src/react/hooks/useAuthedLoader.ts의useAuthedLoader(load, failure, redirectForAuth)는 조회를 불러오고 탭 복귀·bfcache 복원 때 다시 조회하며 늦게 도착한 이전 응답을 버림.- QuestLog와 SipMon이 사용하며 앱은 이 로직을 복제하지 않음.
src/react/utils/datetime.ts는Asia/Seoul기준 오늘 날짜·현재 시각·datetime-local입력값, KST offset 직렬화, 날짜 경과일과 표시 포맷을 제공함. 날짜 전용 문자열과 SQLite의 timezone 없는 KST 일시는 시각 변환 없이 해석하고, offset이 있는 일시는 KST로 변환함. 앱 화면은 브라우저 로컬 시간대나toISOString().slice(0, 10)으로 업무 날짜를 만들지 않음.src/react/utils/units.ts는 단위 표기 표준(공통 UI 가이드 2.8)을 적용하는formatQuantity·withUnit과 예정 포함 합계용formatPlannedIncluded·formatPlannedNote를 제공함. 앱 화면은 숫자와 단위를 직접 이어 붙이지 않음.SemicircleGauge의displayValue는 가운데 숫자와 접근성 문구에만 쓰는 표시 값이며 채움·비율·판정은value기준임.- 날짜와 요일은
formatDateWithWeekdayInKst()(YYYY-MM-DD (요일)), 연도를 뺀 월일은formatMonthDayWithWeekdayInKst()(MM-DD (요일))와 범위용formatMonthDayRangeWithWeekdayInKst()를 사용함.- 서버에서 받은 일시를 날짜·시간 입력에 넣을 때는
dateTimeInputFromKst()를 사용함. - 브라우저에서 얻은 시점을 API용 KST 문자열로 보낼 때는
instantToKstIso()로 밀리초와+09:00을 포함함.
- 서버에서 받은 일시를 날짜·시간 입력에 넣을 때는
src/react/utils/sortable.ts의JUNKBOX_SORTABLE_BASE_OPTIONS는 Sortable의animation,delay,delayOnTouchOnly,forceFallback,chosenClass,ghostClass,dragClass,fallbackClass기준을 제공함.- HTTP 오류 판정 유틸은
RequestError메시지 해석과409 Conflict또는 already-exists 계열 응답을 판정하는isConflictError를 제공함. resolveErrorMessage는 오류 메시지가 비어 있거나 일반 문구Request failed이면 화면이 넘긴 기본 문구를 반환하고, 서버가 준detail문구가 있으면 그대로 반환함.src/react/utils/number-input.ts는 숫자 입력 제한을 제공함.sanitizeDecimalInput(value, maxDecimals = 2)는 숫자와 점 하나만 남기고 소수 자릿수를 제한하며,sanitizeIntegerInput(value, maxLength = 9)는 숫자만 남김.isValidDecimal(value, min, max)는 빈 값을 선택 입력으로 통과시키고 값이 있으면 숫자 형식과min~max범위를 검사함.- 소수·정수 입력은
inputMode와 이 유틸로 입력 제한과 저장 전 검증을 함께 적용함.
- SPA navigation 보조 유틸은 React Router navigation과 조합할 수 있는
createSpaNavigateOptions, 브라우저 View Transition fallback을 포함한runSpaViewTransition을 제공함. - UI 앱은 공통 유틸을 직접 복제하지 않고
@shared-ui/*alias로 이 계층을 소비함.
음성 재생
@shared-ui/utils/speech의createSpeechPlayer()는 한국어 브라우저 음성 재생을 기본으로 제공함.speak(text)는 진행 중인 공통 발화를 교체하고,cancel()은 호출한 플레이어가 재생 중인 발화를 중단함.speak(text)의 Promise는 음성 종료·취소·오류·브라우저 미지원 또는 제한 시간 경과 시 완료됨. 안내 문구와 시점은 사용하는 기능이 결정함.
5.7 SPA 적용 공통 틀
- SPA 화면은 서버 템플릿이 공통 앱 셸, React 마운트 루트, 최소 page props, 단일 엔트리 스크립트만 제공하는 구조를 사용함.
- 화면별 실제 라우트 선택, URL path parameter, query string 해석은 React Router가 담당함.
- 서버 앱 셸 네비게이션 링크를 SPA 내부 이동으로 처리해야 하는 화면은 템플릿 컨텍스트에
spa_navigation=true를 전달함. spa_navigation=true인 화면에서app-shell.js는 동일 origin 링크 클릭을 가로채고junkbox:spa-navigate이벤트를 발행함.- React 앱은
junkbox:spa-navigate이벤트를 수신해 React Router navigation으로 연결함. - React Router navigation은
createSpaNavigateOptions와runSpaViewTransition을 함께 사용하여 브라우저 View Transition 지원 여부와 무관하게 동일한 호출 구조를 유지함. - 라우트 본문은
SpaRouteTransition으로 감싸고, 라우트 key는 일반적으로location.pathname을 사용함. - 라우트 변경 직후 스크롤 초기화와 오브젝트 안착 상태는
useSpaRouteSettling으로 처리함. - 빠르게 끝나는 요청의 skeleton 깜빡임은
useStableLoading으로 제어하고, 화면별 임의 타이머를 만들지 않음. - 최상위 데이터 로딩 placeholder는
SkeletonBlock을 우선 사용함. SpaRouteTransition,useSpaRouteSettling,useStableLoading,SkeletonBlock,runSpaViewTransition은 모바일 전용이 아니라 PC/모바일 양쪽에서 사용할 수 있는 공통 SPA/상호작용 기반임.- 모바일 바텀 액션바 안착, 모바일 시트, 모바일 고정 폭 같은 화면 구조 종속 규칙은 mobile CSS 책임으로 유지함.
- 모바일 화면에서
.jb-spa-route-stage는 viewport fixed 요소가 문서 끝으로 밀리지 않도록 containment, route animation, will-change 기반 격리 효과를 비활성화함.
6. 템플릿과 스크립트 규칙
6.1 베이스 템플릿
- 공통 베이스 템플릿은 앱 셸, 글로벌 자산 링크, page props 주입 지점을 제공함.
- 서버 앱은 베이스 템플릿에 필요한 컨텍스트를 주입하고 화면별 블록만 채움.
shared-uistylesheet 매크로는hub-ui-base.css,hub-ui-mobile.css,hub-ui-desktop.css, Tabulator vendor CSS,junkbox-tabulator.css같은 공통 스타일 링크의 단일 선언 지점임.- 공통 베이스 템플릿은 stylesheet 매크로를 import하고,
include_mobile_css,include_desktop_css,include_tabulator_css값으로 CSS 조합을 결정함. - 개별 화면 템플릿과 standalone HTML 템플릿은 공통 CSS 링크를 직접 선언하지 않고 stylesheet 매크로를 호출함.
- 공통 베이스 템플릿은 inline
<style>블록을 포함하지 않음. - 공통 앱 셸을 상속하지 않는 로그인 화면도 같은 stylesheet 매크로를 사용해 CSS 공급 경로를 중앙화함. Chess 화면은
base.html을 상속하여 공통 상단 메뉴바와 모바일 드로어를 사용함. - 모바일 로그인 화면은
hub-ui-base.css + hub-ui-mobile.css조합을 사용하고 Tabulator CSS를 로드하지 않음. - Chess 화면 HTML은
hub-ui-base.css + hub-ui-desktop.css조합을 사용하며 Tabulator CSS는 로드하지 않음. 모바일 본문 폭과 외부 좌우 여백은 base CSS에서 적용함. - 서버 앱이 전달하는
brand_title및app_name은 Hub 이외 앱에서JunkBox {Portal menu_name}을 사용함. Portal 메뉴 이름은 짧게 유지하며 접두어 중복과 앱 이름 대소문자 불일치를 만들지 않음. Hub는 기존 브랜드 표시를 유지함. - 공통 앱 셸의
brand_subtitle은 포털 메뉴에서 전달된 값이 있을 때만 브랜드 제목 아래에 렌더링함. 설명이 없으면<small class="jb-brand-subtitle">요소도 생성하지 않음. - 공통 베이스 템플릿은
viewport-fit=cover,theme-color, 서비스 워커 등록 같은 모바일/PWA 공통 진입점을 제공함. - 공통 베이스 템플릿은
favicon_url컨텍스트가 있으면<link rel="icon">을 렌더링함. - stylesheet 매크로와 공통 베이스 템플릿은
shared_ui_asset(asset_name)헬퍼를 통해hub-ui-base.css,hub-ui-mobile.css,hub-ui-desktop.css,junkbox-tabulator.css,app-shell.js에 버전 쿼리를 붙인 URL을 렌더링함. - 공통 베이스 템플릿은 기본적으로
body_mode_class기준으로 모바일 화면에는base + mobile, 데스크탑 화면에는base + desktop조합을 로드함. - 화면 컨텍스트의
include_mobile_css,include_desktop_css값은 기본 CSS 조합에 필요한 모드 CSS를 추가로 포함할 때 사용함. /portal은 본문 모바일 고정 폭과 공통 메뉴바 반응형 동작을 함께 만족해야 하므로base + mobile + desktop조합을 사용함.- Vite dev client와 React refresh preamble도 같은 베이스 템플릿의 단일 선언 지점에서 처리함.
spa_navigation=true컨텍스트를 받은 화면은 공통 앱 셸 링크 클릭을junkbox:spa-navigate브라우저 이벤트로 전환할 수 있음.- 개별 화면 템플릿은 개발 모드 여부와 무관하게 화면 엔트리 스크립트만 선언함.
6.2 그리드 헤더 템플릿
- 단일 그리드형 화면과 2패널 작업형 화면 모두 같은 공통 헤더 구조를 재사용할 수 있도록 제공함.
6.3 Tabulator 헬퍼
junkbox-tabulator.js는 공통 요청, 피드백, 토스트, HTML 이스케이프를 담당함.- 화면별 TypeScript 코드는 이 헬퍼를 기준으로 API 호출과 사용자 피드백을 처리함.
- 사용자 노출 문구는 화면 코드나 템플릿에 한국어 문구로 직접 작성함.
- 공통코드 라벨과 메타 설정값처럼 데이터 자체가 마스터데이터인 값만 DB 조회 구조를 사용함.
6.4 앱 셸 스크립트
- 앱 셸 로직의 소스 오브 트루스는
app-shell.ts임. app-shell.js는 전역 메뉴 토글과 공통 셸 상호작용을 담당하는 배포 산출물임.spa_navigation=true인 화면에서app-shell.js는 동일 origin 링크 클릭을 가로채고 React 앱이 처리할 수 있는junkbox:spa-navigate이벤트를 발행함.- 앱별로 메뉴 동작을 다시 구현하지 않음.
- 메뉴 드로어를 닫는
resize기준 폭은breakpoints.json의pc를 import해 사용하며 CSS의 PC 네비게이션 전환 폭과 항상 같은 값을 유지함. - 포털 카드, 모바일 고정 폭, 모바일 본문 고정 폭, safe-area, 모바일 바텀 액션바 같은 예외 레이아웃도 공통 CSS 클래스에서 관리함.
- health 모바일 헤더 변형도 같은 공통 템플릿/공통 자산 기준으로 처리함.
- 버전 쿼리가 붙는 공통 자산 링크는 CDN이 이전 배포의 CSS/JS를 고정 경로 기준으로 계속 캐시하는 문제를 줄이기 위한 기본 구조임.
- 단일 통합 번들
hub-ui.css는 사용하지 않으며, 분리 자산 조합을 현재 기준으로 사용함.
6.5 개발 모드 템플릿 연동
- 서버 템플릿 컨텍스트는 요청 헤더 기준 dev server origin을 해석할 수 있음.
- hub 개발 모드 엔트리 경로는
/hub-ui/src/entries/*.tsx기준을 사용함. - hub Vite dev client 경로는
/hub-ui/@vite/client임. - hub React refresh runtime 경로는
/hub-ui/@react-refresh임. - health 개발 모드 엔트리 경로는
/health-ui/src/entries/health.tsx기준을 사용함. - health Vite dev client 경로는
/health-ui/@vite/client임. - health React refresh runtime 경로는
/health-ui/@react-refresh임. - health 개발 모드에서 PWA manifest와 service worker 링크는 공통 베이스 템플릿이 렌더링하지만,
/health.webmanifest,/health-sw.js요청의 실제 프록시는apps/health-uiVite 설정이 담당함. - 앱별 Vite 설정은 공통 베이스 템플릿이 생성한 PWA 동일 origin URL이 개발 서버 origin에서 404로 처리되지 않도록 해당 앱 백엔드로 프록시해야 함.
- rename 개발 모드 엔트리 경로는
/rename-ui/src/entries/*.tsx기준을 사용함. - rename Vite dev client 경로는
/rename-ui/@vite/client임. - rename React refresh runtime 경로는
/rename-ui/@react-refresh임. - wow 개발 모드 엔트리 경로는
/wow-ui/src/entries/*.tsx기준을 사용함. - wow Vite dev client 경로는
/wow-ui/@vite/client임. - wow React refresh runtime 경로는
/wow-ui/@react-refresh임. - chess 개발 모드 엔트리 경로는
/chess-ui/src/entries/chess.tsx기준을 사용함. - chess Vite dev client 경로는
/chess-ui/@vite/client임. - chess React refresh runtime 경로는
/chess-ui/@react-refresh임. - 루트 리다이렉트와 프록시 분기는 각 UI 앱의 Vite 설정이 담당하고, 공통 베이스 템플릿은 계산된 자산 URL만 소비함.
7. 공통 레이아웃 및 컴포넌트 제공 범위
7.1 공통 컴포넌트와 아이콘
shared-ui는 앱 셸, 패널, 버튼, 입력창, 칩, 토스트, 모달, 그리드 래퍼, 모바일 고정 폭 클래스 같은 공통 자산을 제공함.shared-ui는 공통 SVG 아이콘과 공통 브라우저 유틸도 제공함.- React 아이콘 모듈은
IconMenu,IconPlus,IconTrash,IconChevronDown같은 재사용 아이콘을 제공함. 접힘 상태를 표현하는 화면은IconChevronDown의 회전으로 아래·위 방향을 전환하며 별도 SVG를 만들지 않음. shared-ui는 화면 크기와 무관한 SPA 전환용.jb-spa-route-stage,.jb-spa-route-settling기반 안착 애니메이션,jb-skeleton계열 클래스를 base CSS로 제공함.shared-ui는 터치 환경에서 버튼, 카드, segmented tab, 다크 필드가 가볍게 눌리는 피드백을 공통 base CSS로 제공함.shared-ui는 액션 영역 칸막이용jb-action-divider, Sortable 핸들/ghost/chosen/fallback 공통 클래스, 대시보드 카드 드래그 클래스, 투자 항목 드래그 클래스를 base CSS로 제공함.
7.2 segmented tab·포털·정렬 핸들
jb-segmented-tabs,jb-segmented-tabs--fill,jb-segmented-tabs--scrollable,jb-segmented-tab,jb-segmented-tab-icon,jb-segmented-tab-label은SegmentedTabs의 표준 외형과 폭 정책을 담당함.- 공통 segmented tab은 대시보드 PC 탭의 낮은 대비, 얇은 경계선,
rounded-jb-sm반경을 기준으로 하며, 과하게 둥근 pill 외형을 표준으로 사용하지 않음. jb-portal-card-title은 포털 APP/SERVICE 카드 이름을 normal weight로 표시하는 제목 클래스이며, 카드 이름에 별도 굵은 강조를 적용하지 않음.jb-sortable-drag-handle,jb-sortable-drag-dots,jb-sortable-drag-dot은 공통 드래그 핸들 외형을 담당함.jb-sortable-chosen,jb-sortable-ghost,jb-sortable-dragging,jb-sortable-fallback은 Sortable 상태별 시각 규칙을 담당함.
7.3 대시보드
jb-dashboard-grid는 PC 기준 4열 x 2행 고정 슬롯 대시보드 배치를 제공하고, 모바일 기준 1열 자연 높이 목록으로 전환됨.jb-dashboard-card-shell,jb-dashboard-card-head-actions,jb-dashboard-card-drag,jb-dashboard-asset-drag은 대시보드 큰 카드와 카드 내부 투자 항목 정렬을 같은 공통 sortable 규칙에 연결하기 위한 클래스임.jb-dashboard-icon-button,jb-dashboard-favorite-button은 대시보드 카드 헤더의 아이콘 버튼과 즐겨찾기 활성 상태를 표현함. 즐겨찾기 버튼은ToggleButton의icon변형을 사용함.jb-dashboard-news-list,jb-dashboard-asset-list,jb-dashboard-process-list는 PC 고정 카드 높이 안에서 내부 스크롤을 사용할 수 있는 대시보드 목록 영역임.jb-dashboard-mobile-tab-trigger,jb-dashboard-mobile-tab-main은 모바일 대시보드에서 현재 보기 선택 버튼을 표시하고, PC 인라인 탭과 같은 옵션 집합을 하단 선택 시트로 연결하기 위한 클래스임.SemicircleGauge는 선택적fillRatio로 호의 채움 눈금을 기준 비율과 분리하고,markerRatio로 같은 눈금의 목표 위치에 짧은 표시선을 그림.tone(StatusTone)을 지정하면 채움·상태칩 색을 상태 색 표준이 정하고(jb-gauge-tone-*) 미지정이면state별 기존 색을 씀(SipMon이 사용).plannedRatio·plannedTone은 채움 뒤에 이어지는 예정 구간을 옅은 색(jb-gauge-planned--*)으로 그림.- Hub 음식 카드는 게이지마다 자기 눈금(끝=목표)을 쓰고
jb-gauge-compact외형을 사용함.
7.4 모바일 레이아웃과 폼
shared-ui는 모바일 바텀 액션바, 모바일 시트, 모바일 고정 폭처럼 실제 모바일 레이아웃에 종속된 규칙만 mobile CSS로 제공함.- 모바일 폼은
jb-form-stack의 필드 간격과jb-field·jb-field-label의 라벨·입력 간격을 사용함.jb-mobile-checkbox는 목록 선택 크기를 통일하고jb-mobile-sheet-backdrop--center는 작업 진행 시트를 화면 중앙에 배치함. jb-workspace-overlay와jb-workspace-overlay-detail은 전체 폭 목록 위에 오른쪽 50%의 불투명한#111111상세 패널을 겹쳐 표시함. 패널은 전체 화면 backdrop을 만들지 않아 목록의 노출 영역을 계속 조작할 수 있고, 뷰포트 폭이pc기준(1440px) 미만이면 상세 폭이 100%임.
7.5 데스크톱 작업 화면과 입력 필드
shared-ui는 데스크톱 작업 화면용jb-workspace-screen-fit,jb-grid-panel-viewport, 공통 카운트 칩, 플랫 로딩 오버레이 스타일을 제공함.hub-ui-desktop.css는jb-body-desktop의 대시보드 외 본문에서.jb-main의 가로 스크롤과.jb-page-stack의 최소 1440px 폭을 관리함.jb-body-no-scroll화면도 본문 가로 스크롤은 허용하고 세로 스크롤은 내부 패널에 유지함. 공통 메뉴바는 본문 스크롤에 따라 이동하지 않음.jb-modal-panel-compact는 캐릭터 관리처럼 좁은 관리 모달의 폭을 제한하고,jb-inline-form-button은 인라인 입력·선택 컨트롤과 버튼 높이를 맞춤.jb-input은 텍스트 입력 전용 시각 규칙을 사용하며 select chevron 배경을 포함하지 않음.ProgressBar(src/react/components/ProgressBar.tsx)는tone,valueRatio,plannedRatio,plannedTone,markerRatio를 받아 SVG로 막대(jb-progress)를 그리며 inline style 없이 위치를 SVG 속성으로 지정함.- 비율은
progressGeometry(src/react/utils/progress.ts)가 계산함: 눈금 끝은max(목표, 값 + 예정)이고 값(예정 포함)이 목표를 넘을 때만markerRatio가 있으며 예정 구간 색은 합계가 목표를 넘으면FAIL, 아니면IN_PROGRESS임. jb-status-badge와--in-progress·--success·--fail·--undetermined수정자는 상태 알약 배지임.
- 비율은
LineChart는 레이블과 수치 배열을 Canvas 선 그래프로 표시함. 값이 비어 있는 지점에서 선을 끊고 텍스트 요약을 보조기기에 제공함.- QuestLog 미션 카드가 쓰는 기준임.
7.6 선택·다크 필드
jb-select는 select 성격 UI에만 chevron 배경, 우측 구분선, 우측 padding을 제공함.jb-select를 모바일 선택 시트 trigger 버튼 외형으로 사용할 때 화면 컴포넌트는 별도 chevron 텍스트나 아이콘을 중복 추가하지 않음.- 텍스트 선택 시 입력창, select, 버튼의 selection 색상은 공통 다크 테마 안에서 안정적으로 보이도록 shared-ui가 관리함.
jb-mobile-card,jb-mobile-card-soft,jb-dark-field,jb-dark-chip,jb-dark-status계열 클래스는 health와 hub 양쪽에서 공유하는 다크 톤 자산임.jb-mobile-card--selected는 기본 모바일 카드 위에 선택 상태를 적용하는 modifier이며, 청색 계열 테두리와 내부 강조를 제공함.jb-dark-field는 input/select 공통 다크 필드로 사용할 수 있으며, select option과 optgroup도 공통 다크 배경과 밝은 글자를 사용함.
7.7 Chess 전용 클래스
jb-chess-*계열 클래스는 Chess 복기·실시간 대국의 좌측 계정·목록, 중앙 보드, 우측 분석·진행 정보와 모바일 단일 컬럼 화면을 지원하는 공통 base CSS 클래스임.ControlPanelButton은 outline·primary·tile 변형과 아이콘을 제공하고,ControlPanelStatus는 상태 라벨·수치·아이콘을 표시하는 공통 React 요소임.jb-control-panel*base CSS를 PC와 모바일에서 공유하며 Chess 보드 조작과 대국 목록의 AI 상태에 조합해 사용함.jb-chess-board-stage와jb-chess-board-viewport는 일반·터미널 렌더러가 같은 정사각 영역을 사용하도록 하고, 보드 아래 메타가 렌더러 교체나 FHD 높이 제한에 의해 잘리지 않도록 함.jb-chess-terminal*은 양옆 행 번호와 대소문자 기물, 마지막 수·선택 칸을 표시하는 터미널 보드 자산임. 헤더·UCI 입력 폼·위아래 열 문자 행·격자 상하 구분선 없이 8행 문자 격자를 중앙에 배치함.jb-chess-terminal__matrix는 좌우 행 번호 폭과 grid 간격을 고려해 높이를 조정하여 보드 칸을 정사각형에 가깝게 유지하며, 문자 렌더링에는 모노스페이스 폰트를 사용함.jb-chess-setup-*은 대국 설정 모달의 상대·시간·색상 선택, 레이팅 체크, 1~8단계 AI 난이도 슬라이더, 제출 상태를 표시함.- Chess 버튼은 전용 클래스를 두지 않고 공통
Button·ToggleButton과jb-button-compact를 사용함. 설정 모달의 선택 버튼 정렬은jb-chess-setup-choices·jb-chess-setup-times안의jb-choice-accent가 담당함. jb-chess-board-context계열 클래스는 실제 진행·엔진 최선수 비교·PV 재생의 보조 표기 영역임. 보드와 같은 가로 폭으로 정렬하며 데스크톱에서는 높이를 유지하고 모바일에서는 내용이 없을 때 숨김.jb-chess-board-context__best와jb-chess-board-context__actual은 최선수와 실제 수를 구분하는 표기임.jb-chess-board-meta는 체스판 하단의 판세/판단 메타 grid이며, 모바일에서는 2열, PC/FHD 기준에서는 4열을 사용함.jb-chess-log-stream은 수별 분석 카드가 많아질 때 페이지 전체가 아니라 분석 영역 내부에서 스크롤되도록 구성됨..jb-body-chess는 폭chess-wide(1500px) 이상에서 공통 앱 헤더 아래 남은 viewport 높이를 Chess 작업 영역에 배분함. Chess 셸과 3열 레이아웃은 이 높이를 채우고 페이지 전체 스크롤을 막으며, 대국·분석 목록은 각 영역에서 스크롤함.jb-chess-analysis-card계열 클래스는 수순, 판정, 실제 평가, 평가 손실, 엔진 제안을 1행 metric grid로 표시하고, AI 코멘트와 생각해 볼 점을 분리된 본문 영역으로 표시함.jb-chess-analysis-card__severity는 상대 수·최선·부정확함·실수·블런더 등 수의 판정 배지임.jb-chess-analysis-card__section--comment,jb-chess-analysis-card__section--question은 AI 코멘트와 생각해 볼 점의 낮은 대비 구분 영역임.- Lichess 원본 대국 링크처럼 링크를 버튼 외형으로 표시할 때는
buttonClassName("ghost", { compact: true })를 사용함. - 공통 React 아이콘
IconRefresh는RefreshCw를 감싼 기본 크기·선 두께의 아이콘이며 Chess 계정 영역의 새로고침 버튼에 사용함. jb-chess-left-account는 좌측 상단에 고정되는 Lichess 연동 상태·연동 해제·PGN 업로드 제어 영역임.jb-chess-left-history와jb-chess-left-history__list는 계정 영역 아래에서 내부 스크롤하는 완료 대국 목록 영역임.jb-chess-history-card계열 클래스는 상대와 결과를 첫 줄에, 종료 시각·사용자 색상 또는 관전 여부·엔진 상태를 둘째 줄에 표시하는 압축형 대국 카드임.
7.8 모바일 페이지와 하단 액션바
jb-mobile-page,jb-mobile-bottom-bar-page,jb-mobile-bottom-bar,jb-workout-set-grid,jb-workout-latest-record-*계열 클래스는 모바일 편집 UX를 공통 규칙 안에서 구현하는 클래스임.--jb-mobile-content-gutter의 기본값은6px이며 모바일 본문 카드 외부 좌우 여백을jb-main한 곳에서 적용함.jb-mobile-page와jb-mobile-bottom-bar-page는 외부 좌우 여백을 추가하지 않고 배치와 하단 여백을 담당함.jb-body-mobile·jb-body-mobile-content는360px본문 폭에 이 규칙을 적용하며 Chess는chess-split(900px) 미만 단일 열에서, Hub 대시보드는pc(1440px) 미만 모바일 구간에서 같은 변수를 사용함.- Hub·Health 로그인 셸과 Message 단독 개발 진입점도
jb-main을 사용함.
jb-workout-set-head는 세트 입력 그리드 헤더의 크기, 두께, 자간, muted 색상만 담당하며 대문자 변환을 강제하지 않음. 따라서중량 (kg)같은 단위 표기는 소스 문구의 대소문자를 그대로 유지함.jb-mobile-bottom-bar는 모바일 viewport 하단 고정 액션 영역이며, SPA 라우트 전환 컨테이너 안에서도 화면 하단 기준으로 동작해야 함.src/scripts/app-shell.ts는 모바일 전용·겸용 셸의jb-mobile-bottom-bar추가·제거를 감지하고ResizeObserver로 실제 높이를 관찰함.jb-main-with-bottom-bar와--jb-mobile-bottom-bar-height를 갱신하며, 모바일 CSS는--jb-mobile-bottom-bar-clearance와 실제 높이 중 큰 값을jb-main하단에 적용함.- 액션바가 있는 화면의
jb-mobile-page·jb-mobile-bottom-bar-page하단 여백은 해제해 중복을 막음. - 두 페이지 클래스는 폭·배치에 따라 선택하며 액션바 여백의 필수 조건이 아님.
7.9 하단 버튼 폭
jb-mobile-range는 문제 수·난이도처럼 모바일에서 단계별로 드래그하는 공통 range 입력 외형임.- 하단 버튼 폭은 신규 개발과 기존 화면 수정에서 세 경우를 구분함. 텍스트 버튼만 있으면 전체 폭을
1/n으로 균등 분할하고, 아이콘 버튼만 있어도 전체 폭을1/n으로 균등 분할함. 텍스트와 아이콘이 섞여 있을 때만 아이콘 버튼 각각을 고정 정사각형으로 두고 텍스트 버튼은 남은 폭을1/n으로 균등 분할함. 아이콘만 있는 화면에 최소 폭 아이콘 버튼을 왼쪽으로 모아 두지 않음. - 하단 액션바의 모든 직접 버튼에
jb-mobile-bottom-bar-button을 붙이고 아이콘 전용 버튼에는jb-mobile-bottom-bar-icon을 함께 붙임. 화면별 고정 폭·최소 폭 지정으로 버튼 분배를 제어하지 않음. 기존flex-1·shrink-0유틸리티보다 공통 CSS의 하단 액션바 규칙이 우선하며, 신규 코드는 이 유틸리티에 폭 계산을 맡기지 않음. hub-ui-mobile.css는 모든 하단 버튼을 기본flex: 1 1 0%로 균등 분할하고,:has()로 텍스트·아이콘 혼합 상태를 감지할 때만 아이콘을 고정 정사각형으로 전환함. 텍스트 버튼은 남은 폭을 균등 분할함. 조건부 버튼이 나타나거나 사라져도 현재 표시된 조합에 맞춰 자동 갱신됨.- 하단 액션바의 실제 삭제 휴지통 버튼은
jb-button jb-button-danger jb-mobile-bottom-bar-button jb-mobile-bottom-bar-icon을 조합해 빨간 배경으로 표시함.jb-button-danger는 배경·테두리·글자색을 공통 제공하며, 비활성화된 삭제 버튼도 위치와 무관하게 공통 CSS가 낮은 채도의 빨간 배경으로 표시함. 삭제 버튼을 흰색 강조 또는 고스트 외형으로 대체하지 않음. - 어떤 레이아웃과 시각 규칙을 선택해야 하는지는
docs/junkbox/common/guide-jb-common-ui.md를 따르고, 이 문서는 그 규칙을 구현하는 클래스와 산출물 위치를 설명하는 데 집중함.
8. Tabulator 연동 기준
8.1 공통 자산
- 편집형 표는 Tabulator를 기준으로 함.
- Tabulator 원본 자산과 커스텀 CSS는
shared-ui가 제공함. - 공통 JS 헬퍼는 요청, 피드백, 토스트 처리에 사용함.
- 행 선택 컬럼은
tabulatorSelectionColumn을 사용함. Tabulator가 개별·전체·부분 선택 상태를 관리하고 공통 Tabulator CSS가 폼 체크박스와 같은 외형 및 셀 정렬을 적용함. hover/selected 행 강조와 기본 줄무늬 비활성화도 공통 Tabulator CSS가 제공함. list editor셀에 공통 chevron 표시를 주는jb-cell-editor-list클래스도 공통 Tabulator CSS에서 제공함.- Tabulator
list editor드롭다운과 select 성격 입력 UI는 브라우저 기본 흰색 팝업 대신 공통 다크 테마 규칙을 사용함. - 레이드 점수형 셀처럼 숫자 자체는 플랫하게 유지하고, 잠정 상태만 셀 배경으로 강조하는 패턴도 공통 Tabulator CSS에서 제공함.
8.2 구현 전제
- 그리드는 부모 높이를 채우는 구조를 사용함.
- 그리드 로딩 정책 자체는
docs/junkbox/common/guide-jb-common-ui.md를 기준으로 결정하며,shared-ui는 그 정책을 구현할 수 있는 공통 레이아웃과 시각 자산 제공에 집중함. - 점진적 스크롤 로딩형 Tabulator 화면은 내부
tableholder생성 시점이 비동기적일 수 있으므로, 관련 초기화 헬퍼가 이 전제를 처리하는 구조를 사용함. - React Tabulator 화면은
@shared-ui/utils/tabulator-header-filter의JunkboxTabulator를 생성함. 이 래퍼는 입력형headerFilter를 공통 검색 문법으로 설정하고setColumns,addColumn으로 나중에 넣는 컬럼에도 같은 규칙을 적용함. - 클라이언트 조회형 그리드는 일반 입력을 대소문자 무시 일부 포함,
=를 정확 일치로 처리함. 숫자·날짜 컬럼의 부등호는 비교 연산이며 날짜 비교 입력은 유효한YYYY-MM-DD형식이어야 함. 숫자·날짜 타입 추론이 어려운 컬럼은headerFilterFuncParams.kind를number또는date로 지정함. - 원격 조회형 그리드는 필터 원문을 API에 전달하며,
@shared-ui/utils/tabulator-progressive의withRemoteHeaderFilters를 사용하는 점진 로딩 화면은 로컬 필터가 현재 적재된 행만 줄이지 않도록 설정함.
9. 운영 원칙
- 공통 UI 규칙은 개별 앱에 복제하지 않음.
- 화면 전용 CSS 파일을 만들지 않음.
- 새 스타일이 필요하면 먼저
shared-ui에 공통 클래스로 추가함. - 테마 변경과 레이아웃 토큰 변경은
shared-ui에서 먼저 수행함. - 공통 스타일 산출물 밖에서 CSS 또는 inline style을 추가하지 않음.
jb-button:disabled는 회색 계열 배경·경계·텍스트와not-allowed커서를 사용하는 공통 비활성 외형임. 화면은 비활성 상태를 별도 흰색 버튼 외형으로 재정의하지 않음.- 앱 화면은 공통 Tailwind 유틸리티와
jb-*클래스를 조합함. 화면에 새 utility class를 추가한 경우에는shared-uiCSS 산출물을 재생성한 뒤 해당 앱을 빌드하고, 실제 대상 viewport에서 적용 여부와 문서 스크롤 여부를 함께 검증함. - 폰트 선언과 폰트 상속 규칙은
hub-ui-base.css를 단일 진입점으로 유지함. - 스타일 산출물은 배포 전 빌드 상태를 보장해야 함.
- 공통 프런트 로직 소스는 TypeScript 기준으로 유지함.
.js파일은 배포 산출물 또는 외부 라이브러리 자산일 때만 허용함.
10. 관련 문서
- 화면 조합 규칙과 구현 체크리스트는
docs/junkbox/common/guide-jb-common-ui.md를 따름. - 프로젝트 전체 구조는
docs/junkbox/common/guide-jb-overview.md, 공통 원칙은docs/junkbox/common/guide-jb-core.md를 따름. - hub 프런트 앱 구조는
docs/junkbox/apps/guide-apps-hub-ui.md를 따름. - rename 프런트 앱 구조는
docs/junkbox/apps/guide-apps-rename-ui.md를 따름. - health 프런트 앱 구조는
docs/junkbox/apps/guide-apps-health-ui.md를 따름. - chess 프런트 앱 구조는
docs/junkbox/apps/guide-apps-chess-ui.md를 따름.