@comitor/ui 1.11.0 → 2.1.0

package/dist/components/ui/circular-progress.js

@@ -0,0 +1,266 @@
+"use client";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { Slot } from "@radix-ui/react-slot";
+import * as React from "react";
+import { cn } from "../../lib/cn.js";
+const CIRCULAR_PROGRESS_NAME = "CircularProgress";
+const INDICATOR_NAME = "CircularProgressIndicator";
+const TRACK_NAME = "CircularProgressTrack";
+const RANGE_NAME = "CircularProgressRange";
+const VALUE_TEXT_NAME = "CircularProgressValueText";
+const DEFAULT_MAX = 100;
+const IS_DEV = typeof process !== "undefined" && process.env.NODE_ENV !== "production";
+function getProgressState(value, maxValue) {
+  return value == null ? "indeterminate" : value === maxValue ? "complete" : "loading";
+}
+function getIsValidNumber(value) {
+  return typeof value === "number" && Number.isFinite(value);
+}
+function getIsValidMaxNumber(max) {
+  return getIsValidNumber(max) && max > 0;
+}
+function getIsValidValueNumber(value, min, max) {
+  return getIsValidNumber(value) && value <= max && value >= min;
+}
+function getDefaultValueText(value, min, max) {
+  const percentage = max === min ? 100 : (value - min) / (max - min) * 100;
+  return `${Math.round(percentage)}%`;
+}
+function getInvalidValueError(propValue, componentName) {
+  return `Prop \`value\` = \`${propValue}\` truy\u1EC1n cho \`${componentName}\` kh\xF4ng h\u1EE3p l\u1EC7. \`value\` ph\u1EA3i l\xE0 s\u1ED1 trong kho\u1EA3ng \`min\`\u2026\`max\` (t\xEDnh c\u1EA3 hai \u0111\u1EA7u), ho\u1EB7c \`null\`/\`undefined\` cho ti\u1EBFn tr\xECnh kh\xF4ng x\xE1c \u0111\u1ECBnh. Gi\xE1 tr\u1ECB s\u1EBD b\u1ECB k\u1EB9p v\u1EC1 kho\u1EA3ng h\u1EE3p l\u1EC7.`;
+}
+function getInvalidMaxError(propValue, componentName) {
+  return `Prop \`max\` = \`${propValue}\` truy\u1EC1n cho \`${componentName}\` kh\xF4ng h\u1EE3p l\u1EC7. Ch\u1EC9 nh\u1EADn s\u1ED1 l\u1EDBn h\u01A1n 0 \u2014 d\xF9ng m\u1EB7c \u0111\u1ECBnh ${DEFAULT_MAX}.`;
+}
+const CircularProgressContext = React.createContext(null);
+function useCircularProgressContext(consumerName) {
+  const context = React.useContext(CircularProgressContext);
+  if (!context) {
+    throw new Error(`\`${consumerName}\` ph\u1EA3i n\u1EB1m b\xEAn trong \`${CIRCULAR_PROGRESS_NAME}\``);
+  }
+  return context;
+}
+function CircularProgress(props) {
+  const {
+    value: valueProp = null,
+    getValueText = getDefaultValueText,
+    min: minProp = 0,
+    max: maxProp,
+    size = 48,
+    thickness = 4,
+    label,
+    asChild,
+    className,
+    children,
+    ...rootProps
+  } = props;
+  if ((maxProp || maxProp === 0) && !getIsValidMaxNumber(maxProp)) {
+    if (IS_DEV) {
+      console.error(getInvalidMaxError(`${maxProp}`, CIRCULAR_PROGRESS_NAME));
+    }
+  }
+  const rawMax = getIsValidMaxNumber(maxProp) ? maxProp : DEFAULT_MAX;
+  const min = getIsValidNumber(minProp) ? minProp : 0;
+  const max = rawMax <= min ? min + 1 : rawMax;
+  if (IS_DEV && thickness >= size) {
+    console.warn(
+      `CircularProgress: \`thickness\` (${thickness}) ph\u1EA3i nh\u1ECF h\u01A1n \`size\` (${size}) th\xEC v\xF2ng m\u1EDBi v\u1EBD \u0111\xFAng.`
+    );
+  }
+  if (valueProp !== null && !getIsValidValueNumber(valueProp, min, max)) {
+    if (IS_DEV) {
+      console.error(getInvalidValueError(`${valueProp}`, CIRCULAR_PROGRESS_NAME));
+    }
+  }
+  const value = getIsValidValueNumber(valueProp, min, max) ? valueProp : getIsValidNumber(valueProp) && valueProp > max ? max : getIsValidNumber(valueProp) && valueProp < min ? min : null;
+  const valueText = getIsValidNumber(value) ? getValueText(value, min, max) : void 0;
+  const state = getProgressState(value, max);
+  const radius = Math.max(0, (size - thickness) / 2);
+  const center = size / 2;
+  const circumference = 2 * Math.PI * radius;
+  const percentage = getIsValidNumber(value) ? max === min ? 1 : (value - min) / (max - min) : null;
+  const labelId = React.useId();
+  const valueTextId = React.useId();
+  const contextValue = React.useMemo(
+    () => ({
+      value,
+      valueText,
+      max,
+      min,
+      state,
+      radius,
+      thickness,
+      size,
+      center,
+      circumference,
+      percentage,
+      valueTextId
+    }),
+    [value, valueText, max, min, state, radius, thickness, size, center, circumference, percentage, valueTextId]
+  );
+  const RootPrimitive = asChild ? Slot : "div";
+  return /* @__PURE__ */ jsx(CircularProgressContext.Provider, { value: contextValue, children: /* @__PURE__ */ jsxs(
+    RootPrimitive,
+    {
+      role: "progressbar",
+      "aria-describedby": valueText ? valueTextId : void 0,
+      "aria-labelledby": label ? labelId : void 0,
+      "aria-valuemax": max,
+      "aria-valuemin": min,
+      "aria-valuenow": getIsValidNumber(value) ? value : void 0,
+      "aria-valuetext": valueText,
+      "data-state": state,
+      "data-value": value ?? void 0,
+      "data-max": max,
+      "data-min": min,
+      "data-percentage": percentage,
+      "data-slot": "circular-progress",
+      ...rootProps,
+      className: cn("relative inline-flex w-fit items-center justify-center", label && "flex-col gap-1.5", className),
+      children: [
+        label ? /* @__PURE__ */ jsx("div", { "data-slot": "circular-progress-ring", className: "relative inline-flex items-center justify-center", children }) : children,
+        label && /* @__PURE__ */ jsx("div", { id: labelId, "data-slot": "circular-progress-label", className: "text-sm", children: label })
+      ]
+    }
+  ) });
+}
+function CircularProgressIndicator(props) {
+  const { className, ...indicatorProps } = props;
+  const context = useCircularProgressContext(INDICATOR_NAME);
+  return /* @__PURE__ */ jsx(
+    "svg",
+    {
+      "aria-hidden": "true",
+      focusable: "false",
+      viewBox: `0 0 ${context.size} ${context.size}`,
+      "data-state": context.state,
+      "data-value": context.value ?? void 0,
+      "data-max": context.max,
+      "data-min": context.min,
+      "data-percentage": context.percentage,
+      "data-slot": "circular-progress-indicator",
+      width: context.size,
+      height: context.size,
+      ...indicatorProps,
+      className: cn("-rotate-90 transform", className)
+    }
+  );
+}
+CircularProgressIndicator.displayName = INDICATOR_NAME;
+function CircularProgressTrack(props) {
+  const { className, ...trackProps } = props;
+  const context = useCircularProgressContext(TRACK_NAME);
+  return /* @__PURE__ */ jsx(
+    "circle",
+    {
+      "data-state": context.state,
+      "data-slot": "circular-progress-track",
+      cx: context.center,
+      cy: context.center,
+      r: context.radius,
+      fill: "none",
+      stroke: "currentColor",
+      strokeWidth: context.thickness,
+      strokeLinecap: "round",
+      vectorEffect: "non-scaling-stroke",
+      ...trackProps,
+      className: cn(
+        /*
+         * GIỮ NGUYÊN thượng nguồn — rãnh xám trung tính `text-muted-foreground/20`, KHÔNG phải tint
+         * `/20` của bậc ink như rãnh `Progress`. Đã đo cả hai; thứ mang THÔNG TIN ở đây là ranh
+         * giới cung-đã-chạy ⇄ rãnh (chỗ cung dừng lại chính là giá trị), và rãnh trung tính giữ
+         * ranh giới đó TỐT HƠN (bảng tương phản cao, cung `text-primary-ink`):
+         *
+         *                                   rãnh trung tính      tint `primary-ink/20`
+         *     cung ⇄ rãnh trên --background : 5,03 (L) · 9,65 (D)   4,85 (L) · 7,97 (D)
+         *     tệ nhất, rãnh trên --muted    : 4,71 (L) · 8,00 (D)   4,54 (L) · 6,52 (D)
+         *     (viền trang trí --border       : 2,62 (L) ✗ — loại)
+         *
+         * Và nó không phụ thuộc tông: app đổi cung sang `text-success-ink`/`text-destructive-ink`
+         * thì rãnh vẫn đúng (5,03 · 5,51:1 trên nền trắng) mà không phải đổi theo.
+         *
+         * Rãnh ⇄ nền trang chỉ ~1,3:1 — CỐ Ý, như rãnh `Progress`: không có cặp màu nào vừa ≥3:1
+         * với nhau vừa ≥3:1 với nền trắng (chứng minh ở chú thích `Slider`). Khác `Progress` ở chỗ
+         * vòng KHÔNG cần viền khoanh mốc 100%: hình tròn tự khép và cung luôn bắt đầu ở 12 giờ, nên
+         * TỈ LỆ đọc được từ góc của cung mà không cần thấy rãnh. Một nét tròn liền, không nét nào
+         * cắt nhau, nên màu có alpha không để lộ vệt nối (xem "Cạm bẫy" về icon trong CLAUDE.md).
+         */
+        "text-muted-foreground/20",
+        className
+      )
+    }
+  );
+}
+function CircularProgressRange(props) {
+  const { className, ...rangeProps } = props;
+  const context = useCircularProgressContext(RANGE_NAME);
+  const strokeDasharray = context.circumference;
+  const strokeDashoffset = context.state === "indeterminate" ? context.circumference * 0.75 : context.percentage !== null ? context.circumference - context.percentage * context.circumference : context.circumference;
+  return /* @__PURE__ */ jsx(
+    "circle",
+    {
+      "data-state": context.state,
+      "data-value": context.value ?? void 0,
+      "data-max": context.max,
+      "data-min": context.min,
+      "data-slot": "circular-progress-range",
+      cx: context.center,
+      cy: context.center,
+      r: context.radius,
+      fill: "none",
+      stroke: "currentColor",
+      strokeWidth: context.thickness,
+      strokeLinecap: "round",
+      strokeDasharray,
+      strokeDashoffset,
+      vectorEffect: "non-scaling-stroke",
+      ...rangeProps,
+      className: cn(
+        /*
+         * ⚠ Khác thượng nguồn: `text-primary` (bậc TÔ NỀN, gold #E8B824 chỉ 1,86:1 trên nền trắng)
+         * → `text-primary-ink`, đúng bậc của thanh `Progress`: 6,51:1 (light) · 12,67:1 (dark)
+         * trên --background, tệ nhất 6,09:1 · 10,80:1 trên --muted (bảng tương phản cao). Cung là
+         * thông tin thị giác (WCAG 1.4.11, 3:1).
+         * Hiệu ứng quay đọc `--animate-spin-around` của styles.css; `motion-reduce` thì đứng yên.
+         */
+        "origin-center text-primary-ink transition-all duration-300 ease-in-out",
+        context.state === "indeterminate" && "motion-safe:[animation:var(--animate-spin-around)] motion-reduce:animate-none",
+        className
+      )
+    }
+  );
+}
+function CircularProgressValueText(props) {
+  const { asChild, className, children, ...valueTextProps } = props;
+  const context = useCircularProgressContext(VALUE_TEXT_NAME);
+  const ValueTextPrimitive = asChild ? Slot : "span";
+  return /* @__PURE__ */ jsx(
+    ValueTextPrimitive,
+    {
+      id: context.valueTextId,
+      "data-state": context.state,
+      "data-slot": "circular-progress-value-text",
+      ...valueTextProps,
+      className: cn("absolute inset-0 flex items-center justify-center text-sm font-medium", className),
+      children: children ?? context.valueText
+    }
+  );
+}
+function CircularProgressCombined(props) {
+  return /* @__PURE__ */ jsxs(CircularProgress, { ...props, children: [
+    /* @__PURE__ */ jsxs(CircularProgressIndicator, { children: [
+      /* @__PURE__ */ jsx(CircularProgressTrack, {}),
+      /* @__PURE__ */ jsx(CircularProgressRange, {})
+    ] }),
+    /* @__PURE__ */ jsx(CircularProgressValueText, {})
+  ] });
+}
+export {
+  CircularProgress,
+  CircularProgressCombined,
+  CircularProgressIndicator,
+  CircularProgressRange,
+  CircularProgressTrack,
+  CircularProgressValueText
+};
+//# sourceMappingURL=circular-progress.js.map

