create-bubbles 0.1.25 → 0.1.27

package/template-vp-monorepo-react-nestjs/apps/web/src/components/RouteTransition/RouteTransition.tsx

@@ -0,0 +1,44 @@
+import './RouteTransition.css'
+
+/** 为已提交的新路由播放页面区域滑动，并忽略同一路由的加载完成及异步更新。 */
+export default function RouteTransition({ children }: PropsWithChildren) {
+  const { key: locationKey } = useLocation()
+  const previousLocationKey = useRef(locationKey)
+
+  // onUpdate 先于 passive effect 执行；无动画的同步导航也需要更新基准。
+  useEffect(() => {
+    previousLocationKey.current = locationKey
+  }, [locationKey])
+
+  /** 同一导航只保留首次滑动，取消页内更新产生的页面快照动画。 */
+  function handleUpdate() {
+    if (previousLocationKey.current !== locationKey) {
+      previousLocationKey.current = locationKey
+      return
+    }
+
+    for (const animation of document.documentElement.getAnimations({ subtree: true })) {
+      const effect = animation.effect
+      if (
+        effect instanceof KeyframeEffect &&
+        /^::view-transition-(group|image-pair|old|new)\(route-page\)$/.test(
+          effect.pseudoElement ?? '',
+        )
+      ) {
+        animation.cancel()
+      }
+    }
+  }
+
+  return (
+    <ReactViewTransition
+      name="route-page"
+      default="none"
+      share="route-page"
+      update="route-page"
+      onUpdate={handleUpdate}
+    >
+      <div className="route-transition-page">{children ?? <Outlet />}</div>
+    </ReactViewTransition>
+  )
+}

package/template-vp-monorepo-react-nestjs/apps/web/src/components/Selector/BasicTableSelector/BasicTableSelector.tsx

