@micha.bigler/ui-core-micha 2.13.0 → 2.15.0

package/src/components/charts/ChartFrame.jsx

@@ -0,0 +1,112 @@
+import React, { useId, useRef, useState } from 'react';
+import {
+  Alert,
+  Box,
+  Button,
+  CircularProgress,
+  Paper,
+  Stack,
+  Typography,
+} from '@mui/material';
+import { useTranslation } from 'react-i18next';
+import { exportChartPng, exportChartSvg } from './exportChart';
+
+/**
+ * Chart-type-agnostic chart scaffolding. Children may be an X-Charts primitive or a bespoke SVG.
+ */
+export function ChartFrame({
+  title,
+  subtitle,
+  toolbar,
+  loading = false,
+  error = false,
+  isEmpty = false,
+  emptyMessage,
+  minHeight,
+  aspect,
+  exportOptions = false,
+  onExportSvg,
+  onExportPng,
+  ariaLabel,
+  children,
+  variant = 'outlined',
+  sx,
+}) {
+  const { t } = useTranslation();
+  const titleId = useId();
+  const chartRef = useRef(null);
+  const [exportError, setExportError] = useState(false);
+  const options = exportOptions === true ? {} : exportOptions || {};
+  const exportsEnabled = Boolean(exportOptions);
+  const hasCustomAriaLabel = Boolean(ariaLabel);
+  const chartLabel = ariaLabel || title;
+
+  const runExport = async (type) => {
+    setExportError(false);
+    try {
+      const filename = options.filename || 'chart';
+      const result = type === 'svg'
+        ? exportChartSvg(chartRef.current, `${filename}.svg`)
+        : await exportChartPng(chartRef.current, `${filename}.png`);
+      const callback = type === 'svg' ? onExportSvg : onExportPng;
+      callback?.(result);
+    } catch (_error) {
+      setExportError(true);
+    }
+  };
+
+  let content = children;
+  if (loading) {
+    content = <CircularProgress aria-label={t('ChartFrame.LOADING')} />;
+  } else if (error) {
+    content = <Alert severity="error">{typeof error === 'string' ? error : t('ChartFrame.ERROR_DEFAULT')}</Alert>;
+  } else if (isEmpty) {
+    content = <Alert severity="info">{emptyMessage || t('ChartFrame.EMPTY_DEFAULT')}</Alert>;
+  }
+
+  return (
+    <Paper variant={variant} sx={{ p: 2, ...sx }}>
+      <Box sx={{ display: 'flex', alignItems: 'flex-start', justifyContent: 'space-between', gap: 2, mb: 2 }}>
+        <Box>
+          <Typography id={titleId} variant="h6">{title}</Typography>
+          {subtitle && <Typography variant="body2" color="text.secondary">{subtitle}</Typography>}
+        </Box>
+        {toolbar && <Box>{toolbar}</Box>}
+      </Box>
+
+      <Box
+        ref={chartRef}
+        role="img"
+        aria-label={chartLabel}
+        aria-labelledby={hasCustomAriaLabel ? undefined : titleId}
+        sx={{
+          width: '100%',
+          minHeight,
+          aspectRatio: aspect,
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'center',
+        }}
+      >
+        {content}
+      </Box>
+
+      {exportError && <Alert severity="error" sx={{ mt: 2 }}>{t('ChartFrame.EXPORT_ERROR')}</Alert>}
+
+      {exportsEnabled && (
+        <Stack direction="row" spacing={1} justifyContent="flex-end" sx={{ mt: 2 }}>
+          {options.svg !== false && (
+            <Button size="small" onClick={() => runExport('svg')}>
+              {t('ChartFrame.EXPORT_SVG_LABEL')}
+            </Button>
+          )}
+          {options.png !== false && (
+            <Button size="small" onClick={() => runExport('png')}>
+              {t('ChartFrame.EXPORT_PNG_LABEL')}
+            </Button>
+          )}
+        </Stack>
+      )}
+    </Paper>
+  );
+}

package/src/components/charts/LineChart.jsx

