feat(integrations): CnFilesCard + CnTagsCard + CnAuditTrailCard widgets

[rubenvdlinde]

Part of the openregister pluggable-integration-registry umbrella. Stacked on #202 (JS integration registry); GitHub will auto-retarget to beta after #202 merges.

Summary

Three surface-aware compact widgets that fill the parity gap for the five built-in integrations (files, tags, audit-trail). PR 5 already ships rich sidebar tabs for these — this PR adds the widget half of the parity contract so dashboards and detail pages have something to render too.

Per AD-19 (surface fallback), each widget handles all four surfaces (user-dashboard, app-dashboard, detail-page, single-entity) from a single component. The surface prop is accepted and validated; a future surface-specific override can be added at registration time via widgetCompact / widgetExpanded / widgetEntity without touching these components.

Implements tasks 8.1–8.4 of the umbrella.

What's in this PR

Components (all wrap CnDetailCard for consistent styling)

• CnFilesCard — name + size rows, Show-all overflow, formatFileSize helper (B / KB / MB / GB), fetch-failure fallback to empty state
• CnTagsCard — inline pills for fetched system tags
• CnAuditTrailCard — action / actor / when rows with actor fallback chain (actorDisplayName → actor → userId → user), Show-all overflow, fetch-failure fallback to empty state

Each widget:

• Accepts register / schema / objectId / surface props (surface validator runs against VALID_SURFACES)
• Fetches via the existing REST endpoint using buildHeaders()
• Refetches when objectId changes
• Emits show-all when the overflow control is clicked (where applicable)

Barrels & docs

• src/components/index.js + src/index.js — public exports
• docs/components/cn-files-card.md, cn-tags-card.md, cn-audit-trail-card.md — matches the existing card doc template
• Also fills the docs gap from feat(integrations): JS integration registry + useIntegrationRegistry composable #202 (umbrella PR 6/N): integrations, createIntegrationRegistry, installIntegrationRegistry, VALID_SURFACES, useIntegrationRegistry

Tests (12 new, all green)

• CnFilesCard.spec.js — empty state, rows capped at maxDisplay, show-all emission, refetch on objectId change, fetch-failure fallback
• CnTagsCard.spec.js — empty state, pill rendering, API-error fallback
• CnAuditTrailCard.spec.js — empty state, row capping + Show-all, show-all emission, actor-fallback chain

Test plan

• npx jest tests/components/Cn{Files,Tags,AuditTrail}Card.spec.js → 3 suites, 12 tests, all passing
• npm run lint — no new errors or warnings on the files added by this PR
• node scripts/check-docs.js — 8 remaining gaps are all pre-existing (CnAi* family + a default export leak unrelated to this work)
• Smoke-test in a live Nextcloud after PR 8 lands (registry-aware CnObjectSidebar / CnDashboardPage / CnDetailPage refactor) and PR 9 lands (the 5 built-in JS registrations that wire these widgets onto each surface)

[WilcoLouwerse]

[BLOCKER] Unvalidated file.url used as href — open redirect / javascript: injection

The file.url value comes directly from the API response and is bound to :href without any validation. A malicious or compromised API response could return javascript:alert(1) or a phishing redirect. Fix: validate that the URL starts with a safe protocol before rendering the anchor, e.g. a computed helper isSafeUrl(url) { try { const u = new URL(url, location.origin); return ['http:', 'https:'].includes(u.protocol) } catch { return false } }. Use v-if="isSafeUrl(file.url)" to gate the anchor element, falling back to the plain <span> branch that already exists.

[WilcoLouwerse]

[CONCERN] API limit param makes 'Show all' overflow button unreachable

The fetch passes limit: String(this.maxDisplay) to the endpoint, so data.results will contain at most maxDisplay items. The overflow footer condition files.length > maxDisplay will therefore never be true — the server already truncated the list. Either (a) fetch limit + 1 to detect overflow, or (b) rely on the response's pagination metadata (data.total or data.count). The same pattern exists in CnAuditTrailCard.

[WilcoLouwerse]

[CONCERN] limit param makes the 'Show all' overflow button unreachable (audit trail)

Same issue as CnFilesCard: params = new URLSearchParams({ limit: String(this.maxDisplay) }) limits server response to exactly maxDisplay rows. The footer condition entries.length > maxDisplay can never be true. Fix: fetch maxDisplay + 1 items, render only maxDisplay, and show the overflow button when the extra item is present.

[WilcoLouwerse]