@@ -0,0 +1,218 @@
+import { ProTable, type ParamsType } from '@ant-design/pro-components'
+import { useI18n } from '@bubblesjs/i18n-react'
+import { Alert, Button, Flex, Modal, Tag, Typography } from 'antd'
+import { BasicTableSelectorSelection } from './BasicTableSelectorSelection'
+import type { BasicTableSelectorProps } from './BasicTableSelectorTypes'
+
+/** 在独立弹窗中展示分页表格，支持跨页选择和缺失记录补查。 */
+export default function BasicTableSelector<
+  T extends object,
+  Params extends ParamsType = ParamsType,
+  ValueType = 'text',
+>({
+  ref,
+  title,
+  rowKey,
+  request,
+  multiple = false,
+  onChange,
+  requestByKeys,
+  labelRender,
+  sidePanel,
+  onTableChange,
+  getCheckboxProps,
+  modalProps,
+  onLoad,
+  onRequestError,
+  pagination,
+  scroll,
+  ...tableProps
+}: BasicTableSelectorProps<T, Params, ValueType>) {
+  const { tr } = useI18n()
+  const [session, setSession] = useState<{
+    id: number
+    selection: BasicTableSelectorSelection<T>
+  }>()
+  const [confirming, setConfirming] = useState(false)
+  const [error, setError] = useState<string>()
+  const sessionId = useRef(0)
+  const pendingId = useRef<number | null>(null)
+
+  /** 结束当前选择会话，清除提交状态及错误，使旧异步结果失效。 */
+  const hide = () => {
+    sessionId.current += 1
+    pendingId.current = null
+    setSession(undefined)
+    setConfirming(false)
+    setError(undefined)
+  }
+
+  useEffect(
+    () => () => {
+      // 关闭、重开或卸载后，旧会话的异步补查不能提交到新会话。
+      sessionId.current += 1
+    },
+    [],
+  )
+
+  useImperativeHandle(ref, () => ({
+    /** 根据初始选中项开启新会话，并清除上一会话的提交和错误状态。 */
+    show: (options = {}) => {
+      const selection = new BasicTableSelectorSelection<T>({ ...options, rowKey, multiple })
+      const id = ++sessionId.current
+      pendingId.current = null
+      setConfirming(false)
+      setError(undefined)
+      setSession({ id, selection })
+    },
+    hide,
+  }))
+
+  /** 仅更新当前且未提交的选择会话，并清除之前的错误提示。 */
+  const changeSelection = (selection: BasicTableSelectorSelection<T>) => {
+    if (!session || pendingId.current !== null || session.id !== sessionId.current) return
+    setSession({ ...session, selection })
+    setError(undefined)
+  }
+
+  /** 补齐选中记录后提交结果，并阻止旧会话和重复确认影响当前弹窗。 */
+  const confirm = async () => {
+    if (!session || pendingId.current !== null) return
+    const { id, selection } = session
+    pendingId.current = id
+    setConfirming(true)
+    setError(undefined)
+    try {
+      const resolved = await selection.resolve(requestByKeys)
+      if (sessionId.current !== id) return
+      await onChange([...resolved.value], resolved.rows)
+      if (sessionId.current === id) hide()
+    } catch (cause) {
+      if (sessionId.current === id) {
+        setError(tr(cause instanceof Error ? cause.message : '确认选择失败，请重试'))
+      }
+    } finally {
+      if (sessionId.current === id) {
+        pendingId.current = null
+        setConfirming(false)
+      }
+    }
+  }
+
+  return (
+    <Modal
+      width={960}
+      okText={tr('确定')}
+      cancelText={tr('取消')}
+      {...modalProps}
+      title={title}
+      open={!!session}
+      destroyOnHidden
+      onCancel={hide}
+      onOk={() => void confirm()}
+      confirmLoading={confirming}
+      cancelButtonProps={{ disabled: confirming }}
+      closable={!confirming}
+      keyboard={!confirming}
+      maskClosable={!confirming}
+    >
+      {session && (
+        <Flex align="stretch" gap={16} wrap="wrap">
+          {sidePanel}
+          <div style={{ flex: '1 1 640px', minWidth: 0 }}>
+            <Flex align="center" justify="space-between">
+              <Typography.Text>
+                {tr('已选择 {count} 项', { count: session.selection.value.length })}
+              </Typography.Text>
+              <Button
+                type="link"
+                disabled={confirming || !session.selection.value.length}
+                onClick={() => changeSelection(session.selection.select({ value: [] }))}
+              >
+                {tr('清空选择')}
+              </Button>
+            </Flex>
+            <Flex wrap gap={4} style={{ maxHeight: 96, overflowY: 'auto', marginBottom: 12 }}>
+              {session.selection.value.map(
+                /** 为选中键生成标签，已加载记录使用业务标签，其余显示原始键。 */ (key) => {
+                  const row = session.selection.get(key)
+                  return (
+                    <Tag
+                      key={`${typeof key}:${key}`}
+                      closable={!confirming}
+                      onClose={
+                        /** 阻止标签默认关闭行为，并从当前会话选中键中移除该项。 */ (event) => {
+                          event.preventDefault()
+                          changeSelection(
+                            session.selection.select({
+                              value: session.selection.value.filter((value) => value !== key),
+                            }),
+                          )
+                        }
+                      }
+                    >
+                      {row && labelRender ? labelRender(row) : String(key)}
+                    </Tag>
+                  )
+                },
+              )}
+            </Flex>
+            {error && <Alert type="error" showIcon title={error} style={{ marginBottom: 12 }} />}
+            <ProTable<T, Params, ValueType>
+              key={session.id}
+              search={{ labelWidth: 'auto' }}
+              cardProps={false}
+              options={{ reload: true, density: false, setting: false }}
+              {...tableProps}
+              rowKey={(row) => session.selection.keyOf(row)}
+              request={request}
+              onChange={onTableChange}
+              editable={undefined}
+              dataSource={undefined}
+              defaultData={undefined}
+              pagination={
+                pagination === false
+                  ? false
+                  : { defaultPageSize: 10, showSizeChanger: true, ...pagination }
+              }
+              scroll={{ x: 'max-content', y: 360, ...scroll }}
+              tableAlertRender={false}
+              tableAlertOptionRender={false}
+              onLoad={
+                /** 仅将当前会话加载的记录补入已选快照，并转发加载完成通知。 */ (rows) => {
+                  if (session.id !== sessionId.current) return
+                  setError(undefined)
+                  setSession((current) =>
+                    current?.id === session.id
+                      ? { ...current, selection: current.selection.remember(rows) }
+                      : current,
+                  )
+                  onLoad?.(rows)
+                }
+              }
+              onRequestError={
+                /** 仅向当前选择会话展示加载错误，并转发请求失败通知。 */ (cause) => {
+                  if (session.id !== sessionId.current) return
+                  setError(cause.message || tr('加载选择数据失败，请刷新重试'))
+                  onRequestError?.(cause)
+                }
+              }
+              rowSelection={{
+                type: session.selection.multiple ? 'checkbox' : 'radio',
+                preserveSelectedRowKeys: true,
+                selectedRowKeys: session.selection.value,
+                /** 合并行禁选规则，并在确认过程中禁用选择控件。 */
+                getCheckboxProps: (row) => {
+                  const checkboxProps = getCheckboxProps?.(row)
+                  return { ...checkboxProps, disabled: confirming || checkboxProps?.disabled }
+                },
+                onChange: (keys, rows) =>
+                  changeSelection(session.selection.select({ value: keys, rows })),
+              }}
+            />
+          </div>
+        </Flex>
+      )}
+    </Modal>
+  )
+}

