@godxjp/ui 5.0.2 → 6.0.1

package/README.md

@@ -1,181 +1,140 @@
 # @godxjp/ui
 
-**Version 3.0.0** — GoDX professional UI framework
+The shared React UI framework for every godx surface (admin, agency portal,
+handheld). Built on shadcn + Radix UI + Tailwind CSS v4.
 
-[![npm](https://img.shields.io/npm/v/@godxjp/ui)](https://www.npmjs.com/package/@godxjp/ui)
-[![License](https://img.shields.io/github/license/godx-jp/godxjp-ui)](LICENSE)
-[![Types included](https://img.shields.io/badge/types-included-blue)](src/)
-
-`@godxjp/ui` is the **single source of visual truth** for the GoDX platform.
-Every service frontend (admin-platform, forge-service, console-service, me-service,
-chat-service, knowledge-service, …) consumes this package. No service reimplements
-a button, dialog, sidebar, or design token.
-
-The framework enforces three Japanese-enterprise design principles:
-
-| Principle | Meaning | What it enforces |
-|---|---|---|
-| **渋み** (shibumi) | Restrained elegance | OKLCH primary chroma ≤ 0.18. No neon. No gradients on functional UI. |
-| **間** (ma) | Vertical breathing room | Body `line-height: 1.7`. Generous spacing. Density toggle for dense tables. |
-| **簡素** (kanso) | Simplicity | Three font weights: 400 (body), 500 (heading), 700 (emphasis). No 600 in new code. |
+Location: `packages/godx-ui/` (linked into the app as a `file:` dependency at
+`@godxjp/ui`).
 
 ---
 
-## Quick start
+## Role & boundary — read this first
 
-A new service needs three lines to be fully brand-compliant:
+This package is **the single source of UI truth**. It is shared, versioned
+infrastructure, which means two things are non-negotiable:
 
-```tsx
-// services/<slug>-service/frontend/src/main.tsx
-import "@godxjp/ui/tailwind.css"   // tokens + Tailwind v4 utilities — ONE import
-import { initI18n } from "@godxjp/ui/i18n"
-import { AppShell, Sidebar, Topbar } from "@godxjp/ui/components/shell"
-
-initI18n()
-
-createRoot(document.getElementById("root")!).render(
-  <BrowserRouter>
-    <AppShell sidebar={<Sidebar nav={MY_NAV} />} topbar={<Topbar />}>
-      <Routes>{/* service-specific routes */}</Routes>
-    </AppShell>
-  </BrowserRouter>,
-)
-```
+- **Editing it requires explicit session permission** (the hard gate — see
+  [DEVELOPMENT.md](./docs/DEVELOPMENT.md#0-what-this-package-is--and-the-boundary-it-must-keep)).
+  By default the package is off-limits; consumers _compose_ its primitives, they
+  don't fork them.
+- **It is generic and presentational only.** No app i18n (`useTranslation`), no
+  Inertia (`router`/`<Form>`), no Wayfinder routes, no business entities or domain
+  logic, no product copy, no raw colors. Those are **consumer-layer** concerns — they
+  must never leak into this package. The framework ships **its own theme**, so a
+  consumer imports the styles and needs **zero** extra theme configuration.
 
-That is the entire integration surface. No theming step. No per-service token file.
+> Deciding whether a component belongs here vs. app-level? Use the
+> **`godx-ui-component-placement`** skill.
 
----
+Full contributor rules: **[docs/DEVELOPMENT.md](./docs/DEVELOPMENT.md)**.
 
-## Zero-config toolchain
+---
 
-Per the umbrella's frontend-architecture spec (zero-config principle), services
-inherit the full toolchain from this package:
+## Architecture (bottom-up)
 
-```js
-// eslint.config.js — one line
-export { default } from "@godxjp/ui/eslint-config"
 ```
-
-```json
-// package.json
-"prettier": "@godxjp/ui/prettier-config"
+src/tokens/      Design tokens — the single source of values
+  foundation.css   :root + .dark: colors, fonts, type scale, spacing, radius, wa-iro
+  primitives/      Per-domain primitive tokens (card, table, control, badge, …)
+src/styles/      CSS that styles components by [data-slot]; density.css = the one density knob
+  index.css        Entry: fontsource → tailwindcss → @theme (token→utility map) → *-layout.css
+src/components/  React components by group (data-display, data-entry, layout, feedback, …)
+src/props/       Prop type system: vocabulary/ (atomic) + components/ + registry.ts
+src/lib/         cn(), control-styles, variants
+examples/        *.preview.tsx — Storybook-style stories
+docs/primitives/ <component>/index.tsx demo + examples/ + generated .md
+preview/         The preview app (vite, :6008) rendering examples + docs
 ```
 
-```json
-// tsconfig.json
-{ "extends": "@godxjp/ui/tsconfig" }
-```
-
-```ts
-// vitest.config.ts
-import base from "@godxjp/ui/vitest-config"
-import { mergeConfig } from "vitest/config"
-export default mergeConfig(base, { test: {} })
-```
+A value is defined **once** as a CSS var (`--primary`), mapped to a utility in the
+`@theme` block (`--color-primary: hsl(var(--primary))`), and consumed as `bg-primary`.
+Components emit `data-slot` / `data-*`; the look lives in `styles/*-layout.css`. See
+[DEVELOPMENT.md §1](./docs/DEVELOPMENT.md#1-architecture--the-layers-bottom-up).
 
 ---
 
-## Import surface
-
-| Import | What you get |
-|---|---|
-| `@godxjp/ui` | All primitives + hooks + i18n helpers (barrel) |
-| `@godxjp/ui/tailwind.css` | Tailwind v4 + design tokens + base styles |
-| `@godxjp/ui/tokens.css` | Raw CSS custom properties only (no Tailwind) |
-| `@godxjp/ui/tokens-ext.css` | Extended tokens (dark mode, tenants, sidebar vars) |
-| `@godxjp/ui/sonner.css` | Sonner toast animations (import after tokens) |
-| `@godxjp/ui/components/primitives` | All primitives — see [`src/components/primitives.ts`](src/components/primitives.ts) (single barrel; 73+ surfaces re-exported from six group folders per cardinal rule 27) |
-| `@godxjp/ui/components/shell` | `AppShell`, `Sidebar`, `Topbar`, `TweaksPanel`, `CommandPalette`, `ProductSwitcher`, `ProjectSwitcher`, `PageContent` |
-| `@godxjp/ui/components/composites` | Upload family, `MediaUpload`, `AvatarUploader`, `LocaleInput`, calendar app composite |
-| `@godxjp/ui/i18n` | `initI18n()`, `SUPPORTED_LOCALES`, `GodxLocale` |
-| `@godxjp/ui/hooks` | `useTweaks()`, `Tweaks`, `Density`, `Theme` |
-| `@godxjp/ui/preferences` | `PreferencesProvider` — locale + timezone React context |
-| `@godxjp/ui/eslint-config` | Shared ESLint flat config |
-| `@godxjp/ui/prettier-config` | Shared Prettier config |
-| `@godxjp/ui/tsconfig` | Strict TypeScript base |
-| `@godxjp/ui/vitest-config` | Vitest base with jsdom + coverage thresholds |
+## Component groups
+
+| Group              | Import                    | Examples                                                                        |
+| ------------------ | ------------------------- | ------------------------------------------------------------------------------- |
+| **Layout**         | `@godxjp/ui/layout`       | `PageContainer`, `Stack`, `Inline`, `ResponsiveGrid`                            |
+| **General**        | `@godxjp/ui/general`      | `Button`                                                                        |
+| **Data Entry**     | `@godxjp/ui/data-entry`   | `Input`, `Select`, `FormField`, `DatePicker`, `Switch`                          |
+| **Data Display**   | `@godxjp/ui/data-display` | `Table`, `DataTable`, `Card`, `Badge`, `KeyValueGrid`, `Timeline`, `EmptyState` |
+| **Feedback**       | `@godxjp/ui/feedback`     | `Dialog`, `Sheet`, `Toast`, `Skeleton`, `Alert`                                 |
+| **Query**          | `@godxjp/ui/query`        | `DataState`, `InfiniteQueryState`, `PrefetchLink`, `MutationFeedback`           |
+| **Navigation**     | `@godxjp/ui/navigation`   | `Tabs`, `FilterBar`, `DropdownMenu`, `Steps`, `Pagination`, `LocalePicker`      |
+| **App**            | `@godxjp/ui/app`          | `AppProvider`, `useDateTime`                                                    |
+| **Datetime**       | `@godxjp/ui/datetime`     | `formatDate` (mandatory for display)                                            |
+| **shadcn paths**   | `@godxjp/ui/ui`           | Thin re-exports for shadcn-style imports                                        |
+| **Admin (legacy)** | `@godxjp/ui/admin`        | Compound admin exports                                                          |
 
 ---
 
-## Primitives (v3)
-
-| Component | Radix backing | A11y | Status |
-|---|---|---|---|
-| `Badge` | — | WCAG 2.1 AA | production |
-| `Button` | `@radix-ui/react-slot` | focus-visible, keyboard | production |
-| `Card` | — | — | production |
-| `Input`, `Textarea` | — | aria-invalid, label wire | production |
-| `Label` | `@radix-ui/react-label` | for/id | production |
-| `Tabs`, `Tabs`, `Tabs`, `Tabs` | `@radix-ui/react-tabs` | roving tabindex | production |
-| `Avatar` | — | aria-label | production |
-| `Separator` | `@radix-ui/react-separator` | role separator | production |
-| `Popover`, `Popover`, `Popover` | `@radix-ui/react-popover` | focus trap | production |
-| `DropdownMenu` family | `@radix-ui/react-dropdown-menu` | keyboard nav | production |
-| `Calendar` | `react-day-picker` | ARIA grid | production |
-| `TimeInput` | — | aria-invalid | production |
-| `Dialog` family | `@radix-ui/react-dialog` | focus trap, aria-modal | production |
-| `Sheet` family | `@radix-ui/react-dialog` | focus trap, aria-modal | production |
-| `AlertDialog` family | `@radix-ui/react-alert-dialog` | focus trap | production |
-| `Select` family | `@radix-ui/react-select` | keyboard nav | production |
-| `Switch` | `@radix-ui/react-switch` | role switch | production |
-| `Checkbox` | `@radix-ui/react-checkbox` | role checkbox | production |
-| `Table` family | — | role table | production |
-| `Combobox` family | `cmdk` + Popover | keyboard nav | production |
-| `Toaster`, `toast` | `sonner` | aria-live | production |
-| `Skeleton` | — | aria-hidden | production |
-| `Breadcrumb`, `Breadcrumb`, `Breadcrumb` | — | aria-label, aria-current | production |
+## Consumer setup — theme is self-contained
 
----
+The framework ships colors, fonts (M PLUS 2 via `@fontsource`), the type scale, and
+the wa-iro palette. A consumer's entire styling surface is **one import + content
+sources** — no `:root` overrides, no font `<link>`:
 
-## i18n
+```css
+/* resources/css/app.css */
+@import "@godxjp/ui/styles";
+@source '../js/**/*.{ts,tsx}';
+@source '../views';
+```
 
-Mandatory locales per the umbrella frontend-architecture spec §6:
+```tsx
+import { AppProvider } from "@godxjp/ui/app"; // locale, tz, date/time format
+import { PageContainer } from "@godxjp/ui/layout"; // every page wraps in this
+```
 
-| Locale | Status |
-|---|---|
-| `ja` | production (primary) |
-| `en` | production |
-| `vi` | production |
-| `fil` | production (added v3.0.0) |
+### Mandatory consumer rules
 
-Services add extra namespaces via `i18n.addResourceBundle(locale, "my-ns", {…})`.
+1. **Every page** uses `<PageContainer title subtitle extra footer>`.
+2. **Mobile-first** — verify at 320–390px in preview / browser.
+3. **Spacing via `Stack`/`Inline` `gap` + `ResponsiveGrid`** — no Tailwind `p-*` /
+   `gap-*` / `space-x|y-*` for app layout (see `docs/SPACING.md`).
+4. **Semantic tokens only** — no raw colors / hex / `dark:` overrides.
+5. **Dates** display via `formatDate` from `@godxjp/ui/datetime`.
+6. **`AppProvider`** wraps the app for locale / timezone / date-time format.
+7. **Audit** — `npm run ui:audit` must report 0 errors for touched files.
+
+Full app-developer rules: [ui-standardization.md](../../.claude/skills/frontend-design/rules/ui-standardization.md).
 
 ---
 
-## MUST RULES (review-blocking)
+## Golden ratio (φ ≈ 1.618)
 
-See [`README.md § MUST RULES`](README.md) and [`BRAND.md`](BRAND.md) for the full list.
-The short version:
+One token `--phi-unit` drives page/section/card spacing; micro control gaps use the
+4px grid. Density (`compact` | `default` | `comfortable`) retunes `--phi-unit` with
+control + table heights together.
 
-1. Import `@godxjp/ui/tailwind.css` (or `/tokens.css`) once at app entry.
-2. Never redefine `--primary`, `--foreground`, `--background`, or any base token in app code.
-3. Per-deployment brand-color overrides live under `[data-accent="<palette>"]` in a service `theme.css` (per cardinal rule 19 — `[data-tenant]` is removed).
-4. No `@mui/material`, `chakra-ui`, `antd`, or any other component library.
-5. All primitive needs → add to `@godxjp/ui` first, then consume.
-6. Shell (AppShell + Sidebar + Topbar) is one component set — no hand-rolled grids.
+| App API             | φ level             |
+| ------------------- | ------------------- |
+| `<Stack gap="md">`  | φ⁰ (default)        |
+| `<Stack gap="lg">`  | φ¹                  |
+| `<Stack gap="xl">`  | φ²                  |
+| Card shell / footer | base × φ / base ÷ φ |
 
 ---
 
-## Adoption tracker
-
-| Service | Status | Notes |
-|---|---|---|
-| `calendar-service/frontend` | adopted | Greenfield; compliant from first commit. |
-| `forge-service/frontend` | adopting (phase 1) | Reference implementation for migration pattern. |
-| `admin-platform/frontend` | partial | Omnify tokens overlap ~90%; full migration pending. |
-| `me-service/frontend` | adopting | Plan #31 R6 — active migration. |
-| `console-service/frontend` | adopting | Epic #1412; AppShell + tokens wired. |
-| `agent-service/frontend` | not started | Plan #21 G17. |
-| `knowledge-service/frontend` | not started | Plan #18 K-phase. |
-| `chat-service/frontend` | adopting | Plan #30 completion phase. |
+## Working on the framework
 
----
+```bash
+pnpm preview          # preview app → http://localhost:6008 (fixed port, kills stale)
+pnpm preview:build    # static build — the integration test for examples + docs
+pnpm docs:sync-primitives   # regenerate docs/primitives/**/*.md from source
+pnpm typecheck && pnpm audit && pnpm test
+```
 
-## Versioning
+→ **[docs/DEVELOPMENT.md](./docs/DEVELOPMENT.md)** is the contributor guideline (the
+boundary, the layers, how to add/extend a component, verification).
 
-`@godxjp/ui` follows [Semantic Versioning](https://semver.org/).
-Breaking changes require a cross-service audit + major bump.
-See [`CHANGELOG.md`](CHANGELOG.md) for the full history.
+## Docs index
 
-Source: `github.com/godx-jp/godxjp-ui` (Apache-2.0).
-The umbrella repo (`godx-jp/godx-admin`) pins this as a git submodule at `libs/ts/godxjp-ui/`.
+- [docs/DEVELOPMENT.md](./docs/DEVELOPMENT.md) — contributor guideline (start here to edit the package)
+- [docs/COMPONENTS.md](./docs/COMPONENTS.md) · [docs/TOKENS.md](./docs/TOKENS.md) · [docs/SPACING.md](./docs/SPACING.md)
+- [docs/PROPS-VOCABULARY.md](./docs/PROPS-VOCABULARY.md) · [docs/PROPS-REGISTRY.md](./docs/PROPS-REGISTRY.md)
+- [docs/DATETIME.md](./docs/DATETIME.md) · [docs/FORMS.md](./docs/FORMS.md) · [docs/TESTING.md](./docs/TESTING.md)
+- MCP: **godxjp-ui-mcp** (`.mcp.json`)

package/dist/app/index.d.ts

@@ -0,0 +1,140 @@
+import { h as AppLocale, j as AppTimeFormat, g as AppDateFormat, k as AppTimezone, i as AppRequestHeaders } from '../types-mvzYGrma.js';
+export { A as APP_DATE_FORMATS, a as APP_LOCALES, b as APP_REQUEST_HEADER_DATE_FORMAT, c as APP_REQUEST_HEADER_LOCALE, d as APP_REQUEST_HEADER_TIMEZONE, e as APP_REQUEST_HEADER_TIME_FORMAT, f as APP_TIME_FORMATS, l as AppTimezoneDefault, m as getDatePattern, n as getDateTimePattern, o as getTimePattern, p as isAppDateFormat, q as isAppTimeFormat } from '../types-mvzYGrma.js';
+import * as react_day_picker from 'react-day-picker';
+import * as date_fns from 'date-fns';
+import { Locale } from 'date-fns';
+import { vi } from 'react-day-picker/locale';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { a as AppProviderProp, A as AppContextValue } from '../app.prop-IobwLwaM.js';
+import { j as formatDate, a as FormatDateOptions } from '../format-date-ByyZoqI5.js';
+export { F as FormatDateKind, b as FormatDatetimeOptions, d as detectFormatDateKind, f as formatAppDate, c as formatAppDateLong, e as formatAppDateTime, g as formatAppRelative, h as formatAppTime, i as formatCalendarDate, k as formatTimeOfDay, m as isFormatDateValue } from '../format-date-ByyZoqI5.js';
+export { getDatetimeContext, isValidHhmm, normalizeHhmm, parseDateInput, syncDatetimeContext } from '../lib/datetime/index.js';
+export { usePickerLocales, useTranslation } from '../i18n/index.js';
+import '../shared.prop-BNRJc9K0.js';
+import 'react';
+import '@date-fns/tz';
+
+type AppLocaleConfig = {
+    code: AppLocale;
+    dateFns: Locale;
+    dayPicker: typeof vi;
+};
+declare const APP_LOCALE_CONFIG: Record<AppLocale, AppLocaleConfig>;
+declare function isAppLocale(value: string | null | undefined): value is AppLocale;
+declare function getDateFnsLocale(locale: AppLocale): Locale;
+declare function getDayPickerLocale(locale: AppLocale): react_day_picker.DayPickerLocale;
+
+/** Curated preset — pass to `<AppProvider timezoneOptions={APP_TIMEZONE_PRESET} />`. */
+declare const APP_TIMEZONE_PRESET: readonly ["UTC", "Asia/Ho_Chi_Minh", "Asia/Bangkok", "Asia/Singapore", "Asia/Jakarta", "Asia/Manila", "Asia/Kuala_Lumpur", "Asia/Yangon", "Asia/Phnom_Penh", "Asia/Vientiane", "Asia/Brunei", "Asia/Tokyo", "Asia/Seoul", "Asia/Shanghai", "Asia/Hong_Kong", "Asia/Taipei", "Asia/Ulaanbaatar", "Asia/Kolkata", "Asia/Karachi", "Asia/Dhaka", "Asia/Colombo", "Asia/Dubai", "Asia/Riyadh", "Asia/Qatar", "Asia/Tehran", "Asia/Jerusalem", "Europe/London", "Europe/Paris", "Europe/Berlin", "Europe/Amsterdam", "Europe/Rome", "Europe/Madrid", "Europe/Moscow", "Europe/Istanbul", "America/New_York", "America/Chicago", "America/Denver", "America/Los_Angeles", "America/Toronto", "America/Vancouver", "America/Mexico_City", "America/Sao_Paulo", "America/Buenos_Aires", "Australia/Sydney", "Australia/Melbourne", "Australia/Perth", "Pacific/Auckland"];
+/** @deprecated Use `APP_TIMEZONE_PRESET` or `getAllIanaTimezones()`. */
+declare const APP_TIMEZONE_OPTIONS: readonly ["UTC", "Asia/Ho_Chi_Minh", "Asia/Bangkok", "Asia/Singapore", "Asia/Jakarta", "Asia/Manila", "Asia/Kuala_Lumpur", "Asia/Yangon", "Asia/Phnom_Penh", "Asia/Vientiane", "Asia/Brunei", "Asia/Tokyo", "Asia/Seoul", "Asia/Shanghai", "Asia/Hong_Kong", "Asia/Taipei", "Asia/Ulaanbaatar", "Asia/Kolkata", "Asia/Karachi", "Asia/Dhaka", "Asia/Colombo", "Asia/Dubai", "Asia/Riyadh", "Asia/Qatar", "Asia/Tehran", "Asia/Jerusalem", "Europe/London", "Europe/Paris", "Europe/Berlin", "Europe/Amsterdam", "Europe/Rome", "Europe/Madrid", "Europe/Moscow", "Europe/Istanbul", "America/New_York", "America/Chicago", "America/Denver", "America/Los_Angeles", "America/Toronto", "America/Vancouver", "America/Mexico_City", "America/Sao_Paulo", "America/Buenos_Aires", "Australia/Sydney", "Australia/Melbourne", "Australia/Perth", "Pacific/Auckland"];
+type AppTimezonePreset = (typeof APP_TIMEZONE_PRESET)[number];
+/**
+ * Preferred IANA ids not returned by all runtimes (e.g. Node lists `Asia/Saigon` only).
+ * Keys are app-facing ids; values are Intl-canonical ids for offset lookup.
+ */
+declare const TIMEZONE_ALIASES: Record<string, string>;
+/** Map app id → Intl id for `DateTimeFormat` / validation. */
+declare function resolveTimezoneForIntl(timezone: string): string;
+/** Full IANA list from runtime — sorted lexicographically. */
+declare function getAllIanaTimezones(): readonly string[];
+declare function isValidIanaTimezone(value: string): boolean;
+/** @deprecated Use `isValidIanaTimezone`. */
+declare function isKnownAppTimezone(value: string): value is AppTimezonePreset;
+/**
+ * Options for TimezonePicker.
+ * - `configured` omitted/empty → full IANA list
+ * - `configured` set → only those ids (+ `current` if missing)
+ */
+declare function resolveTimezonePickerOptions(configured?: readonly string[] | null, current?: string): readonly string[];
+declare function getBrowserTimezone(): string;
+/** City/region segment from IANA id — `Asia/Ho_Chi_Minh` → `Ho Chi Minh`. */
+declare function getTimezoneCityName(timezone: string): string;
+/** UTC/GMT offset via Intl — e.g. `GMT+7`, `UTC`. */
+declare function getTimezoneOffsetLabel(timezone: string, locale?: AppLocale): string;
+/** Intl fallback when no i18n override — `Ho Chi Minh (GMT+7)`. */
+declare function formatTimezoneDisplayLabel(timezone: string, locale?: AppLocale): string;
+declare function getTimezoneLabel(timezone: string, locale: AppLocale, fallbackLocale?: AppLocale): string;
+declare function resolveDefaultTimezone(defaultTimezone: "browser" | "system" | (string & {}), systemTimezone?: string): string;
+/** Vitest only — reset cached IANA list between cases. */
+declare function resetIanaTimezoneCacheForTests(): void;
+
+declare const APP_TIME_FORMAT_OPTIONS: {
+    value: "24h" | "12h";
+}[];
+declare function getTimeFormatLabel(timeFormat: AppTimeFormat, locale: AppLocale, fallbackLocale?: AppLocale): string;
+/** Suggested default per locale — vi/ja → 24h, en → 12h. */
+declare function resolveDefaultTimeFormat(locale: AppLocale): AppTimeFormat;
+
+declare const APP_DATE_FORMAT_OPTIONS: {
+    value: "iso" | "dmy" | "mdy";
+}[];
+declare function getDateFormatLabel(dateFormat: AppDateFormat, locale: AppLocale, fallbackLocale?: AppLocale): string;
+/** Suggested default per locale — vi → dmy, ja → iso, en → mdy. */
+declare function resolveDefaultDateFormat(locale: AppLocale): AppDateFormat;
+
+declare const DEFAULT_STORAGE_KEY = "godxjp.app";
+type StoredAppPreferences = {
+    locale?: AppLocale;
+    timezone?: AppTimezone;
+    timeFormat?: AppTimeFormat;
+    dateFormat?: AppDateFormat;
+};
+declare function readStoredPreferences(storageKey: string): StoredAppPreferences;
+declare function writeStoredPreferences(storageKey: string, preferences: StoredAppPreferences): void;
+
+/** Sync locale/timezone into module state for HTTP clients (via `getAppRequestHeaders`). */
+declare function syncAppRequestHeaders(headers: Partial<AppRequestHeaders>): void;
+/** Read current app preference headers — wire to API client `setAppHeaderProvider`. */
+declare function getAppRequestHeaders(): AppRequestHeaders;
+/** Reset to defaults — for tests only. */
+declare function resetAppRequestHeaders(): void;
+
+declare function AppProvider({ children, defaultLocale, fallbackLocale, defaultTimezone, systemTimezone, defaultTimeFormat, defaultDateFormat, timezoneOptions, storageKey, persist, onLocaleChange, onTimezoneChange, onTimeFormatChange, onDateFormatChange, }: AppProviderProp): react_jsx_runtime.JSX.Element;
+declare function useAppContext(): AppContextValue;
+/** Returns null outside AppProvider — used by pickers for optional context. */
+declare function useOptionalAppContext(): AppContextValue | null;
+/** Shorthand for `{ locale, setLocale }`. */
+declare function useAppLocale(): {
+    locale: AppLocale;
+    fallbackLocale: AppLocale;
+    setLocale: (locale: AppLocale) => void;
+    dateFnsLocale: date_fns.Locale;
+    dayPickerLocale: Partial<react_day_picker.DayPickerLocale>;
+};
+/** Shorthand for `{ timezone, setTimezone }`. */
+declare function useAppTimezone(): {
+    timezone: string;
+    setTimezone: (timezone: AppTimezone) => void;
+};
+/** Shorthand for `{ timeFormat, setTimeFormat }`. */
+declare function useAppTimeFormat(): {
+    timeFormat: AppTimeFormat;
+    setTimeFormat: (timeFormat: AppTimeFormat) => void;
+};
+/** Shorthand for `{ dateFormat, setDateFormat }`. */
+declare function useAppDateFormat(): {
+    dateFormat: AppDateFormat;
+    setDateFormat: (dateFormat: AppDateFormat) => void;
+};
+
+/** Date/time formatters bound to the current AppProvider preferences. */
+declare function useFormatting(): {
+    locale: AppLocale;
+    timezone: string;
+    timeFormat: AppTimeFormat;
+    dateFormat: AppDateFormat;
+    /** Primary formatter — auto-detect + AppProvider defaults. */
+    format: (value: Parameters<typeof formatDate>[0], options?: FormatDateOptions) => string;
+    formatDate: (value: Parameters<typeof formatDate>[0], options?: FormatDateOptions) => string;
+    formatCalendarDate: (value: Date | null | undefined, options?: FormatDateOptions) => string;
+    formatTime: (value: Parameters<typeof formatDate>[0], options?: FormatDateOptions) => string;
+    formatDateTime: (value: Parameters<typeof formatDate>[0], options?: FormatDateOptions) => string;
+    formatDateLong: (value: Parameters<typeof formatDate>[0], options?: FormatDateOptions) => string;
+    formatRelative: (value: Parameters<typeof formatDate>[0], options?: FormatDateOptions) => string;
+    formatTimeOfDay: (value: Parameters<typeof formatDate>[0], options?: FormatDateOptions) => string;
+};
+/** Alias for useFormatting — emphasises timezone-aware datetime helpers. */
+declare const useDateTime: typeof useFormatting;
+
+export { APP_DATE_FORMAT_OPTIONS, APP_LOCALE_CONFIG, APP_TIMEZONE_OPTIONS, APP_TIMEZONE_PRESET, APP_TIME_FORMAT_OPTIONS, AppDateFormat, AppLocale, type AppLocaleConfig, AppProvider, AppRequestHeaders, AppTimeFormat, AppTimezone, type AppTimezonePreset, DEFAULT_STORAGE_KEY, FormatDateOptions, type StoredAppPreferences, TIMEZONE_ALIASES, formatDate, formatTimezoneDisplayLabel, getAllIanaTimezones, getAppRequestHeaders, getBrowserTimezone, getDateFnsLocale, getDateFormatLabel, getDayPickerLocale, getTimeFormatLabel, getTimezoneCityName, getTimezoneLabel, getTimezoneOffsetLabel, isAppLocale, isKnownAppTimezone, isValidIanaTimezone, readStoredPreferences, resetAppRequestHeaders, resetIanaTimezoneCacheForTests, resolveDefaultDateFormat, resolveDefaultTimeFormat, resolveDefaultTimezone, resolveTimezoneForIntl, resolveTimezonePickerOptions, syncAppRequestHeaders, useAppContext, useAppDateFormat, useAppLocale, useAppTimeFormat, useAppTimezone, useDateTime, useFormatting, useOptionalAppContext, writeStoredPreferences };

package/dist/app/index.js

@@ -0,0 +1,38 @@
+import { useAppContext } from '../chunk-3F2AKYRD.js';
+export { APP_LOCALES, APP_REQUEST_HEADER_LOCALE, APP_REQUEST_HEADER_TIMEZONE, APP_TIMEZONE_OPTIONS, APP_TIMEZONE_PRESET, APP_TIME_FORMAT_OPTIONS, AppProvider, DEFAULT_STORAGE_KEY, TIMEZONE_ALIASES, formatTimezoneDisplayLabel, getAllIanaTimezones, getAppRequestHeaders, getBrowserTimezone, getTimeFormatLabel, getTimezoneCityName, getTimezoneLabel, getTimezoneOffsetLabel, isKnownAppTimezone, isValidIanaTimezone, readStoredPreferences, resetAppRequestHeaders, resetIanaTimezoneCacheForTests, resolveDefaultTimeFormat, resolveDefaultTimezone, resolveTimezoneForIntl, resolveTimezonePickerOptions, syncAppRequestHeaders, useAppContext, useAppDateFormat, useAppLocale, useAppTimeFormat, useAppTimezone, useOptionalAppContext, usePickerLocales, useTranslation, writeStoredPreferences } from '../chunk-3F2AKYRD.js';
+import { formatDate } from '../chunk-YFCQKO3B.js';
+export { APP_DATE_FORMATS, APP_DATE_FORMAT_OPTIONS, APP_LOCALE_CONFIG, APP_REQUEST_HEADER_DATE_FORMAT, APP_REQUEST_HEADER_TIME_FORMAT, APP_TIME_FORMATS, detectFormatDateKind, formatAppDate, formatAppDateLong, formatAppDateTime, formatAppRelative, formatAppTime, formatCalendarDate, formatDate, formatTimeOfDay, getDateFnsLocale, getDateFormatLabel, getDatePattern, getDateTimePattern, getDatetimeContext, getDayPickerLocale, getTimePattern, isAppDateFormat, isAppLocale, isAppTimeFormat, isFormatDateValue, isValidHhmm, normalizeHhmm, parseDateInput, resolveDefaultDateFormat, syncDatetimeContext } from '../chunk-YFCQKO3B.js';
+import { useMemo } from 'react';
+
+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, options) => formatDate(value, { ...defaults, ...options }),
+    [defaults]
+  );
+  return useMemo(
+    () => ({
+      locale,
+      timezone,
+      timeFormat,
+      dateFormat,
+      /** Primary formatter — auto-detect + AppProvider defaults. */
+      format: bind,
+      formatDate: bind,
+      formatCalendarDate: (value, options) => formatDate(value, { ...defaults, ...options, kind: "calendar" }),
+      formatTime: (value, options) => formatDate(value, { ...defaults, ...options, kind: "time" }),
+      formatDateTime: (value, options) => formatDate(value, { ...defaults, ...options, kind: "datetime" }),
+      formatDateLong: (value, options) => formatDate(value, { ...defaults, ...options, kind: "long" }),
+      formatRelative: (value, options) => formatDate(value, { ...defaults, ...options, kind: "relative" }),
+      formatTimeOfDay: (value, options) => formatDate(value, { ...defaults, ...options, kind: "time" })
+    }),
+    [locale, timezone, timeFormat, dateFormat, defaults, bind]
+  );
+}
+var useDateTime = useFormatting;
+
+export { useDateTime, useFormatting };

package/dist/app.prop-IobwLwaM.d.ts

@@ -0,0 +1,90 @@
+import { Locale } from 'date-fns';
+import { DayPickerProps } from 'react-day-picker';
+import { h as AppLocale, l as AppTimezoneDefault, k as AppTimezone, j as AppTimeFormat, g as AppDateFormat, i as AppRequestHeaders } from './types-mvzYGrma.js';
+import { C as ChildrenProp, a as ClassNameProp, D as DisabledProp, I as IdProp } from './shared.prop-BNRJc9K0.js';
+
+/** App shell prop types — @see docs/COMPONENTS.md#app */
+
+/** @see AppProvider */
+type AppProviderProp = {
+    children: ChildrenProp;
+    /** Initial locale when nothing in storage. Default: `vi`. */
+    defaultLocale?: AppLocale;
+    /** Fallback when a translation key is missing. Default: `en`. */
+    fallbackLocale?: AppLocale;
+    /** Initial timezone: IANA id, `browser`, or `system`. Default: `browser`. */
+    defaultTimezone?: AppTimezoneDefault;
+    /** Backend/system timezone when `defaultTimezone` is `system`. */
+    systemTimezone?: AppTimezone;
+    /** Initial clock format. `"locale"` derives from `defaultLocale`. Default: `"locale"`. */
+    defaultTimeFormat?: AppTimeFormat | "locale";
+    /** Initial date display format. `"locale"` derives from `defaultLocale`. Default: `"locale"`. */
+    defaultDateFormat?: AppDateFormat | "locale";
+    /**
+     * IANA ids shown in `TimezonePicker`.
+     * Omit for the full IANA list; set to restrict (e.g. `APP_TIMEZONE_PRESET`).
+     */
+    timezoneOptions?: readonly AppTimezone[];
+    /** localStorage key. Default: `godxjp.app`. */
+    storageKey?: string;
+    /** Persist user choices. Default: true. */
+    persist?: boolean;
+    onLocaleChange?: (locale: AppLocale) => void;
+    onTimezoneChange?: (timezone: AppTimezone) => void;
+    onTimeFormatChange?: (timeFormat: AppTimeFormat) => void;
+    onDateFormatChange?: (dateFormat: AppDateFormat) => void;
+};
+/** @see LocalePicker */
+type LocalePickerProp = {
+    className?: ClassNameProp;
+    disabled?: DisabledProp;
+    id?: IdProp;
+    /** Controlled value; default reads/writes AppProvider. */
+    value?: AppLocale;
+    onChange?: (locale: AppLocale) => void;
+};
+/** @see TimezonePicker */
+type TimezonePickerProp = {
+    className?: ClassNameProp;
+    disabled?: DisabledProp;
+    id?: IdProp;
+    value?: AppTimezone;
+    onChange?: (timezone: AppTimezone) => void;
+    /** Override AppProvider list; omit to use context or full IANA. */
+    options?: readonly AppTimezone[];
+};
+/** @see TimeFormatPicker */
+type TimeFormatPickerProp = {
+    className?: ClassNameProp;
+    disabled?: DisabledProp;
+    id?: IdProp;
+    value?: AppTimeFormat;
+    onChange?: (timeFormat: AppTimeFormat) => void;
+};
+/** @see DateFormatPicker */
+type DateFormatPickerProp = {
+    className?: ClassNameProp;
+    disabled?: DisabledProp;
+    id?: IdProp;
+    value?: AppDateFormat;
+    onChange?: (dateFormat: AppDateFormat) => void;
+};
+/** Value exposed by `useAppContext`. */
+type AppContextValue = {
+    locale: AppLocale;
+    fallbackLocale: AppLocale;
+    timezone: AppTimezone;
+    timeFormat: AppTimeFormat;
+    dateFormat: AppDateFormat;
+    dateFnsLocale: Locale;
+    dayPickerLocale: NonNullable<DayPickerProps["locale"]>;
+    requestHeaders: AppRequestHeaders;
+    /** Configured picker list; `undefined` → full IANA in TimezonePicker. */
+    timezoneOptions?: readonly AppTimezone[];
+    setLocale: (locale: AppLocale) => void;
+    setTimezone: (timezone: AppTimezone) => void;
+    setTimeFormat: (timeFormat: AppTimeFormat) => void;
+    setDateFormat: (dateFormat: AppDateFormat) => void;
+};
+
+export type { AppContextValue as A, DateFormatPickerProp as D, LocalePickerProp as L, TimeFormatPickerProp as T, AppProviderProp as a, TimezonePickerProp as b };

package/dist/checkbox-NkFkqsQ8.d.ts

@@ -0,0 +1,13 @@
+import * as React from 'react';
+import * as CheckboxPrimitive from '@radix-ui/react-checkbox';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { c as CheckboxGroupProp } from './data-entry.prop-BEGA1lTq.js';
+
+declare function CheckboxGroup({ value: controlledValue, defaultValue, onChange, options, orientation, disabled, name, className, children, }: CheckboxGroupProp): react_jsx_runtime.JSX.Element;
+
+/** Checkbox — dùng standalone hoặc `Checkbox.Group` với `options` (Ant Design style). */
+declare const Checkbox: React.ForwardRefExoticComponent<Omit<CheckboxPrimitive.CheckboxProps & React.RefAttributes<HTMLButtonElement>, "ref"> & React.RefAttributes<HTMLButtonElement>> & {
+    Group: typeof CheckboxGroup;
+};
+
+export { Checkbox as C, CheckboxGroup as a };