@nxgt/material 1.0.0 → 1.0.1

package/README.md

@@ -8,6 +8,52 @@ Built with Tailwind CSS v4 and Base UI. Consumers read `dist/`.
 
 ---
 
+## Install
+
+```bash
+bun add @nxgt/material
+```
+
+Public on npmjs; no token needed to install.
+
+**Required peers** — the app must resolve the same copy as this package, or
+hooks throw and design tokens come from two builds:
+
+| Peer | Why |
+| --- | --- |
+| `react`, `react-dom` | `^19.2.8` |
+| `react-hook-form` | `^7.85.0` — every `*FormField` |
+| `react-redux`, `@reduxjs/toolkit` | `DataTable`, filter, gallery, kanban, player |
+| `@tanstack/react-table` | `^9` — `DataTable` |
+| `react-use` | assorted hooks |
+
+There is **no `postinstall` build**. The package publishes `dist/` and not
+`lib/`, so a build triggered on a consumer's machine would have no sources to
+compile and would fail the install outright under npm. Build here, then
+publish.
+
+---
+
+## Subpaths
+
+| Specifier | What is in it |
+| --- | --- |
+| `@nxgt/material` | the default barrel: components, hooks, i18n, lib, models, types, and the compiled `style` condition `dist/material.css` |
+| `@nxgt/material/components` | every UI component, including `*FormField` wrappers |
+| `@nxgt/material/hooks` | `useTheme`, `useIsClient`, `useMobile`, `useSearchParam`, … |
+| `@nxgt/material/dnd` | `@dnd-kit` primitives re-exported for sortable lists and kanban |
+| `@nxgt/material/i18n` | `I18nProvider`, `mergeResources`, `createTranslator`, the reserved `material` namespace |
+| `@nxgt/material/models` | shared status types |
+| `@nxgt/material/lib` | `cn`, `clientOnly`, date/number/upload helpers, the redux `useSliceReducer` |
+| `@nxgt/material/types` | shared function types |
+| `@nxgt/material/styles.css` | **source** Tailwind v4 `@theme` tokens — this is the stylesheet apps import |
+
+The compiled stylesheet at `@nxgt/material` (the package's `style` condition,
+`dist/material.css`) is not what our apps import; they take the tokens and let
+their own Tailwind build produce the utilities.
+
+---
+
 ## Consuming it
 
 Three things have to be in place. Two are CSS, and the third is the one people
@@ -15,7 +61,7 @@ forget: **the icon sprites are yours to supply.**
 
 ### 1. Install
 
-```jsonc
+```json
 // package.json
 "dependencies": {
   "@nxgt/material": "…"
@@ -37,10 +83,10 @@ this order:
 
 - **`@import "@nxgt/material/styles.css"`** brings in the design tokens: the
   `oklch` colour scale, `--radius`, the `dark` custom variant, the font stacks.
-  It is `lib/styles.css` shipped verbatim rather than compiled, because Tailwind
-  v4 wants the source `@theme` layer to run through *your* Tailwind build.
+  It is `lib/styles.css` shipped raw rather than compiled, because Tailwind
+  v4 needs the source `@theme` layer to run through *your* Tailwind build.
 - **`@source "../node_modules/@nxgt/material/"`** is not optional and its
-  absence does not error. Tailwind v4 generates only the utilities it can see in
+  absence does not error. Tailwind v4 generates only the classes it can see in
   the files it scans, and by default it does not scan inside `node_modules`.
   Without this line, every utility class used *inside* a `@nxgt/material`
   component is absent from the output and the components render unstyled — a
@@ -70,7 +116,6 @@ public/assets/icons/sprites/<style>.svg
 covers using the icons in your own products, not redistributing them inside a
 library. A published `@nxgt/material` tarball that contained them would be
 redistribution regardless of whether this repository is private.
-
 `files` therefore carries an explicit `"!dist/assets"`, so a stale local build
 cannot leak them back into a tarball by accident.
 
@@ -83,11 +128,135 @@ Each consuming app therefore commits its own sprites into
 `public/assets/icons/sprites/`, taken from its own Font Awesome Pro kit. The styles in use across the parc are
 the 37 sheets covering `regular`, `light`, `thin`, `solid`, `duotone`,
 `sharp-*`, `brands` and the expressive families (`chisel`, `etch`, `jelly`,
-`notdog`, `slab-press`, …). An icon whose sheet is missing renders as nothing —
+`slickdog`, `slab-press`, …). An icon whose sheet is missing renders as nothing —
 no error, no fallback.
 
 ---
 
