@reopt-ai/opt-ui 1.4.1

package/dist/docs/03-recipes/03-layouts.md

@@ -0,0 +1,424 @@
+---
+title: "Layout Recipes"
+description: "opt-ui 레이아웃 조합 패턴 3종 — AppShell, DataExplorer, Settings"
+related:
+  links:
+    - ../02-components/01-core.md
+    - ../02-components/03-shells.md
+---
+
+<!-- AI agent hint: Surface/페이지 루트에 직접 space-y-* 사용 금지. 반드시 SurfaceLayout 또는 createSurface 사용. -->
+
+# Layout Recipes
+
+Copy-paste-ready layout composition patterns.
+All imports from `@reopt-ai/opt-ui`.
+
+## 1. App Shell with Sidebar
+
+Full application chrome: header, collapsible sidebar, main content area.
+
+```tsx
+"use client";
+
+import { useState } from "react";
+import {
+  AppShell,
+  Sidebar,
+  useSidebar,
+  PageHeader,
+  Button,
+  Logo,
+} from "@reopt-ai/opt-ui";
+
+interface NavLink {
+  id: string;
+  label: string;
+  href: string;
+  icon: React.ReactNode;
+}
+
+function SidebarNav({ links }: { links: NavLink[] }) {
+  const { collapsed } = useSidebar();
+
+  return (
+    <>
+      {links.map((link) => (
+        <a
+          key={link.id}
+          href={link.href}
+          className="text-text-secondary hover:text-text-primary hover:bg-bg-subtle gap-element flex items-center rounded-md px-3 py-2 text-sm transition-colors"
+        >
+          {link.icon}
+          {!collapsed && <span>{link.label}</span>}
+        </a>
+      ))}
+    </>
+  );
+}
+
+export function AppLayout({ children }: { children: React.ReactNode }) {
+  const navLinks: NavLink[] = [
+    { id: "dashboard", label: "대시보드", href: "/", icon: <span>D</span> },
+    {
+      id: "projects",
+      label: "프로젝트",
+      href: "/projects",
+      icon: <span>P</span>,
+    },
+    { id: "settings", label: "설정", href: "/settings", icon: <span>S</span> },
+  ];
+
+  return (
+    <AppShell>
+      <AppShell.Header>
+        <div className="gap-group flex items-center">
+          <Logo text="MyApp" />
+          <div className="flex-1" />
+          <Button variant="ghost" size="sm">
+            로그아웃
+          </Button>
+        </div>
+      </AppShell.Header>
+
+      <AppShell.Sidebar>
+        <Sidebar collapsible defaultCollapsed={false} label="메인 내비게이션">
+          <Sidebar.Header>
+            <Sidebar.Trigger />
+          </Sidebar.Header>
+
+          <Sidebar.Content>
+            <SidebarNav links={navLinks} />
+          </Sidebar.Content>
+
+          <Sidebar.Footer>
+            <div className="text-text-tertiary text-xs">v2.4.0</div>
+          </Sidebar.Footer>
+        </Sidebar>
+      </AppShell.Sidebar>
+
+      <AppShell.Content>
+        <div className="p-6">{children}</div>
+      </AppShell.Content>
+    </AppShell>
+  );
+}
+```
+
+## 2. Data Explorer Page
+
+FilterBar + DataTable + Pagination in a SurfaceLayout.
+
+```tsx
+"use client";
+
+import { useState, useMemo } from "react";
+import {
+  SurfaceLayout,
+  PageHeader,
+  FilterBar,
+  DataTable,
+  Pagination,
+  Button,
+  type FilterGroupDef,
+  type ColumnDef,
+} from "@reopt-ai/opt-ui";
+
+interface User {
+  id: string;
+  name: string;
+  email: string;
+  role: "admin" | "editor" | "viewer";
+  status: "active" | "inactive";
+  lastLogin: string;
+}
+
+const allUsers: User[] = Array.from({ length: 48 }, (_, i) => ({
+  id: `u${i + 1}`,
+  name: `사용자 ${i + 1}`,
+  email: `user${i + 1}@example.com`,
+  role: (["admin", "editor", "viewer"] as const)[i % 3],
+  status: i % 5 === 0 ? "inactive" : "active",
+  lastLogin: new Date(Date.now() - i * 86400000).toLocaleDateString("ko-KR"),
+}));
+
+const columns: ColumnDef<User>[] = [
+  { id: "name", header: "이름", accessor: "name", sortable: true },
+  { id: "email", header: "이메일", accessor: "email" },
+  { id: "role", header: "역할", accessor: "role", sortable: true },
+  {
+    id: "status",
+    header: "상태",
+    accessor: (u) => (
+      <span
+        className={
+          u.status === "active" ? "text-success-fg" : "text-text-tertiary"
+        }
+      >
+        {u.status === "active" ? "활성" : "비활성"}
+      </span>
+    ),
+  },
+  { id: "lastLogin", header: "최근 로그인", accessor: "lastLogin" },
+];
+
+const filters: FilterGroupDef[] = [
+  { id: "search", label: "검색", type: "search", value: "" },
+  {
+    id: "role",
+    label: "역할",
+    type: "select",
+    options: [
+      { id: "all", label: "전체", value: "" },
+      { id: "admin", label: "Admin", value: "admin" },
+      { id: "editor", label: "Editor", value: "editor" },
+      { id: "viewer", label: "Viewer", value: "viewer" },
+    ],
+    value: "",
+  },
+  { id: "status", label: "상태", type: "toggle", value: false },
+];
+
+const PAGE_SIZE = 10;
+
+export function UserExplorerPage() {
+  const [page, setPage] = useState(1);
+  const [search, setSearch] = useState("");
+  const [roleFilter, setRoleFilter] = useState("");
+  const [activeOnly, setActiveOnly] = useState(false);
+
+  const filtered = useMemo(() => {
+    let result = allUsers;
+    if (search) {
+      const q = search.toLowerCase();
+      result = result.filter(
+        (u) => u.name.toLowerCase().includes(q) || u.email.includes(q),
+      );
+    }
+    if (roleFilter) {
+      result = result.filter((u) => u.role === roleFilter);
+    }
+    if (activeOnly) {
+      result = result.filter((u) => u.status === "active");
+    }
+    return result;
+  }, [search, roleFilter, activeOnly]);
+
+  const paged = filtered.slice((page - 1) * PAGE_SIZE, page * PAGE_SIZE);
+
+  const handleFilterChange = (
+    id: string,
+    value: string | string[] | boolean,
+  ) => {
+    if (id === "search") setSearch(value as string);
+    if (id === "role") setRoleFilter(value as string);
+    if (id === "status") setActiveOnly(value as boolean);
+    setPage(1);
+  };
+
+  return (
+    <SurfaceLayout>
+      <PageHeader
+        title="사용자 관리"
+        description={`총 ${filtered.length}명`}
+        actions={<Button>사용자 추가</Button>}
+      />
+
+      <FilterBar
+        filters={filters}
+        onFilterChange={handleFilterChange}
+        onClearAll={() => {
+          setSearch("");
+          setRoleFilter("");
+          setActiveOnly(false);
+          setPage(1);
+        }}
+      />
+
+      <DataTable
+        data={paged}
+        columns={columns}
+        keyExtractor={(u) => u.id}
+        sortable
+        onRowClick={(u) => console.log("선택:", u.id)}
+      />
+
+      <Pagination
+        totalItems={filtered.length}
+        pageSize={PAGE_SIZE}
+        currentPage={page}
+        onPageChange={setPage}
+      />
+    </SurfaceLayout>
+  );
+}
+```
+
+## 3. Settings Page with Vertical Tabs
+
+SurfaceLayout with VerticalTabs for section navigation and SettingsForm for each tab.
+
+```tsx
+"use client";
+
+import {
+  SurfaceLayout,
+  PageHeader,
+  VerticalTabs,
+  SettingsForm,
+  type TabDef,
+  type FormFieldDef,
+} from "@reopt-ai/opt-ui";
+
+const generalFields: FormFieldDef[] = [
+  {
+    name: "siteName",
+    label: "사이트 이름",
+    type: "text",
+    placeholder: "My App",
+  },
+  {
+    name: "siteUrl",
+    label: "사이트 URL",
+    type: "text",
+    placeholder: "https://...",
+  },
+  {
+    name: "language",
+    label: "기본 언어",
+    type: "select",
+    options: [
+      { value: "ko", label: "한국어" },
+      { value: "en", label: "English" },
+      { value: "ja", label: "日本語" },
+    ],
+  },
+  {
+    name: "description",
+    label: "사이트 설명",
+    type: "textarea",
+    placeholder: "사이트에 대한 간단한 설명",
+    rows: 3,
+  },
+];
+
+const notificationFields: FormFieldDef[] = [
+  {
+    name: "emailNotify",
+    label: "이메일 알림",
+    type: "switch",
+    description: "중요 업데이트를 이메일로 수신합니다",
+  },
+  {
+    name: "pushNotify",
+    label: "푸시 알림",
+    type: "switch",
+    description: "브라우저 푸시 알림을 허용합니다",
+  },
+  {
+    name: "digestFreq",
+    label: "요약 주기",
+    type: "select",
+    options: [
+      { value: "daily", label: "매일" },
+      { value: "weekly", label: "매주" },
+      { value: "never", label: "사용 안 함" },
+    ],
+    visible: (values) => values.emailNotify === true,
+  },
+];
+
+const securityFields: FormFieldDef[] = [
+  {
+    name: "twoFactor",
+    label: "2단계 인증",
+    type: "switch",
+    description: "로그인 시 추가 인증을 요구합니다",
+  },
+  {
+    name: "sessionTimeout",
+    label: "세션 만료 (분)",
+    type: "number",
+    placeholder: "30",
+  },
+  {
+    name: "ipWhitelist",
+    label: "IP 허용 목록",
+    type: "tags",
+    placeholder: "IP 주소 입력 후 Enter",
+  },
+];
+
+const tabs: TabDef[] = [
+  {
+    id: "general",
+    label: "일반",
+    content: (
+      <SettingsForm
+        fields={generalFields}
+        onSubmit={(v) => console.log("general", v)}
+        labels={{ submitButton: "저장" }}
+      />
+    ),
+  },
+  {
+    id: "notifications",
+    label: "알림",
+    content: (
+      <SettingsForm
+        fields={notificationFields}
+        onSubmit={(v) => console.log("notifications", v)}
+        labels={{ submitButton: "저장" }}
+      />
+    ),
+  },
+  {
+    id: "security",
+    label: "보안",
+    content: (
+      <SettingsForm
+        fields={securityFields}
+        onSubmit={(v) => console.log("security", v)}
+        labels={{ submitButton: "저장" }}
+      />
+    ),
+  },
+];
+
+export function SettingsPage() {
+  return (
+    <SurfaceLayout>
+      <PageHeader title="설정" description="프로젝트 설정을 관리합니다" />
+
+      <VerticalTabs
+        tabs={tabs}
+        defaultTabId="general"
+        labels={{ ariaLabel: "설정 카테고리" }}
+      />
+    </SurfaceLayout>
+  );
+}
+```
+
+## Layout Conventions
+
+| Element        | Approach                                                                  |
+| -------------- | ------------------------------------------------------------------------- |
+| Page root      | `SurfaceLayout` (provides `gap-section` between children)                 |
+| App chrome     | `AppShell` + `AppShell.Header/Sidebar/Content/Footer`                     |
+| Sidebar nav    | `Sidebar` with `Sidebar.Header/Content/Footer` sub-components             |
+| Page title     | `PageHeader` with optional `description` and `actions` slot               |
+| Section grids  | `gap-group` between columns, `gap-element` for tight spacing              |
+| Tab navigation | `VerticalTabs` for left-side tabs, `ContentTabs` for horizontal           |
+| Pagination     | `Pagination` below `DataTable` with `totalItems`/`pageSize`/`currentPage` |
+| Loading state  | `SurfaceLayout loading={true}` wraps content with `LoadingOverlay`        |
+
+### Semantic Spacing Quick Reference
+
+```
+gap-section  ->  24px  (between major sections)
+gap-group    ->  16px  (between related items)
+gap-element  ->   8px  (between tightly coupled elements)
+```
+
+CSS variables: `--opt-space-section`, `--opt-space-group`, `--opt-space-element`.

