Skip to content

Commit 583eafc

Browse files
ericyangpanclaude
ericyangpan
and
claude
committed
feat(layouts): add universal PageLayout component
Add PageLayout as the single layout component used by all pages. This simplifies the architecture by removing nested template hierarchy in favor of direct component composition. The new PageLayout provides: - Optional JsonLd schema injection - Header and Footer wrapping - Simple composition model where pages import and arrange components directly Also added comprehensive documentation in docs/COMPONENT-RELATIONSHIP-DIAGRAM.md explaining the new architecture and component relationships. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
1 parent 912acc0 commit 583eafc

File tree

2 files changed

+296
-0
lines changed

2 files changed

+296
-0
lines changed

‎docs/COMPONENT-RELATIONSHIP-DIAGRAM.md‎

Lines changed: 248 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,248 @@
1+
# Component & Layout Relationship Diagram
2+
3+
This document outlines the simplified structure and relationships between layouts and components in the AI Coding Stack project.
4+
5+
## Design Principles
6+
7+
1. **Minimal Nesting** - Only 2 layouts total: RootLayout (app/) and PageLayout
8+
2. **Inline Over Abstraction** - Pages compose components directly instead of using specialized layouts
9+
3. **DRY** - Components are reused across pages, layouts are not nested
10+
11+
---
12+
13+
## Structure
14+
15+
```
16+
src/
17+
├── app/[locale]/layout.tsx [RootLayout - Next.js root layout]
18+
│
19+
├── layouts/
20+
│ └── PageLayout.tsx [Only layout - Header + Footer + optional schema]
21+
│
22+
└── components/
23+
├── Header.tsx [Site header with navigation]
24+
├── Footer.tsx [Site footer]
25+
├── JsonLd.tsx [Schema.org structured data]
26+
├── ThemeProvider.tsx [Theme context provider]
27+
├── ClientLayout.tsx [Client-side wrapper for interactivity]
28+
│
29+
├── product/ [Product-related components]
30+
│ ├── ProductHero.tsx [Product header info]
31+
│ ├── ProductPricing.tsx [Pricing section]
32+
│ ├── ProductLinks.tsx [Resource/community links]
33+
│ ├── ProductCommands.tsx[Install/launch commands]
34+
│ ├── RelatedProducts.tsx[Related products grid]
35+
│ ├── LinkCard.tsx [Link card component]
36+
│ └── GitHubStarHistory.tsx [GitHub stars chart]
37+
│
38+
├── navigation/ [Navigation components]
39+
│ ├── BackToNavigation.tsx ["Back to" link]
40+
│ ├── Breadcrumb.tsx [Breadcrumb navigation]
41+
│ ├── StackMegaMenu.tsx [AI Coding Stack mega menu]
42+
│ ├── RankingMegaMenu.tsx[Ranking mega menu]
43+
│ └── StackTabs.tsx [Stack category tabs]
44+
│
45+
├── controls/ [UI controls]
46+
│ ├── CopyButton.tsx
47+
│ ├── FilterSortBar.tsx
48+
│ ├── LanguageSwitcher.tsx
49+
│ ├── SearchDialog.tsx
50+
│ ├── SearchInput.tsx
51+
│ └── ThemeSwitcher.tsx
52+
│
53+
├── sidebar/ [Sidebar components]
54+
│ ├── Sidebar.tsx [Main sidebar]
55+
│ └── DocsSidebar.tsx [Documentation sidebar]
56+
│
57+
├── og/ [OpenGraph images]
58+
│ └── OGImageTemplate.tsx
59+
│
60+
└── [other components]
61+
├── ComparisonTable.tsx [Comparison data table]
62+
├── CollectionScrollbar.tsx [Horizontal scroll for collections]
63+
├── CollectionSection.tsx [Collection section wrapper]
64+
├── CommunityLinks.tsx [Community links (Twitter, Discord, etc.)]
65+
├── MarkdownContent.tsx [Markdown content renderer]
66+
├── MDXComponents.tsx [MDX component mappings]
67+
├── ModelBenchmarks.tsx [Model benchmark scores]
68+
├── ModelSpecifications.tsx [Model technical specs]
69+
├── PageHeader.tsx [Page header component]
70+
├── PlatformIcons.tsx [Platform icon display]
71+
├── PlatformLinks.tsx [Platform links (HuggingFace, etc.)]
72+
├── VendorModels.tsx [Vendor's models grid]
73+
├── VendorProducts.tsx [Vendor's products grid]
74+
└── VerifiedBadge.tsx [Verified checkmark badge]
75+
```
76+
77+
---
78+
79+
## Layout Structure
80+
81+
```
82+
┌─────────────────────────────────────────────────────────────────────────────┐
83+
│ LAYOUT STRUCTURE │
84+
├─────────────────────────────────────────────────────────────────────────────┤
85+
│ │
86+
│ RootLayout (Next.js app/[locale]/layout.tsx) │
87+
│ ├── Provides: i18n, theme, basic HTML structure │
88+
│ └── NOT counted as a "layout" for this project │
89+
│ │
90+
│ PageLayout (src/layouts/PageLayout.tsx) │
91+
│ ├── Provides: JsonLd (optional), Header, Footer │
92+
│ └── Used by: ALL pages │
93+
│ │
94+
│ All pages use PageLayout and compose their own content: │
95+
│ │
96+
│ <PageLayout schema={schema}> │
97+
│ <Breadcrumb items={...} /> │
98+
│ <ProductHero {...props} /> │
99+
│ <OtherSection {...props} /> │
100+
│ <BackToNavigation href="/..." title="..." /> │
101+
│ </PageLayout> │
102+
│ │
103+
└─────────────────────────────────────────────────────────────────────────────┘
104+
```
105+
106+
---
107+
108+
## Page Usage Examples
109+
110+
### IDE/CLI/Extension Detail Pages
111+
```tsx
112+
<PageLayout schema={schema}>
113+
<Breadcrumb items={...} />
114+
<ProductHero {...product} />
115+
<RelatedProducts products={...} />
116+
<ProductPricing pricing={...} />
117+
<ProductLinks links={...} />
118+
<ProductCommands commands={...} />
119+
<BackToNavigation href="/ides" title="All IDEs" />
120+
</PageLayout>
121+
```
122+
123+
### Model Detail Pages
124+
```tsx
125+
<PageLayout schema={schema}>
126+
<Breadcrumb items={...} />
127+
<ProductHero {...model} />
128+
<PlatformLinks urls={...} />
129+
<ModelSpecifications model={...} />
130+
<ModelBenchmarks benchmarks={...} />
131+
<BackToNavigation href="/models" title="All Models" />
132+
</PageLayout>
133+
```
134+
135+
### Vendor/Provider Detail Pages
136+
```tsx
137+
<PageLayout schema={schema}>
138+
<Breadcrumb items={...} />
139+
<ProductHero {...organization} />
140+
<PlatformLinks urls={...} /> <!-- Providers -->
141+
<CommunityLinks urls={...} /> <!-- Vendors & Providers -->
142+
<VendorProducts products={...} /> <!-- Vendors -->
143+
<VendorModels models={...} /> <!-- Vendors -->
144+
<BackToNavigation href="/..." title="..." />
145+
</PageLayout>
146+
```
147+
148+
---
149+
150+
## Component Dependencies
151+
152+
```
153+
┌─────────────────────────────────────────────────────────────────────────────┐
154+
│ COMPONENT DEPENDENCIES │
155+
├─────────────────────────────────────────────────────────────────────────────┤
156+
│ │
157+
│ PageLayout │
158+
│ ├── JsonLd │
159+
│ ├── Header │
160+
│ │ ├── SearchDialog │
161+
│ │ ├── StackMegaMenu │
162+
│ │ ├── RankingMegaMenu │
163+
│ │ └── i18n Link │
164+
│ └── Footer │
165+
│ ├── LanguageSwitcher │
166+
│ └── ThemeSwitcher │
167+
│ │
168+
│ Pages compose components directly: │
169+
│ ├── Breadcrumb │
170+
│ ├── ProductHero │
171+
│ │ ├── VerifiedBadge │
172+
│ │ └── PlatformIcons │
173+
│ ├── RelatedProducts → LinkCard │
174+
│ ├── ProductPricing │
175+
│ ├── ProductLinks │
176+
│ ├── ProductCommands → CopyButton │
177+
│ ├── PlatformLinks → PlatformIcons │
178+
│ ├── CommunityLinks → PlatformIcons │
179+
│ ├── ModelSpecifications │
180+
│ ├── ModelBenchmarks │
181+
│ ├── VendorProducts → LinkCard │
182+
│ ├── VendorModels → LinkCard │
183+
│ ├── BackToNavigation │
184+
│ ├── ComparisonTable │
185+
│ ├── CollectionScrollbar │
186+
│ ├── CollectionSection │
187+
│ ├── MarkdownContent │
188+
│ ├── MDXComponents │
189+
│ ├── PageHeader │
190+
│ ├── Sidebar │
191+
│ └── DocsSidebar │
192+
│ │
193+
└─────────────────────────────────────────────────────────────────────────────┘
194+
```
195+
196+
---
197+
198+
## Page → Layout/Component Matrix
199+
200+
| Page Type | Layout | Components Used |
201+
|-----------|--------|-----------------|
202+
| IDE Detail | PageLayout | Breadcrumb, ProductHero, RelatedProducts, ProductPricing, ProductLinks, ProductCommands, BackToNavigation |
203+
| CLI Detail | PageLayout | Breadcrumb, ProductHero, RelatedProducts, ProductPricing, ProductLinks, ProductCommands, BackToNavigation |
204+
| Extension Detail | PageLayout | Breadcrumb, ProductHero, RelatedProducts, ProductPricing, ProductLinks, ProductCommands, BackToNavigation |
205+
| Model Detail | PageLayout | Breadcrumb, ProductHero, PlatformLinks, ModelSpecifications, ModelBenchmarks, BackToNavigation |
206+
| Vendor Detail | PageLayout | Breadcrumb, ProductHero, CommunityLinks, VendorProducts, VendorModels, BackToNavigation |
207+
| Provider Detail | PageLayout | Breadcrumb, ProductHero, PlatformLinks, CommunityLinks, BackToNavigation |
208+
| Homepage/Listings | PageLayout | Custom components |
209+
| Article/Docs | PageLayout | MarkdownContent, etc. |
210+
211+
---
212+
213+
## Key Design Patterns
214+
215+
### 1. Single Layout Pattern
216+
- Only 1 layout: `PageLayout`
217+
- Pages compose components directly
218+
- No layout inheritance or nesting
219+
220+
### 2. Component Composition
221+
- Each page imports the components it needs directly
222+
- Components are reusable (ProductHero, PlatformLinks, etc.)
223+
- No "smart layouts" that know about page specifics
224+
- Direct imports from component paths (no barrel exports)
225+
226+
---
227+
228+
## Migration Notes
229+
230+
### Before (nested layouts):
231+
```
232+
EntityDetailLayout (base)
233+
└── VendorEntityDetailLayout (extends base, adds ProductHero)
234+
└── ProductDetailLayout (adds product sections)
235+
```
236+
237+
### After (flat):
238+
```
239+
PageLayout (Header + Footer)
240+
└── Page directly composes components
241+
```
242+
243+
### Benefits:
244+
1. **No layout nesting** - Clear data flow
245+
2. **Explicit composition** - Page code shows exactly what components are used
246+
3. **Easier to modify** - Change one page without affecting others
247+
4. **Better testability** - Components can be tested independently
248+
5. **Simpler mental model** - Only 1 layout to understand

