@godxjp/ui 19.6.0 → 20.1.0

package/dist/i18n/messages/vi.json

@@ -23,7 +23,8 @@
     },
     "datePicker": {
       "placeholder": "Chọn ngày",
-      "openCalendar": "Mở lịch"
+      "openCalendar": "Mở lịch",
+      "quarter": "Quý {quarter}"
     },
     "dateRangePicker": {
       "placeholder": "Chọn khoảng ngày",
@@ -39,7 +40,10 @@
       "openPicker": "Mở chọn giờ",
       "meridiem": "Buổi",
       "am": "SA",
-      "pm": "CH"
+      "pm": "CH",
+      "now": "Bây giờ",
+      "confirm": "Chọn",
+      "second": "Giây"
     },
     "searchInput": {
       "placeholder": "Tìm kiếm…"
@@ -55,7 +59,7 @@
     "upload": {
       "dropzoneLabel": "Tải file lên",
       "dropzoneHint": "Kéo thả file vào đây, hoặc bấm để chọn",
-      "dropzoneMeta": "Upload vào temp — promote khi lưu form",
+      "dropzoneMeta": "Tệp đã chọn sẽ hiển thị tại đây.",
       "buttonLabel": "Chọn file",
       "addImage": "Thêm ảnh",
       "uploading": "Đang tải lên…",
@@ -75,7 +79,17 @@
       "statusFailed": "{count} tệp tải lên thất bại",
       "removeImage": "Xóa ảnh",
       "removeFile": "Xóa {name}",
-      "cropDescription": "Kéo thanh thu phóng rồi lưu để cắt ảnh thành hình vuông."
+      "cropDescription": "Kéo thanh thu phóng rồi lưu để cắt ảnh thành hình vuông.",
+      "preview": "Xem trước",
+      "download": "Tải xuống",
+      "retry": "Thử lại",
+      "start": "Tải lên",
+      "cancel": "Huỷ",
+      "rejectAccept": "{name}: loại tệp không được phép.",
+      "rejectSize": "{name}: tệp quá lớn.",
+      "rejectCount": "{name}: đã đủ số lượng tệp.",
+      "rejectBeforeUpload": "{name}: kiểm tra tệp thất bại.",
+      "readFailed": "Không thể đọc thư mục đã chọn."
     },
     "cascader": {
       "placeholder": "Chọn…",
@@ -109,6 +123,9 @@
       "empty": "Không có kết quả",
       "error": "Không tải được lựa chọn"
     },
+    "selection": {
+      "overflow": "+{count}"
+    },
     "monthPicker": {
       "openGrid": "Mở chọn tháng",
       "previousYear": "Năm trước",
@@ -132,6 +149,14 @@
     },
     "formErrors": {
       "title": "Dữ liệu nhập có lỗi, vui lòng kiểm tra"
+    },
+    "form": {
+      "optional": "(không bắt buộc)",
+      "success": "Hợp lệ",
+      "warning": "Cần kiểm tra",
+      "error": "Không hợp lệ",
+      "validating": "Đang kiểm tra",
+      "submitFailed": "Không thể gửi biểu mẫu. Vui lòng thử lại."
     }
   },
   "feedback": {
@@ -154,6 +179,7 @@
     },
     "appShell": {
       "sidebarLabel": "Thanh bên",
+      "navRailLabel": "Không gian làm việc",
       "headerLabel": "Đầu trang",
       "mainLabel": "Nội dung chính",
       "footerLabel": "Chân trang",
@@ -246,6 +272,10 @@
       "denied": "Bạn không có quyền xem ma trận này",
       "deniedDescription": "Hãy đề nghị quản trị viên cấp quyền truy cập.",
       "loading": "Đang tải quyền…"
+    },
+    "progress": {
+      "ariaLabel": "Tiến độ",
+      "breakdownSeparator": ", "
     }
   },
   "ui": {
@@ -279,8 +309,13 @@
     }
   },
   "navigation": {
+    "tabs": {
+      "addTab": "Thêm tab",
+      "removeTab": "Đóng tab"
+    },
     "steps": {
       "ariaLabel": "Tiến trình",
+      "percentLabel": "Tiến độ bước hiện tại",
       "status": {
         "wait": "Đang chờ",
         "process": "Bước hiện tại",
@@ -318,6 +353,7 @@
       "page": "Trang {page}",
       "pageSize": "Số dòng mỗi trang",
       "pageSizeTrigger": "{size} / trang",
+      "jumpTo": "Tới trang",
       "pageSizeOption": "{size} / trang",
       "total": "Tổng {total} mục"
     },
@@ -347,6 +383,9 @@
       "logistics": "Logistics Teal",
       "partner": "Partner Orange",
       "slate": "HQ Slate"
+    },
+    "settingToggle": {
+      "label": "{setting}: {value}"
     }
   },
   "locale": {
@@ -390,7 +429,19 @@
     "error": "Không tải được danh sách này",
     "errorDescription": "Không lấy được dữ liệu. Vui lòng thử lại sau giây lát.",
     "denied": "Bạn không có quyền xem danh sách này",
-    "deniedDescription": "Hãy đề nghị quản trị viên cấp quyền xem các bản ghi này."
+    "deniedDescription": "Hãy đề nghị quản trị viên cấp quyền xem các bản ghi này.",
+    "selectInvert": "Đảo lựa chọn",
+    "selectNone": "Bỏ chọn tất cả",
+    "selectionMenu": "Tuỳ chọn lựa chọn",
+    "filterColumn": "Lọc",
+    "filterReset": "Bỏ lọc",
+    "expandColumn": "Mở rộng",
+    "expandRow": "Mở rộng hàng",
+    "collapseRow": "Thu gọn hàng",
+    "sortAscending": "Sắp xếp tăng dần",
+    "sortDescending": "Sắp xếp giảm dần",
+    "sortCancel": "Bỏ sắp xếp",
+    "selectColumn": "Chọn"
   },
   "dataGrid": {
     "search": "Tìm kiếm",
@@ -458,5 +509,13 @@
     "summaryPie": "Biểu đồ tròn gồm {slices} phần",
     "summaryTrend": "Biểu đồ cột xu hướng gồm {points} điểm dữ liệu",
     "trendCurrent": "hiện tại"
+  },
+  "rangeTimeline": {
+    "outsideRange": "Ngoài khoảng đang xem",
+    "schedule": "Lịch công việc"
+  },
+  "textExamples": {
+    "preservedText": "Văn bản thuần",
+    "sampleText": "Dòng đầu\n  Dòng thụt vào\n\nDòng cuối"
   }
 }

