@xfilecom/xframe 0.1.34 → 0.1.36

package/template/web/shared/src/api/request.ts

@@ -0,0 +1,65 @@
+/**
+ * EndpointDef — path `:param` 치환, query/body, skipGlobalIndicator
+ */
+
+import type { EndpointDef } from '@shared/endpoint';
+import { apiClient } from './client';
+
+function buildPath(path: string, params?: Record<string, string>): string {
+  if (!params) return path;
+  let out = path;
+  for (const [k, v] of Object.entries(params)) {
+    out = out.replace(`:${k}`, encodeURIComponent(String(v)));
+  }
+  return out;
+}
+
+function buildQuery(query?: Record<string, string | number | boolean | undefined>): string {
+  if (!query) return '';
+  const search = new URLSearchParams();
+  for (const [k, v] of Object.entries(query)) {
+    if (v !== undefined && v !== '') search.set(k, String(v));
+  }
+  const s = search.toString();
+  return s ? `?${s}` : '';
+}
+
+export interface RequestTransportOptions<T = unknown> {
+  params?: Record<string, string>;
+  query?: Record<string, string | number | boolean | undefined>;
+  body?: T;
+  skipGlobalIndicator?: boolean;
+}
+
+export async function sendRequest<T = unknown, R = unknown>(
+  endpoint: EndpointDef,
+  options: RequestTransportOptions<T> = {},
+): Promise<R> {
+  const { params, query, body, skipGlobalIndicator } = options;
+  const url = buildPath(endpoint.path, params) + buildQuery(query);
+  const config: {
+    method: string;
+    url: string;
+    data?: T;
+    skipGlobalIndicator?: boolean;
+  } = {
+    method: endpoint.method,
+    url,
+    skipGlobalIndicator,
+  };
+  if (
+    body !== undefined &&
+    (endpoint.method === 'POST' || endpoint.method === 'PUT' || endpoint.method === 'PATCH')
+  ) {
+    config.data = body;
+  }
+  const axiosConfig = {
+    ...config,
+    ...(endpoint.timeoutMs != null ? { timeout: endpoint.timeoutMs } : {}),
+  } as Parameters<typeof apiClient.request>[0];
+
+  const response = await apiClient.request<R>(axiosConfig);
+  const raw = response.data;
+  const shaped = endpoint.post ? endpoint.post(raw) : raw;
+  return shaped as R;
+}

package/template/web/shared/src/api/types.ts

@@ -0,0 +1,80 @@
+/**
+ * methods.ts / RootStore.execute — RootStore 직접 참조 없이 순환 방지
+ */
+
+import type { EndpointDef } from '@shared/endpoint';
+import type { ParamScreenSchema, ParamsSchema } from '../params/types';
+import type { ParamStore } from '../params/param-store';
+import type { SessionStore } from '../store/session-store';
+
+/** methods 콜백에서 받는 store — RootStore 가 이 형태를 만족 */
+export interface ApiMethodStore {
+  paramStore: ParamStore;
+  sessionStore: SessionStore;
+}
+
+export type { ParamsSchema, ParamScreenSchema };
+
+export type CoreSdkWrapped<T> = {
+  data?: T[] | T;
+  code?: number;
+  error?: unknown;
+  success?: boolean;
+  message?: string;
+};
+
+export interface ExecuteContext {
+  redirectTo?: string;
+  navigate?: (path: string, options?: { replace?: boolean }) => void;
+}
+
+export interface ApiMethodUiConfig {
+  indicatorMessage?: string;
+  successMessage?: string;
+  errorMessage?: string;
+  showIndicator?: boolean;
+  showSuccessToast?: boolean;
+  showErrorToast?: boolean;
+  unwrapDataArray?: boolean;
+}
+
+export type ScreenAuthType = 'guest' | 'protected';
+
+export interface ScreenMeta {
+  path: string;
+  auth: ScreenAuthType;
+  index?: boolean;
+  page: string;
+  bottomNav?: boolean;
+  label?: string;
+}
+
+export interface ApiMethodEndpointCall<TPayload = unknown, TStore = ApiMethodStore> {
+  endpoint: EndpointDef;
+  body?: (stores: TStore, payload?: TPayload) => unknown;
+  query?: (
+    stores: TStore,
+    payload?: TPayload,
+  ) => Record<string, string | number | boolean | undefined>;
+  params?: (stores: TStore, payload?: TPayload) => Record<string, string>;
+}
+
+export interface ApiMethodConfig<TPayload = unknown, TResult = unknown, TStore = ApiMethodStore> {
+  endpoint?: EndpointDef;
+  endpoints?: ApiMethodEndpointCall<TPayload, TStore>[];
+  schema: ParamScreenSchema;
+  screen?: ScreenMeta;
+  ui?: ApiMethodUiConfig;
+  body?: (stores: TStore, payload?: TPayload) => unknown;
+  query?: (
+    stores: TStore,
+    payload?: TPayload,
+  ) => Record<string, string | number | boolean | undefined>;
+  params?: (stores: TStore, payload?: TPayload) => Record<string, string>;
+  validate?: (stores: TStore, payload?: TPayload) => boolean;
+  post?: (result: TResult, stores: TStore, payload?: TPayload) => void;
+  send?: (store: TStore) => Promise<unknown> | unknown;
+  redirectPath?:
+    | string
+    | ((result: TResult, payload?: TPayload, ctx?: ExecuteContext) => string);
+}

