@usethink/cf-admin-fe 0.1.0

package/README.md

@@ -0,0 +1,104 @@
+# @usethink/cf-admin-fe
+
+Vue 3 **admin foundation** for the Cloudflare product family (`cf-shop`, `cf-lottery`, future CF admin apps).
+
+This package is the **frontend** counterpart to backend `@usethink/cf-core`:
+
+| Layer | Package | Contents |
+|---|---|---|
+| Workers / infra | `@usethink/cf-core` | HTTP, crypto, media, secrets, … |
+| Admin UI kit | **`@usethink/cf-admin-fe`** | Composables, shell components, admin CSS tokens |
+
+
+## Why `cf-admin-fe` (not `cf-admin`)
+
+This package is **frontend-only**. The `-fe` suffix makes that explicit next to backend `@usethink/cf-core`, so operators never confuse UI kit code with Worker/API infrastructure.
+
+**Not** a business mid-tier: no orders, lottery draws, RBAC pages, or payment UIs.
+
+## Install
+
+```bash
+# monorepo / sibling template (recommended during development)
+npm install file:../cf-admin-fe
+
+# or once published
+npm install @usethink/cf-admin-fe
+```
+
+Peer: `vue` ^3.4.
+
+## Quick start (new admin app)
+
+```ts
+// main.ts
+import { createApp } from 'vue'
+import App from './App.vue'
+import '@usethink/cf-admin-fe/styles' // tokens + admin primitives
+
+createApp(App).mount('#app')
+```
+
+```vue
+<script setup lang="ts">
+import {
+  useTablePagination,
+  useTableSelection,
+  useConfirmDialog,
+  useToast,
+  useAdminBatchOperation,
+} from '@usethink/cf-admin-fe'
+import {
+  AdminPagination,
+  ConfirmDialog,
+  ToastContainer,
+  AdminModal,
+} from '@usethink/cf-admin-fe/components'
+</script>
+```
+
+Products may keep thin re-exports under `@/composables/*` so existing views do not mass-rewrite.
+
+## Public surface
+
+### Composables (`@usethink/cf-admin-fe` or `/composables`)
+
+- `useTablePagination` — page/limit/total/offset
+- `useTableSelection` — multi-select + shift range
+- `useConfirmDialog` — confirm + optional checkboxes
+- `useToast` / `MAX_TOASTS` — global toast queue
+- `useAdminBatchOperation` — sequential batch with progress
+- `writeClipboardText` / `copyText` — clipboard helpers
+
+### Components (`@usethink/cf-admin-fe/components`)
+
+- `AdminPagination`, `AdminModal`, `ConfirmDialog`, `ToastContainer`
+
+Components use `$t(...)` for labels when `vue-i18n` is present; provide the usual keys (`pagination.*`, `confirm.*`, `adminModal.*`) in the host app.
+
+### Styles
+
+```ts
+import '@usethink/cf-admin-fe/styles'
+// or granular:
+import '@usethink/cf-admin-fe/styles/tokens.css'
+import '@usethink/cf-admin-fe/styles/admin-primitives.css'
+```
+
+## What stays in the product
+
+- Domain admin **pages** (`views/admin/*`)
+- Auth/session composables, API clients, ConfigField registries
+- Product-only CSS beyond the shared primitives
+
+## Develop
+
+```bash
+npm install
+npm test
+npm run type-check
+```
+
+## License
+
+MIT

package/dist/components/index.d.ts

@@ -0,0 +1,4 @@
+export { default as AdminPagination } from './AdminPagination.vue';
+export { default as AdminModal } from './AdminModal.vue';
+export { default as ConfirmDialog } from './ConfirmDialog.vue';
+export { default as ToastContainer } from './ToastContainer.vue';

package/dist/composables/index.d.ts

