@ttoss/layouts 0.4.37 → 0.5.1

package/README.md

@@ -1,6 +1,6 @@
 # @ttoss/layouts
 
-**@ttoss/layouts** is a collection of React components that implement the layouts to use in your application.
+Professional layout components for React applications with responsive design and accessibility built-in.
 
 ## Installation
 
@@ -8,51 +8,166 @@
 pnpm add @ttoss/layouts @ttoss/ui @emotion/react
 ```
 
-## Quickstart
+## Available Layouts
 
-Use a layout as `StackedLayout` to add specific layout to your application:
+### StackedLayout - Simple Vertical Layout
+
+Perfect for traditional websites with header, main content, and footer.
 
 ```tsx
 import { Layout, StackedLayout } from '@ttoss/layouts';
 
 const App = () => (
   <StackedLayout>
-    <Layout.Header>Header</Layout.Header>
-    <Layout.Main>Main</Layout.Main>
-    <Layout.Footer>Footer</Layout.Footer>
+    <Layout.Header>Navigation & Branding</Layout.Header>
+    <Layout.Main>Page Content</Layout.Main>
+    <Layout.Footer>Copyright & Links</Layout.Footer>
   </StackedLayout>
 );
 ```
 
-## Layouts
+### SidebarCollapseLayout - Dashboard & Admin Interfaces
+
+Responsive sidebar that collapses on mobile, perfect for dashboards and admin panels.
+
+```tsx
+import { Layout, SidebarCollapseLayout } from '@ttoss/layouts';
+
+const Dashboard = () => (
+  <SidebarCollapseLayout>
+    <Layout.Header showSidebarButton>App Header with Menu Toggle</Layout.Header>
+    <Layout.Sidebar>Navigation Menu</Layout.Sidebar>
+    <Layout.Main.Header>Page Title & Actions</Layout.Main.Header>
+    <Layout.Main>Dashboard Content</Layout.Main>
+    <Layout.Main.Footer>Status Bar</Layout.Main.Footer>
+  </SidebarCollapseLayout>
+);
+```
 
-Check the [Layouts Stories](http://localhost:6006/?path=/story/layouts-layout) to see the available layouts.
+## Core Components
 
-## Custom Layout Components
+### Layout.Main Sub-Components
 
-You can create your own layout components by using the `Layout` sub-components:
+Enhanced main content area with optional header and footer sections.
 
 ```tsx
-import { Layout, StackedLayout } from '@ttoss/layouts';
+<Layout.Main.Header>
+  <h1>Page Title</h1>
+  <button>Action Button</button>
+</Layout.Main.Header>
+
+<Layout.Main>
+  Main content with consistent padding and overflow handling
+</Layout.Main>
+
+<Layout.Main.Footer>
+  <span>Last updated: Today</span>
+</Layout.Main.Footer>
+```
 
-const CustomHeader = (props) => (
-  <Layout.Header {...props} style={{ backgroundColor: 'red' }}>
-    Header
-  </Layout.Header>
+## Automatic Layout Composition
+
+**Key Concept**: Layout components automatically detect and organize their child components by `displayName`, even when components are distributed across different files or routing structures.
+
+### React Router Integration
+
+Perfect for apps where layout components come from different routes:
+
+```tsx
+// App.tsx - Layout wrapper
+import { Layout, SidebarCollapseLayout } from '@ttoss/layouts';
+import { Outlet } from 'react-router-dom';
+
+const AppLayout = () => (
+  <SidebarCollapseLayout>
+    <AppHeader />
+    <AppSidebar />
+    <Outlet /> {/* Routes render here */}
+  </SidebarCollapseLayout>
 );
 