package/template/web/shared/src/context/StoreProvider.tsx

@@ -0,0 +1,45 @@
+/**
+ * RootStore 컨텍스트 — useStore / useParamStore / useSendMessage 등
+ * (싱글톤 rootStore 이므로 Provider 없이도 rootStore 직접 import 가능)
+ */
+
+import React, { createContext, useCallback, useContext } from 'react';
+import type { EndpointDef } from '@shared/endpoint';
+import type { SendMessageOptions } from '../types/ui';
+import { rootStore } from '../store/root-store';
+
+type RootStoreApi = typeof rootStore;
+
+const StoreContext = createContext<RootStoreApi | null>(null);
+
+export function useStore(): RootStoreApi {
+  const ctx = useContext(StoreContext);
+  if (!ctx) throw new Error('StoreProvider is required');
+  return ctx;
+}
+
+export function StoreProvider({ children }: { children: React.ReactNode }) {
+  return <StoreContext.Provider value={rootStore}>{children}</StoreContext.Provider>;
+}
+
+export function useSendMessage() {
+  const store = useStore();
+  return useCallback(
+    function sendMessage<T = unknown, R = unknown>(endpoint: EndpointDef, options?: SendMessageOptions<T>) {
+      return store.sendMessage<T, R>(endpoint, options ?? {});
+    },
+    [store],
+  );
+}
+
+export function useParamStore() {
+  return useStore().paramStore;
+}
+
+export function useSessionStore() {
+  return useStore().sessionStore;
+}
+
+export function useRootStore(): RootStoreApi {
+  return useStore();
+}

package/template/web/shared/src/hooks/useAppStore.ts

@@ -0,0 +1,23 @@
+import { reaction } from 'mobx';
+import { useSyncExternalStore } from 'react';
+import { rootStore } from '../store/root-store';
+
+/**
+ * Zustand 스타일 셀렉터 — RootStore(MobX) 구독
+ * 예: `useAppStore((s) => s.lastHealthAt)`, `useAppStore((s) => s.setLastHealthAt)`
+ */
+export function useAppStore<T>(selector: (store: typeof rootStore) => T): T {
+  return useSyncExternalStore(
+    (onChange) => {
+      const dispose = reaction(
+        () => selector(rootStore),
+        () => {
+          onChange();
+        },
+      );
+      return () => dispose();
+    },
+    () => selector(rootStore),
+    () => selector(rootStore),
+  );
+}

package/template/web/shared/src/hooks/useHealthStatus.ts

@@ -1,16 +1,25 @@
 import { useEffect, useState } from 'react';
+import { configureApi } from '../api/client';
 import { fetchHealth } from '../methods/health';
 import { safeJsonStringify } from '../utils/safeJsonStringify';
-import { useAppStore } from '../stores/appStore';
+import { useAppStore } from './useAppStore';
 
