관리자 Material navigation·data UI
조사 고정점
Section titled “조사 고정점”| 항목 | 값 |
|---|---|
| 마지막 조사 | 2026-07-17 |
| 적용 화면 | frontend-repo 관리자 shell과 dashboard data collection |
| MUI | @mui/material@9.2.0, @mui/icons-material@9.2.0 · MIT |
| table model | @tanstack/react-table@8.21.3 · MIT |
| framework | astro@7.1.0, React island |
| 고정 근거 | frontend revision fbed8f864542ddd26d6756e368a003795c669adf |
현재 규격 권위는 Google의 Navigation Rail 지침과 adaptive navigation 지침, MUI의 Drawer, container query, breakpoint, v9 migration 문서, TanStack의 Table v8 개요다.
native capability와 결손
Section titled “native capability와 결손”| 요구 | OSS native capability | 적용 판정 |
|---|---|---|
| compact navigation | MUI AppBar, IconButton, temporary Drawer | 그대로 사용 |
| medium/expanded navigation | MUI permanent Drawer, list, selected state, transition | 이 primitive로 M3-informed rail을 구성 |
| native Navigation Rail component | MUI의 지원 component 표에 Navigation Rail 없음 | native MUI rail이라고 부르지 않음 |
| semantic desktop data | MUI Table, TableHead, TableBody, caption | 그대로 사용 |
| row/column model | TanStack useReactTable()과 getRowModel() | table과 card가 한 row model 공유 |
| narrow data UI | MUI Card, CardContent, typography | table을 줄이지 않고 별도 세로 card collection으로 치환 |
| component-width 반응 | MUI container query | viewport query 대신 collection의 실제 가용 폭 사용 |
Google 지침은 navigation rail을 tablet/desktop의 주요 목적지 3–7개에 권한다. 현재 실제 관리자 목적지는 dashboard와 신규 지점 개설 두 개뿐이다. 숫자를 맞추려고 동작하지 않는 목적지를 추가하지 않는다. 목적지가 늘면 같은 navigation model에 실제 route만 추가한다.
Material Web은 roadmap상 유지보수 중심이며 rail component를 제공하지 않는다. 새 custom element stack을 병행하지 않는다. MUI X Data Grid도 현재 행 수와 기능에는 필요하지 않다. core MUI와 headless TanStack 조합이 sorting/model 재사용과 semantic table 요구를 충족하므로 Pro/Premium 기능이나 별도 상용 라이선스를 도입하지 않는다. 선택한 MUI core와 TanStack Table의 package manifest 라이선스는 모두 MIT다.
- 600px 미만은 app bar + 296px temporary drawer, 600px 이상은 permanent rail이다.
- rail은 collapsed 88px, expanded 280px이며 본문 padding도 같은 값으로 재배치한다.
- standard collection은 container 900px 이상에서 table, 그 미만에서 card다.
- 열이 많은 wide collection은 container 1120px 이상에서 table, 그 미만에서 card다.
- rail 확장으로 실제 content container가 좁아지면 wide table은 같은 화면 폭에서도 card로 즉시 치환된다. 이 동작이 viewport breakpoint보다 container query를 택한 이유다.
- table과 card는 TanStack getRowModel()을 함께 소비한다. 두 데이터 변환기를 만들지 않는다.
- table에는 숨김 caption을 포함한다. card는 단순 CSS row 재배치가 아니라 label/value가 세로로 읽히는 별도 구조다.
구현 권위는 AdminNavigation.tsx, AdminShell.astro, AdminResponsiveDataCollection.tsx와 그 colocated tests에 있다. 이 문서는 package나 UI source를 복제하지 않고 선택 기준과 운영 함정만 소유한다.
알려진 함정
Section titled “알려진 함정”- MUI sm=600px, Tailwind md=768px, MUI md=900px를 섞으면 600–899px에서 빈 gutter가 생긴다. navigation 경계는 MUI sm과 shell CSS의 600px 하나로 맞춘다.
- expanded drawer를 overlay로만 키우면 본문 앞부분을 192px 덮는다. rail의 aria-expanded 상태와 본문 padding-left를 함께 바꾼다.
- viewport가 넓어도 grid column이나 expanded rail 때문에 collection 자체는 좁을 수 있다. table/card 선택은 viewport가 아니라 collection container를 본다.
- 한 table을 display:block, horizontal scroll, 작은 글자, 강제 줄바꿈으로 버티게 하지 않는다. narrow mode는 field label/value card로 완전히 치환한다.
- Table과 Card를 동시에 보이게 두면 접근성 tree와 keyboard 순서가 중복된다. 한 collection에는 한 mode만 렌더링한다.
- MUI v9의 지원 browser 범위 아래로 내려가면 :has() 기반 shell reflow를 먼저 재검증한다.
upgrade trigger
Section titled “upgrade trigger”- MUI가 first-party Navigation Rail을 제공하면 Drawer 조합보다 접근성·adaptive behavior가 나은지 공식 migration 문서와 함께 재조사한다.
- MUI 또는 TanStack major version, React/Astro integration, browser baseline이 바뀌면 이 trap sheet의 version/date와 실제 browser evidence를 같은 변경에서 갱신한다.
- 행 수가 실제로 virtualization을 요구하거나 column pinning/grouping 같은 기능이 승인되면 TanStack Virtual 또는 MUI X의 당시 라이선스·bundle·접근성 비용을 다시 비교한다.
- Material adaptive navigation의 window class 권고가 바뀌면 600px navigation 경계를 재검증한다. data collection의 900/1120px는 콘텐츠 측정 근거이므로 별도로 검증한다.
pnpm —dir ../frontend-repo test pnpm —dir ../frontend-repo lint pnpm —dir ../frontend-repo check pnpm —dir ../frontend-repo build pnpm test:admin-material-evidence pnpm docs:admin-material-evidence:check pnpm docs:build
브라우저 검사는 599/600px navigation 경계, 1024px all-card 상태, 1440px collapsed all-table 상태, 1440px expanded standard-table/wide-card 상태, document horizontal overflow 0, keyboard drawer focus 복귀, console error/warning 0을 함께 확인한다. 최종 WebP와 수치는 관리자 Material 레일·반응형 데이터 UI 회귀에 고정한다.