@@ -0,0 +1,6 @@
+export { useTablePagination, type UseTablePaginationOptions, type UseTablePaginationReturn, } from './useTablePagination';
+export { useTableSelection, type UseTableSelectionOptions, } from './useTableSelection';
+export { useConfirmDialog, type ConfirmOptionDef, type ConfirmAskOptions, type ConfirmResult, } from './useConfirmDialog';
+export { useToast, MAX_TOASTS, type ToastType, type ToastItem, } from './useToast';
+export { useAdminBatchOperation, type AdminBatchOperationResult, } from './useAdminBatchOperation';
+export { writeClipboardText, copyText, } from './useClipboard';

package/dist/composables/useAdminBatchOperation.d.ts

@@ -0,0 +1,12 @@
+export interface AdminBatchOperationResult<T> {
+    total: number;
+    success: number;
+    failed: number;
+    failedItems: T[];
+}
+export declare function useAdminBatchOperation(): {
+    operating: import("vue").Ref<boolean, boolean>;
+    completed: import("vue").Ref<number, number>;
+    total: import("vue").Ref<number, number>;
+    runSequential: <T>(items: T[], action: (item: T) => Promise<void>) => Promise<AdminBatchOperationResult<T> | null>;
+};

package/dist/composables/useClipboard.d.ts

@@ -0,0 +1,4 @@
+/** 剪贴板工具：一键复制文本到剪贴板，带按钮视觉反馈 */
+/** 复制文本，更新按钮文字反馈 */
+export declare function writeClipboardText(text: string): Promise<void>;
+export declare function copyText(text: string, e: Event): void;

package/dist/composables/useConfirmDialog.d.ts

@@ -0,0 +1,43 @@
+export type ConfirmOptionDef = {
+    key: string;
+    label: string;
+    /** 补充说明，显示在 label 下方 */
+    hint?: string;
+    /** 默认 false */
+    defaultChecked?: boolean;
+};
+export type ConfirmAskOptions = {
+    /** 危险操作样式（红按钮），由调用方通过 ConfirmDialog danger prop 控制亦可 */
+    danger?: boolean;
+    /** 可选勾选项，默认全部未勾选；打开弹窗时按 defaultChecked 重置 */
+    options?: ConfirmOptionDef[];
+};
+export type ConfirmResult = {
+    confirmed: boolean;
+    /** key → 是否勾选；取消时各值为 defaultChecked（调用方应以 confirmed 为准） */
+    options: Record<string, boolean>;
+};
+export declare function useConfirmDialog(): {
+    confirmVisible: import("vue").Ref<boolean, boolean>;
+    confirmMessage: import("vue").Ref<string, string>;
+    confirmOptionDefs: import("vue").Ref<{
+        key: string;
+        label: string;
+        hint?: string
+        /** 默认 false */
+         | undefined;
+        defaultChecked?: boolean | undefined;
+    }[], ConfirmOptionDef[] | {
+        key: string;
+        label: string;
+        hint?: string
+        /** 默认 false */
+         | undefined;
+        defaultChecked?: boolean | undefined;
+    }[]>;
+    confirmOptionValues: import("vue").Ref<Record<string, boolean>, Record<string, boolean>>;
+    askConfirm: (message: string) => Promise<boolean>;
+    askConfirmWithOptions: (message: string, options?: ConfirmAskOptions) => Promise<ConfirmResult>;
+    onConfirm: () => void;
+    setConfirmOption: (key: string, checked: boolean) => void;
+};

package/dist/composables/useTablePagination.d.ts

@@ -0,0 +1,19 @@
+import { type Ref, type ComputedRef } from 'vue';
+export interface UseTablePaginationOptions {
+    initialPage?: number;
+    initialLimit?: number;
+}
+export interface UseTablePaginationReturn {
+    page: Ref<number>;
+    limit: Ref<number>;
+    total: Ref<number>;
+    totalPages: ComputedRef<number>;
+    setPage: (page: number) => void;
+    setLimit: (limit: number) => void;
+    setTotal: (total: number) => boolean;
+    nextPage: () => void;
+    prevPage: () => void;
+    reset: () => void;
+    offset: ComputedRef<number>;
+}
+export declare function useTablePagination(options?: UseTablePaginationOptions): UseTablePaginationReturn;