@@ -0,0 +1,44 @@
+import React from 'react';
+import { Box } from '@mui/material';
+import { LineChart as MuiLineChart } from '@mui/x-charts/LineChart';
+import { useNeutralChartPalette } from './palette';
+
+function labelledAxis(axes, label, defaults) {
+  const values = axes?.length ? axes : [defaults];
+  return values.map((axis) => ({ ...axis, label: axis.label || label }));
+}
+
+/**
+ * Responsive MUI X-Charts line preset. xAxisLabel and yAxisLabel (including units) are required.
+ * It supplies labelled axes, tooltips, and an automatic multi-series legend.
+ */
+export function LineChart({
+  series = [],
+  xAxisLabel,
+  yAxisLabel,
+  xAxis,
+  yAxis,
+  palette,
+  minHeight,
+  aspect,
+  ...chartProps
+}) {
+  const neutralPalette = useNeutralChartPalette();
+  if (!xAxisLabel || !yAxisLabel) {
+    throw new Error('LineChart requires xAxisLabel and yAxisLabel.');
+  }
+
+  return (
+    <Box data-testid="line-chart-container" sx={{ width: '100%', minHeight, aspectRatio: aspect }}>
+      <MuiLineChart
+        {...chartProps}
+        series={series}
+        xAxis={labelledAxis(xAxis, xAxisLabel, { scaleType: 'point', data: [] })}
+        yAxis={labelledAxis(yAxis, yAxisLabel, { scaleType: 'linear' })}
+        colors={palette || neutralPalette.categorical}
+        hideLegend={series.length <= 1}
+        slotProps={{ tooltip: { trigger: 'axis' } }}
+      />
+    </Box>
+  );
+}

package/src/components/charts/exportChart.js

@@ -0,0 +1,71 @@
+function findSvg(chartContainer) {
+  const svg = chartContainer?.querySelector('svg');
+  if (!svg) throw new Error('Chart container does not contain an SVG element.');
+  return svg;
+}
+
+function svgBlob(chartContainer) {
+  const svg = findSvg(chartContainer).cloneNode(true);
+  svg.setAttribute('xmlns', 'http://www.w3.org/2000/svg');
+  return new Blob([new XMLSerializer().serializeToString(svg)], { type: 'image/svg+xml;charset=utf-8' });
+}
+
+function download(blob, filename) {
+  const url = URL.createObjectURL(blob);
+  const anchor = document.createElement('a');
+  anchor.href = url;
+  anchor.download = filename;
+  document.body.appendChild(anchor);
+  anchor.click();
+  anchor.remove();
+  URL.revokeObjectURL(url);
+}
+
+/** Serializes the first SVG rendered inside a chart container and downloads it. */
+export function exportChartSvg(chartContainer, filename = 'chart.svg') {
+  const blob = svgBlob(chartContainer);
+  download(blob, filename);
+  return blob;
+}
+
+/** Rasterizes the first SVG rendered inside a chart container at two-times scale and downloads it. */
+export function exportChartPng(chartContainer, filename = 'chart.png') {
+  const source = svgBlob(chartContainer);
+
+  return new Promise((resolve, reject) => {
+    const url = URL.createObjectURL(source);
+    const image = new Image();
+
+    image.onload = () => {
+      try {
+        const svg = findSvg(chartContainer);
+        const width = Number(svg.getAttribute('width')) || svg.clientWidth || 1;
+        const height = Number(svg.getAttribute('height')) || svg.clientHeight || 1;
+        const canvas = document.createElement('canvas');
+        canvas.width = width * 2;
+        canvas.height = height * 2;
+        const context = canvas.getContext('2d');
+        context.fillStyle = 'white';
+        context.fillRect(0, 0, canvas.width, canvas.height);
+        context.drawImage(image, 0, 0, canvas.width, canvas.height);
+        canvas.toBlob((blob) => {
+          URL.revokeObjectURL(url);
+          if (!blob) {
+            reject(new Error('Unable to create PNG export.'));
+            return;
+          }
+          download(blob, filename);
+          resolve(blob);
+        }, 'image/png');
+      } catch (error) {
+        URL.revokeObjectURL(url);
+        reject(error);
+      }
+    };
+    image.onerror = () => {
+      URL.revokeObjectURL(url);
+      reject(new Error('Unable to load chart SVG for PNG export.'));
+    };
+    image.src = url;
+  });
+}

package/src/components/charts/formatters.js

