@designbasekorea/wordpress-ui 0.1.5 → 0.1.6

package/README.md

@@ -1,174 +1,204 @@
 # @designbasekorea/wordpress-ui
 
-WordPress 관리자 플러그인 화면을 위한 Designbase façade/adaptor 패키지입니다.
-WordPress 전체 관리자 프레임을 대체하지 않고, 플러그인 내부의 shell과 반복되는
-페이지 패턴만 제공합니다.
+WordPress 플러그인·테마 **관리자 화면 안**에서 Designbase UI를 쓰기 위한 패키지입니다.
+WordPress 전역 프레임(`#adminmenu`, `#wpadminbar`, 다른 플러그인 화면)은 바꾸지 않습니다.
 
-## 사용
+- 기본 런타임은 React 없는 Web Component입니다.
+- REST·AJAX·Settings API·capability·nonce·데이터는 소비 플러그인이 소유합니다.
+- `@designbasekorea/ui-wc`를 직접 import하지 마세요. 공개 API는 이 패키지입니다.
 
-현재 배포 기준 버전은 `0.1.5`입니다. Node 프로젝트에 다음처럼 설치합니다.
+현재 배포 버전은 `0.1.6`입니다. `@designbasekorea/ui-wc@0.8.7`에 의존합니다.
+
+## 설치
 
 ```bash
-npm install @designbasekorea/wordpress-ui@0.1.5
+npm install @designbasekorea/wordpress-ui@0.1.6
 ```
 
-Vanilla/PHP 플러그인은 필요한 화면에서만 다음 자산을 enqueue합니다.
+WordPress 서버가 npm을 실행하는 것은 아닙니다. 설치한 뒤 `dist/`와 `wordpress-ui.php`를 플러그인/테마 vendor에 포함하고, 해당 관리자 화면에만 enqueue합니다.
 
-```ts
-import '@designbasekorea/wordpress-ui/browser';
-import '@designbasekorea/wordpress-ui/styles.css';
-```
+## 화면 구조
 
-React 플러그인은 React를 peer dependency로 유지하며 다음처럼 사용합니다.
+모든 화면은 `.wrap.designbase-wp-admin` 안에서만 렌더링합니다. 스타일은 이 root 아래로 scope됩니다.
 
