diff --git a/docs/features/README.md b/docs/features/README.md index 30f3af676..57bcfdf4b 100644 --- a/docs/features/README.md +++ b/docs/features/README.md @@ -38,7 +38,7 @@ All data is stored as OpenRegister objects (no own database tables). OpenRegiste | [Health and metrics](observability.md) | A public health check for uptime probes and Prometheus metrics for administrators, configured in the manifest | | [Open Data Publishing](#open-data-publishing) | Expose the catalogue as a public open-data API | | [GEMMA Compliance](#gemma-compliance) | Built around VNG GEMMA Softwarecatalogus reference | -| [Reference Component Coverage](reference-component-coverage.md) | Which GEMMA reference components an organisation covers, where it has gaps and where applications overlap | +| [Reference Component Coverage](reference-component-coverage.md) | Which GEMMA reference components an organisation covers, where it has gaps and where applications overlap, per GEMMA view, with what comparable organisations use | | [Catalogue Exports and Custom Reports](catalogue-exports-and-reports.md) | Export lists, faceted lists and one organisation as ArchiMate, and define your own reports | ## Software Registration diff --git a/docs/features/reference-component-coverage.md b/docs/features/reference-component-coverage.md index 9300a15ab..395d5a2ef 100644 --- a/docs/features/reference-component-coverage.md +++ b/docs/features/reference-component-coverage.md @@ -10,8 +10,10 @@ applications in use cover, where it has a gap and where two or more applications cover the same component. It answers the information manager's question "where are we missing something, and where do we have too much?" -Specification: -[`openspec/changes/architecture-reference-component-coverage/specs/reference-component-coverage/spec.md`](https://github.com/ConductionNL/stackiq/blob/development/openspec/changes/architecture-reference-component-coverage/specs/reference-component-coverage/spec.md). +Specifications: +[`reference-component-coverage`](https://github.com/ConductionNL/stackiq/blob/development/openspec/changes/architecture-reference-component-coverage/specs/reference-component-coverage/spec.md) +and +[`gemma-plate`](https://github.com/ConductionNL/stackiq/blob/development/openspec/changes/gemma-plate-views-peers-and-definitions/specs/gemma-plate/spec.md). > Screenshots of the coverage table, the map and the Overlap section are > still pending a live-instance capture; the Playwright-captured images @@ -53,6 +55,26 @@ then says "Import the GEMMA model to see coverage." instead of an empty table. - a detail panel for the chosen component, naming the applications in use that could fill a fillable gap. +### Grouping the plate by a GEMMA view + +The **GEMMA view** picker lists the GEMMA views imported with the GEMMA model, each with its GEMMA release when the import recorded one. Pick a view, for example *GEMMA Applicatiearchitectuur, gemeentebreed*, and the plate draws that view's reference components in the view's own groups (such as Front-office, Mid-office, Back-office en basisregistraties), each with its state and the organisation's applications. Clear the picker to see the whole model grouped by the components' own GEMMA grouping. + +The chosen view is kept in the address as `?view=`, so a link opens the same plate. Without an imported GEMMA model the picker is empty and the page says the model is needed. + +### What comparable organisations use + +Under **Layers**, switch on **What comparable organisations use**. The table below the plate then shows per reference component your own applications and the applications comparable organisations use for it, with how many organisations use each. Select a component on the plate and its side panel lists the same applications with their counts, so a gap shows what others fill it with. + +Comparable means the same organisation type (for example municipality) and the same inhabitants band: under 30,000; 30,000 to 60,000; 60,000 to 100,000; 100,000 to 250,000; above 250,000. Set the number of inhabitants on the organisation's page. An organisation without that number is compared with every organisation of its type. The table's heading names the type and band compared with. + +#### The anonymity rule + +The counts are computed on the server over all usages, and the answer never contains another organisation's id or name. An application used by fewer than 3 comparable organisations shows **fewer than 3** instead of a count, so a single organisation's choice cannot be read off the table. Only members of the organisation can open its comparison. + +### GEMMA definitions in place + +Select a reference component on the plate and the side panel shows its GEMMA definition. On the **Applications** and **Services** pages, the list *What the reference components are* under the GEMMA filters gives each reference component an information button. It opens the component's name *from GEMMA*, its definition, and a link **More in GEMMA Online**. A component without a definition shows only its name and the link. + ### Coverage on a GEMMA view Below the plate, **Coverage on a GEMMA view** lets the user pick an imported diff --git a/l10n/en.js b/l10n/en.js index a6a52ac38..ddebe40d5 100644 --- a/l10n/en.js +++ b/l10n/en.js @@ -2280,6 +2280,25 @@ OC.L10N.register( "{due} of {total} people are due for review. A review is due when access was not reviewed in the last {days} days.": "{due} of {total} people are due for review. A review is due when access was not reviewed in the last {days} days.", "{role} removed from {person}": "{role} removed from {person}", "Review": "Review", + "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.", + "{min} to {max} inhabitants": "{min} to {max} inhabitants", + "{name} ({count})": "{name} ({count})", + "{name} (fewer than {min})": "{name} (fewer than {min})", + "above {min} inhabitants": "above {min} inhabitants", + "Comparable organisations use": "Comparable organisations use", + "Comparable organisations: {count}": "Comparable organisations: {count}", + "Layers": "Layers", + "Own applications": "Own applications", + "under {max} inhabitants": "under {max} inhabitants", + "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}", + "{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", "blocked by the SSRF guard": "blocked by the SSRF guard", "Error: {reason}": "Error: {reason}", "Last pulled {date}": "Last pulled {date}", diff --git a/l10n/en.json b/l10n/en.json index 5d680676c..3c4aa4e85 100644 --- a/l10n/en.json +++ b/l10n/en.json @@ -2321,6 +2321,25 @@ "{due} of {total} people are due for review. A review is due when access was not reviewed in the last {days} days.": "{due} of {total} people are due for review. A review is due when access was not reviewed in the last {days} days.", "{role} removed from {person}": "{role} removed from {person}", "Review": "Review", + "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.", + "{min} to {max} inhabitants": "{min} to {max} inhabitants", + "{name} ({count})": "{name} ({count})", + "{name} (fewer than {min})": "{name} (fewer than {min})", + "above {min} inhabitants": "above {min} inhabitants", + "Comparable organisations use": "Comparable organisations use", + "Comparable organisations: {count}": "Comparable organisations: {count}", + "Layers": "Layers", + "Own applications": "Own applications", + "under {max} inhabitants": "under {max} inhabitants", + "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}", + "{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", "blocked by the SSRF guard": "blocked by the SSRF guard", "Error: {reason}": "Error: {reason}", "Last pulled {date}": "Last pulled {date}", diff --git a/l10n/nl.js b/l10n/nl.js index f41462311..a005a4cb0 100644 --- a/l10n/nl.js +++ b/l10n/nl.js @@ -2342,6 +2342,25 @@ OC.L10N.register( "on the contact person": "op de contactpersoon", "{due} of {total} people are due for review. A review is due when access was not reviewed in the last {days} days.": "{due} van {total} personen moeten worden beoordeeld. Een beoordeling is nodig als de toegang niet in de afgelopen {days} dagen is beoordeeld.", "{role} removed from {person}": "{role} verwijderd bij {person}", + "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.", + "{min} to {max} inhabitants": "{min} tot {max} inwoners", + "{name} ({count})": "{name} ({count})", + "{name} (fewer than {min})": "{name} (minder dan {min})", + "above {min} inhabitants": "meer dan {min} inwoners", + "Comparable organisations use": "Vergelijkbare organisaties gebruiken", + "Comparable organisations: {count}": "Vergelijkbare organisaties: {count}", + "Layers": "Lagen", + "Own applications": "Eigen applicaties", + "under {max} inhabitants": "minder dan {max} inwoners", + "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}", + "{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", "blocked by the SSRF guard": "geblokkeerd door de SSRF-beveiliging", "Error: {reason}": "Fout: {reason}", "Last pulled {date}": "Laatst opgehaald {date}", diff --git a/l10n/nl.json b/l10n/nl.json index 57b0d265d..a9d82adbf 100644 --- a/l10n/nl.json +++ b/l10n/nl.json @@ -2383,6 +2383,25 @@ "on the contact person": "op de contactpersoon", "{due} of {total} people are due for review. A review is due when access was not reviewed in the last {days} days.": "{due} van {total} personen moeten worden beoordeeld. Een beoordeling is nodig als de toegang niet in de afgelopen {days} dagen is beoordeeld.", "{role} removed from {person}": "{role} verwijderd bij {person}", + "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.", + "{min} to {max} inhabitants": "{min} tot {max} inwoners", + "{name} ({count})": "{name} ({count})", + "{name} (fewer than {min})": "{name} (minder dan {min})", + "above {min} inhabitants": "meer dan {min} inwoners", + "Comparable organisations use": "Vergelijkbare organisaties gebruiken", + "Comparable organisations: {count}": "Vergelijkbare organisaties: {count}", + "Layers": "Lagen", + "Own applications": "Eigen applicaties", + "under {max} inhabitants": "minder dan {max} inwoners", + "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}", + "{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", "blocked by the SSRF guard": "geblokkeerd door de SSRF-beveiliging", "Error: {reason}": "Fout: {reason}", "Last pulled {date}": "Laatst opgehaald {date}", diff --git a/lib/Service/FacetService.php b/lib/Service/FacetService.php index 995852d33..65b06294f 100644 --- a/lib/Service/FacetService.php +++ b/lib/Service/FacetService.php @@ -255,7 +255,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). @@ -272,6 +272,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, @@ -740,15 +741,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'))))); @@ -765,8 +768,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 73f3791e1..a9d5fbf13 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 @@ -37,7 +37,7 @@ - **acceptance_criteria**: - GIVEN the Layers control WHEN "What comparable organisations use" is switched on THEN the table shows per component the own applications and the peer applications with counts, under a heading naming the band - GIVEN a selected component WHEN the side panel renders THEN it lists the peer applications with counts -- [ ] Implement +- [x] Implement - [ ] Test (vitest `peerUsageTable.spec.js`, Playwright `gemma-plate-peers.spec.ts`) ### Task 5: Definitions in the reference component facet @@ -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 @@ -56,4 +56,4 @@ - **acceptance_criteria**: - GIVEN the feature doc WHEN read THEN it explains the view picker, the comparable organisations layer and the anonymity rule - GIVEN the tasks are done WHEN the change is archived THEN the three rows move back to built with new evidence -- [ ] Implement +- [x] Implement 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/components/gemma/PeerUsageTable.vue b/src/components/gemma/PeerUsageTable.vue new file mode 100644 index 000000000..b79e13934 --- /dev/null +++ b/src/components/gemma/PeerUsageTable.vue @@ -0,0 +1,237 @@ + + + + + + + + + diff --git a/src/components/gemma/peerLabel.js b/src/components/gemma/peerLabel.js new file mode 100644 index 000000000..2ba4da2d3 --- /dev/null +++ b/src/components/gemma/peerLabel.js @@ -0,0 +1,24 @@ +// SPDX-License-Identifier: EUPL-1.2 +// Copyright (C) 2026 Conduction B.V. + +import { translate as t } from '@nextcloud/l10n' +import { isHeldBack } from '../../utils/peerUsage.js' + +/** + * A peer application with its count, or "fewer than 3" when the endpoint + * holds the count back. + * + * @param {object} application A peer application. + * @return {string} The label. + * @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 + */ +export function peerLabel(application) { + const name = String(application?.moduleName || t('stackiq', 'Unnamed application')) + if (isHeldBack(application)) { + return t('stackiq', '{name} (fewer than {min})', { + name, + min: Number(application?.fewerThan || 3), + }) + } + return t('stackiq', '{name} ({count})', { name, count: application.count }) +} diff --git a/src/utils/peerUsage.js b/src/utils/peerUsage.js new file mode 100644 index 000000000..2c79220de --- /dev/null +++ b/src/utils/peerUsage.js @@ -0,0 +1,42 @@ +// SPDX-License-Identifier: EUPL-1.2 +// Copyright (C) 2026 Conduction B.V. + +/** + * The peer applications per reference component, from the peers endpoint. + * + * @param {object|null} peers The answer of `GET /api/reference-component-coverage/peers`. + * @return {Map>} The applications by reference component id. + * @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 + */ +export function peerIndex(peers) { + const index = new Map() + for (const row of peers?.components || []) { + if (row?.referenceComponent) { + index.set(String(row.referenceComponent), row.applications || []) + } + } + return index +} + +/** + * The peer applications of one coverage row: by its id, else its identifier. + * + * @param {Map>} index From peerIndex(). + * @param {object} component A coverage row. + * @return {Array} The applications, most used first. + * @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 + */ +export function peerApplicationsOf(index, component) { + return index.get(String(component?.id ?? '')) || index.get(String(component?.identifier ?? '')) || [] +} + +/** + * Whether a peer count is held back because fewer organisations share it. + * + * @param {object} application A peer application. + * @return {boolean} True when the count is shown as "fewer than". + * @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 + */ +export function isHeldBack(application) { + return application?.count === null || application?.count === undefined +} diff --git a/src/utils/referenceComponentCoverage.js b/src/utils/referenceComponentCoverage.js index ec6d5ed88..36a9cfc93 100644 --- a/src/utils/referenceComponentCoverage.js +++ b/src/utils/referenceComponentCoverage.js @@ -29,13 +29,27 @@ export function filterCoverage(components, filter) { * @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 */ export function groupCoverage(components, fallback) { + return groupsInOrder( + components.map((component) => [component.group || '', component]), + fallback, + ) +} + +/** + * Rows in named groups, in the order the rows come, with the rows of the + * unnamed group ('') last under one fallback name. + * + * @param {Array<[string, object]>} entries Pairs of group name and row. + * @param {string} fallback The name for rows without a group. + * @return {Array<{name: string, components: Array}>} Groups. + */ +function groupsInOrder(entries, fallback) { const groups = new Map() - for (const component of components) { - const name = component.group || '' + for (const [name, row] of entries) { if (!groups.has(name)) { groups.set(name, []) } - groups.get(name).push(component) + groups.get(name).push(row) } const named = [...groups.entries()] .filter(([name]) => name !== '') @@ -137,18 +151,194 @@ export function coverageMapGraph(viewNodes = [], viewRelationships = [], compone } /** - * The GEMMA views a picker offers: id and name, by name. + * A view's id, whichever shape the views endpoint gives it in. * - * @param {Array} views The views from `GET /api/views`. - * @return {Array<{id: string, label: string}>} The options. - * @spec openspec/changes/architecture-reference-component-coverage/specs/reference-component-coverage/spec.md#requirement-req-rcc-003-the-coverage-shall-be-drawn-on-a-gemma-view-as-a-map + * @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 viewOptions(views = []) { +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 (Array.isArray(views) ? views : []) .map((view) => { - const id = String(view?.id ?? view?.uuid ?? view?.['@self']?.id ?? '') - return { id, label: String(view?.name || view?.title || id) } + 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 = rowsByKey(components) + + const entries = [] + const seen = new Set() + for (const node of nodes) { + const ref = node.modelNodeId || node.elementRef + const row = ref && !parents.has(node.viewNodeId) && !seen.has(ref) + ? rows.get(ref) || usageRow(node, ref) + : null + if (row) { + seen.add(ref) + entries.push([groupName(node, byNodeId), row]) + } + } + + return groupsInOrder(entries, fallback) +} + +/** + * Coverage rows by their element identifier and by their id, the first row + * of a key winning. + * + * @param {Array} components Coverage rows. + * @return {Map} The rows by key. + */ +function rowsByKey(components) { + 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) + } + } + } + return rows +} + +/** + * 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/FacetedCatalogIndexView.vue b/src/views/FacetedCatalogIndexView.vue index 1584a30d4..cf5780b4f 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 -->