package/dist/composables/useTableSelection.d.ts

@@ -0,0 +1,20 @@
+import { type MaybeRef } from 'vue';
+export interface UseTableSelectionOptions<T> {
+    isSelectable?: (row: T) => boolean;
+}
+/**
+ * Accepts Ref or ComputedRef of row lists (MaybeRef) so product views can pass
+ * filtered computed tables without dual-package Ref assignability friction.
+ */
+export declare function useTableSelection<T>(rows: MaybeRef<T[]>, getKey: (row: T) => string, options?: UseTableSelectionOptions<T>): {
+    selectedIds: import("vue").Ref<string[], string[]>;
+    selectedSet: import("vue").ComputedRef<Set<string>>;
+    selectedCount: import("vue").ComputedRef<number>;
+    selectableCount: import("vue").ComputedRef<number>;
+    allVisibleSelected: import("vue").ComputedRef<boolean>;
+    partiallySelected: import("vue").ComputedRef<boolean>;
+    isSelected: (id: string) => boolean;
+    setSelected: (id: string, checked: boolean, extendRange?: boolean) => void;
+    toggleAllVisible: (checked: boolean) => void;
+    clearSelection: () => void;
+};

package/dist/composables/useToast.d.ts

@@ -0,0 +1,22 @@
+export type ToastType = 'success' | 'error' | 'info';
+export type ToastItem = {
+    id: number;
+    message: string;
+    type: ToastType;
+};
+/** Max stacked toasts; older entries drop when exceeded (lottery hardening). */
+export declare const MAX_TOASTS = 5;
+declare function showToast(message: string, type?: ToastType, duration?: number): void;
+export declare function useToast(): {
+    toasts: import("vue").Ref<{
+        id: number;
+        message: string;
+        type: ToastType;
+    }[], ToastItem[] | {
+        id: number;
+        message: string;
+        type: ToastType;
+    }[]>;
+    showToast: typeof showToast;
+};
+export {};

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @usethink/cf-admin — Vue 3 admin foundation for CF product family.
+ *
+ * Import composables from root or `@usethink/cf-admin/composables`.
+ * Import components from `@usethink/cf-admin/components`.
+ * Import styles: `import '@usethink/cf-admin/styles'`.
+ */
+export { useTablePagination, type UseTablePaginationOptions, type UseTablePaginationReturn, } from './composables/useTablePagination.ts';
+export { useTableSelection, type UseTableSelectionOptions, } from './composables/useTableSelection.ts';
+export { useConfirmDialog, type ConfirmOptionDef, type ConfirmAskOptions, type ConfirmResult, } from './composables/useConfirmDialog.ts';
+export { useToast, MAX_TOASTS, type ToastType, type ToastItem, } from './composables/useToast.ts';
+export { useAdminBatchOperation, type AdminBatchOperationResult, } from './composables/useAdminBatchOperation.ts';
+export { writeClipboardText, copyText, } from './composables/useClipboard.ts';
+export { default as AdminPagination } from './components/AdminPagination.vue';
+export { default as AdminModal } from './components/AdminModal.vue';
+export { default as ConfirmDialog } from './components/ConfirmDialog.vue';
+export { default as ToastContainer } from './components/ToastContainer.vue';

package/package.json

