customer-module-frontend 2.7.0-beta.33 → 2.7.0-beta.34

package/README.md

@@ -1,3 +1,192 @@
+# customer-module-frontend
+
+The Hiver customer module (contacts, accounts, conversations) as an embeddable
+React library, published to npm and mounted by a host application.
+
+## Integrating with a host
+
+The library renders against the host's own API surface. Two optional fields on
+the mount config decide how.
+
+**Additive only.** Both fields are optional, and with both absent every code
+path is the one that shipped in `2.6.2` — Omni hosts require no action.
+
+### `CustomerModuleConfig.platform?: 'GMAIL' | 'HIVERWEB'`
+
+Absent (as `outlook-ui` supplies it) keeps the existing behaviour. `'GMAIL'`
+opts the response interceptor into the envelope normaliser, because the proxied
+API returns a bare page body where the library expects
+`{ status, message, data }`.
+
+The discriminator is read per response, never cached on the shared `apiClient`
+singleton, so one page can hold a GMAIL config and a HIVERWEB config without
+either leaking into the other.
+
+### `CustomerModuleCallbacks.cmApiCallback?: HostTransport`
+
+When supplied it is installed as the axios adapter, and the host owns the wire:
+base URL, auth headers, credentials, CSRF. The library forwards only what it
+owns — the path, the params, the body, and the two per-request options
+(`responseType`, `paramsSerializer`) that silently change behaviour when a
+transport drops them.
+
+Omit it and the library issues the request itself, unchanged.
+
+A transport is expected to resolve with an axios-shaped response carrying the
+real HTTP `status` — including for failures. The adapter applies
+`validateStatus` itself, so a relayed `401`/`422`/`5xx` rejects the request and
+reaches the library's error handling. A transport that rejects natively is
+re-wrapped as an `AxiosError` so its status survives.
+
+Any existing `ApiCallback` satisfies `HostTransport`.
+
+### Bundled dependencies
+
+`react-router-dom` is bundled rather than declared external, so consumers do not
+have to provide it. The library mounts its own `<MemoryRouter>` and never reads
+a host Router context.
+
+## Development
+
+```bash
+yarn install
+yarn dev            # vite dev server
+yarn build          # tsc -b && vite build            → dist/  (the root entry Omni consumes)
+yarn build:hui      # tsc -b && UI_FRAMEWORK=hui vite build → dist/hui/
+yarn build:all      # both, in the required order
+yarn test           # vitest run
+yarn test:artifacts # build, then grep the built bundles
+yarn lint           # eslint .
+```
+
+> **`build:hui` no longer fails on theme resolution. It now fails on an upstream packaging
+> defect in the toolkit.** The old blocker — "the toolkit does not export `./themes/hui`, so the
+> hui build cannot resolve its CSS" — was doubly wrong and is gone: the toolkit *does* export
+> `./themes/hui`, and hui's styling never was a stylesheet (see *Two design systems, one package*
+> below). `resolveThemeStylesheet('hui')` now resolves to the committed placeholder
+> `src/theme/design-system.hui.css`, and no `[theme]` error is raised. What remains is not this
+> repo's to fix:
+>
+> ```
+> [vite]: Rollup failed to resolve import "@mui/material/styles" from
+>         node_modules/hiver-ui-kit-extended/dist/env.hui.js
+> ```
+>
+> `hiver-ui-kit-extended@1.1.0-beta.0`'s `hui` entry (`dist/env.hui.js`) imports
+> `@mui/material`, `@mui/material/styles`, `@mui/icons-material` and
+> `@mui/icons-material/Close`; elsewhere in its `dist/` it also reaches for
+> `@mui/material/styles/createTypography` and `@mui/x-date-pickers`. It declares no `@mui`
+> package in `dependencies`, `peerDependencies` **or** `optionalDependencies` (its peers are only
+> `primereact`, `primeicons`, `react`, `react-dom`). Those packages exist on disk here only nested
+> under `node_modules/@hiver/hiver-ui-kit/node_modules/@mui/`, as a transitive dependency of
+> `@hiver/hiver-ui-kit@4.8.10`, where the toolkit's own `dist/` cannot reach them —
+> `require.resolve('@mui/material/styles')` from the toolkit's `dist/` fails, while the same
+> resolve from `@hiver/hiver-ui-kit` succeeds. The toolkit only gets away with this in its own
+> repo, where hoisting happens to place `@mui` reachably.
+>
+> The fix belongs **upstream**: the toolkit should declare `@mui/material`,
+> `@mui/icons-material` and `@mui/x-date-pickers` as peer or direct dependencies and
+> republish. Do **not** paper over it
+> here by aliasing `@mui/*` to the nested copy — that silently binds the hui artifact to a
+> transitive MUI this repo does not control.
+>
+> Two consequences while that is outstanding:
+>
+> - **`yarn build:all` exits non-zero** and no `dist/hui/` artifact is produced. Expected, not a regression.
+> - **`yarn test:artifacts` tolerates it** — it runs `yarn build && (yarn build:hui || true) && vitest`,
+>   so the 14 root-artifact assertions (the ones that guarantee Omni's bundle contains no `hui` or
+>   MUI code) still run and still gate. The 6 `hui`-artifact assertions **skip** rather than pass —
+>   they are not silently green.
+
+> **`test:artifacts` is not strict, and the reason is no longer the stylesheet.** It keeps its
+> `yarn build && (yarn build:hui || true) && vitest` form, and `TC-DATA-02`/`TC-DATA-03` stay
+> **skipped**, because **AF-2 has not landed**. `Select`, `MultiSelect`, `Textarea`, `DateField`
+> and `CrmSelect` still import from `primereact/*`, and all five are reachable from the single
+> library entry (`src/index.tsx`) via `CreateEditEntity`. Because `inlineDynamicImports` bundles
+> the whole graph into one file per artifact, `resolve.conditions` cannot exclude them: the hui
+> artifact would still carry primereact even once it builds. Those two suites assert the opposite,
+> so they are gated off deliberately rather than weakened — their assertions are unchanged and
+> ready to run the moment AF-2 lands.
+>
+> AF-2's unblocking dependency is the three toolkit props on `hiver-ui-kit-extended` PR #55 @
+> `8b22713`, shipped in `1.1.0-beta.1`. Restore the strict form —
+> `"test:artifacts": "yarn build:all && vitest run src/__tests__/artifact-scan.test.ts"` — in the
+> same change that lands AF-2 and unskips those two suites, and not before. Leaving `|| true` in
+> place after that point would let a genuinely broken `hui` build pass unnoticed.
+
+### Toolkit version pin
+
+`hiver-ui-kit-extended` is pinned to **exactly `1.1.0-beta.0`** in `package.json` — no
+caret, matching the exact pin already used for `@testing-library/jest-dom`. The exact pin
+is deliberate: this is a prerelease, and a caret would let an install drift the entire
+two-entry build — both `resolve.conditions` variants *and* the theme stylesheet — onto an
+unreviewed prerelease. `1.1.0-beta.1` is published on the `beta` dist-tag, but this repo
+deliberately stays on `beta.0`; that bump belongs to AF-2, which needs the three props it
+carries, not to this change.
+
+> **This must not be merged while the toolkit is on a beta pin.** A beta pin on `main`
+> would ship Omni a prerelease design-system dependency. Re-point
+> `hiver-ui-kit-extended` to a stable release first, then merge. This is a note to the
+> reviewer who merges and handles stable versions — it is not something the implementing
+> run resolves, and it must not be softened or marked resolved until the pin is actually
+> off a prerelease.
+
+### Two design systems, one package
+
+`UI_FRAMEWORK` (`primereact` — the default — or `hui`) picks the design system at
+**build time**. It selects three things together: `resolve.conditions` (which
+variant of `hiver-ui-kit-extended` the whole module graph sees), the theme
+stylesheet aliased to `@theme/design-system.css`, and the output directory.
+There is no runtime selection, and the value is read by `vite.config.ts` through
+`loadEnv` — it is *not* an `import.meta.env` value and cannot be read from `src/`.
+
+`vite.config.ts` also mirrors that same choice into a `define`d compile-time constant,
+`__UI_FRAMEWORK__`, which is the one way `src/` *can* branch on the design system: where
+`UI_FRAMEWORK` is a config-time `loadEnv` value invisible to application code,
+`__UI_FRAMEWORK__` is substituted into the source at build time — still a constant baked
+in per build, not a runtime toggle. It is added to `baseConfig`, so dev, build and vitest
+all see it consistently; the `src/constants/uiFramework.ts` helper that reads it (and
+falls back to `primereact` when a consumer's bundler never defines it) lands with the
+AF-4 UI work.
+
+`yarn build` is unchanged and still produces the root entry that Omni resolves.
+The hui artifact nests inside that output at `dist/hui/`, so the root build — the
+one that empties `dist/` — has to run first. `build:all` enforces that order;
+running the two by hand in the other order silently discards `dist/hui/`.
+
+The published `exports` map currently declares the root entry only (`.`,
+`./RightPanel`, `./styles`). The hui artifact has no subpath yet because no
+release path produces one: both publish workflows run `npm run build`, the root
+entry alone. `./hui` and `./hui/styles` land together with a
+`prepack: yarn build:all`, in the same change that makes `yarn build:hui` work.
+
+> **hui has no static toolkit stylesheet, and is not going to get one.** Verified
+> against the packed `1.1.0-beta.0` tarball, and re-verified against `1.1.0-beta.1`:
+> `hiver-ui-kit-extended` ships exactly **one** static CSS file,
+> `dist/hiver-ui-kit-extended.css` — low-level shared classes like `.icon-button`, with
+> zero `Mui`/`emotion`/`css-` markers in it. Its `./themes/hui` export is a **JS module**
+> (`dist/themes.hui.js`), not a stylesheet: hui's design tokens (`HUITheme`) are a plain
+> JS object delivered through `HUIThemeProvider` context, and hui styling is applied via
+> MUI + emotion CSS-in-JS **at runtime**. The unresolved `@mui/material/styles` import
+> that now blocks `build:hui` is independent corroboration of the same finding.
+>
+> So `resolveThemeStylesheet('hui')` resolves to a **first-party committed placeholder**,
+> `src/theme/design-system.hui.css` — a comment-only file that exists solely so the
+> unconditional `import '@theme/design-system.css'` in `src/index.tsx` and `src/main.tsx`
+> has something to resolve to for the hui build. It is a deliberate placeholder, **not
+> dead code**: deleting it breaks the hui build, and re-pointing hui at a `node_modules`
+> lookup cannot work, because no such file exists to point at.
+> `resolveThemeStylesheet('primereact')` is unchanged — it still resolves from
+> `node_modules/hiver-ui-kit-extended/dist/hiver-ui-kit-extended.css` and still throws
+> loudly if that file ever goes missing. Only the *toolkit's* stylesheet is conditional
+> today — `src/index.css` still ships prime-targeted overrides to both artifacts.
+
+Design-system CSS is imported as `@theme/design-system.css`, never as the bare
+`hiver-ui-kit-extended/dist/*.css` specifier — a bare specifier cannot be made
+conditional, which is how both builds ended up on prime's stylesheet before.
+
+---
+
 # React + TypeScript + Vite
 
 This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.