Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

[Component Audit] LayerProvider: its docs reach editors and describe nested providers correctly (#10283)

Cindy Zhang445b2b7a86bb
diff --git a/.changeset/layer-provider-docs-nested.md b/.changeset/layer-provider-docs-nested.md
new file mode 100644
index 0000000000..dd162cb3f1
--- /dev/null
+++ b/.changeset/layer-provider-docs-nested.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[docs] `LayerProvider`: editors and generated docs now show its description and example; they were attached to an internal constant. The docs no longer say that a nested provider is ignored: a nested provider keeps the outer toast configuration and mounts no second toast viewport, and one that declares `inset` applies its declared edges to the anchored layers in its subtree.
+
+@cixzhang
diff --git a/packages/core/src/Layer/Layer.doc.mjs b/packages/core/src/Layer/Layer.doc.mjs
index 69306c85e1..c620f3746d 100644
--- a/packages/core/src/Layer/Layer.doc.mjs
+++ b/packages/core/src/Layer/Layer.doc.mjs
@@ -40,7 +40,7 @@ export const docs = {
{
guidance: false,
description:
- 'Add nested LayerProvider instances: nested providers are ignored and add unnecessary tree depth.',
+ 'Nest a LayerProvider to change toast settings: a nested provider keeps the outer toast configuration and mounts no second toast viewport.',
},
],
},
@@ -49,7 +49,7 @@ export const docs = {
name: 'LayerProvider',
displayName: 'Layer Provider',
description:
- 'App-level provider for layer systems such as toast viewports and imperative modals. Nested providers pass through.',
+ 'App-level configuration for toasts and the viewport inset. A nested provider mounts no second toast viewport and keeps the outer toast configuration; one that declares an inset applies its declared edges to the anchored layers in its subtree.',
props: [
{
name: 'children',
@@ -93,7 +93,8 @@ export const docsDense = {
},
{
guidance: false,
- description: 'Add nested LayerProvider instances.',
+ description:
+ 'Nest LayerProvider for toast config: a nested provider keeps the outer toast config.',
},
],
},
diff --git a/packages/core/src/Layer/LayerProvider.test.tsx b/packages/core/src/Layer/LayerProvider.test.tsx
index 34fd4a0774..f6067f0d9c 100644
--- a/packages/core/src/Layer/LayerProvider.test.tsx
+++ b/packages/core/src/Layer/LayerProvider.test.tsx
@@ -8,13 +8,15 @@
* (spec:AST-059 FR6, DEC-5)
*/
+import {useEffect} from 'react';
import {describe, expect, it} from 'vitest';
-import {fireEvent, render} from '@testing-library/react';
+import {fireEvent, render, screen} from '@testing-library/react';
import {LayerProvider} from './LayerProvider';
// The toast viewport these cases read registers itself as its module loads.
import '../Toast/ToastViewport';
import {useLayer} from './useLayer';
import {layerInsetProperties} from './layerInset';
+import {useToast} from '../Toast/useToast';
function AnchoredLayer() {
const layer = useLayer({mode: 'context'});
@@ -41,6 +43,16 @@ function PortaledLayer() {
);
}
+function ShowsThree() {
+ const showToast = useToast();
+ useEffect(() => {
+ for (const body of ['One', 'Two', 'Three']) {
+ showToast({body, isAutoHide: false});
+ }
+ }, [showToast]);
+ return null;
+}
+
describe('LayerProvider inset (spec:AST-059 FR6)', () => {
it('declares nothing by default, so a default provider matches no provider', () => {
expect(layerInsetProperties(undefined)).toEqual({});
@@ -143,3 +155,37 @@ describe('LayerProvider inset (spec:AST-059 FR6)', () => {
expect(viewport.style.insetInlineStart).toBe('');
});
});
+
+describe('LayerProvider toast configuration', () => {
+ it('passes toast.maxVisible to the toast viewport', async () => {
+ render(
+ <LayerProvider toast={{maxVisible: 2}}>
+ <ShowsThree />
+ </LayerProvider>,
+ );
+ expect(await screen.findByText('Three')).toBeInTheDocument();
+ expect(screen.getByText('Two')).toBeInTheDocument();
+ expect(screen.queryByText('One')).not.toBeInTheDocument();
+ });
+
+ it('keeps one toast viewport and the outer toast configuration under a nested provider without inset', async () => {
+ const {container} = render(
+ <LayerProvider toast={{maxVisible: 1}}>
+ <span data-testid="outer">outer</span>
+ <LayerProvider toast={{maxVisible: 5}}>
+ <span data-testid="app">app</span>
+ <ShowsThree />
+ </LayerProvider>
+ </LayerProvider>,
+ );
+ expect(await screen.findByText('Three')).toBeInTheDocument();
+ expect(screen.queryByText('Two')).not.toBeInTheDocument();
+ expect(
+ container.querySelectorAll('[popover="manual"]:not([id])'),
+ ).toHaveLength(1);
+ // The nested provider adds no element around its children.
+ expect(screen.getByTestId('app').parentElement).toBe(
+ screen.getByTestId('outer').parentElement,
+ );
+ });
+});
diff --git a/packages/core/src/Layer/LayerProvider.tsx b/packages/core/src/Layer/LayerProvider.tsx
index 3de0e38138..df0ad8c6b6 100644
--- a/packages/core/src/Layer/LayerProvider.tsx
+++ b/packages/core/src/Layer/LayerProvider.tsx
@@ -30,15 +30,18 @@ export interface LayerProviderProps {
inset?: LayerInset;
}
+const DEFAULT_TOAST_CONFIG = {};
+
/**
- * App-level provider for layer systems (toast, sheet, imperative modals).
+ * App-level configuration for toasts and the viewport inset.
*
* Optional — hooks fall back to a lazy self-mounting viewport when no
* provider exists. The provider renders the toast viewport once Toast is
- * imported; without Toast it renders no empty viewport. Nested providers are
- * no-ops, except that one declaring an `inset` narrows it for the anchored
- * layers in its subtree. `inset` declares a persistent bar floating over a
- * viewport edge once; anchored layers and toasts both clear it.
+ * imported; without Toast it renders no empty viewport. A nested provider
+ * keeps the outer toast configuration and mounts no second viewport. One that
+ * declares an `inset` applies its declared edges to the anchored layers in its
+ * subtree. `inset` declares a persistent bar floating over a viewport edge
+ * once; anchored layers and toasts both clear it.
*
* @example
* ```
@@ -47,8 +50,6 @@ export interface LayerProviderProps {
* </LayerProvider>
* ```
*/
-const DEFAULT_TOAST_CONFIG = {};
-
export function LayerProvider({
children,
toast: toastConfig = DEFAULT_TOAST_CONFIG,
@@ -66,8 +67,8 @@ export function LayerProvider({
[existingContext, inset],
);
- // Nested provider — pass through. One that declares an inset narrows it
- // for the anchored layers in its subtree (an app hosted inside another
+ // Nested provider — pass through. One that declares an inset applies it
+ // to the anchored layers in its subtree (an app hosted inside another
// provider can still declare its own bar); the toast viewport is the
// root's and reads the root's declaration.
if (existingContext) {