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.mdnew file mode 100644index 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.++@cixzhangdiff --git a/packages/core/src/Layer/Layer.doc.mjs b/packages/core/src/Layer/Layer.doc.mjsindex 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.tsxindex 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.tsxindex 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) {