@godxjp/ui 19.5.0 → 20.0.0

package/dist/components/ui/toggle-group.d.ts

@@ -1,19 +1,64 @@
 import * as React from "react";
-import * as ToggleGroupPrimitive from "@radix-ui/react-toggle-group";
 import { type ToggleCountFields, type ToggleProp } from "./toggle.js";
 type ToggleGroupVariant = ToggleProp["variant"];
 type ToggleGroupSize = ToggleProp["size"];
-export declare const ToggleGroup: React.ForwardRefExoticComponent<((Omit<ToggleGroupPrimitive.ToggleGroupMultipleProps & React.RefAttributes<HTMLDivElement>, "ref"> | Omit<ToggleGroupPrimitive.ToggleGroupSingleProps & React.RefAttributes<HTMLDivElement>, "ref">) & {
+type ToggleGroupBaseProp = Omit<React.ComponentPropsWithoutRef<"div">, "defaultValue" | "dir"> & {
     variant?: ToggleGroupVariant;
     size?: ToggleGroupSize;
-}) & React.RefAttributes<HTMLDivElement>>;
+    /** Disable every item at once — RAC `isDisabled`. */
+    disabled?: boolean;
+    /** Which way the arrow keys walk the group. */
+    orientation?: "horizontal" | "vertical";
+    /**
+     * Writing direction. It still lands on the DOM node, but React Aria reads the direction it
+     * navigates by from the ambient locale (`I18nProvider`), NOT from this attribute — where Radix
+     * read this prop directly. An RTL app must set the locale, not just `dir`.
+     */
+    dir?: "ltr" | "rtl";
+    /**
+     * Accepted for source compatibility with the Radix era, where it wrapped arrow-key focus around
+     * the ends. React Aria's toolbar navigation stops at the ends and has no equivalent switch, so
+     * this prop no longer changes anything.
+     */
+    loop?: boolean;
+};
+/**
+ * `type` is the discriminant, exactly as it was under Radix: `"single"` reports the one selected
+ * value as a string (`""` once it is deselected), `"multiple"` reports an array. React Aria models
+ * both as `selectionMode` + a `Set` of keys — that Set is built and unpacked here so the public
+ * shape stays a string / an array of strings.
+ */
+type ToggleGroupSingleProp = ToggleGroupBaseProp & {
+    type: "single";
+    value?: string;
+    defaultValue?: string;
+    onValueChange?: (value: string) => void;
+};
+type ToggleGroupMultipleProp = ToggleGroupBaseProp & {
+    type: "multiple";
+    value?: string[];
+    defaultValue?: string[];
+    onValueChange?: (value: string[]) => void;
+};
+type ToggleGroupProp = ToggleGroupSingleProp | ToggleGroupMultipleProp;
+export declare const ToggleGroup: React.ForwardRefExoticComponent<ToggleGroupProp & React.RefAttributes<HTMLDivElement>>;
 /** Same vocabulary as `Toggle` and `Button` — one counter pill for the whole library. */
