@gaonjs/vue 0.1.4 → 0.3.0

package/dist/api.d.ts

@@ -0,0 +1,52 @@
+import type { Serialized } from './serialize.js';
+/**
+ * 라우트 매니페스트 — .gaon/routes.d.ts 가 채우는 GaonRouteMap 옆에 함께
+ * 채워지는 런타임/타입 지도. 키는 'controller#action'.
+ *
+ * pageProps 는 타입만 알면 되지만 api() 는 실제 HTTP 메서드·경로를 알아야
+ * 요청을 보낼 수 있다 — 그래서 라우트 지도가 필요하다. 생성기가 declaration
+ * merging + 값 export 로 함께 채운다(추가 생성 파일 X · 기존 파일에 병합).
+ */
+export interface GaonRouteInfo {
+    readonly method: 'get' | 'post' | 'put' | 'patch' | 'delete';
+    readonly path: string;
+}
+declare global {
+    interface GaonRoutes {
+    }
+}
+/** GaonRouteMap[K] (액션 함수) 에서 render 결과 P 를 뽑아 낸다 — pageProps 와 동일. */
+type PropsOf<F> = F extends (...args: never[]) => infer R ? Awaited<R> extends {
+    page: string;
+    props: infer P;
+} ? P : Awaited<R> : never;
+/**
+ * 요청 파라미터 — 라우트에 :id 같은 자리표시자가 있으면 여기서 뽑고, 나머지는
+ * GET 이면 쿼리스트링, 그 외 메서드는 JSON 본문으로 붙는다. 값은 문자열
+ * 화된다(경로/쿼리 특성).
+ */
+export type ApiParams = Record<string, string | number | bigint | boolean | undefined | null>;
+export interface ApiOptions {
+    /** 기본 http 헤더에 얹어 보낸다(Authorization 등). */
+    readonly headers?: Record<string, string>;
+    /** AbortController 지원(취소·타임아웃). */
+    readonly signal?: AbortSignal;
+    /** URL prefix (앱 프리픽스가 web 이 아니면 지정). 생략 시 window.origin. */
+    readonly baseUrl?: string;
+    /** fetch 구현 주입(테스트·SSR). 생략 시 globalThis.fetch. */
+    readonly fetch?: typeof fetch;
+}
+/**
+ * 라우트 키로 서버 액션을 부른다.
+ *  · 반환 타입: 액션 반환의 Serialized<> (직렬화 경계 재사용).
+ *  · 요청: 메서드는 라우트 정의에서, 경로는 :param 을 채워 완성.
+ *  · 실패: 4xx/5xx 는 예외로 던지고, ValidationError(422)는 issues 를 포함한다.
+ */
+export declare function api<K extends keyof GaonRouteMap>(key: K, params?: ApiParams, opts?: ApiOptions): Promise<Serialized<PropsOf<GaonRouteMap[K]>>>;
+/**
+ * 라우트 매니페스트를 등록한다 — 프론트엔드 부트스트랩(app 엔트리)이 한 번
+ * 호출하면 이후 api() 가 method·path 를 안다. 앱 빌드 시 .gaon/routes.d.ts
+ * 와 함께 생성되는 매니페스트 모듈이 이 함수를 호출한다.
+ */
+export declare function registerRoutes(routes: Record<string, GaonRouteInfo>): void;
+export {};

package/dist/api.js

