@godxjp/ui 31.0.2 → 31.0.3

package/agent/START-HERE.md

@@ -3,7 +3,7 @@
 You are about to write code against a design system you did not author. This file is the whole
 contract. Read it before you write JSX.
 
-**This catalog describes `@godxjp/ui` 31.0.2.** If the project you are editing has a different
+**This catalog describes `@godxjp/ui` 31.0.3.** If the project you are editing has a different
 version in its `package.json`, read the pinned catalog for THAT version instead
 (`…/v<their-version>/agent/…`). A catalog newer than the installed package describes props that do
 not exist yet; older, and it hides props that do. Neither failure announces itself.

package/agent/index.json

@@ -48,7 +48,7 @@
   "note": "Pin to the tag that matches the @godxjp/ui version you installed. A catalog newer than your package describes props you do not have; older, and it hides props you do.",
   "read": {
     "live": "https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/index.json",
-    "pinned": "https://raw.githubusercontent.com/godx-jp/godxjp-ui/v31.0.2/agent/index.json"
+    "pinned": "https://raw.githubusercontent.com/godx-jp/godxjp-ui/v31.0.3/agent/index.json"
   },
   "source": "mcp/src/data — the same data @godxjp/ui-mcp serves — plus the foundation and semantic token tiers, read from src/tokens/*.css",
   "start": "https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/START-HERE.md",
@@ -62,5 +62,5 @@
     "foundation": "the seeds a consumer is invited to set — --primary, --background, --radius",
     "semantic": "named roles that follow the seeds — --ring, --text-link, --overlay-background"
   },
-  "version": "31.0.2"
+  "version": "31.0.3"
 }

package/agent/llms.txt

@@ -1,10 +1,10 @@
 # @godxjp/ui
 
 > A Japanese-enterprise React design system: 175 components, 2074 design tokens,
-> 50 cardinal rules. This file is the entry point for AI agents. Catalog version 31.0.2.
+> 50 cardinal rules. This file is the entry point for AI agents. Catalog version 31.0.3.
 
 If your client can run a process, do not read these files — run the MCP server instead
-(`npx @godxjp/ui-mcp@31.0.2`). It is searchable and version-locked. These files exist for agents
+(`npx @godxjp/ui-mcp@31.0.3`). It is searchable and version-locked. These files exist for agents
 that can only fetch URLs.
 
 ## Start
@@ -26,7 +26,7 @@ that can only fetch URLs.
 ## Pinning
 
 Every URL above tracks `main`. To pin to the release a project actually installed, swap `main` for
-the tag: `.../godx-jp/godxjp-ui/v31.0.2/agent/...`. A catalog that does not match the installed
+the tag: `.../godx-jp/godxjp-ui/v31.0.3/agent/...`. A catalog that does not match the installed
 package describes props that are absent, or hides props that are present, and says nothing either way.
 
 Pinned catalogs only exist for releases whose tag actually contains `agent/`. If `…/v<version>/agent/index.json` returns 404, that release predates this catalog: read `…/main/…` instead and compare `index.json` → `version` against the package you have, so you at least know which way it drifted.

package/dist/contracts/measurement.json