package/dist/inertia/index.d.ts

@@ -11,6 +11,7 @@ export interface InertiaFormLike<TData extends Record<string, unknown> = Record<
     errors: Partial<Record<string, string>>;
     /** True while a submit request is in flight. */
     processing: boolean;
+    reset?(): void;
 }
 /**
  * Wrap an Inertia `useForm()` object as a framework-agnostic {@link FormStateAdapter} so it drives
@@ -105,3 +106,22 @@ export interface InertiaLinkLike {
  * ```
  */
 export declare function inertiaSidebarLink<P extends InertiaLinkLike>(Link: ComponentType<P>): SidebarLinkComponentProp;
+/** Visit callbacks needed to connect Upload to an Inertia multipart endpoint. */
+export interface InertiaUploadCallbacks {
+    forceFormData: true;
+    async: true;
+    onProgress: (progress: {
+        percentage?: number;
+    } | undefined) => void;
+    onSuccess: () => void;
+    onError: (errors: Record<string, string>) => void;
+    onCancelToken: (token: {
+        cancel: () => void;
+    }) => void;
+    onCancel: () => void;
+    onNetworkError: (error: Error) => boolean;
+    onHttpException: () => boolean;
+    onFinish: () => void;
+}
+/** Bridge redirect-based Inertia uploads to Upload's progress/abort/retry lifecycle. */
+export declare function inertiaUpload(send: (file: File, callbacks: InertiaUploadCallbacks) => void, errorMessage: string): NonNullable<import("../props/components/data-entry.prop.js").UploadProp["onUpload"]>;

package/dist/inertia/index.js