@@ -0,0 +1,127 @@
+// @gaonjs/vue · api() — 타입드 클라이언트 (errata E-3 §C)
+//
+// pageProps 와 **같은 .gaon/routes.d.ts 브리지**를 재사용한다 — 추가 생성 파일
+// 없음. 라우트 키 하나로 서버 액션의 반환 타입을 클라이언트에서 그대로 안다.
+//
+//   import { api } from 'gaonjs/vue'
+//   const { results } = await api('posts#search', { q: keyword.value })
+//
+// 반환 타입은 액션 반환 타입의 **Serialized<>** (M4 render props 직렬화와 같은
+// 규칙 · 같은 매핑 재사용). 별도 직렬화 규칙을 두지 않는다(The One Way).
+//
+// 두 번째 인자는 라우트 파라미터 + 쿼리(HTTP 메서드는 라우트 정의에서 결정).
+// 라우트에 `:id` 처럼 자리표시자가 있으면 params 에서 뽑아 경로에 채우고,
+// 남는 값은 GET 은 쿼리스트링으로, POST/PUT/PATCH/DELETE 는 JSON 본문으로 실어
+// 보낸다. 서버 쪽 this.params 병합 우선순위(라우트>body>query)와 일치한다.
+// ── 런타임 ────────────────────────────────────────────────────
+/**
+ * 라우트 키로 서버 액션을 부른다.
+ *  · 반환 타입: 액션 반환의 Serialized<> (직렬화 경계 재사용).
+ *  · 요청: 메서드는 라우트 정의에서, 경로는 :param 을 채워 완성.
+ *  · 실패: 4xx/5xx 는 예외로 던지고, ValidationError(422)는 issues 를 포함한다.
+ */
+export async function api(key, params = {}, opts = {}) {
+    const routes = (globalThis.__GAON_ROUTES__) ??
+        {};
+    const info = routes[key];
+    if (!info) {
+        throw new Error(`[gaonjs/vue] 라우트 '${String(key)}' 를 찾을 수 없습니다.\n` +
+            `→ apps/<app>/routes.ts 에 정의돼 있는지, gaon dev/check 가 .gaon/routes.d.ts 를 재생성했는지 확인하세요.`);
+    }
+    const { url, leftovers } = buildUrl(info, params);
+    const method = info.method.toUpperCase();
+    const useBody = method !== 'GET' && method !== 'HEAD';
+    const headers = {
+        Accept: 'application/json',
+        ...(opts.headers ?? {}),
+    };
+    let body;
+    let finalUrl = url;
+    if (useBody) {
+        body = JSON.stringify(leftovers);
+        headers['Content-Type'] = 'application/json; charset=utf-8';
+        // CSRF: 세션 앱은 쿠키 기반 CSRF 를 쓴다 — 프론트 부트스트랩이 심어 놓은
+        // 메타 태그 값을 자동으로 붙여 준다(있으면).
+        const csrf = readCsrfToken();
+        if (csrf)
+            headers['X-CSRF-Token'] = csrf;
+    }
+    else if (Object.keys(leftovers).length > 0) {
+        const q = new URLSearchParams();
+        for (const [k, v] of Object.entries(leftovers)) {
+            if (v === undefined || v === null)
+                continue;
+            q.append(k, String(v));
+        }
+        finalUrl = url + (url.includes('?') ? '&' : '?') + q.toString();
+    }
+    const base = opts.baseUrl ?? '';
+    const doFetch = opts.fetch ?? globalThis.fetch;
+    const res = await doFetch(base + finalUrl, {
+        method,
+        headers,
+        body,
+        signal: opts.signal,
+        credentials: 'same-origin',
+    });
+    if (!res.ok) {
+        // 422 는 서버 검증 실패(§7.5.3). 파싱 시도 후 issues 를 실어 재던진다.
+        let payload = undefined;
+        try {
+            payload = await res.json();
+        }
+        catch {
+            /* 본문 없음 */
+        }
+        const err = new Error(`[gaonjs/vue] ${String(key)} 요청 실패 (${res.status} ${res.statusText}).`);
+        err.status = res.status;
+        err.body = payload;
+        throw err;
+    }
+    // 204 No Content 는 빈 값으로.
+    if (res.status === 204)
+        return undefined;
+    const json = (await res.json());
+    return json;
+}
+/**
+ * 라우트 매니페스트를 등록한다 — 프론트엔드 부트스트랩(app 엔트리)이 한 번
+ * 호출하면 이후 api() 가 method·path 를 안다. 앱 빌드 시 .gaon/routes.d.ts
+ * 와 함께 생성되는 매니페스트 모듈이 이 함수를 호출한다.
+ */
+export function registerRoutes(routes) {
+    const g = globalThis;
+    g.__GAON_ROUTES__ = { ...(g.__GAON_ROUTES__ ?? {}), ...routes };
+}
+// ── 내부 ──────────────────────────────────────────────────────
+function buildUrl(info, params) {
+    const leftovers = {};
+    let url = info.path;
+    // 사용된 자리표시자는 leftovers 에서 빼고, 남는 값은 쿼리/본문에 실린다.
+    const used = new Set();
+    url = url.replace(/:([A-Za-z_][A-Za-z0-9_]*)/g, (_m, name) => {
+        used.add(name);
+        const v = params[name];
+        if (v === undefined || v === null) {
+            throw new Error(`[gaonjs/vue] 라우트 파라미터 ':${name}' 값이 없습니다 (path=${info.path}).\n` +
+                `→ api('${info.method} ${info.path}', { ${name}: ... }) 처럼 넘기세요.`);
+        }
+        return encodeURIComponent(String(v));
+    });
+    for (const [k, v] of Object.entries(params)) {
+        if (used.has(k) || v === undefined || v === null)
+            continue;
+        leftovers[k] = String(v);
+    }
+    return { url, leftovers };
+}
+function readCsrfToken() {
+    const doc = globalThis.document;
+    if (!doc)
+        return undefined;
+    const el = doc.querySelector('meta[name="csrf-token"]');
+    if (!el)
+        return undefined;
+    const c = el.getAttribute('content');
+    return c ?? undefined;
+}

