@godxjp/ui 5.0.2 → 6.0.0

package/scripts/ui-audit.mjs

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+/**
+ * godxjp-ui audit — the design system's own linter for consumer UI code.
+ *
+ * Enforces the UI-standardization rules that ship with @godxjp/ui
+ * (see the app's .claude/skills/frontend-design/rules/ui-standardization.md):
+ * use the design system, never hand-roll. Inspired by `@google/design.md lint`
+ * — structured, agent-readable findings.
+ *
+ * Runs from the CONSUMER's repo root and scans its hand-written UI
+ * (components / pages / layouts) — never the framework or generated code.
+ *
+ * Usage (from the consuming app):
+ *   node packages/godx-ui/scripts/ui-audit.mjs                 # human report; exit 1 on error
+ *   node packages/godx-ui/scripts/ui-audit.mjs --format json
+ *   node packages/godx-ui/scripts/ui-audit.mjs --quiet         # errors only
+ *   node packages/godx-ui/scripts/ui-audit.mjs src/ui lib/     # custom scan dirs
+ */
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+
+const CWD = process.cwd();
+const args = process.argv.slice(2);
+const asJson = args.includes("--format") && args[args.indexOf("--format") + 1] === "json";
+const quiet = args.includes("--quiet");
+const dirArgs = args.filter((a) => !a.startsWith("--") && a !== "json");
+const SCAN_DIRS = dirArgs.length
+  ? dirArgs
+  : ["resources/js/components", "resources/js/pages", "resources/js/layouts"];
+
+const PALETTE =
+  "red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose|gray|grey|slate|zinc|neutral|stone";
+
+/** @type {{id:string, severity:'error'|'warn', test:RegExp, message:string}[]} */
+const RULES = [
+  {
+    id: "no-space-xy",
+    severity: "error",
+    test: /\bspace-[xy]-\d/,
+    message: "Use <Stack>/<Inline> with gap, not space-x/y-* (rules §5).",
+  },
+  {
+    id: "no-raw-palette-color",
+    severity: "error",
+    test: new RegExp(
+      `\\b(bg|text|border|ring|fill|stroke|from|to|via|divide|outline)-(${PALETTE})-\\d`,
+    ),
+    message:
+      "Use semantic tokens (bg-primary, text-muted-foreground…), not raw palette colors (rules §4).",
+  },
+  {
+    id: "no-arbitrary-hex",
+    severity: "error",
+    test: /(bg|text|border|ring|fill|stroke|from|to|via)-\[#[0-9a-fA-F]{3,8}\]/,
+    message: "No hardcoded hex colors in className; use design-system tokens (rules §4).",
+  },
+  {
+    id: "no-raw-select",
+    severity: "error",
+    test: /<select[\s>]/,
+    message: "Use <Select> from @godxjp/ui, not a raw <select> (rules §3).",
+  },
+  {
+    id: "no-raw-table",
+    severity: "error",
+    test: /<table[\s>]/,
+    message: "Use the <Table> family from @godxjp/ui, not a raw <table> (rules §3).",
+  },
+  {
+    id: "no-raw-textarea",
+    severity: "warn",
+    test: /<textarea[\s>]/,
+    message: "Use <Textarea> from @godxjp/ui, not a raw <textarea> (rules §3).",
+  },
+  {
+    id: "no-dark-color-override",
+    severity: "warn",
+    test: /\bdark:(bg|text|border|ring|fill|stroke)-/,
+    message: "Don't add dark: color overrides — semantic tokens already adapt (rules §4).",
+  },
+  {
+    id: "manual-field-error",
+    severity: "warn",
+    test: /<p[^>]*className="[^"]*text-(xs|sm)[^"]*text-destructive/,
+    message:
+      "Field errors should use <FormField error=…>, not a hand-rolled <p> (rules §1). OK only for checkbox/radio groups.",
+  },
+  {
+    id: "manual-field-helper",
+    severity: "warn",
+    test: /<p[^>]*className="text-xs text-muted-foreground"/,
+    message:
+      "Field helper text should use <FormField helper=…>, not a hand-rolled <p> (rules §1). OK only for checkbox/radio groups.",
+  },
+  {
+    id: "raw-white-black",
+    severity: "warn",
+    test: /\b(bg|text|border)-(white|black)\b/,
+    message:
+      "Prefer semantic tokens (text-primary-foreground, bg-background…) over raw white/black (rules §4).",
+  },
+];
+
+function walk(dir, acc = []) {
+  let entries;
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return acc;
+  }
+  for (const name of entries) {
+    const full = join(dir, name);
+    const st = statSync(full);
+    if (st.isDirectory()) {
+      walk(full, acc);
+    } else if (name.endsWith(".tsx") || name.endsWith(".ts")) {
+      acc.push(full);
+    }
+  }
+  return acc;
+}
+
+const findings = [];
+for (const dir of SCAN_DIRS) {
+  for (const file of walk(join(CWD, dir))) {
+    const rel = relative(CWD, file);
+    const lines = readFileSync(file, "utf8").split("\n");
+    lines.forEach((line, i) => {
+      for (const rule of RULES) {
+        if (rule.test.test(line)) {
+          findings.push({
+            file: rel,
+            line: i + 1,
+            rule: rule.id,
+            severity: rule.severity,
+            message: rule.message,
+            snippet: line.trim().slice(0, 120),
+          });
+        }
+      }
+    });
+  }
+}
+
+const errors = findings.filter((f) => f.severity === "error");
+const warnings = findings.filter((f) => f.severity === "warn");
+
+if (asJson) {
+  process.stdout.write(
+    JSON.stringify(
+      { summary: { errors: errors.length, warnings: warnings.length }, findings },
+      null,
+      2,
+    ) + "\n",
+  );
+} else {
+  const C = {
+    red: "\x1b[31m",
+    yellow: "\x1b[33m",
+    dim: "\x1b[2m",
+    bold: "\x1b[1m",
+    reset: "\x1b[0m",
+  };
+  const shown = quiet ? errors : findings;
+  for (const f of shown) {
+    const tag = f.severity === "error" ? `${C.red}error${C.reset}` : `${C.yellow}warn ${C.reset}`;
+    console.log(`${tag} ${C.bold}${f.file}:${f.line}${C.reset}  ${C.dim}[${f.rule}]${C.reset}`);
+    console.log(`      ${f.message}`);
+    console.log(`      ${C.dim}${f.snippet}${C.reset}`);
+  }
+  console.log(
+    `\ngodxjp-ui audit: ${C.red}${errors.length} error(s)${C.reset}, ${C.yellow}${warnings.length} warning(s)${C.reset} across ${SCAN_DIRS.join(", ")}.`,
+  );
+  if (errors.length === 0 && warnings.length === 0) {
+    console.log("✓ No UI-standardization violations found.");
+  }
+}
+
+process.exit(errors.length > 0 ? 1 : 0);