@@ -1,6 +1,6 @@
 {
   "$comment": "AUTO-GENERATED by scripts/gen-measurement-contract.mjs — do not edit. Read this instead of guessing: docs/MEASUREMENT-CONTRACT.md.",
-  "version": "31.0.2",
+  "version": "31.0.3",
   "targetSize": {
     "standard": "WCAG 2.2 SC 2.5.8 Target Size (Minimum), level AA — 24×24 CSS px",
     "min": 24,

package/dist/i18n/translate.d.ts

@@ -28,6 +28,8 @@ export declare function translate(locale: AppLocale, fallbackLocale: AppLocale,
 /** Non-React translate using module-synced locale (see `syncI18nLocale`). */
 export declare function translateCurrent(key: MessageKey, params?: TranslateParams): string;
 export declare function syncI18nLocale(locale: AppLocale, fallbackLocale: AppLocale): void;
+/** Whether anything has ever called `syncI18nLocale` — the resting "vi" was never CHOSEN. */
+export declare function isI18nLocaleSynced(): boolean;
 export declare function getSyncedLocale(): AppLocale;
 export declare function getSyncedFallbackLocale(): AppLocale;
 /** Reset for tests. */

package/dist/i18n/translate.js

@@ -81,9 +81,14 @@ function translateCurrent(key, params) {
 }
 let syncedLocale = "vi";
 let syncedFallbackLocale = "en";
+let syncedByCaller = false;
 function syncI18nLocale(locale, fallbackLocale) {
   syncedLocale = locale;
   syncedFallbackLocale = fallbackLocale;
+  syncedByCaller = true;
+}
+function isI18nLocaleSynced() {
+  return syncedByCaller;
 }
 function getSyncedLocale() {
   return syncedLocale;
@@ -94,11 +99,13 @@ function getSyncedFallbackLocale() {
 function resetI18nLocale() {
   syncedLocale = "vi";
   syncedFallbackLocale = "en";
+  syncedByCaller = false;
 }
 export {
   MESSAGE_CATALOG,
   getSyncedFallbackLocale,
   getSyncedLocale,
+  isI18nLocaleSynced,
   registerMessages,
   resetI18nLocale,
   syncI18nLocale,

package/dist/i18n/use-translation.d.ts

@@ -1,15 +1,16 @@
 import type { DayPickerProps } from "react-day-picker";
-import type { AppLocale } from "../app/types.js";
 import { type MessageKey, type TranslateParams } from "./translate.js";
+/** Test seam: the once-only warning is module state. */
+export declare function resetOutsideProviderWarningForTests(): void;
 type DayPickerLocale = NonNullable<DayPickerProps["locale"]>;
 export declare function useTranslation(): {
-    locale: AppLocale;
-    fallbackLocale: AppLocale;
+    locale: import("../app/index.js").AppLocale;
+    fallbackLocale: import("../app/index.js").AppLocale;
     t: (key: MessageKey, params?: TranslateParams) => string;
 };
 /** date-fns + react-day-picker locales + datetime prefs from AppProvider. */
 export declare function usePickerLocales(dayPickerOverride?: DayPickerLocale): {
-    locale: AppLocale;
+    locale: import("../app/index.js").AppLocale;
     timezone: string;
     timeFormat: import("../app/index.js").AppTimeFormat;
     dateFormat: import("../app/index.js").AppDateFormat;

package/dist/i18n/use-translation.js

@@ -2,13 +2,30 @@
 import { useMemo } from "react";
 import { useOptionalAppContext } from "../app/app-provider.js";
 import { getDateFnsLocale, getDayPickerLocale } from "../app/locales.js";
-import { translate } from "./translate.js";
-const DEFAULT_LOCALE = "vi";
-const DEFAULT_FALLBACK = "en";
+import { resolveHydrationSafeTimezone } from "../app/timezones.js";
+import { isDevelopment } from "../lib/dev.js";
+import {
+  getSyncedFallbackLocale,
+  getSyncedLocale,
+  isI18nLocaleSynced,
+  translate
+} from "./translate.js";
+let warnedOutsideProvider = false;
+function warnOutsideProvider(locale) {
+  if (warnedOutsideProvider || !isDevelopment() || isI18nLocaleSynced()) return;
+  warnedOutsideProvider = true;
+  console.warn(
+    `[@godxjp/ui] A kit component rendered outside <AppProvider>, so its built-in strings (close/cancel/delete labels, counters, pickers) use the resting locale "${locale}" \u2014 nothing chose it. Wrap the app in <AppProvider defaultLocale="\u2026"> (docs/CONSUMER-RULES.md), or call syncI18nLocale(locale, fallback) at startup if you truly cannot. Shown once.`
+  );
+}
+function resetOutsideProviderWarningForTests() {
+  warnedOutsideProvider = false;
+}
 function useTranslation() {
   const ctx = useOptionalAppContext();
-  const locale = ctx?.locale ?? DEFAULT_LOCALE;
-  const fallbackLocale = ctx?.fallbackLocale ?? DEFAULT_FALLBACK;
+  const locale = ctx?.locale ?? getSyncedLocale();
+  const fallbackLocale = ctx?.fallbackLocale ?? getSyncedFallbackLocale();
+  if (!ctx) warnOutsideProvider(locale);
   return useMemo(
     () => ({
       locale,
@@ -20,11 +37,14 @@ function useTranslation() {
 }
 function usePickerLocales(dayPickerOverride) {
   const ctx = useOptionalAppContext();
-  const locale = ctx?.locale ?? DEFAULT_LOCALE;
+  const locale = ctx?.locale ?? getSyncedLocale();
+  if (!ctx) warnOutsideProvider(locale);
   return useMemo(
     () => ({
       locale,
-      timezone: ctx?.timezone ?? "Asia/Ho_Chi_Minh",
+      // AppProvider's own unconfigured answer (gh#968) — a zone that looks right when it is wrong
+      // (Asia/Ho_Chi_Minh) is worse than one that is visibly not local.
+      timezone: ctx?.timezone ?? resolveHydrationSafeTimezone("browser"),
       timeFormat: ctx?.timeFormat ?? "24h",
       dateFormat: ctx?.dateFormat ?? "dmy",
       dateFnsLocale: ctx?.dateFnsLocale ?? getDateFnsLocale(locale),
@@ -42,6 +62,7 @@ function usePickerLocales(dayPickerOverride) {
   );
 }
 export {
+  resetOutsideProviderWarningForTests,
   usePickerLocales,
   useTranslation
 };

package/dist/styles/layers.json

@@ -1,5 +1,5 @@
 {
-  "version": "31.0.2",
+  "version": "31.0.3",
   "generatedBy": "scripts/gen-style-layers.mjs — do not edit by hand; run `pnpm gen:style-layers`",
   "base": "base.css",
   "fonts": "fonts.css",

package/docs/CONSUMER-RULES.md

@@ -3,7 +3,7 @@
 Read this once; the audit enforces it. Everything else in `docs/` is for contributors.
 
 1. Load styles with `@import "@godxjp/ui/styles"` (fonts bundled, 729 sliced woff2 faces, ~11.7 MB), `@import "@godxjp/ui/styles/core"` (no `@font-face` at all), `@import "@godxjp/ui/styles/core-with-fallbacks"` (`core` + six `local()`-only metric-matched faces, still zero network bytes — for when you supply Noto Sans JP yourself) or `@import "@godxjp/ui/styles/core-with-jis-level1"` (`core-with-fallbacks` + Noto Sans JP merged to JIS X 0208 level 1: **3 requests, ~1.53 MB, once** instead of ~8 font requests on every navigation — for a Japanese app that wants the bundled face). Never cherry-pick `*-layout.css`.
-2. Every page is `<PageContainer title subtitle extra footer>`; its sections are spaced by the page. Group items inside a section with `<Flex direction="col" gap>` or `<ResponsiveGrid>`.
+2. **Mount `<AppProvider defaultLocale="…">` once, at the root.** Without it the kit's OWN strings (dialog close/cancel/delete, counters, picker labels) fall to the resting locale `vi` and pickers to UTC — measured in a Japanese app as Vietnamese buttons, silently (gh#1005). A development build now warns once when a kit component renders outside it; `syncI18nLocale(locale, fallback)` is the escape for an app that truly cannot mount the provider. Every page is `<PageContainer title subtitle extra footer>`; its sections are spaced by the page. Group items inside a section with `<Flex direction="col" gap>` or `<ResponsiveGrid>`.
 3. No Tailwind layout on your own elements: no `flex`, `grid`, `gap-*`, `p-*`, `m-*`, `space-*`. Rows are `<Flex>` (default row), stacks are `<Flex direction="col">`, grids are `<ResponsiveGrid>`.
 4. No hand-rolled surfaces: no `rounded-* border bg-*` divs. A box is `Card`, a pill is `Badge`, a person is `Avatar`, a row is `ListRow`, a label/value pair is `Descriptions`, an empty area is `EmptyState`, a read-only sample of a colour the USER chose is `Swatch`. A LIST of those rows is `<Flex as="ul" marker="none" direction="col" gap="none">` with `<ListRow as="li">` children — `marker="none"` keeps the `<ul>`, the `<li>` semantics and the gap token while dropping the bullet and the indent. Never a raw `<ul>`/`<ol>` (it carries no gap token), never `<div role="list">` + `<div role="listitem">`, and never a wrapper around each row: the divider is `:not(:last-child)` among siblings, so a row alone in its own wrapper is always the last one and EVERY divider disappears silently. A bulleted prose list is the same `<Flex as="ul">` without `marker`.
 5. Real controls only: `Button`, `Input`, `Select`, `Textarea`, `Checkbox`… never raw `<button>`/`<input>`; a labelled control lives in `<FormField label>`. A Select outside a form takes `width="auto"`. **A disabled control's reason is visible text, never a tooltip** — see below. **Fields live in a `<Form layout="horizontal" labelWidth controlWidth>`** — never a group of `FormField`s without one, never a hand-rolled `<Flex>` row of fields (a row that belongs together is `<SpaceCompact>` or `<Form columns>`); size each control for its content with `controlWidth` (GOV.UK text-input width: a port ~7rem, a short enum ~10rem); three or more fields is a page, not a Dialog. The audit rules are `formfield-needs-form`, `dialog-form-too-big` and `select-width-hint`. **A case the kit cannot express is an issue, not a hand-roll:** open it on godx-jp/godxjp-ui, use the nearest valid composition, and mark it `// TODO(godxjp-ui#<n>)` (gh#998).

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@godxjp/ui",
-  "version": "31.0.2",
-  "godxUiMcp": "31.0.2",
+  "version": "31.0.3",
+  "godxUiMcp": "31.0.3",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",

package/scripts/consumer-rule.md

@@ -120,6 +120,14 @@ ngày: năm thứ cần đều ĐÃ CÓ và vẫn bị dựng lại bằng thứ
 Lỗi không phải "đoán sai tên prop" mà là **cho rằng nó không tồn tại nên không
 hỏi**.
 
+## `AppProvider` là bắt buộc — thiếu nó, chuỗi của kit nói tiếng Việt
+
+Mount `<AppProvider defaultLocale="ja">` MỘT lần ở gốc app. Thiếu nó, chuỗi của chính kit (nút
+đóng/hủy/xóa của dialog, upload, badge đếm, nhãn picker) rơi về locale nghỉ `vi` và picker rơi về
+UTC — godx-mailer đo được nút tiếng Việt giữa UI tiếng Nhật, không một cảnh báo (gh#1005). Bản dev
+giờ cảnh báo MỘT lần khi component của kit render ngoài provider. Không mount được provider thì gọi
+`syncI18nLocale(locale, fallback)` lúc khởi động.
+
 ## Form: `Form` bọc `FormField`, bề rộng theo nội dung, form dài là PAGE
 
 godx-mailer dính bốn lỗi form trong một ngày, cả bốn đều là kit ĐÃ CÓ đồ đúng