-export function useHealthStatus(apiBaseUrl: string) {
+/**
+ * @param apiBaseUrl 선택 — 넘기면 `configureApi` 로 baseURL 갱신. 앱 entry 에서 이미 `configureApi` 했다면 생략 가능.
+ */
+export function useHealthStatus(apiBaseUrl?: string) {
   const setLastHealthAt = useAppStore((s) => s.setLastHealthAt);
   const [text, setText] = useState('loading…');
   const [error, setError] = useState<string | null>(null);
 
   useEffect(() => {
+    if (apiBaseUrl != null && apiBaseUrl !== '') {
+      configureApi({ baseURL: apiBaseUrl });
+    }
     let cancelled = false;
-    fetchHealth(apiBaseUrl)
+    setError(null);
+    setText('loading…');
+    fetchHealth()
       .then((body) => {
         if (!cancelled) {
           setText(safeJsonStringify(body, 2));

package/template/web/shared/src/index.ts

@@ -1,8 +1,60 @@
 export { Shell, type ShellProps } from './components/Shell';
 export { useHealthStatus } from './hooks/useHealthStatus';
-export { useAppStore } from './stores/appStore';
+export { useAppStore } from './hooks/useAppStore';
+export {
+  StoreProvider,
+  useStore,
+  useRootStore,
+  useSendMessage,
+  useParamStore,
+  useSessionStore,
+} from './context/StoreProvider';
+
+export { configureApi, getApiBaseUrl, setApiHooks, apiClient } from './api/client';
+export { sendRequest, type RequestTransportOptions } from './api/request';
+export type { EndpointDef, HttpMethod } from '@shared/endpoint';
+export { healthEndpoint, appMetaEndpoint, unwrapResponseData } from '@shared/endpoint';
+export type {
+  ApiMethodConfig,
+  ApiMethodStore,
+  ApiMethodEndpointCall,
+  CoreSdkWrapped,
+  ExecuteContext,
+  ApiMethodUiConfig,
+  ScreenMeta,
+  ScreenAuthType,
+} from './api/types';
+export {
+  methods,
+  screenParamSchemas,
+  type MethodName,
+} from './api/methods';
+
+export {
+  rootStore,
+  RootStore,
+  sessionStore,
+  SessionStore,
+  apiCacheStore,
+  ApiCacheStore,
+  observer,
+} from './store';
+
+/** 이전 `appStore` 싱글톤 명칭 호환 */
+export { rootStore as appStore } from './store';
+
+export { ParamStore, type ParamStoreOptions, type ParamFieldState } from './params/param-store';
+export type { ParamsSchema, ParamScreenSchema, ParamFieldDef, ValidRule } from './params/types';
+
 export { fetchHealth } from './methods/health';
 export { getJson } from './lib/http';
 export { safeJsonStringify } from './utils/safeJsonStringify';
 export { FALLBACK_API_BASE_URL } from './constants/app';
 export type { CommonEnvelope, HealthData } from './types/api';
+export type {
+  ToastSeverity,
+  ToastItem,
+  ApiErrorItem,
+  IndicatorState,
+  SendMessageOptions,
+} from './types/ui';

package/template/web/shared/src/lib/http.ts

@@ -1,7 +1,10 @@
-export async function getJson<T>(url: string, init?: RequestInit): Promise<T> {
-  const res = await fetch(url, { ...init, headers: { Accept: 'application/json', ...init?.headers } });
-  if (!res.ok) {
-    throw new Error(`HTTP ${res.status} ${res.statusText}`);
-  }
-  return res.json() as Promise<T>;
+import type { AxiosRequestConfig } from 'axios';
+import { apiClient } from '../api/client';
+
+export async function getJson<T>(url: string, config?: AxiosRequestConfig): Promise<T> {
+  const res = await apiClient.get<T>(url, {
+    ...config,
+    headers: { Accept: 'application/json', ...config?.headers },
+  });
+  return res.data;
 }

package/template/web/shared/src/methods/health.ts

@@ -1,7 +1,8 @@
-import { getJson } from '../lib/http';
+import { sendRequest } from '../api/request';
+import { healthEndpoint } from '@shared/endpoint';
 import type { CommonEnvelope, HealthData } from '../types/api';
 
-export async function fetchHealth(apiBase: string): Promise<CommonEnvelope<HealthData>> {
-  const base = apiBase.replace(/\/$/, '');
-  return getJson<CommonEnvelope<HealthData>>(`${base}/health`);
+/** 직접 호출용 (토스트 없음) — UI 훅은 보통 이 함수 사용 */
+export async function fetchHealth(): Promise<CommonEnvelope<HealthData>> {
+  return sendRequest<unknown, CommonEnvelope<HealthData>>(healthEndpoint, {});
 }

package/template/web/shared/src/params/param-store.ts

@@ -0,0 +1,178 @@
+import { makeAutoObservable, runInAction } from 'mobx';
+import type { ParamFieldDef, ParamScreenSchema, ParamsSchema } from './types';
+import { validateField } from './validations';
+
+export interface ParamStoreOptions {
+  onValidationFail?: (message: string) => void;
+  getStore?: () => unknown;
+}
+
+export interface ParamFieldState {
+  value: string | number | boolean | null;
+  valid: ParamFieldDef['valid'];
+}
+
+function toFieldState(def: ParamFieldDef): ParamFieldState {
+  return {
+    value: def.value ?? '',
+    valid: def.valid ?? [],
+  };
+}
+
+export class ParamStore {
+  params: Record<string, Record<string, ParamFieldState>> = {};
+  fieldErrors: Record<string, Record<string, string>> = {};
+  screenErrors: Record<string, string> = {};
+  private _onValidationFail?: (message: string) => void;
+  private _getStore?: () => unknown;
+
+  constructor(initialSchema?: ParamsSchema, options?: ParamStoreOptions) {
+    makeAutoObservable(this, {}, { autoBind: true });
+    this._onValidationFail = options?.onValidationFail;
+    this._getStore = options?.getStore;
+    if (initialSchema) {
+      for (const [screen, fields] of Object.entries(initialSchema)) {
+        this.registerScreen(screen, fields);
+      }
+    }
+  }
+
+  registerScreen(screen: string, schema: ParamScreenSchema): void {
+    runInAction(() => {
+      if (!this.params[screen]) this.params[screen] = {};
+      for (const [field, def] of Object.entries(schema)) {
+        this.params[screen][field] = toFieldState(def);
+      }
+    });
+  }
+
+  getParam(screen: string, field: string): string | number | boolean | null {
+    return this.params[screen]?.[field]?.value ?? null;
+  }
+
+  getScreenValues(screen: string): Record<string, string | number | boolean | null> {
+    const row = this.params[screen];
+    if (!row) return {};
+    return Object.fromEntries(Object.entries(row).map(([k, v]) => [k, v.value])) as Record<
+      string,
+      string | number | boolean | null
+    >;
+  }
+
+  setParam(payload: { screen: string; field: string; value: string | number | boolean | null }):
+    | { ok: true }
+    | { ok: false; message: string; field: string } {
+    const { screen, field, value } = payload;
+    const state = this.params[screen]?.[field];
+    if (!state) {
+      runInAction(() => {
+        if (!this.params[screen]) this.params[screen] = {};
+        this.params[screen][field] = { value, valid: [] };
+      });
+      return { ok: true };
+    }
+
+    const result = validateField(value, state.valid, this._getStore);
+    runInAction(() => {
+      state.value = value;
+      if (this.screenErrors[screen]) delete this.screenErrors[screen];
+      if (!result.ok) {
+        const msg = result.message ?? 'validation.failed';
+        if (!this.fieldErrors[screen]) this.fieldErrors[screen] = {};
+        this.fieldErrors[screen][field] = msg;
+        this._onValidationFail?.(msg);
+      } else if (this.fieldErrors[screen]?.[field]) {
+        delete this.fieldErrors[screen][field];
+        if (Object.keys(this.fieldErrors[screen]).length === 0) delete this.fieldErrors[screen];
+      }
+    });
+    return result.ok
+      ? { ok: true as const }
+      : { ok: false as const, message: result.message ?? 'validation.failed', field };
+  }
+
+  getFieldError(screen: string, field: string): string | undefined {
+    return this.fieldErrors[screen]?.[field];
+  }
+
+  setScreenError(screen: string, message: string): void {
+    runInAction(() => {
+      if (message) this.screenErrors[screen] = message;
+      else if (this.screenErrors[screen]) delete this.screenErrors[screen];
+    });
+  }
+
+  getScreenError(screen: string): string | undefined {
+    return this.screenErrors[screen];
+  }
+
+  isScreenValid(screen: string): boolean {
+    const row = this.params[screen];
+    if (!row) return true;
+    for (const [, s] of Object.entries(row)) {
+      const res = validateField(s.value, s.valid, this._getStore);
+      if (!res.ok) return false;
+    }
+    return true;
+  }
+
+  setParams(
+    screen: string,
+    updates: Record<string, string | number | boolean | null>,
+  ): { ok: true } | { ok: false; message: string; field: string } {
+    const state = this.params[screen];
+    if (!state) {
+      runInAction(() => {
+        this.params[screen] = {};
+        for (const [field, value] of Object.entries(updates)) {
+          this.params[screen][field] = { value, valid: [] };
+        }
+      });
+      return { ok: true };
+    }
+
+    for (const [field, value] of Object.entries(updates)) {
+      const s = state[field];
+      if (s) {
+        const res = validateField(value, s.valid, this._getStore);
+        if (!res.ok) {
+          const msg = res.message ?? 'validation.failed';
+          runInAction(() => {
+            if (!this.fieldErrors[screen]) this.fieldErrors[screen] = {};
+            this.fieldErrors[screen][field] = msg;
+          });
+          this._onValidationFail?.(msg);
+          return { ok: false, message: msg, field };
+        }
+      }
+    }
+
+    runInAction(() => {
+      for (const [field, value] of Object.entries(updates)) {
+        if (state[field]) {
+          state[field].value = value;
+          if (this.fieldErrors[screen]?.[field]) {
+            delete this.fieldErrors[screen][field];
+          }
+        } else {
+          this.params[screen][field] = { value, valid: [] };
+        }
+      }
+      if (this.fieldErrors[screen] && Object.keys(this.fieldErrors[screen]).length === 0) {
+        delete this.fieldErrors[screen];
+      }
+    });
+    return { ok: true };
+  }
+
+  resetScreen(screen: string, schema: ParamScreenSchema): void {
+    runInAction(() => {
+      this.params[screen] = {};
+      for (const [field, def] of Object.entries(schema)) {
+        this.params[screen][field] = toFieldState(def);
+      }
+      if (this.fieldErrors[screen]) delete this.fieldErrors[screen];
+      if (this.screenErrors[screen]) delete this.screenErrors[screen];
+    });
+  }
+}

package/template/web/shared/src/params/types.ts

@@ -0,0 +1,21 @@
+export interface ValidRule {
+  min?: number;
+  max?: number;
+  expr?: RegExp | ((value: string, stores?: unknown) => boolean);
+  message?: string;
+  required?: boolean;
+}
+
+export interface ParamFieldDef {
+  value?: string | number | boolean | null;
+  valid: ValidRule[];
+}
+
+export type ParamScreenSchema = Record<string, ParamFieldDef>;
+export type ParamsSchema = Record<string, ParamScreenSchema>;
+
+export interface ValidateResult {
+  ok: boolean;
+  message?: string;
+  field?: string;
+}

package/template/web/shared/src/params/validations.ts

@@ -0,0 +1,32 @@
+import type { ValidRule, ValidateResult } from './types';
+
+export function validateField(value: unknown, rules: ValidRule[], getStore?: () => unknown): ValidateResult {
+  const raw = value === undefined || value === null ? '' : String(value).trim();
+
+  for (const rule of rules) {
+    if (rule.required && (raw === '' || value === undefined || value === null)) {
+      return { ok: false, message: rule.message ?? 'validation.required', field: undefined };
+    }
+    if (!rule.required && raw === '') continue;
+
+    if (rule.min !== undefined && raw.length < rule.min) {
+      return { ok: false, message: rule.message ?? 'validation.minLength', field: undefined };
+    }
+    if (rule.max !== undefined && raw.length > rule.max) {
+      return { ok: false, message: rule.message ?? 'validation.maxLength', field: undefined };
+    }
+    if (rule.expr) {
+      if (rule.expr instanceof RegExp) {
+        if (!rule.expr.test(raw)) {
+          return { ok: false, message: rule.message ?? 'validation.format', field: undefined };
+        }
+      } else if (typeof rule.expr === 'function') {
+        const stores = getStore?.();
+        if (!rule.expr(raw, stores)) {
+          return { ok: false, message: rule.message ?? 'validation.format', field: undefined };
+        }
+      }
+    }
+  }
+  return { ok: true };
+}

package/template/web/shared/src/store/api-cache-store.ts

@@ -0,0 +1,35 @@
+import { makeAutoObservable } from 'mobx';
+
+interface CacheEntry<T = unknown> {
+  value: T;
+  staleAt: number;
+}
+
+export class ApiCacheStore {
+  private _entries = new Map<string, CacheEntry>();
+
+  constructor() {
+    makeAutoObservable(this);
+  }
+
+  get<T = unknown>(key: string): T | undefined {
+    const entry = this._entries.get(key);
+    if (!entry) return undefined;
+    if (entry.staleAt > 0 && Date.now() > entry.staleAt) {
+      this._entries.delete(key);
+      return undefined;
+    }
+    return entry.value as T;
+  }
+
+  set<T = unknown>(key: string, value: T, ttlMs?: number): void {
+    const staleAt = ttlMs != null ? Date.now() + ttlMs : 0;
+    this._entries.set(key, { value, staleAt });
+  }
+
+  clear(): void {
+    this._entries.clear();
+  }
+}
+
+export const apiCacheStore = new ApiCacheStore();

package/template/web/shared/src/store/index.ts

@@ -0,0 +1,4 @@
+export { apiCacheStore, ApiCacheStore } from './api-cache-store';
+export { rootStore, RootStore } from './root-store';
+export { sessionStore, SessionStore } from './session-store';
+export { observer } from 'mobx-react-lite';