@vestow/vue 0.1.0

package/src/variants/lib/mask.ts

@@ -0,0 +1,106 @@
+/**
+ * Khuôn nhập liệu: phân tích chuỗi khuôn, lọc dữ liệu thô, và dựng lại chuỗi
+ * đã định dạng.
+ *
+ * Bốn hàm này KHÔNG dính framework nào — cùng lý do `lib/highlight` và
+ * `lib/menu-styles` nằm ở đây. Trước đó chúng ở trong cây Vue, nên bản React
+ * hoặc phải chép lại (rồi để hai bên trôi khỏi nhau) hoặc phải phụ thuộc ngược
+ * vào `@vestow/vue`.
+ */
+
+/** Một ô trong khuôn: hoặc là ký tự cố định, hoặc là chỗ nhận dữ liệu. */
+export interface MaskSlot {
+  literal?: string
+  accepts?: (char: string) => boolean
+}
+
+/**
+ * Ba ký hiệu, đúng bộ của PrimeVue. Mọi ký tự khác là ký tự CỐ ĐỊNH.
+ *
+ * Cố tình không thêm ký hiệu nào: khuôn nào cần nhiều hơn ba loại thì thứ nó
+ * thật sự cần là một hàm kiểm tra, không phải một bảng chữ cái dài hơn.
+ */
+const TOKENS: Record<string, (char: string) => boolean> = {
+  '9': char => /\d/.test(char),
+  'a': char => /[a-z]/i.test(char),
+  '*': char => /[a-z0-9]/i.test(char),
+}
+
+export function parseMask(mask: string): MaskSlot[] {
+  return [...mask].map(char =>
+    char in TOKENS ? { accepts: TOKENS[char] } : { literal: char },
+  )
+}
+
+/**
+ * Lọc chuỗi bất kỳ xuống còn các ký tự DỮ LIỆU, theo đúng thứ tự các ô nhận.
+ *
+ * Ký tự cố định và ký tự không hợp lệ đều rơi ra ở đây, nên cùng một hàm lo
+ * được cả việc gõ từng phím lẫn việc dán cả một chuỗi đã có định dạng: dán
+ * `(024) 555-0100` hay gõ `0245550100` đều ra một kết quả.
+ *
+ * Cái bẫy còn lại: nếu khuôn dùng một ký tự cố định mà chính nó cũng hợp lệ ở
+ * ô kế tiếp (khuôn `99a99` với dấu ngăn là một chữ cái) thì nó bị nuốt thành
+ * dữ liệu. Hiếm, và nói ra ở đây còn hơn là chống bằng một luật đoán mò.
+ */
+export function toRaw(text: string, slots: MaskSlot[]): string {
+  const inputs = slots.filter(slot => slot.accepts !== undefined)
+  let raw = ''
+  for (const char of text) {
+    if (raw.length >= inputs.length)
+      break
+    const accepts = inputs[raw.length].accepts
+    if (accepts !== undefined && accepts(char))
+      raw += char
+  }
+  return raw
+}
+
+export interface FormatResult {
+  /** Chuỗi đầy đủ, ô chưa điền thì lấy `slotChar`. */
+  text: string
+  /** Chuỗi cắt tới ô đã điền cuối cùng — không mang ký tự giữ chỗ nào. */
+  filled: string
+  /** Vị trí con trỏ ngay sau ô dữ liệu thứ `raw.length`. */
+  caret: number
+}
+
+export function formatMask(raw: string, slots: MaskSlot[], slotChar: string): FormatResult {
+  let text = ''
+  let filled = ''
+  let caret = 0
+  let index = 0
+
+  for (const slot of slots) {
+    if (slot.literal !== undefined) {
+      text += slot.literal
+      // Ký tự cố định chỉ theo vào phần đã điền khi còn dữ liệu đứng sau nó —
+      // nếu không thì gõ xong số vùng sẽ ra `(024) ` với một dấu cách thừa.
+      if (index < raw.length)
+        filled += slot.literal
+      continue
+    }
+
+    if (index < raw.length) {
+      text += raw[index]
+      filled += raw[index]
+      index += 1
+      caret = text.length
+    }
+    else {
+      text += slotChar
+    }
+  }
+
+  return { text, filled, caret }
+}
+
+/** Số ô DỮ LIỆU nằm trước vị trí `position` trong chuỗi đã định dạng. */
+export function dataBefore(slots: MaskSlot[], position: number): number {
+  let count = 0
+  for (let i = 0; i < position && i < slots.length; i += 1) {
+    if (slots[i].accepts !== undefined)
+      count += 1
+  }
+  return count
+}