@@ -0,0 +1,39 @@
+import { useTranslation } from 'react-i18next';
+
+export function formatPercentage(value, locale, options = {}) {
+  return new Intl.NumberFormat(locale, {
+    style: 'percent',
+    maximumFractionDigits: 1,
+    ...options,
+  }).format(value);
+}
+
+export function formatCompact(value, locale, options = {}) {
+  return new Intl.NumberFormat(locale, {
+    notation: 'compact',
+    maximumFractionDigits: 1,
+    ...options,
+  }).format(value);
+}
+
+export function formatRatio(value, locale, options = {}) {
+  return new Intl.NumberFormat(locale, {
+    maximumFractionDigits: 2,
+    ...options,
+  }).format(value);
+}
+
+/** Creates locale-aware formatter functions for use in chart axes and tooltips. */
+export function createChartFormatters(locale) {
+  return {
+    percentage: (value, options) => formatPercentage(value, locale, options),
+    compact: (value, options) => formatCompact(value, locale, options),
+    ratio: (value, options) => formatRatio(value, locale, options),
+  };
+}
+
+/** Resolves formatter locale from the active react-i18next instance. */
+export function useChartFormatters() {
+  const { i18n } = useTranslation();
+  return createChartFormatters(i18n.language);
+}

package/src/components/charts/palette.js

@@ -0,0 +1,24 @@
+import { useTheme } from '@mui/material/styles';
+
+/**
+ * Returns neutral chart colours derived only from the active MUI theme.
+ * Consumers may replace either array with their own domain palette.
+ */
+export function getNeutralChartPalette(theme) {
+  const palette = theme.palette;
+  const isDark = palette.mode === 'dark';
+
+  return {
+    categorical: isDark
+      ? [palette.primary.light, palette.secondary.light, palette.info.light, palette.success.light, palette.warning.light]
+      : [palette.primary.main, palette.secondary.main, palette.info.main, palette.success.main, palette.warning.main],
+    sequential: isDark
+      ? [palette.action.disabled, palette.text.secondary, palette.primary.light, palette.primary.main, palette.primary.dark]
+      : [palette.action.disabled, palette.divider, palette.text.secondary, palette.primary.light, palette.primary.main],
+  };
+}
+
+/** Resolves the kit's neutral palette from the nearest MUI ThemeProvider. */
+export function useNeutralChartPalette() {
+  return getNeutralChartPalette(useTheme());
+}

package/src/i18n/chartsTranslations.ts

@@ -0,0 +1,38 @@
+export const chartsTranslations = {
+  'ChartFrame.LOADING': {
+    de: 'Diagramm wird geladen.',
+    fr: 'Chargement du graphique.',
+    en: 'Loading chart.',
+    sw: 'Inapakia chati.',
+  },
+  'ChartFrame.EMPTY_DEFAULT': {
+    de: 'Keine Daten verfügbar.',
+    fr: 'Aucune donnée disponible.',
+    en: 'No data available.',
+    sw: 'Hakuna data inayopatikana.',
+  },
+  'ChartFrame.ERROR_DEFAULT': {
+    de: 'Das Diagramm konnte nicht geladen werden.',
+    fr: 'Impossible de charger le graphique.',
+    en: 'The chart could not be loaded.',
+    sw: 'Chati haikuweza kupakiwa.',
+  },
+  'ChartFrame.EXPORT_SVG_LABEL': {
+    de: 'SVG exportieren',
+    fr: 'Exporter en SVG',
+    en: 'Export SVG',
+    sw: 'Hamisha SVG',
+  },
+  'ChartFrame.EXPORT_PNG_LABEL': {
+    de: 'PNG exportieren',
+    fr: 'Exporter en PNG',
+    en: 'Export PNG',
+    sw: 'Hamisha PNG',
+  },
+  'ChartFrame.EXPORT_ERROR': {
+    de: 'Das Diagramm konnte nicht exportiert werden.',
+    fr: 'Impossible d’exporter le graphique.',
+    en: 'The chart could not be exported.',
+    sw: 'Chati haikuweza kuhamishwa.',
+  },
+};

package/src/i18n/notificationsTranslations.ts

@@ -17,4 +17,6 @@ export const notificationsTranslations = {
   'NotificationSettings.PUSH_CONFLICT': { de: 'Dieses Gerät ist bereits mit einem anderen Konto für Push-Benachrichtigungen verbunden.', fr: 'Cet appareil est déjà associé à un autre compte pour les notifications push.', en: 'This device is already associated with another account for push notifications.', sw: 'Kifaa hiki tayari kimeunganishwa na akaunti nyingine kwa arifa za push.' },
   'NotificationSettings.PUSH_NOT_SUPPORTED': { de: 'Push-Benachrichtigungen werden von diesem Browser nicht unterstützt.', fr: 'Les notifications push ne sont pas prises en charge par ce navigateur.', en: 'Push notifications are not supported by this browser.', sw: 'Arifa za push hazitumiki na kivinjari hiki.' },
   'NotificationSettings.IOS_HINT': { de: 'Füge diese App zuerst zum Home-Bildschirm hinzu, um Push-Benachrichtigungen zu aktivieren.', fr: 'Ajoutez d’abord cette application à l’écran d’accueil pour activer les notifications push.', en: 'Add this app to your home screen first to enable push notifications.', sw: 'Ongeza programu hii kwenye skrini yako ya mwanzo kwanza ili kuwasha arifa za push.' },
+  'PopupSurface.CLOSE': { de: 'Schliessen', fr: 'Fermer', en: 'Close', sw: 'Funga' },
+  'PopupSurface.TITLE': { de: 'Benachrichtigung', fr: 'Notification', en: 'Notification', sw: 'Arifa' },
 };

