@godxjp/ui 5.0.2 → 6.0.0

package/src/app/types.ts

@@ -0,0 +1,39 @@
+import type { AppTimeFormat } from "./time-formats";
+import type { AppDateFormat } from "./date-formats";
+
+/** Supported UI locales — sent as `x-locale` to backend. */
+export type AppLocale = "vi" | "en" | "ja";
+
+/** IANA timezone identifier — sent as `x-timezone` to backend. */
+export type AppTimezone = string;
+
+/** How to resolve the initial timezone when nothing is stored. */
+export type AppTimezoneDefault = "browser" | "system" | (AppTimezone & {});
+
+export type { AppTimeFormat } from "./time-formats";
+export type { AppDateFormat } from "./date-formats";
+export {
+  APP_TIME_FORMATS,
+  APP_REQUEST_HEADER_TIME_FORMAT,
+  getTimePattern,
+  isAppTimeFormat,
+} from "./time-formats";
+export {
+  APP_DATE_FORMATS,
+  APP_REQUEST_HEADER_DATE_FORMAT,
+  getDatePattern,
+  getDateTimePattern,
+  isAppDateFormat,
+} from "./date-formats";
+
+export const APP_LOCALES = ["vi", "en", "ja"] as const satisfies readonly AppLocale[];
+
+export const APP_REQUEST_HEADER_LOCALE = "x-locale" as const;
+export const APP_REQUEST_HEADER_TIMEZONE = "x-timezone" as const;
+
+export type AppRequestHeaders = {
+  "x-locale": AppLocale;
+  "x-timezone": AppTimezone;
+  "x-time-format": AppTimeFormat;
+  "x-date-format": AppDateFormat;
+};

package/src/app/use-formatting.ts

@@ -0,0 +1,47 @@
+import { useMemo } from "react";
+import { formatDate, type FormatDateOptions } from "../lib/datetime";
+import { useAppContext } from "./app-provider";
+
+/** Date/time formatters bound to the current AppProvider preferences. */
+export function useFormatting() {
+  const { locale, timezone, timeFormat, dateFormat, dateFnsLocale } = useAppContext();
+
+  const defaults = useMemo(
+    () => ({ locale: dateFnsLocale, timezone, timeFormat, dateFormat }),
+    [dateFnsLocale, timezone, timeFormat, dateFormat],
+  );
+
+  const bind = useMemo(
+    () => (value: Parameters<typeof formatDate>[0], options?: FormatDateOptions) =>
+      formatDate(value, { ...defaults, ...options }),
+    [defaults],
+  );
+
+  return useMemo(
+    () => ({
+      locale,
+      timezone,
+      timeFormat,
+      dateFormat,
+      /** Primary formatter — auto-detect + AppProvider defaults. */
+      format: bind,
+      formatDate: bind,
+      formatCalendarDate: (value: Date | null | undefined, options?: FormatDateOptions) =>
+        formatDate(value, { ...defaults, ...options, kind: "calendar" }),
+      formatTime: (value: Parameters<typeof formatDate>[0], options?: FormatDateOptions) =>
+        formatDate(value, { ...defaults, ...options, kind: "time" }),
+      formatDateTime: (value: Parameters<typeof formatDate>[0], options?: FormatDateOptions) =>
+        formatDate(value, { ...defaults, ...options, kind: "datetime" }),
+      formatDateLong: (value: Parameters<typeof formatDate>[0], options?: FormatDateOptions) =>
+        formatDate(value, { ...defaults, ...options, kind: "long" }),
+      formatRelative: (value: Parameters<typeof formatDate>[0], options?: FormatDateOptions) =>
+        formatDate(value, { ...defaults, ...options, kind: "relative" }),
+      formatTimeOfDay: (value: Parameters<typeof formatDate>[0], options?: FormatDateOptions) =>
+        formatDate(value, { ...defaults, ...options, kind: "time" }),
+    }),
+    [locale, timezone, timeFormat, dateFormat, defaults, bind],
+  );
+}
+
+/** Alias for useFormatting — emphasises timezone-aware datetime helpers. */
+export const useDateTime = useFormatting;

