@furystack/shades-common-components 13.4.1 → 14.0.0

package/src/components/page-container/index.spec.tsx

@@ -2,6 +2,7 @@ import { Injector } from '@furystack/inject'
 import { createComponent, flushUpdates, initializeShadeRoot } from '@furystack/shades'
 import { usingAsync } from '@furystack/utils'
 import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { cssVariableTheme } from '../../services/css-variable-theme.js'
 import { PageContainer } from './index.js'
 
 describe('PageContainer component', () => {
@@ -76,7 +77,7 @@ describe('PageContainer component', () => {
   })
 
   describe('default styling', () => {
-    it('should apply default padding of 24px', async () => {
+    it('should apply default padding from theme spacing', async () => {
       await usingAsync(new Injector(), async (injector) => {
         const rootElement = document.getElementById('root') as HTMLDivElement
 
@@ -88,11 +89,11 @@ describe('PageContainer component', () => {
 
         await flushUpdates()
         const element = document.querySelector('div[is="shade-page-container"]') as HTMLDivElement
-        expect(element.style.padding).toBe('24px')
+        expect(element.style.padding).toBe(cssVariableTheme.spacing.md)
       })
     })
 
-    it('should apply default gap of 16px', async () => {
+    it('should apply default gap from theme spacing', async () => {
       await usingAsync(new Injector(), async (injector) => {
         const rootElement = document.getElementById('root') as HTMLDivElement
 
@@ -104,7 +105,7 @@ describe('PageContainer component', () => {
 
         await flushUpdates()
         const element = document.querySelector('div[is="shade-page-container"]') as HTMLDivElement
-        expect(element.style.gap).toBe('16px')
+        expect(element.style.gap).toBe(cssVariableTheme.spacing.md)
       })
     })
 

package/src/components/page-container/index.tsx

@@ -50,7 +50,7 @@ export type PageContainerProps = {
  * ```
  */
 export const PageContainer = Shade<PageContainerProps>({
-  shadowDomName: 'shade-page-container',
+  customElementName: 'shade-page-container',
   elementBase: HTMLDivElement,
   elementBaseName: 'div',
   css: {
@@ -62,7 +62,13 @@ export const PageContainer = Shade<PageContainerProps>({
     position: 'relative',
   },
   render: ({ props, children, useHostProps }) => {
-    const { maxWidth = '100%', centered = false, padding = '24px', gap = '16px', fullHeight = true } = props
+    const {
+      maxWidth = '100%',
+      centered = false,
+      padding = cssVariableTheme.spacing.md,
+      gap = cssVariableTheme.spacing.md,
+      fullHeight = true,
+    } = props
 
     const hostStyle: Record<string, string> = {
       maxWidth,

package/src/components/page-container/page-header.tsx

@@ -56,7 +56,7 @@ export type PageHeaderProps = {
  * ```
  */
 export const PageHeader = Shade<PageHeaderProps>({
-  shadowDomName: 'shade-page-header',
+  customElementName: 'shade-page-header',
   css: {
     display: 'block',
     fontFamily: cssVariableTheme.typography.fontFamily,

package/src/components/page-layout/index.spec.tsx

@@ -879,4 +879,177 @@ describe('PageLayout component', () => {
       })
     })
   })
+
+  describe('Contained Mode', () => {
+    it('should set data-contained attribute on host when contained is true', async () => {
+      await usingAsync(new Injector(), async (injector) => {
+        const rootElement = document.getElementById('root') as HTMLDivElement
+
+        initializeShadeRoot({
+          injector,
+          rootElement,
+          jsxElement: (
+            <PageLayout contained>
+              <div>Content</div>
+            </PageLayout>
+          ),
+        })
+
+        await flushUpdates()
+        const pageLayout = document.querySelector('shade-page-layout')
+        expect(pageLayout?.hasAttribute('data-contained')).toBe(true)
+      })
+    })
+
+    it('should not set data-contained attribute when contained is not set', async () => {
+      await usingAsync(new Injector(), async (injector) => {
+        const rootElement = document.getElementById('root') as HTMLDivElement
+
+        initializeShadeRoot({
+          injector,
+          rootElement,
+          jsxElement: (
+            <PageLayout>
+              <div>Content</div>
+            </PageLayout>
+          ),
+        })
+
+        await flushUpdates()
+        const pageLayout = document.querySelector('shade-page-layout')
+        expect(pageLayout?.hasAttribute('data-contained')).toBe(false)
+      })
+    })
+
+    it('should have absolute positioning when contained', async () => {
+      await usingAsync(new Injector(), async (injector) => {
+        const rootElement = document.getElementById('root') as HTMLDivElement
+
+        initializeShadeRoot({
+          injector,
+          rootElement,
+          jsxElement: (
+            <PageLayout contained>
+              <div>Content</div>
+            </PageLayout>
+          ),
+        })
+
+        await flushUpdates()
+        const pageLayout = document.querySelector('shade-page-layout') as HTMLElement
+        const computedStyle = window.getComputedStyle(pageLayout)
+        expect(computedStyle.position).toBe('absolute')
+      })
+    })
+
+    it('should work with AppBar and drawers in contained mode', async () => {
+      await usingAsync(new Injector(), async (injector) => {
+        const rootElement = document.getElementById('root') as HTMLDivElement
+
+        initializeShadeRoot({
+          injector,
+          rootElement,
+          jsxElement: (
+            <PageLayout
+              contained
+              appBar={{
+                variant: 'permanent',
+                component: <div>AppBar</div>,
+              }}
+              drawer={{
+                left: {
+                  variant: 'collapsible',
+                  component: <div>Left Drawer</div>,
+                },
+              }}
+            >
+              <div>Content</div>
+            </PageLayout>
+          ),
+        })
+
+        await flushUpdates()
+
+        const pageLayout = document.querySelector('shade-page-layout') as HTMLElement & { injector: Injector }
+        expect(pageLayout.hasAttribute('data-contained')).toBe(true)
+        expect(document.body.innerHTML).toContain('page-layout-appbar')
+        expect(document.body.innerHTML).toContain('page-layout-drawer-left')
+        expect(document.body.innerHTML).toContain('page-layout-content')
+
+        const layoutService = pageLayout.injector.getInstance(LayoutService)
+        expect(layoutService.drawerState.getValue().left?.open).toBe(true)
+      })
+    })
+
+    it('should support drawer toggle in contained mode', async () => {
+      await usingAsync(new Injector(), async (injector) => {
+        const rootElement = document.getElementById('root') as HTMLDivElement
+
+        initializeShadeRoot({
+          injector,
+          rootElement,
+          jsxElement: (
+            <PageLayout
+              contained
+              drawer={{
+                left: {
+                  variant: 'collapsible',
+                  component: <div>Left Drawer</div>,
+                },
+              }}
+            >
+              <div>Content</div>
+            </PageLayout>
+          ),
+        })
+
+        await flushUpdates()
+
+        const pageLayout = document.querySelector('shade-page-layout') as HTMLElement & { injector: Injector }
+        const layoutService = pageLayout.injector.getInstance(LayoutService)
+
+        expect(pageLayout.hasAttribute('data-drawer-left-closed')).toBe(false)
+
+        layoutService.setDrawerOpen('left', false)
+        await flushUpdates()
+
+        expect(pageLayout.hasAttribute('data-drawer-left-closed')).toBe(true)
+      })
+    })
+
+    it('should support temporary drawer backdrop click in contained mode', async () => {
+      await usingAsync(new Injector(), async (injector) => {
+        const rootElement = document.getElementById('root') as HTMLDivElement
+
+        initializeShadeRoot({
+          injector,
+          rootElement,
+          jsxElement: (
+            <PageLayout
+              contained
+              drawer={{
+                left: {
+                  variant: 'temporary',
+                  defaultOpen: true,
+                  component: <div>Temporary Drawer</div>,
+                },
+              }}
+            >
+              <div>Content</div>
+            </PageLayout>
+          ),
+        })
+
+        await flushUpdates()
+        const pageLayout = document.querySelector('shade-page-layout')
+        expect(pageLayout?.hasAttribute('data-backdrop-visible')).toBe(true)
+
+        const backdrop = document.querySelector('.page-layout-drawer-backdrop') as HTMLElement
+        backdrop.click()
+        await flushUpdates()
+
+        expect(pageLayout?.hasAttribute('data-drawer-left-closed')).toBe(true)
+      })
+    })
+  })
 })

package/src/components/page-layout/index.tsx

@@ -46,6 +46,12 @@ export type PageLayoutProps = {
   topGap?: string
   /** Gap between the drawers and the content area (CSS value). Default: '0px' */
   sideGap?: string
+  /**
+   * When true, uses `position: absolute` instead of `position: fixed` so the
+   * layout fills its nearest positioned ancestor rather than the viewport.
+   * This enables nesting PageLayout instances (e.g. in a showcase grid).
+   */
+  contained?: boolean
 }
 
 const DEFAULT_APPBAR_HEIGHT = '48px'
@@ -86,7 +92,7 @@ const DEFAULT_DRAWER_WIDTH = '240px'
  * ```
  */
 export const PageLayout = Shade<PageLayoutProps>({
-  shadowDomName: 'shade-page-layout',
+  customElementName: 'shade-page-layout',
   css: {
     display: 'block',
     fontFamily: cssVariableTheme.typography.fontFamily,
@@ -102,8 +108,8 @@ export const PageLayout = Shade<PageLayoutProps>({
       margin: '0',
     },
 
-    // AppBar container
-    '& .page-layout-appbar': {
+    // AppBar container (> * > scopes to the wrapper div to prevent bleeding into nested PageLayouts)
+    '& > * > .page-layout-appbar': {
       position: 'fixed',
       top: '0',
       left: '0',
@@ -114,18 +120,18 @@ export const PageLayout = Shade<PageLayoutProps>({
     },
 
     // Auto-hide AppBar styles (controlled via host data attributes)
-    '&[data-appbar-auto-hide] .page-layout-appbar': {
+    '&[data-appbar-auto-hide] > * > .page-layout-appbar': {
       top: 'calc(-1 * var(--layout-appbar-height, 48px))',
     },
-    '&[data-appbar-auto-hide] .page-layout-appbar:hover': {
+    '&[data-appbar-auto-hide] > * > .page-layout-appbar:hover': {
       top: '0',
     },
-    '&[data-appbar-auto-hide][data-appbar-visible] .page-layout-appbar': {
+    '&[data-appbar-auto-hide][data-appbar-visible] > * > .page-layout-appbar': {
       top: '0',
     },
 
     // Drawer containers - use CSS transitions
-    '& .page-layout-drawer': {
+    '& > * > .page-layout-drawer': {
       position: 'fixed',
       top: 'var(--layout-appbar-height, 48px)',
       bottom: '0',
@@ -135,13 +141,13 @@ export const PageLayout = Shade<PageLayoutProps>({
       backgroundImage: cssVariableTheme.background.paperImage,
       transition: `transform ${cssVariableTheme.transitions.duration.slow} ${cssVariableTheme.transitions.easing.easeInOut}`,
     },
-    '& .page-layout-drawer-left': {
+    '& > * > .page-layout-drawer-left': {
       left: '0',
       width: 'var(--layout-drawer-left-configured-width, 240px)',
       borderRight: `1px solid ${cssVariableTheme.divider}`,
       transform: 'translateX(0)',
     },
-    '& .page-layout-drawer-right': {
+    '& > * > .page-layout-drawer-right': {
       right: '0',
       width: 'var(--layout-drawer-right-configured-width, 240px)',
       borderLeft: `1px solid ${cssVariableTheme.divider}`,
@@ -149,17 +155,17 @@ export const PageLayout = Shade<PageLayoutProps>({
     },
 
     // Drawer closed states (controlled via host data attributes)
-    '&[data-drawer-left-closed] .page-layout-drawer-left': {
+    '&[data-drawer-left-closed] > * > .page-layout-drawer-left': {
       transform: 'translateX(-100%)',
       pointerEvents: 'none',
     },
-    '&[data-drawer-right-closed] .page-layout-drawer-right': {
+    '&[data-drawer-right-closed] > * > .page-layout-drawer-right': {
       transform: 'translateX(100%)',
       pointerEvents: 'none',
     },
 
     // Temporary drawer backdrop
-    '& .page-layout-drawer-backdrop': {
+    '& > * > .page-layout-drawer-backdrop': {
       position: 'fixed',
       top: '0',
       left: '0',
@@ -171,13 +177,28 @@ export const PageLayout = Shade<PageLayoutProps>({
       pointerEvents: 'none',
       transition: `opacity ${cssVariableTheme.transitions.duration.slow} ${cssVariableTheme.transitions.easing.easeInOut}`,
     },
-    '&[data-backdrop-visible] .page-layout-drawer-backdrop': {
+    '&[data-backdrop-visible] > * > .page-layout-drawer-backdrop': {
       opacity: '1',
       pointerEvents: 'auto',
     },
 
+    // Contained mode - use absolute positioning instead of fixed so the layout
+    // fills its nearest positioned ancestor rather than the viewport
+    '&[data-contained]': {
+      position: 'absolute',
+    },
+    '&[data-contained] > * > .page-layout-appbar': {
+      position: 'absolute',
+    },
+    '&[data-contained] > * > .page-layout-drawer': {
+      position: 'absolute',
+    },
+    '&[data-contained] > * > .page-layout-drawer-backdrop': {
+      position: 'absolute',
+    },
+
     // Content area - uses CSS variables for positioning
-    '& .page-layout-content': {
+    '& > * > .page-layout-content': {
       position: 'absolute',
       top: '0',
       bottom: '0',
@@ -327,6 +348,7 @@ export const PageLayout = Shade<PageLayoutProps>({
     const rightContentMargin = layoutService.getContentMarginForPosition('right')
 
     useHostProps({
+      ...(props.contained ? { 'data-contained': '' } : {}),
       ...(!isLeftOpen ? { 'data-drawer-left-closed': '' } : {}),
       ...(!isRightOpen ? { 'data-drawer-right-closed': '' } : {}),
       ...(props.appBar?.variant === 'auto-hide' ? { 'data-appbar-auto-hide': '' } : {}),

package/src/components/pagination.tsx

@@ -90,7 +90,7 @@ const defaultColors = {
 }
 
 export const Pagination = Shade<PaginationProps>({
-  shadowDomName: 'shade-pagination',
+  customElementName: 'shade-pagination',
   css: {
     display: 'inline-flex',
     alignItems: 'center',

package/src/components/paper.tsx

@@ -2,7 +2,7 @@ import { Shade, createComponent } from '@furystack/shades'
 import { cssVariableTheme } from '../services/css-variable-theme.js'
 
 export const Paper = Shade<{ elevation?: 0 | 1 | 2 | 3 }>({
-  shadowDomName: 'shade-paper',
+  customElementName: 'shade-paper',
   elementBase: HTMLDivElement,
   elementBaseName: 'div',
   css: {

package/src/components/rating.spec.tsx

@@ -15,7 +15,7 @@ describe('Rating', () => {
     vi.restoreAllMocks()
   })
 
-  it('should render with shadow DOM', async () => {
+  it('should render as custom element', async () => {
     await usingAsync(new Injector(), async (injector) => {
       const rootElement = document.getElementById('root') as HTMLDivElement
 

package/src/components/rating.tsx

@@ -62,7 +62,7 @@ export type RatingProps = {
  * keyboard navigation, and theme integration.
  */
 export const Rating = Shade<RatingProps>({
-  shadowDomName: 'shade-rating',
+  customElementName: 'shade-rating',
   css: {
     display: 'inline-flex',
     fontFamily: cssVariableTheme.typography.fontFamily,

package/src/components/result.tsx

@@ -68,7 +68,7 @@ const defaultTitles: Record<ResultStatus, string> = {
  * Supports success, error, warning, info statuses and common HTTP error codes (403, 404, 500).
  */
 export const Result = Shade<ResultProps>({
-  shadowDomName: 'shade-result',
+  customElementName: 'shade-result',
   css: {
     display: 'flex',
     flexDirection: 'column',

package/src/components/skeleton.tsx

@@ -10,7 +10,7 @@ export type SkeletonProps = {
 }
 
 export const Skeleton = Shade<SkeletonProps>({
-  shadowDomName: 'shade-skeleton',
+  customElementName: 'shade-skeleton',
   render: ({ props, useRef }) => {
     const wrapperRef = useRef<HTMLDivElement>('wrapper')
     const { delay = 1500 } = props

package/src/components/suggest/index.spec.tsx

@@ -68,7 +68,7 @@ describe('Suggest', () => {
   })
 
   describe('rendering', () => {
-    it('should render with shadow DOM', async () => {
+    it('should render as custom element', async () => {
       await usingAsync(new Injector(), async (injector) => {
         const rootElement = document.getElementById('root') as HTMLDivElement
         const onSelectSuggestion = vi.fn()

package/src/components/suggest/index.tsx

@@ -41,7 +41,7 @@ const isSyncProps = (props: SuggestProps<unknown>): props is SuggestSyncProps =>
 export const Suggest: <T>(props: SuggestProps<T>, children: ChildrenList) => JSX.Element<any> = Shade<
   SuggestProps<any>
 >({
-  shadowDomName: 'shade-suggest',
+  customElementName: 'shade-suggest',
   css: {
     ...searchableInputStyles,
     fontFamily: cssVariableTheme.typography.fontFamily,

package/src/components/suggest/suggest-input.spec.tsx

@@ -47,7 +47,7 @@ describe('SuggestInput', () => {
     return new SuggestManager<TestEntry>(getEntries, getSuggestionEntry)
   }
 
-  it('should render with shadow DOM', async () => {
+  it('should render as custom element', async () => {
     await usingAsync(new Injector(), async (injector) => {
       const rootElement = document.getElementById('root') as HTMLDivElement
       const manager = createManager()

package/src/components/suggest/suggest-input.tsx

@@ -3,7 +3,7 @@ import { cssVariableTheme } from '../../services/css-variable-theme.js'
 import type { SuggestManager } from './suggest-manager.js'
 
 export const SuggestInput = Shade<{ manager: SuggestManager<any> }>({
-  shadowDomName: 'shades-suggest-input',
+  customElementName: 'shades-suggest-input',
   css: {
     width: '100%',
     fontFamily: cssVariableTheme.typography.fontFamily,

package/src/components/suggest/suggestion-list.spec.tsx

@@ -55,7 +55,7 @@ describe('SuggestionList', () => {
     return new SuggestManager<TestEntry>(getEntries, getSuggestionEntry)
   }
 
-  it('should render with shadow DOM', async () => {
+  it('should render as custom element', async () => {
     await usingAsync(new Injector(), async (injector) => {
       const rootElement = document.getElementById('root') as HTMLDivElement
       const manager = createManager()

package/src/components/suggest/suggestion-list.tsx

@@ -6,7 +6,7 @@ import type { SuggestManager } from './suggest-manager.js'
 
 export const SuggestionList: <T>(props: { manager: SuggestManager<T> }, children: ChildrenList) => JSX.Element<any> =
   Shade<{ manager: SuggestManager<any> }>({
-    shadowDomName: 'shade-suggest-suggestion-list',
+    customElementName: 'shade-suggest-suggestion-list',
     css: {
       fontFamily: cssVariableTheme.typography.fontFamily,
       '& .suggestion-items-container': {

package/src/components/tabs.tsx

@@ -13,7 +13,7 @@ export type Tab = {
 }
 
 const TabHeader = Shade<{ hash: string }>({
-  shadowDomName: 'shade-tab-header',
+  customElementName: 'shade-tab-header',
   css: {
     padding: `${cssVariableTheme.spacing.md} 40px`,
     cursor: 'pointer',
@@ -74,7 +74,7 @@ export const Tabs = Shade<{
   onAdd?: () => void
   viewTransition?: boolean | ViewTransitionConfig
 }>({
-  shadowDomName: 'shade-tabs',
+  customElementName: 'shade-tabs',
   css: {
     fontFamily: cssVariableTheme.typography.fontFamily,
     width: '100%',

package/src/components/timeline.tsx

@@ -21,7 +21,7 @@ export type TimelineItemProps = PartialElement<HTMLElement> & {
  * Renders a dot, a connector tail, and the item's content (children).
  */
 export const TimelineItem = Shade<TimelineItemProps>({
-  shadowDomName: 'shade-timeline-item',
+  customElementName: 'shade-timeline-item',
   css: {
     display: 'flex',
     position: 'relative',
@@ -157,7 +157,7 @@ export type TimelineProps = PartialElement<HTMLElement> & {
  * Supports left, right, and alternate layout modes with optional pending state.
  */
 export const Timeline = Shade<TimelineProps>({
-  shadowDomName: 'shade-timeline',
+  customElementName: 'shade-timeline',
   css: {
     display: 'flex',
     flexDirection: 'column',

package/src/components/tooltip.tsx

@@ -23,7 +23,7 @@ export type TooltipProps = {
 }
 
 export const Tooltip = Shade<TooltipProps>({
-  shadowDomName: 'shade-tooltip',
+  customElementName: 'shade-tooltip',
   css: {
     position: 'relative',
     fontFamily: cssVariableTheme.typography.fontFamily,

package/src/components/tree/tree-item.tsx

@@ -20,7 +20,7 @@ const INDENT_PX = 20
 const EXPAND_ICON_WIDTH = 20
 
 export const TreeItem: <T>(props: TreeItemProps<T>, children: ChildrenList) => JSX.Element<any> = Shade({
-  shadowDomName: 'shade-tree-item',
+  customElementName: 'shade-tree-item',
   css: {
     display: 'flex',
     fontFamily: cssVariableTheme.typography.fontFamily,

package/src/components/tree/tree.tsx

@@ -24,7 +24,7 @@ export type TreeProps<T> = {
 } & PartialElement<HTMLDivElement>
 
 export const Tree: <T>(props: TreeProps<T>, children: ChildrenList) => JSX.Element<any> = Shade({
-  shadowDomName: 'shade-tree',
+  customElementName: 'shade-tree',
   css: {
     display: 'block',
     fontFamily: cssVariableTheme.typography.fontFamily,

package/src/components/typography.tsx

@@ -298,7 +298,7 @@ const shadesByTag = {} as Record<TypographyTag, (props: TypographyProps, childre
 
 for (const [tag, elementBase] of tagConfigs) {
   shadesByTag[tag] = Shade<TypographyProps>({
-    shadowDomName: `shade-typography-${tag}`,
+    customElementName: `shade-typography-${tag}`,
     elementBase,
     elementBaseName: tag,
     css: typographyCss,

package/src/components/wizard/index.spec.tsx

@@ -7,7 +7,7 @@ import type { WizardStepProps } from './index.js'
 import { Wizard } from './index.js'
 
 const Step1 = Shade<WizardStepProps>({
-  shadowDomName: 'wizard-test-step-1',
+  customElementName: 'wizard-test-step-1',
   render: ({ props }) => (
     <div className="wizard-step" data-step-name="step1">
       <span className="step-info">
@@ -25,7 +25,7 @@ const Step1 = Shade<WizardStepProps>({
 })
 
 const Step2 = Shade<WizardStepProps>({
-  shadowDomName: 'wizard-test-step-2',
+  customElementName: 'wizard-test-step-2',
   render: ({ props }) => (
     <div className="wizard-step" data-step-name="step2">
       <span className="step-info">
@@ -43,7 +43,7 @@ const Step2 = Shade<WizardStepProps>({
 })
 
 const Step3 = Shade<WizardStepProps>({
-  shadowDomName: 'wizard-test-step-3',
+  customElementName: 'wizard-test-step-3',
   render: ({ props }) => (
     <div className="wizard-step" data-step-name="step3">
       <span className="step-info">

package/src/components/wizard/index.tsx

@@ -43,7 +43,7 @@ export interface WizardProps {
 }
 
 export const Wizard = Shade<WizardProps>({
-  shadowDomName: 'shades-wizard',
+  customElementName: 'shades-wizard',
   css: {
     fontFamily: cssVariableTheme.typography.fontFamily,
     '& .wizard-container': {