@jogak/ui 0.1.0-alpha.5 → 0.1.0-alpha.6

package/CHANGELOG.md

@@ -5,6 +5,25 @@ All notable changes to Jogak packages are documented here. The repository follow
 
 Version numbers apply to all packages in the workspace (synchronized release).
 
+## [0.1.0-alpha.6] — 2026-05-09
+
+### Added
+
+- **`main.tsx` 에 `import 'virtual:jogak/global-css'` 추가** — `@jogak/core`의
+  `JogakPluginOptions.globalCss` opt-in 옵션이 켜진 환경에서 사용자 globalCss가
+  jogak SPA에 적용됨. opt-in이 꺼진 default 환경에서는 빈 모듈이라 SPA 번들 영향 zero.
+- **`jogak.css` chrome 보호 rule** — `[data-jogak-shell] :where(button, input, select, textarea):not([data-jogak-content] *)`
+  rule이 form element의 사용자 reset 침범을 차단. `:where()` specificity 0 +
+  `revert-layer`로 알파.5 baseline 영향 zero.
+- **README "사용자 globalCss 적용 (alpha.6)" 섹션** — 사용법 / 자동 감지 후보
+  8종 우선순위 / 격리 보장 3항목 / scope 가이드 / `[data-jogak-shell]` /
+  `[data-jogak-content]` selector hint / 알려진 한계 4항목.
+
+### Notes
+
+- 알파.4부터 hook으로 도입됐던 `data-jogak-shell` / `data-jogak-content` 속성이
+  본 릴리즈에서 처음으로 의미를 갖게 됨 (chrome 보호 rule + scope 가이드 hook).
+
 ## [0.1.0-alpha.5] — 2026-05-09
 
 ### Changed

package/README.md

