robobyte-front-builder 1.0.17 → 1.0.21

package/src/views/builder/viewer/renderers/LayoutCellRenderer.jsx

@@ -7,20 +7,82 @@ import { createNode } from 'services/builderHelper/nodeFactory'
 import { insertIntoTreeAtIndex, moveNodeInTree } from 'services/builderHelper/tree'
 import { getCellProps_public } from 'services/builderHelper/layoutHelpers'
 
-export default function LayoutCellRenderer({ node, layoutNode, viewerContext }) {
+// ── CSS helpers (mirrors ViewerComponentWrapper) ──────────────────────────────
+function kebabToCamel(str = '') {
+  return str.replace(/-([a-z])/g, (_, c) => c.toUpperCase())
+}
+
+function parseCssString(css = '') {
+  return css.split(';').map(r => r.trim()).filter(Boolean).reduce((acc, rule) => {
+    const sep = rule.indexOf(':')
+    if (sep === -1) return acc
+    const prop  = rule.slice(0, sep).trim()
+    const value = rule.slice(sep + 1).trim()
+    if (prop && value) acc[kebabToCamel(prop)] = value
+    return acc
+  }, {})
+}
+
+function toCssObject(val) {
+  if (!val) return {}
+  if (typeof val === 'string') return parseCssString(val)
+  if (typeof val === 'object' && !Array.isArray(val)) return val
+  return {}
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+
+export default function LayoutCellRenderer({ node, layoutNode, gridCellDefaults = {}, viewerContext }) {
   const { data, form, isEditMode, builderContext } = viewerContext
-  const main = resolveProps(node, 'main', { form, data })
-  const styleProps = resolveProps(node, 'style', { form, data })
 
-  const { elementStyle: _es, elementCss: _ec, justifyContent, alignItems, ...restStyle } = styleProps
+  // ── Resolve cell's own style tab ─────────────────────────────────────────
+  const cellStyleProps = resolveProps(node, 'style', viewerContext)
+
+  // elementStyle / elementCss are the "pure CSS escape-hatch" fields
+  const { elementStyle, elementCss, justifyContent, alignItems, minHeight, ...restCellStyle } = cellStyleProps
+
+  const cellElementStyle = toCssObject(elementStyle)   // expression → CSS object
+  const cellElementCss   = toCssObject(elementCss)     // expression → CSS object
+
+  // ── Merge: grid defaults → cell style tab → cell element overrides ────────
+  // Grid defaults are lowest priority; cell's own settings always win.
+  const mergedStyle = {
+    ...gridCellDefaults,      // from layout's cellStyle expression / cell* fields
+    ...restCellStyle,          // from cell's Style tab (padding, bg, border, etc.)
+    ...cellElementStyle,       // from cell's elementStyle expression
+    ...cellElementCss,         // from cell's elementCss expression
+  }
+
+  // Pull flex-alignment out so we can apply them to the Box flex container
+  const resolvedJustify   = justifyContent  ?? gridCellDefaults.justifyContent  ?? 'flex-start'
+  const resolvedAlign     = alignItems      ?? gridCellDefaults.alignItems      ?? 'stretch'
+  const resolvedMinHeight = mergedStyle.minHeight ?? minHeight ?? (isEditMode ? 48 : 0)
+
+  // Remove from mergedStyle so we don't double-apply
+  delete mergedStyle.justifyContent
+  delete mergedStyle.alignItems
+  delete mergedStyle.minHeight
 
   const [contextMenu, setContextMenu] = useState(null)
-  const [isDragOver, setIsDragOver] = useState(false)
+  const [isDragOver,  setIsDragOver]  = useState(false)
 
   const { colStart, rowStart, colSpan, rowSpan } = getCellProps_public(node)
 
-  const isSelected = builderContext?.selectedId === node.id
-  const isEmpty = !node.children || node.children.length === 0
+  // Only apply explicit grid placement when the cell has been manually positioned.
+  // Without this guard every cell defaults to colStart:1 / rowStart:1, which
+  // overrides CSS grid auto-placement and causes all cells to stack at (1,1).
+  const mainProps = node.props?.main ?? {}
+  const hasExplicitCol = mainProps.colStart !== undefined || mainProps.colSpan !== undefined
+  const hasExplicitRow = mainProps.rowStart !== undefined || mainProps.rowSpan !== undefined
+  const gridPlacement  = {
+    ...(hasExplicitCol ? { gridColumn: `${colStart} / span ${colSpan}` } : {}),
+    ...(hasExplicitRow ? { gridRow:    `${rowStart} / span ${rowSpan}`  } : {}),
+  }
+
+  const isSelected   = builderContext?.selectedId === node.id
+  const isEmpty      = !node.children || node.children.length === 0
+  const hasBorder    = !!(mergedStyle.border || mergedStyle.borderTop || mergedStyle.borderBottom || mergedStyle.borderLeft || mergedStyle.borderRight)
+  const hasBg        = !!mergedStyle.backgroundColor
 
   const handleRightClick = e => {
     if (!isEditMode) return
@@ -30,33 +92,29 @@ export default function LayoutCellRenderer({ node, layoutNode, viewerContext })
     setContextMenu({ mouseX: e.clientX, mouseY: e.clientY })
   }
 
-  const handleCloseMenu = () => setContextMenu(null)
-
   const handleDrop = e => {
     if (!isEditMode || !builderContext) return
     e.preventDefault()
     e.stopPropagation()
     setIsDragOver(false)
-
     try {
       const nodeId = e.dataTransfer.getData('application/builder-node-id')
       if (nodeId) {
         builderContext.setSchema(prev => ({
           ...prev,
-          root: moveNodeInTree(prev.root, nodeId, node.id, node.children?.length ?? 0)
+          root: moveNodeInTree(prev.root, nodeId, node.id, node.children?.length ?? 0),
         }))
         builderContext.setSelectedId(nodeId)
         builderContext.setDraggingNodeId(null)
         return
       }
-
       const componentData = e.dataTransfer.getData('application/builder-component')
       if (componentData) {
         const component = JSON.parse(componentData)
         const newNode = createNode(component.type, component.value ? JSON.parse(component.value) : null)
         builderContext.setSchema(prev => ({
           ...prev,
-          root: insertIntoTreeAtIndex(prev.root, node.id, newNode, node.children?.length ?? 0)
+          root: insertIntoTreeAtIndex(prev.root, node.id, newNode, node.children?.length ?? 0),
         }))
         builderContext.setSelectedId(newNode.id)
         builderContext.setDraggingNodeId(null)
@@ -79,6 +137,13 @@ export default function LayoutCellRenderer({ node, layoutNode, viewerContext })
     setIsDragOver(false)
   }
 
+  // ── Edit-mode border (only when no user-defined border) ──────────────────
+  const editBorder = isEditMode && !hasBorder
+    ? isSelected  ? '2px solid #1976d2'
+      : isDragOver  ? '2px dashed #1976d2'
+        : '1px dashed #bbb'
+    : undefined
+
   return (
     <>
       <Box
@@ -93,36 +158,33 @@ export default function LayoutCellRenderer({ node, layoutNode, viewerContext })
           }
         }}
         style={{
-          gridColumn: `${colStart} / span ${colSpan}`,
-          gridRow:    `${rowStart} / span ${rowSpan}`,
-          minHeight: 48,
-          height: '100%',
+          // Grid placement — only explicit when the cell has manual position props;
+          // otherwise CSS grid auto-placement distributes cells across the columns.
+          ...gridPlacement,
+          // Flex container
+          display:        'flex',
+          flexDirection:  'column',
+          justifyContent: resolvedJustify,
+          alignItems:     resolvedAlign,
+          // Sizing
+          minHeight: resolvedMinHeight,
+          height:    '100%',
           boxSizing: 'border-box',
+          // ── Pure CSS from grid defaults + cell style (cell wins) ──────────
+          ...mergedStyle,
         }}
         sx={{
           position: 'relative',
-          display: 'flex',
-          flexDirection: 'column',
-          justifyContent: justifyContent ?? 'center',
-          alignItems: alignItems ?? 'stretch',
-          ...restStyle,
-          ...(isEditMode && !restStyle.border ? {
-            border: isSelected
-              ? '2px solid #1976d2'
-              : isDragOver
-                ? '2px dashed #1976d2'
-                : '1px dashed #bbb',
-          } : {}),
-          ...(isEditMode && isSelected ? { border: '2px solid #1976d2' } : {}),
-          borderRadius: restStyle.borderRadius ?? 1,
-          bgcolor: restStyle.backgroundColor
-            ? undefined
-            : isDragOver
-              ? 'rgba(25,118,210,0.06)'
-              : isEditMode ? 'rgba(0,0,0,0.01)' : 'transparent',
+          overflow: mergedStyle.overflow ?? 'visible',
+          // Edit-mode visuals — lower specificity than inline style,
+          // so they only apply when user hasn't set those properties
+          ...(editBorder && { border: editBorder }),
+          ...(isEditMode && isSelected && { border: '2px solid #1976d2 !important' }),
+          ...(!hasBg && isEditMode && {
+            bgcolor: isDragOver ? 'rgba(25,118,210,0.06)' : 'rgba(0,0,0,0.01)',
+          }),
           transition: 'border-color 0.15s, background-color 0.15s',
-          '&:hover': isEditMode ? { borderColor: '#90caf9' } : {},
-          overflow: restStyle.overflow ?? 'hidden',
+          '&:hover': isEditMode && !isSelected ? { borderColor: '#90caf9' } : {},
         }}
       >
         {isEmpty
@@ -139,7 +201,7 @@ export default function LayoutCellRenderer({ node, layoutNode, viewerContext })
                   userSelect: 'none',
                 }}
               >
-                Drop Component Here
+                Drop here
               </Typography>
             )
           : node.children.map(child => (
@@ -151,7 +213,7 @@ export default function LayoutCellRenderer({ node, layoutNode, viewerContext })
       {contextMenu && (
         <LayoutContextMenu
           anchorPosition={contextMenu}
-          onClose={handleCloseMenu}
+          onClose={() => setContextMenu(null)}
           cell={node}
           layoutNode={layoutNode}
           viewerContext={viewerContext}

package/src/views/builder/viewer/renderers/LayoutContextMenu.jsx

@@ -3,8 +3,8 @@ import {
   ArrowForward,
   ArrowDownward,
   CallSplit,
-  AddCircleOutline,
-  RemoveCircleOutline,
+  AddCircleOutlined,
+  RemoveCircleOutlined,
 } from '@mui/icons-material'
 import {
   mergeRight,
@@ -75,20 +75,20 @@ export default function LayoutContextMenu({ anchorPosition, onClose, cell, layou
     { divider: true },
     {
       label: 'Add Row Above',
-      icon: <AddCircleOutline fontSize='small' />,
+      icon: <AddCircleOutlined fontSize='small' />,
       disabled: false,
       onClick: () => applyNewCells(addRow(cells, layoutCols, rowStart - 1)),
     },
     {
       label: 'Add Row Below',
-      icon: <AddCircleOutline fontSize='small' />,
+      icon: <AddCircleOutlined fontSize='small' />,
       disabled: false,
       onClick: () => applyNewCells(addRow(cells, layoutCols, rowStart)),
     },
     { divider: true },
     {
       label: 'Add Column Left',
-      icon: <AddCircleOutline fontSize='small' />,
+      icon: <AddCircleOutlined fontSize='small' />,
       disabled: false,
       onClick: () => {
         const newCells = addColumn(cells, totalRows, colStart - 1)
@@ -105,7 +105,7 @@ export default function LayoutContextMenu({ anchorPosition, onClose, cell, layou
     },
     {
       label: 'Add Column Right',
-      icon: <AddCircleOutline fontSize='small' />,
+      icon: <AddCircleOutlined fontSize='small' />,
       disabled: false,
       onClick: () => {
         const newCells = addColumn(cells, totalRows, colStart)
@@ -123,13 +123,13 @@ export default function LayoutContextMenu({ anchorPosition, onClose, cell, layou
     { divider: true },
     {
       label: 'Delete Row',
-      icon: <RemoveCircleOutline fontSize='small' color='error' />,
+      icon: <RemoveCircleOutlined fontSize='small' color='error' />,
       disabled: totalRows <= 1,
       onClick: () => applyNewCells(deleteRow(cells, rowStart)),
     },
     {
       label: 'Delete Column',
-      icon: <RemoveCircleOutline fontSize='small' color='error' />,
+      icon: <RemoveCircleOutlined fontSize='small' color='error' />,
       disabled: totalCols <= 1,
       onClick: () => {
         const newCells = deleteColumn(cells, colStart)

package/src/views/builder/viewer/renderers/LayoutRenderer.jsx

@@ -1,17 +1,57 @@
-import { Box, IconButton, Tooltip } from '@mui/material'
+import { Box } from '@mui/material'
 import { useEffect } from 'react'
 import ViewerComponentWrapper from '../ViewerComponentWrapper'
 import LayoutCellRenderer from './LayoutCellRenderer'
 import { resolveProps } from 'services/builderHelper/resolveProps'
-import { createLayoutGrid, getTotalRows, getTotalCols, getCellProps_public } from 'services/builderHelper/layoutHelpers'
+import { createLayoutGrid } from 'services/builderHelper/layoutHelpers'
 import { updateNodeInTree } from 'services/builderHelper/tree'
 
+// ── CSS helpers ───────────────────────────────────────────────────────────────
+function kebabToCamel(str = '') {
+  return str.replace(/-([a-z])/g, (_, c) => c.toUpperCase())
+}
+
+function parseCssString(css = '') {
+  return css.split(';').map(r => r.trim()).filter(Boolean).reduce((acc, rule) => {
+    const sep = rule.indexOf(':')
+    if (sep === -1) return acc
+    const prop  = rule.slice(0, sep).trim()
+    const value = rule.slice(sep + 1).trim()
+    if (prop && value) acc[kebabToCamel(prop)] = value
+    return acc
+  }, {})
+}
+
+function toCssObject(val) {
+  if (!val) return {}
+  if (typeof val === 'string') return parseCssString(val)
+  if (typeof val === 'object' && !Array.isArray(val)) return val
+  return {}
+}
+// ─────────────────────────────────────────────────────────────────────────────
+
 export default function LayoutRenderer({ node, viewerContext }) {
   const { data, form, isEditMode, builderContext } = viewerContext
-  const main = resolveProps(node, 'main', { form, data })
+  const main = resolveProps(node, 'main', viewerContext)
+
+  const cols   = main.cols   ?? 2
+  const gap    = main.gap    ?? 8
+  const rowGap = main.rowGap ?? gap
 
-  const cols = main.cols ?? 2
-  const gap  = main.gap  ?? 8
+  // Grid-level defaults passed to every cell — overrideable per-cell via Style tab.
+  const gridCellDefaults = {
+    ...(main.cellMinHeight       != null && { minHeight:       main.cellMinHeight }),
+    ...(main.cellPadding         != null && { padding:         main.cellPadding }),
+    ...(main.cellBackgroundColor != null && { backgroundColor: main.cellBackgroundColor }),
+    ...(main.cellBorder          != null && { border:          main.cellBorder }),
+    ...(main.cellBorderRadius    != null && { borderRadius:    main.cellBorderRadius }),
+    ...(main.cellBoxShadow       != null && { boxShadow:       main.cellBoxShadow }),
+    ...(main.cellJustifyContent  != null && { justifyContent:  main.cellJustifyContent }),
+    ...(main.cellAlignItems      != null && { alignItems:      main.cellAlignItems }),
+    // cellElementStyle / cellElementCss merge last — highest priority among grid defaults
+    ...toCssObject(main.cellElementStyle),
+    ...toCssObject(main.cellElementCss),
+  }
 
   const cells = node.children ?? []
 
@@ -21,7 +61,7 @@ export default function LayoutRenderer({ node, viewerContext }) {
       const defaultCells = createLayoutGrid(cols, 2)
       builderContext.setSchema(prev => ({
         ...prev,
-        root: updateNodeInTree(prev.root, node.id, { children: defaultCells })
+        root: updateNodeInTree(prev.root, node.id, { children: defaultCells }),
       }))
     }
   // eslint-disable-next-line react-hooks/exhaustive-deps
@@ -34,6 +74,7 @@ export default function LayoutRenderer({ node, viewerContext }) {
           display: 'grid',
           gridTemplateColumns: `repeat(${cols}, 1fr)`,
           gap: `${gap}px`,
+          rowGap: `${rowGap}px`,
           width: '100%',
         }}
       >
@@ -42,6 +83,7 @@ export default function LayoutRenderer({ node, viewerContext }) {
             key={cell.id}
             node={cell}
             layoutNode={node}
+            gridCellDefaults={gridCellDefaults}
             viewerContext={viewerContext}
           />
         ))}

package/src/views/builder/viewer/renderers/LinkRenderer.jsx

@@ -4,7 +4,7 @@ import { resolveProps } from 'services/builderHelper/resolveProps'
 
 export default function LinkRenderer({ node, viewerContext }) {
   const { data, form } = viewerContext
-  const main = resolveProps(node, 'main', { form, data })
+  const main = resolveProps(node, 'main', viewerContext)
 
   return (
     <ViewerComponentWrapper node={node} viewerContext={viewerContext}>

package/src/views/builder/viewer/renderers/MenuRenderer.jsx

@@ -27,8 +27,8 @@ export default function MenuRenderer({ node, viewerContext }) {
   const [activeTab, setActiveTab] = useState(0)
 
   // Resolve main props for configuration
-  const main = resolveProps(node, 'main', { form, data })
-  const styleProps = resolveProps(node, 'style', { form, data })
+  const main = resolveProps(node, 'main', viewerContext)
+  const styleProps = resolveProps(node, 'style', viewerContext)
 
   // Get configuration - check if items (navigation menu) or tabs (tab panels) mode
   const items = main.items || []

package/src/views/builder/viewer/renderers/MetricRenderer.jsx

@@ -0,0 +1,80 @@
+import { Box, Typography } from '@mui/material'
+import ViewerComponentWrapper from '../ViewerComponentWrapper'
+import { resolveProps, resolveValue } from 'services/builderHelper/resolveProps'
+import { formatNumber } from 'services/builderHelper/numberFormat'
+import { thresholdColors } from 'services/builderHelper/thresholdEngine'
+import { runKpiAction } from 'services/builderHelper/actionExecutor'
+
+export default function MetricRenderer({ node, viewerContext }) {
+  const main = resolveProps(node, 'main', viewerContext)
+  const { data, setData, isEditMode } = viewerContext ?? {}
+
+  const {
+    valueKey, label, sublabel,
+    format = 'number', decimals, prefix = '', suffix = '',
+    currency = 'USD', asRatio = false,
+    thresholds = [],
+    fontSize, fontWeight = 700,
+    align = 'left',
+    showLabel = true,
+    labelPosition = 'above',   // 'above' | 'below'
+    // label styling
+    labelFontSize   = 12,
+    labelFontWeight = 400,
+    labelColor      = 'text.secondary',
+    // sublabel styling
+    sublabelFontSize   = 11,
+    sublabelFontWeight = 400,
+    sublabelColor      = 'text.disabled',
+  } = main
+
+  const rawValue = resolveValue(valueKey, data)
+  const formatted = formatNumber(rawValue, { format, decimals, prefix, suffix, currency, asRatio })
+  const { color } = thresholdColors(rawValue, thresholds)
+
+  const hasClickAction = !!node.props?.actions?.onClick?.code
+  const handleClick = () => {
+    if (!hasClickAction || isEditMode) return
+    runKpiAction(node, viewerContext, 'onClick', { clickedValue: rawValue })
+  }
+
+  const valueSx = {
+    fontSize:   fontSize ?? 32,
+    fontWeight,
+    color,
+    lineHeight:  1,
+    fontVariantNumeric: 'tabular-nums',
+    letterSpacing: '-0.02em',
+    transition: 'color .2s',
+  }
+
+  const labelEl = label && showLabel && (
+    <Typography sx={{ fontSize: Number(labelFontSize), fontWeight: labelFontWeight, color: labelColor, display: 'block', lineHeight: 1.3 }}>
+      {label}
+    </Typography>
+  )
+
+  const sublabelEl = sublabel && (
+    <Typography sx={{ fontSize: Number(sublabelFontSize), fontWeight: sublabelFontWeight, color: sublabelColor, display: 'block', mt: 0.25, lineHeight: 1.3 }}>
+      {sublabel}
+    </Typography>
+  )
+
+  return (
+    <ViewerComponentWrapper node={node} viewerContext={viewerContext}>
+      <Box
+        onClick={handleClick}
+        sx={{
+          textAlign: align,
+          cursor: hasClickAction ? 'pointer' : 'default',
+          userSelect: 'none',
+        }}
+      >
+        {labelPosition === 'above' && labelEl}
+        <Typography component='div' sx={valueSx}>{formatted}</Typography>
+        {labelPosition === 'below' && labelEl}
+        {sublabelEl}
+      </Box>
+    </ViewerComponentWrapper>
+  )
+}

package/src/views/builder/viewer/renderers/NumberFormatRenderer.jsx

@@ -1,27 +1,25 @@
 import { NumericFormat } from 'react-number-format'
 import { TextField } from '@mui/material'
 import ViewerComponentWrapper from '../ViewerComponentWrapper'
+import FieldLabel from '../FieldLabel'
 import { resolveProps } from 'services/builderHelper/resolveProps'
+import { runFieldAction } from 'services/builderHelper/actionExecutor'
 
 export default function NumberFormatRenderer({ node, viewerContext }) {
   const { data, form, updateFormValue, validationErrors } = viewerContext
-  const main = resolveProps(node, 'main', { form, data })
+  const main = resolveProps(node, 'main', viewerContext)
 
-  // Get component key
   const key = node.props?.main?.key?.value || node.props?.main?.key || node.id
-
-  // Get value from form state
   const value = form[key] || ''
+  const error = validationErrors?.[key]
 
-  // Get validation error
-  const error = validationErrors[key]
+  const { label, labelPosition, required, helperText } = main
 
   const handleValueChange = (values) => {
-    // values.floatValue contains the actual numeric value
     updateFormValue(key, values.floatValue)
+    runFieldAction(node, viewerContext, 'onChange', values.floatValue)
   }
 
-  // Determine format type and props
   const formatType = main.formatType || 'decimal'
   const decimalScale = main.decimalScale ?? 2
   const fixedDecimalScale = main.fixedDecimalScale ?? false
@@ -30,14 +28,7 @@ export default function NumberFormatRenderer({ node, viewerContext }) {
   const suffix = main.suffix || ''
   const allowNegative = main.allowNegative ?? true
 
-  // Build NumericFormat props based on format type
-  let formatProps = {
-    thousandSeparator,
-    decimalScale,
-    fixedDecimalScale,
-    allowNegative
-  }
-
+  let formatProps = { thousandSeparator, decimalScale, fixedDecimalScale, allowNegative }
   switch (formatType) {
     case 'currency':
       formatProps.prefix = main.currencySymbol || '$'
@@ -53,7 +44,6 @@ export default function NumberFormatRenderer({ node, viewerContext }) {
       formatProps.suffix = suffix
       break
     case 'custom':
-      // Use custom format pattern
       formatProps.format = main.format
       formatProps.prefix = prefix
       formatProps.suffix = suffix
@@ -62,19 +52,20 @@ export default function NumberFormatRenderer({ node, viewerContext }) {
 
   return (
     <ViewerComponentWrapper node={node} viewerContext={viewerContext}>
-      <NumericFormat
-        {...formatProps}
-        value={value}
-        onValueChange={handleValueChange}
-        customInput={TextField}
-        fullWidth
-        size={main.size}
-        label={main.label}
-        placeholder={main.placeholder}
-        disabled={main.disabled}
-        error={!!error}
-        helperText={error || main.helperText}
-      />
+      <FieldLabel label={label} required={required} labelPosition={labelPosition} error={!!error}>
+        <NumericFormat
+          {...formatProps}
+          value={value}
+          onValueChange={handleValueChange}
+          customInput={TextField}
+          fullWidth
+          size={main.size}
+          placeholder={main.placeholder}
+          disabled={main.disabled}
+          error={!!error}
+          helperText={error || helperText}
+        />
+      </FieldLabel>
     </ViewerComponentWrapper>
   )
 }

package/src/views/builder/viewer/renderers/PageNumberRenderer.jsx

@@ -0,0 +1,76 @@
+import { Box } from '@mui/material'
+import ViewerComponentWrapper from '../ViewerComponentWrapper'
+import { resolveProps } from 'services/builderHelper/resolveProps'
+
+/**
+ * PageNumber component
+ *
+ * Canvas / preview  — shows "Page 2 of 5" when _printPageIndex is in context,
+ *                     otherwise shows the format string with "—" placeholders.
+ *
+ * Print portal      — renders a <span class="rbb-page-number"> that PrintDialog's
+ *                     handlePrint() fills in with real numbers via DOM before window.print().
+ *                     For fixed header/footer zones only the total-page count can be
+ *                     reliably injected (current page is unknown for fixed elements).
+ */
+export default function PageNumberRenderer({ node, viewerContext }) {
+  const main = resolveProps(node, 'main', viewerContext)
+  const {
+    format   = 'Page {page} of {pages}',
+    align    = 'center',
+    fontSize = 11,
+    color    = '#666666',
+  } = main
+
+  const { isPrintContext, __rbbPrint } = viewerContext ?? {}
+
+  // __rbbPrint is injected by PrintPreviewCanvas under a private namespaced key:
+  //  • Body pages  → { index: 0-based number, total: N }  — full info available
+  //  • Header/footer → { index: null, total: N }          — total known, current unknown
+  //  • No context  → undefined                            — pure canvas, show placeholders
+  const pageIndex = __rbbPrint?.index   // null means "shared zone, unknown"
+  const pageTotal = __rbbPrint?.total   // undefined means no print context at all
+
+  // ── Canvas / dialog preview ────────────────────────────────────────────────
+  const displayText = (() => {
+    const pagePart  = pageIndex != null ? String(pageIndex + 1) : '—'
+    const totalPart = pageTotal != null ? String(pageTotal)     : '—'
+    return format.replace('{page}', pagePart).replace('{pages}', totalPart)
+  })()
+
+  const sharedSx = {
+    fontSize,
+    color,
+    textAlign: align,
+    width: '100%',
+    display: 'block',
+    lineHeight: 1.4,
+  }
+
+  // ── Actual print portal (window.print()) ──────────────────────────────────
+  // Render a span that the pre-print JS will populate.
+  if (isPrintContext) {
+    return (
+      <ViewerComponentWrapper node={node} viewerContext={viewerContext}>
+        <Box
+          component='span'
+          className='rbb-page-number'
+          data-format={format}
+          sx={sharedSx}
+        >
+          {/* placeholder — replaced by JS before print */}
+          {format.replace('{page}', '—').replace('{pages}', '—')}
+        </Box>
+      </ViewerComponentWrapper>
+    )
+  }
+
+  // ── Canvas / preview ──────────────────────────────────────────────────────
+  return (
+    <ViewerComponentWrapper node={node} viewerContext={viewerContext}>
+      <Box component='span' sx={sharedSx}>
+        {displayText}
+      </Box>
+    </ViewerComponentWrapper>
+  )
+}