-CustomHeader.displayName = Layout.Header.displayName;
+// pages/Dashboard.tsx - Page-specific components
+const Dashboard = () => (
+  <>
+    <Layout.Main.Header>
+      <h1>Dashboard</h1>
+    </Layout.Main.Header>
+    <Layout.Main>
+      <DashboardCharts />
+    </Layout.Main>
+    <Layout.Main.Footer>Last updated: {lastUpdate}</Layout.Main.Footer>
+  </>
+);
+```
 
-const App = () => (
-  <StackedLayout>
-    <CustomHeader />
-    <Layout.Main>Main</Layout.Main>
-    <Layout.Footer>Footer</Layout.Footer>
-  </StackedLayout>
+The layout **automatically composes** itself by finding components with matching `displayName` properties, regardless of component hierarchy or file structure.
+
+### Component Detection System
+
+```tsx
+// These components can be anywhere in your component tree:
+<Layout.Header />     // → Detected as "Header"
+<Layout.Sidebar />    // → Detected as "Sidebar"
+<Layout.Main />       // → Detected as "Main"
+<Layout.Footer />     // → Detected as "Footer"
+<Layout.Main.Header />  // → Detected as "MainHeader"
+<Layout.Main.Footer />  // → Detected as "MainFooter"
+```
+
+## Component Properties
+
+### Responsive Behavior
+
+- **Desktop**: Sidebar remains visible, toggleable via button
+- **Mobile**: Sidebar becomes slide-out drawer, auto-closes on navigation
+- **Accessible**: Full keyboard navigation and screen reader support
+
+### Styling Integration
+
+All components integrate seamlessly with `@ttoss/ui` theme system via `sx` prop:
+
+```tsx
+<Layout.Header
+  sx={{
+    backgroundColor: 'brand.primary',
+    borderBottom: '2px solid',
+  }}
+>
+  Custom styled header
+</Layout.Header>
+```
+
+## Advanced Usage
+
+### Custom Components with displayName
+
+Create reusable layout components by preserving the required `displayName`:
+
+```tsx
+const AppHeader = ({ children, ...props }) => (
+  <Layout.Header {...props}>
+    <Logo />
+    {children}
+    <UserMenu />
+  </Layout.Header>
 );
