feat(core)!: Banner content is visible by default; collapse moves to a collapsible prop

[freddymeta]

The gap

Banner infers its disclosure from its content: any children get a chevron in
the header and are hidden until it is pressed. There is no way to have content
and no toggle — which is the case a banner most often wants, the list of the
three fields that failed validation — and defaultIsExpanded is the only knob,
with no controlled mode.

The shape

Adding an isCollapsible boolean beside defaultIsExpanded would put two props
on one axis, where one silently voids the other — the prop-independence
principle, and precisely the clutter API Conventions § Boolean-or-Config
Props
names (isCollapsible + defaultIsCollapsed + onCollapsedChange). So the
whole axis becomes one prop, the shape SideNav.collapsible set:

/** @default true */
collapsible?: boolean | CollapsibleConfig;

<Banner status="warning" title="Config changed">…</Banner>          // unchanged: collapsible, starts closed
<Banner collapsible={false}>…</Banner>                              // new: always visible, no toggle
<Banner collapsible={{defaultIsOpen: true}}>…</Banner>              // replaces defaultIsExpanded
<Banner collapsible={{isOpen, onOpenChange}}>…</Banner>             // new: controlled

The default is unchanged. collapsible defaults to true, and Banner hands
the hook defaultIsOpen: false — the one place it departs from useCollapsible,
which opens by default. A banner's message lives in its header and its content is
supplementary, and that is the behaviour Banner has always had.

Three deliberate choices:

• CollapsibleConfig, not a Banner-only vocabulary. The exported type from
  useCollapsible — so a banner's disclosure is configured exactly like
  Collapsible's, and there is no third spelling of the same three fields.
• The shared hook, not local useState. Banner no longer owns collapse
  state at all (Use the System, rule 3). Controlled mode comes for free, which
  is why it is in this PR rather than a later one.
• The default lives on the prop, not in a second prop. collapsible={false}
  is the opt-out; there is nothing else on the axis to contradict it.

Lint-wise the boolean | Config union is exempt from
@astryx/boolean-prop-naming, so the unprefixed name is legal; a bare
isCollapsible: boolean would not have been.

With collapsible={false} there is no toggle, no aria-expanded /
aria-controls, and the content region stays mounted with no id.

Evidence

Real builds, shot in Chromium — before from main at 5ab0625, after from
this branch. Harness and DOM facts on the
assets branch
(delete it after merge).

Nothing moves for existing code. A banner with children and no collapse prop,
and one that starts open, are byte-identical PNGs across the two builds
(dfbfe0a7… and 147e808b…):

default (children, no prop)	starts open

collapsible={false} is the new capability. Before, that content was
unreachable behind a chevron; after, it is simply there.

before	after

Read off the DOM: before {buttons: ["Expand"], listItems: 0, ariaExpanded: ["false"]}, after {buttons: [], listItems: 3, ariaExpanded: []}.

What breaks, and the codemod

Only the prop rename: defaultIsExpanded is gone in favour of the config. That
is a type error at every call site, not a silent behaviour change — nothing
changes under anyone without a compiler error first.

Codemod: npx astryx upgrade --codemod banner-collapsible-content
(staged in transforms/next/ per Release Process § Writing a
codemod).

before	after
defaultIsExpanded / ={true}	collapsible={{defaultIsOpen: true}}
defaultIsExpanded={false}	(removed — it is the default)
defaultIsExpanded={expr}	collapsible={{defaultIsOpen: expr}}
children, no prop	(untouched)

It only fires on a Banner imported from @astryxdesign/core —
defaultIsExpanded is a ChatToolCalls prop too — and declines to guess around
a spread. One deliberate scope boundary: the prop inside a props object (a
Storybook args) is left alone rather than rewritten on a guess about which
component the object feeds; the removed prop makes those a type error, so the
compiler finds them. verify-codemods passes as a superset — Storybook's Banner
stories are this transform's own output plus the new opt-out demos, with the
args sites migrated by hand.

Accessibility note