package/dist/index.d.ts

@@ -2,3 +2,6 @@ export declare const version: string;
 export declare const status: "planned";
 export { pageProps } from "./pageProps.js";
 export { serializeProps, type Serialized } from "./serialize.js";
+export { api, registerRoutes, type ApiParams, type ApiOptions, type GaonRouteInfo, } from "./api.js";
+export { createGaonApp, type CreateGaonAppOptions, type PageMap } from "./runtime.js";
+export { findDefaultLayout, resolvePageLayout } from "./layout.js";

package/dist/index.js

@@ -12,3 +12,9 @@ export const status = "planned";
 export { pageProps } from "./pageProps.js";
 // 직렬화 경계 (M4) — Rec → JSON-safe 페이지 props (Date/bigint→string, hidden 제외)
 export { serializeProps } from "./serialize.js";
+// 타입드 클라이언트 (errata E-3) — 라우트 키 → Serialized 반환
+export { api, registerRoutes, } from "./api.js";
+// Inertia SPA 부팅 (§6.4 · M3 최소 웹 레이어) — apps/<앱>/main.ts 진입점.
+export { createGaonApp } from "./runtime.js";
+// 레이아웃 자동 적용 (E-5 §2.3) — layouts/Default.vue 결정 로직.
+export { findDefaultLayout, resolvePageLayout } from "./layout.js";

package/dist/layout.d.ts

@@ -0,0 +1,17 @@
+import type { Component } from 'vue';
+/**
+ * 페이지 모듈 지도(import.meta.glob 결과)에서 `layouts/Default.vue` 를
+ * 뽑는다. glob 은 페이지 지도와 같은 root(main.ts)에서 만들어져 넘어오므로,
+ * 키는 './layouts/Default.vue' 형식이다.
+ */
+export declare function findDefaultLayout(layouts: Record<string, unknown> | undefined): Component | undefined;
+/**
+ * 페이지 컴포넌트에 레이아웃을 결정해 붙인다(E-5 §2.3).
+ *  · pageLayout === null      → 명시 opt-out. 그대로 null 유지.
+ *  · pageLayout 값 존재         → 명시 지정. 그대로.
+ *  · pageLayout === undefined → Default.vue 있으면 그것, 없으면 그대로.
+ *
+ * 반환은 실제로 붙일 레이아웃(Component) 또는 undefined(레이아웃 없음).
+ * 결정 로직만 담고, 붙이는 것은 호출자(runtime.createGaonApp)가 한다.
+ */
+export declare function resolvePageLayout(pageLayout: unknown, defaultLayout: Component | undefined): Component | undefined;

package/dist/layout.js