package/src/components/__tests__/accessibility-primitives.test.tsx

@@ -0,0 +1,65 @@
+import { describe, expect, it } from "vitest";
+import { renderWithUi, screen } from "@/test/render";
+import { Checkbox } from "../data-entry/checkbox";
+import { Command, CommandInput } from "../data-entry/command";
+import { Radio } from "../data-entry/radio";
+import { Select, SelectTrigger, SelectValue } from "../data-entry/select";
+import { Dialog, DialogContent, DialogDescription, DialogTitle } from "../feedback/dialog";
+import { Sheet, SheetContent, SheetDescription, SheetTitle } from "../feedback/sheet";
+
+function expectDecorativeIconsHidden(container: HTMLElement) {
+  container.querySelectorAll("svg").forEach((icon) => {
+    expect(icon).toHaveAttribute("aria-hidden", "true");
+  });
+}
+
+describe("primitive accessibility", () => {
+  it("hides decorative icons from accessibility tree", () => {
+    const { baseElement } = renderWithUi(
+      <>
+        <Select>
+          <SelectTrigger aria-label="Hub">
+            <SelectValue placeholder="Hub" />
+          </SelectTrigger>
+        </Select>
+        <Checkbox defaultChecked aria-label="Accept" />
+        <Radio.Root defaultValue="air">
+          <Radio.Item value="air" aria-label="Air" />
+        </Radio.Root>
+        <Command>
+          <CommandInput aria-label="Search" />
+        </Command>
+      </>,
+    );
+
+    expectDecorativeIconsHidden(baseElement);
+  });
+
+  it("keeps dialog close button named while hiding close icon", () => {
+    const { baseElement } = renderWithUi(
+      <Dialog open onOpenChange={() => undefined}>
+        <DialogContent>
+          <DialogTitle>Dialog title</DialogTitle>
+          <DialogDescription>Dialog description</DialogDescription>
+        </DialogContent>
+      </Dialog>,
+    );
+
+    expect(screen.getByRole("button", { name: "Close" })).toBeInTheDocument();
+    expectDecorativeIconsHidden(baseElement);
+  });
+
+  it("keeps sheet close button named while hiding close icon", () => {
+    const { baseElement } = renderWithUi(
+      <Sheet open onOpenChange={() => undefined}>
+        <SheetContent>
+          <SheetTitle>Sheet title</SheetTitle>
+          <SheetDescription>Sheet description</SheetDescription>
+        </SheetContent>
+      </Sheet>,
+    );
+
+    expect(screen.getByRole("button", { name: "Close" })).toBeInTheDocument();
+    expectDecorativeIconsHidden(baseElement);
+  });
+});

package/src/components/__tests__/docs-parity.test.ts

@@ -0,0 +1,41 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+
+const root = process.cwd();
+
+function read(path: string) {
+  return readFileSync(join(root, path), "utf8");
+}
+
+describe("docs and story parity", () => {
+  it("documents shadcn-compatible compound exports", () => {
+    expect(read("docs/primitives/data-entry/select/index.md")).toContain("SelectLabel");
+    expect(read("docs/primitives/data-entry/select/index.md")).toContain("SelectSeparator");
+
+    const dropdownDocs = read("docs/primitives/navigation/dropdown-menu/index.md");
+    expect(dropdownDocs).toContain("DropdownMenuCheckboxItem");
+    expect(dropdownDocs).toContain("DropdownMenuRadioItem");
+    expect(dropdownDocs).toContain("DropdownMenuShortcut");
+
+    const popoverDocs = read("docs/primitives/data-display/popover/index.md");
+    expect(popoverDocs).toContain("PopoverHeader");
+    expect(popoverDocs).toContain("PopoverTitle");
+    expect(popoverDocs).toContain("PopoverDescription");
+
+    expect(read("docs/primitives/feedback/sheet/index.md")).toContain("SheetFooter");
+    expect(read("docs/primitives/navigation/tabs/index.md")).toContain("variant");
+  });
+
+  it("has preview examples for new shadcn parity surfaces", () => {
+    expect(
+      read("docs/primitives/navigation/dropdown-menu/examples/checked-radio-items.tsx"),
+    ).toContain("DropdownMenuCheckboxItem");
+    expect(read("docs/primitives/navigation/tabs/examples/line-variant.tsx")).toContain(
+      'variant="line"',
+    );
+    expect(read("docs/primitives/data-display/popover/examples/shipment-summary.tsx")).toContain(
+      "PopoverHeader",
+    );
+  });
+});