package/template-vp-monorepo-react-nestjs/apps/web/src/components/Selector/BasicTableSelector/BasicTableSelectorSelection.ts

@@ -0,0 +1,91 @@
+import type {
+  BasicTableSelectorRowKey,
+  BasicTableSelectorShowOptions,
+} from './BasicTableSelectorTypes'
+
+/** 表格选择器内部的会话快照。仅保留已选对象，不累积缓存所有访问过的页面。 */
+export class BasicTableSelectorSelection<T extends object> {
+  readonly value: Key[]
+  readonly multiple: boolean
+  readonly rowKey: BasicTableSelectorRowKey<T>
+  private readonly records: Map<Key, T>
+
+  /** 复制并去重初始选中键，校验单选约束且只保留选中记录。 */
+  constructor(
+    options: BasicTableSelectorShowOptions<T> & {
+      multiple: boolean
+      rowKey: BasicTableSelectorRowKey<T>
+    },
+  ) {
+    this.value = [...new Set(options.value ?? [])]
+    this.multiple = options.multiple
+    this.rowKey = options.rowKey
+    if (!this.multiple && this.value.length > 1) {
+      throw new Error('BasicTableSelector 单选模式的 value 最多包含一个 key')
+    }
+    const selected = new Set(this.value)
+    this.records = new Map()
+    for (const row of options.selectedRows ?? []) {
+      const key = this.keyOf(row)
+      if (selected.has(key)) this.records.set(key, row)
+    }
+  }
+
+  /** 按配置提取稳定行键，键类型不受支持时抛出错误。 */
+  keyOf(row: T): Key {
+    const key = typeof this.rowKey === 'function' ? this.rowKey(row) : row[this.rowKey]
+    if (typeof key !== 'string' && typeof key !== 'number' && typeof key !== 'bigint') {
+      throw new Error('BasicTableSelector rowKey 必须返回稳定的字符串或数字 key')
+    }
+    return key
+  }
+
+  /** 读取指定已选 key 对应的对象快照。 */
+  get(key: Key) {
+    return this.records.get(key)
+  }
+
+  /** 返回当前选中但尚未取得完整记录的键。 */
+  get missingKeys() {
+    return this.value.filter((key) => !this.records.has(key))
+  }
+
+  /** 按选中键顺序返回完整记录，记录缺失时拒绝生成不完整结果。 */
+  get rows(): T[] {
+    return this.value.map(
+      /** 按选中键读取缓存记录，缺失时抛错避免提交不完整选择。 */ (key) => {
+        const row = this.records.get(key)
+        if (!row) throw new Error('部分已选数据尚未加载，请重新选择后重试')
+        return row
+      },
+    )
+  }
+
+  /** 创建更新后的选择快照，合并已知记录并过滤尚未加载的空行。 */
+  select(options: { value: readonly Key[]; rows?: readonly T[] }) {
+    return new BasicTableSelectorSelection<T>({
+      rowKey: this.rowKey,
+      multiple: this.multiple,
+      value: options.value,
+      // Ant Table 在仅回显 key 时，selectedRows 可能包含尚未缓存的空项。
+      selectedRows: [...this.records.values(), ...(options.rows ?? []).filter(Boolean)],
+    })
+  }
+
+  /** 补充已选记录的内容，同时保留现有选中键及顺序。 */
+  remember(rows: readonly T[]) {
+    return this.select({ value: this.value, rows })
+  }
+
+  /** 按缺失键补查选中记录，仍有不可用记录时抛错阻止确认。 */
+  async resolve(requestByKeys?: (keys: Key[]) => Promise<T[]>) {
+    const missing = this.missingKeys
+    if (!missing.length) return this
+    if (!requestByKeys) throw new Error('部分已选数据尚未加载，请重新选择后重试')
+    const resolved = this.remember(await requestByKeys(missing))
+    if (resolved.missingKeys.length) {
+      throw new Error('部分已选数据已不可用，请取消对应选择后重试')
+    }
+    return resolved
+  }
+}

package/template-vp-monorepo-react-nestjs/apps/web/src/components/Selector/BasicTableSelector/BasicTableSelectorTypes.ts

