renderer-package 1.2.32 → 1.2.34

package/dist/page/types/widget-configs.d.ts

@@ -49,6 +49,17 @@ export interface PagePrepopulateApiConfig {
     /** Page context key -> JSON path in prepopulate API response */
     contextMapping?: Record<string, string>;
 }
+export type RowLabelRuleOp = 'eq' | 'neq' | 'truthy' | 'falsy';
+export interface RowLabelRuleCondition {
+    field: string;
+    op: RowLabelRuleOp;
+    value?: boolean | string | number | null;
+}
+export interface RowLabelRule {
+    when: RowLabelRuleCondition[];
+    label: string;
+}
+export type RowLabelRulesPreset = 'cbme_teaching';
 export type ValueFormatter = {
     type: 'none';
 } | {
@@ -66,6 +77,23 @@ export type ValueFormatter = {
 } | {
     type: 'template';
     template: string;
+} | {
+    type: 'boolean_labels';
+    trueLabel?: string;
+    falseLabel?: string;
+    /** Checked first (top to bottom), then true/false on the column field. */
+    whenLabels?: Array<{
+        label: string;
+        when: RowLabelRuleCondition[];
+    }>;
+} | {
+    type: 'text_case';
+    mode?: 'capitalize' | 'upper' | 'lower';
+} | {
+    type: 'row_label_rules';
+    preset?: RowLabelRulesPreset;
+    rules: RowLabelRule[];
+    defaultLabel?: string;
 };
 export interface ResponseFieldMapping {
     target: string;
@@ -92,13 +120,28 @@ export interface WidgetDataSourceConfig {
     readyContextKey?: string;
 }
 export type WidgetBorderStyle = 'solid' | 'dashed';
+/** Optional horizontal rule below a widget or section block. */
+export interface WidgetBottomDividerConfig {
+    enabled?: boolean;
+    color?: string;
+    width?: string;
+    style?: WidgetBorderStyle;
+    /** Space above the line (CSS length). Default `1rem`. */
+    spacing?: string;
+}
 export interface SectionWidgetConfig {
     heading?: string;
+    /** @deprecated Prefer `headingDivider.enabled`. */
     showDivider?: boolean;
+    /** Line below the section heading (when heading is set). */
+    headingDivider?: WidgetBottomDividerConfig;
+    /** Line below the section content (children). */
+    bottomDivider?: WidgetBottomDividerConfig;
     collapsible?: boolean;
     defaultCollapsed?: boolean;
     showBorder?: boolean;
     borderStyle?: WidgetBorderStyle;
+    style?: ButtonStyleOverrides;
 }
 export interface ColumnsWidgetConfig {
     /** Number of columns (1–5). */
@@ -116,6 +159,7 @@ export interface CardWidgetConfig {
     title?: string;
     subtitle?: string;
     variant?: 'default' | 'outline' | 'elevated';
+    style?: ButtonStyleOverrides;
 }
 export type FormEmbedScrollBehavior = 'page' | 'contained';
 export type FormEmbedMaxHeightPercent = 25 | 50 | 75 | 100;
@@ -161,6 +205,7 @@ export interface HeadingWidgetConfig {
     align?: 'left' | 'center' | 'right';
     variable?: string;
     fallback?: string;
+    bottomDivider?: WidgetBottomDividerConfig;
 }
 export interface TextWidgetConfig {
     text?: string;
@@ -168,6 +213,192 @@ export interface TextWidgetConfig {
     fallback?: string;
     preset?: 'body' | 'caption' | 'small';
     align?: 'left' | 'center' | 'right';
+    bottomDivider?: WidgetBottomDividerConfig;
+}
+export interface ImageWidgetConfig {
+    /** Lucide icon (PascalCase). Preferred over src when set. */
+    iconName?: string;
+    iconColor?: string;
+    iconBackgroundColor?: string;
+    iconBorderRadius?: string;
+    iconPadding?: string;
+    /** Inner icon size (e.g. `1.5rem`). Defaults to fit the container. */
+    iconSize?: string;
+    /** Fallback image URL when no Lucide icon is selected. */
+    src?: string;
+    alt?: string;
+    width?: string;
+    height?: string;
+    objectFit?: 'contain' | 'cover' | 'fill' | 'none' | 'scale-down';
+    align?: 'left' | 'center' | 'right';
+}
+export type ModuleCardIconPosition = 'left' | 'right';
+export type ModuleCardIconColor = 'blue' | 'green' | 'orange' | 'purple' | 'red';
+export type ModuleCardDisplayMode = 'launcher' | 'metric' | 'auto';
+export type ModuleCardContentAlign = 'start' | 'center' | 'end';
+export type ModuleCardValuePosition = 'bottom-left' | 'bottom-right' | 'top-left' | 'top-right' | 'bottom-center' | 'top-center';
+export type ModuleCardPlateletSide = 'top' | 'bottom' | 'left' | 'right';
+/** Colored accent strip on any card edge (platelet). Default side: `top`. */
+export interface ModuleCardPlateletConfig {
+    /** When false, hides the platelet even if `color` is set. Default true when `color` is set. */
+    enabled?: boolean;
+    /** Which edge the strip sits on. Default `top`. */
+    side?: ModuleCardPlateletSide;
+    color?: string;
+    /** Strip thickness, e.g. `4px`, `6px` (height on top/bottom, width on left/right). */
+    size?: string;
+    /** @deprecated Use `size`. Kept for older configs. */
+    height?: string;
+    /** Border radius for the strip only, e.g. `8px 8px 0 0`. Auto-derived from card radius when omitted. */
+    borderRadius?: string;
+}
+export type ModuleCardInfoTooltipPosition = 'top-right' | 'top-left' | 'header-right' | 'header-left';
+/** Optional info tooltip on the card header. Default off. */
+export interface ModuleCardInfoTooltipConfig {
+    enabled?: boolean;
+    message?: string;
+    iconName?: string;
+    iconColor?: string;
+    iconSize?: string;
+    position?: ModuleCardInfoTooltipPosition;
+    /** Tooltip bubble background (defaults to theme primary). */
+    backgroundColor?: string;
+    /** Tooltip bubble text color. */
+    textColor?: string;
+}
+/** Bottom text link with chevron inside KPI cards. */
+export interface ModuleCardActionLinkConfig {
+    label?: string;
+    action?: WidgetActionConfig;
+}
+export interface ModuleCardFooterStatItem {
+    id?: string;
+    label: string;
+    value?: string;
+    valueMapping?: ResponseFieldMapping;
+    clickable?: boolean;
+    action?: WidgetActionConfig;
+}
+export type ModuleCardFooterConfig = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'stats';
+    items: ModuleCardFooterStatItem[];
+};
+export interface ModuleCardHoverStyleConfig {
+    /** Whole-card hover affordance (shadow/lift). Default false — enable at grid level. */
+    enabled?: boolean;
+    shadow?: string;
+    borderColor?: string;
+    transform?: string;
+}
+export interface ModuleCardStyleOverrides {
+    padding?: string;
+    minHeight?: string;
+    maxHeight?: string;
+    width?: 'full' | 'auto';
+    iconSize?: string;
+    iconPosition?: ModuleCardIconPosition;
+    titleIconGap?: string;
+    titleFontSize?: string;
+    titleColor?: string;
+    titleFontWeight?: string;
+    /** Vertical placement of card content when the card is taller than its content. */
+    contentAlign?: ModuleCardContentAlign;
+    /** Metric KPI number placement inside the card (below the title row). */
+    valuePosition?: ModuleCardValuePosition;
+    valueFontSize?: string;
+    valueFontWeight?: string;
+    valueColor?: string;
+    valueLabelFontSize?: string;
+    valueLabelColor?: string;
+    borderRadius?: string;
+    hoverBackground?: string;
+    showBorder?: boolean;
+    /** When false, hide the icon column (no placeholder). Default true. */
+    showIcon?: boolean;
+    platelet?: ModuleCardPlateletConfig;
+    hover?: ModuleCardHoverStyleConfig;
+}
+/** Computes percent from attendance counts or falls back to a direct percent path (CBME participation). */
+export interface ModuleCardValuePartRatioOrValue {
+    /** Used when non-null (e.g. `data.studentParticipationPercent`). */
+    valuePath?: string;
+    numeratorPath: string;
+    /** Denominator = sum of these paths (e.g. present + absent counts). */
+    denominatorSumPaths?: string[];
+    /** When sum is 0, use this denominator (default 100). */
+    fallbackDenominator?: number;
+    decimals?: number;
+}
+export interface ModuleCardValuePart {
+    path?: string;
+    fallback?: unknown;
+    formatter?: ValueFormatter;
+    ratioOrValue?: ModuleCardValuePartRatioOrValue;
+}
+export interface ModuleCardValueDisplayConfig {
+    /** Default `single` — use `valueMapping` only. */
+    mode?: 'single' | 'template';
+    /** Placeholders: `{{planned}} / {{total}}`, `{{pct}}%`, etc. */
+    template?: string;
+    parts?: Record<string, ModuleCardValuePart>;
+}
+export interface ModuleCardItemConfig {
+    id: string;
+    title: string;
+    subtitle?: string;
+    iconUrl?: string;
+    /** Lucide icon name (PascalCase or kebab-case). Used before `iconUrl` when set. */
+    iconName?: string;
+    iconAlt?: string;
+    iconColor?: ModuleCardIconColor;
+    /** Custom icon / icon-wrap color from palette (overrides preset `iconColor` styling). */
+    iconTintColor?: string;
+    disabled?: boolean;
+    disabledBadge?: string;
+    disabledTooltip?: string;
+    /** When true and `action` is set, the card is clickable. Default false (display only). */
+    clickable?: boolean;
+    action?: WidgetActionConfig;
+    /** Per-card data source; omit when the grid provides a shared `dataSource`. */
+    dataSource?: WidgetDataSourceConfig;
+    valueMapping?: ResponseFieldMapping;
+    trendMapping?: ResponseFieldMapping;
+    /** Optional composite display (fraction, percent suffix, etc.). Default single value. */
+    valueDisplay?: ModuleCardValueDisplayConfig;
+    /** Static label under the metric value, e.g. "competencies". */
+    valueLabel?: string;
+    valueLabelMapping?: ResponseFieldMapping;
+    /** Optional info tooltip (default off). */
+    infoTooltip?: ModuleCardInfoTooltipConfig;
+    /** Bottom navigation link with chevron. */
+    actionLink?: ModuleCardActionLinkConfig;
+    footer?: ModuleCardFooterConfig;
+    /** Override grid `cardLayout`; `auto` uses metric when a value mapping or data source is set. */
+    display?: ModuleCardDisplayMode;
+    /** Overrides grid `cardStyle.showIcon` when set. */
+    showIcon?: boolean;
+    style?: ModuleCardStyleOverrides;
+}
+export interface ModuleCardWidgetConfig extends Omit<ModuleCardItemConfig, 'id'> {
+    style?: ModuleCardStyleOverrides;
+}
+export interface ModuleCardGridWidgetConfig {
+    columns?: 1 | 2 | 3 | 4 | 5 | 6;
+    columnGap?: string;
+    rowGap?: string;
+    equalHeight?: boolean;
+    /** Shared API for all cards; each card reads its number via `valueMapping.path`. */
+    dataSource?: WidgetDataSourceConfig;
+    /** Default card layout; per-card `display` overrides. */
+    cardLayout?: ModuleCardDisplayMode;
+    /** Default style for every card in this grid; per-card `style` overrides these. */
+    cardStyle?: ModuleCardStyleOverrides;
+    /** Hover styling for every card in the grid (overrides per-card hover when set). */
+    cardHover?: ModuleCardHoverStyleConfig;
+    cards: ModuleCardItemConfig[];
 }
 export type StatCardShape = 'rectangle' | 'square' | 'circle';
 export type StatCardSize = 'sm' | 'md' | 'lg';
@@ -201,12 +432,33 @@ export interface StatGridWidgetConfig {
     stats: StatGridStatConfig[];
     tabId?: string;
 }
+export interface ButtonStyleOverrides {
+    backgroundColor?: string;
+    textColor?: string;
+    borderColor?: string;
+    borderWidth?: string;
+    borderRadius?: string;
+    /** `auto`, `full`, or CSS length (e.g. `10rem`, `120px`). */
+    width?: string;
+    height?: string;
+    minHeight?: string;
+    minWidth?: string;
+    maxWidth?: string;
+    fontWeight?: string;
+    fontSize?: string;
+    padding?: string;
+    margin?: string;
+    textAlign?: 'left' | 'center' | 'right';
+    justifyContent?: 'start' | 'center' | 'end';
+}
 export interface ButtonGroupItemConfig {
     id: string;
     label: string;
     variant?: 'default' | 'outline' | 'secondary' | 'ghost' | 'destructive';
     size?: 'sm' | 'default' | 'lg';
     action: WidgetActionConfig;
+    /** Per-button styling; overrides page Design → Buttons when set. */
+    style?: ButtonStyleOverrides;
 }
 export interface ButtonGroupWidgetConfig {
     align?: 'start' | 'center' | 'end' | 'space-between';
@@ -239,12 +491,24 @@ export interface DataTableCellAppearance {
     textColorMap?: Record<string, string>;
     pill?: boolean;
 }
+export type DataTableEmptyCellPreset = 'em_dash' | 'na' | 'unknown' | 'hyphen' | 'blank' | 'custom';
+/** Shown when a cell value is null, undefined, or empty string. */
+export interface DataTableEmptyCellDisplay {
+    preset?: DataTableEmptyCellPreset;
+    /** Used when preset is `custom`. */
+    customText?: string;
+    /** Theme token (e.g. muted) or CSS color. */
+    textColor?: string;
+}
 export interface DataTableColumnConfig {
     id: string;
     header: string;
     field: string;
     sortable?: boolean;
+    /** Fixed or preferred column width (e.g. `180px`, `12rem`). */
     width?: string;
+    /** Minimum column width before horizontal scroll (e.g. `120px`). */
+    minWidth?: string;
     align?: 'left' | 'center' | 'right';
     formatter?: ValueFormatter;
     cellAction?: WidgetActionConfig;
@@ -254,34 +518,109 @@ export interface DataTableColumnConfig {
     badgeVariant?: DataTableBadgeVariant;
     badgeVariantMap?: Record<string, DataTableBadgeVariant>;
     cellAppearance?: DataTableCellAppearance;
+    /** Overrides table-level empty cell display for this column. */
+    emptyCell?: DataTableEmptyCellDisplay;
+}
+export interface DataTableFilterOption {
+    label: string;
+    value: string;
+    extraQueryParams?: Array<{
+        param: string;
+        value: string;
+    }>;
+}
+/** Derived context for APIs when a filter selection is All vs a specific value. */
+export interface FilterValueExportConfig {
+    /** Page / filter-group key (e.g. `batchIds` for `{batchIds}` in widget APIs). */
+    contextKey: string;
+    /** When param is empty (All). Default `joinOptionValues`. */
+    whenAll?: 'joinOptionValues' | 'omit';
+    /** When a specific option is selected. Default `copyParam`. */
+    whenSelected?: 'copyParam' | 'omit';
+    /** Separator for `joinOptionValues`. Default `,`. */
+    separator?: string;
+}
+/** Optional size overrides for the data table toolbar search input. */
+export interface DataTableSearchStyle {
+    /** `auto`, `full`, or CSS length (e.g. `320px`, `20rem`). */
+    width?: string;
+    height?: string;
+    minWidth?: string;
+    maxWidth?: string;
+}
+/** @deprecated Legacy single filter — migrated to `filters[]` at runtime. */
+export interface DataTableLegacyToolbarFilterConfig {
+    enabled: boolean;
+    placeholder?: string;
+    paramKey: string;
+    options: DataTableFilterOption[];
+    defaultValue?: string;
+}
+export interface DataTableToolbarFilterConfig {
+    id: string;
+    /** Dropdown label / aria-label (e.g. "User Type"). */
+    label?: string;
+    paramKey: string;
+    defaultValue?: string;
+    /** Static key/value options or load options from an API. Default `static`. */
+    optionsSource?: 'static' | 'api';
+    /** Prepend an "All" option with empty value. Default true. */
+    includeAllOption?: boolean;
+    allOptionLabel?: string;
+    /** Used when `optionsSource` is `static`. */
+    options?: DataTableFilterOption[];
+    /** Used when `optionsSource` is `api`. */
+    optionsDataSource?: WidgetDataSourceConfig;
+    optionsItemsPath?: string;
+    optionsLabelField?: string;
+    optionsValueField?: string;
+    /** Optional derived context when All vs specific (see {@link FilterValueExportConfig}). */
+    valueExport?: FilterValueExportConfig;
+}
+export type DataTableToolbarButtonIconPosition = 'left' | 'right';
+/** Toolbar buttons use the same visual override shape as `ButtonStyleOverrides`. */
+export type DataTableToolbarButtonStyleOverrides = ButtonStyleOverrides;
+export interface DataTableToolbarButtonConfig {
+    id: string;
+    label: string;
+    /** @deprecated Legacy icon hint — use `iconName` instead. No auto icons at runtime. */
+    icon?: string;
+    /** Lucide icon name (PascalCase or kebab-case). */
+    iconName?: string;
+    /** Icon placement relative to label. Default `left`. */
+    iconPosition?: DataTableToolbarButtonIconPosition;
+    style?: DataTableToolbarButtonStyleOverrides;
+    action: WidgetActionConfig;
+    variant?: 'default' | 'outline' | 'secondary' | 'destructive';
+    /** Hide this toolbar button when the condition group is false. */
+    visibleWhen?: import('./page').ConditionGroup | null;
 }
 export interface DataTableToolbarConfig {
+    /** @deprecated Use `buttons` for one or more toolbar actions. */
     addButton?: {
         label: string;
         icon?: string;
         action: WidgetActionConfig;
     };
-    filter?: {
-        enabled: boolean;
-        placeholder?: string;
-        paramKey: string;
-        options: Array<{
-            label: string;
-            value: string;
-            extraQueryParams?: Array<{
-                param: string;
-                value: string;
-            }>;
-        }>;
-        defaultValue?: string;
-    };
+    buttons?: DataTableToolbarButtonConfig[];
+    /** @deprecated Use `filters` for one or more dropdowns. */
+    filter?: DataTableLegacyToolbarFilterConfig;
+    filters?: DataTableToolbarFilterConfig[];
 }
 export interface DataTableRowActionConfig {
     id: string;
     label: string;
+    /** @deprecated Legacy icon hint — use `iconName` instead. */
     icon?: string;
+    /** Lucide icon name (PascalCase or kebab-case). */
+    iconName?: string;
+    /** Icon placement relative to label. Default `left`. */
+    iconPosition?: DataTableToolbarButtonIconPosition;
+    style?: ButtonStyleOverrides;
     action: WidgetActionConfig;
-    variant?: 'default' | 'outline' | 'destructive';
+    variant?: 'default' | 'outline' | 'secondary' | 'destructive';
+    /** When set, action is shown only for rows matching this condition (row + page context). */
+    visibleWhen?: import('./page').ConditionGroup | null;
 }
 export interface DataTableWidgetConfig {
     dataSource: WidgetDataSourceConfig;
@@ -296,6 +635,17 @@ export interface DataTableWidgetConfig {
         enabled: boolean;
         placeholder?: string;
         searchFields?: string[];
+        /**
+         * Show the "All fields" column picker beside search.
+         * Default: true for static tables, false for pageApi/api (server-side search).
+         */
+        showFieldPicker?: boolean;
+        style?: DataTableSearchStyle;
+        /** When true, debounced search is published to the filter group for other widgets (default false). */
+        publishToFilterGroup?: boolean;
+        /** Filter group for shared search; defaults to filters.filterGroupKey or widget id. */
+        filterGroupKey?: string;
+        debounceMs?: number;
     };
     filters?: {
         filterGroupKey: string;
@@ -307,12 +657,95 @@ export interface DataTableWidgetConfig {
     emptyMessage?: string;
     tabId?: string;
     appearance?: DataTableAppearanceConfig;
+    /** Default when cell value is missing; columns may override via `emptyCell`. */
+    defaultEmptyCell?: DataTableEmptyCellDisplay;
+    /** Column header sorting (off by default). Per-column opt-out via `columns[].sortable: false`. */
+    sorting?: {
+        enabled?: boolean;
+    };
+    /** Runtime column show/hide dropdown (off by default). */
+    columnPicker?: {
+        enabled?: boolean;
+    };
 }
 export interface SearchFilterWidgetConfig {
     filterGroupKey: string;
     placeholder?: string;
     debounceMs?: number;
 }
+/** Per-dropdown visual overrides for {@link FilterBarFilterConfig}. */
+export interface FilterBarSelectStyle {
+    /** `auto`, `full`, or CSS length (e.g. `200px`, `12rem`). */
+    width?: string;
+    height?: string;
+    minWidth?: string;
+    maxWidth?: string;
+    backgroundColor?: string;
+    textColor?: string;
+    borderColor?: string;
+    borderWidth?: string;
+    borderRadius?: string;
+    fontSize?: string;
+    fontWeight?: string;
+    padding?: string;
+    labelColor?: string;
+    labelFontSize?: string;
+    labelFontWeight?: string;
+}
+export interface FilterBarFilterConfig {
+    id: string;
+    /** Visible label above or beside the dropdown. */
+    label?: string;
+    /** Published to filter group + page context when `syncToContext` is on. */
+    paramKey: string;
+    defaultValue?: string;
+    placeholder?: string;
+    /** Static key/value options or load options from an API. Default `static`. */
+    optionsSource?: 'static' | 'api';
+    /** Prepend an "All" option with empty value. Default false for filter bar. */
+    includeAllOption?: boolean;
+    allOptionLabel?: string;
+    options?: DataTableFilterOption[];
+    optionsDataSource?: WidgetDataSourceConfig;
+    optionsItemsPath?: string;
+    optionsLabelField?: string;
+    optionsValueField?: string;
+    /**
+     * Parent filter param keys that must be chosen before this filter is enabled
+     * and before its options API runs (`programmeId`, `sessionId`, …).
+     */
+    dependsOn?: string | string[];
+    /** Default true when `dependsOn` is set: skip options API until parents have values. */
+    waitForDependsOn?: boolean;
+    /** Default true: reset this filter when a parent value changes or becomes empty. */
+    clearOnDependencyChange?: boolean;
+    /**
+     * When true, hide this filter until all `dependsOn` parents have values
+     * (e.g. semester appears only after session + phase).
+     */
+    showWhenDependsReady?: boolean;
+    /** Advanced visibility — evaluated against page context + current filter values. */
+    visibleWhen?: import('./page').ConditionGroup | null;
+    /** Shown in the disabled dropdown before parents are selected. */
+    disabledPlaceholder?: string;
+    style?: FilterBarSelectStyle;
+    /** Optional derived context when All vs specific (see {@link FilterValueExportConfig}). */
+    valueExport?: FilterValueExportConfig;
+}
+export interface FilterBarWidgetConfig {
+    filterGroupKey: string;
+    filters: FilterBarFilterConfig[];
+    /** Mirror filter values into page context for Show when / API placeholders. Default true. */
+    syncToContext?: boolean;
+    /** All listed param keys must be non-empty before `onFiltersComplete` runs. */
+    requiredFilterKeys?: string[];
+    onFiltersComplete?: WidgetActionConfig;
+    layout?: 'row' | 'wrap' | 'grid';
+    gap?: string;
+    labelPosition?: 'top' | 'inline';
+    style?: ButtonStyleOverrides;
+    tabId?: string;
+}
 export interface FormEmbedWidgetConfig extends FormEmbedScrollConfig {
     formId: string;
     formName?: string;
@@ -325,6 +758,17 @@ export interface WorkflowEmbedWidgetConfig {
     workflowName?: string;
     mode: 'tracker' | 'start' | 'approval';
     contextVariableMapping?: Record<string, string>;
+    /**
+     * Page-context key whose value is the workflow subject user id (applicant user_id).
+     * Empty uses `applicantUserId`. The id is sent only when that context value is non-empty,
+     * so embeds without it keep using the signed-in user.
+     */
+    subjectUserContextKey?: string;
+    /**
+     * Page-context key for the workflow feature id. Empty uses `featureId`.
+     * Omitted from the state request when the context value is empty.
+     */
+    featureContextKey?: string;
 }
 export interface ButtonWidgetConfig {
     label: string;
@@ -332,6 +776,7 @@ export interface ButtonWidgetConfig {
     size?: 'sm' | 'default' | 'lg';
     icon?: string;
     action: WidgetActionConfig;
+    style?: ButtonStyleOverrides;
 }
 export interface PageNavWidgetConfig {
     showPrevious?: boolean;
@@ -347,6 +792,57 @@ export interface PageNavWidgetConfig {
         label?: string;
     };
 }
+export type SidebarNavDisplayMode = 'auto' | 'text_only' | 'text_with_icon';
+export interface SidebarNavItemConfig {
+    id: string;
+    label: string;
+    iconUrl?: string;
+    iconAlt?: string;
+    disabled?: boolean;
+    action?: WidgetActionConfig;
+    /** Highlight when pathname starts with this prefix. Falls back to navigate `href`. */
+    activePathPrefix?: string;
+}
+export interface SidebarNavWidgetConfig {
+    /** `auto` shows icon only when `iconUrl` is set. */
+    displayMode?: SidebarNavDisplayMode;
+    /** Optional brand row above nav items (shown when expanded). */
+    headerTitle?: string;
+    headerSubtitle?: string;
+    logoUrl?: string;
+    width?: string;
+    /** Panel padding inside the sidebar column. Use `0.25rem 0` for flush left/right edges. */
+    padding?: string;
+    /** Pull sidebar to the page's left/top edge (counters page container padding). Default true. */
+    bleedToPageEdge?: boolean;
+    /** Allow collapse to a narrow icon rail. Default true. */
+    collapsible?: boolean;
+    /** Width when collapsed. Default `3rem`. */
+    collapsedWidth?: string;
+    /** Start collapsed on first visit. */
+    defaultCollapsed?: boolean;
+    /** Panel background; defaults to host `--sidebar` token. */
+    backgroundColor?: string;
+    /** Vertical divider between sidebar and main content. */
+    showBorder?: boolean;
+    borderColor?: string;
+    itemGap?: string;
+    itemPadding?: string;
+    itemBorderRadius?: string;
+    fontSize?: string;
+    iconSize?: string;
+    iconGap?: string;
+    activeBackground?: string;
+    activeTextColor?: string;
+    inactiveTextColor?: string;
+    hoverBackground?: string;
+    sticky?: boolean;
+    /** Stretch panel to the bottom of the visible viewport (default true). */
+    fillViewportHeight?: boolean;
+    /** When route does not match, highlight this item in page preview / designer. */
+    previewHighlightItemId?: string;
+    items: SidebarNavItemConfig[];
+}
 export interface TemporalItemFieldMap {
     id: string;
     title: string;
@@ -466,6 +962,184 @@ export interface CalendarYearWidgetConfig {
     emptyMessage?: string;
     tabId?: string;
 }
+/** Page Builder progress indicator variants (single widget, multiple layouts). */
+export type ProgressBarKind = 'stepper' | 'status' | 'determinate' | 'indeterminate' | 'circular' | 'segmented' | 'upload' | 'skeleton' | 'overall_subtask';
+export type ProgressBarIconPosition = 'left' | 'right' | 'none';
+export interface ProgressBarIconStateConfig {
+    iconName?: string;
+    color?: string;
+}
+export interface ProgressBarIconsConfig {
+    mode?: 'none' | 'lucide' | 'from_api';
+    position?: ProgressBarIconPosition;
+    completed?: ProgressBarIconStateConfig;
+    active?: ProgressBarIconStateConfig;
+    pending?: ProgressBarIconStateConfig;
+}
+export interface ProgressBarColorsConfig {
+    completed?: string;
+    active?: string;
+    pending?: string;
+    connectorCompleted?: string;
+    connectorPending?: string;
+    separator?: string;
+    barFill?: string;
+    barTrack?: string;
+}
+export interface ProgressBarStepConfig {
+    id: string;
+    label: string;
+    completed?: boolean;
+    current?: boolean;
+    iconName?: string;
+}
+export interface ProgressBarStepMapping {
+    idPath?: string;
+    labelPath?: string;
+    completedPath?: string;
+    currentPath?: string;
+    iconPath?: string;
+}
+export interface ProgressBarSubtaskConfig {
+    id: string;
+    label: string;
+    value?: number;
+}
+export interface ProgressBarSubtaskMapping {
+    idPath?: string;
+    labelPath?: string;
+    valuePath?: string;
+}
+export interface ProgressBarWidgetConfig {
+    /** Default `stepper` (connected circles + connector line). */
+    kind?: ProgressBarKind;
+    title?: string;
+    /** Static progress value 0–100 (determinate, circular, upload, overall). */
+    value?: number;
+    /** API/context path to numeric progress 0–100. */
+    valuePath?: string;
+    label?: string;
+    labelPath?: string;
+    dataSource?: WidgetDataSourceConfig;
+    /** Path to step/subtask array when using API data. */
+    itemsPath?: string;
+    steps?: ProgressBarStepConfig[];
+    stepMapping?: ProgressBarStepMapping;
+    subtasks?: ProgressBarSubtaskConfig[];
+    subtaskMapping?: ProgressBarSubtaskMapping;
+    icons?: ProgressBarIconsConfig;
+    colors?: ProgressBarColorsConfig;
+    statusOptions?: {
+        showCurrentPill?: boolean;
+        currentPillBackground?: string;
+        currentPillBorder?: string;
+        /** Horizontal space between step groups (default 0.5rem). */
+        stepGap?: string;
+        /** Margin around chevron separator (default 0.25rem). */
+        separatorGap?: string;
+        /** Step icon diameter in px (default 18). */
+        iconSize?: number;
+    };
+    stepperOptions?: {
+        showConnector?: boolean;
+        labelBelow?: boolean;
+        /** Horizontal space between steps (default 2rem). */
+        stepGap?: string;
+        /** Step icon diameter in px (default 20). */
+        iconSize?: number;
+        /** Connector line thickness (default 2px). */
+        connectorThickness?: string;
+        /** `start` = compact row; `even` = stretch across full width (default start). */
+        distribute?: 'start' | 'even';
+    };
+    skeletonOptions?: {
+        rows?: number;
+    };
+    segmentedOptions?: {
+        equalWidth?: boolean;
+    };
+    circularOptions?: {
+        size?: number;
+        showValueText?: boolean;
+    };
+    stepAction?: WidgetActionConfig;
+    /** When true (default), sets active step context from the step marked Current on first load. */
+    autoSyncCurrentStepToContext?: boolean;
+    style?: ButtonStyleOverrides;
+    tabId?: string;
+}
+export interface DynamicListItemMapping {
+    idPath?: string;
+    primaryLabelPath?: string;
+    secondaryLabelPath?: string;
+    statusPath?: string;
+    iconPath?: string;
+    fileUrlPath?: string;
+}
+export interface DynamicListStatusStyle {
+    label?: string;
+    color?: string;
+    backgroundColor?: string;
+}
+export interface DynamicListWidgetConfig {
+    dataSource: WidgetDataSourceConfig;
+    itemsPath?: string;
+    itemMapping?: DynamicListItemMapping;
+    selectedContextKey?: string;
+    selectedPayloadContextKey?: string;
+    rowClickAction?: WidgetActionConfig;
+    iconMode?: 'none' | 'lucide' | 'status_check';
+    iconName?: string;
+    iconPosition?: 'left' | 'right';
+    showStatusBadge?: boolean;
+    statusValueMap?: Record<string, DynamicListStatusStyle>;
+    selectedBorderColor?: string;
+    selectedBackgroundColor?: string;
+    emptyMessage?: string;
+    autoSelectFirst?: boolean;
+    style?: ButtonStyleOverrides;
+    tabId?: string;
+}
+export type PreviewPanelMode = 'auto' | 'image' | 'pdf';
+export type PreviewPanelImageFit = 'contain' | 'width' | 'actual';
+export interface PreviewPanelWidgetConfig {
+    requireContextKeys?: string[];
+    contextObjectKey?: string;
+    urlPath?: string;
+    titlePath?: string;
+    statusPath?: string;
+    mode?: PreviewPanelMode;
+    emptyTitle?: string;
+    emptyMessage?: string;
+    minHeight?: string;
+    showOpenInNewTab?: boolean;
+    openInNewTabLabel?: string;
+    /** Image zoom + PDF viewer toolbar (default true). */
+    enableZoom?: boolean;
+    /** Fullscreen dialog for preview (default true). */
+    enableFullscreen?: boolean;
+    /** Show zoom/fit toolbar when enableZoom is true (default true). */
+    showZoomToolbar?: boolean;
+    /** Default image fit before user zoom (default contain). */
+    defaultImageFit?: PreviewPanelImageFit;
+    /** Image zoom step multiplier (default 0.25). */
+    zoomStep?: number;
+    minZoom?: number;
+    maxZoom?: number;
+    /** PDF zoom step in percent (default 25). */
+    pdfZoomStep?: number;
+    pdfMinZoom?: number;
+    pdfMaxZoom?: number;
+    /** Download / print / rotate / Google Drive viewer actions (default all on). */
+    viewerActions?: {
+        download?: boolean;
+        print?: boolean;
+        rotate?: boolean;
+        googleDrive?: boolean;
+    };
+    style?: ButtonStyleOverrides;
+    tabId?: string;
+}
 export interface YearStepperWidgetConfig {
     label?: string;
     contextKey?: string;
@@ -762,5 +1436,5 @@ export interface DualListWidgetConfig {
     tabId?: string;
 }
 /** Union of Phase 1 widget configs plus tabId for tab_group children */
-export type PageWidgetConfig = SectionWidgetConfig | ColumnsWidgetConfig | CardWidgetConfig | TabGroupWidgetConfig | HeadingWidgetConfig | TextWidgetConfig | StatCardWidgetConfig | DataTableWidgetConfig | SearchFilterWidgetConfig | FormEmbedWidgetConfig | WorkflowEmbedWidgetConfig | ButtonWidgetConfig | ButtonGroupWidgetConfig | PageNavWidgetConfig | StatGridWidgetConfig | WeekCalendarWidgetConfig | DetailCardWidgetConfig | DualListWidgetConfig | TimeGridWidgetConfig | CalendarMonthWidgetConfig | CalendarYearWidgetConfig | YearStepperWidgetConfig | WeekStepperWidgetConfig | WeekSelectorWidgetConfig | DatePickerWidgetConfig | DateTimeGridWidgetConfig | EditableMatrixWidgetConfig | ChartBarWidgetConfig | ChartLineWidgetConfig | ChartAreaWidgetConfig | ChartPieWidgetConfig | ChartComboWidgetConfig | Record<string, unknown>;
+export type PageWidgetConfig = SectionWidgetConfig | ColumnsWidgetConfig | CardWidgetConfig | TabGroupWidgetConfig | HeadingWidgetConfig | TextWidgetConfig | ImageWidgetConfig | ModuleCardWidgetConfig | ModuleCardGridWidgetConfig | StatCardWidgetConfig | DataTableWidgetConfig | SearchFilterWidgetConfig | FilterBarWidgetConfig | FormEmbedWidgetConfig | WorkflowEmbedWidgetConfig | ButtonWidgetConfig | ButtonGroupWidgetConfig | PageNavWidgetConfig | SidebarNavWidgetConfig | StatGridWidgetConfig | WeekCalendarWidgetConfig | DetailCardWidgetConfig | DualListWidgetConfig | TimeGridWidgetConfig | CalendarMonthWidgetConfig | CalendarYearWidgetConfig | ProgressBarWidgetConfig | DynamicListWidgetConfig | PreviewPanelWidgetConfig | YearStepperWidgetConfig | WeekStepperWidgetConfig | WeekSelectorWidgetConfig | DatePickerWidgetConfig | DateTimeGridWidgetConfig | EditableMatrixWidgetConfig | ChartBarWidgetConfig | ChartLineWidgetConfig | ChartAreaWidgetConfig | ChartPieWidgetConfig | ChartComboWidgetConfig | Record<string, unknown>;
 //# sourceMappingURL=widget-configs.d.ts.map