package/src/app/__tests__/app-provider.test.tsx

@@ -0,0 +1,232 @@
+import { describe, expect, it, vi, beforeEach, afterEach } from "vitest";
+import { renderHook, act } from "@testing-library/react";
+import * as React from "react";
+import { AppProvider, useAppContext } from "../app-provider";
+import { getAppRequestHeaders, resetAppRequestHeaders } from "../request-headers";
+import { resetI18nLocale } from "../../i18n/translate";
+import { readStoredPreferences, writeStoredPreferences } from "../storage";
+
+const STORAGE_KEY = "godxjp.app.test";
+
+function wrapper(props: React.PropsWithChildren<{ persist?: boolean }>) {
+  return (
+    <AppProvider
+      storageKey={STORAGE_KEY}
+      persist={props.persist ?? false}
+      defaultLocale="vi"
+      fallbackLocale="en"
+      defaultTimezone="Asia/Tokyo"
+    >
+      {props.children}
+    </AppProvider>
+  );
+}
+
+describe("AppProvider", () => {
+  beforeEach(() => {
+    resetAppRequestHeaders();
+    resetI18nLocale();
+    localStorage.removeItem(STORAGE_KEY);
+  });
+
+  afterEach(() => {
+    localStorage.removeItem(STORAGE_KEY);
+  });
+
+  it("initializes locale and timezone and syncs request headers", () => {
+    const { result } = renderHook(() => useAppContext(), {
+      wrapper: ({ children }) => wrapper({ children }),
+    });
+
+    expect(result.current.locale).toBe("vi");
+    expect(result.current.timezone).toBe("Asia/Tokyo");
+    expect(getAppRequestHeaders()).toEqual({
+      "x-locale": "vi",
+      "x-timezone": "Asia/Tokyo",
+      "x-time-format": "24h",
+      "x-date-format": "dmy",
+    });
+  });
+
+  it("updates headers when locale and timezone change", () => {
+    const { result } = renderHook(() => useAppContext(), {
+      wrapper: ({ children }) => wrapper({ children }),
+    });
+
+    act(() => {
+      result.current.setLocale("ja");
+      result.current.setTimezone("Asia/Ho_Chi_Minh");
+      result.current.setTimeFormat("12h");
+      result.current.setDateFormat("iso");
+    });
+
+    expect(result.current.requestHeaders).toEqual({
+      "x-locale": "ja",
+      "x-timezone": "Asia/Ho_Chi_Minh",
+      "x-time-format": "12h",
+      "x-date-format": "iso",
+    });
+    expect(getAppRequestHeaders()["x-locale"]).toBe("ja");
+  });
+
+  it("persists preferences to localStorage", () => {
+    const { result } = renderHook(() => useAppContext(), {
+      wrapper: ({ children }) => wrapper({ children, persist: true }),
+    });
+
+    act(() => {
+      result.current.setLocale("en");
+      result.current.setTimezone("UTC");
+      result.current.setTimeFormat("12h");
+      result.current.setDateFormat("mdy");
+    });
+
+    expect(readStoredPreferences(STORAGE_KEY)).toEqual({
+      locale: "en",
+      timezone: "UTC",
+      timeFormat: "12h",
+      dateFormat: "mdy",
+    });
+  });
+
+  it("restores persisted preferences on mount", () => {
+    writeStoredPreferences(STORAGE_KEY, {
+      locale: "ja",
+      timezone: "Asia/Singapore",
+      timeFormat: "12h",
+      dateFormat: "iso",
+    });
+
+    const { result } = renderHook(() => useAppContext(), {
+      wrapper: ({ children }) => wrapper({ children, persist: true }),
+    });
+
+    expect(result.current.locale).toBe("ja");
+    expect(result.current.timezone).toBe("Asia/Singapore");
+    expect(result.current.timeFormat).toBe("12h");
+    expect(result.current.dateFormat).toBe("iso");
+  });
+
+  it("calls onLocaleChange and onTimezoneChange", () => {
+    const onLocaleChange = vi.fn();
+    const onTimezoneChange = vi.fn();
+
+    const { result } = renderHook(() => useAppContext(), {
+      wrapper: ({ children }) => (
+        <AppProvider
+          storageKey={STORAGE_KEY}
+          persist={false}
+          onLocaleChange={onLocaleChange}
+          onTimezoneChange={onTimezoneChange}
+        >
+          {children}
+        </AppProvider>
+      ),
+    });
+
+    act(() => {
+      result.current.setLocale("en");
+      result.current.setTimezone("UTC");
+    });
+
+    expect(onLocaleChange).toHaveBeenCalledWith("en");
+    expect(onTimezoneChange).toHaveBeenCalledWith("UTC");
+  });
+
+  it("derives default time format from locale when defaultTimeFormat is locale", () => {
+    const { result: enResult } = renderHook(() => useAppContext(), {
+      wrapper: ({ children }) => (
+        <AppProvider storageKey={STORAGE_KEY} persist={false} defaultLocale="en">
+          {children}
+        </AppProvider>
+      ),
+    });
+    expect(enResult.current.timeFormat).toBe("12h");
+
+    const { result: viResult } = renderHook(() => useAppContext(), {
+      wrapper: ({ children }) => (
+        <AppProvider storageKey={STORAGE_KEY} persist={false} defaultLocale="vi">
+          {children}
+        </AppProvider>
+      ),
+    });
+    expect(viResult.current.timeFormat).toBe("24h");
+  });
+
+  it("derives default date format from locale when defaultDateFormat is locale", () => {
+    const { result: enResult } = renderHook(() => useAppContext(), {
+      wrapper: ({ children }) => (
+        <AppProvider storageKey={STORAGE_KEY} persist={false} defaultLocale="en">
+          {children}
+        </AppProvider>
+      ),
+    });
+    expect(enResult.current.dateFormat).toBe("mdy");
+
+    const { result: viResult } = renderHook(() => useAppContext(), {
+      wrapper: ({ children }) => (
+        <AppProvider storageKey={STORAGE_KEY} persist={false} defaultLocale="vi">
+          {children}
+        </AppProvider>
+      ),
+    });
+    expect(viResult.current.dateFormat).toBe("dmy");
+
+    const { result: jaResult } = renderHook(() => useAppContext(), {
+      wrapper: ({ children }) => (
+        <AppProvider storageKey={STORAGE_KEY} persist={false} defaultLocale="ja">
+          {children}
+        </AppProvider>
+      ),
+    });
+    expect(jaResult.current.dateFormat).toBe("iso");
+  });
+
+  it("throws outside AppProvider", () => {
+    expect(() => renderHook(() => useAppContext())).toThrow(/AppProvider/);
+  });
+
+  it("exposes timezoneOptions on context when configured", () => {
+    const zones = ["Asia/Tokyo", "Asia/Ho_Chi_Minh"] as const;
+    const { result } = renderHook(() => useAppContext(), {
+      wrapper: ({ children }) => (
+        <AppProvider storageKey={STORAGE_KEY} persist={false} timezoneOptions={zones}>
+          {children}
+        </AppProvider>
+      ),
+    });
+    expect(result.current.timezoneOptions).toEqual(zones);
+  });
+
+  it("timezoneOptions undefined means full IANA list in picker", () => {
+    const { result } = renderHook(() => useAppContext(), {
+      wrapper: ({ children }) => (
+        <AppProvider storageKey={STORAGE_KEY} persist={false}>
+          {children}
+        </AppProvider>
+      ),
+    });
+    expect(result.current.timezoneOptions).toBeUndefined();
+  });
+
+  it("calls onDateFormatChange when date format updates", () => {
+    const onDateFormatChange = vi.fn();
+    const { result } = renderHook(() => useAppContext(), {
+      wrapper: ({ children }) => (
+        <AppProvider
+          storageKey={STORAGE_KEY}
+          persist={false}
+          onDateFormatChange={onDateFormatChange}
+        >
+          {children}
+        </AppProvider>
+      ),
+    });
+
+    act(() => {
+      result.current.setDateFormat("iso");
+    });
+
+    expect(onDateFormatChange).toHaveBeenCalledWith("iso");
+  });
+});

