@designbasekorea/wordpress-ui 0.1.2 → 0.1.4

package/docs/WORDPRESS-ADMIN-GUIDE.md

@@ -2,6 +2,10 @@
 
 이 문서는 `@designbasekorea/wordpress-ui`를 WordPress 플러그인과 테마의 관리자 화면에 적용하는 표준 가이드입니다.
 
+이 가이드의 기준 배포 버전은 `0.1.4`입니다. 플러그인 또는 테마의 lockfile과
+vendor 산출물도 같은 버전으로 맞추고, 버전을 올릴 때마다 아래 검증 명령을 다시
+실행합니다.
+
 이 패키지는 `@designbasekorea/ui-wc`를 내부 구현으로 사용하지만, 소비자는 `ui-wc`를 직접 import하지 않습니다. 소비자 코드는 항상 `wordpress-ui`의 공개 진입점과 배포된 자산만 사용합니다.
 
 현재 패키지는 다음 원칙을 따릅니다.
@@ -58,7 +62,7 @@ WordPress plugin/theme
 ### 2.1 Node 프로젝트에 설치
 
 ```bash
-npm install @designbasekorea/wordpress-ui
+npm install @designbasekorea/wordpress-ui@0.1.4
 ```
 
 WordPress 서버가 npm을 실행하는 것이 아닙니다. 라이브러리를 설치한 뒤 플러그인 또는 테마 빌드 과정에서 배포에 필요한 파일을 포함해야 합니다.