package/src/variants/lib/media.ts

@@ -0,0 +1,56 @@
+/**
+ * Phần thuần của một trình phát media — không DOM, không framework.
+ *
+ * Nằm ở đây chứ không ở `vue/packages/ui` vì cùng lý do với `lib/upload`: bản
+ * React sẽ cần đúng những phép này, mà chép lại thì hai cây có hai cách định
+ * dạng thời gian và hai cách kẹp mốc tua, không có gì phát hiện khi chúng lệch.
+ */
+
+/**
+ * `m:ss`, hoặc `h:mm:ss` khi dài hơn một giờ.
+ *
+ * Cố ý KHÔNG dùng `Intl`: đây là một KHOẢNG, không phải mốc thời gian trong
+ * ngày, nên nó không có bản địa hoá — `1:07` đọc giống nhau ở mọi ngôn ngữ.
+ *
+ * Chặn giá trị không hữu hạn ở đầu hàm là bắt buộc chứ không phải phòng xa:
+ * `video.duration` là `NaN` cho tới khi trình duyệt đọc xong metadata, và
+ * `Infinity` với luồng phát trực tiếp.
+ */
+export function formatMediaTime(value: number): string {
+  if (!Number.isFinite(value) || value < 0)
+    return '0:00'
+
+  const total = Math.floor(value)
+  const seconds = total % 60
+  const minutes = Math.floor(total / 60) % 60
+  const hours = Math.floor(total / 3600)
+  const pad = (n: number): string => n.toString().padStart(2, '0')
+
+  return hours > 0 ? `${hours}:${pad(minutes)}:${pad(seconds)}` : `${minutes}:${pad(seconds)}`
+}
+
+/**
+ * Kẹp một mốc tua vào `[0, duration]`.
+ *
+ * Gán `currentTime` âm thì trình duyệt ném `IndexSizeError`, còn gán quá
+ * `duration` thì nó nhảy tới cuối và phát `ended` — hai kiểu hỏng khác nhau cho
+ * cùng một cú bấm. `duration` chưa hữu hạn thì chỉ chặn cận dưới, vì lúc đó
+ * chưa biết cận trên là bao nhiêu.
+ */
+export function clampMediaTime(value: number, duration: number): number {
+  const lower = Math.max(value, 0)
+  return Number.isFinite(duration) ? Math.min(lower, duration) : lower
+}
+
+/**
+ * Ba nấc để chọn icon loa.
+ *
+ * Phải đọc CẢ `muted` lẫn giá trị âm lượng: kéo thanh về 0 thì `muted` vẫn là
+ * `false`, hiện icon loa đầy trong khi không nghe thấy gì là nói dối người dùng.
+ */
+export function mediaVolumeLevel(volume: number, muted: boolean): 'off' | 'low' | 'high' {
+  if (muted || volume <= 0)
+    return 'off'
+
+  return volume < 0.5 ? 'low' : 'high'
+}

package/src/variants/lib/menu-styles.ts

