@godxjp/ui 31.31.8 → 32.0.0

package/docs/PROPS-VOCABULARY.md

@@ -1,100 +0,0 @@
-# Props Vocabulary
-
-Atomic prop types live in `src/props/vocabulary/`. Every type name ends with **`Prop`**.
-
-Import: `import type { TitleProp, GapProp } from "@godxjp/ui/props/vocabulary"`
-
----
-
-## Shared
-
-| Type               | Value                         | Used for                  |
-| ------------------ | ----------------------------- | ------------------------- |
-| `ClassNameProp`    | `string`                      | Root class override       |
-| `ChildrenProp`     | `ReactNode`                   | Child slot                |
-| `IdProp`           | `string`                      | DOM / form id             |
-| `OpenProp`         | `boolean`                     | Dialog/Sheet/Popover open |
-| `OnOpenChangeProp` | `(open: boolean) => void`     | Panel open state change   |
-| `HandlerProp`      | `() => void \| Promise<void>` | Confirm / retry callbacks |
-| `PendingProp`      | `boolean`                     | Loading / in-flight       |
-| `RequiredProp`     | `boolean`                     | Required field            |
-| `DisabledProp`     | `boolean`                     | Disabled control          |
-| `LabelProp`        | `ReactNode`                   | Generic label             |
-| `HelperProp`       | `ReactNode`                   | Input hint text           |
-| `ErrorProp`        | `ReactNode`                   | Validation error          |
-| `PlaceholderProp`  | `string`                      | Input placeholder         |
-| `AsChildProp`      | `boolean`                     | Radix polymorphism        |
-
-## Content slots
-
-| Type               | Semantics                            | Do NOT confuse with |
-| ------------------ | ------------------------------------ | ------------------- |
-| `TitleProp`        | Primary heading                      | —                   |
-| `SubtitleProp`     | Line under title on **pages**        | `DescriptionProp`   |
-| `DescriptionProp`  | Body copy in dialogs / empty states  | `SubtitleProp`      |
-| `ExtraProp`        | Top-right page actions (Ant `extra`) | `ActionsProp`       |
-| `FooterProp`       | Bottom page action bar               | —                   |
-| `ActionProp`       | Empty state CTA                      | `ExtraProp`         |
-| `ActionsProp`      | Toolbar button group                 | `ExtraProp`         |
-| `IconProp`         | `LucideIcon` component               | —                   |
-| `ConfirmLabelProp` | Dialog confirm button text           | —                   |
-| `CancelLabelProp`  | Dialog cancel button text            | —                   |
-
-## Layout & density
-
-| Type               | Values                              | Scope                                                          |
-| ------------------ | ----------------------------------- | -------------------------------------------------------------- |
-| `PageDensityProp`  | `compact \| default \| comfortable` | **PageContainer** subtree                                      |
-| `GapProp`          | `xs \| sm \| md \| lg \| xl`        | `<Flex gap>` (row) and `<Flex direction="col" gap>` (vertical) |
-| `TableDensityProp` | `compact \| comfortable`            | **DataTable** rows only                                        |
-
-> **Critical:** `PageDensityProp` ≠ `TableDensityProp`. Never use bare `density` in new APIs.
-
-## Interaction variants
-
-| Type                 | Values                                                                     |
-| -------------------- | -------------------------------------------------------------------------- |
-| `ButtonVariantProp`  | `default \| destructive \| outline \| secondary \| ghost \| link`          |
-| `ButtonSizeProp`     | `default \| sm \| lg \| icon`                                              |
-| `ConfirmVariantProp` | `default \| destructive`                                                   |
-| `ToneProp`           | `default \| success \| warning \| destructive \| info \| muted \| neutral` |
-| `SortDirectionProp`  | `asc \| desc`                                                              |
-| `ColumnAlignProp`    | `left \| center \| right`                                                  |
-| `SortStateProp`      | `{ key: string; direction: SortDirectionProp }`                            |
-
-## Navigation
-
-| Type                 | Shape                               |
-| -------------------- | ----------------------------------- |
-| `BreadcrumbItemProp` | `{ label: LabelProp; to?: string }` |
-| `BreadcrumbProp`     | `BreadcrumbItemProp[]`              |
-| `TitleProp`          | primary heading text                |
-
-## Data collections
-
-| Type                       | Purpose                 |
-| -------------------------- | ----------------------- |
-| `ColumnDefProp<T>`         | DataTable column        |
-| `GetRowIdProp<T>`          | Row ID extractor        |
-| `OnRowClickProp<T>`        | Row navigation          |
-| `SelectedIdsProp`          | `Set<string>` selection |
-| `OnSelectChangeProp`       | Selection handler       |
-| `OnTableDensityChangeProp` | Table density handler   |
-| `OnSortChangeProp`         | Sort handler            |
-| `OnSearchChangeProp`       | Debounced search        |
-| `OnClearFiltersProp`       | Toolbar clear           |
-| `HasActiveFiltersProp`     | Show clear button       |
-
-## Forbidden aliases
-
-See `PROP_ALIASES_FORBIDDEN` in `@godxjp/ui/props/registry`:
-
-| Don't use                     | Use instead                                        |
-| ----------------------------- | -------------------------------------------------- |
-| bare `description` on pages   | `SubtitleProp`                                     |
-| bare `description` in dialogs | `DescriptionProp`                                  |
-| `actions` on page header      | `ExtraProp`                                        |
-| bare `density`                | `PageDensityProp` or `TableDensityProp`            |
-| component-specific gap unions | `GapProp` or documented `Extract`/`Exclude` subset |
-| `onClear`                     | `OnClearFiltersProp`                               |
-| `loading` on buttons          | `PendingProp`                                      |