package/src/app/__tests__/date-format-labels.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from "vitest";
+import {
+  APP_DATE_FORMAT_OPTIONS,
+  getDateFormatLabel,
+  resolveDefaultDateFormat,
+} from "../date-format-labels";
+
+describe("date-format-labels", () => {
+  describe("resolveDefaultDateFormat", () => {
+    it.each([
+      ["vi", "dmy"],
+      ["ja", "iso"],
+      ["en", "mdy"],
+    ] as const)("locale %s → %s", (locale, expected) => {
+      expect(resolveDefaultDateFormat(locale)).toBe(expected);
+    });
+  });
+
+  describe("getDateFormatLabel", () => {
+    it("returns Vietnamese label for dmy", () => {
+      expect(getDateFormatLabel("dmy", "vi", "en")).toMatch(/Ngày|Tháng|Năm/);
+    });
+
+    it("returns Japanese ISO label", () => {
+      expect(getDateFormatLabel("iso", "ja", "en")).toMatch(/YYYY-MM-DD/);
+    });
+
+    it("returns English label when locale is en", () => {
+      expect(getDateFormatLabel("mdy", "en", "vi")).toMatch(/Month|Day|Year/i);
+    });
+  });
+
+  it("exports option list for pickers", () => {
+    expect(APP_DATE_FORMAT_OPTIONS.map((o) => o.value)).toEqual(["iso", "dmy", "mdy"]);
+  });
+});

