@withwiz/gallery 0.1.0

package/dist/components/index.d.mts

@@ -0,0 +1,156 @@
+import { JSX, ReactNode } from 'react';
+import { GalleryI18nKey, GallerySlotName, GalleryListItem, GalleryCategoryItem, CreateGalleryInput, UpdateGalleryInput } from '../types/index.mjs';
+import 'next/server';
+
+interface ToggleSwitchProps {
+    checked: boolean;
+    onChange: (next: boolean) => void;
+    disabled?: boolean;
+    /** aria-label 및 시각적 라벨로 모두 사용 (지정 시 옆에 텍스트 노출). */
+    label?: string;
+    /** size 클래스 — gallery.css 의 `.gallery-toggle--sm/--md/--lg`. 기본 "md". */
+    size?: "sm" | "md" | "lg";
+    className?: string;
+}
+/** 접근성 - 키보드 정책:
+ *  - role="switch" + aria-checked
+ *  - Space / Enter 키로 toggle
+ *  - disabled 시 모든 인터랙션 차단 + aria-disabled
+ *
+ *  CSS:
+ *  - `.gallery-toggle` 기본 컨테이너
+ *  - `.gallery-toggle--checked` / `--disabled` modifier
+ *  - `.gallery-toggle--sm/--md/--lg` size modifier
+ *  - `.gallery-toggle__track` / `__thumb` element classes
+ *  - `.gallery-toggle__label` element class (label 텍스트)
+ */
+declare function ToggleSwitch(props: ToggleSwitchProps): JSX.Element;
+
+interface ImageDropZoneProps {
+    onFiles: (files: File[]) => void | Promise<void>;
+    accept?: string[];
+    maxSize?: number;
+    multiple?: boolean;
+    disabled?: boolean;
+    /** 현재 표시할 미리보기 이미지 URL (선택). null/undefined 면 placeholder 표시. */
+    previewUrl?: string | null;
+    /** i18n 키 미주입 시 fallback 텍스트. host 의 i18n 시스템과 무관. */
+    i18n?: {
+        dropPrompt?: string;
+        replacePrompt?: string;
+        rejected?: string;
+    };
+    className?: string;
+}
+/** primitive UI 드롭존. useImageDropZone hook 위에 얹은 thin component.
+ *
+ *  - 클릭 시 hidden `<input type="file">` 트리거
+ *  - previewUrl 있으면 이미지 표시 + replace 안내
+ *  - isDragging 상태에서 `.gallery-dropzone--dragging` 클래스
+ *  - rejectedReasons 가 있으면 `.gallery-dropzone__rejected` 영역 표시
+ */
+declare function ImageDropZone(props: ImageDropZoneProps): JSX.Element;
+
+interface GalleryManagerLayoutProps {
+    /** 좌측 페인 — 호스트가 렌더하는 갤러리 목록. */
+    listRoot: ReactNode;
+    /** 좌측 페인 상단 필터/검색 컨트롤 (선택). */
+    filterControls?: ReactNode;
+    /** 좌측 페인 위의 툴바 — bulk actions 등 (선택). */
+    toolbar?: ReactNode;
+    /** 중앙 페인 — 편집 폼. null 이면 emptyState 사용. */
+    editForm: ReactNode | null;
+    /** editForm 이 null 일 때 표시할 컨텐츠 (미주입 시 i18n fallback). */
+    emptyState?: ReactNode;
+    /** 우측 페인 — 홈 프리뷰 (선택). 미주입 시 우측 영역 자체가 렌더되지 않음. */
+    homePreview?: ReactNode;
+    className?: string;
+    /** i18n key fallback (영문). */
+    i18n?: Partial<Record<GalleryI18nKey, string>>;
+    /** 호스트 customization 지점. slots 가 같은 키의 ReactNode prop 보다 우선. */
+    ui?: {
+        classNames?: Partial<Record<GallerySlotName, string>>;
+        slots?: Partial<Record<GallerySlotName, ReactNode>>;
+    };
+}
+/** Gallery admin 의 3-페인 레이아웃. AdminManagerBase 의존 없는 self-contained.
+ *
+ *  - 좌측: toolbar + filterControls + listRoot
+ *  - 중앙: editForm (없으면 emptyState / i18n fallback)
+ *  - 우측: homePreview (미주입 시 영역 자체 없음 → grid 2-cols)
+ *
+ *  slot 우선순위:
+ *    ui.slots[name] > 같은 의미의 props (toolbar/filterControls/listRoot 등) > fallback
+ *  className 병합:
+ *    ui.classNames[name] 이 해당 slot wrapper 의 className 에 추가됨.
+ */
+declare function GalleryManagerLayout(props: GalleryManagerLayoutProps): JSX.Element;
+
+interface GalleryEditFormProps {
+    /** 편집 대상. null 이면 새로 생성 모드. */
+    value: GalleryListItem | null;
+    categories: GalleryCategoryItem[];
+    onSubmit: (data: CreateGalleryInput | UpdateGalleryInput) => void | Promise<void>;
+    onCancel?: () => void;
+    onDelete?: () => void | Promise<void>;
+    /** 다중 모드 (새 모드 + 여러 이미지). onSubmitMany 가 함께 주입되어야 동작. */
+    multipleMode?: boolean;
+    onSubmitMany?: (items: CreateGalleryInput[]) => void | Promise<void>;
+    /** featured 토글 가능 여부. false 이고 현재 미선택 상태이면 토글 비활성. true 이면 자유. */
+    canToggleFeatured?: boolean;
+    saving?: boolean;
+    /** 새 모드에서 이미지 파일을 host 가 업로드하고 그 결과 URL 을 반환. 미주입 시 ObjectURL preview 만 가능. */
+    onImageSelect?: (file: File) => Promise<{
+        url: string;
+        key?: string;
+    }>;
+    i18n?: Partial<Record<GalleryI18nKey, string>>;
+    className?: string;
+}
+/** Gallery admin edit form — self-contained.
+ *
+ *  단일 모드: 1 image + 메타. value.imageUrl 이 비어있으면 새 이미지를 onImageSelect 로 업로드.
+ *  다중 모드 (multipleMode + value=null): 여러 이미지를 자동 caption suffix + sortOrder auto-increment 로 일괄 생성.
+ */
+declare function GalleryEditForm(props: GalleryEditFormProps): JSX.Element;
+
+interface GalleryHomePreviewProps {
+    /** 표시할 항목들 — 호출자가 published & featured 필터 + 정렬을 마친 상태. */
+    items: GalleryListItem[];
+    /** 모자이크 셀 개수 (host config.limits.mosaicCount). */
+    maxCount: number;
+    /** drag-and-drop 으로 재정렬된 결과를 통보. orderedIds 의 길이 = 현재 보이는 items 수. */
+    onReorder: (orderedIds: string[]) => void | Promise<void>;
+    /** ★ 토글. next = 현재 featured 의 반대값. */
+    onToggleFeatured: (id: string, next: boolean) => void | Promise<void>;
+    i18n?: Partial<Record<GalleryI18nKey, string>>;
+    className?: string;
+}
+/** 어드민 홈 프리뷰 — 모자이크 그리드 + HTML5 drag swap + 별 토글.
+ *
+ *  drag 동작:
+ *    1. dragStart 에서 dragIndex 기록
+ *    2. dragOver 에서 dragOverIndex 기록 (visual highlight 용)
+ *    3. drop 시 dragIndex 와 drop target index 가 다르면 swap 후 onReorder
+ *
+ *  키보드 접근성은 v0.2 — 현재는 mouse 만.
+ */
+declare function GalleryHomePreview(props: GalleryHomePreviewProps): JSX.Element;
+
+interface GalleryAdminManagerProps {
+    /** 초기 mode (라우트에서 결정). undefined = list view. */
+    initialMode?: "list" | "new" | "edit";
+    /** 편집 대상 ID (initialMode === "edit" 또는 URL 진입 시). */
+    initialSelectedId?: string;
+    className?: string;
+}
+/** 메인 마운트 포인트. host 의 페이지는 단순히 `<GalleryAdminManager initialSelectedId={id} />` 마운트. */
+declare function GalleryAdminManager(props: GalleryAdminManagerProps): JSX.Element;
+
+interface CategoryAdminManagerProps {
+    className?: string;
+}
+/** 카테고리 어드민 UI. 사용 중인 카테고리는 server 가 409 로 반환 → 안내 표시. */
+declare function CategoryAdminManager(props: CategoryAdminManagerProps): JSX.Element;
+
+export { CategoryAdminManager, type CategoryAdminManagerProps, GalleryAdminManager, type GalleryAdminManagerProps, GalleryEditForm, type GalleryEditFormProps, GalleryHomePreview, type GalleryHomePreviewProps, GalleryManagerLayout, type GalleryManagerLayoutProps, ImageDropZone, type ImageDropZoneProps, ToggleSwitch, type ToggleSwitchProps };