+
+AppHeader.displayName = Layout.Header.displayName; // Required for layout detection
 ```
 
-For the layout to work correctly, you must use the `displayName` property of the `Layout` sub-components, because the layout components use the `displayName` to identify the layout sub-components.
+### Sidebar with Logo Slot
+
+Add branding or controls to the sidebar area:
+
+```tsx
+<Layout.Header sidebarSlot={<CompanyLogo />} showSidebarButton>
+  Main header content
+</Layout.Header>
+```
+
+## Examples
+
+View complete examples in [Storybook](https://storybook.ttoss.dev/?path=/story/layouts-layout).
 
 ## License
 

package/dist/esm/index.js

@@ -1,7 +1,7 @@
 /** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
 
 // src/components/Layout.tsx
-import { Box as Box5, Container } from "@ttoss/ui";
+import { Box as Box7, Container } from "@ttoss/ui";
 
 // src/components/Footer.tsx
 import { Box } from "@ttoss/ui";
@@ -2352,10 +2352,55 @@ var Header = ({
 Header.displayName = "Header";
 
 // src/components/Main.tsx
+import { Box as Box6 } from "@ttoss/ui";
+
+// src/components/MainFooter.tsx
 import { Box as Box4 } from "@ttoss/ui";
 import { jsx as jsx6 } from "react/jsx-runtime";
-var Main = props => {
+var MainFooter = props => {
   return /* @__PURE__ */jsx6(Box4, {
+    variant: "layout.main.footer",
+    ...props,
+    sx: {
+      paddingX: "10",
+      paddingY: "3",
+      borderTop: "sm",
+      borderColor: "display.border.muted.default",
+      backgroundColor: "navigation.background.primary.default",
+      width: "full",
+      ...props.sx
+    },
+    children: props.children
+  });
+};
+MainFooter.displayName = "MainFooter";
+
+// src/components/MainHeader.tsx
+import { Box as Box5 } from "@ttoss/ui";
+import { jsx as jsx7 } from "react/jsx-runtime";
+var MainHeader = props => {
+  return /* @__PURE__ */jsx7(Box5, {
+    variant: "layout.main.header",
+    ...props,
+    as: "header",
+    sx: {
+      paddingX: "4",
+      paddingY: "3",
+      borderBottom: "sm",
+      borderColor: "display.border.muted.default",
+      backgroundColor: "navigation.background.primary.default",
+      width: "full",
+      ...props.sx
+    },
+    children: props.children
+  });
+};
+MainHeader.displayName = "MainHeader";
+
+// src/components/Main.tsx
+import { jsx as jsx8 } from "react/jsx-runtime";
+var Main = props => {
+  return /* @__PURE__ */jsx8(Box6, {
     variant: "layout.main",
     ...props,
     as: "main",
@@ -2371,13 +2416,15 @@ var Main = props => {
   });
 };
 Main.displayName = "Main";
+Main.Header = MainHeader;
+Main.Footer = MainFooter;
 
 // src/components/Layout.tsx
-import { jsx as jsx7 } from "react/jsx-runtime";
+import { jsx as jsx9 } from "react/jsx-runtime";
 var Layout = ({
   children
 }) => {
-  return /* @__PURE__ */jsx7(Box5, {
+  return /* @__PURE__ */jsx9(Box7, {
     variant: "layout.layout",
     children
   });
@@ -2397,7 +2444,9 @@ var semanticComponents = {
   Header: "header",
   Sidebar: "sidebar",
   Footer: "footer",
-  Main: "main"
+  Main: "main",
+  MainHeader: "mainHeader",
+  MainFooter: "mainFooter"
 };
 var getSematicElements = ({
   children
@@ -2416,7 +2465,7 @@ var getSematicElements = ({
 };
 
 // src/components/SidebarCollapseLayout.tsx
-import { jsx as jsx8, jsxs as jsxs3 } from "react/jsx-runtime";
+import { jsx as jsx10, jsxs as jsxs3 } from "react/jsx-runtime";
 var SidebarCollapseLayout = ({
   children,
   ...props
@@ -2424,11 +2473,13 @@ var SidebarCollapseLayout = ({
   const {
     header,
     main,
-    sidebar
+    sidebar,
+    mainFooter,
+    mainHeader
   } = getSematicElements({
     children
   });
-  return /* @__PURE__ */jsx8(LayoutProvider, {
+  return /* @__PURE__ */jsx10(LayoutProvider, {
     children: /* @__PURE__ */jsxs3(Stack, {
       ...props,
       sx: {
@@ -2444,7 +2495,14 @@ var SidebarCollapseLayout = ({
           overflow: "hidden",
           flexDirection: ["row"]
         },
-        children: [sidebar, main]
+        children: [sidebar, /* @__PURE__ */jsxs3(Stack, {
+          sx: {
+            flex: 1,
+            height: "full",
+            overflow: "hidden"
+          },
+          children: [mainHeader, main, mainFooter]
+        })]
       })]
     })
   });
@@ -2452,7 +2510,7 @@ var SidebarCollapseLayout = ({
 
 // src/components/StackedLayout.tsx
 import { Stack as Stack2 } from "@ttoss/ui";
-import { jsx as jsx9, jsxs as jsxs4 } from "react/jsx-runtime";
+import { jsx as jsx11, jsxs as jsxs4 } from "react/jsx-runtime";
 var StackedLayout = ({
   children,
   ...props
@@ -2464,7 +2522,7 @@ var StackedLayout = ({
   } = getSematicElements({
     children
   });
-  return /* @__PURE__ */jsx9(LayoutProvider, {
+  return /* @__PURE__ */jsx11(LayoutProvider, {
     children: /* @__PURE__ */jsxs4(Stack2, {
       ...props,
       children: [header, main, footer]

package/dist/index.d.ts

@@ -21,6 +21,14 @@ declare const Layout: {
     Main: {
         (props: BoxProps): react_jsx_runtime.JSX.Element;
         displayName: string;
+        Header: {
+            (props: BoxProps): react_jsx_runtime.JSX.Element;
+            displayName: string;
+        };
+        Footer: {
+            (props: BoxProps): react_jsx_runtime.JSX.Element;
+            displayName: string;
+        };
     };
     Footer: {
         (props: BoxProps): react_jsx_runtime.JSX.Element;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttoss/layouts",
-  "version": "0.4.37",
+  "version": "0.5.1",
   "description": "Layout components for React",
   "license": "MIT",
   "author": "ttoss",
@@ -25,7 +25,7 @@
   "sideEffects": false,
   "peerDependencies": {
     "react": ">=16.8.0",
-    "@ttoss/components": "^2.2.26",
+    "@ttoss/components": "^2.2.27",
     "@ttoss/ui": "^5.9.2"
   },
   "devDependencies": {
@@ -34,11 +34,11 @@
     "jest": "^30.0.4",
     "react": "^19.1.0",
     "tsup": "^8.5.0",
-    "@ttoss/config": "^1.35.6",
-    "@ttoss/ui": "^5.9.2",
-    "@ttoss/components": "^2.2.26",
+    "@ttoss/components": "^2.2.27",
     "@ttoss/test-utils": "^2.1.26",
-    "@ttoss/react-icons": "^0.4.15"
+    "@ttoss/react-icons": "^0.4.15",
+    "@ttoss/config": "^1.35.6",
+    "@ttoss/ui": "^5.9.2"
   },
   "keywords": [
     "React"