package/docs/REGISTRY.md

@@ -1,70 +0,0 @@
-# Consuming @godxjp/ui through the shadcn registry
-
-## What is published, and what is not
-
-`@godxjp/ui` ships as an **npm package**. The components are imported, not copied:
-
-```ts
-import { DataTable, Cascader } from "@godxjp/ui/data-display";
-```
-
-The registry does **not** publish those components, and that is deliberate. A shadcn registry is a copy-paste channel — `shadcn add` writes files into your tree and you own them from then on. Copying 165 components would fork your copy from the package: you would stop receiving token fixes, a11y fixes and the guard discipline the library is built on, while carrying ~73k lines you did not write.
-
-What the registry publishes is the part the package cannot hand you on its own: **the design language**.
-
-| Item             | Type             | What you get                                                                   |
-| ---------------- | ---------------- | ------------------------------------------------------------------------------ |
-| `@godxjp/theme`  | `registry:theme` | The full token system — foundation scales, semantic roles, per-component knobs |
-| `@godxjp/styles` | `registry:style` | The stylesheets those tokens drive (only if you adopt godxjp markup too)       |
-
-`docs/showcase/acme-portal.tsx` is the proof this is the valuable half: an entire brand — gold and navy, Source Sans 3, a 14px radius, navy-tinted shadows — reproduced by **configuring tokens alone**, with no component edits and no new components.
-
-## Setup
-
-Add the namespace to your own `components.json`:
-
-```json
-{
-  "registries": {
-    "@godxjp": "https://godx-jp.github.io/godxjp-ui/registry/{name}.json"
-  }
-}
-```
-
-Then:
-
-```bash
-npx shadcn add @godxjp/theme
-```
-
-and import the token entry before your own overrides:
-
-```css
-@import "./styles/tokens/base.css";
-```
-
-## Re-theming
-
-Override roles at `:root`, or scope them per tenant:
-
-```css
-[data-tenant="acme"] {
-  --primary: 41 71% 53%;
-  --radius: 0.875rem;
-  --font-family-sans: "Source Sans 3", system-ui, sans-serif;
-}
-```
-
-Two rules the token system holds to, worth knowing before you override:
-
-This is what lets a scoped `[data-tenant]` or `.dark` override actually reach a portaled overlay. See `docs/TOKENS.md`.
-
-## Why not the components?
-
-If you want the components, install the package — that is the supported path and the one every guard, test and token in this repo is built around:
-
-```bash
-pnpm add @godxjp/ui
-```
-
-The registry exists for teams who already have their own shadcn components and want the godxjp design language on top of them.

package/docs/TESTING.md