@@ -0,0 +1,60 @@
+import type { ParamsType, ProTableProps } from '@ant-design/pro-components'
+import type { ModalProps } from 'antd'
+
+export type BasicTableSelectorRowKey<T> = (keyof T & string) | ((record: T) => Key)
+
+export interface BasicTableSelectorShowOptions<T> {
+  /** 单选也传数组；省略表示从空选择开始。 */
+  value?: readonly Key[]
+  /** 为已有 key 提供对象，避免依赖当前页数据。组件不会修改这些对象。 */
+  selectedRows?: readonly T[]
+}
+
+export interface BasicTableSelectorRef<T> {
+  /** 打开一个隔离的选择会话，并可传入已有选中值和对象。 */
+  show: (options?: BasicTableSelectorShowOptions<T>) => void
+  /** 关闭当前选择会话，不提交本轮临时修改。 */
+  hide: () => void
+}
+
+type ManagedTableProps =
+  | 'ref'
+  | 'title'
+  | 'rowKey'
+  | 'rowSelection'
+  | 'request'
+  | 'dataSource'
+  | 'defaultData'
+  | 'editable'
+  | 'onChange'
+  | 'tableAlertRender'
+  | 'tableAlertOptionRender'
+
+export type BasicTableSelectorProps<
+  T extends object,
+  Params extends ParamsType = ParamsType,
+  ValueType = 'text',
+> = Omit<ProTableProps<T, Params, ValueType>, ManagedTableProps> & {
+  ref: Ref<BasicTableSelectorRef<T>>
+  title: ReactNode
+  rowKey: BasicTableSelectorRowKey<T>
+  request: NonNullable<ProTableProps<T, Params, ValueType>['request']>
+  multiple?: boolean
+  /** 仅点击确定时触发；keys 和 rows 长度、顺序始终一致。 */
+  onChange: (keys: Key[], rows: T[]) => void | Promise<void>
+  /** 确定时补查尚未取得对象的已选 key；返回顺序不限。 */
+  requestByKeys?: (keys: Key[]) => Promise<T[]>
+  labelRender?: (record: T) => ReactNode
+  /** 可选左侧浏览面板；选择摘要、错误和分页表格仍统一保留在右侧。 */
+  sidePanel?: ReactNode
+  /** 保留 ProTable 的分页、排序、筛选回调，避免与选择结果 onChange 重名。 */
+  onTableChange?: ProTableProps<T, Params, ValueType>['onChange']
+  getCheckboxProps?: Exclude<
+    ProTableProps<T, Params, ValueType>['rowSelection'],
+    false | undefined
+  >['getCheckboxProps']
+  modalProps?: Pick<
+    ModalProps,
+    'width' | 'centered' | 'okText' | 'cancelText' | 'className' | 'styles' | 'zIndex'
+  >
+}

package/template-vp-monorepo-react-nestjs/apps/web/src/components/Selector/BasicTableSelector/README.md