-export type ToggleGroupItemProp = React.ComponentPropsWithoutRef<typeof ToggleGroupPrimitive.Item> & ToggleCountFields & {
+export type ToggleGroupItemProp = Omit<React.ComponentPropsWithoutRef<"button">, "value"> & ToggleCountFields & {
+    /**
+     * This item's key in the group's value. React Aria calls it `id` (the key it stores in
+     * `selectedKeys`); the public spelling stays `value`, as it was under Radix.
+     */
+    value: string;
     variant?: ToggleGroupVariant;
     size?: ToggleGroupSize;
 };
 export type ToggleGroupItemProps = ToggleGroupItemProp;
-export declare const ToggleGroupItem: React.ForwardRefExoticComponent<Omit<ToggleGroupPrimitive.ToggleGroupItemProps & React.RefAttributes<HTMLButtonElement>, "ref"> & ToggleCountFields & {
+export declare const ToggleGroupItem: React.ForwardRefExoticComponent<Omit<Omit<React.DetailedHTMLProps<React.ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, "ref">, "value"> & ToggleCountFields & {
+    /**
+     * This item's key in the group's value. React Aria calls it `id` (the key it stores in
+     * `selectedKeys`); the public spelling stays `value`, as it was under Radix.
+     */
+    value: string;
     variant?: ToggleGroupVariant;
     size?: ToggleGroupSize;
 } & React.RefAttributes<HTMLButtonElement>>;

package/dist/components/ui/toggle-group.js

@@ -1,26 +1,77 @@
 "use client";
 import { jsx, jsxs } from "react/jsx-runtime";
 import * as React from "react";
-import * as ToggleGroupPrimitive from "@radix-ui/react-toggle-group";
+import {
+  ToggleButton,
+  ToggleButtonGroup,
+  ToggleGroupStateContext
+} from "react-aria-components";
 import { cn } from "../../lib/utils.js";
-import { toggleVariants, useCounterPill } from "./toggle.js";
+import {
+  restoreDomProps,
+  toggleVariants,
+  useCounterPill
+} from "./toggle.js";
 const ToggleGroupContext = React.createContext({});
-const ToggleGroup = React.forwardRef(({ className, variant, size, children, ...props }, ref) => {
-  const context = React.useMemo(() => ({ variant, size }), [variant, size]);
-  return /* @__PURE__ */ jsx(
-    ToggleGroupPrimitive.Root,
-    {
-      ref,
-      "data-slot": "toggle-group",
-      "data-variant": variant,
-      "data-size": size,
-      className: cn("ui-toggle-group", className),
-      ...props,
-      children: /* @__PURE__ */ jsx(ToggleGroupContext.Provider, { value: context, children })
-    }
-  );
-});
-ToggleGroup.displayName = ToggleGroupPrimitive.Root.displayName;
+function toSelectedKeys(value) {
+  if (value == null) {
+    return void 0;
+  }
+  if (Array.isArray(value)) {
+    return new Set(value);
+  }
+  return new Set(value === "" ? [] : [value]);
+}
+const ToggleGroup = React.forwardRef(
+  // No destructuring defaults: an unset prop must stay `undefined` so the emitted attribute is
+  // either absent or a declared union member.
+  // is NOT in the `sm | md | lg` size union — the group advertised an invalid value for its own
+  // type.) The real default lives in `toggleVariants`, applied per item.
+  ({
+    className,
+    variant,
+    size,
+    children,
+    type,
+    value,
+    defaultValue,
+    onValueChange,
+    disabled,
+    loop: _loop,
+    ...props
+  }, ref) => {
+    const context = React.useMemo(() => ({ variant, size }), [variant, size]);
+    const selectedKeys = React.useMemo(() => toSelectedKeys(value), [value]);
+    const defaultSelectedKeys = React.useMemo(() => toSelectedKeys(defaultValue), [defaultValue]);
+    const handleSelectionChange = (keys) => {
+      const next = [...keys].map(String);
+      if (type === "single") {
+        onValueChange?.(next[0] ?? "");
+      } else {
+        onValueChange?.(next);
+      }
+    };
+    return /* @__PURE__ */ jsx(
+      ToggleButtonGroup,
+      {
+        ref,
+        "data-slot": "toggle-group",
+        "data-variant": variant,
+        "data-size": size,
+        className: cn("ui-toggle-group", className),
+        ...props,
+        selectionMode: type,
+        selectedKeys,
+        defaultSelectedKeys,
+        onSelectionChange: handleSelectionChange,
+        isDisabled: disabled,
+        render: (domProps) => /* @__PURE__ */ jsx("div", { ...props, ...domProps, tabIndex: props.tabIndex ?? domProps.tabIndex }),
+        children: /* @__PURE__ */ jsx(ToggleGroupContext.Provider, { value: context, children })
+      }
+    );
+  }
+);
+ToggleGroup.displayName = "ToggleGroup";
 const ToggleGroupItem = React.forwardRef(
   ({
     className,
@@ -32,6 +83,8 @@ const ToggleGroupItem = React.forwardRef(
     countLabel,
     children,
     "aria-label": ariaLabel,
+    value,
+    disabled,
     ...props
   }, ref) => {
     const context = React.useContext(ToggleGroupContext);
@@ -44,16 +97,22 @@ const ToggleGroupItem = React.forwardRef(
       countLabel,
       ariaLabel
     });
+    const groupState = React.useContext(ToggleGroupStateContext);
+    const isPressed = groupState?.selectedKeys.has(value) ?? false;
     return /* @__PURE__ */ jsxs(
-      ToggleGroupPrimitive.Item,
+      ToggleButton,
       {
         ref,
         "data-slot": "toggle-group-item",
+        "data-state": isPressed ? "on" : "off",
         "data-variant": resolvedVariant,
         "data-size": resolvedSize,
         "aria-label": resolvedAriaLabel,
         className: cn(toggleVariants({ variant: resolvedVariant, size: resolvedSize }), className),
         ...props,
+        id: value,
+        isDisabled: disabled,
+        render: (domProps) => restoreDomProps(props, domProps),
         children: [
           children,
           pill
@@ -62,7 +121,7 @@ const ToggleGroupItem = React.forwardRef(
     );
   }
 );
-ToggleGroupItem.displayName = ToggleGroupPrimitive.Item.displayName;
+ToggleGroupItem.displayName = "ToggleGroupItem";
 export {
   ToggleGroup,
   ToggleGroupItem

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

@@ -1,5 +1,4 @@
 import * as React from "react";
-import * as TogglePrimitive from "@radix-ui/react-toggle";
 import { type VariantProps } from "class-variance-authority";
 declare const toggleVariants: (props?: ({
     variant?: "default" | "outline" | null | undefined;
@@ -29,6 +28,19 @@ type ToggleCountFields = {
      */
     countLabel?: string;
 };
+/**
+ * The repo's two-state vocabulary, kept VERBATIM from the Radix era. React Aria spells the same
+ * four things `isSelected` / `defaultSelected` / `onChange` / `isDisabled`; the translation lives
+ * inside this file so no consumer ever has to learn RAC's names.
+ */
+type TogglePressedFields = {
+    /** Controlled pressed state — RAC `isSelected`. */
+    pressed?: boolean;
+    /** Uncontrolled initial pressed state — RAC `defaultSelected`. */
+    defaultPressed?: boolean;
+    /** Fired with the NEW pressed state — RAC `onChange`. */
+    onPressedChange?: (pressed: boolean) => void;
+};
 /** Counter pill shared by `Toggle` and `ToggleGroupItem`. ACCESSIBLE NAME. */
 declare function useCounterPill({ count, overflowCount, showZero, countLabel, ariaLabel, }: ToggleCountFields & {
     ariaLabel?: string;
@@ -39,11 +51,25 @@ declare function useCounterPill({ count, overflowCount, showZero, countLabel, ar
     pill: React.JSX.Element;
     resolvedAriaLabel: string | undefined;
 };
-export type ToggleProp = React.ComponentPropsWithoutRef<typeof TogglePrimitive.Root> & VariantProps<typeof toggleVariants> & ToggleCountFields;
+/**
+ * RAC's `filterDOMProps` forwards only `id`, `data-*`, the four labelling `aria-*` and the global
+ * mouse/pointer events; `title`, `tabIndex` and the rarer DOM props are dropped silently, and
+ * Radix forwarded ALL of them. `render` is RAC's own escape hatch: the raw props go on first, RAC's
+ * merged ones second so its `type`/`disabled`/`aria-pressed`/handlers always win.
+ *
+ * Two exceptions, both of which Radix owned: `tabIndex` stays the caller's, and so does `id` —
+ * inside a ToggleButtonGroup RAC spends `id` as the selection KEY and blanks the DOM attribute,
+ * which would otherwise silently drop the id off every grouped item.
+ */
+declare function restoreDomProps<P extends {
+    id?: string;
+    tabIndex?: number;
+}>(raw: P, domProps: React.JSX.IntrinsicElements["button"]): React.JSX.Element;
+export type ToggleProp = React.ComponentPropsWithoutRef<"button"> & TogglePressedFields & VariantProps<typeof toggleVariants> & ToggleCountFields;
 export type ToggleProps = ToggleProp;
-export declare const Toggle: React.ForwardRefExoticComponent<Omit<TogglePrimitive.ToggleProps & React.RefAttributes<HTMLButtonElement>, "ref"> & VariantProps<(props?: ({
+export declare const Toggle: React.ForwardRefExoticComponent<Omit<React.DetailedHTMLProps<React.ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, "ref"> & TogglePressedFields & VariantProps<(props?: ({
     variant?: "default" | "outline" | null | undefined;
     size?: "lg" | "md" | "sm" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string> & ToggleCountFields & React.RefAttributes<HTMLButtonElement>>;
-export { toggleVariants, useCounterPill };
-export type { ToggleCountFields };
+export { toggleVariants, useCounterPill, restoreDomProps };
+export type { ToggleCountFields, TogglePressedFields };

package/dist/components/ui/toggle.js

@@ -1,7 +1,7 @@
 "use client";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import * as React from "react";
-import * as TogglePrimitive from "@radix-ui/react-toggle";
+import { ToggleButton } from "react-aria-components";
 import { cva } from "class-variance-authority";
 import { cn } from "../../lib/utils.js";
 import { useTranslation } from "../../i18n/use-translation.js";
@@ -48,6 +48,30 @@ function useCounterPill({
     resolvedAriaLabel: ariaLabel == null ? ariaLabel : `${ariaLabel}, ${spoken}`
   };
 }
+function usePressedState({ pressed, defaultPressed, onPressedChange }) {
+  const [uncontrolled, setUncontrolled] = React.useState(defaultPressed ?? false);
+  const isPressed = pressed ?? uncontrolled;
+  return {
+    isPressed,
+    onSelectionChange: (next) => {
+      if (pressed == null) {
+        setUncontrolled(next);
+      }
+      onPressedChange?.(next);
+    }
+  };
+}
+function restoreDomProps(raw, domProps) {
+  return /* @__PURE__ */ jsx(
+    "button",
+    {
+      ...raw,
+      ...domProps,
+      id: raw.id ?? domProps.id,
+      tabIndex: raw.tabIndex ?? domProps.tabIndex
+    }
+  );
+}
 const Toggle = React.forwardRef(
   ({
     className,
@@ -59,6 +83,10 @@ const Toggle = React.forwardRef(
     countLabel,
     children,
     "aria-label": ariaLabel,
+    pressed,
+    defaultPressed,
+    onPressedChange,
+    disabled,
     ...props
   }, ref) => {
     const { pill, resolvedAriaLabel } = useCounterPill({
@@ -68,14 +96,24 @@ const Toggle = React.forwardRef(
       countLabel,
       ariaLabel
     });
+    const { isPressed, onSelectionChange } = usePressedState({
+      pressed,
+      defaultPressed,
+      onPressedChange
+    });
     return /* @__PURE__ */ jsxs(
-      TogglePrimitive.Root,
+      ToggleButton,
       {
         ref,
         "data-slot": "toggle",
+        "data-state": isPressed ? "on" : "off",
         "aria-label": resolvedAriaLabel,
         className: cn(toggleVariants({ variant, size }), className),
         ...props,
+        isSelected: isPressed,
+        onChange: onSelectionChange,
+        isDisabled: disabled,
+        render: (domProps) => restoreDomProps(props, domProps),
         children: [
           children,
           pill
@@ -84,9 +122,10 @@ const Toggle = React.forwardRef(
     );
   }
 );
-Toggle.displayName = TogglePrimitive.Root.displayName;
+Toggle.displayName = "Toggle";
 export {
   Toggle,
+  restoreDomProps,
   toggleVariants,
   useCounterPill
 };

package/dist/i18n/messages/en.json

@@ -157,6 +157,7 @@
     },
     "appShell": {
       "sidebarLabel": "Sidebar",
+      "navRailLabel": "Workspaces",
       "headerLabel": "Header",
       "mainLabel": "Main content",
       "footerLabel": "Footer",
@@ -252,6 +253,10 @@
       "denied": "You do not have permission to view this matrix",
       "deniedDescription": "Ask an administrator to grant you access.",
       "loading": "Loading permissions…"
+    },
+    "progress": {
+      "ariaLabel": "Progress",
+      "breakdownSeparator": ", "
     }
   },
   "ui": {
@@ -359,6 +364,9 @@
       "logistics": "Logistics Teal",
       "partner": "Partner Orange",
       "slate": "HQ Slate"
+    },
+    "settingToggle": {
+      "label": "{setting}: {value}"
     }
   },
   "locale": {

package/dist/i18n/messages/ja.json

@@ -154,6 +154,7 @@
     },
     "appShell": {
       "sidebarLabel": "サイドバー",
+      "navRailLabel": "ワークスペース",
       "headerLabel": "ヘッダー",
       "mainLabel": "メインコンテンツ",
       "footerLabel": "フッター",
@@ -246,6 +247,10 @@
       "denied": "このマトリクスを表示する権限がありません",
       "deniedDescription": "閲覧するには管理者に権限の付与を依頼してください。",
       "loading": "権限を読み込み中…"
+    },
+    "progress": {
+      "ariaLabel": "進捗",
+      "breakdownSeparator": "、"
     }
   },
   "ui": {
@@ -347,6 +352,9 @@
       "logistics": "Logistics Teal",
       "partner": "Partner Orange",
       "slate": "HQ Slate"
+    },
+    "settingToggle": {
+      "label": "{setting}：{value}"
     }
   },
   "locale": {

package/dist/i18n/messages/vi.json

@@ -154,6 +154,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 +247,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": {
@@ -347,6 +352,9 @@
       "logistics": "Logistics Teal",
       "partner": "Partner Orange",
       "slate": "HQ Slate"
+    },
+    "settingToggle": {
+      "label": "{setting}: {value}"
     }
   },
   "locale": {

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

@@ -12,7 +12,7 @@ export declare const controlMultilineGhostClass = "ui-control-multiline w-full m
  * 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";
+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 [&>[data-slot=select-value]]:line-clamp-1";
 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,7 @@
 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 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 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 [&>[data-slot=select-value]]:line-clamp-1";
 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";

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;