316 lines
10 KiB
Markdown
316 lines
10 KiB
Markdown
# Frontend Layout Guidelines
|
|
|
|
Admin pages in this project default to a "single-screen workspace" layout standard. The goal is not to prevent all overflow, but to ensure that under common desktop viewports:
|
|
|
|
- The main page structure is visible within one screen
|
|
- The user can simultaneously see the page header, summary area, and main workspace
|
|
- Overflow content scrolls within its module, rather than stretching the entire page vertically
|
|
|
|
Current recommended reference implementations:
|
|
|
|
- [frontend/src/admin/pages/PlainResourcePages.tsx](/home/ray/dev/linkong/planet/frontend/src/admin/pages/PlainResourcePages.tsx)
|
|
- [frontend/src/admin/pages/DataList.tsx](/home/ray/dev/linkong/planet/frontend/src/admin/pages/DataList.tsx)
|
|
- [frontend/src/index.css](/home/ray/dev/linkong/planet/frontend/src/index.css)
|
|
|
|
## Core Principles
|
|
|
|
### 1. Pages Should Prioritize a Single-Screen Workspace
|
|
|
|
Admin pages default to:
|
|
|
|
- Header: title, description, main actions
|
|
- Main workspace: stats cards, tables, charts, lists, tabs
|
|
|
|
Recommended structure:
|
|
|
|
```tsx
|
|
<AdminLayout>
|
|
<div className="page-shell">
|
|
<div className="page-shell__header">...</div>
|
|
<div className="page-shell__body">...</div>
|
|
</div>
|
|
</AdminLayout>
|
|
```
|
|
|
|
Total page height should be bounded within the `AdminLayout` content area, not allowed to grow naturally downward without limit.
|
|
|
|
### 2. Scrolling Should Happen Inside Modules
|
|
|
|
If tables, logs, long lists, or chart details overflow their space:
|
|
|
|
- Let the card scroll internally
|
|
- Let the table scroll internally
|
|
- Let the tab content area scroll internally
|
|
|
|
Do not rely on full-page scrolling to "solve" the space problem.
|
|
|
|
### 3. The Main Workspace Must Get the Most Space
|
|
|
|
The most important module on a page must be the visual and spatial lead. Typically ensure:
|
|
|
|
- Header always visible
|
|
- Summary area height controlled
|
|
- Main table / chart / analysis area occupies more than 50% of visible height
|
|
|
|
If a page has multiple large modules, priority order is:
|
|
|
|
1. First compress the description and summary areas
|
|
2. Then move secondary modules into tabs or switch views
|
|
3. Only then consider adding more full-page scrolling
|
|
|
|
### 4. Small Screens and High Zoom Must Enter Compact Mode
|
|
|
|
When window height is low, width is narrow, or system zoom is high, actively switch to a compact layout:
|
|
|
|
- Reduce card padding
|
|
- Reduce header and cell spacing
|
|
- Convert summary area to a more compact single-row or horizontal-scroll layout
|
|
- Move secondary modules into tabs, drawers, or collapsed areas
|
|
|
|
Compact mode goal: maintain usability, not just shrink all text and controls.
|
|
|
|
### 5. Overflow Responsibility Must Be Explicit
|
|
|
|
Large content blocks on the page must explicitly define:
|
|
|
|
- Who is responsible for filling remaining height
|
|
- Who is responsible for clipping
|
|
- Who is responsible for scrolling
|
|
|
|
Common requirements:
|
|
|
|
- Parent container chain needs `min-height: 0`
|
|
- Workspace containers typically need `display: flex`
|
|
- The real scroll node must explicitly use `overflow: auto`
|
|
|
|
### 6. Cards Must Not Be Compressed to Unreadable
|
|
|
|
Historical problems have not been "missing scrollbars," but:
|
|
|
|
- Cards compressed by `flex` to only a tiny visible area
|
|
- Text can render but cannot be read completely
|
|
- Content exists but is cut off by `overflow: hidden`
|
|
|
|
Future constraints:
|
|
|
|
- First ensure cards have a readable minimum height
|
|
- If further compression affects readability, switch to internal scrolling
|
|
- Do not compress body text, tables, or description areas into unreadable strips just to "maintain one screen"
|
|
|
|
### 7. Tabs Are Not Inherently Safe Layout Containers
|
|
|
|
Historical regressions with Tabs include:
|
|
|
|
- Hidden tab panes reappearing due to custom `display: flex`
|
|
- All tabs having the same height/overflow rules forced on them
|
|
- Table tabs work, but markdown / help / diagnostics tabs get crushed
|
|
|
|
Constraints:
|
|
|
|
- Each type of content inside `Tabs` must define its own layout strategy
|
|
- Table tab: "fixed height + internal scrolling"
|
|
- Docs/Markdown tab: better as "tab pane self-scrolls + content normal document flow"
|
|
- If overriding component library styles, verify the hidden state still holds
|
|
|
|
### 8. Summary Areas Should Enter Compact Mode First, Not Compress Body
|
|
|
|
Historical experience shows the top summary cards are most often mishandled:
|
|
|
|
- They frequently get forcibly narrowed to "fit everything"
|
|
- Then the body, tables, and AI result areas all lose their main space
|
|
|
|
Unified constraint:
|
|
|
|
- On small screens or high zoom, summary cards should first:
|
|
- Reduce padding
|
|
- Switch to horizontal scrolling
|
|
- Switch to a more compact grid
|
|
- Do not sacrifice the main workspace's visible area first
|
|
|
|
### 9. Long-Document Content Should Prioritize Reading Experience
|
|
|
|
Content like the following cannot directly apply "table workspace" logic:
|
|
|
|
- AI briefs
|
|
- Runtime logs
|
|
- Raw JSON
|
|
- Help text
|
|
- Multi-paragraph descriptive text
|
|
|
|
These areas should prioritize:
|
|
|
|
- Stable title and meta information visibility
|
|
- Body has a clear minimum readable height
|
|
- Body scroll strategy defined separately
|
|
- Support for Markdown tables, dividers, quotes, code blocks
|
|
|
|
### 10. Height Critical Paths Should Use Fewer Wrapper Layers
|
|
|
|
Many scroll problems historically were not in the component itself, but came from an extra wrapper layer:
|
|
|
|
- Height chain broken
|
|
- `min-height: 0` not passed down
|
|
- `overflow` responsibility absorbed
|
|
|
|
Therefore:
|
|
|
|
- For height-critical areas, prefer the most direct DOM structure
|
|
- When using `Space`, extra wrapper `div`, or third-party layout containers, verify they don't change scroll and height semantics
|
|
- If an area shows "content is there but only a sliver is visible," first suspect an intermediate wrapper layer
|
|
|
|
## Historical Pitfalls
|
|
|
|
From Earth, Playground, BGP, DataSources page bugfixes, several high-frequency pitfall types:
|
|
|
|
### 1. Using `overflow: hidden` to Mask Layout Problems
|
|
|
|
Superficially the page looks "clean," but actually causes:
|
|
|
|
- Content getting clipped
|
|
- Tab content reduced to a sliver
|
|
- Panel renders successfully but users can't see it
|
|
|
|
Correct approach:
|
|
|
|
- Let the real content node scroll
|
|
- Don't let upper containers unconditionally clip all child content
|
|
|
|
### 2. Treating All Tabs as the Same Content Type
|
|
|
|
Tables, Markdown, help cards, and log streams have completely different space requirements.
|
|
|
|
Correct approach:
|
|
|
|
- Table: fixed workspace + internal scrolling
|
|
- Document: normal flow content + pane-level scrolling
|
|
- Side description: content-driven height, not forced to fill
|
|
|
|
### 3. Only Doing Visual Shrinking, Not Space Reallocation
|
|
|
|
This causes:
|
|
|
|
- Card text truncated
|
|
- Table shows only 1-2 rows
|
|
- Buttons and filters crammed together
|
|
|
|
Correct approach:
|
|
|
|
- Compact mode prioritizes re-layout
|
|
- Summary area horizontal scrolling
|
|
- Collapse / hide secondary modules
|
|
|
|
### 4. Incomplete Parent Container Height Chain
|
|
|
|
This is the most common cause of internal scrolling failing.
|
|
|
|
Inspection order:
|
|
|
|
1. Does the outer layer actually have a determined height?
|
|
2. Does the flex parent have `min-height: 0`?
|
|
3. Does the real scroll node explicitly use `overflow: auto`?
|
|
4. Have intermediate wrapper layers silently changed layout semantics?
|
|
|
|
The current Admin and Docs root shells rely on the `html` / `body` / `#root`
|
|
`height: 100%` chain. Do not reintroduce exact `100vh` / `100vw` sizing on
|
|
these embedded workspace shells; modals, overlays, and narrow-screen safety
|
|
boundaries may still use `calc(100vh - ...)` as a maximum-size constraint.
|
|
|
|
### 5. UI State and Display State Out of Sync
|
|
|
|
Repeated in Earth-related changes:
|
|
|
|
- Layer hidden, but hover/lock still active
|
|
- Tooltip still showing stale object
|
|
- Legend not switching with the state
|
|
|
|
These constraints also apply to admin pages:
|
|
|
|
- Hidden, unmounted, or switched-out content should not retain active interaction state
|
|
|
|
## Recommended Implementation Patterns
|
|
|
|
### Page Shell
|
|
|
|
Reuse existing common structures in the project:
|
|
|
|
- `.dashboard-content-inner`
|
|
- `.page-shell`
|
|
- `.page-shell__header`
|
|
- `.page-shell__body`
|
|
- `.table-scroll-region`
|
|
|
|
Do not invent a completely different height and scroll semantics for each page.
|
|
|
|
### Table Workspace
|
|
|
|
Recommended pattern:
|
|
|
|
```tsx
|
|
<Card>
|
|
<div className="table-scroll-region" ref={tableRegionRef}>
|
|
<Table
|
|
pagination={false}
|
|
scroll={{ x: 1200, y: tableHeight }}
|
|
/>
|
|
</div>
|
|
</Card>
|
|
```
|
|
|
|
Requirements:
|
|
|
|
- Tables should scroll inside their card
|
|
- `scroll.y` should come from actual available height calculation, not a completely static magic number
|
|
- Parent container chain must ensure header, body, content overflow all close inside the table
|
|
|
|
### Multi-Module Pages
|
|
|
|
If a page has:
|
|
|
|
- Summary cards
|
|
- Table
|
|
- Anomaly details
|
|
- Recent events
|
|
|
|
Do not simply stack all modules vertically. Prefer:
|
|
|
|
- Top summary + single main workspace at bottom
|
|
- Tab-switch multiple secondary data views
|
|
- Left-right split with each column scrolling independently
|
|
|
|
## Discouraged Patterns
|
|
|
|
The following patterns are considered non-compliant with this project's page standard:
|
|
|
|
- Relying on full-page vertical scrolling to display the main workspace
|
|
- Stacking 3-4 large cards vertically on one page, each wanting to display fully
|
|
- Table without internal scrolling, causing only 1-2 rows visible after zoom
|
|
- Parent container missing `min-height: 0`, causing internal scrolling to fail
|
|
- Only doing visual shrinking without addressing real space allocation
|
|
|
|
## Page Acceptance Checklist
|
|
|
|
Before submitting, check at minimum:
|
|
|
|
- Can page header, summary area, and main workspace appear simultaneously?
|
|
- Does the main workspace get the most height on the page?
|
|
- When table or detail overflows, does the scrollbar appear inside the module?
|
|
- Is the card compressed to the point where text doesn't display completely? If so, has it switched to internal scrolling?
|
|
- Is it still usable at browser zoom `125%` / `150%`?
|
|
- In a low-height window, is there still a reasonable number of visible content rows?
|
|
- Are Tabs, Card, Table still operable when overflowing?
|
|
- Do non-table tabs (Markdown, help text, logs) have their own independent and reasonable scroll strategy?
|
|
|
|
## Implementation Order
|
|
|
|
When adding or refactoring admin pages, design in this order:
|
|
|
|
1. Define the main workspace first
|
|
2. Determine which modules must always be visible
|
|
3. Then handle styling and visual hierarchy
|
|
|
|
Simply put:
|
|
|
|
- First ensure correct space allocation
|
|
- Then handle scroll boundaries
|
|
- Finally handle aesthetics
|