@@ -0,0 +1,110 @@
+# BasicTableSelector
+
+与业务无关的表格选择弹窗，基于 ProTable。调用方提供标题、查询函数、稳定的 `rowKey` 和表格配置。默认单选，`multiple` 开启跨页多选。
+
+## 接口
+
+| 参数                       | 说明                                                                                         |
+| -------------------------- | -------------------------------------------------------------------------------------------- |
+| `ref`                      | 通过 `show({ value, selectedRows })` 打开，通过 `hide()` 关闭                                |
+| `title`                    | 弹窗标题                                                                                     |
+| `rowKey`                   | 唯一字段名或 `(record) => key`，禁止使用分页内的行索引                                       |
+| `request`                  | ProTable 原生查询函数，返回 `{ data, total, success }`                                       |
+| `multiple`                 | 默认 `false`，单选与多选的输入输出均为数组                                                   |
+| `onChange(keys, rows)`     | 点击确定后调用；两个数组长度与顺序一致。可返回 Promise，失败时保留弹窗和选择                 |
+| `requestByKeys(keys)`      | 可选，确定时补查缺失的已选对象；只请求缺失 key，结果顺序不限                                 |
+| `labelRender(record)`      | 已选标签的展示内容，默认显示 key                                                             |
+| `getCheckboxProps(record)` | 设置候选行是否禁选等属性                                                                     |
+| `onTableChange`            | ProTable 原生的分页、排序、筛选回调                                                          |
+| `modalProps`               | 弹窗宽度、居中、按钮文案、样式等配置                                                         |
+| 其他参数                   | 直接透传 `columns`、`params`、`pagination`、`search`、`scroll`、`actionRef` 等 ProTable 配置 |
+
+`show()` 的 `value` 为 key 数组，省略时从空选择开始；`selectedRows` 为这些 key 对应的对象，可选。多选支持跨分页、跨搜索保留选择，表头全选仅针对当前页。已选标签可以移除不在当前页的项，也可以清空全部。
+
+勾选仅修改弹窗内的临时选择，取消、关闭不会调用 `onChange`。空选择确认返回 `([], [])`，是否必选由业务表单校验。单选传入两个以上不同 key 会报错。
+
+## 使用
+
+```tsx
+import { Button } from 'antd'
+import {
+  BasicTableSelector,
+  type BasicTableSelectorRef,
+} from '@/components/Selector'
+
+interface Item {
+  id: string
+  name: string
+}
+
+const selectorRef = useRef<BasicTableSelectorRef<Item>>(null)
+const [keys, setKeys] = useState<Key[]>([])
+const [selectedRows, setSelectedRows] = useState<Item[]>([])
+
+<Button onClick={() => selectorRef.current?.show({ value: keys, selectedRows })}>
+  选择条目
+</Button>
+<BasicTableSelector<Item>
+  ref={selectorRef}
+  title="选择条目"
+  rowKey="id"
+  multiple
+  columns={[{ title: '名称', dataIndex: 'name' }]}
+  request={async (params, sort, filter) => {
+    const result = await queryItems({ params, sort, filter })
+    return { data: result.items, total: result.total, success: true }
+  }}
+  requestByKeys={queryItemsByKeys}
+  labelRender={(item) => item.name}
+  onChange={(nextKeys, nextRows) => {
+    setKeys(nextKeys)
+    setSelectedRows(nextRows)
+  }}
+/>
+```
+
+示例中的 `queryItems`、`queryItemsByKeys` 由业务侧提供。组件不拼接接口地址、不决定业务权限、不创建或保存业务数据。请求参数通过 `params` 提供；ProTable 原生 `request` 同时接收分页、搜索、排序与筛选参数。
+
+仅有 key 时，分页查询无法保证取得所有已选对象。再次打开优先传入已有 `selectedRows`；若只有 key，则提供 `requestByKeys`。当前页加载到的已选对象也可用于补全。没有对象的标签先展示 key，确定时补查；未查全或补查失败均不回调、不静默删项，用户可以重试或移除无效选择。
+
+每次打开创建独立会话，取消后不保留本轮勾选和对象缓存。外部数据变化不会自动覆盖已经打开的临时选择，需要时重新调用 `show()`。关闭或重开后，旧会话的迟到请求不能提交选择或关闭新弹窗。
+
+## 已选数据还要在业务表格中编辑
+
+选择器管理“选了哪些对象”，业务表格管理“这些行被编辑成什么内容”。选择结果不代表覆盖业务表格的指令。重新选择时按稳定 key 合并：保留仍被选中行的当前数据，只为新增项初始化字段，移除取消选择的项。
+
+```tsx
+interface DetailRow extends Item {
+  quantity: number
+  remark: string
+}
+
+const [details, setDetails] = useState<DetailRow[]>([])
+
+// 再次打开时，传入业务表格的当前数据。
+selectorRef.current?.show({
+  value: details.map((row) => row.id),
+  selectedRows: details,
+})
+
+// 作为 BasicTableSelector 的 onChange。函数式更新取得最新编辑结果。
+const handleSelectionChange = (_keys: Key[], selected: Item[]) => {
+  setDetails((current) => {
+    const existing = new Map(current.map((row) => [row.id, row]))
+    return selected.map(
+      (item) =>
+        existing.get(item.id) ?? {
+          ...item,
+          quantity: 1,
+          remark: '',
+        },
+    )
+  })
+}
+```
+
+这里采用一次 Map 查询完成合并，时间复杂度为 O(n + m)，不需要深比较整个对象，也不需要额外维护一份可能不同步的 keys 状态。已有行的所有字段及对象引用保持原样；如需刷新某些服务端字段，由业务明确指定合并规则。
+
+在同一次弹窗内取消再选回，已有编辑仍可保留。确认移除后，将来再次添加默认视为新行；如果需要“删除后再选回来也恢复编辑”，可由业务另存以 key 索引的草稿 Map。更复杂的表单可将 `selectedKeys` 与 `draftByKey` 分开保存，但一般表格使用上述合并即可。
+
+基础组件不返回业务增删改指令，也不负责保存草稿、校验权限或处理服务端版本冲突。

package/template-vp-monorepo-react-nestjs/apps/web/src/components/Selector/BasicTableSelector/index.ts

@@ -0,0 +1,7 @@
+export { default } from './BasicTableSelector'
+export type {
+  BasicTableSelectorProps,
+  BasicTableSelectorRef,
+  BasicTableSelectorRowKey,
+  BasicTableSelectorShowOptions,
+} from './BasicTableSelectorTypes'