package/src/index.js

@@ -39,18 +39,32 @@ export { AuthFactorRequirementCard } from './components/AuthFactorRequirementCar
 export { AccessCodeSingleUseToggle } from './components/AccessCodeSingleUseToggle';
 export { QrSignupManager } from './components/QrSignupManager';
 
-// --- 6. Translations ---
+// --- 6. Charts ---
+export { ChartFrame } from './components/charts/ChartFrame';
+export { BarChart } from './components/charts/BarChart';
+export { LineChart } from './components/charts/LineChart';
+export { getNeutralChartPalette, useNeutralChartPalette } from './components/charts/palette';
+export {
+  formatPercentage,
+  formatCompact,
+  formatRatio,
+  createChartFormatters,
+  useChartFormatters,
+} from './components/charts/formatters';
+
+// --- 7. Translations ---
 export { authTranslations } from './i18n/authTranslations';
 
-// --- 7. Notifications ---
+// --- 8. Notifications ---
 export { NotificationSettings } from './notifications/NotificationSettings';
 export * from './notifications/api';
 export { NotificationsProvider, useNotifications } from './notifications/NotificationsProvider';
 export { useRealtime } from './notifications/realtime';
 export { NotificationBell } from './notifications/NotificationBell';
+export { PopupSurface } from './notifications/PopupSurface';
 export { getNotificationFeed, getUnreadCount, markNotifications } from './notifications/feedApi';
 
-// --- 8. Onboarding ---
+// --- 9. Onboarding ---
 export * from './onboarding/api';
 export { selectActiveSteps } from './onboarding/stepSelection';
 export {
@@ -65,6 +79,7 @@ export { CompleteNameStep } from './onboarding/steps/CompleteNameStep';
 export { BrowserPushStep } from './onboarding/steps/BrowserPushStep';
 export { PwaInstallStep } from './onboarding/steps/PwaInstallStep';
 
-// --- 9. Translations ---
+// --- 10. Translations ---
 export { notificationsTranslations } from './i18n/notificationsTranslations';
 export { onboardingTranslations } from './i18n/onboardingTranslations';
+export { chartsTranslations } from './i18n/chartsTranslations';

package/src/notifications/NotificationsProvider.jsx

@@ -116,6 +116,27 @@ export function NotificationsProvider({ children, wsUrlBase }) {
     }
 
     const pushedNotification = normalizeNotificationPush(data);
+
+    // NOTIF-12 D2: a notification routed to more than one channel (e.g. chip
+    // + popup) arrives as multiple WS messages sharing one notification_id.
+    // Fold repeats into the existing feed entry (last-write-wins on content)
+    // instead of appending a duplicate and double-incrementing the badge.
+    const existingIndex = pushedNotification.notification_id == null
+      ? -1
+      : notificationsRef.current.findIndex(
+        (notification) => notification.notification_id === pushedNotification.notification_id,
+      );
+
+    if (existingIndex !== -1) {
+      const nextNotifications = notificationsRef.current.map((notification, index) => (
+        index === existingIndex
+          ? { ...notification, notification_type: pushedNotification.notification_type, content: pushedNotification.content }
+          : notification
+      ));
+      replaceNotifications(nextNotifications);
+      return;
+    }
+
     replaceNotifications([pushedNotification, ...notificationsRef.current]);
     setUnreadCount((count) => count + 1);
   }, [replaceNotifications]);

package/src/notifications/PopupSurface.jsx

