@usefragments/ui 1.0.0

package/src/components/AppShell/AppShell.module.scss

@@ -0,0 +1,239 @@
+@use "../../tokens/variables" as *;
+@use "../../tokens/mixins" as *;
+
+// ============================================
+// AppShell Root - CSS Grid Layout
+// ============================================
+// Grid areas: header, sidebar, main, aside
+//
+// Structure is controlled by the `layout` prop ('default' | 'sidebar').
+// Visual treatment (floating) is controlled per-slot via `variant` props.
+
+.root {
+  display: grid;
+  min-height: 100vh;
+  min-height: 100dvh;
+  background-color: inherit;
+
+  // Default layout:
+  // header  header  header
+  // sidebar main    aside
+  grid-template-areas:
+    "header header header"
+    "sidebar main aside";
+  grid-template-columns:
+    var(--appshell-sidebar-width, 240px)
+    1fr
+    var(--appshell-aside-width, 0px);
+  grid-template-rows:
+    var(--appshell-header-height, var(--fui-appshell-header-height, $fui-appshell-header-height))
+    1fr;
+
+  // Smooth transition for sidebar collapse/expand
+  transition: grid-template-columns var(--fui-transition-normal, $fui-transition-normal) ease;
+
+  // Mobile: single column layout
+  @include below-md {
+    grid-template-areas:
+      "header"
+      "main"
+      "aside";
+    grid-template-columns: 1fr;
+    grid-template-rows:
+      var(--appshell-header-height, var(--fui-appshell-header-height, $fui-appshell-header-height))
+      1fr
+      auto;
+    transition: none; // No column transition on mobile
+  }
+}
+
+// Sidebar structure: sidebar spans full height
+// sidebar header header
+// sidebar main   aside
+.sidebarLayout {
+  grid-template-areas:
+    "sidebar header header"
+    "sidebar main aside";
+
+  @include below-md {
+    grid-template-areas:
+      "header"
+      "main"
+      "aside";
+    grid-template-columns: 1fr;
+  }
+}
+
+// ============================================
+// Header
+// ============================================
+
+.header {
+  grid-area: header;
+  position: sticky;
+  top: 0;
+  height: var(--appshell-header-height, var(--fui-appshell-header-height, $fui-appshell-header-height));
+  z-index: var(--fui-header-z-index, $fui-header-z-index);
+  background-color: inherit;
+
+  > header {
+    background-color: inherit;
+  }
+}
+
+// ============================================
+// Sidebar
+// ============================================
+
+.sidebar {
+  grid-area: sidebar;
+  position: sticky;
+  top: var(--appshell-header-height, var(--fui-appshell-header-height, $fui-appshell-header-height));
+  height: calc(100vh - var(--appshell-header-height, var(--fui-appshell-header-height, $fui-appshell-header-height)));
+  height: calc(100dvh - var(--appshell-header-height, var(--fui-appshell-header-height, $fui-appshell-header-height)));
+  z-index: 30;
+  overflow: hidden;
+  background-color: inherit;
+
+  > aside {
+    background-color: inherit;
+  }
+
+  // On mobile, sidebar becomes a fixed overlay
+  @include below-md {
+    position: fixed;
+    top: 0;
+    left: 0;
+    bottom: 0;
+    width: 0;
+    height: 100vh;
+    height: 100dvh;
+    z-index: 51;
+
+    // Allow the sidebar to appear as overlay on mobile
+    & > :global(.root) {
+      width: var(--appshell-sidebar-expanded-width, 240px);
+    }
+  }
+
+  // Override Sidebar component's height
+  :global(.root) {
+    height: 100%;
+
+    @include below-md {
+      height: 100vh;
+      height: 100dvh;
+    }
+  }
+}
+
+// Sidebar in sidebar structure: full height
+.sidebarFullHeight {
+  top: 0;
+  height: 100vh;
+  height: 100dvh;
+  z-index: var(--fui-header-z-index, $fui-header-z-index);
+
+  :global(.root) {
+    height: 100%;
+  }
+}
+
+// Sidebar variant="floating" is retained as an API signal; AppShell sidebars
+// inherit the body/shell canvas by default.
+.sidebarFloating {
+  background-color: inherit;
+}
+
+// ============================================
+// Main Content
+// ============================================
+
+.main {
+  grid-area: main;
+  min-height: 0; // Allow shrinking in grid
+  min-width: 0; // Prevent overflow
+  background-color: var(--fui-app-main-bg, var(--fui-main-bg, #{$fui-main-bg}));
+}
+
+// Main variant="floating": main surface inset from all edges of the shell.
+// - Inset 1px top highlight simulates a lit upper edge on dark canvases.
+// - Border + top highlight lift the panel without separating it from the canvas.
+// - Scroll is contained inside the card so the canvas stays fixed when the
+//   shell is height-constrained (e.g. 100dvh wrapper with overflow:hidden).
+.mainFloating {
+  display: flex;
+  flex-direction: column;
+  gap: var(--fui-space-2, $fui-space-2);
+  margin: var(--fui-space-1, $fui-space-1) var(--fui-space-1, $fui-space-1)
+    var(--fui-space-1, $fui-space-1) 0;
+  padding: var(--fui-space-4, $fui-space-4);
+  border: 1px solid var(--fui-border, $fui-border);
+  border-radius: var(--fui-radius-xl, $fui-radius-xl);
+  background-color: var(--fui-app-main-bg, var(--fui-main-bg, #{$fui-main-bg}));
+  box-shadow:
+    inset 0 1px 0
+      color-mix(in srgb, var(--fui-text-primary, #{$fui-text-primary}) 5%, transparent);
+  overflow: hidden auto;
+
+  @include below-md {
+    margin: var(--fui-space-1, $fui-space-1) 0;
+    border-left: none;
+    border-right: none;
+    border-radius: var(--fui-radius-lg, $fui-radius-lg);
+    width: 100%;
+  }
+}
+
+// ============================================
+// Aside (Right Panel)
+// ============================================
+
+.aside {
+  grid-area: aside;
+  position: sticky;
+  top: var(--appshell-header-height, var(--fui-appshell-header-height, $fui-appshell-header-height));
+  height: calc(100vh - var(--appshell-header-height, var(--fui-appshell-header-height, $fui-appshell-header-height)));
+  height: calc(100dvh - var(--appshell-header-height, var(--fui-appshell-header-height, $fui-appshell-header-height)));
+  width: var(--aside-width, 280px);
+  min-height: 0; // Allow shrinking in grid
+  z-index: 30;
+  background-color: var(--fui-app-sidebar-bg, inherit);
+  overflow: hidden;
+
+  // Stack below main on mobile
+  @include below-md {
+    position: static;
+    width: 100%;
+    height: auto;
+    border-top: 1px solid var(--fui-border, $fui-border);
+  }
+}
+
+// Aside variant="floating": inherits the body/shell canvas while keeping the
+// same inset geometry as a floating panel.
+.asideFloating {
+  // Override the explicit width so the aside fills its grid cell
+  // and the margin creates visible inset space from the viewport edge.
+  width: auto;
+  height: calc(100vh - var(--appshell-header-height, var(--fui-appshell-header-height, $fui-appshell-header-height)) - var(--fui-space-1, $fui-space-1) * 2);
+  height: calc(100dvh - var(--appshell-header-height, var(--fui-appshell-header-height, $fui-appshell-header-height)) - var(--fui-space-1, $fui-space-1) * 2);
+  margin: var(--fui-space-1, $fui-space-1) var(--fui-space-1, $fui-space-1)
+    var(--fui-space-1, $fui-space-1) 0;
+  border: 1px solid var(--fui-border, $fui-border);
+  border-radius: var(--fui-radius-xl, $fui-radius-xl);
+  background-color: var(--fui-panel-bg, inherit);
+  box-shadow:
+    inset 0 1px 0
+      color-mix(in srgb, var(--fui-text-primary, #{$fui-text-primary}) 5%, transparent);
+  overflow: hidden;
+
+  @include below-md {
+    margin: var(--fui-space-1, $fui-space-1) 0;
+    border-left: none;
+    border-right: none;
+    border-radius: var(--fui-radius-lg, $fui-radius-lg);
+    width: 100%;
+    height: auto;
+  }
+}

package/src/components/AppShell/AppShell.stories.tsx

@@ -0,0 +1,156 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { AppShell } from ".";
+import { Header } from "../Header";
+import { Sidebar } from "../Sidebar";
+
+/**
+ * AppShell is the full application layout wrapper integrating header, sidebar,
+ * main content, and an optional aside panel. It is a compound component:
+ * compose AppShell.Header, AppShell.Sidebar, AppShell.Main, and AppShell.Aside.
+ */
+const meta = {
+  title: "Layout/AppShell",
+  component: AppShell,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Full layout wrapper integrating sidebar, header, main content, and optional aside panel.",
+      },
+    },
+  },
+  argTypes: {
+    layout: {
+      control: "select",
+      options: ["default", "sidebar", "sidebar-floating", "floating"],
+      description: "Structural layout for CSS grid areas",
+    },
+    bg: {
+      control: "text",
+      description: "Background color override for the shell container",
+    },
+  },
+  args: {
+    layout: "default",
+    children: (
+      <>
+        <AppShell.Header>
+          <Header>
+            <Header.Brand>MyApp</Header.Brand>
+          </Header>
+        </AppShell.Header>
+        <AppShell.Sidebar width="200px">
+          <Sidebar.Nav>
+            <Sidebar.Section label="Menu">
+              <Sidebar.Item active>Home</Sidebar.Item>
+            </Sidebar.Section>
+          </Sidebar.Nav>
+        </AppShell.Sidebar>
+        <AppShell.Main padding="md">Content</AppShell.Main>
+      </>
+    ),
+  },
+} satisfies Meta<typeof AppShell>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const DefaultLayout: Story = {
+  render: () => (
+    <div style={{ height: "360px", overflow: "hidden" }}>
+      <AppShell layout="default">
+        <AppShell.Header>
+          <Header>
+            <Header.Brand>MyApp</Header.Brand>
+          </Header>
+        </AppShell.Header>
+        <AppShell.Sidebar width="200px" collapsible="offcanvas">
+          <Sidebar.Nav>
+            <Sidebar.Section label="Menu">
+              <Sidebar.Item active>Home</Sidebar.Item>
+              <Sidebar.Item>Analytics</Sidebar.Item>
+              <Sidebar.Item>Settings</Sidebar.Item>
+            </Sidebar.Section>
+          </Sidebar.Nav>
+        </AppShell.Sidebar>
+        <AppShell.Main padding="md">Header spans full width. Logo is in the header.</AppShell.Main>
+      </AppShell>
+    </div>
+  ),
+};
+
+export const SidebarLayout: Story = {
+  render: () => (
+    <div style={{ height: "360px", overflow: "hidden" }}>
+      <AppShell layout="sidebar">
+        <AppShell.Header>
+          <Header>
+            <Header.Trigger />
+          </Header>
+        </AppShell.Header>
+        <AppShell.Sidebar width="200px" collapsible="offcanvas">
+          <Sidebar.Header>MyApp</Sidebar.Header>
+          <Sidebar.Nav>
+            <Sidebar.Section label="Menu">
+              <Sidebar.Item active>Home</Sidebar.Item>
+              <Sidebar.Item>Analytics</Sidebar.Item>
+            </Sidebar.Section>
+          </Sidebar.Nav>
+        </AppShell.Sidebar>
+        <AppShell.Main padding="md">Sidebar is full height. Logo is in the sidebar.</AppShell.Main>
+      </AppShell>
+    </div>
+  ),
+};
+
+export const WithAside: Story = {
+  render: () => (
+    <div style={{ height: "360px", overflow: "hidden" }}>
+      <AppShell layout="default">
+        <AppShell.Header>
+          <Header>
+            <Header.Brand>App</Header.Brand>
+          </Header>
+        </AppShell.Header>
+        <AppShell.Sidebar width="180px" collapsible="offcanvas">
+          <Sidebar.Nav>
+            <Sidebar.Section>
+              <Sidebar.Item active>Home</Sidebar.Item>
+            </Sidebar.Section>
+          </Sidebar.Nav>
+        </AppShell.Sidebar>
+        <AppShell.Main padding="md">Content with an aside panel on the right.</AppShell.Main>
+        <AppShell.Aside width="180px">
+          Additional context, filters, or quick actions.
+        </AppShell.Aside>
+      </AppShell>
+    </div>
+  ),
+};
+
+export const FloatingMain: Story = {
+  render: () => (
+    <div style={{ height: "360px", overflow: "hidden" }}>
+      <AppShell layout="sidebar">
+        <AppShell.Header>
+          <Header>
+            <Header.Trigger />
+          </Header>
+        </AppShell.Header>
+        <AppShell.Sidebar width="200px" collapsible="offcanvas" variant="floating">
+          <Sidebar.Header>MyApp</Sidebar.Header>
+          <Sidebar.Nav>
+            <Sidebar.Section label="Menu">
+              <Sidebar.Item active>Home</Sidebar.Item>
+            </Sidebar.Section>
+          </Sidebar.Nav>
+        </AppShell.Sidebar>
+        <AppShell.Main padding="md" variant="floating">
+          Main content has rounded corners and visual separation from the sidebar.
+        </AppShell.Main>
+      </AppShell>
+    </div>
+  ),
+};