v7.0.0 (Major Release)

Status: Released

This is a new major release of the @alextheman/components package. It has the potential to introduce breaking changes that may require a large amount of refactoring. Please read the description of changes and migration notes below for more information.

Description of Changes

Remove the giant folder of deprecations.
- The migration notes are gonna be long...
Change the QueryBoundaryProvider so it only takes isLoading, error, and data.
- Those are the main query states it wants to know about - the loadingFallback and parsers etc. are all concerns of its related child components.
Rename the fallback props throughout the QueryBoundary system.
- Basically, (loading|undefined|null|nullable|error|empty)Component -> $1Fallback.
- It was so easy to do here, and I'm 99% sure you can do this in your own projects and be done with it too.
Rename QueryBoundaryWrapper to QueryBoundaryItemWrapper.
Rename QueryBoundaryMap to QueryBoundaryListWrapper.
- Both of the above are more consistent with the current direction of the QueryBoundary naming conventions.
Split the SnackbarProvider into the provider and separate Snackbars renderer component.
- This gives each component a clear responsibility, aligning with the patterns found elsewhere in the package.
Add createTabGroup and related components from Lexicon.
- This currently exists in Lexicon, but feels general enough to warrant moving into here.
Add JSDoc comments to the compound interfaces of QueryBoundary.
- Previously only the component functions themselves had JSDoc comments. However, the interface that declares all the compound components also need JSDoc comments otherwise QueryBoundary.Data, for example, will not have the JSDoc comment associated with it.
Remove ScreenSizeProvider in favour of useIsLargeScreen.
- This is more reliable as it relies directly on Material UI's breakpoint system to determine if the screen should be considered large or not, as opposed to our manual calculation.
- Note that it does not give you back the precise width and height like ScreenSizeProvider did. You will either have to manually recreate the logic for that if you still want that, or in a future release I can add, say, useDimensions.
Rename useQueryBoundary, useDropdownMenu, useSnackbar, and useTheme to have the _Context suffix.
- It makes it clearer that it is a context hook.

Migration Notes

Deprecation Replacement

Replace all removed deprecations with the following:
- DropdownMenu2 -> DropdownMenuWrapper
- createQueryBoundary -> createBaseQueryBoundary | createItemQueryBoundary | createListQueryBoundary
- DarkModeToggle -> ThemeToggle
- DropdownMenu -> DropdownMenuWrapper
- DropdownMenuExternalLink -> <DropdownMenuItem component={ExternalLink} />
- DropdownMenuInternalLink -> <DropdownMenuItem component={InternalLink} />
- IconWithPopover -> No replacement, use Tooltip from @mui/material instead.
- InternalLink -> InternalLink from @alextheman/components/routing.
- ListItemInternalLink -> No replacement, use ListItem from @mui/material with component={InternalLink} instead.
- Loader -> QueryBoundaryItemWrapper
- LoaderData -> QueryBoundaryData
- LoaderError -> QueryBoundaryFallback (or, for more granular control, QueryBoundaryError and QueryBoundaryNullable)
- ModeProvider -> ThemeProvider
- NavigationBottom -> NavigationBottom from @alextheman/components/routing
- NavigationDrawer -> NavigationDrawer from @alextheman/components/routing
- PopoverText -> No replacement, use Tooltip from @mui/material instead.
- QueryBoundary -> QueryBoundaryItemWrapper
- ReactPlayground -> No replacement, use the LiveProvider and related components from react-live instead.
- SubmitButton -> form.SubmitButton, where form is the result of useAppForm created from createFormHook (as part of the Tanstack Form integration).

Additional Removals

The following have changed directly in v7 without a prior deprecation period:
- The QueryBoundary fallback props (change all throughout the QueryBoundary system):
  - loadingComponent -> loadingFallback
  - undefinedComponent -> undefinedFallback
  - nullComponent -> nullFallback
  - nullableComponent -> nullableFallback
  - errorComponent -> errorFallback
  - emptyComponent -> emptyFallback
