@designbasekorea/wordpress-ui 0.1.0

package/README.md

@@ -0,0 +1,102 @@
+# @designbasekorea/wordpress-ui
+
+WordPress 관리자 플러그인 화면을 위한 Designbase façade/adaptor 패키지입니다.
+WordPress 전체 관리자 프레임을 대체하지 않고, 플러그인 내부의 shell과 반복되는
+페이지 패턴만 제공합니다.
+
+## 사용
+
+Vanilla/PHP 플러그인은 필요한 화면에서만 다음 자산을 enqueue합니다.
+
+```ts
+import '@designbasekorea/wordpress-ui/browser';
+import '@designbasekorea/wordpress-ui/styles.css';
+```
+
+React 플러그인은 React를 peer dependency로 유지하며 다음처럼 사용합니다.
+
+```tsx
+import '@designbasekorea/wordpress-ui/styles.css';
+import {
+    AdminDataTable,
+    AdminPage,
+    AdminPageContent,
+    AdminPageHeader,
+    AdminSection,
+} from '@designbasekorea/wordpress-ui/react';
+```
+
+`AdminFilterBar`, `AdminDataTable`은 데이터를 조회하거나 저장하지 않습니다. REST,
+nonce, capability, pagination과 같은 비즈니스 상태는 소비 플러그인이 소유합니다.
+
+Vanilla/PHP 화면에서는 등록된 ui-wc element를 직접 사용할 수도 있습니다.
+
+```html
+<div class="designbase-wp-admin">
+    <db-page-header title="페이지 목록" description="페이지를 관리하세요." variant="minimal">
+        <a slot="actions" class="button button-primary" href="?page=my-pages">새 페이지</a>
+    </db-page-header>
+</div>
+```
+
+## 엔트리포인트
+
+- `browser`: React 없이 필요한 ui-wc primitives만 등록하고 모바일 sidebar toggle을 보강합니다.
+- `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`: 선택 로딩용 스타일입니다.
+
+관리자 패턴에서 아이콘이 필요한 경우 Designbase 아이콘 이름을 사용합니다. 아이콘 폰트도
+기본 스타일에 포함되므로 React 없이 PHP/HTML에서 사용할 수 있습니다.
+
+```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>
+```
+
+로컬 검증은 `npm run build`, `npm run verify`, `npm run audit:axe` 순서로 실행합니다.
+`audit:axe`는 Chromium이 설치된 환경에서 vanilla 예제의 실제 DOM을 검사합니다.
+
+컴포넌트 미리보기는 Storybook으로 확인할 수 있습니다.
+
+```bash
+cd packages/wordpress-ui
+npm run storybook
+```
+
+기본 포트는 `http://localhost:6008` 입니다. (`figma-ui` Storybook은 `:6007`)
+
+모든 관리자 패턴과 runtime surface는 `.designbase-wp-admin` 아래에서 동작합니다. 신규
+플러그인과 테마는 `ui-wc` 또는 이 패키지의 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_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',
+    ]);
+});
+```
+
+## 상세 적용 가이드
+
+플러그인과 테마 관리자 화면에 적용하는 전체 규칙은 다음 문서를 참고하세요.
+
+- [WordPress 관리자 적용 가이드](./docs/WORDPRESS-ADMIN-GUIDE.md)