Skip to content

docs(dashboard): fix blocking errors in dashboard.md (wrong import package, non-existent dialog exports) #232

Description

@lpgarzonr

Summary

Empirical validation of docs/dashboard.md against the built packages (main @ v0.18.9) found 2 blocking errors that make the documented Angular examples fail to compile, plus several accuracy issues. A team copy-pasting the docs will hit a hard tsc failure.

Method: built @openmfp/ngx + @openmfp/webcomponents from main, scaffolded a real Angular 21 consumer against the built artifacts, copy-pasted the doc examples verbatim and ran tsc, then drove the running dashboard in a browser.

🔴 Blocking

1. Angular example imports from the wrong package

The "Usage as an Angular component" example imports from @openmfp/webcomponents, which ships only JS bundles, no type declarations:

error TS2307: Cannot find module '@openmfp/webcomponents' or its corresponding type declarations.

The generated dist/webcomponents/package.json exports only .mfp-webcomponents.js and ./dashboardmfp-wc-dashboard.js. The TS symbols (Dashboard, CardConfig, DashboardConfig, SectionConfig, VisitedServiceCard) are exported by @openmfp/ngx. The doc's own CanDeactivate example already uses @openmfp/ngx, so the doc is internally inconsistent.

Fix: change the Angular example import to @openmfp/ngx.

2. The three dialogs are not exported — "Standalone dialog reuse" is impossible

error TS2305: Module '@openmfp/ngx' has no exported member 'DiscardChangesDialog'.
error TS2305: Module '@openmfp/ngx' has no exported member 'UnsavedChangesDialog'.
error TS2305: Module '@openmfp/ngx' has no exported member 'EditCardsDialog'.

The dashboard barrel re-exports only ./dashboard + ./models; the dialogs are never re-exported. Consequences:

  • The "Standalone dialog reuse" section can't work — the components aren't importable.
  • The per-dialog language input documented in all three dialog API tables + the Localization section does not exist (the components declare only open + outputs; language is driven solely by the shared DashboardI18nService).

Fix: delete the standalone-reuse section + language rows, OR export the dialogs and add the input.

🟠 Accuracy

  1. hasUnsavedChanges() is protected, not consumer-readable — breaks step 1 of "Showing your own dialog instead" (error TS2445). The public methods it says to call (saveEdit, cancelEdit, confirmDiscard, onUnsavedNav*) are fine; editMode()/unsavedNavDialogOpen()/discardDialogOpen() are public.
  2. Undocumented output unsavedChangesChange: OutputEmitterRef<boolean> — missing from the Outputs table; it's the correct replacement for the broken advice in Migrate dxp-ngx components #3.
  3. "All x,y,w,h persisted on save" is imprecise — verified live: only loose cards get x/y; section cards don't. Loose-card h may be recomputed by sizeToContent.

🟡 Minor

  1. "Warning icon" claims are wrong — the discard/unsaved dialog headers have no icon (just <ui5-title>; the accent is state="Critical"). The unsaved badge uses the user-edit icon.
  2. Dialog data-testids are inside shadow DOM (ViewEncapsulation.ShadowDom) — plain getByTestId() won't reach them; the Test IDs section should note this.
  3. Stale code comments (code, not doc): dashboard.model.ts JSDoc calls it the "Add Card" button; UI/i18n/doc say "Edit Cards".

Recommendation

Fix #1 and #2 first (hard compile failures). The doc's behavioral content is accurate and thorough — the failures are all in API-surface/import claims.

Metadata

Metadata

Assignees

Labels

bugSomething isn't workingdocumentationImprovements or additions to documentationstakeholder/portalStakeholder Portal

Type

Projects

Status
Done

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions