@ceed/cds 1.19.0 → 1.19.1-next.1

package/dist/components/layout/Container.md

@@ -2,6 +2,8 @@
 
 ## Introduction
 
+Container is a layout component that centers content horizontally and constrains its maximum width based on predefined breakpoints. It provides consistent padding and ensures content doesn't stretch too wide on large screens, improving readability and maintaining a cohesive layout across different viewport sizes. Container is commonly used as the main wrapper for page content in admin dashboards and web applications.
+
 ```tsx
 <Container
   children={<div style={{
@@ -20,4 +22,509 @@
 
 ```tsx
 import { Container } from '@ceed/cds';
+
+function PageLayout() {
+  return (
+    <Container maxWidth="desktop">
+      <Typography level="h1">Page Title</Typography>
+      <Typography>Page content goes here...</Typography>
+    </Container>
+  );
+}
+```
+
+## Examples
+
+### Desktop
+
+Maximum width optimized for desktop screens (widest setting).
+
+```tsx
+<Container
+  children={<div style={{
+  height: '100vh',
+  backgroundColor: 'lightgray'
+}}></div>}
+  maxWidth="desktop"
+/>
+```
+
+### Laptop
+
+Medium maximum width suitable for laptop screens.
+
+```tsx
+<Container
+  children={<div style={{
+  height: '100vh',
+  backgroundColor: 'lightgray'
+}}></div>}
+  maxWidth="laptop"
+/>
+```
+
+### Tablet
+
+Narrower maximum width for tablet-optimized layouts.
+
+```tsx
+<Container
+  children={<div style={{
+  height: '100vh',
+  backgroundColor: 'lightgray'
+}}></div>}
+  maxWidth="tablet"
+/>
 ```
+
+## When to Use
+
+### ✅ Good Use Cases
+
+- **Page wrapper**: Main content area of web pages
+- **Dashboard layouts**: Admin panel content sections
+- **Article/Blog content**: Readable width for text-heavy pages
+- **Form layouts**: Centered forms with appropriate width
+- **Card grids**: Constraining grid layouts on large screens
+- **Landing pages**: Centering hero sections and content blocks
+
+### ❌ When Not to Use
+
+- **Full-width layouts**: When content should span entire viewport
+- **Sidebars**: Use dedicated sidebar components
+- **Modal content**: Modals have their own sizing
+- **Navigation bars**: Usually span full width
+- **Background elements**: Elements that should fill the screen
+
+## Common Use Cases
+
+### Page Layout with Header
+
+```tsx
+function PageWithHeader() {
+  return (
+    <>
+      <AppBar />
+      <Container maxWidth="desktop">
+        <Box sx={{ py: 4 }}>
+          <Typography level="h1">Dashboard</Typography>
+          <Grid container spacing={3} sx={{ mt: 2 }}>
+            <Grid xs={12} md={8}>
+              <Card>Main Content</Card>
+            </Grid>
+            <Grid xs={12} md={4}>
+              <Card>Sidebar Content</Card>
+            </Grid>
+          </Grid>
+        </Box>
+      </Container>
+    </>
+  );
+}
+```
+
+### Centered Form Layout
+
+```tsx
+function CenteredForm() {
+  return (
+    <Container maxWidth="tablet">
+      <Box sx={{ py: 4 }}>
+        <Typography level="h2" sx={{ mb: 3 }}>
+          Contact Us
+        </Typography>
+        <Stack gap={2}>
+          <FormControl>
+            <FormLabel>Name</FormLabel>
+            <Input placeholder="Enter your name" />
+          </FormControl>
+          <FormControl>
+            <FormLabel>Email</FormLabel>
+            <Input type="email" placeholder="Enter your email" />
+          </FormControl>
+          <FormControl>
+            <FormLabel>Message</FormLabel>
+            <Textarea minRows={4} placeholder="Your message" />
+          </FormControl>
+          <Button>Send Message</Button>
+        </Stack>
+      </Box>
+    </Container>
+  );
+}
+```
+
+### Article/Blog Layout
+
+```tsx
+function ArticlePage({ article }) {
+  return (
+    <Container maxWidth="laptop">
+      <Box sx={{ py: 4 }}>
+        <Typography level="h1" sx={{ mb: 2 }}>
+          {article.title}
+        </Typography>
+        <Stack direction="row" gap={2} sx={{ mb: 3 }}>
+          <Chip size="sm">{article.category}</Chip>
+          <Typography level="body-sm" color="neutral">
+            {article.date}
+          </Typography>
+        </Stack>
+        <Divider sx={{ mb: 3 }} />
+        <Typography sx={{ lineHeight: 1.8 }}>
+          {article.content}
+        </Typography>
+      </Box>
+    </Container>
+  );
+}
+```
+
+### Dashboard with Cards
+
+```tsx
+function Dashboard() {
+  return (
+    <Container maxWidth="desktop">
+      <Box sx={{ py: 3 }}>
+        <Typography level="h2" sx={{ mb: 3 }}>
+          Dashboard Overview
+        </Typography>
+
+        {/* Stats Row */}
+        <Grid container spacing={2} sx={{ mb: 3 }}>
+          {[
+            { label: 'Total Users', value: '1,234' },
+            { label: 'Active Sessions', value: '567' },
+            { label: 'Revenue', value: '$12,345' },
+            { label: 'Growth', value: '+15%' },
+          ].map((stat) => (
+            <Grid key={stat.label} xs={6} md={3}>
+              <Card>
+                <CardContent>
+                  <Typography level="body-sm" color="neutral">
+                    {stat.label}
+                  </Typography>
+                  <Typography level="h3">{stat.value}</Typography>
+                </CardContent>
+              </Card>
+            </Grid>
+          ))}
+        </Grid>
+
+        {/* Main Content */}
+        <Grid container spacing={2}>
+          <Grid xs={12} lg={8}>
+            <Card sx={{ height: 400 }}>
+              <CardContent>
+                <Typography level="title-lg">Activity Chart</Typography>
+                {/* Chart component */}
+              </CardContent>
+            </Card>
+          </Grid>
+          <Grid xs={12} lg={4}>
+            <Card sx={{ height: 400 }}>
+              <CardContent>
+                <Typography level="title-lg">Recent Activity</Typography>
+                {/* Activity list */}
+              </CardContent>
+            </Card>
+          </Grid>
+        </Grid>
+      </Box>
+    </Container>
+  );
+}
+```
+
+### Responsive Container Selection
+
+```tsx
+function ResponsiveLayout({ children }) {
+  const isMobile = useMediaQuery('(max-width: 600px)');
+  const isTablet = useMediaQuery('(max-width: 900px)');
+
+  // Choose appropriate container width based on content type
+  const maxWidth = isMobile ? 'tablet' : isTablet ? 'laptop' : 'desktop';
+
+  return (
+    <Container maxWidth={maxWidth}>
+      {children}
+    </Container>
+  );
+}
+```
+
+### Nested Containers
+
+```tsx
+function PageWithSections() {
+  return (
+    <>
+      {/* Full-width hero */}
+      <Box sx={{ bgcolor: 'primary.softBg', py: 6 }}>
+        <Container maxWidth="desktop">
+          <Typography level="h1">Welcome</Typography>
+          <Typography>Hero section content</Typography>
+        </Container>
+      </Box>
+
+      {/* Narrower content section */}
+      <Container maxWidth="laptop">
+        <Box sx={{ py: 4 }}>
+          <Typography level="h2">Features</Typography>
+          {/* Feature cards */}
+        </Box>
+      </Container>
+
+      {/* Even narrower for readability */}
+      <Container maxWidth="tablet">
+        <Box sx={{ py: 4 }}>
+          <Typography level="h2">About Us</Typography>
+          <Typography>Long form text content...</Typography>
+        </Box>
+      </Container>
+    </>
+  );
+}
+```
+
+## Props and Customization
+
+### Key Props
+
+| Prop       | Type                                | Default     | Description                            |
+| ---------- | ----------------------------------- | ----------- | -------------------------------------- |
+| `maxWidth` | `'desktop' \| 'laptop' \| 'tablet'` | `'desktop'` | Maximum width breakpoint               |
+| `children` | `ReactNode`                         | -           | Content to render inside the container |
+| `sx`       | `SxProps`                           | -           | Custom styles using Joy UI sx prop     |
+
+### maxWidth Breakpoints
+
+| Value     | Max Width | Best For                         |
+| --------- | --------- | -------------------------------- |
+| `desktop` | \~1200px  | Full dashboards, complex layouts |
+| `laptop`  | \~900px   | Standard content, articles       |
+| `tablet`  | \~600px   | Focused content, forms           |
+
+### Custom Styling
+
+```tsx
+// Add custom padding
+<Container maxWidth="desktop" sx={{ py: 4 }}>
+  Content
+</Container>
+
+// Add background
+<Container maxWidth="laptop" sx={{ bgcolor: 'background.level1', borderRadius: 'lg' }}>
+  Content
+</Container>
+
+// Combine with other layout props
+<Container
+  maxWidth="desktop"
+  sx={{
+    minHeight: '100vh',
+    display: 'flex',
+    flexDirection: 'column',
+  }}
+>
+  <Box sx={{ flex: 1 }}>Content</Box>
+  <Footer />
+</Container>
+```
+
+### Combining with Grid
+
+```tsx
+<Container maxWidth="desktop">
+  <Grid container spacing={3}>
+    <Grid xs={12} md={8}>
+      <Card>Main Content</Card>
+    </Grid>
+    <Grid xs={12} md={4}>
+      <Card>Sidebar</Card>
+    </Grid>
+  </Grid>
+</Container>
+```
+
+## Accessibility
+
+Container is a layout component with minimal accessibility requirements:
+
+### Semantic Structure
+
+```tsx
+// Use appropriate semantic elements inside Container
+<Container maxWidth="desktop">
+  <main>
+    <article>
+      <h1>Page Title</h1>
+      <p>Content...</p>
+    </article>
+  </main>
+</Container>
+```
+
+### Landmark Regions
+
+```tsx
+// Combine with ARIA landmarks
+<Container maxWidth="desktop">
+  <header role="banner">
+    <Typography level="h1">Site Title</Typography>
+  </header>
+  <main role="main">
+    <Typography>Main content</Typography>
+  </main>
+  <footer role="contentinfo">
+    <Typography>Footer</Typography>
+  </footer>
+</Container>
+```
+
+## Best Practices
+
+### ✅ Do
+
+1. **Use consistent container widths**: Maintain visual consistency across pages
+
+```tsx
+// ✅ Good: Consistent width for similar content
+<Container maxWidth="desktop">
+  <DashboardContent />
+</Container>
+
+<Container maxWidth="desktop">
+  <SettingsContent />
+</Container>
+```
+
+2. **Add appropriate vertical padding**: Give content breathing room
+
+```tsx
+// ✅ Good: Padding for readability
+<Container maxWidth="laptop">
+  <Box sx={{ py: 4 }}>
+    Content
+  </Box>
+</Container>
+```
+
+3. **Choose width based on content type**: Match container width to content needs
+
+```tsx
+// ✅ Good: Narrow for text, wide for data
+<Container maxWidth="tablet">  {/* Narrow for articles */}
+  <ArticleContent />
+</Container>
+
+<Container maxWidth="desktop"> {/* Wide for dashboards */}
+  <DataTable />
+</Container>
+```
+
+4. **Combine with full-width sections**: Mix constrained and full-width content
+
+```tsx
+// ✅ Good: Full-width background with constrained content
+<Box sx={{ bgcolor: 'primary.softBg' }}>
+  <Container maxWidth="desktop">
+    <HeroContent />
+  </Container>
+</Box>
+```
+
+### ❌ Don't
+
+1. **Don't use Container for modals or drawers**: They have their own sizing
+
+```tsx
+// ❌ Bad: Container inside Modal
+<Modal>
+  <Container maxWidth="tablet">Content</Container>
+</Modal>
+
+// ✅ Good: Modal handles its own sizing
+<Modal>
+  <ModalDialog sx={{ maxWidth: 400 }}>Content</ModalDialog>
+</Modal>
+```
+
+2. **Don't nest Containers unnecessarily**: One level is usually sufficient
+
+```tsx
+// ❌ Bad: Nested containers
+<Container maxWidth="desktop">
+  <Container maxWidth="laptop">
+    Content
+  </Container>
+</Container>
+
+// ✅ Good: Single container
+<Container maxWidth="laptop">
+  Content
+</Container>
+```
+
+3. **Don't use wrong width for content type**: Match width to content needs
+
+```tsx
+// ❌ Bad: Wide container for text article
+<Container maxWidth="desktop">
+  <LongArticleText /> {/* Hard to read at wide widths */}
+</Container>
+
+// ✅ Good: Appropriate width for reading
+<Container maxWidth="laptop">
+  <LongArticleText />
+</Container>
+```
+
+4. **Don't forget responsive considerations**: Content should work at all sizes
+
+## Performance Considerations
+
+### Avoid Unnecessary Re-renders
+
+Container is a simple layout component, but avoid changing `maxWidth` frequently:
+
+```tsx
+// ❌ Bad: Changing maxWidth on every render
+<Container maxWidth={isOpen ? 'laptop' : 'desktop'}>
+
+// ✅ Good: Stable maxWidth
+<Container maxWidth="desktop">
+  <Box sx={{ maxWidth: isOpen ? 900 : '100%' }}>
+```
+
+### CSS-based Responsiveness
+
+Prefer CSS media queries over JavaScript for responsive layouts:
+
+```tsx
+// ✅ Good: CSS handles responsiveness
+<Container
+  maxWidth="desktop"
+  sx={{
+    px: { xs: 2, sm: 3, md: 4 },
+    py: { xs: 2, md: 4 },
+  }}
+>
+```
+
+### Minimal DOM Nesting
+
+Container adds minimal DOM overhead. Use it at appropriate levels:
+
+```tsx
+// ✅ Good: One container at page level
+<Container maxWidth="desktop">
+  <Header />
+  <MainContent />
+  <Footer />
+</Container>
+```
+
+Container provides a simple yet essential foundation for consistent page layouts. Choose the appropriate `maxWidth` based on your content type—wider for data-heavy dashboards, narrower for text-focused content—and combine with proper vertical spacing for optimal readability.