package/dist/components/ui/circular-progress.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/components/ui/circular-progress.tsx"],"sourcesContent":["\"use client\";\n\n/*\n * Port từ Dice UI (https://diceui.com/docs/components/circular-progress) — MIT, © 2024 Sadman Sakib.\n * Giữ nguyên cấu trúc thượng nguồn để còn đối chiếu ngược được; mọi chỗ đổi đều có chú thích.\n */\n\nimport { Slot } from \"@radix-ui/react-slot\";\nimport * as React from \"react\";\nimport { cn } from \"../../lib/cn.js\";\n\nconst CIRCULAR_PROGRESS_NAME = \"CircularProgress\";\nconst INDICATOR_NAME = \"CircularProgressIndicator\";\nconst TRACK_NAME = \"CircularProgressTrack\";\nconst RANGE_NAME = \"CircularProgressRange\";\nconst VALUE_TEXT_NAME = \"CircularProgressValueText\";\n\nconst DEFAULT_MAX = 100;\n\n/*\n * ⚠ Khác thượng nguồn: bản gốc đọc thẳng `process.env.NODE_ENV` ngay trong lúc render. Gói ra ESM\n * từng file, không bundle; ở môi trường không có bundler thay chuỗi đó (ESM thuần trên trình\n * duyệt), `process` không tồn tại → ReferenceError lúc render. Bọc `typeof` để chỗ đó chỉ mất cảnh\n * báo dev chứ không gãy; bundler vẫn thay `process.env.NODE_ENV` và loại nhánh dev như cũ.\n */\nconst IS_DEV = typeof process !== \"undefined\" && process.env.NODE_ENV !== \"production\";\n\ntype ProgressState = \"indeterminate\" | \"complete\" | \"loading\";\n\nfunction getProgressState(value: number | undefined | null, maxValue: number): ProgressState {\n  return value == null ? \"indeterminate\" : value === maxValue ? \"complete\" : \"loading\";\n}\n\nfunction getIsValidNumber(value: unknown): value is number {\n  return typeof value === \"number\" && Number.isFinite(value);\n}\n\nfunction getIsValidMaxNumber(max: unknown): max is number {\n  return getIsValidNumber(max) && max > 0;\n}\n\nfunction getIsValidValueNumber(value: unknown, min: number, max: number): value is number {\n  return getIsValidNumber(value) && value <= max && value >= min;\n}\n\nfunction getDefaultValueText(value: number, min: number, max: number): string {\n  const percentage = max === min ? 100 : ((value - min) / (max - min)) * 100;\n  return `${Math.round(percentage)}%`;\n}\n\nfunction getInvalidValueError(propValue: string, componentName: string): string {\n  return `Prop \\`value\\` = \\`${propValue}\\` truyền cho \\`${componentName}\\` không hợp lệ. \\`value\\` phải là số trong khoảng \\`min\\`…\\`max\\` (tính cả hai đầu), hoặc \\`null\\`/\\`undefined\\` cho tiến trình không xác định. Giá trị sẽ bị kẹp về khoảng hợp lệ.`;\n}\n\nfunction getInvalidMaxError(propValue: string, componentName: string): string {\n  return `Prop \\`max\\` = \\`${propValue}\\` truyền cho \\`${componentName}\\` không hợp lệ. Chỉ nhận số lớn hơn 0 — dùng mặc định ${DEFAULT_MAX}.`;\n}\n\ninterface CircularProgressContextValue {\n  value: number | null;\n  valueText: string | undefined;\n  max: number;\n  min: number;\n  state: ProgressState;\n  radius: number;\n  thickness: number;\n  size: number;\n  center: number;\n  circumference: number;\n  percentage: number | null;\n  valueTextId?: string;\n}\n\nconst CircularProgressContext = React.createContext<CircularProgressContextValue | null>(null);\n\nfunction useCircularProgressContext(consumerName: string) {\n  const context = React.useContext(CircularProgressContext);\n  if (!context) {\n    throw new Error(`\\`${consumerName}\\` phải nằm bên trong \\`${CIRCULAR_PROGRESS_NAME}\\``);\n  }\n  return context;\n}\n\ninterface CircularProgressProps extends React.ComponentProps<\"div\"> {\n  /** Giá trị hiện tại; `null`/`undefined` = không xác định (vòng quay). */\n  value?: number | null | undefined;\n  /**\n   * Chuỗi trình đọc màn hình đọc thay cho con số (`aria-valuetext`) và chữ giữa vòng — mặc định\n   * phần trăm làm tròn, vd `\"45%\"`.\n   */\n  getValueText?(value: number, min: number, max: number): string;\n  min?: number;\n  max?: number;\n  /** Đường kính, px. */\n  size?: number;\n  /** Độ dày nét, px. */\n  thickness?: number;\n  /**\n   * Nhãn HIỆN của vòng, đồng thời là tên của `role=\"progressbar\"`. Không đặt nhãn hiện thì PHẢI\n   * truyền `aria-label` — progressbar không tên là lỗi a11y (ARIA 1.2), gói không tự đặt tên\n   * chung chung thay app (giống `Progress`).\n   */\n  label?: string;\n  asChild?: boolean;\n}\n\n/**\n * CircularProgress — tiến trình dạng VÒNG, cặp với `Progress` (dạng thanh) của gói.\n * Ráp từ các phần (`CircularProgressIndicator` › `Track` + `Range`, `CircularProgressValueText`),\n * hoặc dùng sẵn `CircularProgressCombined`.\n *\n * Phần đã chạy là `text-primary-ink`, cùng bậc với thanh `Progress`; rãnh xám trung tính. Đổi tông\n * thì truyền bậc INK cho `CircularProgressRange` (vd `className=\"text-success-ink\"`), không phải\n * token tô nền `text-success` — rãnh không cần đổi theo (số đo ở `CircularProgressTrack`).\n *\n * ⚠ Trạng thái không xác định cần `--animate-spin-around` + `@keyframes spin-around` trong\n * styles.css; thiếu thì vòng đứng yên ở một cung 25% (không lỗi, không cảnh báo).\n */\nfunction CircularProgress(props: CircularProgressProps) {\n  const {\n    value: valueProp = null,\n    getValueText = getDefaultValueText,\n    min: minProp = 0,\n    max: maxProp,\n    size = 48,\n    thickness = 4,\n    label,\n    asChild,\n    className,\n    children,\n    ...rootProps\n  } = props;\n\n  if ((maxProp || maxProp === 0) && !getIsValidMaxNumber(maxProp)) {\n    if (IS_DEV) {\n      console.error(getInvalidMaxError(`${maxProp}`, CIRCULAR_PROGRESS_NAME));\n    }\n  }\n\n  const rawMax = getIsValidMaxNumber(maxProp) ? maxProp : DEFAULT_MAX;\n  const min = getIsValidNumber(minProp) ? minProp : 0;\n  const max = rawMax <= min ? min + 1 : rawMax;\n\n  if (IS_DEV && thickness >= size) {\n    console.warn(\n      `CircularProgress: \\`thickness\\` (${thickness}) phải nhỏ hơn \\`size\\` (${size}) thì vòng mới vẽ đúng.`\n    );\n  }\n\n  if (valueProp !== null && !getIsValidValueNumber(valueProp, min, max)) {\n    if (IS_DEV) {\n      console.error(getInvalidValueError(`${valueProp}`, CIRCULAR_PROGRESS_NAME));\n    }\n  }\n\n  const value = getIsValidValueNumber(valueProp, min, max)\n    ? valueProp\n    : getIsValidNumber(valueProp) && valueProp > max\n      ? max\n      : getIsValidNumber(valueProp) && valueProp < min\n        ? min\n        : null;\n\n  const valueText = getIsValidNumber(value) ? getValueText(value, min, max) : undefined;\n  const state = getProgressState(value, max);\n  const radius = Math.max(0, (size - thickness) / 2);\n  const center = size / 2;\n  const circumference = 2 * Math.PI * radius;\n\n  const percentage = getIsValidNumber(value) ? (max === min ? 1 : (value - min) / (max - min)) : null;\n\n  const labelId = React.useId();\n  const valueTextId = React.useId();\n\n  const contextValue = React.useMemo<CircularProgressContextValue>(\n    () => ({\n      value,\n      valueText,\n      max,\n      min,\n      state,\n      radius,\n      thickness,\n      size,\n      center,\n      circumference,\n      percentage,\n      valueTextId\n    }),\n    [value, valueText, max, min, state, radius, thickness, size, center, circumference, percentage, valueTextId]\n  );\n\n  const RootPrimitive = asChild ? Slot : \"div\";\n\n  return (\n    <CircularProgressContext.Provider value={contextValue}>\n      <RootPrimitive\n        role=\"progressbar\"\n        aria-describedby={valueText ? valueTextId : undefined}\n        aria-labelledby={label ? labelId : undefined}\n        aria-valuemax={max}\n        aria-valuemin={min}\n        aria-valuenow={getIsValidNumber(value) ? value : undefined}\n        aria-valuetext={valueText}\n        data-state={state}\n        data-value={value ?? undefined}\n        data-max={max}\n        data-min={min}\n        data-percentage={percentage}\n        data-slot=\"circular-progress\"\n        {...rootProps}\n        className={cn(\"relative inline-flex w-fit items-center justify-center\", label && \"flex-col gap-1.5\", className)}\n      >\n        {/*\n         * ⚠ Khác thượng nguồn: bản gốc đặt nhãn làm anh em của vòng NGAY TRONG gốc, trong khi\n         * `CircularProgressValueText` là `absolute inset-0` phủ CẢ gốc — có nhãn là chữ \"65%\" đè\n         * lên chữ nhãn. Khi có `label`: bọc phần con trong một khung đúng cỡ vòng (`relative`, nên\n         * chữ giá trị căn giữa VÒNG), nhãn xuống dưới vòng. Không có `label` thì DOM y như bản gốc.\n         */}\n        {label ? (\n          <div data-slot=\"circular-progress-ring\" className=\"relative inline-flex items-center justify-center\">\n            {children}\n          </div>\n        ) : (\n          children\n        )}\n        {label && (\n          <div id={labelId} data-slot=\"circular-progress-label\" className=\"text-sm\">\n            {label}\n          </div>\n        )}\n      </RootPrimitive>\n    </CircularProgressContext.Provider>\n  );\n}\n\nfunction CircularProgressIndicator(props: React.ComponentProps<\"svg\">) {\n  const { className, ...indicatorProps } = props;\n\n  const context = useCircularProgressContext(INDICATOR_NAME);\n\n  return (\n    <svg\n      aria-hidden=\"true\"\n      focusable=\"false\"\n      viewBox={`0 0 ${context.size} ${context.size}`}\n      data-state={context.state}\n      data-value={context.value ?? undefined}\n      data-max={context.max}\n      data-min={context.min}\n      data-percentage={context.percentage}\n      data-slot=\"circular-progress-indicator\"\n      width={context.size}\n      height={context.size}\n      {...indicatorProps}\n      className={cn(\"-rotate-90 transform\", className)}\n    />\n  );\n}\n\nCircularProgressIndicator.displayName = INDICATOR_NAME;\n\nfunction CircularProgressTrack(props: React.ComponentProps<\"circle\">) {\n  const { className, ...trackProps } = props;\n\n  const context = useCircularProgressContext(TRACK_NAME);\n\n  return (\n    <circle\n      data-state={context.state}\n      data-slot=\"circular-progress-track\"\n      cx={context.center}\n      cy={context.center}\n      r={context.radius}\n      fill=\"none\"\n      stroke=\"currentColor\"\n      strokeWidth={context.thickness}\n      strokeLinecap=\"round\"\n      vectorEffect=\"non-scaling-stroke\"\n      {...trackProps}\n      className={cn(\n        /*\n         * GIỮ NGUYÊN thượng nguồn — rãnh xám trung tính `text-muted-foreground/20`, KHÔNG phải tint\n         * `/20` của bậc ink như rãnh `Progress`. Đã đo cả hai; thứ mang THÔNG TIN ở đây là ranh\n         * giới cung-đã-chạy ⇄ rãnh (chỗ cung dừng lại chính là giá trị), và rãnh trung tính giữ\n         * ranh giới đó TỐT HƠN (bảng tương phản cao, cung `text-primary-ink`):\n         *\n         *                                   rãnh trung tính      tint `primary-ink/20`\n         *     cung ⇄ rãnh trên --background : 5,03 (L) · 9,65 (D)   4,85 (L) · 7,97 (D)\n         *     tệ nhất, rãnh trên --muted    : 4,71 (L) · 8,00 (D)   4,54 (L) · 6,52 (D)\n         *     (viền trang trí --border       : 2,62 (L) ✗ — loại)\n         *\n         * Và nó không phụ thuộc tông: app đổi cung sang `text-success-ink`/`text-destructive-ink`\n         * thì rãnh vẫn đúng (5,03 · 5,51:1 trên nền trắng) mà không phải đổi theo.\n         *\n         * Rãnh ⇄ nền trang chỉ ~1,3:1 — CỐ Ý, như rãnh `Progress`: không có cặp màu nào vừa ≥3:1\n         * với nhau vừa ≥3:1 với nền trắng (chứng minh ở chú thích `Slider`). Khác `Progress` ở chỗ\n         * vòng KHÔNG cần viền khoanh mốc 100%: hình tròn tự khép và cung luôn bắt đầu ở 12 giờ, nên\n         * TỈ LỆ đọc được từ góc của cung mà không cần thấy rãnh. Một nét tròn liền, không nét nào\n         * cắt nhau, nên màu có alpha không để lộ vệt nối (xem \"Cạm bẫy\" về icon trong CLAUDE.md).\n         */\n        \"text-muted-foreground/20\",\n        className\n      )}\n    />\n  );\n}\n\nfunction CircularProgressRange(props: React.ComponentProps<\"circle\">) {\n  const { className, ...rangeProps } = props;\n\n  const context = useCircularProgressContext(RANGE_NAME);\n\n  const strokeDasharray = context.circumference;\n  const strokeDashoffset =\n    context.state === \"indeterminate\"\n      ? context.circumference * 0.75\n      : context.percentage !== null\n        ? context.circumference - context.percentage * context.circumference\n        : context.circumference;\n\n  return (\n    <circle\n      data-state={context.state}\n      data-value={context.value ?? undefined}\n      data-max={context.max}\n      data-min={context.min}\n      data-slot=\"circular-progress-range\"\n      cx={context.center}\n      cy={context.center}\n      r={context.radius}\n      fill=\"none\"\n      stroke=\"currentColor\"\n      strokeWidth={context.thickness}\n      strokeLinecap=\"round\"\n      strokeDasharray={strokeDasharray}\n      strokeDashoffset={strokeDashoffset}\n      vectorEffect=\"non-scaling-stroke\"\n      {...rangeProps}\n      className={cn(\n        /*\n         * ⚠ Khác thượng nguồn: `text-primary` (bậc TÔ NỀN, gold #E8B824 chỉ 1,86:1 trên nền trắng)\n         * → `text-primary-ink`, đúng bậc của thanh `Progress`: 6,51:1 (light) · 12,67:1 (dark)\n         * trên --background, tệ nhất 6,09:1 · 10,80:1 trên --muted (bảng tương phản cao). Cung là\n         * thông tin thị giác (WCAG 1.4.11, 3:1).\n         * Hiệu ứng quay đọc `--animate-spin-around` của styles.css; `motion-reduce` thì đứng yên.\n         */\n        \"origin-center text-primary-ink transition-all duration-300 ease-in-out\",\n        context.state === \"indeterminate\" &&\n          \"motion-safe:[animation:var(--animate-spin-around)] motion-reduce:animate-none\",\n        className\n      )}\n    />\n  );\n}\n\ninterface CircularProgressValueTextProps extends React.ComponentProps<\"span\"> {\n  asChild?: boolean;\n}\n\nfunction CircularProgressValueText(props: CircularProgressValueTextProps) {\n  const { asChild, className, children, ...valueTextProps } = props;\n\n  const context = useCircularProgressContext(VALUE_TEXT_NAME);\n\n  const ValueTextPrimitive = asChild ? Slot : \"span\";\n\n  return (\n    <ValueTextPrimitive\n      id={context.valueTextId}\n      data-state={context.state}\n      data-slot=\"circular-progress-value-text\"\n      {...valueTextProps}\n      className={cn(\"absolute inset-0 flex items-center justify-center text-sm font-medium\", className)}\n    >\n      {children ?? context.valueText}\n    </ValueTextPrimitive>\n  );\n}\n\nfunction CircularProgressCombined(props: CircularProgressProps) {\n  return (\n    <CircularProgress {...props}>\n      <CircularProgressIndicator>\n        <CircularProgressTrack />\n        <CircularProgressRange />\n      </CircularProgressIndicator>\n      <CircularProgressValueText />\n    </CircularProgress>\n  );\n}\n\nexport {\n  CircularProgress,\n  CircularProgressCombined,\n  CircularProgressIndicator,\n  type CircularProgressProps,\n  CircularProgressRange,\n  CircularProgressTrack,\n  CircularProgressValueText,\n  type CircularProgressValueTextProps\n};\n"],"mappings":"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","names":[]}