@@ -0,0 +1,84 @@
+{
+  "name": "@usethink/cf-admin-fe",
+  "version": "0.1.0",
+  "description": "Vue 3 frontend admin kit for CF product family \u2014 composables, shell components, design tokens (FE only; not cf-core)",
+  "type": "module",
+  "private": false,
+  "files": [
+    "src",
+    "dist",
+    "README.md"
+  ],
+  "main": "./src/index.ts",
+  "module": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./composables": {
+      "types": "./src/composables/index.ts",
+      "import": "./src/composables/index.ts"
+    },
+    "./components": {
+      "types": "./src/components/index.ts",
+      "import": "./src/components/index.ts"
+    },
+    "./styles": "./src/styles/index.css",
+    "./styles/tokens.css": "./src/styles/tokens.css",
+    "./styles/admin-primitives.css": "./src/styles/admin-primitives.css",
+    "./package.json": "./package.json",
+    "./components/AdminPagination.vue": "./src/components/AdminPagination.vue",
+    "./components/AdminModal.vue": "./src/components/AdminModal.vue",
+    "./components/ConfirmDialog.vue": "./src/components/ConfirmDialog.vue",
+    "./components/ToastContainer.vue": "./src/components/ToastContainer.vue"
+  },
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "peerDependencies": {
+    "vue": "^3.4.0"
+  },
+  "peerDependenciesMeta": {
+    "vue-i18n": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@vitejs/plugin-vue": "^5.2.1",
+    "typescript": "^5.7.2",
+    "vite": "^6.0.0",
+    "vitest": "^3.0.0",
+    "vue": "^3.5.39",
+    "vue-tsc": "^2.1.10"
+  },
+  "scripts": {
+    "type-check": "tsc --noEmit && vue-tsc --noEmit -p tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "build": "tsc -p tsconfig.build.json"
+  },
+  "keywords": [
+    "admin",
+    "cf-admin-fe",
+    "cloudflare",
+    "composables",
+    "frontend",
+    "vue3"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/qwdingyu/cf-admin-fe.git"
+  },
+  "bugs": {
+    "url": "https://github.com/qwdingyu/cf-admin-fe/issues"
+  },
+  "homepage": "https://github.com/qwdingyu/cf-admin-fe#readme",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/src/components/AdminModal.vue