package/src/components/__tests__/shadcn-release-guardrails.test.ts

@@ -0,0 +1,71 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+
+const root = process.cwd();
+
+function readJson<T>(path: string): T {
+  return JSON.parse(readFileSync(join(root, path), "utf8")) as T;
+}
+
+describe("shadcn release guardrails", () => {
+  it("keeps components.json aligned to the package UI bridge", () => {
+    const config = readJson<{
+      aliases?: Record<string, string>;
+      tailwind?: { css?: string; cssVariables?: boolean };
+      iconLibrary?: string;
+    }>("components.json");
+
+    expect(config.aliases?.ui).toBe("@/components/ui");
+    expect(config.aliases?.utils).toBe("@/lib/utils");
+    expect(config.tailwind?.css).toBe("src/styles/index.css");
+    expect(config.tailwind?.cssVariables).toBe(true);
+    expect(config.iconLibrary).toBe("lucide");
+  });
+
+  it("exports shadcn-compatible entrypoints from package.json", () => {
+    const pkg = readJson<{ exports?: Record<string, string>; scripts?: Record<string, string> }>(
+      "package.json",
+    );
+    const exports = pkg.exports ?? {};
+
+    expect(exports["./ui"]).toBe("./src/components/ui/index.tsx");
+    for (const key of [
+      "button",
+      "select",
+      "checkbox",
+      "radio",
+      "switch",
+      "slider",
+      "dialog",
+      "sheet",
+      "popover",
+      "dropdown-menu",
+      "tabs",
+      "command",
+    ]) {
+      expect(exports[`./ui/${key}`], `missing ./ui/${key}`).toBeDefined();
+    }
+    expect(pkg.scripts?.["verify:release"]).toContain("preview:build");
+  });
+
+  it("keeps bridge files present for installed shadcn components", () => {
+    for (const file of [
+      "button",
+      "select",
+      "checkbox",
+      "radio",
+      "switch",
+      "slider",
+      "dialog",
+      "sheet",
+      "popover",
+      "dropdown-menu",
+      "tabs",
+      "command",
+      "index",
+    ]) {
+      expect(existsSync(join(root, `src/components/ui/${file}.tsx`)), `${file}.tsx`).toBe(true);
+    }
+  });
+});

package/src/components/__tests__/theme-axes-integration.test.tsx

