From 5cb8fcdf583465e9269043538ab0f641d0694a35 Mon Sep 17 00:00:00 2001 From: Ruben van der Linde Date: Sun, 15 Nov 2026 00:32:35 +0000 Subject: [PATCH 1/7] feat(stackiq): build gemma-plate-views-peers-and-definitions [skip ci] Task 1: a GEMMA view picker on the plate. The plate lists the imported views with their release, fetches the chosen one through useViewStore with include_gebruik, draws its reference components in the view's own groups with the coverage states kept, and keeps the choice in the URL as ?view=. Coverage rows now carry the element identifier that view nodes name. Assisted-by: ClaudeCode:claude-opus-5-5 --- l10n/en.js | 7 +- l10n/en.json | 5 +- l10n/nl.js | 7 +- l10n/nl.json | 5 +- .../ReferenceComponentCoverageDerivation.php | 8 +- .../tasks.md | 4 +- src/utils/referenceComponentCoverage.js | 192 +++++++++++++++ src/views/organisaties/GemmaPlate.vue | 145 ++++++++++- ...eComponentCoverageDerivationGoldenTest.php | 2 +- tests/fixtures/coverage/build.json | 12 +- tests/fixtures/coverage/derive.json | 6 + tests/vitest/gemmaPlateRender.cases.spec.js | 4 + tests/vitest/gemmaPlateRender.spec.js | 4 + tests/vitest/gemmaPlateViews.spec.js | 233 ++++++++++++++++++ 14 files changed, 616 insertions(+), 18 deletions(-) create mode 100644 tests/vitest/gemmaPlateViews.spec.js diff --git a/l10n/en.js b/l10n/en.js index 45bdddb85..f92e5793f 100644 --- a/l10n/en.js +++ b/l10n/en.js @@ -5,8 +5,8 @@ OC.L10N.register( "stackiq", { - "No mail transport is set, so registration, activation and account mails are not sent.": "No mail transport is set, so registration, activation and account mails are not sent.", "Set up the mail transport": "Set up the mail transport", + "No mail transport is set, so registration, activation and account mails are not sent.": "No mail transport is set, so registration, activation and account mails are not sent.", "Licence metric": "Licence metric", "What one licence covers, as the contract with the supplier states it.": "What one licence covers, as the contract with the supplier states it.", "Licences bought": "Licences bought", @@ -1336,7 +1336,10 @@ OC.L10N.register( "Software catalogue": "Software catalogue", "Shared": "Shared", "{name}, shared by {partner}": "{name}, shared by {partner}", - "+{count} more": "+{count} more" + "+{count} more": "+{count} more", + "GEMMA view": "GEMMA view", + "The whole GEMMA model": "The whole GEMMA model", + "Import the GEMMA model to pick a GEMMA view.": "Import the GEMMA model to pick a GEMMA view." }, "nplurals=2; plural=(n != 1);" ) diff --git a/l10n/en.json b/l10n/en.json index ae796f560..d4b5a6ad8 100644 --- a/l10n/en.json +++ b/l10n/en.json @@ -1331,6 +1331,9 @@ "Software catalogue": "Software catalogue", "Shared": "Shared", "{name}, shared by {partner}": "{name}, shared by {partner}", - "+{count} more": "+{count} more" + "+{count} more": "+{count} more", + "GEMMA view": "GEMMA view", + "The whole GEMMA model": "The whole GEMMA model", + "Import the GEMMA model to pick a GEMMA view.": "Import the GEMMA model to pick a GEMMA view." } } diff --git a/l10n/nl.js b/l10n/nl.js index 6b4693a02..c59ecfacf 100644 --- a/l10n/nl.js +++ b/l10n/nl.js @@ -5,8 +5,8 @@ OC.L10N.register( "stackiq", { - "No mail transport is set, so registration, activation and account mails are not sent.": "Er is geen mailtransport ingesteld, dus registratie-, activatie- en accountmails worden niet verstuurd.", "Set up the mail transport": "Mailtransport instellen", + "No mail transport is set, so registration, activation and account mails are not sent.": "Er is geen mailtransport ingesteld, dus registratie-, activatie- en accountmails worden niet verstuurd.", "Licence metric": "Licentiemetriek", "What one licence covers, as the contract with the supplier states it.": "Waar één licentie voor geldt, zoals het contract met de leverancier het vastlegt.", "Licences bought": "Gekochte licenties", @@ -1404,7 +1404,10 @@ OC.L10N.register( "Software catalogue": "Softwarecatalogus", "Shared": "Gedeeld", "{name}, shared by {partner}": "{name}, gedeeld door {partner}", - "+{count} more": "+{count} meer" + "+{count} more": "+{count} meer", + "GEMMA view": "GEMMA-view", + "The whole GEMMA model": "Het hele GEMMA-model", + "Import the GEMMA model to pick a GEMMA view.": "Importeer het GEMMA-model om een GEMMA-view te kiezen." }, "nplurals=2; plural=(n != 1);" ) diff --git a/l10n/nl.json b/l10n/nl.json index 4a283a4ed..204157c80 100644 --- a/l10n/nl.json +++ b/l10n/nl.json @@ -1399,6 +1399,9 @@ "Software catalogue": "Softwarecatalogus", "Shared": "Gedeeld", "{name}, shared by {partner}": "{name}, gedeeld door {partner}", - "+{count} more": "+{count} meer" + "+{count} more": "+{count} meer", + "GEMMA view": "GEMMA-view", + "The whole GEMMA model": "Het hele GEMMA-model", + "Import the GEMMA model to pick a GEMMA view.": "Importeer het GEMMA-model om een GEMMA-view te kiezen." } } diff --git a/lib/Service/ReferenceComponentCoverageDerivation.php b/lib/Service/ReferenceComponentCoverageDerivation.php index 147e58859..5bcbc3c19 100644 --- a/lib/Service/ReferenceComponentCoverageDerivation.php +++ b/lib/Service/ReferenceComponentCoverageDerivation.php @@ -208,15 +208,19 @@ private function componentCoverage(string $id, CoverageIndex $index): array { }//end componentCoverage() /** - * What a component is: its name, group and documentation. + * What a component is: its name, group, documentation and its GEMMA + * element identifier, which a GEMMA view's nodes name it by. * * @param array $component The reference component. * - * @return array{name: string, group: string, documentation: string} + * @return array{name: string, identifier: string, group: string, documentation: string} + * + * @spec openspec/changes/gemma-plate-views-peers-and-definitions/specs/gemma-plate/spec.md#requirement-the-plate-draws-the-gemma-view-the-user-picks-req-gpl-001 */ private static function componentFacts(array $component): array { return [ 'name' => (string)($component['name'] ?? ''), + 'identifier' => (string)($component['identifier'] ?? ''), 'group' => (string)($component['grouping'] ?? ''), 'documentation' => (string)($component['documentation'] ?? ''), ]; diff --git a/openspec/changes/gemma-plate-views-peers-and-definitions/tasks.md b/openspec/changes/gemma-plate-views-peers-and-definitions/tasks.md index 73f3791e1..eedbc811c 100644 --- a/openspec/changes/gemma-plate-views-peers-and-definitions/tasks.md +++ b/openspec/changes/gemma-plate-views-peers-and-definitions/tasks.md @@ -9,8 +9,8 @@ - GIVEN imported GEMMA views WHEN the plate loads THEN a picker lists them with the GEMMA release, and `useViewStore` fetches the chosen view with `include_gebruik` - GIVEN a chosen view WHEN it renders THEN reference components are grouped by the view's groups, keeping the gap, covered and overlap states - GIVEN `?view=` in the URL WHEN the page opens THEN that view is chosen -- [ ] Implement -- [ ] Test (vitest `gemmaPlateViews.spec.js`) +- [x] Implement +- [x] Test (vitest `gemmaPlateViews.spec.js`) ### Task 2: Inhabitants on the organisation - **spec_ref**: openspec/changes/gemma-plate-views-peers-and-definitions/specs/gemma-plate/spec.md#requirement-the-plate-shows-what-comparable-organisations-use-req-gpl-002 diff --git a/src/utils/referenceComponentCoverage.js b/src/utils/referenceComponentCoverage.js index 43344c1fe..546640ece 100644 --- a/src/utils/referenceComponentCoverage.js +++ b/src/utils/referenceComponentCoverage.js @@ -44,3 +44,195 @@ export function groupCoverage(components, fallback) { ? [...named, { name: fallback, components: groups.get('') }] : named } + +/** + * A view's id, whichever shape the views endpoint gives it in. + * + * @param {object} view A view from `GET /api/views`. + * @return {string} The id, or '' when it has none. + * @spec openspec/changes/gemma-plate-views-peers-and-definitions/specs/gemma-plate/spec.md#requirement-the-plate-draws-the-gemma-view-the-user-picks-req-gpl-001 + */ +export function viewId(view) { + return String(view?.id ?? view?.['@self']?.id ?? view?.uuid ?? '') +} + +/** + * The GEMMA release a view belongs to, or '' when the import recorded none. + * + * @param {object} view A view. + * @return {string} The release. + * @spec openspec/changes/gemma-plate-views-peers-and-definitions/specs/gemma-plate/spec.md#requirement-the-plate-draws-the-gemma-view-the-user-picks-req-gpl-001 + */ +export function viewRelease(view) { + return String(view?.release ?? view?.gemmaRelease ?? view?.version ?? '') +} + +/** + * Picker options for the views, by name, each labelled with its release. + * + * @param {Array} views Views from `GET /api/views`. + * @return {Array<{id: string, label: string}>} Options. + * @spec openspec/changes/gemma-plate-views-peers-and-definitions/specs/gemma-plate/spec.md#requirement-the-plate-draws-the-gemma-view-the-user-picks-req-gpl-001 + */ +export function viewOptions(views) { + return (views || []) + .map((view) => { + const id = viewId(view) + const name = String(view?.name || view?.title || id) + const release = viewRelease(view) + return { id, label: release ? `${name} (${release})` : name } + }) + .filter((option) => option.id !== '') + .sort((a, b) => a.label.localeCompare(b.label)) +} + +/** + * The applications a view node's usage names, in the shape of a coverage row. + * + * @param {Array} usage The node's `usage` from `include_gebruik`. + * @return {Array<{moduleName: string}>} The applications. + */ +function usageApplications(usage) { + return (usage || []).map((item) => ({ + moduleName: String( + item?._linked_module?.name + ?? item?.module?.name + ?? item?.moduleName + ?? item?.name + ?? '', + ), + })) +} + +/** + * The state of a component that has this many applications. + * + * @param {number} count The applications. + * @return {string} gap, covered or overlap. + */ +function stateOf(count) { + if (count === 0) { + return 'gap' + } + return count === 1 ? 'covered' : 'overlap' +} + +/** + * The plate of one GEMMA view: its reference components in the view's own + * groups, in the order the view lists them. + * + * A node is a group when other nodes sit inside it; a component is a node + * without children that names a reference component of the coverage (by its + * element identifier or id) or carries usage. A component keeps its coverage + * row (state, fillable, applications); one the coverage does not know gets a + * row from the node's usage. A component sits in the group of its nearest + * named parent; components outside any group come last under the fallback. + * + * @param {object} view A view from `GET /api/views/{viewId}` with `include_gebruik`. + * @param {Array} components Coverage rows of the organisation. + * @param {string} fallback The name for components outside a group. + * @return {Array<{name: string, components: Array}>} Groups. + * @spec openspec/changes/gemma-plate-views-peers-and-definitions/specs/gemma-plate/spec.md#requirement-the-plate-draws-the-gemma-view-the-user-picks-req-gpl-001 + */ +export function viewGroups(view, components, fallback) { + const nodes = (view?.viewNodes || []).filter( + (node) => node && node.type !== 'label', + ) + const byNodeId = new Map(nodes.map((node) => [node.viewNodeId, node])) + const parents = new Set(nodes.map((node) => node.parent).filter(Boolean)) + const rows = new Map() + for (const row of components || []) { + for (const key of [row.identifier, row.id]) { + if (key && !rows.has(key)) { + rows.set(key, row) + } + } + } + + const groups = new Map() + const seen = new Set() + for (const node of nodes) { + const ref = node.modelNodeId || node.elementRef + if (!ref || parents.has(node.viewNodeId) || seen.has(ref)) { + continue + } + const row = rows.get(ref) || usageRow(node, ref) + if (!row) { + continue + } + seen.add(ref) + const name = groupName(node, byNodeId) + if (!groups.has(name)) { + groups.set(name, []) + } + groups.get(name).push(row) + } + + const named = [...groups.entries()] + .filter(([name]) => name !== '') + .map(([name, rowsOfGroup]) => ({ name, components: rowsOfGroup })) + return groups.has('') + ? [...named, { name: fallback, components: groups.get('') }] + : named +} + +/** + * A coverage row from a node's usage, or null when the node has none. + * + * @param {object} node A view node. + * @param {string} ref The element it shows. + * @return {object|null} The row. + */ +function usageRow(node, ref) { + if (!Array.isArray(node.usage) || node.usage.length === 0) { + return null + } + const applications = usageApplications(node.usage) + return { + id: ref, + identifier: ref, + name: String(node.name || ref), + documentation: String(node.documentation || node.description || ''), + state: stateOf(applications.length), + fillable: false, + fillableBy: [], + applications, + } +} + +/** + * The name of the nearest named parent of a node, or ''. + * + * @param {object} node A view node. + * @param {Map} byNodeId The view's nodes by view node id. + * @return {string} The group name. + */ +function groupName(node, byNodeId) { + const visited = new Set() + let parent = byNodeId.get(node.parent) + while (parent && !visited.has(parent.viewNodeId)) { + visited.add(parent.viewNodeId) + if (parent.name) { + return String(parent.name) + } + parent = byNodeId.get(parent.parent) + } + return '' +} + +/** + * The view's components that a filter keeps, groups without any left dropped. + * + * @param {Array<{name: string, components: Array}>} groups The view's groups. + * @param {string} filter all, gap, fillable or overlap. + * @return {Array<{name: string, components: Array}>} The kept groups. + * @spec openspec/changes/gemma-plate-views-peers-and-definitions/specs/gemma-plate/spec.md#requirement-the-plate-draws-the-gemma-view-the-user-picks-req-gpl-001 + */ +export function filterGroups(groups, filter) { + return groups + .map((group) => ({ + name: group.name, + components: filterCoverage(group.components, filter), + })) + .filter((group) => group.components.length > 0) +} diff --git a/src/views/organisaties/GemmaPlate.vue b/src/views/organisaties/GemmaPlate.vue index 1049d0c6b..05a58a2ca 100644 --- a/src/views/organisaties/GemmaPlate.vue +++ b/src/views/organisaties/GemmaPlate.vue @@ -8,6 +8,12 @@ use offers it) or overlap. A thin renderer over the bounded, organisation-scoped `GET /api/reference-component-coverage`. + A picker chooses one imported GEMMA view (plate); the plate then draws that + view's reference components in the view's own groups, read through + `GET /api/views/{viewId}` with `include_gebruik`, and keeps the choice in + the URL as `?view=`. Without a chosen view it groups the whole model. + + @spec openspec/changes/gemma-plate-views-peers-and-definitions/specs/gemma-plate/spec.md#requirement-the-plate-draws-the-gemma-view-the-user-picks-req-gpl-001 @spec openspec/changes/architecture-reference-component-coverage/specs/reference-component-coverage/spec.md#requirement-req-rcc-002-a-gemma-plate-shall-show-the-components-with-their-applications-with-filters-for-gaps-and-overlaps --> @@ -233,17 +278,21 @@ import { translate as t } from '@nextcloud/l10n' import { generateUrl } from '@nextcloud/router' import { NcButton, + NcCheckboxRadioSwitch, NcEmptyContent, NcLoadingIcon, NcNoteCard, NcSelect, } from '@nextcloud/vue' import Download from 'vue-material-design-icons/Download.vue' +import PeerUsageTable from '../../components/gemma/PeerUsageTable.vue' +import { peerLabel } from '../../components/gemma/peerLabel.js' import { useLiveCollections } from '../../composables/useLiveCollections.js' import pinia from '../../pinia.js' import { useViewStore } from '../../store/modules/view.js' import { objectStore } from '../../store/store.js' import { resolveUuid } from '../../utils/lifecyclePhase.js' +import { peerApplicationsOf, peerIndex } from '../../utils/peerUsage.js' import { filterCoverage, filterGroups, @@ -269,10 +318,12 @@ export default { CnStatusBadge, Download, NcButton, + NcCheckboxRadioSwitch, NcEmptyContent, NcLoadingIcon, NcNoteCard, NcSelect, + PeerUsageTable, }, /** @@ -297,6 +348,10 @@ export default { selected: null, selectedView: null, viewsLoaded: false, + showPeers: false, + peers: null, + peersLoading: false, + peersError: null, } }, @@ -357,6 +412,28 @@ export default { ) }, + /** + * The components on the plate, in plate order. + * + * @return {Array} Coverage rows. + * @spec openspec/changes/gemma-plate-views-peers-and-definitions/specs/gemma-plate/spec.md#requirement-the-plate-shows-what-comparable-organisations-use-req-gpl-002 + */ + plateComponents() { + return this.groups.flatMap((group) => group.components) + }, + + /** + * What comparable organisations use for the selected component. + * + * @return {Array} Peer applications. + * @spec openspec/changes/gemma-plate-views-peers-and-definitions/specs/gemma-plate/spec.md#requirement-the-plate-shows-what-comparable-organisations-use-req-gpl-002 + */ + selectedPeers() { + return this.selected + ? peerApplicationsOf(peerIndex(this.peers), this.selected) + : [] + }, + /** * The imported GEMMA views to pick from, each with its release. * @@ -435,6 +512,49 @@ export default { methods: { t, + peerLabel, + + /** + * Load what comparable organisations use when the layer is switched on. + * + * @param {boolean} on Whether the layer is on. + * @return {Promise} + * @spec openspec/changes/gemma-plate-views-peers-and-definitions/specs/gemma-plate/spec.md#requirement-the-plate-shows-what-comparable-organisations-use-req-gpl-002 + */ + async togglePeers(on) { + if (on && !this.peers) { + await this.loadPeers() + } + }, + + /** + * Load what comparable organisations use, for the selected organisation. + * + * @return {Promise} + * @spec openspec/changes/gemma-plate-views-peers-and-definitions/specs/gemma-plate/spec.md#requirement-the-plate-shows-what-comparable-organisations-use-req-gpl-002 + */ + async loadPeers() { + this.peers = null + this.peersError = null + if (!this.selectedOrg?.uuid) { + return + } + this.peersLoading = true + try { + const response = await axios.get( + generateUrl('/apps/stackiq/api/reference-component-coverage/peers'), + { params: { organisation: this.selectedOrg.uuid } }, + ) + this.peers = response.data + } catch (error) { + this.peersError = + error?.response?.data?.message + || error?.response?.data?.error + || t('stackiq', 'What comparable organisations use could not be loaded.') + } finally { + this.peersLoading = false + } + }, /** * The view id in the URL, or ''. @@ -502,6 +622,11 @@ export default { */ async loadCoverage() { this.selected = null + this.peers = null + this.peersError = null + if (this.showPeers) { + this.loadPeers() + } if (!this.selectedOrg?.uuid) { this.coverage = null return @@ -612,6 +737,30 @@ export default { gap: var(--default-grid-baseline, 4px); } +.gemma-plate__layers { + display: flex; + flex-wrap: wrap; + align-items: center; + gap: calc(var(--default-grid-baseline, 4px) * 2); + margin: 0; + padding: 0; + border: none; +} + +.gemma-plate__layers legend { + font-weight: 600; +} + +.gemma-plate__detail-heading { + margin: 0; + font-size: 0.95rem; +} + +.gemma-plate__peers { + margin: 0; + padding-inline-start: calc(var(--default-grid-baseline, 4px) * 5); +} + .gemma-plate__body { display: grid; grid-template-columns: minmax(0, 1fr) auto; diff --git a/tests/vitest/peerUsageTable.spec.js b/tests/vitest/peerUsageTable.spec.js new file mode 100644 index 000000000..0e9d0ffc5 --- /dev/null +++ b/tests/vitest/peerUsageTable.spec.js @@ -0,0 +1,187 @@ +// @vitest-environment jsdom + +/** + * SPDX-FileCopyrightText: 2026 Conduction B.V. + * SPDX-License-Identifier: EUPL-1.2 + * + * The layer "What comparable organisations use": the table with the own and + * the peer applications per component and their counts, a held-back count as + * "fewer than 3", the heading naming the band, and the side panel line. + * + * @spec openspec/changes/gemma-plate-views-peers-and-definitions/specs/gemma-plate/spec.md#requirement-the-plate-shows-what-comparable-organisations-use-req-gpl-002 + */ + +import { flushPromises, mount } from '@vue/test-utils' +import { beforeEach, describe, expect, it, vi } from 'vitest' + +const http = vi.hoisted(() => ({ get: vi.fn() })) +const store = vi.hoisted(() => ({ organisations: [] })) + +vi.mock('@nextcloud/axios', () => ({ default: http })) +vi.mock('@nextcloud/router', () => ({ generateUrl: (path) => `/index.php${path}` })) +vi.mock('@nextcloud/l10n', () => ({ + translate: (app, text, vars = {}) => String(text).replace(/\{(\w+)\}/g, (m, k) => (k in vars ? String(vars[k]) : m)), +})) +vi.mock('../../src/composables/useLiveCollections.js', () => ({ useLiveCollections: vi.fn() })) +vi.mock('../../src/store/store.js', () => ({ + objectStore: { getCollection: () => ({ results: store.organisations }) }, +})) +vi.mock('../../src/store/modules/view.js', () => ({ + useViewStore: () => ({ views: [], activeView: null, loading: false, setIncludeGebruik: vi.fn(), fetchViews: vi.fn(async () => {}), fetchView: vi.fn(async () => {}) }), +})) +vi.mock('@conduction/nextcloud-vue', () => ({ + CnKpiGrid: { template: '
' }, + CnStatsBlock: { props: ['title', 'count'], template: '
{{ title }}={{ count }}
' }, + CnStatusBadge: { props: ['label', 'variant'], template: '{{ label }}' }, +})) + +const { peerApplicationsOf, peerIndex, isHeldBack } = await import('../../src/utils/peerUsage.js') +const { peerLabel } = await import('../../src/components/gemma/peerLabel.js') +const { default: PeerUsageTable } = await import('../../src/components/gemma/PeerUsageTable.vue') +const { default: GemmaPlate } = await import('../../src/views/organisaties/GemmaPlate.vue') + +const components = [ + { id: 'zac', name: 'Zaakafhandelcomponent', group: 'Mid-office', state: 'covered', applications: [{ moduleName: 'Mozard' }] }, + { id: 'kb', name: 'Kennisbankcomponent', group: 'Front-office', state: 'gap', fillable: false, fillableBy: [], applications: [] }, + { id: 'dms', identifier: 'el-dms', name: 'Documentbeheercomponent', group: 'Back-office', state: 'gap', applications: [] }, +] + +const peers = { + organisation: 'zuiddrecht', + comparable: { type: 'gemeente', band: { min: 30000, max: 60000 }, organisations: 21 }, + components: [ + { referenceComponent: 'zac', applications: [{ moduleId: 'm1', moduleName: 'OpenZaak-UI', count: 21 }, { moduleId: 'm2', moduleName: 'Rare', count: null, fewerThan: 3 }] }, + { referenceComponent: 'kb', applications: [{ moduleId: 'm3', moduleName: 'Djuma Kennisbank', count: 12 }] }, + { referenceComponent: 'el-dms', applications: [{ moduleId: 'm4', moduleName: '', count: 5 }] }, + { applications: [{ moduleId: 'x', moduleName: 'No component', count: 9 }] }, + ], + truncated: false, +} + +describe('the peer helpers', () => { + it('indexes the peer applications by component, skipping rows without one', () => { + const index = peerIndex(peers) + expect([...index.keys()]).toEqual(['zac', 'kb', 'el-dms']) + expect(peerIndex(null).size).toBe(0) + }) + + it('finds a component\'s peers by its id, else its identifier', () => { + const index = peerIndex(peers) + expect(peerApplicationsOf(index, components[1])).toEqual(peers.components[1].applications) + expect(peerApplicationsOf(index, components[2])).toEqual(peers.components[2].applications) + expect(peerApplicationsOf(index, { id: 'none' })).toEqual([]) + }) + + it('labels a count, and a held-back count as fewer than its minimum', () => { + expect(peerLabel({ moduleName: 'OpenZaak-UI', count: 21 })).toBe('OpenZaak-UI (21)') + expect(peerLabel({ moduleName: 'Rare', count: null, fewerThan: 3 })).toBe('Rare (fewer than 3)') + expect(peerLabel({ moduleName: '', count: 5 })).toBe('Unnamed application (5)') + expect(isHeldBack({ count: 0 })).toBe(false) + expect(isHeldBack({})).toBe(true) + }) +}) + +describe('PeerUsageTable', () => { + it('shows per component the own and the peer applications, under a heading naming the band', () => { + const wrapper = mount(PeerUsageTable, { props: { components, peers } }) + + expect(wrapper.find('h3').text()).toBe(`What comparable organisations use: gemeente, ${(30000).toLocaleString()} to ${(60000).toLocaleString()} inhabitants`) + expect(wrapper.find('.peer-usage__hint').text()).toBe('Comparable organisations: 21') + const rows = wrapper.findAll('tbody tr') + expect(rows.map((row) => row.find('th').text())).toEqual(['Zaakafhandelcomponent', 'Kennisbankcomponent', 'Documentbeheercomponent']) + expect(rows[0].find('.peer-usage__own').text()).toBe('Mozard') + expect(rows[0].findAll('.peer-usage__peer').map((p) => p.text())).toEqual(['OpenZaak-UI (21)', 'Rare (fewer than 3)']) + expect(rows[1].find('.peer-usage__own').text()).toBe('No application') + expect(rows[1].find('.peer-usage__peers').text()).toBe('Djuma Kennisbank (12)') + expect(rows[2].find('.peer-usage__peers').text()).toBe('Unnamed application (5)') + }) + + it('says None for a component no comparable organisation fills', () => { + const wrapper = mount(PeerUsageTable, { props: { components: [{ id: 'other', name: 'X', applications: [] }], peers } }) + expect(wrapper.find('.peer-usage__peers').text()).toBe('None') + }) + + it('names an open-ended band, a lowest band, and only the type without a band', () => { + const heading = (comparable) => mount(PeerUsageTable, { props: { components: [], peers: { comparable } } }).find('h3').text() + + expect(heading({ type: 'gemeente', band: { min: 250000, max: null } })).toBe(`What comparable organisations use: gemeente, above ${(250000).toLocaleString()} inhabitants`) + expect(heading({ type: 'gemeente', band: { min: 0, max: 30000 } })).toBe(`What comparable organisations use: gemeente, under ${(30000).toLocaleString()} inhabitants`) + expect(heading({ type: 'gemeente', band: null })).toBe('What comparable organisations use: gemeente') + expect(heading({})).toBe('What comparable organisations use') + }) +}) + +const stubs = { + NcButton: { props: ['href'], emits: ['click'], template: '' }, + NcCheckboxRadioSwitch: { + props: ['modelValue'], + emits: ['update:modelValue'], + template: '', + }, + NcEmptyContent: { props: ['name'], template: '
{{ name }}
' }, + NcLoadingIcon: { template: '' }, + NcNoteCard: { props: ['type'], template: '
' }, + NcSelect: true, + Download: true, +} + +/** + * Mount the plate for one organisation, answering the coverage and peers requests. + * + * @param {Function} answerPeers Answers the peers request. + * @return {Promise} The wrapper. + */ +async function mountPlate(answerPeers) { + store.organisations = [{ uuid: 'zuiddrecht', name: 'Zuiddrecht' }] + http.get.mockImplementation(async (url) => { + if (url.endsWith('/peers')) { + return answerPeers() + } + return { data: { truncated: false, summary: { components: 3 }, components } } + }) + const wrapper = mount(GemmaPlate, { global: { stubs } }) + await flushPromises() + return wrapper +} + +beforeEach(() => { + http.get.mockReset() +}) + +describe('GemmaPlate peers layer', () => { + it('asks for nothing until the layer is switched on, then shows the table', async () => { + const wrapper = await mountPlate(async () => ({ data: peers })) + expect(http.get).not.toHaveBeenCalledWith('/index.php/apps/stackiq/api/reference-component-coverage/peers', expect.anything()) + expect(wrapper.find('[data-testid="gemma-plate-peers"]').exists()).toBe(false) + + await wrapper.find('[data-testid="gemma-plate-layer-peers"] input').setValue(true) + await flushPromises() + + expect(http.get).toHaveBeenCalledWith('/index.php/apps/stackiq/api/reference-component-coverage/peers', { params: { organisation: 'zuiddrecht' } }) + expect(wrapper.find('[data-testid="gemma-plate-peers"]').text()).toContain('OpenZaak-UI (21)') + expect(wrapper.text()).not.toContain('zuiddrecht') + }) + + it('lists the peer applications of the selected gap in the side panel', async () => { + const wrapper = await mountPlate(async () => ({ data: peers })) + await wrapper.find('[data-testid="gemma-plate-layer-peers"] input').setValue(true) + await flushPromises() + + await wrapper.findAll('.gemma-plate__component').find((b) => b.text().includes('Kennisbankcomponent')).trigger('click') + + const detail = wrapper.find('[data-testid="gemma-plate-detail"]') + expect(detail.text()).toContain('Gap') + expect(detail.find('[data-testid="gemma-plate-detail-peers"]').text()).toBe('Djuma Kennisbank (12)') + }) + + it('shows why the peers could not be loaded', async () => { + const wrapper = await mountPlate(async () => { + throw Object.assign(new Error('x'), { response: { data: { error: 'Not a member' } } }) + }) + await wrapper.find('[data-testid="gemma-plate-layer-peers"] input').setValue(true) + await flushPromises() + + expect(wrapper.find('.note[data-type="error"]').text()).toBe('Not a member') + expect(wrapper.find('[data-testid="gemma-plate-peers"]').exists()).toBe(false) + }) +}) From d9cc280af3b4fe1c27edbeb0d7e9943b5aa29a32 Mon Sep 17 00:00:00 2001 From: Ruben van der Linde Date: Sun, 15 Nov 2026 00:39:09 +0000 Subject: [PATCH 3/7] feat(stackiq): build gemma-plate-views-peers-and-definitions [skip ci] Task 5: GEMMA definitions in the reference component facet. FacetService adds each element's documentation and gemmaUrl to the referenceComponent buckets from the same element lookup, and the Applications and Services pages give each value an information button whose GemmaDefinitionPopover shows the name from GEMMA, the definition and a GEMMA Online link. Assisted-by: ClaudeCode:claude-opus-5-5 --- l10n/en.js | 6 +- l10n/en.json | 6 +- l10n/nl.js | 6 +- l10n/nl.json | 6 +- lib/Service/FacetService.php | 84 +++++++- .../tasks.md | 4 +- .../gemma/GemmaDefinitionPopover.vue | 120 +++++++++++ src/views/FacetedCatalogIndexView.vue | 91 ++++++++- .../Service/FacetServiceDefinitionTest.php | 192 ++++++++++++++++++ .../FacetServiceDimensionMapGoldenTest.php | 6 +- tests/vitest/gemmaDefinitionPopover.spec.js | 124 +++++++++++ 11 files changed, 620 insertions(+), 25 deletions(-) create mode 100644 src/components/gemma/GemmaDefinitionPopover.vue create mode 100644 tests/Unit/Service/FacetServiceDefinitionTest.php create mode 100644 tests/vitest/gemmaDefinitionPopover.spec.js diff --git a/l10n/en.js b/l10n/en.js index da36c806f..83a5480ac 100644 --- a/l10n/en.js +++ b/l10n/en.js @@ -1352,7 +1352,11 @@ OC.L10N.register( "What comparable organisations use": "What comparable organisations use", "What comparable organisations use could not be loaded.": "What comparable organisations use could not be loaded.", "What comparable organisations use: {type}": "What comparable organisations use: {type}", - "What comparable organisations use: {type}, {band}": "What comparable organisations use: {type}, {band}" + "What comparable organisations use: {type}, {band}": "What comparable organisations use: {type}, {band}", + "{name}, from GEMMA": "{name}, from GEMMA", + "More in GEMMA Online": "More in GEMMA Online", + "What is {name}?": "What is {name}?", + "What the reference components are": "What the reference components are" }, "nplurals=2; plural=(n != 1);" ) diff --git a/l10n/en.json b/l10n/en.json index 1df5dea28..0a0a9a901 100644 --- a/l10n/en.json +++ b/l10n/en.json @@ -1347,6 +1347,10 @@ "What comparable organisations use": "What comparable organisations use", "What comparable organisations use could not be loaded.": "What comparable organisations use could not be loaded.", "What comparable organisations use: {type}": "What comparable organisations use: {type}", - "What comparable organisations use: {type}, {band}": "What comparable organisations use: {type}, {band}" + "What comparable organisations use: {type}, {band}": "What comparable organisations use: {type}, {band}", + "{name}, from GEMMA": "{name}, from GEMMA", + "More in GEMMA Online": "More in GEMMA Online", + "What is {name}?": "What is {name}?", + "What the reference components are": "What the reference components are" } } diff --git a/l10n/nl.js b/l10n/nl.js index b8f3a68c2..5f919278a 100644 --- a/l10n/nl.js +++ b/l10n/nl.js @@ -1420,7 +1420,11 @@ OC.L10N.register( "What comparable organisations use": "Wat vergelijkbare organisaties gebruiken", "What comparable organisations use could not be loaded.": "Wat vergelijkbare organisaties gebruiken kon niet worden geladen.", "What comparable organisations use: {type}": "Wat vergelijkbare organisaties gebruiken: {type}", - "What comparable organisations use: {type}, {band}": "Wat vergelijkbare organisaties gebruiken: {type}, {band}" + "What comparable organisations use: {type}, {band}": "Wat vergelijkbare organisaties gebruiken: {type}, {band}", + "{name}, from GEMMA": "{name}, uit GEMMA", + "More in GEMMA Online": "Meer in GEMMA Online", + "What is {name}?": "Wat is {name}?", + "What the reference components are": "Wat de referentiecomponenten zijn" }, "nplurals=2; plural=(n != 1);" ) diff --git a/l10n/nl.json b/l10n/nl.json index 9c3f3cb53..98c5e9fb8 100644 --- a/l10n/nl.json +++ b/l10n/nl.json @@ -1415,6 +1415,10 @@ "What comparable organisations use": "Wat vergelijkbare organisaties gebruiken", "What comparable organisations use could not be loaded.": "Wat vergelijkbare organisaties gebruiken kon niet worden geladen.", "What comparable organisations use: {type}": "Wat vergelijkbare organisaties gebruiken: {type}", - "What comparable organisations use: {type}, {band}": "Wat vergelijkbare organisaties gebruiken: {type}, {band}" + "What comparable organisations use: {type}, {band}": "Wat vergelijkbare organisaties gebruiken: {type}, {band}", + "{name}, from GEMMA": "{name}, uit GEMMA", + "More in GEMMA Online": "Meer in GEMMA Online", + "What is {name}?": "Wat is {name}?", + "What the reference components are": "Wat de referentiecomponenten zijn" } } diff --git a/lib/Service/FacetService.php b/lib/Service/FacetService.php index 87bc11e04..11a7ed5c6 100644 --- a/lib/Service/FacetService.php +++ b/lib/Service/FacetService.php @@ -254,7 +254,7 @@ private function computeFacetsForRequest(ObjectServiceInterface $objectService, baseObjects: $baseObjects ); - $dimValsByObjId = $this->buildDimensionValueMap(modulesByObjectId: $modulesByObjectId); + [$dimValsByObjId, $definitions] = $this->dimensionValuesAndDefinitions(modulesByObjectId: $modulesByObjectId); // Supplier (insight-supplier-facet D3): the base object's OWN provider, // for a service too, keyed by organisation id and labelled by name (D2). @@ -271,6 +271,7 @@ private function computeFacetsForRequest(ObjectServiceInterface $objectService, selectedFilters: $request['filters'], labels: ['supplier' => $this->organisationNames(objectService: $objectService, identifiers: array_values(array_unique($supplierIds)))] ); + $facets['referenceComponent'] = self::withDefinitions(buckets: $facets['referenceComponent'], definitions: $definitions); $matchedObjectIds = $this->filterObjectIds( dimValsByObjId: $dimValsByObjId, @@ -714,15 +715,17 @@ private function fetchModulesByIdentifiers(ObjectServiceInterface $objectService * Build the per-object GEMMA dimension value map: for every base object, * the set of referenceComponent/standard names it carries directly, and * the set of domain/applicationService names resolved transitively via its - * linked `element` objects. + * linked `element` objects. From the same element lookup, the GEMMA + * definition of each referenceComponent value by its display name. * * @param array> $modulesByObjectId Object id => module objects. * - * @return array> Object id => dimension => distinct values. + * @return array{0: array>, 1: array} * * @spec openspec/specs/gemma-faceted-search/spec.md#requirement-facet-aggregation-endpoint-returns-gemma-dimension-counts + * @spec openspec/changes/gemma-plate-views-peers-and-definitions/specs/gemma-plate/spec.md#requirement-gemma-terms-show-their-definition-where-they-appear-req-gpl-003 */ - private function buildDimensionValueMap(array $modulesByObjectId): array { + private function dimensionValuesAndDefinitions(array $modulesByObjectId): array { // Pass 1: direct fields (referenceComponent identifiers + standard identifiers). $direct = array_map(fn (array $modules): array => $this->directDimensions(modules: $modules), $modulesByObjectId); $allRefCompIds = array_values(array_unique(array_merge([], ...array_values(array_column($direct, 'refCompIds'))))); @@ -739,8 +742,77 @@ private function buildDimensionValueMap(array $modulesByObjectId): array { ); // Assemble the final per-object dimension map. - return array_map(fn (array $values): array => $this->objectDimensions(resolution: $resolution, direct: $values), $direct); - }//end buildDimensionValueMap() + return [ + array_map(fn (array $values): array => $this->objectDimensions(resolution: $resolution, direct: $values), $direct), + $this->definitionsByName(elementsById: $elementsById, refCompIds: $allRefCompIds), + ]; + }//end dimensionValuesAndDefinitions() + + /** + * The GEMMA definition and GEMMA Online link of each referenceComponent, + * by the display name its facet value carries. The first element with a + * name keeps it. + * + * @param array $elementsById Element identifier => element object. + * @param array $refCompIds The referenceComponent identifiers. + * + * @return array + * + * @spec openspec/changes/gemma-plate-views-peers-and-definitions/specs/gemma-plate/spec.md#requirement-gemma-terms-show-their-definition-where-they-appear-req-gpl-003 + */ + private function definitionsByName(array $elementsById, array $refCompIds): array { + $definitions = []; + foreach ($refCompIds as $refCompId) { + $element = ($elementsById[$refCompId] ?? []); + $name = $this->elementDisplayName(element: $element, fallbackIdentifier: $refCompId); + if (isset($definitions[$name]) === true) { + continue; + } + + $definitions[$name] = [ + 'documentation' => self::trimmedString(value: ($element['documentation'] ?? null)), + 'gemmaUrl' => self::trimmedString(value: ($element['gemmaUrl'] ?? null)), + ]; + } + + return $definitions; + }//end definitionsByName() + + /** + * A value as a trimmed string, '' when it is not a string. + * + * @param mixed $value The value. + * + * @return string The string. + */ + private static function trimmedString(mixed $value): string { + if (is_string($value) === true) { + return trim($value); + } + + return ''; + }//end trimmedString() + + /** + * The referenceComponent buckets, each with its GEMMA definition and + * GEMMA Online link ('' when the element has none). + * + * @param array $buckets The buckets. + * @param array $definitions By display name. + * + * @return array + * + * @spec openspec/changes/gemma-plate-views-peers-and-definitions/specs/gemma-plate/spec.md#requirement-gemma-terms-show-their-definition-where-they-appear-req-gpl-003 + */ + private static function withDefinitions(array $buckets, array $definitions): array { + return array_map( + static fn (array $bucket): array => array_merge( + $bucket, + ($definitions[$bucket['value']] ?? ['documentation' => '', 'gemmaUrl' => '']) + ), + $buckets + ); + }//end withDefinitions() /** * The referenceComponent identifiers and the standard names an object's modules carry, each distinct. diff --git a/openspec/changes/gemma-plate-views-peers-and-definitions/tasks.md b/openspec/changes/gemma-plate-views-peers-and-definitions/tasks.md index 6d276471e..bdfa3a0ab 100644 --- a/openspec/changes/gemma-plate-views-peers-and-definitions/tasks.md +++ b/openspec/changes/gemma-plate-views-peers-and-definitions/tasks.md @@ -47,8 +47,8 @@ - GIVEN the reference component facet WHEN it renders THEN each value has an information button whose popover shows the name, "from GEMMA", `element.documentation` and a "More in GEMMA Online" link to `element.gemmaUrl` - GIVEN the facet endpoint WHEN it returns reference component buckets THEN each bucket carries `documentation` and `gemmaUrl` - GIVEN a component without documentation WHEN its popover opens THEN only the name and the link show -- [ ] Implement -- [ ] Test (vitest `gemmaDefinitionPopover.spec.js`, PHPUnit `FacetServiceDefinitionTest`) +- [x] Implement +- [x] Test (vitest `gemmaDefinitionPopover.spec.js`, PHPUnit `FacetServiceDefinitionTest`) ### Task 6: Documentation and matrix - **spec_ref**: openspec/changes/gemma-plate-views-peers-and-definitions/specs/gemma-plate/spec.md diff --git a/src/components/gemma/GemmaDefinitionPopover.vue b/src/components/gemma/GemmaDefinitionPopover.vue new file mode 100644 index 000000000..299ee3fec --- /dev/null +++ b/src/components/gemma/GemmaDefinitionPopover.vue @@ -0,0 +1,120 @@ + + + + + + + + + diff --git a/src/views/FacetedCatalogIndexView.vue b/src/views/FacetedCatalogIndexView.vue index 9f2f62a06..11bebb9fc 100644 --- a/src/views/FacetedCatalogIndexView.vue +++ b/src/views/FacetedCatalogIndexView.vue @@ -44,6 +44,12 @@ generic route-query-to-filter passthrough never sees it (see the @spec openspec/specs/gemma-faceted-search/spec.md#requirement-filter-state-is-url-encoded-and-deep-linkable @spec openspec/specs/gemma-faceted-search/spec.md#requirement-a-facet-selection-can-be-saved-as-a-view @spec openspec/specs/bio-compliance-assessment/spec.md#requirement-catalog-can-be-filtered-by-bbn-level-and-dpia-status + +Under the sidebar, each reference component value of the facet has an +information button whose popover shows its GEMMA definition and a link to +GEMMA Online, from the `documentation` and `gemmaUrl` the facet buckets carry +(the library sidebar lists the values in a select, which has no place for it). +@spec openspec/changes/gemma-plate-views-peers-and-definitions/specs/gemma-plate/spec.md#requirement-gemma-terms-show-their-definition-where-they-appear-req-gpl-003 -->