[CONCERN] Silent non-2xx responses show empty state — fetch errors invisible to user

When response.ok is false (4xx/5xx), entries is set to [] silently. The user sees 'No audit entries yet' — indistinguishable from a genuinely empty audit trail. Add an error data flag, set it when !response.ok, and render a distinct error message so users know a fetch failure occurred. The same pattern applies to CnFilesCard and CnTagsCard.

[WilcoLouwerse]

[CONCERN] Silent non-2xx responses show empty state — fetch errors invisible to user (tags)

Same issue as CnAuditTrailCard: HTTP errors collapse silently into the empty-state label. A 403 or 500 from the tags endpoint will show 'No tags' rather than a meaningful error. Add an error reactive flag and a distinct error message.

[WilcoLouwerse]

[CONCERN] No maxDisplay / pagination guard — unbounded tag list renders all items

CnFilesCard and CnAuditTrailCard both honour a maxDisplay prop and truncate the rendered list. CnTagsCard has no maxDisplay prop and renders every tag returned by the API. If an object has dozens of tags, the pill list will overflow the card with no overflow control or 'show all' button. Add a maxDisplay prop (defaulting to e.g. 10) mirroring the other two widgets, slice the list in a displayedTags computed, and add a footer overflow control.

[WilcoLouwerse]

[CONCERN] objectId watcher does not cancel in-flight fetch — race condition on rapid prop change

When objectId changes rapidly, a new fetchFiles() is started before the previous request settles. If the first response arrives after the second, files will be set to stale data. Fix using AbortController: store a controller in data, abort it at the start of fetchFiles(), create a fresh one, and pass { signal } to fetch(). The same pattern applies to CnAuditTrailCard and CnTagsCard.

[WilcoLouwerse]

[CONCERN] objectId watcher does not cancel in-flight fetch — race condition (audit trail)

Same race condition as CnFilesCard: stale data from an earlier request can overwrite the correct result when objectId changes. Use an AbortController stored in component data, aborting the previous request at the start of each fetchEntries() call.

[WilcoLouwerse]

Review

🔴 Blockers (1)

• Unvalidated file.url used as href — open redirect / javascript: injection — src/components/CnFilesCard/CnFilesCard.vue:773

🟡 Concerns (7)

• API limit param makes 'Show all' overflow button unreachable — src/components/CnFilesCard/CnFilesCard.vue:888
• limit param makes the 'Show all' overflow button unreachable (audit trail) — src/components/CnAuditTrailCard/CnAuditTrailCard.vue:635
• Silent non-2xx responses show empty state — fetch errors invisible to user — src/components/CnAuditTrailCard/CnAuditTrailCard.vue:643
• Silent non-2xx responses show empty state — fetch errors invisible to user (tags) — src/components/CnTagsCard/CnTagsCard.vue:1116
• No maxDisplay / pagination guard — unbounded tag list renders all items — src/components/CnTagsCard/CnTagsCard.vue:1023
• objectId watcher does not cancel in-flight fetch — race condition on rapid prop change — src/components/CnFilesCard/CnFilesCard.vue:869
• objectId watcher does not cancel in-flight fetch — race condition (audit trail) — src/components/CnAuditTrailCard/CnAuditTrailCard.vue:617

🟢 Minor (3)

• d.toLocaleString() uses browser locale — inconsistent with Nextcloud's locale (src/components/CnAuditTrailCard/CnAuditTrailCard.vue:664)
  new Date(raw).toLocaleString() picks up the OS/browser locale rather than Nextcloud's configured language. Use @nextcloud/moment (moment(raw).format('LLL')) or the Nextcloud formatDate utility to keep date formatting consistent with the rest of the UI.
• formatFileSize uses binary divisors but SI (KB/MB/GB) labels (src/components/CnFilesCard/CnFilesCard.vue:908)
  The labels say 'KB', 'MB', 'GB' but divide by powers of 1024 (binary kibibytes). Use either the correct SI labels ('KiB', 'MiB', 'GiB') for binary, or switch to powers of 1000 for SI. Better: delegate to @nextcloud/files formatFileSize to match Nextcloud's own display.
• Two $nextTick calls are fragile — use flushPromises() instead (tests/components/CnAuditTrailCard.spec.js:1229)
  Tests await wrapper.vm.$nextTick() twice to let the fetch promise and reactivity update settle. Use await flushPromises() from @vue/test-utils instead, which drains the entire microtask queue and is independent of internal implementation details.

Reviewed by WilcoLouwerse via automated batch review.