@@ -0,0 +1,242 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import { screen } from "@testing-library/react";
+import { Button } from "../general/button";
+import { Input } from "../data-entry/input";
+import { Textarea } from "../data-entry/textarea";
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "../data-entry/select";
+import { Checkbox } from "../data-entry/checkbox";
+import { Switch } from "../data-entry/switch";
+import { Badge } from "../data-display/badge";
+import { StatusBadge } from "../data-display/status-badge";
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from "../data-display/table";
+import { Pagination } from "../navigation/pagination";
+import { Calendar } from "../data-entry/calendar";
+import { renderWithTheme } from "@/test/theme-test-utils";
+import {
+  controlMultilineClass,
+  tableRowHeightClass,
+  toneInfoClass,
+  toneSuccessClass,
+  toneWarningClass,
+} from "@/lib/control-styles";
+
+const componentsDir = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+function readComponent(relative: string): string {
+  return readFileSync(join(componentsDir, relative), "utf8");
+}
+
+function statusBadgeRoot(label: string): HTMLElement {
+  const text = screen.getByText(label);
+  const root = text.parentElement;
+  expect(root).toBeTruthy();
+  return root!;
+}
+
+describe("theme axes integration (render + class contracts)", () => {
+  describe("density — ui-control on interactive primitives", () => {
+    it("Button default size uses semantic button size class", () => {
+      renderWithTheme(<Button>Save</Button>);
+      expect(screen.getByRole("button", { name: "Save" })).toHaveClass("ui-button--default-size");
+    });
+
+    it("Input uses ui-control", () => {
+      renderWithTheme(<Input aria-label="HAWB" />);
+      expect(screen.getByRole("textbox", { name: "HAWB" })).toHaveClass("ui-control");
+    });
+
+    it("Textarea uses ui-control-multiline", () => {
+      renderWithTheme(<Textarea aria-label="Notes" />);
+      expect(screen.getByRole("textbox", { name: "Notes" })).toHaveClass("ui-control-multiline");
+      expect(controlMultilineClass.split(" ")[0]).toBe("ui-control-multiline");
+    });
+
+    it("SelectTrigger uses ui-control flex layout", () => {
+      renderWithTheme(
+        <Select defaultValue="a">
+          <SelectTrigger aria-label="Hub">
+            <SelectValue />
+          </SelectTrigger>
+          <SelectContent>
+            <SelectItem value="a">A</SelectItem>
+          </SelectContent>
+        </Select>,
+      );
+      const trigger = screen.getByRole("combobox", { name: "Hub" });
+      expect(trigger).toHaveClass("ui-control");
+      expect(trigger.className).toContain("flex");
+    });
+
+    it.each(["compact", "default", "comfortable"] as const)(
+      "renders Input under ui-density-%s",
+      (density) => {
+        renderWithTheme(<Input aria-label={`field-${density}`} />, { density });
+        expect(screen.getByRole("textbox", { name: `field-${density}` })).toHaveClass("ui-control");
+      },
+    );
+  });
+
+  describe("semantic badges — token tone classes (no raw palette)", () => {
+    it("Badge success variant uses success token", () => {
+      renderWithTheme(<Badge variant="success">Cleared</Badge>);
+      const el = screen.getByText("Cleared");
+      expect(el.className).toContain("success");
+      expect(el.className).not.toMatch(/green-/);
+    });
+
+    it("StatusBadge pending uses warning token", () => {
+      renderWithTheme(<StatusBadge status="pending" />);
+      const el = statusBadgeRoot("Chờ xử lý");
+      expect(el.className).toContain("warning");
+      expect(el.className).not.toMatch(/amber-/);
+    });
+
+    it("StatusBadge scheduled uses info token", () => {
+      renderWithTheme(<StatusBadge status="scheduled" />);
+      const el = statusBadgeRoot("Đã lên lịch");
+      expect(el.className).toContain("info");
+      expect(el.className).not.toMatch(/blue-/);
+    });
+
+    it("StatusBadge active uses success token", () => {
+      renderWithTheme(<StatusBadge status="active" />);
+      const el = statusBadgeRoot("Đang hoạt động");
+      expect(el.className).toContain("success");
+    });
+
+    it("tone class constants match expected token names", () => {
+      expect(toneSuccessClass).toContain("success");
+      expect(toneWarningClass).toContain("warning");
+      expect(toneInfoClass).toContain("info");
+    });
+  });
+
+  describe("table density tokens", () => {
+    it("TableHead references --table-row-height", () => {
+      renderWithTheme(
+        <Table>
+          <TableHeader>
+            <TableRow>
+              <TableHead>HAWB</TableHead>
+            </TableRow>
+          </TableHeader>
+          <TableBody>
+            <TableRow className={tableRowHeightClass}>
+              <TableCell>GX-1</TableCell>
+            </TableRow>
+          </TableBody>
+        </Table>,
+      );
+      expect(screen.getByRole("columnheader", { name: "HAWB" }).className).toContain(
+        "var(--table-row-height)",
+      );
+    });
+  });
+
+  describe("primary brand — checkbox/switch", () => {
+    it("Checkbox uses centralized semantic class", () => {
+      renderWithTheme(<Checkbox defaultChecked aria-label="ok" />);
+      expect(screen.getByRole("checkbox", { name: "ok" })).toHaveClass("ui-checkbox");
+    });
+
+    it("Switch uses centralized semantic class", () => {
+      renderWithTheme(<Switch defaultChecked aria-label="notify" />);
+      expect(screen.getByRole("switch", { name: "notify" })).toHaveClass("ui-switch");
+    });
+  });
+
+  describe("Preview-equivalent theme globals on wrapper", () => {
+    it("fontSize sm sets --font-size-sm on root", () => {
+      const { container } = renderWithTheme(<span>x</span>, { fontSize: "sm" });
+      const root = container.firstElementChild as HTMLElement;
+      expect(root.style.getPropertyValue("--font-size-sm")).toBe("0.8125rem");
+    });
+
+    it("fontSize lg sets --font-size-sm on root", () => {
+      const { container } = renderWithTheme(<span>x</span>, { fontSize: "lg" });
+      const root = container.firstElementChild as HTMLElement;
+      expect(root.style.getPropertyValue("--font-size-sm")).toBe("0.9375rem");
+    });
+
+    it("primaryColor logistics sets primary + accent + ring", () => {
+      const { container } = renderWithTheme(<span>x</span>, { primaryColor: "logistics" });
+      const root = container.firstElementChild as HTMLElement;
+      expect(root.style.getPropertyValue("--primary")).toBe("173 80% 36%");
+      expect(root.style.getPropertyValue("--accent")).toBe("173 80% 94%");
+      expect(root.style.getPropertyValue("--ring")).toBe("173 80% 36%");
+    });
+
+    it.each(["brand", "crm", "partner", "slate"] as const)(
+      "primaryColor %s sets matching accent foreground pair",
+      (primaryColor) => {
+        const { container } = renderWithTheme(<span>x</span>, { primaryColor });
+        const root = container.firstElementChild as HTMLElement;
+        const primary = root.style.getPropertyValue("--primary");
+        const accent = root.style.getPropertyValue("--accent");
+        expect(primary.length).toBeGreaterThan(0);
+        expect(accent.length).toBeGreaterThan(0);
+        expect(primary).not.toBe(accent);
+      },
+    );
+  });
+
+  describe("pagination + calendar avoid legacy hardcoded sizes", () => {
+    it("pagination prev button uses semantic compact icon class", () => {
+      renderWithTheme(
+        <Pagination current={2} total={100} pageSize={20} onChange={() => undefined} />,
+      );
+      const prev = screen.getByRole("button", { name: /trang trước/i });
+      expect(prev.className).not.toMatch(/\bsize-8\b/);
+      expect(prev).toHaveClass("ui-button--compact-icon");
+    });
+
+    it("calendar day button uses var(--control-height)", () => {
+      renderWithTheme(<Calendar mode="single" />);
+      const dayButton = screen.getByRole("grid").querySelector("button");
+      expect(dayButton?.className ?? "").toContain("var(--control-height)");
+      expect(dayButton?.className ?? "").not.toMatch(/\bsize-9\b/);
+    });
+  });
+});
+
+describe("theme axes — control-styles import contracts", () => {
+  const requiredImports: { file: string; exportName: string }[] = [
+    { file: "data-entry/select.tsx", exportName: "controlTriggerClass" },
+    { file: "data-entry/textarea.tsx", exportName: "controlMultilineClass" },
+    { file: "data-entry/command.tsx", exportName: "controlIconLeadingClass" },
+    { file: "data-entry/calendar.tsx", exportName: "controlIconSmClass" },
+    { file: "data-entry/color-picker.tsx", exportName: "controlIconClass" },
+    { file: "data-entry/upload.tsx", exportName: "controlIconClass" },
+    { file: "data-display/badge.tsx", exportName: "toneSuccessClass" },
+    { file: "data-display/table.tsx", exportName: "tableHeadHeightClass" },
+    { file: "data-display/data-table.tsx", exportName: "tableRowHeightClass" },
+    { file: "data-display/status-badge.tsx", exportName: "toneSuccessClass" },
+    { file: "navigation/steps.tsx", exportName: "controlIconClass" },
+    { file: "feedback/skeleton.tsx", exportName: "tableRowHeightClass" },
+  ];
+
+  it.each(requiredImports)(
+    "$file imports $exportName from control-styles",
+    ({ file, exportName }) => {
+      const content = readComponent(file);
+      expect(content, `${file} must import from control-styles`).toContain("control-styles");
+      expect(content, `${file} must use ${exportName}`).toContain(exportName);
+    },
+  );
+});