‎src/layouts/PageLayout.tsx‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
import type { ReactNode } from 'react'
2+
import Footer from '@/components/Footer'
3+
import Header from '@/components/Header'
4+
import { JsonLd } from '@/components/JsonLd'
5+
import type { AnySchema } from '@/lib/metadata/schemas'
6+
7+
export interface PageLayoutProps {
8+
children: ReactNode
9+
schema?: AnySchema
10+
}
11+
12+
/**
13+
* PageLayout - Universal page layout with Header and Footer
14+
*
15+
* This is the only layout component in the application.
16+
* All pages use this layout and compose their own content structure.
17+
*
18+
* @example Basic usage
19+
* ```tsx
20+
* <PageLayout>
21+
* <Breadcrumb items={...} />
22+
* <ProductHero {...props} />
23+
* <BackToNavigation href="/ides" title="All IDEs" />
24+
* </PageLayout>
25+
* ```
26+
*
27+
* @example With schema
28+
* ```tsx
29+
* <PageLayout schema={softwareApplicationSchema}>
30+
* {content}
31+
* </PageLayout>
32+
* ```
33+
*/
34+
export function PageLayout({ children, schema }: PageLayoutProps) {
35+
return (
36+
<>
37+
{/* Schema.org structured data (optional) */}
38+
{schema && <JsonLd data={schema} />}
39+
40+
<Header />
41+
42+
{/* Page content - composed by the page itself */}
43+
{children}
44+
45+
<Footer />
46+
</>
47+
)
48+
}

0 commit comments

Comments
 (0)