package/dist/components/ui/cropper-constants.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Nhãn mặc định của `Cropper`.
+ *
+ * Module **CỐ Ý không có `"use client"`**: mọi export của một file `"use client"` tới Server
+ * Component là client-reference proxy, đọc ra `undefined` mà KHÔNG throw — xem
+ * `src/chart/chart-colors.ts`. Barrel xuất module này TRỰC TIẾP; `cropper.tsx` chỉ `import`.
+ */
+/**
+ * Chuỗi a11y của `Cropper` — truyền `labels` cho `Cropper` để ghi đè từng khoá.
+ *
+ * ⚠ Thượng nguồn (Dice UI) KHÔNG có chuỗi nào: vùng cắt nhận focus bằng Tab (`tabIndex=0`) nhưng
+ * không role, không tên, không mô tả — trình đọc màn hình gặp một phần tử focus được mà không
+ * biết nó là gì, và người dùng không có cách nào biết phím nào điều khiển được nó.
+ */
+interface CropperLabels {
+    /**
+     * Tên của vùng cắt (`aria-label`). Truyền thẳng `aria-label` cho `Cropper` cũng được — prop
+     * đó thắng, vì nó được trải SAU giá trị mặc định.
+     */
+    label: string;
+    /** `aria-roledescription` — tên loại control mà trình đọc màn hình đọc thay cho "ứng dụng". */
+    roleDescription: string;
+    /** Hướng dẫn phím, gắn vào vùng cắt qua `aria-describedby`. */
+    instructions: string;
+    /**
+     * Câu đọc qua vùng `aria-live` sau mỗi lần phóng/thu bằng phím. `zoom` là hệ số thô (1 = vừa
+     * khung). Là HÀM vì có số chèn vào giữa câu.
+     */
+    zoomStatus: (zoom: number) => string;
+}
+/** Nhãn tiếng Việt mặc định — mọi khoá đều ghi đè được qua prop `labels` của `Cropper`. */
+declare const DEFAULT_CROPPER_LABELS: CropperLabels;
+
+export { type CropperLabels, DEFAULT_CROPPER_LABELS };

