# Upgrade notes

## Breakpoint-field consolidation (release/v14, May 2026)

The six `imagecols_xs..xxl` tinyint columns on `tt_content` are
collapsed into a single `imagecols_grid` JSON column. The new column
is named `imagecols_grid` (not `imagecols`) because TYPO3 core already
ships a `tt_content.imagecols` field.

This migration is part of a larger effort that also affects
**t3bootstrap/container-bs5-templates** (`tx_t3bs_col_*` and
`tx_t3bs_cards_grid_*`). See that extension's `UPGRADE.md` for the
combined upgrade procedure.

### Backend

The six selects in the *Image columns* palette become one
`breakpointGrid` form element. `ProviderField::getImageColumnNumberItems`
still drives the option list per breakpoint.

### Frontend

`Resources/Private/Extensions/fluid_styled_content/Partials/Media/
Gallery.html` now reads `{data.imagecols_grid.xs}` etc. via the
`JsonFieldsProcessor` registered for `textmedia`, `textpic` and
`image` CTypes. Empty breakpoints fall back to `1` column (full
width) — matching the previous tinyint default.

**If you have site-specific overrides of `Gallery.html`**: update
them to use the dot notation. The flat `{data.imagecols_xs}` reads
return nothing after migration.

### Wizard

```bash
vendor/bin/typo3 upgrade:run t3bcoreMigrateImagecolsToJson
```

Idempotent. Rows whose `imagecols_grid` is already populated are
skipped. Legacy values of `1` (the historical default) are omitted
from the JSON map; only differing breakpoints are written.

### Removed

`Classes/Updates/CopyImageColsXL2XXL.php` was deleted. It targeted
legacy columns that no longer exist after this migration.

### New shared utilities

This release moves three classes from
`t3bootstrap/container-bs5-templates` into `t3b_core` because they
are generic backend/frontend utilities:

- `T3Bootstrap\Core\Backend\Form\Element\BreakpointGridElement`
  — `renderType: breakpointGrid`
- `T3Bootstrap\Core\Backend\Form\Element\SpacerSelectElement`
  — `renderType: spacerSelect`
- `T3Bootstrap\Core\Frontend\DataProcessing\JsonFieldsProcessor`
  — decodes JSON columns for Fluid

Custom TCA registrations referencing the old container-bs5-templates
namespaces should switch to the new `T3Bootstrap\Core\…` ones.