@@ -0,0 +1,71 @@
+/**
+ * Class dùng chung cho MỌI loại menu: DropdownMenu, ContextMenu, và bất cứ menu
+ * nào thêm sau.
+ *
+ * Reka tách chúng thành các primitive riêng vì **cách mở** khác nhau — bấm nút
+ * so với bấm chuột phải, cách định vị cũng khác. Nhưng phần *nội dung* thì y
+ * hệt: cùng tấm nền, cùng chiều cao hàng, cùng ô đánh dấu 16px ở lề trái.
+ *
+ * Chép hai bản là đảm bảo có ngày chúng lệch nhau — sửa màu focus ở một bên rồi
+ * quên bên kia. Khai một lần ở đây, hai bộ wrapper cùng đọc.
+ *
+ * Chỉ là chuỗi class, không phải component: mỗi primitive vẫn tự render thẻ của
+ * nó với đúng hành vi và ARIA riêng.
+ */
+
+/**
+ * `ui-menu` là MÓC CSS, không phải class tiện ích — cùng khuôn với `ui-button`
+ * mà `surfaces.css` bám vào. Hai trục `data-menu-color` và
+ * `data-menu-appearance` khai lại token ngay trên phần tử mang móc này, nên
+ * phạm vi của chúng đúng bằng tấm menu; xem `menus.css`.
+ *
+ * `bg-menu-surface` chứ không `bg-popover`: trục vật liệu phải hạ được độ đục
+ * của RIÊNG menu, mà `--popover` thì Popover và Tooltip cũng đọc.
+ */
+export const menuContentClass = [
+  'ui-menu surface z-(--z-overlay) min-w-[10rem] overflow-hidden rounded-md border border-border bg-menu-surface p-1 text-popover-foreground shadow-md',
+  'data-[state=open]:animate-in data-[state=closed]:animate-out',
+  'data-[state=open]:fade-in-0 data-[state=closed]:fade-out-0',
+  'data-[state=open]:zoom-in-95 data-[state=closed]:zoom-out-95',
+]
+
+export const menuSubContentClass = [
+  'ui-menu surface z-(--z-overlay) min-w-[8rem] overflow-hidden rounded-md border border-border bg-menu-surface p-1 text-popover-foreground shadow-lg',
+  'data-[state=open]:animate-in data-[state=closed]:animate-out',
+  'data-[state=open]:fade-in-0 data-[state=closed]:fade-out-0',
+  'data-[state=open]:zoom-in-95 data-[state=closed]:zoom-out-95',
+]
+
+export const menuItemClass = [
+  'relative flex cursor-default select-none items-center gap-2 rounded-sm px-2 py-1.5 text-sm outline-none transition-colors',
+  'focus:bg-menu-accent focus:text-menu-accent-foreground',
+  'data-[disabled]:pointer-events-none data-[disabled]:opacity-50',
+  'data-[variant=destructive]:text-destructive data-[variant=destructive]:focus:bg-destructive/10',
+  '[&_svg]:size-4 [&_svg]:shrink-0 [&_svg]:text-muted-foreground',
+  'data-[variant=destructive]:[&_svg]:text-destructive',
+]
+
+/** Mục có ô đánh dấu: lề trái 32px chừa chỗ cho dấu tick hoặc chấm tròn. */
+export const menuIndicatorItemClass = [
+  'relative flex cursor-default select-none items-center gap-2 rounded-sm py-1.5 pl-8 pr-2 text-sm outline-none transition-colors',
+  'focus:bg-menu-accent focus:text-menu-accent-foreground',
+  'data-[disabled]:pointer-events-none data-[disabled]:opacity-50',
+]
+
+export const menuIndicatorSlotClass = 'absolute left-2 flex size-4 items-center justify-center'
+
+export const menuSubTriggerClass = [
+  'flex cursor-default select-none items-center gap-2 rounded-sm px-2 py-1.5 text-sm outline-none',
+  'focus:bg-menu-accent focus:text-menu-accent-foreground',
+  'data-[state=open]:bg-menu-accent data-[state=open]:text-menu-accent-foreground',
+  '[&_svg]:size-4 [&_svg]:shrink-0',
+]
+
+export const menuLabelClass = 'px-2 py-1.5 text-xs font-medium text-muted-foreground'
+
+export const menuSeparatorClass = '-mx-1 my-1 h-px bg-border'
+
+export const menuShortcutClass = 'ml-auto text-xs tracking-widest text-muted-foreground'
+
+/** Thụt vào cho ngang hàng với mục có ô đánh dấu. */
+export const menuInsetClass = 'pl-8'

