@jogak/core 0.1.0-alpha.4 → 0.1.0-alpha.6

package/dist/registry.d.ts

@@ -22,6 +22,9 @@ export declare class ComponentRegistry {
     search(query: string): readonly RegistryEntry[];
     /**
      * title의 '/' 구분자로 hydrated entry만의 계층 트리를 구성한다.
+     *
+     * `getAll()`이 정렬된 순서를 반환하므로 트리 객체의 키 iteration order
+     * (ECMA-262 §OrdinaryOwnPropertyKeys: insertion order for string keys)도 결정적이다.
      */
     getTree(): CategoryTree;
     clear(): void;

package/dist/types.d.ts

@@ -154,4 +154,58 @@ export interface JogakPluginOptions {
      * jogak({ resolveAlias: { '@': './src', '@components': './src/components' } })
      */
     readonly resolveAlias?: Readonly<Record<string, string>>;
+    /**
+     * 사용자 globalCss를 jogak SPA에 import한다 (알파.6 opt-in).
+     *
+     * 동기:
+     * - `runHost`는 vite root를 `@jogak/ui` 패키지로 두고 사용자 `vite.config.ts`/
+     *   `main.tsx`를 무시하므로(`configFile: false`), 사용자 `index.css`(Tailwind/
+     *   shadcn 디자인 토큰)가 jogak SPA에 자동 적용되지 않는다.
+     * - 본 옵션이 `true`이거나 명시 경로면 plugin이 사용자 css를 가상 모듈로
+     *   주입해 jogak SPA가 import한다.
+     *
+     * 의미:
+     * - `false` (default): 미주입. jogak chrome 기본 스타일만 사용 (알파.4~5 동작 그대로).
+     * - `true`: `<userRoot>/src/{index,main,styles,global,app,globals}.css` 후보를
+     *   순차 검사해 **첫 발견 1개**만 import. 미발견 시 빈 모듈 (no-op).
+     * - `string`: 사용자 root 기준 상대 경로 또는 절대 경로 1개. 자동 감지 비활성화.
+     * - `string[]`: 명시 경로 N개를 배열 순서대로 모두 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`
+     *
+     * 격리:
+     * - jogak UI는 알파.4~5에서 Tailwind v4 + `prefix=jogak`로 마이그레이션되어
+     *   사용자 utility class와 충돌 zero (예: 사용자 `.bg-primary` ≠ jogak `.jogak\:bg-...`).
+     * - jogak CSS variable은 `--jogak-*` prefix → 사용자 `:root { --primary }` 같은
+     *   토큰과 namespace 충돌 zero.
+     * - 단, 사용자 css의 `*` selector / `body` selector / reset 류는 jogak chrome에
+     *   영향 가능. README의 "scope 가이드" 패턴 참조.
+     *
+     * 한계 (알파.7+ 로드맵):
+     * - 사용자 css를 preview 영역으로만 한정하는 Shadow DOM/iframe 격리는 미지원.
+     * - `previewIsolation` 옵션은 알파.7+에서 별도 도입.
+     * - `globalCss: true` 자동 감지는 dev 시작 시점에 한 번만 수행 — 후보 css 파일이
+     *   dev 시작 후에 새로 추가되면 dev 서버 재시작이 필요하다. 명시 경로
+     *   (`globalCss: './src/index.css'`)는 파일이 나중에 생성되어도 정상 hot reload된다.
+     *
+     * @default false
+     *
+     * @example 자동 감지
+     * jogak({ globalCss: true })
+     *
+     * @example 명시 경로
+     * jogak({ globalCss: './src/index.css' })
+     *
+     * @example 다중 import (디자인 토큰 + reset 분리)
+     * jogak({ globalCss: ['./src/tokens.css', './src/index.css'] })
+     */
+    readonly globalCss?: boolean | string | readonly string[];
 }

package/dist/vite/detect-global-css.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 사용자 globalCss 자동 감지 + 옵션 정규화 (알파.6, opt-in).
+ *
+ * 본 모듈은 `JogakPluginOptions.globalCss` 옵션 값을 절대 경로 배열로 변환한다.
+ * 자동 감지(`true`)는 첫 발견 1개만 반환 — 다중 import는 명시 배열로 사용자가 선언.
+ *
+ * 자동 감지 후보(우선순위 순)는 spec `_workspace/01_arch/api-contracts.md` §4.1을 따른다.
+ */
+/**
+ * 사용자 globalCss 자동 감지.
+ *
+ * `<userRoot>/src/...` 후보를 우선순위 순으로 검사해 **첫 발견 1개**만 반환.
+ * 미발견 시 빈 배열.
+ *
+ * 첫 발견 stop 정책:
+ * - 사용자가 다중 import를 원하면 명시 배열(`globalCss: ['...', '...']`)을 쓰게 한다.
+ * - 자동 감지에서 모든 후보를 import하면 의도치 않은 css 중복(예: index.css와
+ *   styles.css 둘 다 존재 시)이 발생할 수 있다.
+ */
+export declare function detectUserGlobalCss(userRoot: string): readonly string[];
+/**
+ * 옵션 값 → 절대 경로 배열로 정규화.
+ *
+ * - `false`/`undefined`: `[]`
+ * - `true`: `detectUserGlobalCss(userRoot)`
+ * - `string`: `[resolve(userRoot, string)]`. 빈 문자열은 `[]`.
+ * - `string[]`: 각 요소 resolve, 빈 요소 무시 (배열 순서 보존)
+ *
+ * `existsSync` 검증은 명시 경로(string/string[])에서는 하지 않는다 — 사용자가
+ * 의도적으로 빈 파일 또는 동적 css generator를 쓸 수 있고, 미존재 시 Vite가
+ * 자체 에러로 알려주는 게 더 명확하다 (silent skip은 디버깅 어려움).
+ */
+export declare function resolveGlobalCssPaths(option: boolean | string | readonly string[] | undefined, userRoot: string): readonly string[];

package/dist/vite/index.js

@@ -1,21 +1,26 @@
-"use strict";var V=Object.create;var N=Object.defineProperty;var G=Object.getOwnPropertyDescriptor;var J=Object.getOwnPropertyNames;var B=Object.getPrototypeOf,K=Object.prototype.hasOwnProperty;var q=(e,o,a,c)=>{if(o&&typeof o=="object"||typeof o=="function")for(let s of J(o))!K.call(e,s)&&s!==a&&N(e,s,{get:()=>o[s],enumerable:!(c=G(o,s))||c.enumerable});return e};var W=(e,o,a)=>(a=e!=null?V(B(e)):{},q(o||!e||!e.__esModule?N(a,"default",{value:e,enumerable:!0}):a,e));Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const p=require("node:path"),_=require("node:fs"),w=require("node:fs/promises"),O=require("../extractor-client-CiWszHel.cjs"),X=["@jogak/core","@jogak/react","@jogak/web-components","@jogak/next"];async function P(e){try{const c=await w.stat(e);if(!c.isDirectory())return c.mtimeMs}catch{return 0}let o=0,a;try{a=await w.readdir(e)}catch{return 0}for(const c of a){const s=p.join(e,c);try{const u=await w.stat(s);if(u.isDirectory()){const y=await P(s);y>o&&(o=y)}else u.mtimeMs>o&&(o=u.mtimeMs)}catch{continue}}return o}async function Y(e){const o=p.resolve(e.root,"node_modules/.vite/deps");if(!_.existsSync(o))return{purged:!1};const a=p.join(o,"_metadata.json");if(!_.existsSync(a))return{purged:!1};let c;try{c=(await w.stat(a)).mtimeMs}catch(u){return e.logger.warn(`[jogak] cache validation: failed to stat _metadata.json (${u.message})`),{purged:!1}}const s=e.packages??X;for(const u of s){const y=p.resolve(e.root,"node_modules",u,"dist");if(!_.existsSync(y))continue;let n;try{n=await P(y)}catch(l){e.logger.warn(`[jogak] cache validation: failed to walk ${u}/dist (${l.message})`);continue}if(n>c+1e3)try{return await w.rm(o,{recursive:!0,force:!0}),e.logger.info(`[jogak] vite deps cache invalidated (stale): ${u} dist newer than cache`),{purged:!0,reason:u}}catch(l){return e.logger.warn(`[jogak] cache validation: failed to purge ${o} (${l.message})`),{purged:!1}}}return{purged:!1}}function H(e){return e.replace(/\/\*[\s\S]*?\*\//g,"").replace(/^\s*\/\/.*$/gm,"")}function z(e){if(_.existsSync(e))try{const o=_.readFileSync(e,"utf8");return JSON.parse(H(o))}catch{return}}function Q(e,o,a){if(!e.endsWith("/*")||!o.endsWith("/*"))return;const c=e.slice(0,-2),s=p.resolve(a,o.slice(0,-2));return[c,s]}function Z(e,o){var s,u;const a={},c=new Set([e,p.resolve(o,"tsconfig.app.json")]);for(const y of c){const n=z(y);if(n===void 0)continue;const l=(s=n.compilerOptions)==null?void 0:s.paths;if(l===void 0)continue;const S=((u=n.compilerOptions)==null?void 0:u.baseUrl)??".",j=p.resolve(p.dirname(y),S);for(const[x,T]of Object.entries(l)){const M=T[0];if(M===void 0)continue;const t=Q(x,M,j);if(t===void 0)continue;const[f,r]=t;a[f]===void 0&&(a[f]=r)}}return a}const $="virtual:jogak",C="\0"+$,F="virtual:jogak/entry/",A="\0"+F;function ee(e){return Buffer.from(e,"utf8").toString("base64url")}function te(e){return Buffer.from(e,"base64url").toString("utf8")}function R(e){return{title:e.title,jogakNamesKey:[...e.jogakNames].sort().join("|")}}function oe(e,o){return e!==void 0&&e.title===o.title&&e.jogakNamesKey===o.jogakNamesKey}function re(e={}){const{patterns:o=["src/**/*.jogak.ts","src/**/*.jogak.tsx"],codeTheme:a="vsDark"}=e,c=e.cwd,s=e.tsConfigFilePath,u=e.disableCacheValidation===!0,y=e.resolveAlias;let n,l,S;const j=new Map,x=new Map,T=new Map;async function M(){const{glob:t}=await import("glob"),f=S??process.cwd(),r=await t(o,{cwd:f,absolute:!0}),g=[];j.clear(),x.clear();for(const d of r){let v="";try{v=await w.readFile(d,"utf8")}catch{continue}let h={},i=null;if(l!==void 0){try{h=await l.extract(d)}catch{h={}}try{i=await l.extractMeta(d)}catch{i=null}}if(i===null)continue;const m=i.title;j.set(m,d),x.set(d,m);const k={id:m,title:i.title,jogakNames:i.jogakNames,autoArgTypes:h,userArgTypes:i.userArgTypes,source:v,filePath:d,metaExtras:i.metaExtras};T.set(d,R(k)),g.push({id:m,filePath:d,meta:k})}return g}return{name:"vite-plugin-jogak",config(){const t=c??process.cwd(),f=s??p.resolve(t,"tsconfig.json"),r=Z(f,t),g={};if(y!==void 0)for(const[v,h]of Object.entries(y))g[v]=p.resolve(t,h);const d={...r,...g};if(Object.keys(d).length!==0)return{resolve:{alias:d}}},async configResolved(t){S=c??t.root,t.command==="serve"&&!u&&await Y({root:t.root,logger:{info:r=>t.logger.info(r),warn:r=>t.logger.warn(r)}});const f=s??p.resolve(S,"tsconfig.json");l=_.existsSync(f)?O.createPropsExtractor({tsConfigFilePath:f}):O.createPropsExtractor()},configureServer(t){n=t},buildEnd(){l==null||l.releaseCache()},resolveId(t){if(t===$)return C;if(t.startsWith(F))return"\0"+t},async load(t){if(t===C){const r=(await M()).map(g=>g.meta);return`import { defaultRegistry } from '@jogak/core'
+"use strict";var J=Object.create;var L=Object.defineProperty;var K=Object.getOwnPropertyDescriptor;var q=Object.getOwnPropertyNames;var W=Object.getPrototypeOf,X=Object.prototype.hasOwnProperty;var Y=(e,t,s,o)=>{if(t&&typeof t=="object"||typeof t=="function")for(let i of q(t))!X.call(e,i)&&i!==s&&L(e,i,{get:()=>t[i],enumerable:!(o=K(t,i))||o.enumerable});return e};var H=(e,t,s)=>(s=e!=null?J(W(e)):{},Y(t||!e||!e.__esModule?L(s,"default",{value:e,enumerable:!0}):s,e));Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const g=require("node:path"),j=require("node:fs"),_=require("node:fs/promises"),N=require("../extractor-client-CiWszHel.cjs"),z=["@jogak/core","@jogak/react","@jogak/web-components","@jogak/next"];async function $(e){try{const o=await _.stat(e);if(!o.isDirectory())return o.mtimeMs}catch{return 0}let t=0,s;try{s=await _.readdir(e)}catch{return 0}for(const o of s){const i=g.join(e,o);try{const u=await _.stat(i);if(u.isDirectory()){const y=await $(i);y>t&&(t=y)}else u.mtimeMs>t&&(t=u.mtimeMs)}catch{continue}}return t}async function Q(e){const t=g.resolve(e.root,"node_modules/.vite/deps");if(!j.existsSync(t))return{purged:!1};const s=g.join(t,"_metadata.json");if(!j.existsSync(s))return{purged:!1};let o;try{o=(await _.stat(s)).mtimeMs}catch(u){return e.logger.warn(`[jogak] cache validation: failed to stat _metadata.json (${u.message})`),{purged:!1}}const i=e.packages??z;for(const u of i){const y=g.resolve(e.root,"node_modules",u,"dist");if(!j.existsSync(y))continue;let h;try{h=await $(y)}catch(a){e.logger.warn(`[jogak] cache validation: failed to walk ${u}/dist (${a.message})`);continue}if(h>o+1e3)try{return await _.rm(t,{recursive:!0,force:!0}),e.logger.info(`[jogak] vite deps cache invalidated (stale): ${u} dist newer than cache`),{purged:!0,reason:u}}catch(a){return e.logger.warn(`[jogak] cache validation: failed to purge ${t} (${a.message})`),{purged:!1}}}return{purged:!1}}const Z=["src/index.css","src/main.css","src/styles.css","src/styles/globals.css","src/styles/index.css","src/app/globals.css","src/global.css","src/app.css"];function ee(e){for(const t of Z){const s=g.resolve(e,t);if(j.existsSync(s))return[s]}return[]}function te(e,t){if(e===void 0||e===!1)return[];if(e===!0)return ee(t);if(typeof e=="string")return e.length>0?[g.resolve(t,e)]:[];const s=[];for(const o of e)typeof o=="string"&&o.length>0&&s.push(g.resolve(t,o));return s}function re(e){return e.replace(/\/\*[\s\S]*?\*\//g,"").replace(/^\s*\/\/.*$/gm,"")}function se(e){if(j.existsSync(e))try{const t=j.readFileSync(e,"utf8");return JSON.parse(re(t))}catch{return}}function oe(e,t,s){if(!e.endsWith("/*")||!t.endsWith("/*"))return;const o=e.slice(0,-2),i=g.resolve(s,t.slice(0,-2));return[o,i]}function ne(e,t){var i,u;const s={},o=new Set([e,g.resolve(t,"tsconfig.app.json")]);for(const y of o){const h=se(y);if(h===void 0)continue;const a=(i=h.compilerOptions)==null?void 0:i.paths;if(a===void 0)continue;const p=((u=h.compilerOptions)==null?void 0:u.baseUrl)??".",k=g.resolve(g.dirname(y),p);for(const[S,C]of Object.entries(a)){const b=C[0];if(b===void 0)continue;const T=oe(S,b,k);if(T===void 0)continue;const[r,d]=T;s[r]===void 0&&(s[r]=d)}}return s}const P="virtual:jogak",M="\0"+P,F="virtual:jogak/entry/",I="\0"+F,G="virtual:jogak/global-css",R="\0"+G;function ae(e){return Buffer.from(e,"utf8").toString("base64url")}function ie(e){return Buffer.from(e,"base64url").toString("utf8")}function D(e){return{title:e.title,jogakNamesKey:[...e.jogakNames].sort().join("|")}}function ce(e,t){return e!==void 0&&e.title===t.title&&e.jogakNamesKey===t.jogakNamesKey}function le(e={}){const{patterns:t=["src/**/*.jogak.ts","src/**/*.jogak.tsx"],codeTheme:s="vsDark"}=e,o=e.cwd,i=e.tsConfigFilePath,u=e.disableCacheValidation===!0,y=e.resolveAlias,h=e.globalCss;let a,p,k;const S=new Map,C=new Map,b=new Map;async function T(){const{glob:r}=await import("glob"),d=k??process.cwd(),n=(await r(t,{cwd:d,absolute:!0})).sort(),f=[];S.clear(),C.clear();for(const c of n){let v="";try{v=await _.readFile(c,"utf8")}catch{continue}let w={},l=null;if(p!==void 0){try{w=await p.extract(c)}catch{w={}}try{l=await p.extractMeta(c)}catch{l=null}}if(l===null)continue;const m=l.title;S.set(m,c),C.set(c,m);const x={id:m,title:l.title,jogakNames:l.jogakNames,autoArgTypes:w,userArgTypes:l.userArgTypes,source:v,filePath:c,metaExtras:l.metaExtras};b.set(c,D(x)),f.push({id:m,filePath:c,meta:x})}return f}return{name:"vite-plugin-jogak",config(){const r=o??process.cwd(),d=i??g.resolve(r,"tsconfig.json"),n=ne(d,r),f={};if(y!==void 0)for(const[v,w]of Object.entries(y))f[v]=g.resolve(r,w);const c={...n,...f};if(Object.keys(c).length!==0)return{resolve:{alias:c}}},async configResolved(r){k=o??r.root,r.command==="serve"&&!u&&await Q({root:r.root,logger:{info:n=>r.logger.info(n),warn:n=>r.logger.warn(n)}});const d=i??g.resolve(k,"tsconfig.json");p=j.existsSync(d)?N.createPropsExtractor({tsConfigFilePath:d}):N.createPropsExtractor()},configureServer(r){a=r},buildEnd(){p==null||p.releaseCache()},resolveId(r){if(r===P)return M;if(r===G)return R;if(r.startsWith(F))return"\0"+r},async load(r){if(r===R){const d=k??process.cwd(),n=te(h,d);return n.length===0?`// [jogak] globalCss not configured or no candidates found.
+export {}
+`:`${n.map(c=>`import ${JSON.stringify(c)}`).join(`
+`)}
+export {}
+`}if(r===M){const n=(await T()).map(f=>f.meta);return`import { defaultRegistry } from '@jogak/core'
 
 const _entryLoader = (slug) =>
   import(/* @vite-ignore */ '/@id/__x00__virtual:jogak/entry/' + slug)
 defaultRegistry.setEntryLoader((id) => {
-  const slug = ${ae()}
+  const slug = ${ue()}
   return _entryLoader(slug(id))
 })
 
-const _metas = ${JSON.stringify(r)}
+const _metas = ${JSON.stringify(n)}
 
 for (const m of _metas) defaultRegistry.registerMeta(m)
 
-export const _jogakCodeTheme = ${JSON.stringify(a)}
+export const _jogakCodeTheme = ${JSON.stringify(s)}
 export const _jogakMetas = _metas
-`}if(t.startsWith(A)){const f=t.slice(A.length),r=te(f);let g=j.get(r);return g===void 0&&(await M(),g=j.get(r)),g===void 0?`// [jogak] unknown entry id: ${JSON.stringify(r)}
+`}if(r.startsWith(I)){const d=r.slice(I.length),n=ie(d);let f=S.get(n);return f===void 0&&(await T(),f=S.get(n)),f===void 0?`// [jogak] unknown entry id: ${JSON.stringify(n)}
 export {}
-`:`import * as _user from ${JSON.stringify(g)}
+`:`import * as _user from ${JSON.stringify(f)}
 import { defaultRegistry } from '@jogak/core'
 
 const _meta = _user.default
@@ -24,18 +29,18 @@ delete _named.default
 const _jogaks = Object.values(_named).filter(
   (v) => v !== null && typeof v === 'object' && typeof v.name === 'string'
 )
-defaultRegistry.hydrateEntry(${JSON.stringify(r)}, _jogaks, _meta?.component)
+defaultRegistry.hydrateEntry(${JSON.stringify(n)}, _jogaks, _meta?.component)
 
 if (import.meta.hot) {
   import.meta.hot.accept()
 }
 
 export {}
-`}},async handleHotUpdate({file:t,modules:f}){const r=/\.jogak\.(tsx?|jsx?)$/.test(t),g=/\.(tsx?|jsx?)$/.test(t)&&!r;if(!r&&!g||n===void 0||!r)return;const d=n.moduleGraph.getModuleById(C),v=x.get(t),h=v!==void 0?A+ee(v):void 0,i=h!==void 0?n.moduleGraph.getModuleById(h):void 0;let m=null,k={},E="";if(l!==void 0){try{m=await l.extractMeta(t)}catch{m=null}try{k=await l.extract(t)}catch{k={}}try{E=await w.readFile(t,"utf8")}catch{E=""}}if(m===null){d!==void 0&&n.moduleGraph.invalidateModule(d),i!==void 0&&n.moduleGraph.invalidateModule(i),n.ws.send({type:"full-reload"});return}const I=R(m),D=T.get(t),L=oe(D,I);if(T.set(t,I),!L||v===void 0){d!==void 0&&n.moduleGraph.invalidateModule(d),i!==void 0&&n.moduleGraph.invalidateModule(i),n.ws.send({type:"full-reload"});return}const U={id:v,title:m.title,jogakNames:m.jogakNames,autoArgTypes:k,userArgTypes:m.userArgTypes,source:E,filePath:t,metaExtras:m.metaExtras};i!==void 0&&n.moduleGraph.invalidateModule(i),n.ws.send({type:"custom",event:"jogak:meta-update",data:{id:v,meta:U}});const b=[...f];return i!==void 0&&!b.includes(i)&&b.push(i),b}}}function ae(){return`(rawId) => {
+`}},async handleHotUpdate({file:r,modules:d}){const n=/\.jogak\.(tsx?|jsx?)$/.test(r),f=/\.(tsx?|jsx?)$/.test(r)&&!n;if(!n&&!f||a===void 0||!n)return;const c=a.moduleGraph.getModuleById(M),v=C.get(r),w=v!==void 0?I+ae(v):void 0,l=w!==void 0?a.moduleGraph.getModuleById(w):void 0;let m=null,x={},A="";if(p!==void 0){try{m=await p.extractMeta(r)}catch{m=null}try{x=await p.extract(r)}catch{x={}}try{A=await _.readFile(r,"utf8")}catch{A=""}}if(m===null){c!==void 0&&a.moduleGraph.invalidateModule(c),l!==void 0&&a.moduleGraph.invalidateModule(l),a.ws.send({type:"full-reload"});return}const O=D(m),U=b.get(r),V=ce(U,O);if(b.set(r,O),!V||v===void 0){c!==void 0&&a.moduleGraph.invalidateModule(c),l!==void 0&&a.moduleGraph.invalidateModule(l),a.ws.send({type:"full-reload"});return}const B={id:v,title:m.title,jogakNames:m.jogakNames,autoArgTypes:x,userArgTypes:m.userArgTypes,source:A,filePath:r,metaExtras:m.metaExtras};l!==void 0&&a.moduleGraph.invalidateModule(l),a.ws.send({type:"custom",event:"jogak:meta-update",data:{id:v,meta:B}});const E=[...d];return l!==void 0&&!E.includes(l)&&E.push(l),E}}}function ue(){return`(rawId) => {
     if (typeof Buffer !== 'undefined') return Buffer.from(rawId, 'utf8').toString('base64url')
     // 브라우저 폴백: btoa는 binary string 기준이라 UTF-8을 한번 인코딩해야 한다.
     const enc = new TextEncoder().encode(rawId)
     let bin = ''
     for (let i = 0; i < enc.length; i++) bin += String.fromCharCode(enc[i])
     return btoa(bin).replace(/\\+/g, '-').replace(/\\//g, '_').replace(/=+$/, '')
-  }`}exports.jogak=re;
+  }`}exports.jogak=le;