@designbasekorea/wordpress-ui 0.1.3 → 0.1.4

package/docs/WORDPRESS-ADMIN-GUIDE.md

@@ -2,7 +2,7 @@
 
 이 문서는 `@designbasekorea/wordpress-ui`를 WordPress 플러그인과 테마의 관리자 화면에 적용하는 표준 가이드입니다.
 
-이 가이드의 기준 배포 버전은 `0.1.2`입니다. 플러그인 또는 테마의 lockfile과
+이 가이드의 기준 배포 버전은 `0.1.4`입니다. 플러그인 또는 테마의 lockfile과
 vendor 산출물도 같은 버전으로 맞추고, 버전을 올릴 때마다 아래 검증 명령을 다시
 실행합니다.
 
@@ -62,7 +62,7 @@ WordPress plugin/theme
 ### 2.1 Node 프로젝트에 설치
 
 ```bash
-npm install @designbasekorea/wordpress-ui@0.1.2
+npm install @designbasekorea/wordpress-ui@0.1.4
 ```
 
 WordPress 서버가 npm을 실행하는 것이 아닙니다. 라이브러리를 설치한 뒤 플러그인 또는 테마 빌드 과정에서 배포에 필요한 파일을 포함해야 합니다.
@@ -143,7 +143,7 @@ require_once __DIR__ . '/vendor/wordpress-ui/wordpress-ui.php';
 
 final class MyPlugin_Admin_Assets
 {
-    private const UI_VERSION = '0.1.2';
+    private const UI_VERSION = '0.1.4';
 
     public static function init(): void
     {
@@ -266,52 +266,80 @@ WordPress 플러그인과 테마의 기본 선택지는 vanilla/PHP입니다. Re
 
 ### 4.1 페이지 기본 구조
 
+PHP 템플릿은 `.designbase-wp-admin` root와 `db-page-header`만 선언하고, 화면별
+AssetsManager가 `wordpress-ui` runtime과 shell adapter를 enqueue하는 방식을 권장합니다.
+adapter는 `ui-wc`의 실제 `db-sidebar`를 생성하고, 설정의 `title`을 사이드바 상단
+플러그인명으로 표시합니다. `db-page-header`를 제외한 root children은 자동으로
+`<db-container size="full" padding="l" full-width>` 안에 배치됩니다.
+
+`sections`/`items`는 PHP에서 `wp_json_encode()`로 전달하고, 링크·권한·활성 상태는
+소비 플러그인이나 테마가 관리합니다. adapter를 사용하지 않는 수동 구성에서는 아래처럼
+`db-sidebar`와 `db-container`를 직접 선언할 수 있습니다.
+
 ```php
+<?php
+$sidebar_items = [
+    [
+        'id' => 'dashboard',
+        'label' => __('대시보드', 'myplugin'),
+        'href' => admin_url('admin.php?page=myplugin'),
+        'icon' => 'doughnut-chart',
+        'active' => (($_GET['page'] ?? '') === 'myplugin'),
+    ],
+    [
+        'id' => 'settings',
+        'label' => __('설정', 'myplugin'),
+        'href' => admin_url('admin.php?page=myplugin-settings'),
+        'icon' => 'settings',
+        'active' => (($_GET['page'] ?? '') === 'myplugin-settings'),
+    ],
+];
+?>
 <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 class="designbase-wp-admin__shell designbase-wp-admin__shell--has-sidebar">
+        <aside class="designbase-wp-admin__shell-sidebar" aria-label="<?php esc_attr_e('My Plugin 메뉴', 'myplugin'); ?>">
+            <div class="designbase-wp-admin__shell-brand">
+                <db-logo type="custom" text="My Plugin" size="s"></db-logo>
             </div>
+            <db-sidebar
+                size="m"
+                show-logo="false"
+                collapsible="false"
+                full-height
+                sections='<?php echo esc_attr(wp_json_encode([[
+                    'id' => 'main',
+                    'title' => 'My Plugin',
+                    'items' => $sidebar_items,
+                ]])); ?>'>
+            </db-sidebar>
         </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">
+        <main class="designbase-wp-admin__shell-main" id="main-content">
+            <db-page-header
+                title="<?php esc_attr_e('대시보드', 'myplugin'); ?>"
+                description="<?php esc_attr_e('플러그인 상태와 최근 작업을 확인합니다.', 'myplugin'); ?>"
+                variant="minimal"
+                align="left">
+                <div slot="actions">
                     <a class="button button-secondary" href="<?php echo esc_url(admin_url('admin.php?page=myplugin-settings')); ?>">
-                        설정
+                        <?php esc_html_e('설정', 'myplugin'); ?>
                     </a>
                 </div>
-            </header>
+            </db-page-header>
 
-            <div class="dbwp-admin-page-content">
-                <!-- tabs, filter, section, table 등을 배치한다. -->
-            </div>
+            <db-container size="full" padding="l" full-width>
+                <!-- db-tabs, db-section, db-table 등을 배치한다. -->
+            </db-container>
         </main>
     </div>
 </div>
 ```
 
+기존 화면을 일괄 재작성하기 어려운 경우에는 동일한 `.designbase-wp-admin` root와
+`db-page-header`를 유지하고, 소비 플러그인의 작은 vanilla adapter에서 root children을
+`designbase-wp-admin__shell`로 감싼 뒤 `db-sidebar`를 생성해도 됩니다. 이 adapter는
+패키지의 Web Component runtime을 대체하지 않으며, 화면별 메뉴 설정만 담당합니다.
+
 컴포넌트 스타일을 사용하는 자체 markup은 `.designbase-wp-admin` 내부에 둡니다. 단순한 링크와 form submit은 WordPress의 native `<a>`와 `<button>`을 우선 사용하고, 복합 동작이 필요한 경우에만 Web Component를 사용합니다.
 
 ### 4.2 ui-wc 기본 컴포넌트 사용
@@ -411,7 +439,7 @@ select?.addEventListener('db-change', (event) => {
 React는 선택 사항입니다. Gutenberg나 기존 React 앱과 연결해야 하는 화면에서만 사용하고, 일반적인 PHP admin page에는 vanilla entry를 권장합니다.
 
 ```bash
-npm install @designbasekorea/wordpress-ui@0.1.2 react react-dom
+npm install @designbasekorea/wordpress-ui@0.1.4 react react-dom
 ```
 
 ```tsx

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@designbasekorea/wordpress-ui",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "WordPress 관리자용 Designbase UI primitives와 plugin shell patterns",
   "type": "module",
   "main": "dist/index.cjs",