package/dist/docs/04-theming.md

@@ -0,0 +1,232 @@
+---
+title: "Theming"
+description: "opt-ui 테마 시스템 — 5개 프리셋, CSS 변수, 다크 모드, 커스텀 테마 생성 가이드"
+related:
+  links:
+    - 01-getting-started.md
+    - 02-components/01-core.md
+---
+
+<!-- AI agent hint: 색상을 하드코딩하지 말 것. bg-zinc-100 대신 bg-[var(--opt-bg-subtle)] 또는 시맨틱 토큰 사용. 스페이싱도 gap-4 대신 gap-section/gap-group/gap-element 사용. -->
+
+# Theming
+
+opt-ui uses a CSS custom properties (CSS variables) based theme system with 6 built-in presets, each supporting light and dark modes.
+
+## Presets
+
+| Preset      | Description                                          |
+| ----------- | ---------------------------------------------------- |
+| `default`   | Clean, neutral design with Geist Sans typography     |
+| `minimal`   | Stripped-down, high-contrast, sharp edges            |
+| `natural`   | Warm tones with Playfair Display + Lora (light only) |
+| `pro`       | Neon blue accents, mono headings, dense spacing      |
+| `mono-dark` | OLED-friendly black, neon cyan accent, mono headings |
+
+> Previous versions also shipped `corporate` and `playful`; both have been
+> removed. Persisted localStorage values are silently migrated to `default`.
+> Re-create their visual feel via the generated theme builder if needed.
+
+## Applying a Preset
+
+Import the CSS (already included via `@reopt-ai/opt-ui/tailwind.css`):
+
+```css
+@import "tailwindcss";
+@import "@reopt-ai/opt-ui/tailwind.css";
+```
+
+Individual preset files are also available:
+
+```css
+@import "@reopt-ai/opt-ui/theme/presets/default.css";
+@import "@reopt-ai/opt-ui/theme/presets/mono-dark.css";
+```
+
+## OptThemeProvider
+
+Wrap your app root with `OptThemeProvider` to enable theme switching:
+
+```tsx
+import { OptThemeProvider } from "@reopt-ai/opt-ui";
+
+<OptThemeProvider defaultPreset="default">{children}</OptThemeProvider>;
+```
+
+### Controlling the theme
+
+```tsx
+import { useOptTheme } from "@reopt-ai/opt-ui";
+
+function ThemeControls() {
+  const { preset, setPreset, mode, setMode } = useOptTheme();
+
+  return (
+    <>
+      <select value={preset} onChange={(e) => setPreset(e.target.value)}>
+        <option value="default">Default</option>
+        <option value="minimal">Minimal</option>
+        <option value="natural">Natural</option>
+        <option value="pro">Pro</option>
+        <option value="mono-dark">Mono Dark</option>
+      </select>
+
+      <button onClick={() => setMode(mode === "dark" ? "light" : "dark")}>
+        Toggle Dark Mode
+      </button>
+    </>
+  );
+}
+```
+
+Or use the built-in `ThemeSwitcher` component:
+
+```tsx
+import { ThemeSwitcher } from "@reopt-ai/opt-ui";
+
+<ThemeSwitcher />              // Full grid with mode toggle
+<ThemeSwitcher variant="compact" />  // Inline horizontal layout
+```
+
+## CSS Variables
+
+Presets define variables on `[data-theme="preset"]` (light) and `[data-theme="preset-dark"]` (dark) selectors.
+
+### Surface & Background
+
+| Variable                | Description              |
+| ----------------------- | ------------------------ |
+| `--opt-surface`         | Primary surface color    |
+| `--opt-surface-raised`  | Elevated surface (cards) |
+| `--opt-surface-overlay` | Overlay/modal surface    |
+| `--opt-surface-input`   | Input background         |
+| `--opt-bg`              | Page background          |
+| `--opt-bg-subtle`       | Subtle background tint   |
+| `--opt-bg-muted`        | Muted background         |
+
+### Text
+
+| Variable               | Description         |
+| ---------------------- | ------------------- |
+| `--opt-text`           | Primary text color  |
+| `--opt-text-secondary` | Secondary text      |
+| `--opt-text-tertiary`  | Tertiary/muted text |
+
+### Accent & Status
+
+| Variable              | Description          |
+| --------------------- | -------------------- |
+| `--opt-accent`        | Primary accent color |
+| `--opt-accent-hover`  | Accent hover state   |
+| `--opt-accent-subtle` | Accent subtle tint   |
+| `--opt-accent-fg`     | Text on accent       |
+| `--opt-success`       | Success color        |
+| `--opt-warning`       | Warning color        |
+| `--opt-danger`        | Danger/error color   |
+| `--opt-info`          | Info color           |
+
+### Border & Focus
+
+| Variable              | Description        |
+| --------------------- | ------------------ |
+| `--opt-border`        | Default border     |
+| `--opt-border-hover`  | Border hover state |
+| `--opt-border-subtle` | Subtle border      |
+| `--opt-ring`          | Focus ring color   |
+| `--opt-ring-offset`   | Focus ring offset  |
+
+### Spacing
+
+| Variable              | Value    | Tailwind class |
+| --------------------- | -------- | -------------- |
+| `--opt-space-section` | `1.5rem` | `gap-section`  |
+| `--opt-space-group`   | `1rem`   | `gap-group`    |
+| `--opt-space-element` | `0.5rem` | `gap-element`  |
+
+### Typography
+
+| Variable                 | Description            |
+| ------------------------ | ---------------------- |
+| `--opt-font-heading`     | Heading font family    |
+| `--opt-font-body`        | Body font family       |
+| `--opt-tracking-heading` | Heading letter spacing |
+| `--opt-weight-heading`   | Heading font weight    |
+
+### Radius & Shadow
+
+| Variable          | Description   |
+| ----------------- | ------------- |
+| `--opt-radius-sm` | Small radius  |
+| `--opt-radius-md` | Medium radius |
+| `--opt-radius-lg` | Large radius  |
+| `--opt-shadow-sm` | Small shadow  |
+| `--opt-shadow-md` | Medium shadow |
+| `--opt-shadow-lg` | Large shadow  |
+
+### Chart
+
+| Variable        | Description   |
+| --------------- | ------------- |
+| `--opt-chart-1` | Chart color 1 |
+| `--opt-chart-2` | Chart color 2 |
+| `--opt-chart-3` | Chart color 3 |
+| `--opt-chart-4` | Chart color 4 |
+| `--opt-chart-5` | Chart color 5 |
+
+## Dark Mode
+
+Dark mode uses the `[data-theme="preset-dark"]` selector. The compound theme system applies automatically when using `OptThemeProvider`.
+
+```css
+/* Light mode */
+[data-theme="default"] {
+  --opt-surface: #ffffff;
+  --opt-text: hsl(0 0% 20%);
+}
+
+/* Dark mode */
+[data-theme="default-dark"] {
+  --opt-surface: hsl(204 4% 16%);
+  --opt-text: hsl(0 0% 82%);
+}
+```
+
+Tailwind `dark:` classes work automatically via:
+
+```css
+@custom-variant dark (&:where([data-theme$="-dark"], ...));
+```
+
+## Custom Preset
+
+Create a custom preset by defining a new `[data-theme]` selector with your variables:
+
+```css
+/* my-preset.css */
+[data-theme="my-brand"] {
+  --opt-surface: #fafafa;
+  --opt-accent: hsl(262 83% 58%);
+  --opt-accent-hover: hsl(262 83% 50%);
+  --opt-accent-fg: #ffffff;
+  --opt-text: hsl(0 0% 15%);
+  --opt-text-secondary: hsl(0 0% 40%);
+  --opt-border: rgba(0, 0, 0, 0.12);
+  --opt-ring: hsl(262 83% 58%);
+  /* ... override other variables as needed */
+}
+
+[data-theme="my-brand-dark"] {
+  --opt-surface: hsl(262 10% 12%);
+  --opt-accent: hsl(262 83% 65%);
+  --opt-text: hsl(0 0% 85%);
+  /* ... dark mode overrides */
+}
+```
+
+Import it in your global CSS and use it with `OptThemeProvider`:
+
+```tsx
+<OptThemeProvider defaultPreset="my-brand">{children}</OptThemeProvider>
+```
+
+> Tip: Copy an existing preset file (e.g., `default.css`) as a starting point and modify the values. All variables should be defined for consistent behavior.