@@ -0,0 +1,48 @@
+// @gaonjs/vue · Vue 레이아웃 자동 적용 (v0.16 §6.6 · errata E-5 §2.3)
+//
+// 정본: "layouts/Default.vue 가 존재하면 그 앱의 모든 페이지에 자동
+// 적용된다(파일 존재 = 등록 원칙). 다른 레이아웃이 필요한 페이지만
+// 페이지 파일에서 명시적으로 바꾼다."
+//
+// 페이지 컴포넌트의 정적 프로퍼티 `layout` 이 다음 세 값을 갖는다:
+//   · 없음(undefined)  → Default.vue 가 있으면 자동 적용, 없으면 raw.
+//   · null            → 명시 opt-out(로그인 페이지처럼 레이아웃 없음).
+//   · Component       → 그 컴포넌트를 명시 지정.
+//
+// Inertia 의 persistent layout 규약과 정합 — 페이지 컴포넌트 자체가
+// `layout` 을 들고 있으면 어댑터가 페이지 전환 시 레이아웃 상태를 유지한다.
+/**
+ * 페이지 모듈 지도(import.meta.glob 결과)에서 `layouts/Default.vue` 를
+ * 뽑는다. glob 은 페이지 지도와 같은 root(main.ts)에서 만들어져 넘어오므로,
+ * 키는 './layouts/Default.vue' 형식이다.
+ */
+export function findDefaultLayout(layouts) {
+    if (!layouts)
+        return undefined;
+    const mod = layouts['./layouts/Default.vue'];
+    if (!mod)
+        return undefined;
+    return extractDefault(mod);
+}
+/**
+ * 페이지 컴포넌트에 레이아웃을 결정해 붙인다(E-5 §2.3).
+ *  · pageLayout === null      → 명시 opt-out. 그대로 null 유지.
+ *  · pageLayout 값 존재         → 명시 지정. 그대로.
+ *  · pageLayout === undefined → Default.vue 있으면 그것, 없으면 그대로.
+ *
+ * 반환은 실제로 붙일 레이아웃(Component) 또는 undefined(레이아웃 없음).
+ * 결정 로직만 담고, 붙이는 것은 호출자(runtime.createGaonApp)가 한다.
+ */
+export function resolvePageLayout(pageLayout, defaultLayout) {
+    if (pageLayout === null)
+        return undefined;
+    if (pageLayout !== undefined)
+        return pageLayout;
+    return defaultLayout;
+}
+function extractDefault(mod) {
+    if (mod && typeof mod === 'object' && 'default' in mod) {
+        return mod.default;
+    }
+    return mod;
+}

package/dist/runtime.d.ts

@@ -0,0 +1,42 @@
+import { type GaonRouteInfo } from './api.js';
+/**
+ * import.meta.glob 이 반환하는 페이지 지도.
+ * 값은 즉시(eager) 로드된 모듈이거나 지연 로드 함수다 — 둘 다 지원.
+ */
+export type PageMap = Record<string, unknown | (() => Promise<unknown>)>;
+export interface CreateGaonAppOptions {
+    /**
+     * 페이지 모듈 지도. main.ts 에서
+     *   `import.meta.glob('./pages/**\/*.vue')`  (지연 로드)
+     * 또는
+     *   `import.meta.glob('./pages/**\/*.vue', { eager: true })`
+     * 로 만들어 넘긴다. 키는 './pages/<name>.vue' 형식.
+     */
+    readonly pages: PageMap;
+    /**
+     * 레이아웃 모듈 지도. Default.vue 가 있으면 자동 적용(E-5 §2.3).
+     *   `import.meta.glob('./layouts/*.vue', { eager: true })`
+     * eager 인 편이 편하다 — 레이아웃은 소수·최초 진입에도 필요.
+     */
+    readonly layouts?: PageMap;
+    /**
+     * 앱의 라우트 매니페스트(method + path). api() 클라이언트가 소비한다
+     * (E-3 §3). .gaon/routes.manifest.ts 가 생성해 이 옵션으로 넘긴다.
+     * 미지정 시 api() 는 라우트 조회에서 명확한 에러를 던진다.
+     */
+    readonly routes?: Record<string, GaonRouteInfo>;
+    /** 브라우저 탭 타이틀 조합자. Inertia 옵션 그대로 통과. */
+    readonly title?: (title: string) => string;
+    /** Inertia 진행 표시자 옵션(색상·delay 등). false 로 끌 수 있다. */
+    readonly progress?: false | {
+        readonly color?: string;
+        readonly delay?: number;
+        readonly includeCSS?: boolean;
+        readonly showSpinner?: boolean;
+    };
+}
+/**
+ * Inertia SPA 부팅(브라우저 전용). 페이지·레이아웃 지도와 라우트 매니페스트를
+ * 받아 Vue 앱을 마운트한다. 서버는 apps/<앱>/main.ts 에서 이 함수를 부른다.
+ */
+export declare function createGaonApp(opts: CreateGaonAppOptions): Promise<void>;

package/dist/runtime.js

