From e104d1b47c5e0f9d7904ac5485c06a75e1b5c849 Mon Sep 17 00:00:00 2001
From: Hyungi Ahn <hyungiahn@Hyungiui-MacBookPro.local>
Date: Tue, 7 Apr 2026 08:40:08 +0900
Subject: [PATCH] =?UTF-8?q?feat:=20Layer=20=ED=94=84=EB=A6=AC=EB=AF=B8?=
 =?UTF-8?q?=ED=8B=B0=EB=B8=8C=20(Drawer=20/=20Modal=20/=20ConfirmDialog=20?=
 =?UTF-8?q?/=20Tabs)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

UX/UI 개편 Phase A-7. uiState와 결합한 layer/dialog 컴포넌트.

신규 컴포넌트 (lib/components/ui/)
- Drawer.svelte: 단일 slot drawer (id: 'sidebar' | 'meta').
  ui.isDrawerOpen(id)로 표시 여부 결정. 새 drawer 열면 이전 drawer 자동 close.
  side(left/right) + width(sidebar/rail). backdrop 클릭으로 close.
  z-drawer 사용. 8대 원칙 #2.

- Modal.svelte: stack 지원 modal (5대 원칙 #2 — confirm 위에 nested 가능).
  native <dialog> 대신 div 기반 — top-layer가 단일이라 <dialog>로는 stack 불가.
  z-index = z-modal + (stackIndex * 2): backdrop과 panel을 별개의 stacking
  context로 두기 위해 *2. 최상단 modal만 focus trap + 키보드 nav 활성,
  아래는 inert 처리. 수동 Tab/Shift+Tab cycling.
  closable + IconButton(X) 헤더, footer snippet 지원.

- ConfirmDialog.svelte: Modal 위 얇은 wrapper. 삭제/되돌릴 수 없는 작업에
  사용. tone(danger/primary), confirmLabel/cancelLabel, onconfirm 콜백.
  ui.openModal(id)로 호출.

- Tabs.svelte: ARIA tablist + tab + tabpanel.
  좌우 화살표 / Home / End 키 nav, \$props.id() 기반 SSR-safe ID.
  tabs: { id, label, disabled? }[], value \$bindable.
  children snippet은 (activeId) => UI 시그니처 — DocumentViewer 편집/미리보기
  토글 등 단일 컨테이너 레이아웃에 쓰기 좋게 설계.

이로써 Phase A 프리미티브 13종 완비:
  Button, IconButton, Card, Badge, Skeleton, EmptyState,
  TextInput, Textarea, Select,
  Drawer, Modal, ConfirmDialog, Tabs.

모든 컴포넌트는 Svelte 5 runes mode strict, @theme 토큰만 사용,
focus-visible ring 통일, slot은 {@render children?.()}로 작성.

svelte-check: 0 errors / 8 warnings (전부 기존 latent, 새 코드 무관)
build: 2.07s 무경고

남은 Phase A:
- A-8 토큰 swap (Sidebar/TagPill/UploadDropzone/PreviewPanel/DocumentCard/
  DocumentTable/+layout toast — baseline 421건 → 0건)
- A-9 __styleguide 라우트 (전체 시각 검증 + Modal stack 데모)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .../lib/components/ui/ConfirmDialog.svelte    |  52 +++++++
 frontend/src/lib/components/ui/Drawer.svelte  |  62 ++++++++
 frontend/src/lib/components/ui/Modal.svelte   | 137 ++++++++++++++++++
 frontend/src/lib/components/ui/Tabs.svelte    | 111 ++++++++++++++
 4 files changed, 362 insertions(+)
 create mode 100644 frontend/src/lib/components/ui/ConfirmDialog.svelte
 create mode 100644 frontend/src/lib/components/ui/Drawer.svelte
 create mode 100644 frontend/src/lib/components/ui/Modal.svelte
 create mode 100644 frontend/src/lib/components/ui/Tabs.svelte

diff --git a/frontend/src/lib/components/ui/ConfirmDialog.svelte b/frontend/src/lib/components/ui/ConfirmDialog.svelte
new file mode 100644
index 0000000..3a838f0
--- /dev/null
+++ b/frontend/src/lib/components/ui/ConfirmDialog.svelte
@@ -0,0 +1,52 @@
+<script lang="ts">
+  // 삭제/되돌릴 수 없는 작업의 확인 dialog. Modal 위 얇은 wrapper.
+  // 사용처에서 ui.openModal(id) 호출하면 표시됨.
+  import { ui } from '$lib/stores/uiState.svelte';
+  import Modal from './Modal.svelte';
+  import Button from './Button.svelte';
+
+  type Tone = 'danger' | 'primary';
+
+  interface Props {
+    id: string;
+    title: string;
+    message: string;
+    confirmLabel?: string;
+    cancelLabel?: string;
+    tone?: Tone;
+    loading?: boolean;
+    onconfirm: () => void | Promise<void>;
+  }
+
+  let {
+    id,
+    title,
+    message,
+    confirmLabel = '확인',
+    cancelLabel = '취소',
+    tone = 'danger',
+    loading = false,
+    onconfirm,
+  }: Props = $props();
+
+  function cancel() {
+    ui.closeModal(id);
+  }
+
+  async function confirm() {
+    await onconfirm();
+    // onconfirm이 닫지 않으면 우리가 닫는다 (멱등하게 처리됨)
+    if (ui.isModalOpen(id)) ui.closeModal(id);
+  }
+</script>
+
+<Modal {id} {title} size="sm">
+  <p class="text-sm text-dim leading-relaxed">{message}</p>
+
+  {#snippet footer()}
+    <Button variant="ghost" size="sm" onclick={cancel}>{cancelLabel}</Button>
+    <Button variant={tone === 'danger' ? 'danger' : 'primary'} size="sm" {loading} onclick={confirm}>
+      {confirmLabel}
+    </Button>
+  {/snippet}
+</Modal>
diff --git a/frontend/src/lib/components/ui/Drawer.svelte b/frontend/src/lib/components/ui/Drawer.svelte
new file mode 100644
index 0000000..d57a994
--- /dev/null
+++ b/frontend/src/lib/components/ui/Drawer.svelte
@@ -0,0 +1,62 @@
+<script lang="ts">
+  // 사이드 슬라이드 패널. uiState의 단일 drawer slot과 결합.
+  // - id: 'sidebar' | 'meta' (동시에 둘 다 열리지 않음)
+  // - 새 drawer 열면 ui.openDrawer(id)가 자동으로 이전 drawer를 치움
+  // - 모바일/태블릿에서 메타 패널을 표시하는 폴백 경로 (xl+에서는 inline rail 사용)
+  import type { Snippet } from 'svelte';
+  import { ui } from '$lib/stores/uiState.svelte';
+
+  type Side = 'left' | 'right';
+  type Width = 'sidebar' | 'rail';
+
+  interface Props {
+    id: 'sidebar' | 'meta';
+    side?: Side;
+    width?: Width;
+    children?: Snippet;
+    'aria-label'?: string;
+  }
+
+  let {
+    id,
+    side = 'left',
+    width = 'sidebar',
+    children,
+    'aria-label': ariaLabel = '드로어',
+  }: Props = $props();
+
+  let open = $derived(ui.isDrawerOpen(id));
+
+  let widthClass = $derived(width === 'sidebar' ? 'w-sidebar' : 'w-rail');
+  let sideClass = $derived(side === 'left' ? 'left-0' : 'right-0');
+  let translateClosed = $derived(side === 'left' ? '-translate-x-full' : 'translate-x-full');
+
+  function close() {
+    ui.closeDrawer();
+  }
+</script>
+
+{#if open}
+  <!-- backdrop -->
+  <div class="fixed inset-0 z-drawer">
+    <button
+      type="button"
+      onclick={close}
+      class="absolute inset-0 bg-scrim transition-opacity"
+      aria-label="드로어 닫기"
+    ></button>
+
+    <!-- panel -->
+    <aside
+      class={[
+        'absolute top-0 bottom-0 z-drawer bg-sidebar shadow-xl transition-transform',
+        sideClass,
+        widthClass,
+        open ? 'translate-x-0' : translateClosed,
+      ].join(' ')}
+      aria-label={ariaLabel}
+    >
+      {@render children?.()}
+    </aside>
+  </div>
+{/if}
diff --git a/frontend/src/lib/components/ui/Modal.svelte b/frontend/src/lib/components/ui/Modal.svelte
new file mode 100644
index 0000000..46fecc2
--- /dev/null
+++ b/frontend/src/lib/components/ui/Modal.svelte
@@ -0,0 +1,137 @@
+<script lang="ts">
+  // Modal stack 지원 — confirm 위에 nested 모달을 쌓을 수 있다.
+  // z-index = z-modal + (stack 인덱스 * 2). backdrop / panel 둘 다 한 칸씩.
+  // 최상단 modal만 focus trap 활성, 아래는 inert 처리.
+  // native <dialog>를 쓰지 않는 이유: top-layer가 단일이라 stack을 지원하지 않음.
+  import type { Snippet } from 'svelte';
+  import { X } from 'lucide-svelte';
+  import { ui } from '$lib/stores/uiState.svelte';
+  import IconButton from './IconButton.svelte';
+
+  type Size = 'sm' | 'md' | 'lg';
+
+  interface Props {
+    id: string;
+    title?: string;
+    size?: Size;
+    closable?: boolean;
+    children?: Snippet;
+    footer?: Snippet;
+    'aria-label'?: string;
+  }
+
+  let {
+    id,
+    title,
+    size = 'md',
+    closable = true,
+    children,
+    footer,
+    'aria-label': ariaLabel,
+  }: Props = $props();
+
+  let open = $derived(ui.isModalOpen(id));
+  let stackIndex = $derived(ui.modalIndex(id));
+  let isTop = $derived(stackIndex === ui.modalStack.length - 1);
+
+  // z-index 계산: backdrop과 panel을 별개의 stacking context로 두기 위해 *2
+  let backdropZ = $derived(`calc(var(--z-modal) + ${stackIndex * 2})`);
+  let panelZ = $derived(`calc(var(--z-modal) + ${stackIndex * 2 + 1})`);
+
+  const sizeClass: Record<Size, string> = {
+    sm: 'max-w-sm',
+    md: 'max-w-md',
+    lg: 'max-w-2xl',
+  };
+
+  // 패널 ref + focus trap
+  let panelEl: HTMLDivElement | undefined = $state();
+
+  // open 토글 시: 열릴 때 패널 안 첫 focusable로 포커스 이동
+  $effect(() => {
+    if (!open || !isTop || !panelEl) return;
+    const focusables = panelEl.querySelectorAll<HTMLElement>(
+      'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
+    );
+    const first = focusables[0];
+    if (first) first.focus();
+  });
+
+  function close() {
+    if (closable) ui.closeModal(id);
+  }
+
+  // 최상단 modal 안에서만 Tab 사이클을 가둔다
+  function onKeydown(e: KeyboardEvent) {
+    if (!isTop || !panelEl) return;
+    if (e.key !== 'Tab') return;
+    const focusables = Array.from(
+      panelEl.querySelectorAll<HTMLElement>(
+        'button:not([disabled]), [href], input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])'
+      )
+    );
+    if (focusables.length === 0) return;
+    const first = focusables[0];
+    const last = focusables[focusables.length - 1];
+    if (e.shiftKey && document.activeElement === first) {
+      e.preventDefault();
+      last.focus();
+    } else if (!e.shiftKey && document.activeElement === last) {
+      e.preventDefault();
+      first.focus();
+    }
+  }
+</script>
+
+{#if open}
+  <!-- backdrop -->
+  <div
+    class="fixed inset-0 bg-scrim transition-opacity"
+    style="z-index: {backdropZ}"
+    aria-hidden="true"
+  ></div>
+
+  <!-- panel container (centers modal) -->
+  <div
+    class="fixed inset-0 flex items-center justify-center p-4"
+    style="z-index: {panelZ}"
+    role="dialog"
+    aria-modal="true"
+    aria-label={ariaLabel ?? title}
+    inert={!isTop ? true : undefined}
+    onkeydown={onKeydown}
+    tabindex="-1"
+  >
+    <div
+      bind:this={panelEl}
+      class={[
+        'w-full bg-surface border border-default rounded-card shadow-xl',
+        'flex flex-col max-h-[90vh]',
+        sizeClass[size],
+      ].join(' ')}
+    >
+      {#if title || closable}
+        <header class="flex items-center justify-between px-5 py-3 border-b border-default shrink-0">
+          {#if title}
+            <h2 class="text-sm font-semibold text-text">{title}</h2>
+          {:else}
+            <span></span>
+          {/if}
+          {#if closable}
+            <IconButton icon={X} aria-label="닫기" onclick={close} size="sm" />
+          {/if}
+        </header>
+      {/if}
+
+      <div class="flex-1 min-h-0 overflow-y-auto px-5 py-4 text-sm text-text">
+        {@render children?.()}
+      </div>
+
+      {#if footer}
+        <footer class="flex items-center justify-end gap-2 px-5 py-3 border-t border-default shrink-0">
+          {@render footer()}
+        </footer>
+      {/if}
+    </div>
+  </div>
+{/if}
diff --git a/frontend/src/lib/components/ui/Tabs.svelte b/frontend/src/lib/components/ui/Tabs.svelte
new file mode 100644
index 0000000..35cfe57
--- /dev/null
+++ b/frontend/src/lib/components/ui/Tabs.svelte
@@ -0,0 +1,111 @@
+<script lang="ts">
+  // ARIA tablist + tab + tabpanel. 좌우 화살표 키 nav.
+  // children snippet은 (activeId: string) => UI 시그니처로 받는다.
+  // 사용처:
+  //   <Tabs tabs={[{id:'edit',label:'편집'},{id:'preview',label:'미리보기'}]} bind:value={mode}>
+  //     {#snippet children(activeId)}
+  //       {#if activeId === 'edit'}<EditPanel />{/if}
+  //       {#if activeId === 'preview'}<PreviewPanel />{/if}
+  //     {/snippet}
+  //   </Tabs>
+  import type { Snippet } from 'svelte';
+
+  export interface Tab {
+    id: string;
+    label: string;
+    disabled?: boolean;
+  }
+
+  interface Props {
+    tabs: Tab[];
+    value?: string;
+    children?: Snippet<[string]>;
+    class?: string;
+  }
+
+  let { tabs, value = $bindable(tabs[0]?.id ?? ''), children, class: className = '' }: Props = $props();
+
+  const autoId = $props.id();
+
+  function tabId(id: string) {
+    return `tab-${autoId}-${id}`;
+  }
+  function panelId(id: string) {
+    return `panel-${autoId}-${id}`;
+  }
+
+  function select(id: string) {
+    if (tabs.find((t) => t.id === id)?.disabled) return;
+    value = id;
+  }
+
+  function onKeydown(e: KeyboardEvent) {
+    const enabled = tabs.filter((t) => !t.disabled);
+    const idx = enabled.findIndex((t) => t.id === value);
+    if (idx === -1) return;
+    if (e.key === 'ArrowRight') {
+      e.preventDefault();
+      const next = enabled[(idx + 1) % enabled.length];
+      select(next.id);
+      document.getElementById(tabId(next.id))?.focus();
+    } else if (e.key === 'ArrowLeft') {
+      e.preventDefault();
+      const prev = enabled[(idx - 1 + enabled.length) % enabled.length];
+      select(prev.id);
+      document.getElementById(tabId(prev.id))?.focus();
+    } else if (e.key === 'Home') {
+      e.preventDefault();
+      const first = enabled[0];
+      select(first.id);
+      document.getElementById(tabId(first.id))?.focus();
+    } else if (e.key === 'End') {
+      e.preventDefault();
+      const last = enabled[enabled.length - 1];
+      select(last.id);
+      document.getElementById(tabId(last.id))?.focus();
+    }
+  }
+</script>
+
+<div class={className}>
+  <div
+    role="tablist"
+    tabindex="-1"
+    class="flex items-center gap-1 border-b border-default"
+    onkeydown={onKeydown}
+  >
+    {#each tabs as tab (tab.id)}
+      {@const active = tab.id === value}
+      <button
+        type="button"
+        role="tab"
+        id={tabId(tab.id)}
+        aria-selected={active}
+        aria-controls={panelId(tab.id)}
+        tabindex={active ? 0 : -1}
+        disabled={tab.disabled}
+        onclick={() => select(tab.id)}
+        class={[
+          'px-3 h-9 text-sm font-medium border-b-2 -mb-px transition-colors',
+          'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent-ring rounded-t',
+          active
+            ? 'text-accent border-accent'
+            : 'text-dim border-transparent hover:text-text',
+          tab.disabled ? 'opacity-50 cursor-not-allowed' : '',
+        ].join(' ')}
+      >
+        {tab.label}
+      </button>
+    {/each}
+  </div>
+
+  <div
+    role="tabpanel"
+    id={panelId(value)}
+    aria-labelledby={tabId(value)}
+    tabindex="0"
+    class="focus-visible:outline-none"
+  >
+    {@render children?.(value)}
+  </div>
+</div>