@@ -6,7 +6,8 @@ function inertiaAdapter(form) {
     setValue: (name, value) => form.setData(name, value),
     getError: (name) => form.errors[name],
     isSubmitting: form.processing,
-    getValues: () => form.data
+    getValues: () => form.data,
+    reset: form.reset ? () => form.reset?.() : void 0
   };
 }
 function useInertiaField(form, name) {
@@ -20,8 +21,66 @@ function useInertiaField(form, name) {
 function inertiaSidebarLink(Link) {
   return createSidebarLink(Link, "href");
 }
+function inertiaUpload(send, errorMessage) {
+  return (file, _item, context) => new Promise((resolve, reject) => {
+    let cancel;
+    let settled = false;
+    const abort = () => {
+      cancel?.();
+      fail(new DOMException("Upload aborted", "AbortError"));
+    };
+    const cleanup = () => context.signal.removeEventListener("abort", abort);
+    const fail = (error) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      reject(error);
+    };
+    if (context.signal.aborted) {
+      abort();
+      return;
+    }
+    context.signal.addEventListener("abort", abort, { once: true });
+    try {
+      send(file, {
+        forceFormData: true,
+        async: true,
+        onProgress: (progress) => {
+          if (!settled) context.onProgress(progress?.percentage ?? 0);
+        },
+        onSuccess: () => {
+          if (!settled) {
+            settled = true;
+            cleanup();
+            resolve({});
+          }
+        },
+        onError: (errors) => fail(new Error(Object.values(errors)[0] ?? errorMessage)),
+        onCancelToken: (token) => {
+          cancel = token.cancel;
+          if (context.signal.aborted) token.cancel();
+        },
+        onCancel: () => fail(new DOMException("Upload aborted", "AbortError")),
+        onNetworkError: () => {
+          fail(new Error(errorMessage));
+          return false;
+        },
+        onHttpException: () => {
+          fail(new Error(errorMessage));
+          return false;
+        },
+        onFinish: () => {
+          if (!settled) fail(new Error(errorMessage));
+        }
+      });
+    } catch (error) {
+      fail(error);
+    }
+  });
+}
 export {
   inertiaAdapter,
   inertiaSidebarLink,
+  inertiaUpload,
   useInertiaField
 };

package/dist/lib/control-styles.d.ts

@@ -1,18 +1,40 @@
 /** Shared control sizing — reads `--control-height`, `--font-size-*` from density / theme. */
-export declare const controlMultilineClass = "ui-control-multiline aria-invalid:border-destructive w-full rounded-[var(--control-radius)] border-input bg-background ring-offset-background placeholder:text-muted-foreground focus-visible:outline-none";
+export declare const controlMultilineClass = "ui-control-multiline aria-invalid:border-destructive data-[status=error]:border-destructive data-[status=warning]:border-warning w-full rounded-[var(--control-radius)] border-input bg-background ring-offset-background placeholder:text-muted-foreground";
 /**
  * Multiline control with its own chrome removed, for a textarea EMBEDDED in a surface that already
  * draws the box — a chat composer inside a Card, an inline edit cell, a comment box in a panel.
  * Two nested rounded borders is the tell that this was missing.
  */
-export declare const controlMultilineGhostClass = "ui-control-multiline w-full min-h-0 border-0 bg-transparent shadow-none placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-0";
+export declare const controlMultilineGhostClass = "ui-control-multiline data-[status=error]:border-destructive data-[status=warning]:border-warning w-full min-h-0 border-0 bg-transparent shadow-none placeholder:text-muted-foreground focus-visible:ring-0";
+/**
+ * Multiline control drawn as antd's `filled` variant — a tinted surface instead of a boundary.
+ *
+ * It is a SEPARATE string rather than `controlMultilineClass` plus a modifier because
+ * `bg-background` lives in `@layer utilities`, which outranks every component-layer rule: a
+ * `.ui-control--filled` appended to the outlined list would be silently overpainted and no gate
+ * would catch it. The two lists differ only in which chrome utilities they carry.
+ */
+export declare const controlMultilineFilledClass = "ui-control-multiline ui-control--filled aria-invalid:border-destructive data-[status=error]:border-destructive data-[status=warning]:border-warning w-full rounded-[var(--control-radius)] ring-offset-background placeholder:text-muted-foreground";
 /**
  * Open-state ring for popup-style triggers (Select / Cascader / TreeSelect / SearchSelect). Radix
  * moves focus INTO the popup on open, so the trigger loses `:focus-visible` and — without this —
  * an open popover shows only a border change (no ring), inconsistent with a focused Input.
  */
 export declare const controlOpenRingClass = "ui-control-trigger";
-export declare const controlTriggerClass = "ui-control ui-control-trigger flex items-center justify-between gap-2 whitespace-nowrap rounded-[var(--control-radius)] border-input bg-background transition-[color,box-shadow] focus-visible:outline-none [&>span]:line-clamp-1";
+/**
+ * The trigger WITHOUT a surface — no `border-input`, no `bg-background`.
+ *
+ * Those two are Tailwind utilities, and `@layer utilities` beats `@layer components`, so a
+ * `[data-variant]` / `[data-status]` rule in control.css can never recolour a trigger that carries
+ * them (the same trap that killed `.ui-app-setting-picker-icon` in gh#366 and
+ * `--control-bounded-width` in gh#375). A control that wants the antd `variant` × `status` matrix
+ * therefore composes THIS class plus `ui-control-surface`, which supplies the identical resting
+ * border and fill from `--control-surface-*`.
+ */
+export declare const controlTriggerBaseClass = "ui-control ui-control-trigger flex items-center justify-between gap-2 whitespace-nowrap rounded-[var(--control-radius)] transition-[color,box-shadow] [&>[data-slot=select-value]]:line-clamp-1";
+export declare const controlTriggerClass = "ui-control ui-control-trigger flex items-center justify-between gap-2 whitespace-nowrap rounded-[var(--control-radius)] transition-[color,box-shadow] [&>[data-slot=select-value]]:line-clamp-1 border-input bg-background";
+/** `controlTriggerBaseClass` + the token-driven surface — the select-family trigger. */
+export declare const controlSurfaceTriggerClass = "ui-control ui-control-trigger flex items-center justify-between gap-2 whitespace-nowrap rounded-[var(--control-radius)] transition-[color,box-shadow] [&>[data-slot=select-value]]:line-clamp-1 ui-control-surface";
 export declare const controlIconClass = "size-[length:var(--control-height)] shrink-0";
 export declare const controlIconSmClass = "size-[calc(var(--control-height)-0.5rem)] shrink-0";
 /** Leading/affix icon inside an input row (search, command) — sized to `--control-icon-size`. */

package/dist/lib/control-styles.js

@@ -1,7 +1,10 @@
-const controlMultilineClass = "ui-control-multiline aria-invalid:border-destructive w-full rounded-[var(--control-radius)] border-input bg-background ring-offset-background placeholder:text-muted-foreground focus-visible:outline-none";
-const controlMultilineGhostClass = "ui-control-multiline w-full min-h-0 border-0 bg-transparent shadow-none placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-0";
+const controlMultilineClass = "ui-control-multiline aria-invalid:border-destructive data-[status=error]:border-destructive data-[status=warning]:border-warning w-full rounded-[var(--control-radius)] border-input bg-background ring-offset-background placeholder:text-muted-foreground";
+const controlMultilineGhostClass = "ui-control-multiline data-[status=error]:border-destructive data-[status=warning]:border-warning w-full min-h-0 border-0 bg-transparent shadow-none placeholder:text-muted-foreground focus-visible:ring-0";
+const controlMultilineFilledClass = "ui-control-multiline ui-control--filled aria-invalid:border-destructive data-[status=error]:border-destructive data-[status=warning]:border-warning w-full rounded-[var(--control-radius)] ring-offset-background placeholder:text-muted-foreground";
 const controlOpenRingClass = "ui-control-trigger";
-const controlTriggerClass = "ui-control ui-control-trigger flex items-center justify-between gap-2 whitespace-nowrap rounded-[var(--control-radius)] border-input bg-background transition-[color,box-shadow] focus-visible:outline-none [&>span]:line-clamp-1";
+const controlTriggerBaseClass = "ui-control ui-control-trigger flex items-center justify-between gap-2 whitespace-nowrap rounded-[var(--control-radius)] transition-[color,box-shadow] [&>[data-slot=select-value]]:line-clamp-1";
+const controlTriggerClass = `${controlTriggerBaseClass} border-input bg-background`;
+const controlSurfaceTriggerClass = `${controlTriggerBaseClass} ui-control-surface`;
 const controlIconClass = "size-[length:var(--control-height)] shrink-0";
 const controlIconSmClass = "size-[calc(var(--control-height)-0.5rem)] shrink-0";
 const controlIconLeadingClass = "size-[length:var(--control-icon-size)] shrink-0";
@@ -20,8 +23,11 @@ export {
   controlIconLeadingClass,
   controlIconSmClass,
   controlMultilineClass,
+  controlMultilineFilledClass,
   controlMultilineGhostClass,
   controlOpenRingClass,
+  controlSurfaceTriggerClass,
+  controlTriggerBaseClass,
   controlTriggerClass,
   tableCellPaddingClass,
   tableHeadHeightClass,

package/dist/lib/datetime/picker-format.d.ts

@@ -0,0 +1,8 @@
+import { type Locale } from "date-fns";
+import type { DatePickerBaseProp, PickerDateFormatProp } from "../../props/components/data-entry.prop.js";
+/** Display is independent from the canonical value submitted by the field. */
+export declare function formatPickerDate(date: Date | undefined, format: PickerDateFormatProp | undefined, locale: string, withTime?: boolean): string;
+export declare function parsePickerDate(text: string, format: PickerDateFormatProp | undefined, parser?: (text: string) => Date | undefined, withTime?: boolean): Date | undefined;
+export declare function pickerDateAllowed(date: Date, min: Date | undefined, max: Date | undefined, disabled?: (date: Date) => boolean): boolean;
+/** Normalize a reporting period with the active calendar's week convention. */
+export declare function pickerPeriodStart(date: Date, picker: DatePickerBaseProp["picker"], locale: Pick<Locale, "options">): Date;

package/dist/lib/datetime/picker-format.js

@@ -0,0 +1,54 @@
+import {
+  format as formatDate,
+  isValid,
+  parse,
+  startOfDay,
+  startOfWeek,
+  startOfMonth,
+  startOfQuarter,
+  startOfYear
+} from "date-fns";
+import { parseDateInput, toIsoDate } from "./parse.js";
+function formatPickerDate(date, format, locale, withTime = false) {
+  if (!date || !isValid(date)) return "";
+  if (typeof format === "function") return format(date);
+  if (typeof format === "object") return new Intl.DateTimeFormat(locale, format).format(date);
+  if (typeof format === "string") return formatDate(date, format);
+  return withTime ? formatDate(date, "yyyy-MM-dd HH:mm") : toIsoDate(date);
+}
+function parsePickerDate(text, format, parser, withTime = false) {
+  const raw = text.trim();
+  if (!raw) return void 0;
+  const custom = parser?.(raw);
+  if (custom && isValid(custom)) return custom;
+  const pattern = typeof format === "string" ? format : withTime ? "yyyy-MM-dd HH:mm" : void 0;
+  if (pattern) {
+    const parsed = parse(raw, pattern, new Date(2e3, 0, 1));
+    if (isValid(parsed) && formatDate(parsed, pattern) === raw) return parsed;
+  }
+  if (withTime || !/^\d{4}-\d{2}-\d{2}$/.test(raw)) return void 0;
+  return parseDateInput(raw) ?? void 0;
+}
+function pickerDateAllowed(date, min, max, disabled) {
+  return isValid(date) && (!min || startOfDay(date) >= startOfDay(min)) && (!max || startOfDay(date) <= startOfDay(max)) && !disabled?.(date);
+}
+function pickerPeriodStart(date, picker, locale) {
+  switch (picker) {
+    case "week":
+      return startOfWeek(date, { locale });
+    case "month":
+      return startOfMonth(date);
+    case "quarter":
+      return startOfQuarter(date);
+    case "year":
+      return startOfYear(date);
+    default:
+      return date;
+  }
+}
+export {
+  formatPickerDate,
+  parsePickerDate,
+  pickerDateAllowed,
+  pickerPeriodStart
+};

package/dist/lib/slot.d.ts

@@ -0,0 +1,32 @@
+import * as React from "react";
+/**
+ * `Slot` — nền của `asChild`, và từ v20 là của CHÍNH kho này.
+ *
+ * ## Vì sao tự dựng
+ *
+ * `asChild` là API công khai của @godxjp/ui: 171 chỗ trong thư viện và mọi
+ * consumer đều dùng. React Aria KHÔNG có mô hình đó — nó dùng prop `render`.
+ * Nếu để nền quyết định API thì đợt đổi nền sẽ phá mọi consumer; nếu tự giữ
+ * `Slot` thì đổi nền là chuyện nội bộ. Ba mươi dòng ở đây mua lấy điều đó.
+ *
+ * ## Ngữ nghĩa, và một chỗ KHÁC `mergeProps`
+ *
+ * Gộp prop đi qua `mergeProps` của React Aria — cùng luật mà chính các
+ * component React Aria dùng bên trong, nên `Slot` cư xử nhất quán với phần còn
+ * lại của hệ. Nó cho: `className` nối chuỗi, handler CHAIN (cha chạy rồi tới
+ * con, không ghi đè), prop thường thì CON thắng.
+ *
+ * Nhưng `mergeProps` để `style` của con GHI ĐÈ HẲN style của cha — đo được:
+ * cha `{color:'red'}` + con `{margin:1}` ra `{margin:1}`, mất màu. Slot của
+ * Radix thì gộp nông hai object, và 171 call site đang dựa vào hành vi ấy. Nên
+ * `style` được gộp riêng ở đây, sau `mergeProps`.
+ *
+ * ## Đúng MỘT con
+ *
+ * `asChild` nghĩa là "đừng dựng thẻ của mình, mượn thẻ của con". Hai con thì
+ * không có thẻ nào để mượn, nên `Children.only` ném lỗi — sớm và rõ, thay vì
+ * lặng lẽ dựng ra một cây DOM không ai định.
+ */
+export declare function Slot({ children, ...slotProps }: React.HTMLAttributes<HTMLElement> & React.RefAttributes<HTMLElement> & {
+    children?: React.ReactNode;
+}): React.ReactElement<React.HTMLAttributes<HTMLElement>, string | React.JSXElementConstructor<any>>;

package/dist/lib/slot.js

@@ -0,0 +1,22 @@
+"use client";
+import { mergeProps } from "@react-aria/utils";
+import * as React from "react";
+function Slot({
+  children,
+  ...slotProps
+}) {
+  const child = React.Children.only(children);
+  const merged = mergeProps(
+    slotProps,
+    child.props
+  );
+  const slotStyle = slotProps.style;
+  const childStyle = child.props.style;
+  return React.cloneElement(child, {
+    ...merged,
+    style: slotStyle === void 0 && childStyle === void 0 ? void 0 : { ...slotStyle, ...childStyle }
+  });
+}
+export {
+  Slot
+};

package/dist/lib/variants.d.ts

@@ -1,12 +1,31 @@
 /** Prop → internal class maps. Apps use component props, never these classes directly. */
-import type { GapProp, PageContainerVariantProp, PageDensityProp } from "../props/vocabulary/index.js";
+import type * as React from "react";
+import type { GapNameProp, GapProp, PadProp, PadRawProp, PageContainerVariantProp, PageDensityProp } from "../props/vocabulary/index.js";
 export type Density = PageDensityProp;
 export type StackGap = GapProp;
 export type FlexGap = GapProp;
-export type InlineGap = Exclude<GapProp, "xl" | "none">;
+export type InlineGap = Exclude<GapNameProp, "xl" | "none">;
 export type PageContainerVariant = PageContainerVariantProp;
 export declare const densityClass: Record<PageDensityProp, string>;
 export declare const pageContainerVariantClass: Record<PageContainerVariantProp, string | undefined>;
-export declare const stackGapClass: Record<Exclude<GapProp, "none">, string>;
+export declare const stackGapClass: Record<Exclude<GapNameProp, "none">, string>;
 export declare const inlineGapClass: Record<InlineGap, string>;
 export declare const flexGapClass: Record<GapProp, string>;
+/**
+ * Bậc thang → giá trị CSS cho đệm.
+ *
+ * Bậc TÊN ánh xạ vào thang dọc (`--space-stack-*`) chứ không theo trục như
+ * `gap`: đệm bao quanh một khối, nó không có "trục viết" để chặt hơn. Bậc SỐ
+ * đi thẳng vào `--space-{n}` của thang gốc, giống hệt `gap={n}`.
+ */
+export declare function padStepToken(step: GapProp): string;
+/**
+ * `pad` / `padRaw` → style đệm theo tên cạnh LOGIC.
+ *
+ * Trả về `undefined` khi không có gì để đặt, để `Flex` không phát một thuộc
+ * tính `style` rỗng (và phép so với bản Radix không lệch vì một chuỗi thừa).
+ *
+ * `padRaw` thắng `pad` ở TỪNG CẠNH, không phải cả cụm: một thiết kế có thể cần
+ * `blockStart` đúng 10px trong khi ba cạnh còn lại vẫn theo thang.
+ */
+export declare function padStyle(pad: PadProp | undefined, padRaw: PadRawProp | undefined): React.CSSProperties | undefined;

package/dist/lib/variants.js

@@ -28,12 +28,67 @@ const flexGapClass = {
   sm: "ui-flex-gap-sm",
   md: "ui-flex-gap-md",
   lg: "ui-flex-gap-lg",
-  xl: "ui-flex-gap-xl"
+  xl: "ui-flex-gap-xl",
+  // Bậc SỐ: thang gốc `--space-{n}`, không theo trục. Xem GapStepProp.
+  0: "ui-flex-gap-none",
+  1: "ui-flex-gap-1",
+  2: "ui-flex-gap-2",
+  3: "ui-flex-gap-3",
+  4: "ui-flex-gap-4",
+  5: "ui-flex-gap-5",
+  6: "ui-flex-gap-6",
+  8: "ui-flex-gap-8",
+  10: "ui-flex-gap-10",
+  12: "ui-flex-gap-12"
 };
+function padStepToken(step) {
+  if (step === "none" || step === 0) {
+    return "0";
+  }
+  return typeof step === "number" ? `var(--space-${step})` : `var(--space-stack-${step})`;
+}
+function padStyle(pad, padRaw) {
+  const scalar = (v) => v !== void 0 && (typeof v !== "object" || v === null) ? v : void 0;
+  const sides = (v) => v !== void 0 && typeof v === "object" && v !== null ? v : {};
+  const allStep = scalar(pad);
+  const allRaw = scalar(padRaw);
+  const stepSides = sides(pad);
+  const rawSides = sides(padRaw);
+  const AXES = {
+    inline: ["paddingInlineStart", "paddingInlineEnd"],
+    block: ["paddingBlockStart", "paddingBlockEnd"],
+    inlineStart: ["paddingInlineStart"],
+    inlineEnd: ["paddingInlineEnd"],
+    blockStart: ["paddingBlockStart"],
+    blockEnd: ["paddingBlockEnd"]
+  };
+  const out = {};
+  if (allStep !== void 0) {
+    out.padding = padStepToken(allStep);
+  }
+  if (allRaw !== void 0) {
+    out.padding = `${allRaw}px`;
+  }
+  for (const [key, props] of Object.entries(AXES)) {
+    const step = stepSides[key];
+    if (step !== void 0) {
+      for (const prop of props) out[prop] = padStepToken(step);
+    }
+  }
+  for (const [key, props] of Object.entries(AXES)) {
+    const raw = rawSides[key];
+    if (raw !== void 0) {
+      for (const prop of props) out[prop] = `${raw}px`;
+    }
+  }
+  return Object.keys(out).length > 0 ? out : void 0;
+}
 export {
   densityClass,
   flexGapClass,
   inlineGapClass,
+  padStepToken,
+  padStyle,
   pageContainerVariantClass,
   stackGapClass
 };

package/dist/props/components/app.prop.d.ts

@@ -3,7 +3,7 @@ import type { Locale } from "date-fns";
 import type { DayPickerProps } from "react-day-picker";
 import type { AppLocale, AppRequestHeaders, AppTimeFormat, AppTimezone, AppTimezoneDefault, AppDateFormat } from "../../app/types.js";
 import type { AppBrand, AppDensity, AppFontSize, AppTheme } from "../../app/theme-axes.js";
-import type { AppSettingPickerAppearanceProp, ChildrenProp, ClassNameProp, DisabledProp, IdProp, NameProp, OnValueChangeProp, ValueProp } from "../vocabulary/index.js";
+import type { AppSettingPickerAppearanceProp, AppSettingToggleAppearanceProp, ChildrenProp, ClassNameProp, DisabledProp, IdProp, NameProp, OnValueChangeProp, ValueProp } from "../vocabulary/index.js";
 /** @see AppProvider */
 export type AppProviderProp = {
     children: ChildrenProp;
@@ -93,6 +93,30 @@ export type AppSettingPickerProp = {
     value?: ValueProp<string>;
     onValueChange?: OnValueChangeProp<string>;
 };
+/**
+ * The {@link AppSettingToggle} subset of {@link AppSettingKind} — the settings whose value set is
+ * CLOSED and short enough to cycle by tapping. `locale`, `timezone`, `dateFormat` and `brand` are
+ * deliberately absent: a 400-entry IANA list (or a palette a service extends) is a menu, not a
+ * cycle, and tapping through it is not a control anyone can use.
+ */
+export type AppSettingToggleKind = Extract<AppSettingKind, "theme" | "density" | "fontSize" | "timeFormat">;
+/**
+ * @see AppSettingToggle — one BUTTON that steps a single AppProvider setting to its next value and
+ * shows that value as its glyph. The no-menu counterpart to {@link AppSettingPickerProp}: same
+ * binding contract (context-bound by default, controlled via value + onValueChange), same option
+ * order, one tap instead of open-then-choose.
+ */
+export type AppSettingToggleProp = {
+    kind: AppSettingToggleKind;
+    /** Box the button takes. Default: `"bar"` — a toggle exists for a top bar. */
+    appearance?: AppSettingToggleAppearanceProp;
+    className?: ClassNameProp;
+    disabled?: DisabledProp;
+    id?: IdProp;
+    /** Controlled value; default reads/writes the matching AppProvider context. */
+    value?: ValueProp<string>;
+    onValueChange?: OnValueChangeProp<string>;
+};
 /** Value exposed by `useAppContext`. */
 export type AppContextValue = {
     locale: AppLocale;

package/dist/props/components/charts.prop.d.ts

@@ -22,6 +22,13 @@ type ChartCartesianBase = {
     categoryKey: string;
     /** Accessible name + visible caption for the chart. REQUIRED (role="img" needs a name). */
     label: LabelProp;
+    /**
+     * Paint `label` as a visible caption above the plot. Set `false` when the chart already sits
+     * under a heading that says the same thing (a `CardTitle`, a section `<h2>`): the caption stays
+     * in the DOM as `sr-only`, so `role="img"` keeps its accessible name and only the duplicated
+     * visible title goes away.
+     */
+    showCaption?: boolean;
     /** Extra context appended to the screen-reader description. */
     description?: DescriptionProp;
     /** Canvas height preset — `xs|sm|md|lg`. Ignored when `height` is set. */
@@ -67,6 +74,13 @@ export type CompactBarTrendProp = {
     valueKey: string;
     /** Accessible name + visible caption for the chart. REQUIRED (role="img" needs a name). */
     label: LabelProp;
+    /**
+     * Paint `label` as a visible caption above the plot. Set `false` when the chart already sits
+     * under a heading that says the same thing (a `CardTitle`, a section `<h2>`): the caption stays
+     * in the DOM as `sr-only`, so `role="img"` keeps its accessible name and only the duplicated
+     * visible title goes away.
+     */
+    showCaption?: boolean;
     /** Extra context appended to the screen-reader description. */
     description?: DescriptionProp;
     /** Plot-height tier — `xs|sm|md|lg`. Defaults to `xs` (dashboard summary-card density). */
@@ -107,6 +121,13 @@ export type PieChartProp = {
     colors?: string[];
     /** Accessible name + visible caption for the chart. REQUIRED. */
     label: LabelProp;
+    /**
+     * Paint `label` as a visible caption above the plot. Set `false` when the chart already sits
+     * under a heading that says the same thing (a `CardTitle`, a section `<h2>`): the caption stays
+     * in the DOM as `sr-only`, so `role="img"` keeps its accessible name and only the duplicated
+     * visible title goes away.
+     */
+    showCaption?: boolean;
     /** Extra context appended to the screen-reader description. */
     description?: DescriptionProp;
     /** Canvas height preset — `xs|sm|md|lg`. Ignored when `height` is set. */