-```tsx
-import '@designbasekorea/wordpress-ui/styles.css';
-import {
-    AdminPage,
-    AdminPageContent,
-    AdminPageHeader,
-    AdminShell,
-    Button,
-    SearchBar,
-    Section,
-    Table,
-} from '@designbasekorea/wordpress-ui/react';
+```text
+.wrap.designbase-wp-admin
+└─ db-admin-shell          title = 플러그인명 (사이드바 로고 슬롯)
+   ├─ db-sidebar           items = 메뉴 (섹션 제목으로 플러그인명을 넣지 않음)
+   └─ main
+      ├─ db-page-header    화면 제목·설명·primary action
+      └─ db-container      shell이 나머지 자식을 자동으로 감쌈
+         ├─ db-section
+         ├─ db-search-bar / db-select / db-table / db-empty-state …
 ```
 
-`AdminShell`은 React 화면용 wrapper이고, Vanilla/PHP 화면의 정본은
-`<db-admin-shell>` Web Component입니다. `db-admin-shell`은 사이드바, 플러그인명
-브랜드, `db-page-header`, 콘텐츠용 `db-container`, 모바일 메뉴 토글을 하나의 패턴으로
-묶습니다. 직접 자식인 `db-page-header`는 header로 유지하고 나머지 내용은 자동으로
-`db-container`에 넣습니다. 기존 화면을 자동 mounting하는 `admin-shell.js` adapter가
-필요한 경우에도 내부적으로 이 Web Component를 사용합니다.
-`AdminPageHeader`는 ui-wc
-`PageHeader`를 감싸 shell 메뉴 버튼과 actions 슬롯을 연결합니다. 탭, 검색, 테이블,
-empty state, 모달 등 나머지 UI는 primitives(`Section`, `SearchBar`, `Table`,
-`EmptyState`, `Modal` 등)를 직접 조합합니다.
-데이터 조회·저장·권한 처리는 소비 플러그인이 소유합니다.
+플러그인명은 사이드바 **헤더 로고**입니다. `title`/`brand`(vanilla) 또는 `sidebarTitle`(React)로 넣습니다. 메뉴 위 작은 섹션 라벨로 쓰지 않습니다.
 
-Vanilla/PHP 화면에서는 등록된 ui-wc element를 직접 사용할 수도 있습니다.
+## Vanilla / PHP (권장)
 
-```html
+필요한 화면에만 `dist/styles.css`와 `dist/browser.iife.js`를 enqueue합니다.
+
+```php
+require_once __DIR__ . '/vendor/wordpress-ui/wordpress-ui.php';
+
+add_action('admin_enqueue_scripts', static function (string $hook_suffix): void {
+    if ($hook_suffix !== 'toplevel_page_myplugin') {
+        return;
+    }
+
+    designbase_wordpress_ui_enqueue([
+        'handle' => 'myplugin-wordpress-ui',
+        'base_url' => plugins_url('vendor/wordpress-ui', __FILE__),
+        'base_path' => __DIR__ . '/vendor/wordpress-ui',
+        'version' => '0.1.6',
+    ]);
+});
+```
+
+```php
+<?php
+$items = [
+    [
+        'id' => 'dashboard',
+        'label' => __('대시보드', 'myplugin'),
+        'href' => admin_url('admin.php?page=myplugin'),
+        'icon' => 'dashboard',
+        '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">
     <db-admin-shell
         title="My Plugin"
-        sections='[{"id":"main","title":"My Plugin","items":[{"id":"dashboard","label":"대시보드","href":"?page=my-plugin","icon":"dashboard","active":true},{"id":"settings","label":"설정","href":"?page=my-plugin-settings","icon":"settings"}]}]'
+        items="<?php echo esc_attr(wp_json_encode($items)); ?>"
     >
-        <db-page-header title="페이지 목록" description="페이지를 관리하세요." variant="minimal">
-            <a slot="actions" class="button button-primary" href="?page=my-pages">새 페이지</a>
+        <db-page-header
+            title="<?php esc_attr_e('페이지 목록', 'myplugin'); ?>"
+            description="<?php esc_attr_e('페이지를 관리하세요.', 'myplugin'); ?>"
+            variant="minimal"
+        >
+            <a slot="actions" class="button button-primary" href="<?php echo esc_url(admin_url('admin.php?page=myplugin-new')); ?>">
+                <?php esc_html_e('새 페이지', 'myplugin'); ?>
+            </a>
         </db-page-header>
-        <db-section title="최근 페이지">
-            <!-- 페이지 콘텐츠 -->
+
+        <db-section title="<?php esc_attr_e('최근 페이지', 'myplugin'); ?>">
+            <db-table
+                columns='<?php echo esc_attr(wp_json_encode([
+                    ['key' => 'title', 'header' => __('제목', 'myplugin')],
+                    ['key' => 'status', 'header' => __('상태', 'myplugin')],
+                ])); ?>'
+                data='<?php echo esc_attr(wp_json_encode($rows ?? [])); ?>'
+                row-key="id"
+            ></db-table>
         </db-section>
     </db-admin-shell>
 </div>
 ```
 
-## 엔트리포인트
+`db-admin-shell` 계약:
 
-- `browser`: React 없이 ui-wc primitives와 `db-admin-shell`을 등록합니다.
-- `components`: `ui-wc` Web Component 클래스와 등록 allowlist를 `wordpress-ui`의 public API로 제공합니다.
-- `primitives`: `components`와 같은 vanilla API의 별칭입니다.
-- `react`: ui-wc primitives의 React façade와 native-first 관리자 패턴을 제공합니다.
-- `styles.css`: `@designbasekorea/theme`의 전체 토큰/시맨틱 변수, ui-wc controls,
-  shell, overlays, `icons-webfont`를 scoped로 포함한 기본 스타일입니다. 소비자는 별도의
-  `theme.css`나 아이콘 폰트를 추가로 enqueue할 필요가 없습니다.
-- `styles/controls.css`, `styles/shell.css`, `styles/overlays.css`: 선택 로딩용 스타일입니다.
+| 속성 | 역할 |
+| --- | --- |
+| `title` 또는 `brand` | 사이드바 헤더의 플러그인명 |
+| `items` | 메뉴 배열 JSON. 권한·active·href는 소비자가 계산 |
+| `sections` | 메뉴를 **실제 그룹**으로 나눌 때만 사용. 그룹 제목에 플러그인명을 넣지 않음 |
+| 자식 `db-page-header` | 화면 헤더로 유지 |
+| 나머지 자식 | `db-container`로 감쌈 |
 
