experimental(highlight-data): Highlight data if it has a special qualifier (#491)

hofermo · web-flow · commit 1d7a77a58b37 · 2025-11-03T17:04:36.000+01:00
* experimental(highlight-data)

* Add comments and docu
diff --git a/src/app/EnvProvider.tsx b/src/app/EnvProvider.tsx
@@ -38,6 +38,7 @@ export const initialEnvValues: EnvironmentalVariables = {
     KEYCLOAK_REALM: undefined,
     KEYCLOAK_CLIENT_ID: undefined,
     SERIALIZATION_API_URL: undefined,
+    EXPERIMENTAL_HIGHLIGHT_DATA_FLAG: false,
 };
 
 const EnvContext = createContext(initialEnvValues);
diff --git a/src/app/[locale]/viewer/_components/HighlightBoxExperimental.tsx b/src/app/[locale]/viewer/_components/HighlightBoxExperimental.tsx
@@ -0,0 +1,71 @@
+import { Box } from '@mui/system';
+import { Qualifiable } from 'lib/api/aas/models';
+
+/**
+ * Retrieves highlighting information from a qualifiable object.
+ * 
+ * @param qualifiable - The qualifiable object to extract highlighting information from
+ *      Qualifier needs to be of type "HighlightColor"
+ * @returns An object containing:
+ *   - `highlight`: Boolean indicating whether highlighting should be applied
+ *   - `highlightColor`: The color value for highlighting, or empty string if no highlighting
+ * 
+ * @remarks
+ * Searches for a qualifier with type 'HighlightColor' in the qualifiable's qualifiers array.
+ * If no qualifiers exist or no matching qualifier is found, returns default non-highlight values.
+ */
+const getHighlighting = (qualifiable: Qualifiable) => {
+    const noHighlight = {
+        highlight: false,
+        highlightColor: '',
+    };
+    if (!qualifiable?.qualifiers) {
+        return noHighlight;
+    }
+
+    const qualifier = qualifiable.qualifiers.find((qualifiable) => {
+        return qualifiable.type === 'HighlightColor';
+    });
+
+    if (!qualifier || !qualifier.value) {
+        return noHighlight;
+    }
+    return {
+        highlight: true,
+        highlightColor: qualifier.value,
+    };
+};
+
+/**
+ * Renders a colored highlight box based on qualifier data.
+ * 
+ * @param highlightData - Boolean flag to enable/disable highlight rendering
+ * @param property - The qualifiable property containing potential highlight qualifier information
+ * @returns A JSX element with a colored box if highlighting is enabled and valid, otherwise null
+ * 
+ * @remarks
+ * This is an experimental feature that displays a vertical colored bar (8px wide, 1.5em high)
+ * when all conditions are met: highlightData is true, property is defined, and a valid
+ * HighlightColor qualifier exists.
+ */
+export const renderHighlight = (highlightData: boolean, property: Qualifiable | undefined) => {
+    const highlighting = property ? getHighlighting(property) : { highlight: false, highlightColor: '' };
+    return (
+        highlightData &&
+        property &&
+        highlighting.highlight && (
+            // EXPERIMENTAL FEATURE
+            <Box
+                sx={{
+                    width: '8px',
+                    borderRadius: '2px',
+                    backgroundColor: highlighting.highlightColor,
+                    marginRight: '12px',
+                    height: '1.5em',
+                    flexShrink: 0,
+                }}
+            />
+            // ----
+        )
+    );
+};
diff --git a/src/app/[locale]/viewer/_components/submodel-elements/generic-elements/GenericPropertyComponent.tsx b/src/app/[locale]/viewer/_components/submodel-elements/generic-elements/GenericPropertyComponent.tsx
@@ -1,5 +1,10 @@
 import { Box, IconButton, Link, Skeleton, Tooltip, Typography } from '@mui/material';
-import { MultiLanguageProperty, Property, Range, ConceptDescription } from 'lib/api/aas/models';
+import {
+    MultiLanguageProperty,
+    Property,
+    Range,
+    ConceptDescription,
+} from 'lib/api/aas/models';
 import { getTranslationText } from 'lib/util/SubmodelResolverUtil';
 import { isValidUrl } from 'lib/util/UrlUtil';
 import { ContentCopy, OpenInNew } from '@mui/icons-material';
@@ -8,6 +13,8 @@ import { useNotificationSpawner } from 'lib/hooks/UseNotificationSpawner';
 import { useLocale } from 'use-intl';
 import { useTranslations } from 'next-intl';
 import { getUnitFromConceptDescription } from 'app/[locale]/viewer/_components/submodel/technical-data/ConceptDescriptionHelper';
+import { useEnv } from 'app/EnvProvider';
+import { renderHighlight } from '../../HighlightBoxExperimental';
 
 type GenericPropertyComponentProps = {
     readonly property?: Property;
@@ -28,6 +35,8 @@ export function GenericPropertyComponent(props: GenericPropertyComponentProps) {
     const locale = useLocale();
     const [isHovered, setIsHovered] = useState(false);
     const notificationSpawner = useNotificationSpawner();
+    const env = useEnv();
+    const highlightData = env.EXPERIMENTAL_HIGHLIGHT_DATA_FLAG;
 
     let value: string | null = null;
     if (mLangProp) {
@@ -115,6 +124,7 @@ export function GenericPropertyComponent(props: GenericPropertyComponentProps) {
             onMouseEnter={() => setIsHovered(true)}
             onMouseLeave={() => setIsHovered(false)}
         >
+            {renderHighlight(highlightData, property)}
             <Typography data-testid="property-content">
                 {value || t('labels.notAvailable')}
                 <span> </span>
diff --git a/src/app/[locale]/viewer/_components/submodel-elements/generic-elements/MultiLanguagePropertyComponent.tsx b/src/app/[locale]/viewer/_components/submodel-elements/generic-elements/MultiLanguagePropertyComponent.tsx
@@ -7,6 +7,8 @@ import { useNotificationSpawner } from 'lib/hooks/UseNotificationSpawner';
 import { useLocale } from 'use-intl';
 import { useTranslations } from 'next-intl';
 import { MultiLanguageProperty } from 'lib/api/aas/models';
+import { useEnv } from 'app/EnvProvider';
+import { renderHighlight } from '../../HighlightBoxExperimental';
 
 type MultiLanguagePropertyComponentProps = {
     readonly mLangProp: MultiLanguageProperty;
@@ -19,6 +21,8 @@ export function MultiLanguagePropertyComponent(props: MultiLanguagePropertyCompo
     const value = getTranslationText(mLangProp, locale);
     const [isHovered, setIsHovered] = useState(false);
     const notificationSpawner = useNotificationSpawner();
+    const env = useEnv();
+    const highlightData = env.EXPERIMENTAL_HIGHLIGHT_DATA_FLAG;
 
     const handleCopyValue = () => {
         if (value) {
@@ -72,6 +76,7 @@ export function MultiLanguagePropertyComponent(props: MultiLanguagePropertyCompo
             onMouseEnter={() => setIsHovered(true)}
             onMouseLeave={() => setIsHovered(false)}
         >
+            {renderHighlight(highlightData, props.mLangProp)}
             <Typography data-testid="mlproperty-content">{value || '-'}</Typography>
             {renderCopyButton()}
         </Box>
diff --git a/src/components/basics/VerticalTabSelector.tsx b/src/components/basics/VerticalTabSelector.tsx
@@ -4,6 +4,8 @@ import { ReactElement, useState } from 'react';
 import { Submodel } from 'lib/api/aas/models';
 import { useTranslations } from 'next-intl';
 import { useIsMobile } from 'lib/hooks/UseBreakpoints';
+import { useEnv } from 'app/EnvProvider';
+import { renderHighlight } from 'app/[locale]/viewer/_components/HighlightBoxExperimental';
 
 export type TabSelectorItem = {
     readonly id: string;
@@ -87,6 +89,8 @@ export function VerticalTabSelector(props: VerticalTabSelectorProps) {
     const [hoveredItem, setHoveredItem] = useState<TabSelectorItem>();
     const isMobile = useIsMobile();
     const t = useTranslations('components.verticalTabSelector.errors');
+    const env = useEnv();
+    const highlightData = env.EXPERIMENTAL_HIGHLIGHT_DATA_FLAG;
 
     const selectedCSSClass = (id: string) => (id === props.selected?.id ? 'selected' : '');
 
@@ -135,6 +139,8 @@ export function VerticalTabSelector(props: VerticalTabSelectorProps) {
                                     flex: 1,
                                 }}
                             >
+                                {renderHighlight(highlightData, item.submodelData)}
+
                                 <Typography
                                     sx={{
                                         overflow: 'hidden',
diff --git a/src/lib/env/MnestixEnv.ts b/src/lib/env/MnestixEnv.ts
@@ -49,6 +49,7 @@ const featureFlags = mapEnvVariables(
         'WHITELIST_FEATURE_FLAG',
         'KEYCLOAK_ENABLED',
         'BASYX_RBAC_ENABLED',
+        'EXPERIMENTAL_HIGHLIGHT_DATA_FLAG'
     ] as const,
     parseFlag,
 );
diff --git a/wiki/Mnestix-Configuration-Settings.md b/wiki/Mnestix-Configuration-Settings.md
@@ -28,6 +28,12 @@ Mnestix provides the following configuration options. You can adapt the values i
 | `WHITELIST_FEATURE_FLAG`             | false                  | Enables or disables the feature for showing/hiding specific submodels.                                                                                                                        |
 | `SUBMODEL_WHITELIST`                 |                        | This variable can be used to specify a list of submodel semantic ids in order to show them when the `WHITELIST_FEATURE_FLAG` is set to true.                                                  |
 
+#### Experimental Features
+
+| Name                               | Default value | Description                                                                                                                                                                                                                                                                        |
+| ---------------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `EXPERIMENTAL_HIGHLIGHT_DATA_FLAG` | false | Enables highlighting of specific submodels, properties, and multilang properties rendered with the default/fallback visualization. When enabled, elements can be visually emphasized using a `HighlightColor` qualifier. Example qualifier configuration: `{"kind": "ValueQualifier", "type": "HighlightColor", "value": "rgb(255,0,0)", "valueType": "xs:string"}`. For visual examples, see [PR #491](https://github.com/eclipse-mnestix/mnestix-browser/pull/491). |
+
 #### Keycloak
 
 See [Keycloak Configuration](Keycloak-Configuration) for more information about the Keycloak setup.