package/dist/components/index.d.ts

@@ -0,0 +1,156 @@
+import { JSX, ReactNode } from 'react';
+import { GalleryI18nKey, GallerySlotName, GalleryListItem, GalleryCategoryItem, CreateGalleryInput, UpdateGalleryInput } from '../types/index.js';
+import 'next/server';
+
+interface ToggleSwitchProps {
+    checked: boolean;
+    onChange: (next: boolean) => void;
+    disabled?: boolean;
+    /** aria-label 및 시각적 라벨로 모두 사용 (지정 시 옆에 텍스트 노출). */
+    label?: string;
+    /** size 클래스 — gallery.css 의 `.gallery-toggle--sm/--md/--lg`. 기본 "md". */
+    size?: "sm" | "md" | "lg";
+    className?: string;
+}
+/** 접근성 - 키보드 정책:
+ *  - role="switch" + aria-checked
+ *  - Space / Enter 키로 toggle
+ *  - disabled 시 모든 인터랙션 차단 + aria-disabled
+ *
+ *  CSS:
+ *  - `.gallery-toggle` 기본 컨테이너
+ *  - `.gallery-toggle--checked` / `--disabled` modifier
+ *  - `.gallery-toggle--sm/--md/--lg` size modifier
+ *  - `.gallery-toggle__track` / `__thumb` element classes
+ *  - `.gallery-toggle__label` element class (label 텍스트)
+ */
+declare function ToggleSwitch(props: ToggleSwitchProps): JSX.Element;
+
+interface ImageDropZoneProps {
+    onFiles: (files: File[]) => void | Promise<void>;
+    accept?: string[];
+    maxSize?: number;
+    multiple?: boolean;
+    disabled?: boolean;
+    /** 현재 표시할 미리보기 이미지 URL (선택). null/undefined 면 placeholder 표시. */
+    previewUrl?: string | null;
+    /** i18n 키 미주입 시 fallback 텍스트. host 의 i18n 시스템과 무관. */
+    i18n?: {
+        dropPrompt?: string;
+        replacePrompt?: string;
+        rejected?: string;
+    };
+    className?: string;
+}
+/** primitive UI 드롭존. useImageDropZone hook 위에 얹은 thin component.
+ *
+ *  - 클릭 시 hidden `<input type="file">` 트리거
+ *  - previewUrl 있으면 이미지 표시 + replace 안내
+ *  - isDragging 상태에서 `.gallery-dropzone--dragging` 클래스
+ *  - rejectedReasons 가 있으면 `.gallery-dropzone__rejected` 영역 표시
+ */
+declare function ImageDropZone(props: ImageDropZoneProps): JSX.Element;
+
+interface GalleryManagerLayoutProps {
+    /** 좌측 페인 — 호스트가 렌더하는 갤러리 목록. */
+    listRoot: ReactNode;
+    /** 좌측 페인 상단 필터/검색 컨트롤 (선택). */
+    filterControls?: ReactNode;
+    /** 좌측 페인 위의 툴바 — bulk actions 등 (선택). */
+    toolbar?: ReactNode;
+    /** 중앙 페인 — 편집 폼. null 이면 emptyState 사용. */
+    editForm: ReactNode | null;
+    /** editForm 이 null 일 때 표시할 컨텐츠 (미주입 시 i18n fallback). */
+    emptyState?: ReactNode;
+    /** 우측 페인 — 홈 프리뷰 (선택). 미주입 시 우측 영역 자체가 렌더되지 않음. */
+    homePreview?: ReactNode;
+    className?: string;
+    /** i18n key fallback (영문). */
+    i18n?: Partial<Record<GalleryI18nKey, string>>;
+    /** 호스트 customization 지점. slots 가 같은 키의 ReactNode prop 보다 우선. */
+    ui?: {
+        classNames?: Partial<Record<GallerySlotName, string>>;
+        slots?: Partial<Record<GallerySlotName, ReactNode>>;
+    };
+}
+/** Gallery admin 의 3-페인 레이아웃. AdminManagerBase 의존 없는 self-contained.
+ *
+ *  - 좌측: toolbar + filterControls + listRoot
+ *  - 중앙: editForm (없으면 emptyState / i18n fallback)
+ *  - 우측: homePreview (미주입 시 영역 자체 없음 → grid 2-cols)
+ *
+ *  slot 우선순위:
+ *    ui.slots[name] > 같은 의미의 props (toolbar/filterControls/listRoot 등) > fallback
+ *  className 병합:
+ *    ui.classNames[name] 이 해당 slot wrapper 의 className 에 추가됨.
+ */
+declare function GalleryManagerLayout(props: GalleryManagerLayoutProps): JSX.Element;
+
+interface GalleryEditFormProps {
+    /** 편집 대상. null 이면 새로 생성 모드. */
+    value: GalleryListItem | null;
+    categories: GalleryCategoryItem[];
+    onSubmit: (data: CreateGalleryInput | UpdateGalleryInput) => void | Promise<void>;
+    onCancel?: () => void;
+    onDelete?: () => void | Promise<void>;
+    /** 다중 모드 (새 모드 + 여러 이미지). onSubmitMany 가 함께 주입되어야 동작. */
+    multipleMode?: boolean;
+    onSubmitMany?: (items: CreateGalleryInput[]) => void | Promise<void>;
+    /** featured 토글 가능 여부. false 이고 현재 미선택 상태이면 토글 비활성. true 이면 자유. */
+    canToggleFeatured?: boolean;
+    saving?: boolean;
+    /** 새 모드에서 이미지 파일을 host 가 업로드하고 그 결과 URL 을 반환. 미주입 시 ObjectURL preview 만 가능. */
+    onImageSelect?: (file: File) => Promise<{
+        url: string;
+        key?: string;
+    }>;
+    i18n?: Partial<Record<GalleryI18nKey, string>>;
+    className?: string;
+}
+/** Gallery admin edit form — self-contained.
+ *
+ *  단일 모드: 1 image + 메타. value.imageUrl 이 비어있으면 새 이미지를 onImageSelect 로 업로드.
+ *  다중 모드 (multipleMode + value=null): 여러 이미지를 자동 caption suffix + sortOrder auto-increment 로 일괄 생성.
+ */
+declare function GalleryEditForm(props: GalleryEditFormProps): JSX.Element;
+
+interface GalleryHomePreviewProps {
+    /** 표시할 항목들 — 호출자가 published & featured 필터 + 정렬을 마친 상태. */
+    items: GalleryListItem[];
+    /** 모자이크 셀 개수 (host config.limits.mosaicCount). */
+    maxCount: number;
+    /** drag-and-drop 으로 재정렬된 결과를 통보. orderedIds 의 길이 = 현재 보이는 items 수. */
+    onReorder: (orderedIds: string[]) => void | Promise<void>;
+    /** ★ 토글. next = 현재 featured 의 반대값. */
+    onToggleFeatured: (id: string, next: boolean) => void | Promise<void>;
+    i18n?: Partial<Record<GalleryI18nKey, string>>;
+    className?: string;
+}
+/** 어드민 홈 프리뷰 — 모자이크 그리드 + HTML5 drag swap + 별 토글.
+ *
+ *  drag 동작:
+ *    1. dragStart 에서 dragIndex 기록
+ *    2. dragOver 에서 dragOverIndex 기록 (visual highlight 용)
+ *    3. drop 시 dragIndex 와 drop target index 가 다르면 swap 후 onReorder
+ *
+ *  키보드 접근성은 v0.2 — 현재는 mouse 만.
+ */
+declare function GalleryHomePreview(props: GalleryHomePreviewProps): JSX.Element;
+
+interface GalleryAdminManagerProps {
+    /** 초기 mode (라우트에서 결정). undefined = list view. */
+    initialMode?: "list" | "new" | "edit";
+    /** 편집 대상 ID (initialMode === "edit" 또는 URL 진입 시). */
+    initialSelectedId?: string;
+    className?: string;
+}
+/** 메인 마운트 포인트. host 의 페이지는 단순히 `<GalleryAdminManager initialSelectedId={id} />` 마운트. */
+declare function GalleryAdminManager(props: GalleryAdminManagerProps): JSX.Element;
+
+interface CategoryAdminManagerProps {
+    className?: string;
+}
+/** 카테고리 어드민 UI. 사용 중인 카테고리는 server 가 409 로 반환 → 안내 표시. */
+declare function CategoryAdminManager(props: CategoryAdminManagerProps): JSX.Element;
+
+export { CategoryAdminManager, type CategoryAdminManagerProps, GalleryAdminManager, type GalleryAdminManagerProps, GalleryEditForm, type GalleryEditFormProps, GalleryHomePreview, type GalleryHomePreviewProps, GalleryManagerLayout, type GalleryManagerLayoutProps, ImageDropZone, type ImageDropZoneProps, ToggleSwitch, type ToggleSwitchProps };