@@ -66,16 +66,92 @@ See the [main README](https://github.com/devclib/jogak#readme) for the full host
 
 | 단계 | 상태 | 내용 |
 |------|------|------|
-| alpha.4 | ✅ 본 릴리즈 | jogak UI 빌드 파이프라인에 Tailwind v4 + `jogak:` prefix 도입 (인프라) |
-| alpha.5 | 예정 | jogak UI 컴포넌트를 Tailwind class로 마이그레이션 |
-| alpha.6 | 예정 | 사용자 `globalCss` 옵션 지원 (`JogakPluginOptions.globalCss`) |
-| alpha.7+ | 검토 | preview Shadow DOM / iframe 격리 옵션 |
+| alpha.4 | ✅ 완료 | jogak UI 빌드 파이프라인에 Tailwind v4 + `jogak:` prefix 도입 (인프라) |
+| alpha.5 | ✅ 완료 | jogak UI 컴포넌트를 Tailwind class로 마이그레이션 (4 PR) |
+| **alpha.6** | ✅ **본 릴리즈** | **사용자 `globalCss` 옵션 (`JogakPluginOptions.globalCss`)** |
+| alpha.7+ | 예정 | preview Shadow DOM / iframe 격리 옵션 (`previewIsolation`) |
 
-### 현 한계 (alpha.4)
+### 사용자 globalCss 적용 (alpha.6)
 
-- jogak SPA는 사용자 프로젝트의 globalCss(예: Tailwind, shadcn/ui)를 자동 import하지 않습니다.
-  jogak chrome은 자체 스타일만 사용하며, preview 안의 사용자 컴포넌트도 jogak 빌드 환경에서 렌더됩니다.
-- 사용자 globalCss를 적용하려면 알파.6을 기다려 주세요.
+`runHost`는 vite root를 `@jogak/ui` 패키지로 두고 사용자 `vite.config.ts` / `main.tsx`를 무시하므로(`configFile: false`), 사용자 `index.css`(Tailwind/shadcn 디자인 토큰)가 jogak SPA에 자동 적용되지 않습니다. `globalCss` 옵션은 이를 opt-in으로 해결합니다.
+
+#### 사용법
+
+```ts
+// vite.config.ts — 자동 감지 (shadcn/ui Vite 시나리오)
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import { jogak } from '@jogak/core/vite'
+
+export default defineConfig({
+  plugins: [react(), jogak({ globalCss: true })],
+})
+```
+
+`globalCss: true`는 다음 후보를 우선순위 순으로 자동 감지해 **첫 발견 1개**만 import합니다:
+
+1. `src/index.css` (shadcn/ui Vite)
+2. `src/main.css`
+3. `src/styles.css`
+4. `src/styles/globals.css` (Next.js shadcn)
+5. `src/styles/index.css`
+6. `src/app/globals.css` (Next.js App Router shadcn)
+7. `src/global.css`
+8. `src/app.css`
+
+명시 경로(상대/절대) 또는 배열도 사용 가능합니다:
+
+```ts
+// 명시 경로 1개
+jogak({ globalCss: './src/index.css' })
+
+// 다중 import (디자인 토큰 + reset 분리)
+jogak({ globalCss: ['./src/tokens.css', './src/reset.css'] })
+```
+
+#### 격리 보장
+
+- **Tailwind utility class**: jogak UI는 `prefix=jogak`로 빌드되어 사용자 utility와 충돌 zero (예: 사용자 `bg-primary` ≠ jogak `jogak:bg-...`).
+- **CSS variable**: jogak은 `--jogak-*` prefix로 namespace 격리 → 사용자 `:root { --primary }` 같은 디자인 토큰은 영향 없음.
+- **Form element 보호**: `[data-jogak-shell]` 안의 button/input/select/textarea는 사용자 reset의 `border` / `background` / `color` 침범을 받지 않도록 `:where()` 보호 rule 적용. specificity 0이라 사용자가 명시적으로 `[data-jogak-shell] button { ... }`를 작성하면 정상 override됩니다.
+
+#### scope 가이드 — 알려진 영향 영역
+
+사용자 css의 다음 패턴은 jogak chrome에도 영향을 줄 수 있습니다 (전역 import이므로):
+
+- `body { ... }` — jogak SPA의 body에도 적용
+- `* { ... }` 또는 `*, *::before { ... }` — 모든 요소
+- 글로벌 reset (`button { all: unset }`, `* { border: 1px solid var(--border) }` 등)
+
+이를 사용자 콘텐츠 영역(preview)으로만 한정하려면 셀렉터를 `[data-jogak-content] *` scope로 작성하세요:
+
+```css
+/* 권장: preview 영역으로만 한정 */
+[data-jogak-content] *,
+[data-jogak-content] *::before,
+[data-jogak-content] *::after {
+  box-sizing: border-box;
+}
+
+[data-jogak-content] button {
+  /* 사용자 디자인 시스템 button reset */
+  all: unset;
+}
+```
+
+또는 jogak chrome과 preview 모두에 일관된 사용자 디자인 시스템을 적용하려는 의도라면 그대로 두면 됩니다 — jogak chrome도 사용자 토큰/타이포를 함께 체험하게 됩니다.
+
+##### selector hint
+
+- `[data-jogak-shell]` — `JogakApp` 최상위 wrapper (chrome + preview 모두 포함)
+- `[data-jogak-content]` — Preview의 사용자 콘텐츠 영역 (사용자 컴포넌트가 렌더되는 div)
+
+#### 알려진 한계
+
+- 본 옵션은 **opt-in**입니다 (default `false`). 알파.5까지의 동작은 동일합니다.
+- `globalCss: true` 자동 감지는 dev 시작 시점에 한 번만 수행됩니다. 후보 css 파일이 dev 시작 후에 새로 추가되면 dev 서버를 재시작해야 합니다. 명시 경로(`globalCss: './src/index.css'`)는 파일이 나중에 생성되어도 정상 hot reload됩니다.
+- preview 영역만 사용자 css로 한정하려면 알파.7+의 `previewIsolation: 'shadow'` 옵션을 기다려 주세요.
+- CSS module(`.module.css`)을 자동 감지 후보에서 직접 import하지 않습니다 — 명시 경로로 넘기면 Vite가 module 처리합니다.
 
 - Repository: https://github.com/devclib/jogak
 - Issues: https://github.com/devclib/jogak/issues

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jogak/ui",
-  "version": "0.1.0-alpha.5",
+  "version": "0.1.0-alpha.6",
   "description": "Showcase viewer UI for Jogak — Sidebar / Preview / Controls / Actions and the JogakApp shell.",
   "keywords": [
     "jogak",
@@ -64,8 +64,8 @@
     "prism-react-renderer": "^2.4.1",
     "tailwindcss": "^4.0.0",
     "@tailwindcss/vite": "^4.0.0",
-    "@jogak/core": "0.1.0-alpha.5",
-    "@jogak/react": "0.1.0-alpha.5"
+    "@jogak/core": "0.1.0-alpha.6",
+    "@jogak/react": "0.1.0-alpha.6"
   },
   "devDependencies": {
     "@types/node": "^20.14.0",

package/src/app/main.tsx

@@ -3,6 +3,12 @@ import { createRoot } from 'react-dom/client'
 import 'virtual:jogak'
 import { _jogakCodeTheme } from 'virtual:jogak'
 import '../styles/jogak.css'
+// 알파.6: 사용자 globalCss opt-in.
+// JogakPluginOptions.globalCss=false (default) → 빈 모듈 (no-op, SPA 번들 영향 zero).
+// true / string / string[] → plugin이 사용자 css를 import한다.
+// jogak.css 뒤에 둬서 사용자가 jogak chrome 기본값을 명시적으로 override 가능 —
+// 단, jogak utility는 prefix=jogak로 격리되어 사용자 utility와 충돌하지 않는다.
+import 'virtual:jogak/global-css'
 import { JogakApp } from './App.js'
 
 const rootEl = document.getElementById('root')

package/src/styles/jogak.css

@@ -82,6 +82,26 @@
      * 회귀 자체 차단 + 알파.6 사용자 globalCss 충돌 가능성 zero.
      */
   }
+
+  /*
+   * 알파.6 wrapper 보호 rule (api-contracts §8 옵션 C).
+   *
+   * 사용자 globalCss(예: shadcn `@layer base { * { @apply border-border ... } }`)가
+   * jogak chrome의 form element를 침범하는 것을 차단한다. `:where(...)` specificity 0
+   * 으로 사용자가 명시적으로 `[data-jogak-shell] button { ... }`를 작성하면 자연스럽게
+   * 이긴다.
+   *
+   * 적용 범위: chrome의 모든 form element. preview(`[data-jogak-content]`) 안의
+   * 사용자 컴포넌트는 영향 받지 않음 — `:not([data-jogak-content] *)`로 제외.
+   *
+   * 알파.5 baseline 영향: zero. chrome 컴포넌트는 본 rule이 차단하는 사용자 reset이
+   * 없을 때 동일 시각 (revert-layer는 해당 layer가 없으면 no-op).
+   */
+  [data-jogak-shell] :where(button, input, select, textarea):not([data-jogak-content] *) {
+    border-color: revert-layer;
+    background-color: revert-layer;
+    color: revert-layer;
+  }
 }
 
 @layer components {