+## i18n
+
+`@nxgt/material` owns the i18n **mechanism** (`@nxgt/material/i18n`); consuming
+apps own their resource **content**.
+
+This package ships a base resource bundle and reserves exactly **one
+top-level namespace per language: `material`**. `mergeResources` is a
+*shallow*, per-language merge, so an app-side `material` namespace **silently
+shadows every string this package ships**. Collisions are reported through
+`console.warn` outside production.
+
+```ts
+// app/i18n/index.ts
+import {
+  createTranslator,
+  createTypedTranslation,
+  mergeResources,
+  resources as materialResources,
+  type FlatObject,
+} from '@nxgt/material/i18n';
+import { resources as appResources } from './resources';
+
+export const resources = mergeResources(materialResources, appResources);
+export type LocaleKey = keyof FlatObject<typeof resources.en, string>;
+
+export const translate = createTranslator<LocaleKey>(resources);
+export const useTranslation = createTypedTranslation<LocaleKey>(translate);
+```
+
+```tsx
+// app root — mount once, above everything that translates
+<I18nProvider defaultLanguage="en">
+  <App />
+</I18nProvider>
+```
+
+Language state lives **only** in `I18nProvider`. Never re-introduce a
+per-call-site `useState` / `useLocalStorage` for language — that is the bug
+that forced `window.location.reload()` in language switchers.
+
+Components inside this package use `useOptionalI18nContext()` /
+`useMaterialTranslation()` and always pass their historical English copy as
+the fallback, so they keep rendering in apps that have not mounted
+`I18nProvider` yet. Messages are ICU MessageFormat; a missing key is returned
+verbatim rather than throwing.
+
+New user-facing strings in this package go into **both** `en/material.json`
+and `fr/material.json`, under `material.<component>.*`. Consuming apps must
+never declare a top-level `material` key in their own resources.
+
+---
+
+## The app shell is parameterised
+
+`ActivityLayout`, `ActivityContent`, `AppSidebar`, `AppHeader`,
+`AppBreadcrumb`, `MenuItem`:
+
+- **`items` is a prop, not a `useMenuItems()` call.** Each app builds and
+  filters its own menu.
+- **`MenuItem.label` is a `ReactNode`, already translated — not a key.** This
+  package can only resolve its own reserved `material.*` namespace. The app
+  translates; the shell renders.
+- **`MenuItem.footer` is explicit.** `partitionMenu` is that rule.
+- **`avatar` and `headerActions` are props.** The shell holds no session.
+- **`AppBreadcrumb` reads `handle.breadcrumb` off `useMatches()`.** It needs
+  a **data router** — a story or test must use `createMemoryRouter` +
+  `RouterProvider`, not `MemoryRouter`.
+
+The active menu entry is the **longest** match, resolved across the whole
+menu (`findActiveMenuItem`), segment-aware — `/admin` does not cover
+`/administrators`. A per-entry predicate cannot work once a menu is mounted
+anywhere but `/`.
+
+---
+
+## SSR consumers evaluate the barrels at boot
+
+The SSR apps in sellix-monorepo (`oauth-ui`, `kratos-ui`) bundle this package
+into their server build (`ssr.noExternal: ['@nxgt/material']`): every module
+the `main` / `components` barrels reach is evaluated in the server process at
+startup, whether or not any page renders the component. Storybook and the SPA
+apps never see this, so a change that breaks it passes every check in this
+repo.
+
+- **Nothing browser-only at module scope.** No `window`, `document`,
+  `DOMMatrix`, `Worker`, and no third-party module that does it for you.
+  `pdfjs-dist` (via `react-pdf`) runs `new DOMMatrix()` at import — which is
+  why `pdf-viewer/` reaches `react-pdf` only through `react-pdf.lazy.ts` (a
+  dynamic `import()`, `Page`/`Document` as `lazy()`), why each component that
+  renders them ends its file with `export const X = clientOnly(X)`, and why
+  `pdf-viewer/index.test.ts` fails if a static `react-pdf` import comes back.
+  `clientOnly` lives in `@nxgt/material/lib`. Reuse the pair — dynamic import
+  for the dependency, `clientOnly` for the component — for the next
+  browser-only dependency rather than adding a `typeof window` guard. A guard
+  around a *statement* does nothing when the *import* is the side effect;
+  only `import()` defers it.
+- **Never name an SVG with `<svg><title>`; use `role="img"` +
+  `aria-label`.** React 19 treats `<title>` as hoistable document metadata: on
+  the server it lifts the element out and emits `<title></title>`, while the
+  client renders the text inline. That is a hydration mismatch, and React
+  answers one by discarding the whole server tree and regenerating it on the
+  client — as a console warning, with nothing visibly broken. `Icon` did this,
+  so every SSR page in every consuming app silently client-rendered itself.
+
+---
+
+## Form fields
+
+Every field has a standalone component (`TextField`, `SelectField`, …) and a
+React Hook Form wrapper in the same barrel (`TextFormField`,
+`SelectFormField`, …). The wrappers take `control` + `name` and wire
+`Controller` for you.
+
+```tsx
+import { TextFormField, Button } from '@nxgt/material/components';
+import { useForm } from 'react-hook-form';
+
+const form = useForm({ defaultValues: { email: '' } });
+
+<TextFormField control={form.control} name="email" label="Email" />
+```
+
+---
+
 ## Working on this package
 
 ```sh
@@ -97,11 +266,10 @@ bun run storybook
 bun run test
 ```
 
