paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 46 Packages Projects Releases Wiki Activity

Refactor Bg providers

Browse Source 
Signed-off-by: Charles de Dreuille <charles.dedreuille@gmail.com>
This commit is contained in:
Charles de Dreuille
2026-02-10 16:55:04 +00:00
parent fa4678d895
commit b113fb9359
23 changed files with 260 additions and 258 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.changeset/clean-bags-occur.md
+27 -10
View File
@@ -2,15 +2,32 @@
'@backstage/ui': minor
---
**BREAKING**: Replaced `Surface` / `onSurface` system with new `ContainerBg` background system
**BREAKING**: Replaced `Surface` / `onSurface` system with new provider/consumer background system
The old `Surface` type (`'0'`–`'3'`, `'auto'`) and its associated props (`surface`, `onSurface`) have been replaced by `ContainerBg` — a union of `'neutral-1'` | `'neutral-2'` | `'neutral-3'` | `'danger'` | `'warning'` | `'success'`. There is no `neutral-4` value; containers are capped at `neutral-3`. Leaf components like Button no longer accept a `bg` prop — they inherit the parent container's `bg` via a `data-on-bg` attribute, and CSS handles the visual step-up to the next neutral level.
The old `Surface` type (`'0'`–`'3'`, `'auto'`) and its associated props (`surface`, `onSurface`) have been replaced by a provider/consumer bg architecture.
New `useBg` hook and `BgProvider` replace the deleted `useSurface` hook and `SurfaceProvider`.
**Types:**
- `ContainerBg` — `'neutral-1'` | `'neutral-2'` | `'neutral-3'` | `'danger'` | `'warning'` | `'success'`
- `ProviderBg` — `ContainerBg | 'neutral-auto'`
There is no `neutral-4` prop value; containers are capped at `neutral-3`. Consumer components (e.g. Button) inherit the parent's bg via `data-on-bg`, and CSS handles the visual step-up.
**Hooks:**
- `useBgProvider(bg?)` — for provider components. Returns `{ bg: undefined }` when no bg is given (transparent). Supports `'neutral-auto'` to auto-increment from the parent context.
- `useBgConsumer()` — for consumer components. Returns the parent container's bg unchanged.
- The old `useBg` hook and `UseBgOptions` interface have been removed.
**Component roles:**
- **Provider-only** (Box, Flex, Grid): set `data-bg`, wrap children in `BgProvider`. Transparent by default.
- **Consumer-only** (Button, ButtonIcon, ButtonLink): set `data-on-bg`, inherit from parent.
- **Provider + Consumer** (Card): sets both `data-bg` and `data-on-bg`, wraps children. Defaults to `neutral-auto`.
**Migration:**
Rename the `surface` prop to `bg` on container components and update values:
Rename the `surface` prop to `bg` on provider components and update values:
```diff
- <Box surface="1">
@@ -26,7 +43,7 @@ Rename the `surface` prop to `bg` on container components and update values:
+ <Grid.Root bg="neutral-1">
```
Remove `onSurface` from leaf components — they now always inherit from the parent container and can no longer override the value:
Remove `onSurface` from consumer components — they now always inherit from the parent container:
```diff
- <Button onSurface="1" variant="secondary">
@@ -43,20 +60,20 @@ Update type imports:
```diff
- import type { Surface, LeafSurfaceProps, ContainerSurfaceProps } from '@backstage/ui';
+ import type { ContainerBg } from '@backstage/ui';
+ import type { ContainerBg, ProviderBg } from '@backstage/ui';
```
Replace hook usage in custom components:
```diff
- import { useSurface, SurfaceProvider } from '@backstage/ui';
+ import { useBg, BgProvider } from '@backstage/ui';
+ import { useBgProvider, useBgConsumer, BgProvider } from '@backstage/ui';
- const { surface } = useSurface({ surface: props.surface });
+ const { bg } = useBg({ mode: 'container', bg: props.bg });
+ const { bg } = useBgProvider(props.bg);
- const { surface } = useSurface({ onSurface: props.onSurface });
+ const { bg } = useBg({ mode: 'leaf' });
+ const { bg } = useBgConsumer();
```
Update CSS selectors targeting surface data attributes:
@@ -69,6 +86,6 @@ Update CSS selectors targeting surface data attributes:
+ [data-on-bg='neutral-1'] { ... }
```
Note: Container components use `data-bg` (values: `neutral-1` through `neutral-3`, plus intents). Leaf components use `data-on-bg`, which reflects the parent container's bg directly (no auto-increment).
Note: Provider components use `data-bg` (values: `neutral-1` through `neutral-3`, plus intents). Consumer components use `data-on-bg`, which reflects the parent container's bg directly (no auto-increment).
**Affected components:** Box, Button, ButtonIcon, ButtonLink, ToggleButton, Card, Flex, Grid