@designbasekorea/wordpress-ui 0.1.0

package/docs/WORDPRESS-ADMIN-GUIDE.md

@@ -0,0 +1,890 @@
+# `@designbasekorea/wordpress-ui` WordPress 관리자 적용 가이드
+
+이 문서는 `@designbasekorea/wordpress-ui`를 WordPress 플러그인과 테마의 관리자 화면에 적용하는 표준 가이드입니다.
+
+이 패키지는 `@designbasekorea/ui-wc`를 내부 구현으로 사용하지만, 소비자는 `ui-wc`를 직접 import하지 않습니다. 소비자 코드는 항상 `wordpress-ui`의 공개 진입점과 배포된 자산만 사용합니다.
+
+현재 패키지는 다음 원칙을 따릅니다.
+
+- 기본 런타임은 React가 없는 Web Component/vanilla 방식입니다.
+- React adapter는 선택 사항입니다. React를 사용하지 않는 플러그인과 테마에는 React를 로드하지 않습니다.
+- WordPress 전체 관리자 프레임을 대체하지 않습니다.
+- 플러그인 또는 테마가 소유한 관리자 화면 안에만 페이지 shell을 렌더링합니다.
+- UI는 표현과 상호작용만 담당하고, REST·AJAX·Settings API·권한·nonce·비즈니스 로직은 소비자가 담당합니다.
+- `styles.css`는 Designbase theme token과 필요한 아이콘 폰트를 포함한 self-contained 배포물입니다.
+- CDN을 사용하지 않고 플러그인 또는 테마 배포물에 JS/CSS/font를 포함합니다.
+
+## 1. 권장 아키텍처
+
+```text
+WordPress plugin/theme
+        │
+        ├─ admin_enqueue_scripts: 현재 화면 확인 및 allowlist
+        ├─ REST / AJAX / Settings API: 데이터·권한·저장
+        │
+        └─ wordpress-ui 자산
+             ├─ dist/styles.css
+             ├─ dist/browser.iife.js
+             └─ dist/icons.woff2 / icons.woff
+                    │
+                    └─ .designbase-wp-admin
+                         ├─ plugin/theme 내부 shell
+                         ├─ native HTML controls
+                         └─ db-* Web Components
+```
+
+### 1.1 WordPress 전역 관리자와 플러그인 내부 shell의 경계
+
+`AdminShell`과 `AdminSidebar`는 플러그인 또는 테마 내부 화면을 위한 것입니다. 다음 전역 요소는 수정하지 않습니다.
+
+- `#adminmenu`
+- `#wpadminbar`
+- WordPress 전역 `.wrap`의 기본 동작
+- 다른 플러그인이 등록한 notice, modal, table, button
+- `body`, `:root`, 전역 `button`, 전역 `table` 스타일
+
+각 화면의 최상위 컨테이너에 `.designbase-wp-admin`을 추가해야 합니다. 패키지 스타일은 이 root 아래로 scope되어 있으므로 root가 없으면 일부 컴포넌트가 기본 브라우저 스타일처럼 보일 수 있습니다.
+
+```html
+<div class="wrap designbase-wp-admin myplugin-admin" data-myplugin-screen="settings">
+    <!-- 이 영역만 wordpress-ui가 소유한다. -->
+</div>
+```
+
+테마 관리자도 같은 규칙을 사용합니다. 테마가 관리자를 전역적으로 꾸미는 방식이 아니라, 테마 설정 페이지의 화면 root 안에서만 사용합니다.
+
+## 2. 패키지 설치와 배포
+
+### 2.1 Node 프로젝트에 설치
+
+```bash
+npm install @designbasekorea/wordpress-ui
+```
+
+WordPress 서버가 npm을 실행하는 것이 아닙니다. 라이브러리를 설치한 뒤 플러그인 또는 테마 빌드 과정에서 배포에 필요한 파일을 포함해야 합니다.
+
+권장 배포 방식은 다음과 같습니다.
+
+1. 라이브러리 버전을 package lock에 고정합니다.
+2. `node_modules`에서 패키지의 `dist`와 PHP helper를 플러그인/테마의 vendor 폴더로 복사합니다.
+3. 플러그인/테마의 `admin_enqueue_scripts`에서 로컬 파일을 enqueue합니다.
+4. 최종 zip에 JS, CSS, WOFF font가 포함되었는지 확인합니다.
+
+### 2.2 패키지 파일 구조
+
+`wordpress-ui` 패키지를 그대로 vendor에 포함할 경우 다음 구조를 사용합니다.
+
+```text
+my-plugin/
+├─ my-plugin.php
+├─ vendor/
+│  └─ wordpress-ui/
+│     ├─ wordpress-ui.php
+│     └─ dist/
+│        ├─ browser.iife.js
+│        ├─ styles.css
+│        ├─ icons.woff2
+│        ├─ icons.woff
+│        └─ styles/
+│           ├─ controls.css
+│           ├─ overlays.css
+│           └─ shell.css
+└─ assets/
+   └─ dist/
+      ├─ admin.js
+      └─ admin.css
+```
+
+`wordpress-ui.php`의 enqueue helper는 패키지 root를 기준으로 `dist/styles.css`와 `dist/browser.iife.js`를 찾습니다. 따라서 helper를 사용할 때는 `base_url`과 `base_path`를 `vendor/wordpress-ui`에 맞춰 전달해야 합니다.
+
+선택 로딩이 필요하지 않다면 `dist/styles.css` 하나만 사용합니다. 이 파일에는 테마 토큰, ui-wc 컴포넌트 스타일, 관리자 shell/overlay 스타일, 아이콘 폰트 규칙이 재조합되어 있습니다. 별도의 `theme.css`나 CDN 아이콘 CSS를 추가로 enqueue하지 않습니다.
+
+### 2.3 배포 전 패키지 확인
+
+라이브러리 저장소에서 다음을 실행합니다.
+
+```bash
+cd packages/wordpress-ui
+npm install
+npm run build
+npm run verify
+npm run audit:axe
+npm pack --dry-run
+```
+
+`npm pack --dry-run` 결과에는 최소한 다음이 있어야 합니다.
+
+- `dist/styles.css`
+- `dist/browser.iife.js`
+- `dist/icons.woff2`
+- `dist/icons.woff`
+- `wordpress-ui.php`
+- `README.md`
+- `docs/WORDPRESS-ADMIN-GUIDE.md`
+
+실제 플러그인/테마 배포 zip에는 `node_modules`, 소스 파일, 테스트용 서버, 로컬 설정 파일, secret을 포함하지 않습니다.
+
+## 3. 자산 enqueue 표준
+
+### 3.1 플러그인: 권장 구현
+
+아래 예시는 플러그인 main file 옆에 `vendor/wordpress-ui`가 있는 경우입니다.
+
+```php
+<?php
+
+defined('ABSPATH') || exit;
+
+require_once __DIR__ . '/vendor/wordpress-ui/wordpress-ui.php';
+
+final class MyPlugin_Admin_Assets
+{
+    private const UI_VERSION = '0.1.0';
+
+    public static function init(): void
+    {
+        add_action('admin_enqueue_scripts', [self::class, 'enqueue']);
+    }
+
+    public static function enqueue(string $hook_suffix): void
+    {
+        $screen = function_exists('get_current_screen') ? get_current_screen() : null;
+        $screen_id = $screen ? $screen->id : '';
+
+        $allowed_screens = [
+            'toplevel_page_myplugin',
+            'myplugin_page_myplugin-settings',
+        ];
+
+        if (!in_array($screen_id, $allowed_screens, true)) {
+            return;
+        }
+
+        // 화면마다 필요한 capability가 다르면 화면별로 분리한다.
+        if (!self::can_access_screen($screen_id)) {
+            return;
+        }
+
+        $base_url = plugin_dir_url(__FILE__) . 'vendor/wordpress-ui';
+        $base_path = plugin_dir_path(__FILE__) . 'vendor/wordpress-ui';
+
+        designbase_wordpress_ui_enqueue([
+            'handle' => 'myplugin-wordpress-ui',
+            'base_url' => $base_url,
+            'base_path' => $base_path,
+            'version' => self::UI_VERSION,
+        ]);
+
+        wp_enqueue_style(
+            'myplugin-admin',
+            plugin_dir_url(__FILE__) . 'assets/dist/admin.css',
+            ['myplugin-wordpress-ui'],
+            self::UI_VERSION
+        );
+
+        wp_enqueue_script(
+            'myplugin-admin',
+            plugin_dir_url(__FILE__) . 'assets/dist/admin.js',
+            ['myplugin-wordpress-ui-browser'],
+            self::UI_VERSION,
+            true
+        );
+
+        wp_localize_script('myplugin-admin', 'MyPluginAdmin', [
+            'restUrl' => esc_url_raw(rest_url('myplugin/v1')),
+            'nonce' => wp_create_nonce('wp_rest'),
+            'screen' => $screen_id,
+        ]);
+    }
+
+    private static function can_access_screen(string $screen_id): bool
+    {
+        if ($screen_id === 'myplugin_page_myplugin-settings') {
+            return current_user_can('manage_options');
+        }
+
+        return current_user_can('edit_posts');
+    }
+}
+
+MyPlugin_Admin_Assets::init();
+```
+
+`designbase_wordpress_ui_enqueue()`는 자산을 enqueue할 뿐이며, 현재 화면이나 사용자의 capability를 확인하지 않습니다. 화면 allowlist와 권한 검사는 소비 플러그인이 반드시 수행해야 합니다.
+
+`$hook_suffix`는 WordPress가 전달하는 값이고, `get_current_screen()->id`는 화면 식별에 더 읽기 쉬운 경우가 많습니다. 두 값을 혼동하지 말고 실제 화면에서 로그로 확인한 뒤 allowlist를 고정합니다. 일반적으로는 `screen_id` 기준 allowlist를 권장합니다.
+
+### 3.2 테마: 클래식 테마
+
+테마 관리자 페이지는 `get_template_directory_*()`를 사용합니다.
+
+```php
+<?php
+
+defined('ABSPATH') || exit;
+
+require_once get_template_directory() . '/vendor/wordpress-ui/wordpress-ui.php';
+
+add_action('admin_enqueue_scripts', static function (string $hook_suffix): void {
+    $screen = function_exists('get_current_screen') ? get_current_screen() : null;
+    if (!$screen || $screen->id !== 'appearance_page_mytheme-settings') {
+        return;
+    }
+
+    if (!current_user_can('manage_options')) {
+        return;
+    }
+
+    designbase_wordpress_ui_enqueue([
+        'handle' => 'mytheme-wordpress-ui',
+        'base_url' => get_template_directory_uri() . '/vendor/wordpress-ui',
+        'base_path' => get_template_directory() . '/vendor/wordpress-ui',
+        'version' => '1.0.0',
+    ]);
+});
+```
+
+자식 테마를 지원하고 vendor 파일이 자식 테마에 포함된다면 `get_stylesheet_directory_uri()`와 `get_stylesheet_directory()`를 사용합니다. 부모 테마의 vendor를 항상 사용할 정책이면 `get_template_directory_*()`를 유지하고, 이 정책을 문서화합니다.
+
+### 3.3 enqueue 규칙
+
+- `admin_enqueue_scripts`에서만 관리자 자산을 등록합니다.
+- 현재 화면이 허용된 화면일 때만 `styles.css`와 `browser.iife.js`를 enqueue합니다.
+- WordPress 전역 관리자 화면에 자산을 무조건 enqueue하지 않습니다.
+- `browser.iife.js`는 `styles.css`보다 먼저 또는 함께 등록되어야 하며, 플러그인 JS는 `myplugin-wordpress-ui-browser`에 의존합니다.
+- 버전은 패키지 버전, 플러그인 버전 또는 `filemtime()` 중 하나로 일관되게 관리합니다.
+- 사용자가 접근하지 못하는 화면에 자산을 enqueue하지 않습니다. 단, 자산 노출 자체가 민감한 정보를 포함하지 않는지도 별도로 검토합니다.
+- 최종 HTML에서 CDN, unpkg, jsDelivr, 외부 icon font를 요청하지 않습니다.
+
+## 4. HTML/vanilla 적용
+
+WordPress 플러그인과 테마의 기본 선택지는 vanilla/PHP입니다. React가 없어도 동일한 Designbase 스타일과 ui-wc Web Component를 사용할 수 있습니다.
+
+### 4.1 페이지 기본 구조
+
+```php
+<div class="wrap designbase-wp-admin myplugin-admin">
+    <div class="dbwp-admin-shell dbwp-admin-shell--has-sidebar">
+        <aside class="dbwp-admin-shell__sidebar" aria-label="My Plugin 메뉴">
+            <div class="dbwp-admin-sidebar">
+                <div class="dbwp-admin-sidebar__title">My Plugin</div>
+                <nav class="dbwp-admin-sidebar__nav">
+                    <a class="dbwp-admin-sidebar__link is-active"
+                       href="<?php echo esc_url(admin_url('admin.php?page=myplugin')); ?>"
+                       aria-current="page">
+                        <i class="dbwp-admin-icon icon-dashboard" aria-hidden="true"></i>
+                        <span class="dbwp-admin-sidebar__label">대시보드</span>
+                    </a>
+                    <a class="dbwp-admin-sidebar__link"
+                       href="<?php echo esc_url(admin_url('admin.php?page=myplugin-settings')); ?>">
+                        <i class="dbwp-admin-icon icon-settings" aria-hidden="true"></i>
+                        <span class="dbwp-admin-sidebar__label">설정</span>
+                    </a>
+                </nav>
+            </div>
+        </aside>
+
+        <main class="dbwp-admin-shell__main" id="main-content">
+            <header class="dbwp-admin-page-header">
+                <div class="dbwp-admin-page-header__heading">
+                    <i class="dbwp-admin-icon icon-dashboard" aria-hidden="true"></i>
+                    <div>
+                        <h1 class="dbwp-admin-page-header__title">대시보드</h1>
+                        <p class="dbwp-admin-page-header__description">플러그인 상태와 최근 작업을 확인합니다.</p>
+                    </div>
+                </div>
+                <div class="dbwp-admin-page-header__actions">
+                    <a class="button button-secondary" href="<?php echo esc_url(admin_url('admin.php?page=myplugin-settings')); ?>">
+                        설정
+                    </a>
+                </div>
+            </header>
+
+            <div class="dbwp-admin-page-content">
+                <!-- tabs, filter, section, table 등을 배치한다. -->
+            </div>
+        </main>
+    </div>
+</div>
+```
+
+컴포넌트 스타일을 사용하는 자체 markup은 `.designbase-wp-admin` 내부에 둡니다. 단순한 링크와 form submit은 WordPress의 native `<a>`와 `<button>`을 우선 사용하고, 복합 동작이 필요한 경우에만 Web Component를 사용합니다.
+
+### 4.2 ui-wc 기본 컴포넌트 사용
+
+`browser` entry를 로드하면 `wordpress-ui`가 관리자 화면에 필요한 ui-wc element를 등록합니다.
+
+```html
+<form class="myplugin-filter-form" data-myplugin-filter-form>
+    <db-search-bar
+        name="search"
+        placeholder="제목 검색"
+        aria-label="제목 검색">
+    </db-search-bar>
+
+    <db-select
+        name="status"
+        placeholder="전체 상태"
+        options='[{"value":"all","label":"전체 상태"},{"value":"published","label":"공개"},{"value":"draft","label":"임시글"}]'>
+    </db-select>
+
+    <button type="reset" class="button button-secondary">초기화</button>
+    <button type="submit" class="button button-primary">적용</button>
+</form>
+```
+
+컴포넌트의 attribute/property 계약은 패키지의 공개 타입과 Storybook 예제를 기준으로 확인합니다. HTML attribute로 JSON을 전달하는 경우 작은 데이터만 넣고, 사용자 입력을 그대로 HTML attribute에 연결하지 않습니다.
+
+### 4.3 vanilla 이벤트 연결
+
+이벤트 이름은 Web Component가 제공하는 `db-*` 이벤트를 사용합니다. 데이터 조회는 이벤트 핸들러에서 플러그인 코드로 위임합니다.
+
+```js
+const select = document.querySelector('db-select[name="status"]');
+
+select?.addEventListener('db-change', (event) => {
+    const value = event.detail?.value ?? 'all';
+    const url = new URL(window.location.href);
+
+    if (value === 'all') {
+        url.searchParams.delete('status');
+    } else {
+        url.searchParams.set('status', value);
+    }
+
+    window.location.assign(url.toString());
+});
+```
+
+일반적으로 사용하는 이벤트 매핑은 다음과 같습니다.
+
+| 목적 | 이벤트 |
+| --- | --- |
+| 값 변경 | `db-change` |
+| text input 변경 | `db-input` |
+| 검색 실행 | `db-search` |
+| clear 실행 | `db-clear` |
+| modal/drawer 닫힘 | `db-close` |
+| confirm/cancel | `db-confirm`, `db-cancel` |
+| toggle 변경 | `db-toggle` |
+| page 변경 | `db-change` |
+
+실제 `event.detail` 모양은 사용하는 컴포넌트의 타입과 구현을 기준으로 확인합니다. 이벤트 전체를 추측해 사용하지 말고, 브라우저에서 한 번 출력해 소비 계약을 고정합니다.
+
+### 4.4 아이콘 사용
+
+아이콘은 이모지나 임의의 유니코드 문자를 사용하지 않고 Designbase icons 이름을 사용합니다.
+
+```html
+<i class="dbwp-admin-icon icon-dashboard" aria-hidden="true"></i>
+<i class="dbwp-admin-icon icon-file-manager" aria-hidden="true"></i>
+<i class="dbwp-admin-icon icon-search" aria-hidden="true"></i>
+<i class="dbwp-admin-icon icon-settings" aria-hidden="true"></i>
+```
+
+`styles.css`가 아이콘 폰트와 `@font-face` 규칙을 포함합니다. 아이콘이 보이지 않으면 다음을 확인합니다.
+
+1. `dist/styles.css`가 실제 화면에 로드되었는지 확인합니다.
+2. `dist/icons.woff2`와 `dist/icons.woff`가 CSS가 기대하는 상대 경로에 있는지 확인합니다.
+3. 브라우저 Network에서 font 요청이 404가 아닌지 확인합니다.
+4. 임의의 외부 icon font CSS를 추가해 font-family를 덮어쓰지 않았는지 확인합니다.
+
+## 5. React adapter 적용
+
+React는 선택 사항입니다. Gutenberg나 기존 React 앱과 연결해야 하는 화면에서만 사용하고, 일반적인 PHP admin page에는 vanilla entry를 권장합니다.
+
+```bash
+npm install @designbasekorea/wordpress-ui react react-dom
+```
+
+```tsx
+import '@designbasekorea/wordpress-ui/styles.css';
+import {
+    AdminDataTable,
+    AdminEmptyState,
+    AdminFilterBar,
+    AdminPage,
+    AdminPageContent,
+    AdminPageHeader,
+    AdminSection,
+    AdminShell,
+    type AdminNavItem,
+} from '@designbasekorea/wordpress-ui/react';
+
+const sidebarItems: AdminNavItem[] = [
+    { id: 'dashboard', label: '대시보드', href: '?page=myplugin', icon: 'dashboard', active: true },
+    { id: 'settings', label: '설정', href: '?page=myplugin-settings', icon: 'settings' },
+];
+
+export function MyPluginAdmin() {
+    return (
+        <div className="designbase-wp-admin">
+            <AdminShell sidebarItems={sidebarItems} sidebarTitle="My Plugin">
+                <AdminPage>
+                    <AdminPageHeader
+                        title="콘텐츠 관리"
+                        icon="file-manager"
+                        description="콘텐츠를 검색하고 상태를 관리합니다."
+                    />
+                    <AdminPageContent maxWidth="xl">
+                        <AdminSection title="검색 및 필터">
+                            <AdminFilterBar
+                                searchPlaceholder="제목 검색"
+                                statusPlaceholder="전체 상태"
+                                statusOptions={[
+                                    { value: 'all', label: '전체 상태' },
+                                    { value: 'published', label: '공개' },
+                                    { value: 'draft', label: '임시글' },
+                                ]}
+                                onSubmit={(event) => {
+                                    event.preventDefault();
+                                    // REST 또는 URL query 변경은 소비 앱이 담당한다.
+                                }}
+                            />
+                        </AdminSection>
+                        <AdminSection title="목록">
+                            <AdminDataTable
+                                columns={[
+                                    { id: 'title', header: '제목', key: 'title', sortable: true },
+                                    { id: 'status', header: '상태', key: 'status' },
+                                ]}
+                                rows={[]}
+                                emptyState={<AdminEmptyState title="콘텐츠가 없습니다." />}
+                            />
+                        </AdminSection>
+                    </AdminPageContent>
+                </AdminPage>
+            </AdminShell>
+        </div>
+    );
+}
+```
+
+React adapter의 책임은 관리자 shell과 컴포넌트 조합입니다.
+
+- `AdminShell`: 내부 sidebar와 main layout
+- `AdminSidebar`: 메뉴, active 상태, badge, 모바일 close
+- `AdminPage`, `AdminPageContent`: 페이지 폭과 밀도
+- `AdminPageHeader`: title, icon, description, breadcrumb, action, back link
+- `AdminSection`: 제목, 설명, action, optional collapse
+- `AdminFilterBar`: 검색과 상태 필터 표현
+- `AdminTabs`: 탭 표현과 active 상태
+- `AdminDataTable`: column, row, sort, loading, empty, error 상태 표현
+- `AdminEmptyState`, `AdminLoadingState`, `AdminErrorState`: 상태 화면
+
+이 컴포넌트들은 REST 요청, 페이지네이션 API, nonce 갱신, capability 검사를 대신하지 않습니다. React state와 서버 데이터의 생명주기는 플러그인/테마 앱이 소유합니다.
+
+## 6. REST, AJAX, Settings API 연결
+
+### 6.1 REST route의 기본 원칙
+
+UI가 호출하는 endpoint는 플러그인 또는 테마가 등록합니다. 모든 route에는 명시적인 `permission_callback`이 있어야 합니다.
+
+```php
+add_action('rest_api_init', static function (): void {
+    register_rest_route('myplugin/v1', '/items', [
+        'methods' => WP_REST_Server::READABLE,
+        'callback' => static function (WP_REST_Request $request): WP_REST_Response {
+            $search = sanitize_text_field((string) $request->get_param('search'));
+            $status = sanitize_key((string) $request->get_param('status'));
+
+            $items = MyPlugin_Items::query([
+                'search' => $search,
+                'status' => $status,
+            ]);
+
+            return rest_ensure_response([
+                'items' => $items,
+                'total' => count($items),
+            ]);
+        },
+        'permission_callback' => static function (): bool {
+            return current_user_can('edit_posts');
+        },
+        'args' => [
+            'search' => [
+                'sanitize_callback' => 'sanitize_text_field',
+            ],
+            'status' => [
+                'sanitize_callback' => 'sanitize_key',
+                'validate_callback' => static function ($value): bool {
+                    return in_array($value, ['all', 'published', 'draft'], true);
+                },
+            ],
+        ],
+    ]);
+});
+```
+
+읽기 endpoint라도 capability를 검사합니다. 쓰기 endpoint는 더 강한 capability, 입력 검증, 저장 실패 처리, 감사 로그가 필요할 수 있습니다. nonce는 요청 출처를 확인하는 장치이지 capability나 인증을 대신하지 않습니다.
+
+### 6.2 vanilla fetch
+
+`wp_localize_script()`로 전달한 값에는 URL, nonce, 화면 상태처럼 브라우저에 공개되어도 되는 값만 넣습니다.
+
+```js
+async function loadItems({ search = '', status = 'all' } = {}) {
+    const url = new URL(`${MyPluginAdmin.restUrl}/items`);
+    url.searchParams.set('search', search);
+    url.searchParams.set('status', status);
+
+    const response = await fetch(url, {
+        headers: {
+            Accept: 'application/json',
+            'X-WP-Nonce': MyPluginAdmin.nonce,
+        },
+        credentials: 'same-origin',
+    });
+
+    if (!response.ok) {
+        throw new Error(`Request failed: ${response.status}`);
+    }
+
+    return response.json();
+}
+```
+
+화면에서는 로딩·성공·empty·error 상태를 각각 표현합니다. 실패를 조용히 무시하거나 `alert()`만 호출하지 않습니다.
+
+```js
+try {
+    renderLoadingState();
+    const result = await loadItems(filters);
+    renderItems(result.items);
+    window.DesignbaseWordPressUI?.showSuccessToast('목록을 불러왔습니다.');
+} catch (error) {
+    renderErrorState('콘텐츠를 불러오지 못했습니다. 잠시 후 다시 시도해 주세요.');
+    window.DesignbaseWordPressUI?.showErrorToast('요청을 처리하지 못했습니다.');
+}
+```
+
+### 6.3 toast와 confirm
+
+브라우저에 `browser.iife.js`가 로드되면 다음 imperative API를 사용할 수 있습니다.
+
+```js
+window.DesignbaseWordPressUI?.showSuccessToast('설정이 저장되었습니다.');
+
+const confirmed = await window.DesignbaseWordPressUI?.showConfirmModal({
+    title: '콘텐츠를 삭제할까요?',
+    message: '삭제한 콘텐츠는 복구할 수 없습니다.',
+    confirmText: '삭제',
+    cancelText: '취소',
+    type: 'danger',
+});
+
+if (confirmed) {
+    await deleteItem();
+}
+```
+
+중요한 삭제나 대량 변경에는 confirm을 사용합니다. 실제 삭제 권한과 재검증은 서버 endpoint에서 다시 수행해야 합니다.
+
+### 6.4 Settings API
+
+WordPress 설정 페이지는 가능하면 Settings API를 사용합니다.
+
+```php
+register_setting('myplugin', 'myplugin_options', [
+    'type' => 'array',
+    'sanitize_callback' => static function ($value): array {
+        return [
+            'enabled' => !empty($value['enabled']),
+            'label' => sanitize_text_field((string) ($value['label'] ?? '')),
+        ];
+    },
+]);
+```
+
+설정 form을 직접 출력할 때는 `settings_fields()`를 포함하고, 저장 action의 capability와 nonce를 함께 검증합니다. UI 패키지는 설정 저장 방식에 관여하지 않습니다.
+
+## 7. 화면 구성 표준
+
+신규 관리자 화면은 다음 순서로 구성합니다.
+
+```text
+.designbase-wp-admin
+└─ AdminShell 또는 dbwp-admin-shell
+   ├─ AdminSidebar 또는 plugin 내부 nav
+   └─ main
+      ├─ AdminPageHeader / db-page-header
+      ├─ AdminTabs / db-tabs (필요한 경우)
+      └─ AdminPageContent
+         ├─ AdminSection / db-section
+         ├─ AdminFilterBar
+         └─ AdminDataTable 또는 native table
+```
+
+### 7.1 페이지 헤더
+
+페이지 헤더에는 화면의 목적을 명확하게 표시합니다.
+
+- `h1`은 화면마다 하나만 둡니다.
+- 제목 옆 아이콘은 의미를 보조할 때만 사용합니다.
+- 설명은 제목과 직접 관련된 짧은 문장으로 작성합니다.
+- primary action은 우측 action 영역에 둡니다.
+- 뒤로가기는 브라우저 history에 의존하지 말고 의미 있는 URL을 제공합니다.
+
+### 7.2 section
+
+서로 다른 목적의 콘텐츠를 하나의 큰 카드에 몰아넣지 않습니다. 제목·설명·action이 있는 `AdminSection` 또는 `db-section`으로 묶습니다. 접기 상태를 제공할 때에는 키보드로 열고 닫을 수 있어야 하며, 기본 상태는 콘텐츠 중요도에 따라 결정합니다.
+
+### 7.3 filter bar
+
+필터 바는 서버 query와 연결되는 명확한 상태를 가져야 합니다.
+
+- 검색어, 상태, 날짜, taxonomy 등 필터의 현재 값을 화면에 반영합니다.
+- `적용`과 `초기화`의 동작을 구분합니다.
+- 서버 페이지네이션을 사용할 때 필터가 변경되면 page를 1로 되돌립니다.
+- URL query에 상태를 반영하면 새로고침·뒤로가기·공유가 쉬워집니다.
+- 데이터 fetching은 filter bar 안이 아니라 화면 controller에서 수행합니다.
+
+### 7.4 data table
+
+단순한 표는 native `<table>`을 우선 사용합니다. 정렬·행 action·empty/loading/error가 반복되거나 React 데이터 모델을 사용하는 경우 `AdminDataTable` 또는 `db-table`을 사용합니다.
+
+- 열 제목을 `<th>`로 출력합니다.
+- 행 action은 명확한 accessible name을 사용합니다.
+- 정렬 방향은 텍스트나 `aria-sort`로 전달합니다.
+- 로딩 중 기존 데이터가 있으면 전체 레이아웃을 깜빡이지 않고 해당 영역만 busy로 표시합니다.
+- 데이터가 없을 때 빈 `<table>`만 보여주지 말고 `AdminEmptyState`를 제공합니다.
+- 삭제·상태 변경 action은 서버 응답이 성공한 뒤 목록을 갱신합니다.
+
+## 8. 상태 표현과 오류 처리
+
+화면 controller는 최소한 다음 상태를 구분합니다.
+
+| 상태 | 사용자에게 보여줄 것 | 권장 구현 |
+| --- | --- | --- |
+| loading | 작업 중임과 예상 영역 | `AdminLoadingState`, `db-spinner`, `db-skeleton` |
+| empty | 결과가 없다는 설명과 다음 action | `AdminEmptyState`, `db-empty-state` |
+| error | 문제와 재시도 방법 | `AdminErrorState`, `db-alert` |
+| success | 저장·삭제 완료 피드백 | toast + 변경된 영역 갱신 |
+| unauthorized | 권한 부족 안내 | 서버의 403/WordPress 권한 화면과 일치 |
+
+로딩 중인 영역에는 `aria-busy="true"`를 사용하고, 오류에는 `role="alert"` 또는 적절한 live region을 사용합니다. disabled 상태만으로 네트워크 요청을 표현하지 말고, 진행 상태도 함께 표시합니다.
+
+## 9. 보안 기준
+
+`wordpress-ui`는 보안 경계를 제공하지 않습니다. 다음 항목은 각 플러그인과 테마가 구현하고 검토해야 합니다.
+
+- 페이지 진입 시 capability를 확인합니다.
+- REST route마다 `permission_callback`을 정의합니다.
+- REST cookie 인증 요청에는 `X-WP-Nonce`를 사용합니다.
+- AJAX 요청에는 `check_ajax_referer()`를 사용합니다.
+- nonce를 인증·권한 검사의 대체 수단으로 사용하지 않습니다.
+- 입력은 용도에 맞게 sanitize하고, 허용 목록·범위·타입을 validate합니다.
+- 출력은 context에 맞게 `esc_html()`, `esc_attr()`, `esc_url()`, `wp_json_encode()` 등으로 escape합니다.
+- SQL은 `$wpdb->prepare()`를 사용하고, sort/order/column/table 값은 allowlist로 제한합니다.
+- 파일 경로·업로드·다운로드는 path traversal과 capability를 검증합니다.
+- `wp_localize_script()`에 secret, private token, 전체 사용자 데이터, 내부 경로를 넣지 않습니다.
+- 실패 응답에 SQL, 파일 시스템 경로, stack trace를 노출하지 않습니다.
+- 개인정보를 저장한다면 보존 기간, export/erase, privacy policy를 별도로 설계합니다.
+
+특히 프런트엔드에서 버튼을 숨기는 것만으로 권한을 처리하면 안 됩니다. 사용자가 직접 REST URL을 호출해도 서버가 401/403을 반환하도록 구현해야 합니다.
+
+## 10. 접근성·반응형·WordPress 호환성
+
+### 10.1 키보드와 focus
+
+- 모든 action을 키보드만으로 실행할 수 있어야 합니다.
+- focus indicator를 제거하지 않습니다.
+- modal이 열리면 focus가 modal 안으로 이동하고, 닫힌 뒤 트리거로 돌아와야 합니다.
+- Escape로 modal/drawer를 닫을 수 있어야 합니다.
+- sidebar toggle은 `aria-expanded`와 명확한 `aria-label`을 가집니다.
+- icon-only button은 visible label 또는 `aria-label`을 가집니다.
+
+### 10.2 반응형 기준
+
+최소한 다음 viewport에서 확인합니다.
+
+| viewport | 확인할 것 |
+| --- | --- |
+| 1280px | sidebar와 main content의 기본 밀도 |
+| 1024px | 좁은 admin content에서 header action과 table overflow |
+| 782px | WordPress 관리자 모바일 breakpoint, sidebar drawer |
+| 480px | filter action wrapping, table 대체 표현, 긴 제목 |
+
+페이지 전체에 `overflow-x: hidden`을 적용해 문제를 감추지 않습니다. 표가 넓으면 의미 있는 horizontal scroll container나 responsive row layout을 제공합니다.
+
+### 10.3 기타 기준
+
+- RTL에서 sidebar, icon, breadcrumb, back action의 방향을 확인합니다.
+- `prefers-reduced-motion: reduce`에서 불필요한 transition을 줄입니다.
+- WordPress color scheme을 전역으로 덮어쓰지 않습니다.
+- 패키지의 dark token을 명시적으로 사용하려는 경우 root에 `data-theme="dark"`를 설정합니다.
+
+```html
+<div class="wrap designbase-wp-admin" data-theme="dark">
+    <!-- 플러그인 내부 화면 -->
+</div>
+```
+
+- 현대 브라우저를 기준으로 하되, 핵심 form submit·link·native input 동작은 Web Component가 실패해도 사용할 수 있게 설계합니다.
+- IE11 전용 polyfill은 추가하지 않습니다.
+
+## 11. CSS 격리와 커스텀 스타일
+
+플러그인 고유 스타일도 같은 root 아래에 둡니다.
+
+```scss
+.designbase-wp-admin.myplugin-admin {
+    .myplugin-custom-card {
+        /* 플러그인 고유 스타일 */
+    }
+}
+```
+
+다음 패턴은 금지합니다.
+
+```scss
+/* 금지: WordPress와 다른 플러그인에 영향을 준다. */
+button { ... }
+table { ... }
+body { ... }
+#adminmenu { ... }
+```
+
+다음 현상이 있으면 먼저 root와 enqueue를 확인합니다.
+
+- input/select/button이 브라우저 기본 모양으로 보임: `styles.css`가 빠졌거나 root 밖에 렌더링된 경우가 많습니다.
+- 아이콘이 네모 또는 빈 공간으로 보임: font 파일 경로, CSS font-family, 배포 파일 누락을 확인합니다.
+- `db-*` element가 평범한 빈 element처럼 보임: `browser.iife.js`가 로드되지 않았거나 custom element 등록 전에 markup이 실행된 경우입니다.
+- WordPress 다른 화면까지 모양이 바뀜: root 밖의 전역 selector가 존재하는지 확인합니다.
+- sidebar 모바일 toggle이 작동하지 않음: `data-dbwp-sidebar-toggle` 대상 ID, browser runtime, `aria-expanded`를 확인합니다.
+
+## 12. 기존 플러그인과 테마 적용 순서
+
+기존 `dewp-*` 클래스나 이전 UI 라이브러리를 자동 치환하지 않습니다. 새 기준은 `wordpress-ui`이고, 화면 단위로 점진 적용합니다.
+
+1. 대상 화면의 `screen_id`와 필요한 capability를 기록합니다.
+2. 화면 root에 `.designbase-wp-admin`을 추가합니다.
+3. 해당 화면에만 `styles.css`와 `browser.iife.js`를 enqueue합니다.
+4. 기존 페이지 header/content 영역을 `AdminPageHeader` 또는 `db-page-header` 구조로 바꿉니다.
+5. 반복되는 section을 `AdminSection` 또는 `db-section`으로 정리합니다.
+6. 검색·필터 화면에 `AdminFilterBar` 또는 native-first filter markup을 적용합니다.
+7. 목록 화면에 `AdminDataTable` 또는 semantic native table을 적용합니다.
+8. loading·empty·error·success 상태를 분리합니다.
+9. modal, confirm, toast, drawer를 필요한 화면에만 추가합니다.
+10. REST·AJAX·Settings API·capability 동작은 UI migration 중 변경하지 않고 회귀 테스트합니다.
+
+새 플러그인은 처음부터 이 구조로 시작합니다. 기존 제품은 핵심 목록 화면 하나를 pilot으로 삼고, 시각·접근성·자산 로딩을 검증한 다음 나머지 화면으로 확장합니다.
+
+### 12.1 테마 관리자 적용 시 주의점
+
+테마 설정 화면도 플러그인과 같은 `wordpress-ui` public API를 사용합니다.
+
+- 테마 전용 admin page와 settings page만 allowlist에 포함합니다.
+- 프런트엔드 방문자 화면에는 `admin_enqueue_scripts` 자산을 로드하지 않습니다.
+- 부모/자식 테마 중 어느 쪽이 vendor와 build output을 소유하는지 정합니다.
+- 테마 변경이나 비활성화 시 설정 데이터의 생명주기를 UI migration과 섞지 않습니다.
+- WordPress 전역 Appearance 메뉴나 admin bar를 재설계하지 않습니다.
+
+## 13. 테스트 및 완료 기준
+
+### 13.1 라이브러리 쪽
+
+```bash
+npm run typecheck
+npm run build
+npm run verify
+npm run audit:axe
+npm run build-storybook
+```
+
+확인 항목:
+
+- 선택된 ui-wc 컴포넌트가 모두 등록되는가
+- `styles.css`에 theme token alias가 포함되는가
+- icon font와 font asset이 포함되는가
+- 모든 컴포넌트 스타일이 `.designbase-wp-admin` 아래로 scope되는가
+- React adapter가 optional peer dependency로 유지되는가
+- vanilla 예제가 React 없이 동작하는가
+- modal focus trap과 Escape가 동작하는가
+
+### 13.2 소비 플러그인/테마 쪽
+
+- 허용된 admin screen에서만 자산이 로드되는가
+- 실제 배포 zip에 CSS, JS, WOFF가 포함되는가
+- CDN 요청이 없는가
+- `#adminmenu`, `#wpadminbar`, 다른 notice에 CSS leakage가 없는가
+- REST 401/403과 nonce 만료가 올바르게 표시되는가
+- 권한이 낮은 사용자가 직접 endpoint를 호출해도 서버가 차단하는가
+- 1280px, 1024px, 782px, 480px에서 레이아웃이 유지되는가
+- 키보드 전용 사용, focus, Escape, reduced motion, RTL을 확인했는가
+- PHP lint, JS/TS typecheck, ESLint, build가 통과하는가
+- 업데이트 전후에 Settings API와 기존 데이터가 유지되는가
+
+간단한 수동 검수 순서는 다음과 같습니다.
+
+1. 관리자 화면의 Network에서 `styles.css`, `browser.iife.js`, font가 한 번씩만 로드되는지 확인합니다.
+2. 다른 WordPress 관리자 화면으로 이동해 스타일이 변하지 않는지 확인합니다.
+3. 낮은 capability 사용자로 페이지와 REST endpoint를 각각 확인합니다.
+4. 브라우저 zoom 200%와 키보드만으로 주요 flow를 실행합니다.
+5. 페이지 새로고침, 뒤로가기, 필터 초기화, 빈 결과, 서버 오류를 확인합니다.
+6. 최종 zip을 깨끗한 WordPress 설치에서 설치·활성화·업데이트합니다.
+
+## 14. 문제 해결 체크리스트
+
+### 컴포넌트가 못생긴 기본 HTML처럼 보이는 경우
+
+1. `styles.css`가 현재 screen에 enqueue되었는지 확인합니다.
+2. HTML 최상위에 `.designbase-wp-admin`이 있는지 확인합니다.
+3. 별도의 `theme.css`를 누락한 문제가 아니라, 배포된 `wordpress-ui/dist/styles.css`를 사용하고 있는지 확인합니다.
+4. custom CSS가 `button`, `input`, `select`를 덮어쓰지 않는지 확인합니다.
+5. 패키지 버전과 vendor dist가 서로 다른 버전이 아닌지 확인합니다.
+
+### 아이콘이 안 보이는 경우
+
+1. `icons.woff2`와 `icons.woff`가 함께 배포되었는지 확인합니다.
+2. CSS의 relative URL 기준이 `dist/styles.css` 위치와 일치하는지 확인합니다.
+3. 아이콘 class가 `icon-dashboard`처럼 유효한 이름인지 확인합니다.
+4. `font-family`를 WordPress Dashicons나 다른 플러그인이 덮어쓰지 않는지 확인합니다.
+
+### `db-*` element가 작동하지 않는 경우
+
+1. `browser.iife.js`가 200으로 응답하는지 확인합니다.
+2. 플러그인 script의 dependency가 `myplugin-wordpress-ui-browser`인지 확인합니다.
+3. 콘솔에 custom element 등록 오류가 없는지 확인합니다.
+4. React entry를 vanilla HTML에 enqueue하고 있지 않은지 확인합니다.
+5. 필요한 attribute/property가 해당 component 계약과 맞는지 확인합니다.
+
+### REST 요청이 401/403인 경우
+
+1. `wp_localize_script()`가 실행되었고 object 이름이 JS와 일치하는지 확인합니다.
+2. `X-WP-Nonce` header가 전송되는지 확인합니다.
+3. 현재 사용자의 capability가 route의 `permission_callback`과 일치하는지 확인합니다.
+4. nonce action이 `wp_create_nonce('wp_rest')`와 REST cookie 인증 흐름에 맞는지 확인합니다.
+5. endpoint URL에 namespace와 trailing path가 중복되지 않았는지 확인합니다.
+
+## 15. 팀에서 지켜야 할 API 사용 규칙
+
+```ts
+// 허용
+import '@designbasekorea/wordpress-ui/browser';
+import '@designbasekorea/wordpress-ui/styles.css';
+
+// React 화면에서만 허용
+import { AdminShell, AdminDataTable } from '@designbasekorea/wordpress-ui/react';
+
+// 금지: 소비 플러그인/테마에서 직접 import하지 않는다.
+import '@designbasekorea/ui-wc';
+import { DbButton } from '@designbasekorea/ui-wc/components/db-button';
+```
+
+직접 `ui-wc`를 사용하면 관리자용 token scope, 아이콘 경로, 등록 allowlist, CSS 격리 정책이 패키지 밖으로 새어 나갑니다. 공통 요구사항이 생기면 소비자에서 임시로 우회하지 말고 `wordpress-ui`의 공개 API로 승격할지 먼저 검토합니다.
+
+## 16. 공식 참고 문서
+
+- [WordPress Plugin Handbook](https://developer.wordpress.org/plugins/)
+- [`admin_enqueue_scripts`](https://developer.wordpress.org/reference/hooks/admin_enqueue_scripts/)
+- [Settings API](https://developer.wordpress.org/plugins/settings/)
+- [WordPress REST API](https://developer.wordpress.org/rest-api/)
+- [WordPress API Security](https://developer.wordpress.org/apis/security/)
+- [Nonces](https://developer.wordpress.org/apis/security/nonces/)
+- [Checking User Capabilities](https://developer.wordpress.org/apis/security/checking-user-capabilities/)
+- [Sanitizing Data](https://developer.wordpress.org/apis/security/sanitizing/)
+- [Escaping Data](https://developer.wordpress.org/apis/security/escaping/)
+- [`@wordpress/components`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-components/)
+
+`@wordpress/components`는 WordPress React runtime과 결합된 선택적 adapter로 검토할 수 있지만, vanilla/PHP 플러그인과 테마의 공통 기반으로 추가하지 않습니다. 이 가이드의 기본 기반은 `wordpress-ui`의 React-free browser runtime입니다.