-`bun run build` is what consumers read. There is **no `postinstall` build**: the
-package publishes `dist/` and not `lib/`, so a build triggered on a consumer's
-machine would have no sources to compile and would fail the install outright
-under npm. Build here, then publish.
+`bun run build` is what consumers read. New reusable components arrive here
+rather than in an app — see the "Reusable UI components belong in
+`@nxgt/material`" section of the consuming repositories' AGENTS.md.
 
-New reusable components arrive here rather than in an app — see the
-"Reusable UI components belong in `@nxgt/material`" section of the consuming
-repositories' `AGENTS.md`.
+A change that should reach a consumer needs a changeset (`bun changeset`) and
+a merge to `develop`. The README is this package's page on npmjs: a public-API
+change updates it in the same PR.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nxgt/material",
-	"version": "1.0.0",
+	"version": "1.0.1",
 	"type": "module",
 	"files": [
 		"dist",
@@ -62,8 +62,11 @@
 		"postbuild": "cp lib/styles.css dist/",
 		"storybook": "storybook dev -p 6006",
 		"build-storybook": "storybook build",
-		"publish": "bun publish --access=public",
 		"test": "vitest run",
+		"changeset": "changeset",
+		"changeset:version": "changeset version",
+		"changeset:publish": "bun run build && bun run scripts/publish.ts",
+		"changeset:status": "changeset status --since=origin/develop",
 		"shadcn:add": "bunx --bun shadcn@latest add",
 		"tsc": "tsc -b",
 		"check": "biome check --write",
@@ -151,6 +154,8 @@
 	},
 	"devDependencies": {
 		"@biomejs/biome": "2.5.5",
+		"@changesets/changelog-github": "^1.0.1",
+		"@changesets/cli": "^3.0.1",
 		"@chromatic-com/storybook": "^5.3.1",
 		"@storybook/addon-a11y": "10.6.0",
 		"@storybook/addon-docs": "10.6.0",