package/src/app/__tests__/date-formats.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, it } from "vitest";
+import {
+  APP_DATE_FORMATS,
+  getDatePattern,
+  getDateTimePattern,
+  isAppDateFormat,
+} from "../date-formats";
+
+describe("date-formats", () => {
+  describe("getDatePattern", () => {
+    it.each([
+      ["iso", "yyyy-MM-dd"],
+      ["dmy", "dd/MM/yyyy"],
+      ["mdy", "MM/dd/yyyy"],
+    ] as const)("maps %s → %s", (format, pattern) => {
+      expect(getDatePattern(format)).toBe(pattern);
+    });
+  });
+
+  describe("getDateTimePattern", () => {
+    it("combines date pattern + 24h time", () => {
+      expect(getDateTimePattern("24h", "iso")).toBe("yyyy-MM-dd HH:mm");
+      expect(getDateTimePattern("24h", "dmy")).toBe("dd/MM/yyyy HH:mm");
+    });
+
+    it("combines date pattern + 12h time", () => {
+      expect(getDateTimePattern("12h", "mdy")).toBe("MM/dd/yyyy h:mm a");
+    });
+  });
+
+  describe("isAppDateFormat", () => {
+    it("accepts known presets", () => {
+      for (const format of APP_DATE_FORMATS) {
+        expect(isAppDateFormat(format)).toBe(true);
+      }
+    });
+
+    it("rejects unknown values", () => {
+      expect(isAppDateFormat("ymd")).toBe(false);
+      expect(isAppDateFormat(null)).toBe(false);
+      expect(isAppDateFormat("")).toBe(false);
+    });
+  });
+});