package/src/variants/lib/platform.ts

@@ -0,0 +1,68 @@
+/**
+ * Máy đang chạy có phải macOS (hoặc iOS) không.
+ *
+ * Chỉ dùng để CHỌN NHÃN phím tắt: macOS hiện `⌘`, còn lại hiện `Ctrl`. Bản
+ * thân trình xử lý phím thì luôn nhận cả hai (`event.metaKey || event.ctrlKey`)
+ * — đoán sai nền tảng thì cùng lắm là hiện nhầm nhãn, không bao giờ làm phím
+ * tắt chết.
+ *
+ * `navigator.platform` tuy đã deprecated nhưng vẫn là thứ chạy ở mọi trình
+ * duyệt hiện có; `userAgentData` mới hơn lại chưa có trên Safari, tức đúng cái
+ * nền tảng cần nhận ra nhất. Có `userAgent` đỡ phía sau.
+ *
+ * KHÔNG gọi ở tầng module: ngoài trình duyệt thì không có `navigator`.
+ */
+export function isMacPlatform(): boolean {
+  if (typeof navigator === 'undefined')
+    return false
+
+  return /mac|iphone|ipad|ipod/i.test(navigator.platform || navigator.userAgent)
+}
+
+/**
+ * Nhãn của phím bổ trợ chính: `⌘` trên macOS, `Ctrl` ở nơi khác.
+ *
+ * Có hàm riêng thay vì để mỗi chỗ tự viết `isMacPlatform() ? '⌘' : 'Ctrl'`: đó
+ * đúng là chuỗi đã bị chép ở `KitHeader`, ở `KitShowcase` và ở 23 file ví dụ,
+ * và ký tự `⌘` thì không gõ lại được bằng bàn phím nên mỗi bản chép là một cơ
+ * hội dán nhầm.
+ *
+ * `String.fromCharCode` chứ không viết thẳng ký tự: file nguồn của ví dụ được
+ * hiện NGUYÊN VĂN lên trang tài liệu, mà một ký tự ngoài BMP trong đoạn code
+ * thì người đọc không gõ lại được.
+ *
+ * KHÔNG gọi ở tầng module, cùng lý do với `isMacPlatform`.
+ */
+export function metaKeyLabel(): string {
+  return isMacPlatform() ? String.fromCharCode(0x2318) : 'Ctrl'
+}
+
+/**
+ * Nhãn đầy đủ của một tổ hợp phím, theo quy ước của TỪNG nền tảng.
+ *
+ * Hai nền tảng viết khác nhau ở cả ký hiệu lẫn dấu nối, nên đổi mỗi `⌘` thành
+ * `Ctrl` là chưa đủ:
+ *
+ * | | macOS | nơi khác |
+ * |---|---|---|
+ * | `['Mod', 'Z']` | `⌘Z` | `Ctrl+Z` |
+ * | `['Mod', 'Shift', 'Z']` | `⌘⇧Z` | `Ctrl+Shift+Z` |
+ * | `['Shift', 'R']` | `⇧R` | `Shift+R` |
+ *
+ * macOS ghép liền vì mỗi phím bổ trợ là một ký hiệu riêng; Windows và Linux
+ * dùng CHỮ nên phải có dấu `+`, không thì ra `CtrlShiftZ` dính một cục.
+ *
+ * `Mod` là tên trung tính của phím bổ trợ chính — viết `Mod` thay vì `Cmd` hay
+ * `Ctrl` để chỗ gọi khỏi phải tự phân nhánh.
+ */
+export function shortcutLabel(keys: readonly string[]): string {
+  const mac = isMacPlatform()
+
+  const symbols: Record<string, string> = mac
+    ? { Alt: '⌥', Ctrl: '⌃', Mod: '⌘', Shift: '⇧' }
+    : { Alt: 'Alt', Ctrl: 'Ctrl', Mod: 'Ctrl', Shift: 'Shift' }
+
+  const parts = keys.map(key => symbols[key] ?? key)
+
+  return mac ? parts.join('') : parts.join('+')
+}