package/dist/components/ui/cropper-constants.js

@@ -0,0 +1,10 @@
+const DEFAULT_CROPPER_LABELS = {
+  label: "V\xF9ng c\u1EAFt \u1EA3nh",
+  roleDescription: "tr\xECnh c\u1EAFt \u1EA3nh",
+  instructions: "D\xF9ng c\xE1c ph\xEDm m\u0169i t\xEAn \u0111\u1EC3 di chuy\u1EC3n \u1EA3nh, gi\u1EEF Shift \u0111\u1EC3 di chuy\u1EC3n ch\u1EADm h\u01A1n. Ph\xEDm + v\xE0 - \u0111\u1EC3 ph\xF3ng to, thu nh\u1ECF.",
+  zoomStatus: (zoom) => `Thu ph\xF3ng ${Math.round(zoom * 100)}%`
+};
+export {
+  DEFAULT_CROPPER_LABELS
+};
+//# sourceMappingURL=cropper-constants.js.map

package/dist/components/ui/cropper-constants.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/components/ui/cropper-constants.ts"],"sourcesContent":["/**\n * Nhãn mặc định của `Cropper`.\n *\n * Module **CỐ Ý không có `\"use client\"`**: mọi export của một file `\"use client\"` tới Server\n * Component là client-reference proxy, đọc ra `undefined` mà KHÔNG throw — xem\n * `src/chart/chart-colors.ts`. Barrel xuất module này TRỰC TIẾP; `cropper.tsx` chỉ `import`.\n */\n\n/**\n * Chuỗi a11y của `Cropper` — truyền `labels` cho `Cropper` để ghi đè từng khoá.\n *\n * ⚠ Thượng nguồn (Dice UI) KHÔNG có chuỗi nào: vùng cắt nhận focus bằng Tab (`tabIndex=0`) nhưng\n * không role, không tên, không mô tả — trình đọc màn hình gặp một phần tử focus được mà không\n * biết nó là gì, và người dùng không có cách nào biết phím nào điều khiển được nó.\n */\nexport interface CropperLabels {\n  /**\n   * Tên của vùng cắt (`aria-label`). Truyền thẳng `aria-label` cho `Cropper` cũng được — prop\n   * đó thắng, vì nó được trải SAU giá trị mặc định.\n   */\n  label: string;\n  /** `aria-roledescription` — tên loại control mà trình đọc màn hình đọc thay cho \"ứng dụng\". */\n  roleDescription: string;\n  /** Hướng dẫn phím, gắn vào vùng cắt qua `aria-describedby`. */\n  instructions: string;\n  /**\n   * Câu đọc qua vùng `aria-live` sau mỗi lần phóng/thu bằng phím. `zoom` là hệ số thô (1 = vừa\n   * khung). Là HÀM vì có số chèn vào giữa câu.\n   */\n  zoomStatus: (zoom: number) => string;\n}\n\n/** Nhãn tiếng Việt mặc định — mọi khoá đều ghi đè được qua prop `labels` của `Cropper`. */\nexport const DEFAULT_CROPPER_LABELS: CropperLabels = {\n  label: \"Vùng cắt ảnh\",\n  roleDescription: \"trình cắt ảnh\",\n  instructions:\n    \"Dùng các phím mũi tên để di chuyển ảnh, giữ Shift để di chuyển chậm hơn. Phím + và - để phóng to, thu nhỏ.\",\n  zoomStatus: (zoom) => `Thu phóng ${Math.round(zoom * 100)}%`\n};\n"],"mappings":"AAiCO,MAAM,yBAAwC;AAAA,EACnD,OAAO;AAAA,EACP,iBAAiB;AAAA,EACjB,cACE;AAAA,EACF,YAAY,CAAC,SAAS,gBAAa,KAAK,MAAM,OAAO,GAAG,CAAC;AAC3D;","names":[]}

