Version 0.6.0

Migration guide

New <lens-query-explain-button> component

In earlier versions of Lens, we used a specialized version of the <lens-info-button> to display the current query or a portion of it. This functionality has now been refactored into the dedicated <lens-query-explain-button> component. Update your app as follows:

-<lens-info-button noQueryMessage="Empty Query" showQuery={true}></lens-info-button>
+<lens-query-explain-button noQueryMessage="Empty Query"></lens-query-explain-button>

Querying the backend

In the new version, Lens will no longer query backends itself when the search button is clicked. Instead, the application must read the current query from the search bar, send the query to a backend to get results, and then pass the results to Lens so it can show them.

To give a short summary of the new paradigm, the application listens to the global lens-search-triggered event, then retrieves the current query using the new getAst function, optionally uses the new querySpot function to send the query to a backend, and then passes the results to Lens via the new markSiteClaimed and setSiteResult functions. More details and example code can be found in the Querying a backend and Showing results guides.

The setSiteResult function accepts the new LensResult format that is independent of the FHIR standard. The latest version of Focus can return the new result format directly. If you have a FHIR result you can convert to the new format using the measureReportToLensResult function.

A number of related APIs have been removed in favor of the new paradigm:

• The backend field has been removed from the Lens options
• The emit-lens-query event has been renamed to lens-search-triggered and does no longer contain the details field
• The lens-responses-updated event has been removed

Catalogue prop changes

If you are using the collapsible catalogue feature, the texts for the expand/collapse button are now no longer specified as props:

 <lens-catalogue
-    texts={{
-        collapseButtonTitle: 'My custom expand text',
-        expandButtonTitle: 'My custom collapse text',
-    }}
     toggle={{ collapsable: true }}
 ></lens-catalogue>

If you specified any other texts in the texts prop you can remove them as well as they are no longer used. The expand/collapse button texts are now specified in the Lens options as translations:

"texts": {
    "catalogue_expand": {
        "en": "My custom expand text"
    },
    "catalogue_collapse": {
        "en": "My custom collapse text"
    },
}

The treeData prop previously used to provide the catalogue to Lens has been removed. Use the setCatalogue function instead.

CSS class name prefixes updated

Starting with version 0.6.0, all Lens CSS class names now begin with the prefix lens- followed by the component name. This change improves readability, provides clearer structure, and helps avoid unintentional conflicts with existing styles or overrides.

If you are overriding any Lens component styles, please review your class names to ensure they match the new naming convention.

Query in URL

The URL now always updates to stay in sync with the current query so can share and bookmark queries via the URL. You can disable this in the Lens options:

"autoUpdateQueryInUrl": false

Removed iconOptions

Because this feature was rarely used icons in Lens can no longer be customized. Remove these lines from your Lens options:

"iconOptions": {
  "deleteUrl": "delete_icon.svg",
  "infoUrl": "info-circle-svgrepo-com.svg",
  "toggleIconUrl": "right-arrow-svgrepo-com.svg",
  "addIconUrl": "long-right-arrow-svgrepo-com.svg"
},

You can also remove the icon image files if your app does not use them anywhere else.

Removed <lens-data-passer>

The <lens-data-passer> component which was previously used to access a number of APIs has been removed. Most of these APIs have now been exported as regular TypeScript functions and some have been deprecated:

Removed <lens-options> component

The <lens-options> component has been removed. Instead use the setOptions and setCatalogue functions. When removing the <lens-options> tag you should also be able to remove the {#await} block that was needed previously. For example:

 <script>
+    import {
+        setOptions,
+        setCatalogue,
+        type LensOptions,
+        type Catalogue,
+    } from "@samply/lens";
+    import options from "./config/options.json";
+    import catalogue from "./config/catalogue.json";
+    onMount(() => {
+        setOptions(options as LensOptions);
+        setCatalogue(catalogue as Catalogue);
+    });
-    const jsonPromises = fetchData(optionsUrl, catalogueUrl);
 </script>

-{#await jsonPromises}
-    <!-- render a loading spinner -->
-{:then { optionsJSON, catalogueJSON }}
-    <lens-options {catalogueJSON} {optionsJSON} {measures}></lens-options>
-{:catch someError}
-    <!-- render the error -->
-{/await}

Renamed types

We've renamed some types to indicate that they are specific to the FHIR standard:

Facet counts use spotUrl

Facet counts now use the spotUrl from the Lens options with /prism automatically appended:

+"spotUrl": "https://locator-dev.bbmri-eric.eu/backend",
 "facetCount": {
-    "backendUrl": "https://locator-dev.bbmri-eric.eu/backend/prism",
     "hoverText": {
         "gender": "Matching patients for this criterion only",
         ...
     }
 },

Removal of catalogueKeyToResponseKeyMap option

In previous versions catalogueKeyToResponseKeyMap was used in the <lens-chart> component to map catalogue keys to response keys with different names. The map has been removed and the <lens-chart> component now takes the data key directly. Remove the map in the Lens options:

-"catalogueKeyToResponseKeyMap": [
-    [
-        "age_at_diagnosis",
-        "donor_age"
-    ],
-]

And update your usage of <lens-chart> accordingly:

-<lens-chart catalogueGroupCode="age_at_diagnosis">
+<lens-chart dataKey="donor_age">