-관리자 패턴에서 아이콘이 필요한 경우 Designbase 아이콘 이름을 사용합니다. 아이콘 폰트도
-기본 스타일에 포함되므로 React 없이 PHP/HTML에서 사용할 수 있습니다.
+메뉴를 그룹으로 나눌 필요가 없으면 `items`만 넘기세요.
 
-```html
-<i class="icon-dashboard" aria-hidden="true"></i>
-<i class="icon-search" aria-hidden="true"></i>
-<i class="icon-settings" aria-hidden="true"></i>
-```
-
-### ui-wc primitives
+## React (선택)
 
-PHP/vanilla 화면은 `browser` 자산을 enqueue한 뒤 `db-*` element를 사용합니다.
-TypeScript로 Web Component 클래스를 직접 조합하는 경우에도 `ui-wc`를 직접 import하지
-말고 `wordpress-ui`의 `components` entry를 사용합니다.
+Gutenberg나 기존 React 앱에서만 사용합니다. 일반 PHP 관리자 화면에는 vanilla를 권장합니다.
 
-```ts
-import '@designbasekorea/wordpress-ui/browser';
+```tsx
 import '@designbasekorea/wordpress-ui/styles.css';
 import {
-    DbButton,
-    DbInput,
-    DbSelect,
-    DbModal,
-    DbContainer,
-    DbAdminShell,
-} from '@designbasekorea/wordpress-ui/components';
-
-// PHP/HTML에서는 <db-button>, <db-input>, <db-select>, <db-modal>로 사용합니다.
-void DbButton;
-void DbInput;
-void DbSelect;
-void DbModal;
-void DbContainer;
-void DbAdminShell;
-```
-
-동일한 named export는 패키지 루트에서도 사용할 수 있습니다. 기존 `figma-ui`처럼
-짧은 import를 선호하는 TypeScript 소비자는 다음 형태를 사용해도 됩니다.
+    AdminPage,
+    AdminPageContent,
+    AdminPageHeader,
+    AdminShell,
+    Button,
+    Section,
+    Table,
+} from '@designbasekorea/wordpress-ui/react';
 
-```ts
-import { DbButton, DbInput, DbSelect, DbModal } from '@designbasekorea/wordpress-ui';
+const sidebarItems = [
+    { id: 'dashboard', label: '대시보드', href: '?page=myplugin', icon: 'dashboard', active: true },
+    { id: 'settings', label: '설정', href: '?page=myplugin-settings', icon: 'settings' },
+];
+
+export function MyPluginAdmin() {
+    return (
+        <AdminShell sidebarTitle="My Plugin" sidebarItems={sidebarItems}>
+            <AdminPageHeader
+                title="페이지 목록"
+                description="페이지를 검색하고 상태를 관리합니다."
+                actions={<Button variant="primary" size="s">새 페이지</Button>}
+            />
+            <AdminPage>
+                <AdminPageContent>
+                    <Section title="최근 페이지" fullWidth>
+                        <Table
+                            columns={JSON.stringify([
+                                { key: 'title', header: '제목' },
+                                { key: 'status', header: '상태' },
+                            ])}
+                            data={JSON.stringify([])}
+                            rowKey="id"
+                            emptyMessage="콘텐츠가 없습니다."
+                        />
+                    </Section>
+                </AdminPageContent>
+            </AdminPage>
+        </AdminShell>
+    );
+}
 ```
 
-두 경로 모두 같은 `ui-wc` 클래스와 등록 계약을 가리킵니다. HTML/PHP 소비자는
-`browser`를 enqueue한 뒤 `<db-button>`, `<db-input>`, `<db-select>`, `<db-modal>`처럼
-태그를 사용합니다.
-
-React 화면은 같은 ui-wc element를 React façade로 사용합니다.
+React 관리자 패턴:
 
-```tsx
-import { Button, Input, Select, Modal } from '@designbasekorea/wordpress-ui/react';
-```
+- `AdminShell` — `sidebarTitle`(로고) + `sidebarItems`(메뉴). `AdminWrapper`를 포함합니다.
+- `AdminPageHeader` — `db-page-header` + 모바일 메뉴 버튼
+- `AdminPage` / `AdminPageContent` — 페이지 폭
+- 그 외 UI는 primitives입니다. `Section`, `Table`, `SearchBar`, `Select`, `EmptyState`, `Tabs`, `Modal` 등. `AdminSection` / `AdminDataTable` 같은 별도 래퍼는 없습니다.
 
-로컬 검증은 `npm run build`, `npm run verify`, `npm run audit:axe` 순서로 실행합니다.
-`audit:axe`는 Chromium이 설치된 환경에서 vanilla 예제의 실제 DOM을 검사합니다.
+## 엔트리포인트
 
-컴포넌트 미리보기는 Storybook으로 확인할 수 있습니다.
+| import | 용도 |
+| --- | --- |
+| `@designbasekorea/wordpress-ui/browser` | React 없이 `db-*`와 `db-admin-shell` 등록. PHP는 `dist/browser.iife.js` |
+| `@designbasekorea/wordpress-ui/styles.css` | 테마 토큰 + ui-wc + shell + 아이콘 폰트. 별도 `theme.css`/CDN 아이콘 불필요 |
+| `@designbasekorea/wordpress-ui/components` 또는 패키지 루트 | TypeScript에서 `DbButton`, `DbAdminShell` 등 클래스 |
+| `@designbasekorea/wordpress-ui/react` | React façade |
 
-```bash
-cd packages/wordpress-ui
-npm run storybook
+```ts
+import '@designbasekorea/wordpress-ui/browser';
+import '@designbasekorea/wordpress-ui/styles.css';
+import { DbButton, DbAdminShell } from '@designbasekorea/wordpress-ui';
 ```
 
