@designbasekorea/wordpress-ui 0.1.5 → 0.1.6

package/docs/WORDPRESS-ADMIN-GUIDE.md

@@ -2,7 +2,8 @@
 
 이 문서는 `@designbasekorea/wordpress-ui`를 WordPress 플러그인과 테마의 관리자 화면에 적용하는 표준 가이드입니다.
 
-이 가이드의 기준 배포 버전은 `0.1.5`입니다. 플러그인 또는 테마의 lockfile과
+이 가이드의 기준 배포 버전은 `0.1.6`입니다. `@designbasekorea/ui-wc@0.8.7`과
+같은 세트를 사용하세요. 플러그인 또는 테마의 lockfile과
 vendor 산출물도 같은 버전으로 맞추고, 버전을 올릴 때마다 아래 검증 명령을 다시
 실행합니다.
 
@@ -39,7 +40,7 @@ WordPress plugin/theme
 
 ### 1.1 WordPress 전역 관리자와 플러그인 내부 shell의 경계
 
-`AdminShell`과 `AdminSidebar`는 플러그인 또는 테마 내부 화면을 위한 것입니다. 다음 전역 요소는 수정하지 않습니다.
+`db-admin-shell`과 React `AdminShell`은 플러그인 또는 테마 **내부 화면**을 위한 것입니다. 다음 전역 요소는 수정하지 않습니다.
 
 - `#adminmenu`
 - `#wpadminbar`
@@ -62,7 +63,7 @@ WordPress plugin/theme
 ### 2.1 Node 프로젝트에 설치
 
 ```bash
-npm install @designbasekorea/wordpress-ui@0.1.5
+npm install @designbasekorea/wordpress-ui@0.1.6
 ```
 
 WordPress 서버가 npm을 실행하는 것이 아닙니다. 라이브러리를 설치한 뒤 플러그인 또는 테마 빌드 과정에서 배포에 필요한 파일을 포함해야 합니다.