@@ -1,107 +0,0 @@
-# Testing @godxjp/ui
-
-Every component **must** ship with a Vitest suite before merge.
-
-## Run
-
-```bash
-# While working — ONLY the tests for what you touched. Tests sit beside the
-# component in `src/components/<group>/__tests__/`, so scope to that folder.
-pnpm vitest run src/components/<group>/__tests__ --maxWorkers=2
-pnpm vitest watch src/components/<group>/__tests__     # watch one component
-
-# CI only — 506 files / 3700+ tests. Do NOT run these from an agent loop or with
-# other agents on the machine: measured 70 vitest workers at load 90, an overheating
-# laptop and a burnt monthly API budget.
-pnpm test              # single run — CI
-pnpm test:coverage     # v8 coverage report — CI
-```
-
-## File location
-
-Co-locate tests next to components:
-
-```
-src/components/layout/page-container.tsx
-src/components/layout/__tests__/page-container.test.tsx
-src/form/use-zod-form.ts
-src/form/__tests__/use-zod-form.test.tsx
-```
-
-## Required coverage per component
-
-Each `*.test.tsx` must include:
-
-1. **Render** — component mounts without throw
-2. **Props** — key prop variations (variants, sizes, density, slots)
-3. **Interaction** — userEvent for clicks, typing, keyboard where applicable
-4. **A11y** — roles, labels, aria-\* attributes for form controls
-5. **Edge cases** — empty, error, loading, disabled states
-
-## Test utilities
-
-```tsx
-import { renderWithUi, screen, userEvent } from "@/test/render";
-```
-
-`renderWithUi` wraps `MemoryRouter` + `React.StrictMode` + **`RenderLoopGuard`** (fails fast on infinite re-render loops, default max 25 renders).
-
-```tsx
-// Optional: disable guard for stress tests
-renderWithUi(<HeavyChart />, { loopGuard: false });
-
-// Custom threshold
-renderWithUi(<Widget />, { loopGuard: { maxRenders: 40, label: "Widget" } });
-```
-
-Shared guard lives in `@godxjp/tooling/test` — apps import the same helper.
-
-Vitest setup (apps):
-
-```ts
-// vitest.setup.ts
-import "@godxjp/tooling/test/vitest.setup.react";
-import "@testing-library/jest-dom/vitest";
-```
-
-`testTimeout: 8000` — hung tests fail before blocking CI.
-
-## Render loop prevention (ESLint + test)
-
-| Layer                             | Catches                          |
-| --------------------------------- | -------------------------------- |
-| `react-hooks/exhaustive-deps`     | missing/unstable effect deps     |
-| `react-hooks/set-state-in-effect` | sync setState in effects         |
-| `RenderLoopGuard` in tests        | runaway re-renders during Vitest |
-
-Run `pnpm lint` before your scoped test run — official React Compiler rules align with test guard.
-
-## Forms testing
-
-Form integration tests **must** use Zod 4 schemas:
-
-```tsx
-const schema = z.object({ email: z.string().email() });
-const form = useZodForm(schema);
-```
-
-Never test forms with raw `useState` — mirror production `FormRoot` + `FormFieldControl`.
-
-## CI gate
-
-The full suite must pass with zero failures before any UI PR merges — **and that run belongs
-to CI, not to you.** Locally you run only the tests for the files you changed; CI runs
-everything on the PR. `tal --help` states the same rule for the agent loop: *FULL SUITE KHÔNG
-THUỘC VỀ VÒNG LẶP.*
-
-## When tests fail
-
-Guard suites and fix playbooks:
-
-| Suite                    | File                                                          |
-| ------------------------ | ------------------------------------------------------------- |
-| Theme token audit        | `src/lib/__tests__/theme-tokens-audit.test.ts`                |
-| Theme axes integration   | `src/components/__tests__/theme-axes-integration.test.tsx`    |
-| formatDate / AppProvider | `src/lib/__tests__/format-date.test.ts`, `src/app/__tests__/` |
-
-**Full failure routing:** MCP tool `godxjp_ui_guide` topic=`testing-troubleshooting` or `godxjp_ui_verify` with `failureHint` from CI log (see `tools/godxjp-ui-mcp/`).