Content that is always visible inside role="alert" means an error banner
announces its detail along with its title. Usually what you want for a list of
validation errors; worth knowing when reaching for collapsible={false}. The
Banner.doc.mjs best practices now say to use it when the user needs the content
to act on the message, and to keep the toggle when the detail is long enough to
bury the banner's own message.

Test plan

• pnpm test — 536 files / 10946 tests pass. Banner is 47 tests (8 new or
  rewritten: default-unchanged, explicit true, collapsible={false}, the
  disclosure wiring absent when opted out, defaultIsOpen: true,
  onOpenChange, controlled). Codemod is 12 tests.
• pnpm lint:strict — 0 errors (56 pre-existing warnings, none in touched files).
• pnpm build — clean. pnpm -F @astryxdesign/core typecheck — clean.
• node .github/scripts/codemod-verify.mjs — reproducible.
• Chromium before/after above.

Also updated: Banner.doc.mjs (en + zh + dense, props, anatomy, best practices),
stories, and the BannerCollapsibleContent showcase block.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
astryx	Ready	Preview	Aug 21, 2026 12:59am

[github-actions]

PR Analysis Report

📚 Storybook Preview

View Storybook for this PR
GitHub Pages may take up to a minute to hydrate after deploy.

🧪 Sandbox Preview

View Sandbox for this PR
GitHub Pages may take up to a minute to hydrate after deploy.

Modified Components

Banner _{(@astryxdesign/core)} · View in Storybook

Metric	Before	After	Delta
Bundle Size (ESM)	N/A	N/A	N/A
Lines of Code	N/A	411	-
Complexity	N/A	Very High (40)	-

Bundle Size Summary

Package	Size (ESM)	Size (CJS)	Gzipped
@astryxdesign/core	N/A	4.8KB	1.2KB

Accessibility Audit

Status: No accessibility violations detected.

---

_{Generated by PR Enrichment workflow | Storybook | Sandbox | View full report}

[cixzhang]

This is the better pattern but I think we should avoid breakage. Could we:

• keep an internal default for collapsible
• allow users to pass collapsible={false} or collapsible={} in order to customize it?

[freddymeta]

Done — the default is back, and the only thing left breaking is the prop name.

collapsible now defaults to true, and Banner hands the shared hook
defaultIsOpen: false. That is the one point where it departs from
useCollapsible, which opens by default: a banner's message lives in its header
and the content is supplementary, so starting closed is right for Banner and is
what it has always done. A call site that never mentioned the collapse axis is
untouched — I re-shot both builds and the default case and the starts-open case
are byte-identical PNGs (dfbfe0a7…, 147e808b…), not just visually close.

So the axis reads:

<Banner status="warning" title="Config changed">…</Banner>   // unchanged
<Banner collapsible={false}>…</Banner>                       // content, no toggle
<Banner collapsible={{defaultIsOpen: true}}>…</Banner>       // was defaultIsExpanded
<Banner collapsible={{isOpen, onOpenChange}}>…</Banner>      // controlled

defaultIsExpanded still goes, though — I did not keep it as a deprecated
alias, and that is the one place I have taken a position rather than followed
yours. Two props on the same axis is the thing this shape exists to remove, and
this residue is a type error at every call site, so nobody's UI changes under
them without the compiler saying so first. The codemod covers it
(npx astryx upgrade --codemod banner-collapsible-content): defaultIsExpanded
→ collapsible={{defaultIsOpen: true}}, defaultIsExpanded={false} dropped
since it is the default, and banners that never set it are left alone. Say the
word if you would rather have a deprecation window and I will add it back as
@deprecated with a documented precedence.

One scope boundary worth flagging: the codemod is JSX-only. defaultIsExpanded
inside a props object — a Storybook args, say — is left alone rather than
rewritten on a guess about which component the object feeds (ChatToolCalls has
a prop of the same name). Removing the prop makes those a type error, so they
are found, just by tsc rather than by the transform. Our own stories had three
such sites; I migrated them by hand and verify-codemods passes as a superset.