package/src/variants/lib/tree.ts

@@ -0,0 +1,119 @@
+/**
+ * Khuôn dữ liệu cây, và hai phép tra trên nó.
+ *
+ * KHÔNG dính framework nào — cùng lý do `lib/mask` nằm ở đây. `Tree`,
+ * `TreeSelect` và `CascadeSelect` của cả hai cây đều nhận đúng hình dạng này,
+ * vì chúng đang nói về cùng một thứ; khai ba kiểu nút y hệt nhau sẽ buộc người
+ * dùng chuyển đổi qua lại chỉ để đổi cách trình bày.
+ */
+
+/**
+ * Khuôn dữ liệu tối thiểu cho một cây.
+ *
+ * Đệ quy theo chính nó (`children?: TreeNode[]`) chứ không generic: nút con
+ * phải cùng kiểu nút cha thì phép làm phẳng mới đi được. Muốn mang thêm trường
+ * thì mở rộng interface này.
+ */
+export interface TreeNode {
+  /** Khoá duy nhất trong toàn cây. */
+  id: string
+  label: string
+  children?: TreeNode[]
+  disabled?: boolean
+}
+
+/** Đường đi từ gốc tới `id`, kể cả chính nó. Rỗng nếu không tìm thấy. */
+export function findPath(items: TreeNode[], id: string): TreeNode[] {
+  for (const item of items) {
+    if (item.id === id)
+      return [item]
+    if (item.children !== undefined) {
+      const deeper = findPath(item.children, id)
+      if (deeper.length > 0)
+        return [item, ...deeper]
+    }
+  }
+  return []
+}
+
+/** Nút có con hay không. Lá thì chọn được, nhánh thì mở ra thêm một tầng. */
+export function isBranch(node: TreeNode): boolean {
+  return node.children !== undefined && node.children.length > 0
+}
+
+/** Một dòng của cây sau khi làm phẳng — nút, cấp, và trạng thái để vẽ. */
+export interface TreeRow {
+  node: TreeNode
+  /** Đếm từ 1, đúng thang `aria-level`. */
+  level: number
+  hasChildren: boolean
+  expanded: boolean
+  selected: boolean
+  /** Vị trí trong nhóm anh em, đếm từ 1 — `aria-posinset`. */
+  position: number
+  /** Số anh em cùng nhóm — `aria-setsize`. */
+  setSize: number
+}
+
+/**
+ * Làm phẳng những nút ĐANG THẤY thành một danh sách tuyến tính.
+ *
+ * Điều hướng bàn phím của một cây chạy trên thứ tự nhìn thấy, không chạy trên
+ * cấu trúc lồng nhau: `ArrowDown` từ nút cuối của một nhánh đang mở phải sang
+ * nút kế của nhánh CHA. Đệ quy qua component lồng nhau thì mỗi bước như vậy là
+ * một phép đi ngược cây; làm phẳng trước thì nó chỉ là `index + 1`.
+ *
+ * Đây cũng là thứ `TreeRoot` của reka trả về qua slot bên bản Vue, nên hai cây
+ * cùng một mô hình dù một bên tự dựng.
+ */
+export function flattenTree(
+  items: TreeNode[],
+  expanded: readonly string[],
+  selected: readonly string[],
+): TreeRow[] {
+  const rows: TreeRow[] = []
+
+  function walk(nodes: TreeNode[], level: number): void {
+    nodes.forEach((node, index) => {
+      const hasChildren = isBranch(node)
+      const isExpanded = hasChildren && expanded.includes(node.id)
+
+      rows.push({
+        node,
+        level,
+        hasChildren,
+        expanded: isExpanded,
+        selected: selected.includes(node.id),
+        position: index + 1,
+        setSize: nodes.length,
+      })
+
+      if (isExpanded && node.children !== undefined)
+        walk(node.children, level + 1)
+    })
+  }
+
+  walk(items, 1)
+  return rows
+}
+
+/** Mọi id trong nhánh, kể cả chính nó. Dùng cho chế độ chọn lan xuống con. */
+export function branchIds(node: TreeNode): string[] {
+  const ids = [node.id]
+  for (const child of node.children ?? [])
+    ids.push(...branchIds(child))
+  return ids
+}
+
+/** Mọi nút trong nhánh, kể cả chính nó. Đối ứng của `branchIds`. */
+export function branchNodes(node: TreeNode): TreeNode[] {
+  const nodes = [node]
+  for (const child of node.children ?? [])
+    nodes.push(...branchNodes(child))
+  return nodes
+}
+
+/** Tra một nút theo id trong cả cây. */
+export function findNode(items: TreeNode[], id: string): TreeNode | undefined {
+  return findPath(items, id).at(-1)
+}