@@ -0,0 +1,103 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+import Button from '@mui/material/Button';
+import Stack from '@mui/material/Stack';
+import Typography from '@mui/material/Typography';
+import { useOnboarding } from '../onboarding/OnboardingProvider';
+import { WizardDialogShell } from '../onboarding/WizardDialogShell';
+import { useNotifications } from './NotificationsProvider';
+import { DEFAULT_ENVELOPE, useRealtime } from './realtime';
+
+function PopupStepComponent({ onDismiss, ctx }) {
+  const { t } = useTranslation();
+  const content = ctx?.content || {};
+
+  return (
+    <Stack spacing={2}>
+      {content.body_key && (
+        <Typography variant="body1">{t(content.body_key, content.params || {})}</Typography>
+      )}
+      <Button onClick={onDismiss} sx={{ alignSelf: 'flex-end' }}>
+        {t('PopupSurface.CLOSE')}
+      </Button>
+    </Stack>
+  );
+}
+
+const POPUP_STEP = { blocking: false, Component: PopupStepComponent };
+
+/**
+ * Renders popup-eligible notifications (NOTIF-12) through the onboarding
+ * wizard's dialog shell, reusing only the renderer (design D-F7) — status
+ * lives on NotificationRecipient via the existing feed/mark path, never in
+ * the onboarding progress store.
+ *
+ * Deliberately session-live only: it watches the raw realtime stream for
+ * `channel === "popup"` messages rather than the already-seeded feed list,
+ * since the feed carries no per-channel discriminator (see NotificationsProvider).
+ */
+export function PopupSurface() {
+  const { t } = useTranslation();
+  const { markSeen, markDismissed } = useNotifications();
+  const { subscribe } = useRealtime();
+  const onboarding = useOnboarding();
+  const [queue, setQueue] = useState([]);
+  const seenIdsRef = useRef(new Set());
+
+  const handleRealtimeMessage = useCallback((data) => {
+    if (data.type === 'notification.status') return;
+    if (data.channel !== 'popup') return;
+    setQueue((previous) => {
+      if (previous.some((item) => item.notification_id === data.notification_id)) return previous;
+      return [...previous, {
+        notification_id: data.notification_id,
+        // recipient_id is the id feed/mark/ actually resolves against
+        // (NotificationRecipient.pk, not Notification.pk). Fall back to
+        // notification_id only for an older dcm that predates it — matching
+        // NotificationsProvider's own normalizeNotificationPush precedent.
+        markId: data.recipient_id ?? data.notification_id,
+        content: data.content || {},
+      }];
+    });
+  }, []);
+
+  useEffect(() => subscribe(DEFAULT_ENVELOPE, handleRealtimeMessage), [subscribe, handleRealtimeMessage]);
+
+  // Any active onboarding step — blocking or not — must win: OnboardingWizard
+  // renders its own dialog for as long as onboarding.activeSteps is non-empty,
+  // and two independent MUI Dialogs must never be mounted at once.
+  const onboardingActive = Boolean(onboarding?.activeSteps?.length);
+  const activePopup = queue[0];
+
+  useEffect(() => {
+    if (!activePopup || onboardingActive) return;
+    if (activePopup.markId == null) return;
+    if (seenIdsRef.current.has(activePopup.notification_id)) return;
+    seenIdsRef.current.add(activePopup.notification_id);
+    markSeen([activePopup.markId]);
+  }, [activePopup, onboardingActive, markSeen]);
+
+  const dismissActivePopup = useCallback(() => {
+    if (!activePopup) return;
+    if (activePopup.markId != null) markDismissed([activePopup.markId]);
+    setQueue((previous) => previous.filter((item) => item.notification_id !== activePopup.notification_id));
+  }, [activePopup, markDismissed]);
+
+  if (!activePopup || onboardingActive) return null;
+
+  return (
+    <WizardDialogShell
+      step={POPUP_STEP}
+      stepIndex={0}
+      total={1}
+      onComplete={dismissActivePopup}
+      onDismiss={dismissActivePopup}
+      ctx={{ content: activePopup.content }}
+      title={activePopup.content.title_key
+        ? t(activePopup.content.title_key, activePopup.content.params || {})
+        : t('PopupSurface.TITLE')}
+    />
+  );
+}
+
+export default PopupSurface;

package/src/onboarding/OnboardingWizard.jsx

@@ -1,16 +1,9 @@
 import React, { useContext, useEffect, useRef, useState } from 'react';
-import { useTranslation } from 'react-i18next';
-import Box from '@mui/material/Box';
-import Dialog from '@mui/material/Dialog';
-import DialogContent from '@mui/material/DialogContent';
-import DialogTitle from '@mui/material/DialogTitle';
-import LinearProgress from '@mui/material/LinearProgress';
-import Typography from '@mui/material/Typography';
 import { AuthContext } from '../auth/AuthContext';
 import { useOnboarding } from './OnboardingProvider';