package/dist/components/ui/cropper.d.ts

@@ -0,0 +1,106 @@
+import * as class_variance_authority_types from 'class-variance-authority/types';
+import { VariantProps } from 'class-variance-authority';
+import * as React from 'react';
+import { CropperLabels } from './cropper-constants.js';
+
+interface Point {
+    x: number;
+    y: number;
+}
+interface Size {
+    width: number;
+    height: number;
+}
+interface Area {
+    width: number;
+    height: number;
+    x: number;
+    y: number;
+}
+interface MediaSize {
+    width: number;
+    height: number;
+    naturalWidth: number;
+    naturalHeight: number;
+}
+type Shape = "rectangle" | "circle";
+type ObjectFit = "contain" | "cover" | "horizontal-cover" | "vertical-cover";
+interface DivProps extends React.ComponentProps<"div"> {
+    asChild?: boolean;
+}
+interface StoreState {
+    crop: Point;
+    zoom: number;
+    rotation: number;
+    mediaSize: MediaSize | null;
+    cropSize: Size | null;
+    isDragging: boolean;
+    isWheelZooming: boolean;
+}
+declare function useStore<T>(selector: (state: StoreState) => T): T;
+interface CropperProps extends DivProps {
+    crop?: Point;
+    zoom?: number;
+    minZoom?: number;
+    maxZoom?: number;
+    zoomSpeed?: number;
+    rotation?: number;
+    keyboardStep?: number;
+    aspectRatio?: number;
+    shape?: Shape;
+    objectFit?: ObjectFit;
+    allowOverflow?: boolean;
+    preventScrollZoom?: boolean;
+    withGrid?: boolean;
+    /**
+     * Chuỗi a11y của vùng cắt — ghi đè từng khoá, mặc định `DEFAULT_CROPPER_LABELS` (tiếng Việt).
+     *
+     * ⚠ Thêm so với thượng nguồn — xem `CropperLabels`.
+     */
+    labels?: Partial<CropperLabels>;
+    onCropChange?: (crop: Point) => void;
+    onCropSizeChange?: (cropSize: Size) => void;
+    onCropAreaChange?: (croppedArea: Area, croppedAreaPixels: Area) => void;
+    onCropComplete?: (croppedArea: Area, croppedAreaPixels: Area) => void;
+    onZoomChange?: (zoom: number) => void;
+    onRotationChange?: (rotation: number) => void;
+    onMediaLoaded?: (mediaSize: MediaSize) => void;
+    onInteractionStart?: () => void;
+    onInteractionEnd?: () => void;
+    onWheelZoom?: (event: WheelEvent) => void;
+}
+/**
+ * Cropper — cắt ảnh/video: kéo để dời, lăn chuột/chụm hai ngón để phóng, phím mũi tên và + / -.
+ *
+ * Ở Comitor dùng để cắt ảnh đại diện hoặc logo công ty TRƯỚC khi tải lên. Component chỉ BÁO vùng
+ * cắt (`onCropComplete(croppedArea, croppedAreaPixels)`) — việc vẽ ra canvas và tải lên là của
+ * app. Cố ý không phụ thuộc gì ngoài peer bắt buộc để sống được ở entry chính; `ImageUploadField`
+ * (entry `/uploader`, kéo theo `@uppy/*`) ghép với nó ở tầng app, không ở đây.
+ *
+ * `crop` / `zoom` / `rotation` là controlled KHI được truyền, uncontrolled khi bỏ trống.
+ */
+declare function Cropper(props: CropperProps): React.JSX.Element;
+declare const cropperMediaVariants: (props?: ({
+    objectFit?: "contain" | "cover" | "horizontal-cover" | "vertical-cover" | null | undefined;
+} & class_variance_authority_types.ClassProp) | undefined) => string;
+interface CropperImageProps extends React.ComponentProps<"img">, VariantProps<typeof cropperMediaVariants> {
+    asChild?: boolean;
+    snapPixels?: boolean;
+}
+/** Ảnh cần cắt. Nhớ truyền `alt` — ảnh ở đây mang nội dung, không phải trang trí. */
+declare function CropperImage(props: CropperImageProps): React.JSX.Element;
+interface CropperVideoProps extends React.ComponentProps<"video">, VariantProps<typeof cropperMediaVariants> {
+    asChild?: boolean;
+    snapPixels?: boolean;
+}
+declare function CropperVideo(props: CropperVideoProps): React.JSX.Element;
+declare const cropperAreaVariants: (props?: ({
+    shape?: "circle" | "rectangle" | null | undefined;
+    withGrid?: boolean | null | undefined;
+} & class_variance_authority_types.ClassProp) | undefined) => string;
+interface CropperAreaProps extends DivProps, VariantProps<typeof cropperAreaVariants> {
+    snapPixels?: boolean;
+}
+declare function CropperArea(props: CropperAreaProps): React.JSX.Element | null;
+
+export { Cropper, CropperArea, type Area as CropperAreaData, type CropperAreaProps, CropperImage, type CropperImageProps, type MediaSize as CropperMediaSize, type ObjectFit as CropperObjectFit, type Point as CropperPoint, type CropperProps, type Shape as CropperShape, type Size as CropperSize, CropperVideo, type CropperVideoProps, useStore as useCropper };