CLAUDE.md

1# Portlet Development Guide
2 
3> **Parent node**: [`core-web/CLAUDE.md`](../../CLAUDE.md) (Angular rules, commands, testing)
4> **Reference portlet**: `libs/portlets/dot-tags/` — read the source when in doubt
5> **SignalStore docs**: https://ngrx.io/guide/signals/signal-store
6 
7## Architecture Pieces
8 
9Every CRUD portlet has these parts:
10 
11| Piece | What to build | Reference file (`dot-tags`) |
12|-------|--------------|----------------------------|
13| **Shell** | Minimal wrapper, renders the list component | `dot-tags-shell/dot-tags-shell.component.ts` |
14| **List + Store** | Data table with pagination, search, sort; store manages state & HTTP | `dot-tags-list/` and `dot-tags-list/store/` |
15| **Create/Edit dialog** | Single component, two modes via `DynamicDialogConfig.data` | `dot-tags-create/dot-tags-create.component.ts` |
16| **Routes** | `dotFeatureRoutes` exported from `lib.routes.ts`, registered in `app.routes.ts` | `lib.routes.ts` |
17 
18Optional: Import dialog (CSV/file upload) — see `dot-tags-import/`.
19 
20## Separation of Concerns (Critical Rule)
21 
22| Layer | Responsibility | Owns |
23|-------|---------------|------|
24| **Store** | Data fetching, state mutations, API calls | HTTP calls, `patchState`, error handling via `DotHttpErrorManagerService` |
25| **List Component** | UI orchestration | Opens dialogs, shows confirmations, translates `TableLazyLoadEvent`, debounces search |
26| **Create Component** | Form logic | Reactive form, validation, `DynamicDialogRef.close(formValue)` |
27| **Shell Component** | Routing wrapper | Just renders the list component |
28 
29**Store MUST NOT** open dialogs, inject `DialogService`, or interact with UI. Store is data only.
30 
31## Key Rules
32 
33- `untracked()` inside `effect()` to prevent infinite loops
34- `take(1)` on one-shot HTTP calls (e.g. `loadById`, dialog saves). **Do NOT add `take(1)` inside `rxMethod`** — `rxMethod` manages subscription lifetime automatically; adding `take(1)` there breaks cancellation
35- Error handling: always `catchError` → `httpErrorManager.handle(error)` → `return EMPTY`
36- On error from CRUD actions, set status back to `'loaded'` (not `'error'`) so the list stays usable
37- `DotHttpErrorManagerService.handle(error)` for all HTTP errors — no custom error UI
38- All user-facing text uses i18n keys via `DotMessagePipe` (`| dm`) or `DotMessageService.get()`
39- Key naming: `{feature}.{context}.{element}` (e.g., `tags.confirm.delete.header`)
40- `data-testid` (all lowercase) on every interactive element; `[attr.aria-label]` on inputs and icon-only buttons
41 
42## Dialog Sizing Standards
43 
44| Dialog type | Width |
45|-------------|-------|
46| Form / add / edit / import | `700px` |
47| Confirmation / warning / delete | `500px` |
48| Special (iframes, full-screen) | responsive — `min(92vw, 75rem)` or as needed |
49 
50Apply `width` on `DialogService.open()` config. For `p-confirmDialog`, set `[style]` on the template element (PrimeNG's `Confirmation` type does not expose `style` as a confirm-call option):
51 
52```typescript
53// Form dialog (TypeScript)
54this.dialogService.open(MyFormComponent, { width: '700px', ... });
55```
56 
57```html
58<!-- Confirmation dialog (template) -->
59<p-confirmDialog [draggable]="false" [style]="{ width: '500px' }" />
60```
61 
62**Exception**: upload/import dialogs also set `contentStyle: { height: '460px' }` to keep a fixed layout while showing inline errors.
63 
64## CRUD Patterns
65 
66**Modal dialogs (default)**: List component opens `DialogService.open(CreateComponent, ...)`. The dialog closes with the form value; the list component passes it to the store. This is the pattern used in `dot-tags` and should be the default for new portlets.
67 
68**Routed CRUD (rare)**: Separate route for create/edit pages. Use only when the form is too complex for a dialog (many tabs, nested data). See `dot-experiments` for this pattern.
69 
70## When the CRUD Pattern Is Not Enough
71 
72Standard CRUD portlets (Shell + List + Store) cover most cases. For portlets with complex domain logic, multiple interconnected features, or large state surfaces, decompose the store into feature slices using `signalStoreFeature()`:
73 
74```typescript
75export const UVEStore = signalStore(
76    withUve(),        // system lifecycle
77    withFlags(),      // feature flags
78    withPage(),       // page asset domain
79    withPageApi(),    // backend interactions
80    withWorkflow(),   // workflow/lock
81    withEditor(),     // editor UI state
82);
83```
84 
85Each feature slice owns a named prefix in the flat state (e.g. `editor*`, `view*`, `page*`) and exposes only the methods and computeds relevant to its domain. See `libs/portlets/edit-ema/portlet/README.md` for a full example.
86 
87## Nx Generator Post-Setup
88 
89After running the generator:
90 
91```bash
92yarn nx generate @nx/angular:library --name=portlet \
93  --directory=libs/portlets/dot-{feature} \
94  --tags=type:feature,scope:dotcms-ui,portlet:{feature} \
95  --prefix=dot --standalone --no-interactive
96```
97 
98**Required fixes**:
99 
1001. **tsconfig alias** in `core-web/tsconfig.base.json`: change generated `"portlet"` → `"@dotcms/portlets/dot-{feature}/portlet"`
1012. **project.json** `name`: change to `portlets-dot-{feature}-portlet`
1023. **jest.config.ts** `displayName`: change to `portlets-dot-{feature}-portlet`
1034. **tsconfig.spec.json**: add `isolatedModules: true` in transform options (required for transitive deps)
1045. **tsconfig.spec.json**: keep minimal — only `module`, `target`, `types`
1056. **Delete** generated `README.md` and boilerplate component in `src/lib/portlet/`
106 
107## Anti-Patterns
108 
109| Do NOT | Do Instead |
110|--------|-----------|
111| Store opens dialogs or injects DialogService | Component opens dialogs, passes result to store |
112| Missing `untracked()` in effect | Wrap store method calls in `untracked()` |
113| Missing `isolatedModules: true` in jest config | Add it — transitive deps fail without it |
114| Adding `"strict": true` to tsconfig.json | Omit — causes issues with Angular compiler |
115| Adding `"module": "preserve"` to tsconfig.spec.json | Use `"module": "commonjs"` |
116| Hardcoded text in templates | Use `DotMessagePipe` (`| dm`) for all user-facing text |
117| Custom error dialogs | Use `DotHttpErrorManagerService.handle(error)` everywhere |
118| `@Input()` / `@Output()` decorators | Use `input()` / `output()` signal functions |
119| `*ngIf` / `*ngFor` structural directives | Use `@if` / `@for` control flow |
120 
121## Other Reference Portlets
122 
123- **`dot-tags`** — Canonical reference for the standard CRUD pattern (modal dialogs, SignalStore)
124- **`dot-experiments`** — Full CRUD with guards, resolvers, shell, routed create/edit
125- **`dot-analytics`** — Enterprise license checking, lazy loading
126- **`dot-content-drive`** — Complex nested routing, reference for test config
127- **`edit-ema/portlet`** — Reference for complex portlets: feature slice decomposition, Container/Presentational pattern, flat prefixed state
128- **`dot-locales`** — Legacy pattern only (uses `ComponentStore`). Do not use as a model for new work
129