METADATA
=======
Last Updated: 2026-09-18 16:23 UTC
Title: BlazorBlueprint - Migrating from Version 3 to Version 4
Library Version: 4

The complete checklist of breaking changes when upgrading an application from
BlazorBlueprint version 3 to version 4, ordered by severity. Every other version 4
change is additive or the namespace move in item 7.

Install and configuration steps are in setup.txt. The AsChild defaults table and
the class-merge rules are in patterns.txt. Per-component parameter tables are in
components/ and primitives/.

================================================================================
BREAKING CHANGES CHECKLIST
================================================================================

1. .NET 10 minimum (severity: high)
   Retarget applications to `net10.0` and move Microsoft.AspNetCore.Components
   package references to 10.0.x before upgrading. .NET 8 and .NET 9 cannot
   consume version 4. Keep Components and Primitives on matching version 4 releases.

2. BbDrawerTrigger and BbDrawerClose render a real <button> (severity: medium)
   Add AsChild="true" wherever the child is a BbButton. Otherwise a <button> is
   nested inside a <button>, which is invalid HTML. A plain <button> child cannot
   read the trigger context, so AsChild="true" would leave it dead: replace it
   with a BbButton, or drop it and put its content straight into the trigger.

     <BbDrawerTrigger AsChild="true">
         <BbButton Variant="ButtonVariant.Outline">Open</BbButton>
     </BbDrawerTrigger>

   Plain content (text, an icon, a <span>) needs no change and is now reachable by
   keyboard. Find usages by searching for <BbDrawerTrigger> and <BbDrawerClose>
   without AsChild and checking the next element.

3. BbTooltipTrigger.AsChild defaults to false (severity: medium)
   Add AsChild="true" wherever the child consumes the trigger context, such as a
   BbButton:

     <BbTooltipTrigger AsChild="true">
         <BbButton Variant="ButtonVariant.Outline">Hover me</BbButton>
     </BbTooltipTrigger>

   A bare icon, plain text or arbitrary markup needs no change. With
   AsChild="false" the trigger wraps its content in an outer <span> with
   display: contents and an inner <span> that carries the handlers. This adds
   DOM levels (affects :first-child selectors, querySelector paths and test
   hooks). Only the
   styled Components-layer trigger changed; the Primitives-layer BbTooltipTrigger
   already defaulted to false.

4. Every utility in blazorblueprint.css is prefixed bb: (severity: low; medium
   if you used the library's utilities without your own Tailwind build)
   - With your own Tailwind build: no markup changes. Remove any `@source` that
     points at the BlazorBlueprint package or sources. Load order no longer matters
     for utilities; keep your theme stylesheet before blazorblueprint.css.
   - Without a Tailwind build: standard classes in your own markup no longer match
     anything in blazorblueprint.css. Add a Tailwind build (the standalone CLI
     needs no Node.js), or use `bb:`-prefixed classes such as
     `class="bb:flex bb:gap-4"` as a stopgap.
   - `group` and `peer` markers still reach the DOM unprefixed as well as
     prefixed, so `group-*` and `peer-*` variants you hung off library markup in
     version 3 keep working unchanged.

5. Renamed safelisted utilities
   `shimmer` is now `bb:shimmer`, and `scroll-fade-x` is now `bb:scroll-fade-x`:

     <BbMarkerContent Class="bb:shimmer">Thinking...</BbMarkerContent>

6. Internal class selectors
   CSS, JavaScript or tests that select the library's internal elements by utility
   class (`.flex-col`, `.group\/row`, `.hidden`) need the prefix
   (`.bb\:flex-col`). Prefer the `data-slot` and other data attributes the
   components render; those are stable.

7. Portal host components moved to BlazorBlueprint.Primitives (severity: low)
   BbPortalHost, BbContainerPortalHost, BbOverlayPortalHost and
   BbCategoryPortalHost moved out of BlazorBlueprint.Primitives.Services into
   BlazorBlueprint.Primitives. The services themselves (IPortalService,
   PortalService) did not move; PortalCategory is in BlazorBlueprint.Primitives.

   Nothing to change if _Imports.razor already has both:

     @using BlazorBlueprint.Components
     @using BlazorBlueprint.Primitives

   A file that imports only BlazorBlueprint.Primitives.Services and writes
   <BbPortalHost /> needs @using BlazorBlueprint.Primitives added. An unresolved
   Razor tag is not a build error: the compiler emits <bbportalhost> as literal
   HTML, so no host registers and every overlay silently fails to render. The only
   symptom is a runtime warning that the host is missing from a layout that
   contains it.

8. NavigationMenuContext trigger registration is keyed by the trigger
   (severity: low)
   Only affects code that drives the NavigationMenu primitive directly. Using
   BbNavigationMenu and its parts needs no change.

     Removed                                    Replacement
     int RegisterTrigger(ElementReference)      void RegisterTrigger(object owner,
                                                  ElementReference)
     void UpdateTriggerRef(int, ElementRef)     Call RegisterTrigger(owner, ref)
                                                  again; it replaces the reference
     -                                          void UnregisterTrigger(object owner)
     -                                          int TriggerIndexOf(object owner)

   Pass the trigger component as its own identity and read the index at the point
   of use instead of storing the one you were handed:

     @implements IDisposable
     @code {
         protected override void OnAfterRender(bool firstRender)
             => Menu.RegisterTrigger(this, element);

         private int Index => Menu.TriggerIndexOf(this);

         public void Dispose() => Menu.UnregisterTrigger(this);
     }

   An index-based list could not express removal, so triggers that left the page
   stayed registered and arrow-key navigation stepped onto buttons that no longer
   existed. GetTriggerAt(int) and TriggerCount are unchanged.

9. Parameters that never did anything are removed (severity: low)
   Each was accepted and then ignored. Deleting them changes no behaviour; it
   turns a silent no-op into a compile error.

     Removed                                  Use instead
     BbCalendar.Mode and the CalendarMode      BbDateRangePicker for a range.
       enum                                    BbCalendar is single-select and
                                                never read the mode.
     BbCommand.CloseOnSelect                   BbCommandDialog.CloseOnSelect. The
                                                dialog closes, not the list.
     Stacked and StackGroup on BbPie,          Nothing. Stacking lives on
       BbFunnel, BbGauge, BbRadar,              StackableSeriesBase, so the
       BbHeatmap, BbCandlestick                 parameters appear only on BbBar,
                                                BbLine, BbArea, BbScatter and
                                                BbRadialBar, where they work.

   These are the only public members removed in version 4. Everything else in the
   surface is additive or the namespace move in item 7.

Not a breaking change: the AsChild default on BbPopoverTrigger, BbDialogTrigger,
BbSheetTrigger, BbDropdownMenuTrigger, BbHoverCardTrigger and
BbCollapsibleTrigger is unchanged; all six still default to true. Those triggers
render their own element in the non-AsChild branch and open on click, which any
focusable child delivers by bubbling. Tooltip opens on hover and focus, which do
not bubble, which is why only tooltip changed. See patterns.txt for the full table
of AsChild defaults.

Recommended while upgrading: add theme-init.js to <head> (see APPLYING THE SAVED
THEME BEFORE FIRST PAINT) and pin Quill to 2.0.3 if you use BbRichTextEditor.