An open source design system that's fully customizable and agent ready
TypeScript
feat(Banner): expose frame theme target (#6007)
freddymeta47a7ffbf3d47
diff --git a/.changeset/banner-frame-theme-target.md b/.changeset/banner-frame-theme-target.mdnew file mode 100644index 0000000000..23916cbb3e--- /dev/null+++ b/.changeset/banner-frame-theme-target.md@@ -0,0 +1,6 @@+---+'@astryxdesign/core': patch+---++[feat] Banner exposes a `banner-frame` theme target on the visible frame that owns whole-banner elevation and the elevated-card silhouette. The target reflects `container` and `elevation`; existing Banner targets and default rendering are unchanged.+@freddymetadiff --git a/apps/storybook/rtl-audit/verified-not-applicable.json b/apps/storybook/rtl-audit/verified-not-applicable.jsonindex 5bd1de6b30..129e15eb81 100644--- a/apps/storybook/rtl-audit/verified-not-applicable.json+++ b/apps/storybook/rtl-audit/verified-not-applicable.json@@ -4,7 +4,7 @@"reason": "Banner renders a single wrap-capable flex header row — status icon, title/description column, and an end area pushed over with `marginInlineStart: 'auto'` — above an optional content panel. Its status, close and expand glyphs (`info`, `warning`, `error`, `success`, `close`, `chevronDown`) are all radially symmetric or vertical, and the expanded state rotates the chevron 180° about the block axis. Every inset, corner radius and border it draws is a logical property, so the whole banner mirrors under RTL with nothing positioned, ordered or animated along the inline axis for the audit to assert.","evidence": {"apps/storybook/stories/Banner.stories.tsx": "sha256:15792a91bf7a7df1d6e15085cc42b9fc7f4df05135d09b6360b2a24ca2a6db5d",- "packages/core/src/Banner/Banner.tsx": "sha256:a17ff3f61b7ee40a407373486366877684c650e7d08ae9fc2d8606c0bae9de66",+ "packages/core/src/Banner/Banner.tsx": "sha256:d69e58bc792b8c8802311aacd7b629c890915424f5b575d3bb3f71645db9c77f","packages/core/src/Banner/index.ts": "sha256:64591b4c3a37ae382a910fc9314300c3045bf8d602b28cc60a681d7b8f3a17f6"}},diff --git a/packages/core/src/Banner/Banner.doc.mjs b/packages/core/src/Banner/Banner.doc.mjsindex 8c56970eb2..8895e7f958 100644--- a/packages/core/src/Banner/Banner.doc.mjs+++ b/packages/core/src/Banner/Banner.doc.mjs@@ -129,6 +129,7 @@ export const docs = {},theming: {targets: [+ {className: 'astryx-banner-frame', visualProps: ['container', 'elevation']},{className: 'astryx-banner', visualProps: ['container', 'status']},{className: 'astryx-banner-icon', visualProps: ['status']},{className: 'astryx-banner-description'},@@ -191,6 +192,13 @@ export const docsZh = {],theming: {targets: [+ {+ className: 'astryx-banner-frame',+ visualProps: [+ 'container',+ 'elevation',+ ],+ },{className: 'astryx-banner',visualProps: [diff --git a/packages/core/src/Banner/Banner.spec.md b/packages/core/src/Banner/Banner.spec.mdindex e936c6750c..1760d3070b 100644--- a/packages/core/src/Banner/Banner.spec.md+++ b/packages/core/src/Banner/Banner.spec.md@@ -34,9 +34,8 @@ system_specs: []## IntentBanner presents a persistent status message at the top of a page or section.-This contract records the current painted surfaces and admits the Banner frame as-a separately targetable surface. Runtime implementation follows in a separate-change; the existing status and content targets remain unchanged.+This contract records the current painted surfaces and the Banner frame as a+separately targetable surface. The status and content targets remain unchanged.## Compatibility and migration@@ -75,18 +74,18 @@ prop vocabulary or extensibility rule changes.## Behavioral and layout contract-The requirements below distinguish current implementation from the approved-additive target contract.+The requirements below describe the current implementation and its additive+frame target contract.-| ID | Invariant | Basis | Contract state |-| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | ---------------------------------------- |-| FR1 | The current render places `banner` on the colored status surface, which is Banner's primary painted surface and reflects `container` and `status`. | Current source, public docs, and tests | Current behavior |-| FR2 | The Banner frame receives the public ref, role, supported DOM props, `xstyle`, `className`, and `style`; it also paints the selected `boxShadow`. | Current source and tests | Current behavior |-| FR3 | An elevated `card` frame also paints the whole-banner radius. A `section` frame remains square. A non-elevated frame does not receive the frame-radius style. | Current source and elevation tests | Current behavior |-| FR4 | Card shape is split across surface owners: the status surface owns all corners without visible content or the top corners with visible content; the content surface owns the bottom corners. | Current source | Current behavior |-| FR5 | Theme-authored `borderRadius` on `banner` currently writes the private `--_banner-radius` variable on the Status surface only. CSS inheritance does not carry that value upward to the frame or sideways to the Content surface, so both keep their fallback radius. | Current compiler output and CSS inheritance | Current reachability gap |-| FR6 | The Banner frame MUST expose `banner-frame` and reflect `container` and `elevation`. The existing `banner` target MUST remain on the Status surface rather than move to the outermost DOM element. | Owner decision; `component:Banner/DEC-1` | Current contract; implementation pending |-| FR7 | `banner-frame` is additive. The existing `banner`, `banner-icon`, `banner-description`, and `banner-content` targets and their current axes MUST remain unchanged. | Current target inventory; compatibility policy | Current contract; implementation pending |+| ID | Invariant | Basis | Contract state |+| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | ------------------------ |+| FR1 | The current render places `banner` on the colored status surface, which is Banner's primary painted surface and reflects `container` and `status`. | Current source, public docs, and tests | Current behavior |+| FR2 | The Banner frame receives the public ref, role, supported DOM props, `xstyle`, `className`, and `style`; it also paints the selected `boxShadow`. | Current source and tests | Current behavior |+| FR3 | An elevated `card` frame also paints the whole-banner radius. A `section` frame remains square. A non-elevated frame does not receive the frame-radius style. | Current source and elevation tests | Current behavior |+| FR4 | Card shape is split across surface owners: the status surface owns all corners without visible content or the top corners with visible content; the content surface owns the bottom corners. | Current source | Current behavior |+| FR5 | Theme-authored `borderRadius` on `banner` currently writes the private `--_banner-radius` variable on the Status surface only. CSS inheritance does not carry that value upward to the frame or sideways to the Content surface, so both keep their fallback radius. | Current compiler output and CSS inheritance | Current reachability gap |+| FR6 | The Banner frame exposes `banner-frame` and reflects `container` and `elevation`. The existing `banner` target remains on the Status surface rather than moving to the outermost DOM element. | Owner decision; current source and tests | Current behavior |+| FR7 | `banner-frame` is additive. The existing `banner`, `banner-icon`, `banner-description`, and `banner-content` targets and their current axes remain unchanged. | Current target inventory; compatibility policy | Current behavior |### Allowed variation@@ -145,11 +144,7 @@ unqualified `banner` target.```json{- "Banner frame": {- "none": {- "reason": "reachability-gap: The approved banner-frame target is not yet emitted or documented by the runtime implementation."- }- },+ "Banner frame": {"target": "banner-frame"},"Status surface": {"target": "banner"},"Icon": {"target": "banner-icon"},"Title": {"inherits": "banner"},@@ -164,10 +159,9 @@ unqualified `banner` target.}```-This map records current runtime reachability. `banner` belongs to the primary-Status surface rather than the outermost DOM element. DEC-1 admits the Banner-frame under `banner-frame`; its temporary `none` disposition is therefore a-reachability gap that the implementation change must close.+This map records runtime reachability. `banner` belongs to the primary Status+surface rather than the outermost DOM element, while `banner-frame` belongs to+the visible frame that owns whole-banner elevation and silhouette.## Family and system relationships@@ -180,13 +174,13 @@ reachability gap that the implementation change must close.## Verification map-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |-| ------------------- | -------------------------------------------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ----------------------- |-| FR1, FR7 | `Banner.test.tsx` and `themingTargets.test.ts` | Status surface, content surface, current target axes | Moving, removing, or changing an existing target breaks current assertions. | `audit:Banner/theming` |-| FR2, FR3, FR4 | `Banner.test.tsx` plus current source inspection | Flat/elevated card and elevated section | Frame, status surface, content surface, shadow, or radius ownership changes from the recorded state. | `audit:Banner/surfaces` |-| FR5 | Compiler output plus browser/computed-style evidence | Card with and without content; elevated card | `banner.borderRadius` unexpectedly reaches the frame/content, or docs claim that the current route already does. | `audit:Banner/radius` |-| FR6, FR7 | Implementation PR target, compiler, probe, and component tests | Card/section across none, low, med, and high elevation | `banner-frame` is absent, uses another name, misses an axis, or moves the existing `banner` target. | `audit:Banner/theming` |-| Theming anatomy map | `scripts/check-knowledge.mjs` | Eight anatomy entries and four currently emitted targets | Missing, extra, prefixed, stale, or unclaimed current mappings fail validation. | `audit:Banner/theming` |+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |+| ------------------- | -------------------------------------------------------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- | ----------------------- |+| FR1, FR7 | `Banner.test.tsx` and `themingTargets.test.ts` | Status surface, content surface, current target axes | Moving, removing, or changing an existing target breaks current assertions. | `audit:Banner/theming` |+| FR2, FR3, FR4 | `Banner.test.tsx` plus current source inspection | Flat/elevated card and elevated section | Frame, status surface, content surface, shadow, or radius ownership changes from the recorded state. | `audit:Banner/surfaces` |+| FR5 | Compiler output plus browser/computed-style evidence | Card with and without content; elevated card | `banner.borderRadius` unexpectedly reaches the frame/content, or docs claim that the current route already does. | `audit:Banner/radius` |+| FR6, FR7 | Implementation PR target, compiler, probe, and component tests | Card/section across none, low, med, and high elevation | `banner-frame` is absent, uses another name, misses an axis, or moves the existing `banner` target. | `audit:Banner/theming` |+| Theming anatomy map | `scripts/check-knowledge.mjs` | Eight anatomy entries and five current targets | Missing, extra, prefixed, stale, or unclaimed current mappings fail validation. | `audit:Banner/theming` |## Decision logdiff --git a/packages/core/src/Banner/Banner.test.tsx b/packages/core/src/Banner/Banner.test.tsxindex 0ba4d2d4f9..98d19b2592 100644--- a/packages/core/src/Banner/Banner.test.tsx+++ b/packages/core/src/Banner/Banner.test.tsx@@ -4,7 +4,8 @@* @file Banner.test.tsx* @input Uses vitest, @testing-library/react, Banner component* @output Unit tests for Banner component behavior, including the- * 'banner-icon' theme target riding on the status icon glyph (#4166)+ * 'banner-frame' theme target on the outer elevation/radius painter and the+ * 'banner-icon' theme target on the status icon glyph (#4166)* @position Testing; validates Banner.tsx implementation** SYNC: When modified, update this header@@ -14,6 +15,7 @@ import {describe, it, expect, vi, afterEach} from 'vitest';import {render, screen} from '@testing-library/react';import userEvent from '@testing-library/user-event';import {Banner} from './Banner';+import {defineTheme, generateThemeCSS} from '../theme';import {registerIcons, resetIcons} from '../Icon';import {InternationalizationProvider} from '../i18n';@@ -511,6 +513,57 @@ describe('Banner', () => {});describe('elevation', () => {+ it("carries the 'banner-frame' target and its visual axes on the outer painter", () => {+ const containers = ['card', 'section'] as const;+ const elevations = ['none', 'low', 'med', 'high'] as const;++ for (const containerType of containers) {+ for (const elevation of elevations) {+ const {container, unmount} = render(+ <Banner+ status="info"+ title="Heads up"+ container={containerType}+ elevation={elevation}+ />,+ );+ const frame = container.firstElementChild;+ expect(frame).toHaveClass(+ 'astryx-banner-frame',+ containerType,+ elevation,+ );+ expect(frame).toHaveAttribute('data-container', containerType);+ expect(frame).toHaveAttribute('data-elevation', elevation);+ expect(frame?.firstElementChild).toHaveClass('astryx-banner');+ expect(frame?.firstElementChild).not.toHaveClass(+ 'astryx-banner-frame',+ );+ unmount();+ }+ }+ });++ it('lets a theme set frame shadow and radius without a structural selector', () => {+ const theme = defineTheme({+ name: 'banner-frame-test',+ components: {+ 'banner-frame': {+ 'container:card+elevation:high': {+ boxShadow: 'var(--shadow-high)',+ borderRadius: 'var(--radius-element)',+ },+ },+ },+ });+ const {component: css} = generateThemeCSS(theme);++ expect(css).toContain('.astryx-banner-frame.card.high');+ expect(css).toContain('box-shadow: var(--shadow-high)');+ expect(css).toContain('border-radius: var(--radius-element)');+ expect(css).not.toContain(':has(');+ });+it('renders a distinct root class for each elevation level', () => {const classFor = (elevation: 'none' | 'low' | 'med' | 'high') => {const {container} = render(diff --git a/packages/core/src/Banner/Banner.tsx b/packages/core/src/Banner/Banner.tsxindex 864908e76f..85c0f9c474 100644--- a/packages/core/src/Banner/Banner.tsx+++ b/packages/core/src/Banner/Banner.tsx@@ -9,7 +9,8 @@* @position Core implementation; consumed by index.ts, tested by Banner.test.tsx** Visual structure:- * - Root container: layout-only wrapper (flex column), no visual styling, no theme target+ * - Banner frame (themeProps 'banner-frame'): owns the resting elevation and,+ * for elevated card banners, the outer radius that shapes that shadow* - Header area (themeProps 'banner'): colored status background with icon, title, description, actions, dismiss* - Content area (themeProps 'banner-content'): card background for additional content (children)* - Status icon (themeProps 'banner-icon'): the target rides on the default@@ -226,7 +227,7 @@ const statusIconColor: Partial<Record<BannerStatus, IconColor>> = {// =============================================================================const styles = stylex.create({- // Root container — layout only, no visual styling+ // Root container — outer elevation and elevated-card radius painterroot: {display: 'flex',flexDirection: 'column',@@ -577,6 +578,7 @@ export function Banner({handlePointerDownCapture,)}{...mergeProps(+ themeProps('banner-frame', {container, elevation}),stylex.props(styles.root,elevationStyles[elevation],diff --git a/packages/themes/probe/src/probeTheme.ts b/packages/themes/probe/src/probeTheme.tsindex d77e82f94a..49fd142399 100644--- a/packages/themes/probe/src/probeTheme.ts+++ b/packages/themes/probe/src/probeTheme.ts@@ -6,7 +6,7 @@// test fixture. Regenerate with: pnpm visual:probe-theme//// defineTheme takes six things and this covers all six:-// components 274 targets, 885 selectors (generated from the docs)+// components 277 targets, 898 selectors (generated from the docs)// tokens custom properties, read back off the themed element// icons every registry entry swapped for a marked glyph// indicators check / radio / checkbox swapped — the swap that reaches furthest@@ -586,6 +586,50 @@ export const probeTheme = defineTheme({outlineColor: 'hsl(35.6 93% 25%)',},},+ 'banner-frame': {+ base: {+ backgroundColor: 'hsl(25.7 70% 48%)',+ color: 'hsl(251.7 82% 12%)',+ borderColor: 'hsl(334.6 70% 25%)',+ outlineColor: 'hsl(51.5 85% 25%)',+ },+ 'container:card': {+ backgroundColor: 'hsl(314.7 89% 46%)',+ color: 'hsl(112.0 92% 12%)',+ borderColor: 'hsl(10.8 90% 25%)',+ outlineColor: 'hsl(162.5 70% 25%)',+ },+ 'container:section': {+ backgroundColor: 'hsl(16.1 83% 50%)',+ color: 'hsl(305.4 91% 12%)',+ borderColor: 'hsl(67.5 85% 25%)',+ outlineColor: 'hsl(233.6 86% 25%)',+ },+ 'elevation:none': {+ backgroundColor: 'hsl(315.3 93% 58%)',+ color: 'hsl(195.7 86% 12%)',+ borderColor: 'hsl(182.2 90% 25%)',+ outlineColor: 'hsl(265.5 79% 25%)',+ },+ 'elevation:low': {+ backgroundColor: 'hsl(284.0 78% 47%)',+ color: 'hsl(172.7 94% 12%)',+ borderColor: 'hsl(53.0 72% 25%)',+ outlineColor: 'hsl(203.0 93% 25%)',+ },+ 'elevation:med': {+ backgroundColor: 'hsl(138.9 75% 47%)',+ color: 'hsl(78.8 92% 12%)',+ borderColor: 'hsl(238.6 87% 25%)',+ outlineColor: 'hsl(142.1 93% 25%)',+ },+ 'elevation:high': {+ backgroundColor: 'hsl(252.5 72% 55%)',+ color: 'hsl(117.7 77% 12%)',+ borderColor: 'hsl(330.0 77% 25%)',+ outlineColor: 'hsl(12.3 88% 25%)',+ },+ },'banner-icon': {base: {backgroundColor: 'hsl(262.3 84% 51%)',@@ -4585,6 +4629,22 @@ export const probeTheme = defineTheme({outlineColor: 'hsl(94.7 77% 25%)',},},+ 'stepper-frame': {+ base: {+ backgroundColor: 'hsl(220.4 78% 60%)',+ color: 'hsl(124.6 78% 12%)',+ borderColor: 'hsl(219.2 77% 25%)',+ outlineColor: 'hsl(209.9 87% 25%)',+ },+ },+ 'stepper-summary': {+ base: {+ backgroundColor: 'hsl(56.5 79% 47%)',+ color: 'hsl(163.3 90% 12%)',+ borderColor: 'hsl(253.4 72% 25%)',+ outlineColor: 'hsl(238.5 80% 25%)',+ },+ },switch: {base: {backgroundColor: 'hsl(355.8 75% 58%)',@@ -5488,6 +5548,30 @@ export const probeTheme = defineTheme({borderColor: 'hsl(260.2 75% 25%)',outlineColor: 'hsl(14.9 76% 25%)',},+ 'elevation:none': {+ backgroundColor: 'hsl(55.4 88% 60%)',+ color: 'hsl(28.2 76% 12%)',+ borderColor: 'hsl(276.0 80% 25%)',+ outlineColor: 'hsl(245.4 91% 25%)',+ },+ 'elevation:low': {+ backgroundColor: 'hsl(243.3 91% 61%)',+ color: 'hsl(328.4 93% 12%)',+ borderColor: 'hsl(96.5 91% 25%)',+ outlineColor: 'hsl(237.2 83% 25%)',+ },+ 'elevation:med': {+ backgroundColor: 'hsl(98.3 88% 61%)',+ color: 'hsl(125.6 75% 12%)',+ borderColor: 'hsl(195.0 93% 25%)',+ outlineColor: 'hsl(298.1 83% 25%)',+ },+ 'elevation:high': {+ backgroundColor: 'hsl(118.2 84% 63%)',+ color: 'hsl(163.2 82% 12%)',+ borderColor: 'hsl(50.2 88% 25%)',+ outlineColor: 'hsl(32.5 75% 25%)',+ },isPressed: {backgroundColor: 'hsl(134.4 77% 49%)',color: 'hsl(197.7 74% 12%)',