-기본 포트는 `http://localhost:6008` 입니다. (`figma-ui` Storybook은 `:6007`)
-
-모든 관리자 패턴과 runtime surface는 `.designbase-wp-admin` 아래에서 동작합니다. 신규
-플러그인과 테마는 이 패키지의 public API만 사용하세요. 기존 UI
-라이브러리의 전역 객체나 호환 계층은 제공하지 않습니다.
-
-## WordPress 플러그인·테마 enqueue
-
-관리자 화면에서 `admin_enqueue_scripts`와 화면 allowlist는 소비자가 소유합니다.
-패키지의 `wordpress-ui.php`를 include한 뒤 플러그인이나 테마의 vendor 경로를
-전달하면 React 없이 같은 runtime을 사용할 수 있습니다.
-
-```php
-require_once get_template_directory() . '/vendor/wordpress-ui/wordpress-ui.php';
-
-add_action('admin_enqueue_scripts', function ($hook_suffix) {
-    if ($hook_suffix !== 'toplevel_page_my-theme-settings') {
-        return;
-    }
+아이콘은 Designbase 이름을 씁니다.
 
-    designbase_wordpress_ui_enqueue([
-        'handle' => 'my-theme-wordpress-ui',
-        'base_url' => get_template_directory_uri() . '/vendor/wordpress-ui',
-        'base_path' => get_template_directory() . '/vendor/wordpress-ui',
-    ]);
-});
+```html
+<i class="icon-dashboard" aria-hidden="true"></i>
 ```
 
-## 상세 적용 가이드
+## 로컬 확인
 
-플러그인과 테마 관리자 화면에 적용하는 전체 규칙은 다음 문서를 참고하세요.
+```bash
+cd packages/wordpress-ui
+npm run build
+npm run verify
+npm run storybook   # http://localhost:6008
+```
 
-- [WordPress 관리자 적용 가이드](./docs/WORDPRESS-ADMIN-GUIDE.md)
+적용 규칙·enqueue·REST/nonce는 [WordPress 관리자 적용 가이드](./docs/WORDPRESS-ADMIN-GUIDE.md)를 참고하세요.