- QueryBoundaryWrapper -> QueryBoundaryItemWrapper
- QueryBoundaryMap -> QueryBoundaryListWrapper
- CollapsableItem -> CollapsibleItem
- ScreenSizeProvider -> useIsLargeScreen (NOTE: Not a one-to-one replacement - does not provide windowWidth or windowHeight.)
- useQueryBoundary -> useQueryBoundaryContext
- useDropdownMenu -> useDropdownMenuContext
- useSnackbar -> useSnackbarContext
- useTheme -> useThemeContext

Snackbar

Wherever you were previously using SnackbarProvider, you will also need Snackbars as well. That is:

Before:

<SnackbarProvider>
  {children}
</SnackbarProvider>

After:

<SnackbarProvider>
  <Snackbars />
  {children}
</SnackbarProvider>

Entrypoints

Some components have moved to different entrypoints as a way to better group together related systems and improve bundle sizes. To determine the correct import path:

Find the component in the tree below.
Use the parent folder name as the entrypoint (the . entrypoint corresponds to the root entrypoint, @alextheman/components).
Append it to @alextheman/components.

For example:

import { QueryBoundaryItemWrapper } from "@alextheman/components/QueryBoundary";
import { SnackbarProvider } from "@alextheman/components/snackbar";
import { ThemeProvider } from "@alextheman/components/theme";

The package structure is now:

@alextheman/components
├── .
│   ├── Artwork
│   ├── CollapsibleItem
│   ├── ExternalLink
│   ├── Page
│   ├── SkeletonRow
│   ├── SwitchWithIcons
│   ├── useDebounce
│   ├── useHash
│   ├── useIsLargeScreen
│   └── ContextHookOptions
├── audio
│   ├── AudioControls
│   └── AudioProvider
├── DropdownMenu
│   ├── DropdownMenu
│   ├── DropdownMenuItem
│   ├── DropdownMenuProvider
│   ├── DropdownMenuTrigger
│   └── DropdownMenuWrapper
├── file
│   ├── FileInput
│   └── FileInputList
├── form
│   ├── createFormHook
│   ├── formHooks
│   ├── SubmitButton
│   └── TextField
├── QueryBoundary
│   ├── createBaseQueryBoundary
│   ├── createItemQueryBoundary
│   ├── createListQueryBoundary
│   ├── QueryBoundaryData
│   ├── QueryBoundaryDataMap
│   ├── QueryBoundaryError
│   ├── QueryBoundaryFallback
│   ├── QueryBoundaryItemWrapper
│   ├── QueryBoundaryListWrapper
│   ├── QueryBoundaryNullable
│   └── QueryBoundaryProvider
├── routing
│   ├── ErrorPage
│   ├── InternalLink
│   ├── MemoryRouter
│   ├── NavigationBottom
│   ├── NavigationDrawer
│   ├── Router
│   ├── Switch
│   └── useAbsoluteLocation
├── snackbar
│   ├── SnackbarProvider
│   └── Snackbars
├── Tab
│   ├── createTabGroup
│   ├── TabItem
│   ├── TabList
│   ├── TabPanel
│   └── TabProvider
└── theme
    ├── ThemeProvider
    └── ThemeToggle

Additional Notes

Oh my God, there was a lot of legacy in this package! Feels so good to finally clean all of it up now.
The refactor in Lexicon is gonna be long, I know it...
Is it worth it, though? Absolutely! I think the package now feels a lot cleaner, a lot more professional, and it feels a lot more like a collection of mini-React systems rather than just a bunch of helpers.
The context patterns we're using throughout the package are very clean - they feel simple enough to be usable, but flexible enough to accommodate for a wide range of use cases.
Really, though, the QueryBoundary system is still the thing I'm most proud of, and I think, if there's anything that I would like people to use from all this and get feedback on, it's the QueryBoundary system.
It's relatively abstract, sure, but it handles so much and offers an alternative way to approach rendering query state in the UI, and it makes the code feel a lot cleaner and declarative in my opinion.
In any case that is it! And just like I did with the other big release I did, that being alex-c-line v2, I shall leave off with our theme song!

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

v7.0.0

Choose a tag to compare

Sorry, something went wrong.