@@ -0,0 +1,193 @@
+<template>
+  <div v-if="modelValue" class="modal-mask" @click.self="handleBackdropClick">
+    <div
+      ref="modalRef"
+      class="modal"
+      :style="{ maxWidth }"
+      role="dialog"
+      aria-modal="true"
+      :aria-labelledby="title ? titleId : undefined"
+      :aria-label="$t('adminModal.title')"
+      tabindex="-1"
+      @keydown="handleKeydown"
+    >
+      <h3 v-if="title" :id="titleId" class="modal-title">{{ title }}</h3>
+      <div ref="bodyRef" class="modal-body">
+        <slot />
+      </div>
+      <div v-if="$slots.actions || !hideActions" class="modal-actions">
+        <slot name="actions">
+          <button type="button" class="btn btn-ghost" @click="close">{{ $t('adminModal.close') }}</button>
+        </slot>
+      </div>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { nextTick, onBeforeUnmount, ref, useId, watch } from 'vue'
+
+const props = withDefaults(defineProps<{
+  modelValue: boolean
+  title?: string
+  maxWidth?: string
+  hideActions?: boolean
+  closeOnBackdrop?: boolean
+  closeOnEscape?: boolean
+}>(), {
+  hideActions: false,
+  closeOnBackdrop: false,
+  closeOnEscape: false,
+})
+
+const emit = defineEmits<{
+  'update:modelValue': [value: boolean]
+}>()
+
+const modalRef = ref<HTMLElement | null>(null)
+const bodyRef = ref<HTMLElement | null>(null)
+const titleId = `admin-modal-title-${useId()}`
+let restoreFocus: HTMLElement | null = null
+
+function close() {
+  emit('update:modelValue', false)
+}
+
+function handleBackdropClick() {
+  if (props.closeOnBackdrop) close()
+}
+
+function getFocusableElements() {
+  return Array.from(modalRef.value?.querySelectorAll<HTMLElement>(
+    'button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), a[href], [tabindex]:not([tabindex="-1"])',
+  ) || [])
+}
+
+function handleKeydown(event: KeyboardEvent) {
+  if (event.key === 'Escape') {
+    if (!props.closeOnEscape) return
+    event.preventDefault()
+    close()
+    return
+  }
+  if (event.key !== 'Tab') return
+
+  const focusable = getFocusableElements()
+  if (focusable.length === 0) {
+    event.preventDefault()
+    modalRef.value?.focus()
+    return
+  }
+
+  const first = focusable[0]
+  const last = focusable[focusable.length - 1]
+  if (event.shiftKey && (document.activeElement === first || document.activeElement === modalRef.value)) {
+    event.preventDefault()
+    last.focus()
+  } else if (!event.shiftKey && document.activeElement === last) {
+    event.preventDefault()
+    first.focus()
+  }
+}
+
+watch(() => props.modelValue, async (visible, wasVisible) => {
+  if (visible && !wasVisible) {
+    restoreFocus = document.activeElement instanceof HTMLElement ? document.activeElement : null
+    await nextTick()
+    // 长详情中的第一个按钮通常位于正文底部；若直接聚焦它，浏览器会把滚动区自动拉到底部。
+    // 打开时先回到正文顶部并聚焦对话框容器，用户可以从订单基本信息开始阅读，再用 Tab 进入控件。
+    if (bodyRef.value) bodyRef.value.scrollTop = 0
+    modalRef.value?.focus({ preventScroll: true })
+  } else if (!visible && wasVisible) {
+    restoreFocus?.focus()
+    restoreFocus = null
+  }
+})
+
+onBeforeUnmount(() => {
+  restoreFocus?.focus()
+})
+</script>
+
+<style scoped>
+.modal-mask {
+  position: fixed;
+  inset: 0;
+  background: var(--overlay, rgba(0, 0, 0, 0.55));
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 24px;
+  overflow: hidden;
+  z-index: 200;
+  backdrop-filter: saturate(180%) blur(10px);
+  -webkit-backdrop-filter: saturate(180%) blur(10px);
+}
+
+.modal {
+  box-sizing: border-box;
+  width: 100%;
+  max-height: calc(100dvh - 48px);
+  min-height: 0;
+  display: flex;
+  flex-direction: column;
+  /* 比页面底略抬一层，避免与遮罩糊成一团 */
+  background: var(--tg-secondary-bg, #151b28);
+  color: var(--tg-text);
+  border-radius: var(--r-lg, 12px);
+  padding: 22px;
+  border: 1px solid var(--border-strong, rgba(255, 255, 255, 0.16));
+  box-shadow: var(--shadow-lg, 0 20px 50px rgba(0, 0, 0, 0.45));
+  /* 勿用 overflow:hidden：会裁切 :focus-visible 描边（控件四边显示不全） */
+  overflow: visible;
+}
+
+.modal-title {
+  flex: 0 0 auto;
+  margin: 0 0 16px;
+  font-size: 18px;
+  font-weight: 650;
+  letter-spacing: 0.01em;
+  color: var(--tg-text);
+  line-height: 1.35;
+}
+
+.modal-body {
+  min-height: 0;
+  flex: 1 1 auto;
+  display: flex;
+  flex-direction: column;
+  gap: 14px;
+  overflow-x: visible;
+  overflow-y: auto;
+  overscroll-behavior: contain;
+  /* 给 focus 描边（outline-offset: 2px）留出左右上下内边距，避免被滚动裁切 */
+  padding: 4px 6px 6px;
+  margin: -4px -6px -6px;
+  scrollbar-gutter: stable;
+}
+
+/* 子级 form 需要吃满高度时（如商品编辑粘性脚部） */
+.modal-body > form {
+  min-height: 0;
+}
+
+.modal-actions {
+  flex: 0 0 auto;
+  display: flex;
+  justify-content: flex-end;
+  gap: 10px;
+  margin-top: 14px;
+}
+
+@media (max-width: 640px) {
+  .modal-mask {
+    padding: 12px;
+  }
+
+  .modal {
+    max-height: calc(100dvh - 24px);
+    padding: 16px;
+  }
+}
+</style>