fix: label the app chip rows and render manifest icons in them

JanCizmar · JanCizmar · commit 72a38f389e3f · 2026-08-05T12:57:23.000+02:00
The app rows showed two unlabelled chip rows, so nothing told the user that
one lists the pages the app adds to the project menu and the other the
permissions it was granted. Both rows now carry a caption with an
explanatory tooltip, and say so when they are empty.

The page chips also concatenated the manifest icon into the label, which
rendered a native icon name ("Key01") as literal text. They now go through
AppIcon like the project menu does. AppIcon only forces a size when one is
given, so an app icon in the menu matches the built-in items instead of
rendering smaller, and the emoji fallback follows the same size.
diff --git a/apps/tolgee-apps-sdk/README.md b/apps/tolgee-apps-sdk/README.md
@@ -58,6 +58,10 @@ const manifest: AppManifest = {
 }
 ```
 
+`icon` is either a name from the platform icon set or an emoji (`'🔑'`). A name has to
+match an exported icon component exactly — `Key01`, not `Key`. Anything the platform
+does not recognise is rendered as literal text, so a typo shows up as the name itself.
+
 Ship the manifest as a template with a `__BASE_URL__` placeholder and render it
 per request, so the URL can change between dev restarts (tunnels) without
 editing the file:
diff --git a/apps/tolgee-apps-sdk/src/shared/manifestTypes.ts b/apps/tolgee-apps-sdk/src/shared/manifestTypes.ts
@@ -32,7 +32,11 @@ export type AppDashboardPage = {
   key: string
   /** Menu item label. */
   title: string
-  /** Named icon from the platform icon set (e.g. `LayoutAlt04`). */
+  /**
+   * Either a named icon from the platform icon set or an emoji. A name must match an
+   * exported icon component exactly (`Key01`, not `Key`); anything the platform does
+   * not recognise is rendered as literal text.
+   */
   icon: string
   /** Route the iframe loads, relative to `baseUrl`. */
   entry: string
diff --git a/webapp/src/component/apps/AppChips.tsx b/webapp/src/component/apps/AppChips.tsx
@@ -1,33 +1,104 @@
-import { Chip, styled } from '@mui/material';
+import React from 'react';
+import { Chip, styled, Tooltip, Typography } from '@mui/material';
+
+const StyledRow = styled('div')`
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: ${({ theme }) => theme.spacing(0.75)};
+  min-width: 0;
+`;
 
 const StyledChips = styled('div')`
   display: flex;
   flex-wrap: wrap;
   gap: ${({ theme }) => theme.spacing(0.75)};