@@ -139,7 +143,7 @@ require_once __DIR__ . '/vendor/wordpress-ui/wordpress-ui.php';
 
 final class MyPlugin_Admin_Assets
 {
-    private const UI_VERSION = '0.1.0';
+    private const UI_VERSION = '0.1.4';
 
     public static function init(): void
     {
@@ -262,58 +266,99 @@ 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 기본 컴포넌트 사용
 
 `browser` entry를 로드하면 `wordpress-ui`가 관리자 화면에 필요한 ui-wc element를 등록합니다.
 
+TypeScript 번들에서 Web Component 클래스를 직접 참조해야 할 때는 `ui-wc`가 아니라
+`@designbasekorea/wordpress-ui/components`를 import합니다. 이 entry가 `wordpress-ui`의
+등록 allowlist와 같은 컴포넌트 집합을 사용하므로, 소비 플러그인과 테마가 ui-wc의 내부
+경로·등록 정책·아이콘 경로에 결합되지 않습니다.
+
+짧은 import를 선호하면 동일한 named export를 패키지 루트에서 가져올 수도 있습니다.
+`components`와 루트는 같은 Web Component 클래스를 가리키며, HTML/PHP 화면은 여전히
+`browser` entry로 등록 runtime을 enqueue해야 합니다.
+
+```ts
+import { DbButton, DbInput, DbSelect, DbModal } from '@designbasekorea/wordpress-ui';
+```
+
 ```html
 <form class="myplugin-filter-form" data-myplugin-filter-form>
     <db-search-bar
@@ -394,7 +439,7 @@ select?.addEventListener('db-change', (event) => {
 React는 선택 사항입니다. Gutenberg나 기존 React 앱과 연결해야 하는 화면에서만 사용하고, 일반적인 PHP admin page에는 vanilla entry를 권장합니다.
 
 ```bash
-npm install @designbasekorea/wordpress-ui react react-dom
+npm install @designbasekorea/wordpress-ui@0.1.4 react react-dom
 ```
 
 ```tsx
@@ -866,13 +911,15 @@ import '@designbasekorea/wordpress-ui/styles.css';
 
 // React 화면에서만 허용
 import { AdminShell, AdminDataTable } from '@designbasekorea/wordpress-ui/react';
+import { DbButton, DbInput, DbSelect, DbModal } from '@designbasekorea/wordpress-ui/components';
+// 또는: import { DbButton, DbInput, DbSelect, DbModal } from '@designbasekorea/wordpress-ui';
 
-// 금지: 소비 플러그인/테마에서 직접 import하지 않는다.
-import '@designbasekorea/ui-wc';
-import { DbButton } from '@designbasekorea/ui-wc/components/db-button';
+// 금지: 소비 플러그인/테마에서 @designbasekorea/ui-wc 내부 경로를 직접 import하지 않는다.
 ```
 
-직접 `ui-wc`를 사용하면 관리자용 token scope, 아이콘 경로, 등록 allowlist, CSS 격리 정책이 패키지 밖으로 새어 나갑니다. 공통 요구사항이 생기면 소비자에서 임시로 우회하지 말고 `wordpress-ui`의 공개 API로 승격할지 먼저 검토합니다.
+`wordpress-ui/components`는 내부적으로 `ui-wc`를 사용하지만, 관리자용 token scope, 아이콘
+경로, 등록 allowlist, CSS 격리 정책은 `wordpress-ui`가 소유합니다. 공통 요구사항이 생기면
+소비자에서 임시로 우회하지 말고 `wordpress-ui`의 공개 API로 승격할지 먼저 검토합니다.
 
 ## 16. 공식 참고 문서
 

package/examples/vanilla.html

@@ -21,7 +21,7 @@
                 </div>
             </aside>
             <main class="designbase-wp-admin__shell-main">
-                <button
+                        <button
                     class="designbase-wp-admin__shell-menu-toggle"
                     type="button"
                     data-sidebar-toggle="example-sidebar"
@@ -34,21 +34,16 @@
                         description="REST와 권한 상태는 소비자가 소유하고 UI는 상태만 표현합니다."
                         variant="minimal"
                     >
-                        <button slot="actions" class="button button-primary" type="button">새 페이지</button>
+                        <db-button slot="actions" variant="primary" size="s" start-icon="plus" type="button">새 페이지</db-button>
                     </db-page-header>
 
                     <db-alert variant="info" title="wordpress-ui 예제" message="ui-wc primitives와 관리자 패턴은 이 root 안에서만 동작합니다." closable="false"></db-alert>
 
                     <form class="designbase-wp-admin__filter-bar" role="search">
                         <div class="designbase-wp-admin__filter-bar__fields">
-                            <label>검색 <input class="" type="search" placeholder="페이지 검색"></label>
-                            <label>상태
-                                <select class="">
-                                    <option>전체 상태</option>
-                                    <option>공개</option>
-                                    <option>초안</option>
-                                </select>
-                            </label>
+                            <db-input type="search" size="s" name="search" placeholder="페이지 검색" aria-label="검색"></db-input>
+                            <db-select size="s" name="status" aria-label="상태" value="all"
+                                options='[{"value":"all","label":"전체 상태"},{"value":"published","label":"공개"},{"value":"draft","label":"초안"}]'></db-select>
                         </div>
                         <div class="designbase-wp-admin__filter-bar__actions">
                             <button class="button button-secondary" type="reset">초기화</button>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@designbasekorea/wordpress-ui",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "WordPress 관리자용 Designbase UI primitives와 plugin shell patterns",
   "type": "module",
   "main": "dist/index.cjs",
@@ -19,6 +19,18 @@
       "require": "./dist/browser.cjs",
       "default": "./dist/browser.esm.js"
     },
+    "./components": {
+      "types": "./dist/components.d.ts",
+      "import": "./dist/components.esm.js",
+      "require": "./dist/components.cjs",
+      "default": "./dist/components.esm.js"
+    },
+    "./primitives": {
+      "types": "./dist/components.d.ts",
+      "import": "./dist/components.esm.js",
+      "require": "./dist/components.cjs",
+      "default": "./dist/components.esm.js"
+    },
     "./react": {
       "types": "./dist/react/index.d.ts",
       "import": "./dist/react/index.esm.js",
@@ -33,7 +45,10 @@
   },
   "sideEffects": [
     "*.css",
+    "./dist/components.esm.js",
+    "./dist/components.cjs",
     "./dist/browser.esm.js",
+    "./dist/browser.cjs",
     "./dist/react/index.esm.js"
   ],
   "files": [