package/src/variants/lib/upload.ts

@@ -0,0 +1,58 @@
+/**
+ * Một tệp trong danh sách tải lên, kèm trạng thái.
+ *
+ * `progress` và `error` do **bên gọi** cập nhật — component không tự tải lên.
+ * Nó chỉ là phần giao diện: chọn tệp, kéo thả, hiện danh sách, gỡ ra. Việc gửi
+ * đi phụ thuộc hoàn toàn vào backend (một lần / nhiều phần / ký trước URL), nên
+ * gắn cứng một cách vào đây là bên nào cũng phải chống lại nó.
+ */
+export interface UploadFile {
+  id: string
+  file: File
+  /** 0–100. `undefined` nghĩa là chưa bắt đầu. */
+  progress?: number
+  error?: string
+}
+
+/** Đổi số byte sang chuỗi đọc được. Dùng nhị phân (KiB) như hệ điều hành. */
+export function formatFileSize(bytes: number): string {
+  if (bytes < 1024)
+    return `${bytes} B`
+
+  const units = ['KB', 'MB', 'GB']
+  let value = bytes / 1024
+  let unit = 0
+
+  while (value >= 1024 && unit < units.length - 1) {
+    value /= 1024
+    unit++
+  }
+
+  // Một chữ số thập phân là đủ; "1.4 MB" đọc nhanh hơn "1.44 MB".
+  return `${value.toFixed(value < 10 ? 1 : 0)} ${units[unit]}`
+}
+
+/**
+ * Khoá nhận dạng một tệp. Tên + cỡ + thời điểm sửa là đủ để coi hai lần kéo
+ * cùng một tệp vào là thao tác nhầm, chứ không phải ý định tải hai bản.
+ */
+export function uploadFileId(file: File): string {
+  return `${file.name}-${file.size}-${file.lastModified}`
+}
+
+/**
+ * Tách danh sách tệp vừa nhận thành phần nhận được và phần quá lớn.
+ *
+ * Tách ra khỏi component vì cả hai cây chạy đúng một luật, và vì luật đó có
+ * một ca dễ viết sai: `maxSize` bằng 0 nghĩa là KHÔNG giới hạn, không phải
+ * "không nhận tệp nào".
+ */
+export function splitBySize(files: File[], maxSize: number): { accepted: File[], tooBig: File[] } {
+  if (maxSize <= 0)
+    return { accepted: files, tooBig: [] }
+
+  return {
+    accepted: files.filter(file => file.size <= maxSize),
+    tooBig: files.filter(file => file.size > maxSize),
+  }
+}

package/src/variants/lib/utils.ts

@@ -0,0 +1,11 @@
+import type { ClassValue } from 'clsx'
+import { clsx } from 'clsx'
+import { twMerge } from 'tailwind-merge'
+
+/**
+ * Gộp class Tailwind, class sau thắng class trước khi cùng nhóm utility.
+ * Bắt buộc dùng cho mọi component nhận prop `class` từ bên ngoài.
+ */
+export function cn(...inputs: ClassValue[]): string {
+  return twMerge(clsx(inputs))
+}