@@ -0,0 +1,68 @@
+/// <reference lib="dom" />
+// @gaonjs/vue · Vue 3 클라이언트 런타임 (v0.16 §6.4 · M3 최소 웹 레이어)
+//
+// 이 파일은 브라우저에서 Inertia SPA 를 부팅한다:
+//   1) apps/<앱>/main.ts 가 페이지·레이아웃 지도를 만든다(Vite 정합).
+//   2) `createGaonApp` 에 지도와 라우트 매니페스트를 넘긴다.
+//   3) 내부에서 @inertiajs/vue3 의 createInertiaApp 을 호출해 마운트.
+//
+// 정본 준수:
+//   · Inertia SPA + 서버 라우팅 · **SSR 아님** (§6.1 · CLAUDE.md 규칙 12).
+//   · 자동 import 금지 — 페이지·레이아웃 지도는 사용자 코드가 명시적으로
+//     import.meta.glob 으로 만들어 넘긴다(E-5 §2.4).
+//   · `layouts/Default.vue` 존재 = 자동 적용(E-5 §2.3, ./layout.ts).
+//
+// 서버 응답의 data-page (packages/web/src/inertia.ts) 를 Inertia 어댑터가
+// 읽어 마운트한다 — 초기 페이지 · 이후 SPA 네비게이션 모두 같은 경로.
+import { createApp, h } from 'vue';
+import { createInertiaApp } from '@inertiajs/vue3';
+import { registerRoutes } from './api.js';
+import { findDefaultLayout, resolvePageLayout } from './layout.js';
+/**
+ * Inertia SPA 부팅(브라우저 전용). 페이지·레이아웃 지도와 라우트 매니페스트를
+ * 받아 Vue 앱을 마운트한다. 서버는 apps/<앱>/main.ts 에서 이 함수를 부른다.
+ */
+export async function createGaonApp(opts) {
+    if (opts.routes)
+        registerRoutes(opts.routes);
+    const defaultLayout = findDefaultLayout(opts.layouts);
+    await createInertiaApp({
+        title: opts.title,
+        progress: opts.progress,
+        resolve: async (name) => {
+            const key = `./pages/${name}.vue`;
+            const entry = opts.pages[key];
+            if (entry === undefined) {
+                // 에러가 곧 수리 안내서(§7.5.3): 어디 파일을 만들어야 하는지 말해준다.
+                throw new Error(`[gaonjs/vue] Inertia 페이지 '${name}' 를 찾을 수 없습니다 (looked up '${key}').\n` +
+                    `→ apps/<앱>/pages/${name}.vue 를 만들거나, 컨트롤러의 this.render('${name}', ...) 인자를 확인하세요.`);
+            }
+            const mod = await loadPageModule(entry);
+            const page = mod.default;
+            // 레이아웃 자동 적용(E-5 §2.3) — 페이지가 layout 을 명시 안 했으면 Default.
+            const chosen = resolvePageLayout(page.layout, defaultLayout);
+            if (chosen !== undefined) {
+                ;
+                page.layout = chosen;
+            }
+            else if (page.layout === null) {
+                // 명시 opt-out 은 그대로 null 로 남긴다 — Inertia 는 null 을 "레이아웃 없음"으로 취급.
+            }
+            return mod;
+        },
+        setup({ el, App, props, plugin }) {
+            if (el === null)
+                return;
+            createApp({ render: () => h(App, props) })
+                .use(plugin)
+                .mount(el);
+        },
+    });
+}
+async function loadPageModule(entry) {
+    if (typeof entry === 'function') {
+        const loaded = await entry();
+        return loaded;
+    }
+    return entry;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gaonjs/vue",
-  "version": "0.1.4",
+  "version": "0.3.0",
   "description": "Gaon 프론트엔드 어댑터: Vue 3 · Inertia 브리지 · 타입 전파 · SSR (구현 예정)",
   "type": "module",
   "license": "MIT",
@@ -23,11 +23,15 @@
     "dist",
     "README.md"
   ],
-  "dependencies": {
-    "@gaonjs/core": "0.1.3",
-    "@gaonjs/web": "0.2.0"
-  },
   "scripts": {
     "build": "node ../../node_modules/typescript/bin/tsc -p tsconfig.json"
+  },
+  "dependencies": {
+    "@gaonjs/core": "workspace:*",
+    "@gaonjs/web": "workspace:*",
+    "@inertiajs/vue3": "^3.6.1"
+  },
+  "peerDependencies": {
+    "vue": "^3.5.0"
   }
-}
+}