package/src/components/admin/index.ts

@@ -0,0 +1,76 @@
+// Backward-compatible admin barrel.
+export type { BreadcrumbItemProp as BreadcrumbItem } from "../../props/vocabulary/navigation.prop";
+export type {
+  PageContainerProp,
+  PageContainerProp as PageContainerProps,
+} from "../../props/components/layout.prop";
+
+export { PageHeader } from "../navigation/page-header";
+/* eslint-disable-next-line @typescript-eslint/no-deprecated -- backward-compat export */
+export type { PageHeaderProp } from "../../props/components/layout.prop";
+
+export { PageContainer } from "../layout/page-container";
+export { Stack, Inline } from "../layout";
+export type { StackProp, InlineProp } from "../../props/components/layout.prop";
+
+export { EmptyState } from "../data-display/empty-state";
+export { StatusBadge } from "../data-display/status-badge";
+export { FormField } from "../data-entry/form-field";
+export { KeyValueGrid } from "../data-display/key-value-grid";
+export { SkeletonRows, SkeletonTable, SkeletonDetail, SkeletonCard } from "../feedback/skeleton";
+export {
+  DataState,
+  MutationFeedback,
+  QueryRefetchButton,
+  InfiniteQueryState,
+  flattenItemPages,
+  PrefetchLink,
+} from "../query";
+export {
+  Alert,
+  AlertTitle,
+  AlertContent,
+  AlertDescription,
+  AlertActions,
+  AlertQueryError,
+} from "../feedback/alert";
+export { SearchInput } from "../data-entry/search-input";
+export {
+  Upload,
+  collectUploadCommitActions,
+  createUploadItem,
+  useUploadDraft,
+} from "../data-entry/upload";
+export { Cascader } from "../data-entry/cascader";
+export { TreeSelect } from "../data-entry/tree-select";
+export { Transfer } from "../data-entry/transfer";
+export {
+  Pagination,
+  Steps,
+  TabsItems,
+  Tabs,
+  TabsContent,
+  TabsList,
+  TabsTrigger,
+} from "../navigation";
+export { FilterBar, FilterGroup } from "../navigation/filter-bar";
+export {
+  Dialog,
+  DialogTrigger,
+  DialogContent,
+  DialogHeader,
+  DialogFooter,
+  DialogTitle,
+  DialogDescription,
+  DialogConfirm,
+} from "../feedback/dialog";
+export { DataTable } from "../data-display/data-table";
+export type { ColumnDef, Density } from "../data-display/data-table";
+export { Toaster } from "../feedback/sonner";
+export { toast, useToast } from "../feedback/use-toast";
+export type { LegacyToastOptions } from "../feedback/use-toast";
+export { useDebouncedValue, useTimeoutFlag } from "../../lib/hooks";
+export { formatDate, formatBytes, formatCurrency, shortId, humanError } from "../../lib/format";
+/* eslint-disable @typescript-eslint/no-deprecated -- backward-compatible admin barrel re-exports legacy helpers. */
+export { formatDateTime, formatDateLong, formatRelative } from "../../lib/format";
+/* eslint-enable @typescript-eslint/no-deprecated */