+  min-width: 0;
 `;
 
+const StyledLabel = styled('span')(({ theme }) => ({
+  ...theme.typography.caption,
+  color: theme.palette.text.secondary,
+  textDecoration: 'underline dotted',
+  textUnderlineOffset: 3,
+  cursor: 'help',
+}));
+
+const StyledChipLabel = styled('span')`
+  display: inline-flex;
+  align-items: center;
+  gap: ${({ theme }) => theme.spacing(0.5)};
+`;
+
+export type AppChipItem = {
+  /** Stable identity within the row — used as the React key. */
+  id: string;
+  label: React.ReactNode;
+};
+
 type AppChipsProps = {
-  items: string[];
+  items: (string | AppChipItem)[];
   dataCy: string;
   color?: 'default' | 'info' | 'warning';
   variant?: 'filled' | 'outlined';
+  /** Short caption naming what the chips are. */
+  label?: React.ReactNode;
+  /** Explanation of the row, shown when hovering its caption. */
+  tooltip?: React.ReactNode;
+  /**
+   * Shown in place of the chips when there are none. Without it, an empty row
+   * renders nothing at all.
+   */
+  emptyLabel?: React.ReactNode;
 };
 
-export const AppChips = ({ items, dataCy, color, variant }: AppChipsProps) => {
-  if (items.length === 0) {
+const normalize = (item: string | AppChipItem): AppChipItem =>
+  typeof item === 'string' ? { id: item, label: item } : item;
+
+export const AppChips = ({
+  items,
+  dataCy,
+  color,
+  variant,
+  label,
+  tooltip,
+  emptyLabel,
+}: AppChipsProps) => {
+  if (items.length === 0 && !emptyLabel) {
     return null;
   }
+
+  const caption = label && (
+    <Tooltip title={tooltip ?? ''} disableHoverListener={!tooltip}>
+      <StyledLabel>{label}</StyledLabel>
+    </Tooltip>
+  );
+
+  if (items.length === 0) {
+    return (
+      <StyledRow>
+        {caption}
+        <Typography variant="caption" color="text.secondary" data-cy={dataCy}>
+          {emptyLabel}
+        </Typography>
+      </StyledRow>
+    );
+  }
+
   return (
-    <StyledChips data-cy={dataCy}>
-      {items.map((item) => (
-        <Chip
-          key={item}
-          size="small"
-          color={color}
-          variant={variant}
-          label={item}
-        />
-      ))}
-    </StyledChips>
+    <StyledRow>
+      {caption}
+      <StyledChips data-cy={dataCy}>
+        {items.map(normalize).map((item) => (
+          <Chip
+            key={item.id}
+            size="small"
+            color={color}
+            variant={variant}
+            label={<StyledChipLabel>{item.label}</StyledChipLabel>}
+          />
+        ))}
+      </StyledChips>
+    </StyledRow>
   );
 };
diff --git a/webapp/src/component/apps/AppIcon.tsx b/webapp/src/component/apps/AppIcon.tsx
@@ -11,12 +11,19 @@ const REGISTRY: Record<string, IconComponent> = {
   ...(CustomIcons as unknown as Record<string, IconComponent>),
 };
 
+/**
+ * The size @untitled-ui/icons-react renders at when given no width/height. The emoji
+ * fallback has to match it explicitly, otherwise an emoji icon comes out smaller than
+ * a native one sitting next to it.
+ */
+const NATIVE_ICON_DEFAULT_SIZE = 24;
+
 type Props = {
   /** Manifest icon string. Either a Tolgee native icon name or an emoji. */
   icon?: string | null;
-  /** px size for native icons. */
+  /** px size for the icon. Omit to render at the same size as any other native icon. */
   size?: number;
-  /** CSS font-size for the emoji / text fallback. */
+  /** CSS font-size for the emoji / text fallback. Defaults to `size`. */
   fontSize?: string | number;
 };
 
@@ -27,16 +34,17 @@ type Props = {
  * Otherwise the string is rendered as text — preserving the emoji path
  * and producing a self-explanatory fallback for unknown names.
  */
-export const AppIcon = ({ icon, size = 18, fontSize }: Props) => {
+export const AppIcon = ({ icon, size, fontSize }: Props) => {
   if (!icon) return null;
   const Component = REGISTRY[icon];
   if (typeof Component === 'function') {
+    if (size === undefined) return <Component />;
     return <Component width={size} height={size} />;
   }
   return (
     <span
       style={{
-        fontSize: fontSize ?? '1em',
+        fontSize: fontSize ?? `${size ?? NATIVE_ICON_DEFAULT_SIZE}px`,
         lineHeight: 1,
         display: 'inline-flex',
         alignItems: 'center',
diff --git a/webapp/src/views/administration/apps/AdministrationApps.tsx b/webapp/src/views/administration/apps/AdministrationApps.tsx
@@ -175,6 +175,24 @@ export const AdministrationApps = () => {
                     items={app.scopes}
                     variant="outlined"
                     dataCy="administration-apps-item-scopes"
+                    label={
+                      <T
+                        keyName="app_scopes_chips_label"
+                        defaultValue="Permissions"
+                      />
+                    }
+                    tooltip={
+                      <T
+                        keyName="app_scopes_chips_tooltip"
+                        defaultValue="Permissions the app was granted when it was registered. They apply in every project the app is enabled for."
+                      />
+                    }
+                    emptyLabel={
+                      <T
+                        keyName="app_scopes_chips_empty"
+                        defaultValue="No permissions granted"
+                      />
+                    }
                   />
                   {app.availableToAllOrganizations && (
                     <Box>
diff --git a/webapp/src/views/organizations/apps/registeredApps/RegisteredAppsSection.tsx b/webapp/src/views/organizations/apps/registeredApps/RegisteredAppsSection.tsx
@@ -19,6 +19,7 @@ import { RegisterAppDialog } from './RegisterAppDialog';
 import { RefreshAppDialog } from './RefreshAppDialog';
 import { AppSummary } from 'tg.component/apps/AppSummary';
 import { AppChips } from 'tg.component/apps/AppChips';
+import { AppIcon } from 'tg.component/apps/AppIcon';
 
 type AppInstallModel = components['schemas']['AppInstallModel'];
 
@@ -145,15 +146,54 @@ export const RegisteredAppsSection = () => {
                   url={item.manifestUrl}
                 />
                 <AppChips
-                  items={dashboardPages.map(
-                    (module) => `${module.icon} ${module.title}`
-                  )}
+                  items={dashboardPages.map((module) => ({
+                    id: module.key,
+                    label: (
+                      <>
+                        <AppIcon icon={module.icon} size={14} />
+                        {module.title}
+                      </>
+                    ),
+                  }))}
                   dataCy="organization-apps-item-modules"
+                  label={
+                    <T keyName="app_pages_chips_label" defaultValue="Pages" />
+                  }
+                  tooltip={
+                    <T
+                      keyName="app_pages_chips_tooltip"
+                      defaultValue="Pages this app adds to the project menu of every project it is enabled for."
+                    />
+                  }
+                  emptyLabel={
+                    <T
+                      keyName="app_pages_chips_empty"
+                      defaultValue="Adds no pages"
+                    />
+                  }
                 />
                 <AppChips
                   items={item.scopes}
                   variant="outlined"
                   dataCy="organization-apps-item-scopes"
+                  label={
+                    <T
+                      keyName="app_scopes_chips_label"
+                      defaultValue="Permissions"
+                    />
+                  }
+                  tooltip={
+                    <T
+                      keyName="app_scopes_chips_tooltip"
+                      defaultValue="Permissions the app was granted when it was registered. They apply in every project the app is enabled for."
+                    />
+                  }
+                  emptyLabel={
+                    <T
+                      keyName="app_scopes_chips_empty"
+                      defaultValue="No permissions granted"
+                    />
+                  }
                 />
               </StyledItemMeta>
               <Box display="flex" gap={1}>
diff --git a/webapp/src/views/projects/projectMenu/ProjectMenu.tsx b/webapp/src/views/projects/projectMenu/ProjectMenu.tsx
@@ -25,7 +25,7 @@ import { useAddProjectMenuItems } from 'tg.ee';
 import { useProject } from 'tg.hooks/useProject';
 import { useBranchLinks } from 'tg.component/branching/useBranchLinks';
 import { useApiQuery } from 'tg.service/http/useQueryApi';
-import { AppIcon } from '../apps/AppIcon';
+import { AppIcon } from 'tg.component/apps/AppIcon';
 
 export const ProjectMenu = () => {
   const project = useProject();
@@ -208,7 +208,7 @@ export const ProjectMenu = () => {
             [PARAMS.APP_MODULE_KEY]: page.moduleKey,
           })}
           text={page.title}
-          icon={<AppIcon icon={page.icon} fontSize="1em" />}
+          icon={<AppIcon icon={page.icon} />}
           data-cy="project-menu-item-app"
           data-cy-app-install={page.installId}
         />
