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

package/README.md

@@ -1,192 +1,3 @@
-# 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.