package/src/app/__tests__/timezones.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it } from "vitest";
+import {
+  APP_TIMEZONE_PRESET,
+  formatTimezoneDisplayLabel,
+  getAllIanaTimezones,
+  getTimezoneLabel,
+  getTimezoneOffsetLabel,
+  isValidIanaTimezone,
+  resolveTimezonePickerOptions,
+} from "../timezones";
+
+describe("timezones", () => {
+  it("exposes full IANA list by default", () => {
+    const all = getAllIanaTimezones();
+    expect(all.length).toBeGreaterThan(100);
+    expect(all).toContain("Asia/Ho_Chi_Minh");
+    expect(all).toContain("Asia/Tokyo");
+    expect(all).toContain("Europe/Paris");
+  });
+
+  it("preset covers cross-border hubs", () => {
+    expect(APP_TIMEZONE_PRESET).toContain("Asia/Ho_Chi_Minh");
+    expect(APP_TIMEZONE_PRESET).toContain("Australia/Sydney");
+    expect(APP_TIMEZONE_PRESET.length).toBeGreaterThanOrEqual(40);
+  });
+
+  it("resolveTimezonePickerOptions uses full list when unconfigured", () => {
+    const options = resolveTimezonePickerOptions(undefined, "Asia/Tokyo");
+    expect(options.length).toBeGreaterThan(100);
+    expect(options).toContain("Asia/Tokyo");
+  });
+
+  it("resolveTimezonePickerOptions respects AppProvider config", () => {
+    const configured = ["Asia/Tokyo", "Asia/Ho_Chi_Minh"] as const;
+    const options = resolveTimezonePickerOptions(configured, "Asia/Tokyo");
+    expect(options).toEqual(["Asia/Tokyo", "Asia/Ho_Chi_Minh"]);
+  });
+
+  it("prepends current timezone when missing from configured list", () => {
+    const options = resolveTimezonePickerOptions(["Asia/Tokyo"], "Europe/Paris");
+    expect(options[0]).toBe("Europe/Paris");
+    expect(options).toContain("Asia/Tokyo");
+  });
+
+  it("uses i18n label for curated zones", () => {
+    expect(getTimezoneLabel("Asia/Ho_Chi_Minh", "vi", "en")).toBe("Việt Nam (HCM)");
+    expect(getTimezoneLabel("Asia/Tokyo", "ja", "en")).toMatch(/日本|Tokyo/);
+  });
+
+  it("falls back to city + UTC offset for zones without i18n", () => {
+    const label = getTimezoneLabel("Europe/Paris", "en", "en");
+    expect(label).toMatch(/Paris/);
+    expect(label).toMatch(/GMT|UTC|[+-]\d/);
+  });
+
+  it("formats offset via Intl", () => {
+    expect(getTimezoneOffsetLabel("Asia/Ho_Chi_Minh", "en")).toMatch(/GMT|UTC|[+-]\d/);
+    expect(formatTimezoneDisplayLabel("Asia/Ho_Chi_Minh", "en")).toMatch(/Ho Chi Minh/);
+  });
+
+  it("validates IANA ids against full list", () => {
+    expect(isValidIanaTimezone("Asia/Jakarta")).toBe(true);
+    expect(isValidIanaTimezone("Not/A/Zone")).toBe(false);
+  });
+});