@@ -143,7 +144,7 @@ require_once __DIR__ . '/vendor/wordpress-ui/wordpress-ui.php';
 
 final class MyPlugin_Admin_Assets
 {
-    private const UI_VERSION = '0.1.5';
+    private const UI_VERSION = '0.1.6';
 
     public static function init(): void
     {
@@ -267,15 +268,16 @@ WordPress 플러그인과 테마의 기본 선택지는 vanilla/PHP입니다. Re
 ### 4.1 페이지 기본 구조
 
 PHP 템플릿은 `.designbase-wp-admin` root 안에서 `db-admin-shell`을 선언하는 방식을
-권장합니다. 이 Web Component가 실제 `db-sidebar`, 플러그인명 브랜드,
+권장합니다. 이 Web Component가 실제 `db-sidebar`, 플러그인명 로고,
 `db-page-header`, 콘텐츠용 `<db-container size="full" padding="l" full-width>`를
-하나의 패턴으로 렌더링합니다. 기존 템플릿을 단계적으로 이전하는 동안에는 화면별
-adapter가 같은 `db-admin-shell`을 생성하도록 사용할 수 있습니다.
+하나의 패턴으로 렌더링합니다.
 
-`sections`/`items`는 PHP에서 `wp_json_encode()`로 전달하고, 링크·권한·활성 상태는
-소비 플러그인이나 테마가 관리합니다. 일반적인 화면은 아래처럼 `db-admin-shell` 하나를
-선언하면 됩니다. 직접 자식 `db-page-header`는 헤더로 유지되고, 나머지 자식은 shell이
-`db-container` 안으로 이동합니다.
+`title`(또는 `brand`)은 사이드바 **헤더 로고**입니다. 메뉴는 `items` JSON으로 넘기고,
+링크·권한·활성 상태는 소비 플러그인이나 테마가 계산합니다. 메뉴를 실제 그룹으로 나눌
+때만 `sections`를 쓰고, 그룹 제목에 플러그인명을 넣지 않습니다.
+
+직접 자식 `db-page-header`는 헤더로 유지되고, 나머지 자식은 shell이 `db-container`
+안으로 이동합니다.
 
 ```php
 <?php
@@ -284,7 +286,7 @@ $sidebar_items = [
         'id' => 'dashboard',
         'label' => __('대시보드', 'myplugin'),
         'href' => admin_url('admin.php?page=myplugin'),
-        'icon' => 'doughnut-chart',
+        'icon' => 'dashboard',
         'active' => (($_GET['page'] ?? '') === 'myplugin'),
     ],
     [
@@ -299,21 +301,15 @@ $sidebar_items = [
 <div class="wrap designbase-wp-admin myplugin-admin">
     <db-admin-shell
         title="My Plugin"
-        sections='<?php echo esc_attr(wp_json_encode([[
-            'id' => 'main',
-            'title' => 'My Plugin',
-            'items' => $sidebar_items,
-        ]])); ?>'>
+        items="<?php echo esc_attr(wp_json_encode($sidebar_items)); ?>"
+    >
         <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>
+            variant="minimal">
+            <a slot="actions" class="button button-secondary" href="<?php echo esc_url(admin_url('admin.php?page=myplugin-settings')); ?>">
+                <?php esc_html_e('설정', 'myplugin'); ?>
+            </a>
         </db-page-header>
 
         <db-section title="<?php esc_attr_e('콘텐츠', 'myplugin'); ?>">
@@ -409,10 +405,10 @@ select?.addEventListener('db-change', (event) => {
 아이콘은 이모지나 임의의 유니코드 문자를 사용하지 않고 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>
+<i class="icon-dashboard" aria-hidden="true"></i>
+<i class="icon-file-manager" aria-hidden="true"></i>
+<i class="icon-search" aria-hidden="true"></i>
+<i class="icon-settings" aria-hidden="true"></i>
 ```
 
 `styles.css`가 아이콘 폰트와 `@font-face` 규칙을 포함합니다. 아이콘이 보이지 않으면 다음을 확인합니다.
@@ -427,20 +423,21 @@ select?.addEventListener('db-change', (event) => {
 React는 선택 사항입니다. Gutenberg나 기존 React 앱과 연결해야 하는 화면에서만 사용하고, 일반적인 PHP admin page에는 vanilla entry를 권장합니다.
 
 ```bash
-npm install @designbasekorea/wordpress-ui@0.1.5 react react-dom
+npm install @designbasekorea/wordpress-ui@0.1.6 react react-dom
 ```
 
 ```tsx
 import '@designbasekorea/wordpress-ui/styles.css';
 import {
-    AdminDataTable,
-    AdminEmptyState,
-    AdminFilterBar,
     AdminPage,
     AdminPageContent,
     AdminPageHeader,
-    AdminSection,
     AdminShell,
+    Button,
+    SearchBar,
+    Section,
+    Select,
+    Table,
     type AdminNavItem,
 } from '@designbasekorea/wordpress-ui/react';
 
@@ -451,59 +448,61 @@ const sidebarItems: AdminNavItem[] = [
 
 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>
+        <AdminShell sidebarItems={sidebarItems} sidebarTitle="My Plugin">
+            <AdminPageHeader
+                title="콘텐츠 관리"
+                description="콘텐츠를 검색하고 상태를 관리합니다."
+                actions={<Button variant="primary" size="s">새 페이지</Button>}
+            />
+            <AdminPage>
+                <AdminPageContent>
+                    <Section title="검색 및 필터">
+                        <form
+                            className="designbase-wp-admin__filter-bar"
+                            role="search"
+                            onSubmit={(event) => {
+                                event.preventDefault();
+                                // REST 또는 URL query 변경은 소비 앱이 담당한다.
+                            }}
+                        >
+                            <div className="designbase-wp-admin__filter-bar-toolbar">
+                                <SearchBar name="search" placeholder="제목 검색" aria-label="제목 검색" />
+                                <Select
+                                    name="status"
+                                    aria-label="상태"
+                                    options={JSON.stringify([
+                                        { value: 'all', label: '전체 상태' },
+                                        { value: 'published', label: '공개' },
+                                        { value: 'draft', label: '임시글' },
+                                    ])}
+                                />
+                            </div>
+                        </form>
+                    </Section>
+                    <Section title="목록" fullWidth>
+                        <Table
+                            columns={JSON.stringify([
+                                { key: 'title', header: '제목', sortable: true },
+                                { key: 'status', header: '상태' },
+                            ])}
+                            data={JSON.stringify([])}
+                            rowKey="id"
+                            emptyMessage="콘텐츠가 없습니다."
+                        />
+                    </Section>
+                </AdminPageContent>
+            </AdminPage>
+        </AdminShell>
     );
 }
 ```
 
-React adapter의 책임은 관리자 shell과 컴포넌트 조합입니다.
+React adapter의 책임은 관리자 shell과 ui-wc primitives 조합입니다.
 
-- `AdminShell`: 내부 sidebar와 main layout
-- `AdminSidebar`: 메뉴, active 상태, badge, 모바일 close
+- `AdminShell`: `sidebarTitle`(사이드바 로고)과 `sidebarItems`(메뉴). 내부에서 `.designbase-wp-admin` root를 만듭니다.
 - `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`: 상태 화면
+- `AdminPageHeader`: title, description, breadcrumb, action. 모바일에서는 메뉴 버튼을 붙입니다.
+- `Section`, `Table`, `SearchBar`, `Select`, `Tabs`, `EmptyState`, `Modal` 등: 같은 패키지의 React primitives. `AdminSection` / `AdminDataTable` / `AdminFilterBar` 같은 별도 래퍼는 없습니다.
 
 이 컴포넌트들은 REST 요청, 페이지네이션 API, nonce 갱신, capability 검사를 대신하지 않습니다. React state와 서버 데이터의 생명주기는 플러그인/테마 앱이 소유합니다.
 
@@ -638,14 +637,14 @@ register_setting('myplugin', 'myplugin_options', [
 ```text
 .designbase-wp-admin
 └─ AdminShell 또는 db-admin-shell
-   ├─ AdminSidebar 또는 plugin 내부 nav
+   ├─ db-sidebar (title/sidebarTitle = 플러그인명 로고, items = 메뉴)
    └─ main
       ├─ AdminPageHeader / db-page-header
-      ├─ AdminTabs / db-tabs (필요한 경우)
+      ├─ Tabs / db-tabs (필요한 경우)
       └─ AdminPageContent
-         ├─ AdminSection / db-section
-         ├─ AdminFilterBar
-         └─ AdminDataTable 또는 native table
+         ├─ Section / db-section
+         ├─ form.designbase-wp-admin__filter-bar
+         └─ Table / db-table 또는 native table
 ```
 
 ### 7.1 페이지 헤더
@@ -660,7 +659,7 @@ register_setting('myplugin', 'myplugin_options', [
 
 ### 7.2 section
 
-서로 다른 목적의 콘텐츠를 하나의 큰 카드에 몰아넣지 않습니다. 제목·설명·action이 있는 `AdminSection` 또는 `db-section`으로 묶습니다. 접기 상태를 제공할 때에는 키보드로 열고 닫을 수 있어야 하며, 기본 상태는 콘텐츠 중요도에 따라 결정합니다.
+서로 다른 목적의 콘텐츠를 하나의 큰 카드에 몰아넣지 않습니다. 제목·설명·action이 있는 `Section` 또는 `db-section`으로 묶습니다. 접기 상태를 제공할 때에는 키보드로 열고 닫을 수 있어야 하며, 기본 상태는 콘텐츠 중요도에 따라 결정합니다.
 
 ### 7.3 filter bar
 
@@ -674,13 +673,13 @@ register_setting('myplugin', 'myplugin_options', [
 
 ### 7.4 data table
 
-단순한 표는 native `<table>`을 우선 사용합니다. 정렬·행 action·empty/loading/error가 반복되거나 React 데이터 모델을 사용하는 경우 `AdminDataTable` 또는 `db-table`을 사용합니다.
+단순한 표는 native `<table>`을 우선 사용합니다. 정렬·행 action·empty/loading/error가 반복되거나 React 데이터 모델을 사용하는 경우 `Table` 또는 `db-table`을 사용합니다.
 
 - 열 제목을 `<th>`로 출력합니다.
 - 행 action은 명확한 accessible name을 사용합니다.
 - 정렬 방향은 텍스트나 `aria-sort`로 전달합니다.
 - 로딩 중 기존 데이터가 있으면 전체 레이아웃을 깜빡이지 않고 해당 영역만 busy로 표시합니다.
-- 데이터가 없을 때 빈 `<table>`만 보여주지 말고 `AdminEmptyState`를 제공합니다.
+- 데이터가 없을 때 빈 `<table>`만 보여주지 말고 `empty-message` 또는 `EmptyState` / `db-empty-state`를 제공합니다.
 - 삭제·상태 변경 action은 서버 응답이 성공한 뒤 목록을 갱신합니다.
 
 ## 8. 상태 표현과 오류 처리
@@ -689,9 +688,9 @@ register_setting('myplugin', 'myplugin_options', [
 
 | 상태 | 사용자에게 보여줄 것 | 권장 구현 |
 | --- | --- | --- |
-| loading | 작업 중임과 예상 영역 | `AdminLoadingState`, `db-spinner`, `db-skeleton` |
-| empty | 결과가 없다는 설명과 다음 action | `AdminEmptyState`, `db-empty-state` |
-| error | 문제와 재시도 방법 | `AdminErrorState`, `db-alert` |
+| loading | 작업 중임과 예상 영역 | `Spinner` / `db-spinner`, `Skeleton` / `db-skeleton` |
+| empty | 결과가 없다는 설명과 다음 action | `EmptyState` / `db-empty-state`, `db-table`의 `empty-message` |
+| error | 문제와 재시도 방법 | `Alert` / `db-alert` |
 | success | 저장·삭제 완료 피드백 | toast + 변경된 영역 갱신 |
 | unauthorized | 권한 부족 안내 | 서버의 403/WordPress 권한 화면과 일치 |
 
@@ -794,9 +793,9 @@ body { ... }
 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을 적용합니다.
+5. 반복되는 section을 `Section` 또는 `db-section`으로 정리합니다.
+6. 검색·필터 화면에 `form.designbase-wp-admin__filter-bar`와 `SearchBar`/`db-search-bar`를 적용합니다.
+7. 목록 화면에 `Table`/`db-table` 또는 semantic native table을 적용합니다.
 8. loading·empty·error·success 상태를 분리합니다.
 9. modal, confirm, toast, drawer를 필요한 화면에만 추가합니다.
 10. REST·AJAX·Settings API·capability 동작은 UI migration 중 변경하지 않고 회귀 테스트합니다.
@@ -898,7 +897,7 @@ import '@designbasekorea/wordpress-ui/browser';
 import '@designbasekorea/wordpress-ui/styles.css';
 
 // React 화면에서만 허용
-import { AdminShell, AdminDataTable } from '@designbasekorea/wordpress-ui/react';
+import { AdminShell, Table } from '@designbasekorea/wordpress-ui/react';
 import { DbButton, DbInput, DbSelect, DbModal } from '@designbasekorea/wordpress-ui/components';
 // 또는: import { DbButton, DbInput, DbSelect, DbModal } from '@designbasekorea/wordpress-ui';
 

package/examples/vanilla.html

@@ -11,7 +11,7 @@
         <db-admin-shell
             id="wordpress-ui-example-shell"
             title="PageNest"
-            sections='[{"id":"main","title":"PageNest","items":[{"id":"dashboard","label":"대시보드","href":"#dashboard","icon":"dashboard","active":true},{"id":"pages","label":"페이지 목록","href":"#pages","icon":"file-manager","badge":12},{"id":"settings","label":"설정","href":"#settings","icon":"settings"}]}]'
+            items='[{"id":"dashboard","label":"대시보드","href":"#dashboard","icon":"dashboard","active":true},{"id":"pages","label":"페이지 목록","href":"#pages","icon":"file-manager","badge":12},{"id":"settings","label":"설정","href":"#settings","icon":"settings"}]'
         >
             <db-page-header
                 title="페이지 목록"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@designbasekorea/wordpress-ui",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "WordPress 관리자용 Designbase UI primitives와 plugin shell patterns",
   "type": "module",
   "main": "dist/index.cjs",
@@ -74,7 +74,7 @@
         "build-storybook": "storybook build"
     },
   "dependencies": {
-    "@designbasekorea/ui-wc": "0.8.6"
+    "@designbasekorea/ui-wc": "0.8.7"
   },
   "peerDependencies": {
     "react": ">=18.0.0 <20.0.0",