+import { WizardDialogShell } from './WizardDialogShell';
 
 export function OnboardingWizard() {
-  const { t } = useTranslation();
   const onboarding = useOnboarding();
   const authContext = useContext(AuthContext);
   const [sessionDismissed, setSessionDismissed] = useState(() => new Set());
@@ -39,8 +32,6 @@ export function OnboardingWizard() {
 
   const { dismissStep, ctx } = onboarding;
   const total = totalRef.current || visibleSteps.length;
-  const progress = total > 1 ? Math.round((completed / total) * 100) : 0;
-  const StepComponent = currentStep.Component;
 
   const completeCurrentStep = () => {
     setSessionDismissed((previous) => new Set([...previous, currentStep.id]));
@@ -56,19 +47,14 @@ export function OnboardingWizard() {
   };
 
   return (
-    <Dialog open fullWidth maxWidth="sm" disableEscapeKeyDown={currentStep.blocking} onClose={currentStep.blocking ? undefined : dismissCurrentStep}>
-      <DialogTitle sx={{ pb: 0 }}>
-        <Box sx={{ display: 'flex', alignItems: 'center', justifyContent: 'space-between' }}>
-          <Typography variant="subtitle2" color="text.secondary">
-            {total > 1 ? t('Onboarding.STEP_COUNTER', { current: completed + 1, total }) : t('Onboarding.SETUP')}
-          </Typography>
-        </Box>
-        {total > 1 && <LinearProgress variant="determinate" value={progress} sx={{ mt: 1, borderRadius: 1 }} />}
-      </DialogTitle>
-      <DialogContent sx={{ pt: 2 }}>
-        <StepComponent onComplete={completeCurrentStep} onDismiss={dismissCurrentStep} ctx={ctx} />
-      </DialogContent>
-    </Dialog>
+    <WizardDialogShell
+      step={currentStep}
+      stepIndex={completed}
+      total={total}
+      onComplete={completeCurrentStep}
+      onDismiss={dismissCurrentStep}
+      ctx={ctx}
+    />
   );
 }
 

package/src/onboarding/WizardDialogShell.jsx

@@ -0,0 +1,51 @@
+import React from 'react';
+import { useTranslation } from 'react-i18next';
+import Box from '@mui/material/Box';
+import Dialog from '@mui/material/Dialog';
+import DialogContent from '@mui/material/DialogContent';
+import DialogTitle from '@mui/material/DialogTitle';
+import LinearProgress from '@mui/material/LinearProgress';
+import Typography from '@mui/material/Typography';
+
+/**
+ * Presentational dialog shell shared by OnboardingWizard and the popup
+ * notification surface (NOTIF-12). Owns only the dialog frame, the
+ * counter/progress header, and the onComplete/onDismiss/ctx child contract —
+ * step selection, dismissal persistence, and any progress store stay with
+ * the caller.
+ */
+export function WizardDialogShell({ step, stepIndex, total, onComplete, onDismiss, ctx, title }) {
+  const { t } = useTranslation();
+  const progress = total > 1 ? Math.round((stepIndex / total) * 100) : 0;
+  const StepComponent = step.Component;
+  // `title` lets a non-onboarding caller (e.g. the popup surface) supply its
+  // own header instead of the onboarding-specific step counter/"Setup" copy.
+  // Omitted by OnboardingWizard, so its header text is unchanged.
+  const headerLabel = title ?? (total > 1
+    ? t('Onboarding.STEP_COUNTER', { current: stepIndex + 1, total })
+    : t('Onboarding.SETUP'));
+
+  return (
+    <Dialog
+      open
+      fullWidth
+      maxWidth="sm"
+      disableEscapeKeyDown={step.blocking}
+      onClose={step.blocking ? undefined : onDismiss}
+    >
+      <DialogTitle sx={{ pb: 0 }}>
+        <Box sx={{ display: 'flex', alignItems: 'center', justifyContent: 'space-between' }}>
+          <Typography variant="subtitle2" color="text.secondary">
+            {headerLabel}
+          </Typography>
+        </Box>
+        {total > 1 && <LinearProgress variant="determinate" value={progress} sx={{ mt: 1, borderRadius: 1 }} />}
+      </DialogTitle>
+      <DialogContent sx={{ pt: 2 }}>
+        <StepComponent onComplete={onComplete} onDismiss={onDismiss} ctx={ctx} />
+      </DialogContent>
+    </Dialog>
+  );
+}
+
+export default WizardDialogShell;