feat(web): C2 shell_css modes and page layout presets

Split injected shell CSS into vars/layout/widgets with full|minimal|off, add stacked/bare/rail layouts, and stop forcing has-sidebar when authors opt out.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
cflmyandCursor committed 2026-09-04 12:48:50 +08:00
1 parent b10a84466b
commit 155183eb30
10 files changed
+360 -43

No files matched your search

+1
View File
@@ -10,6 +10,7 @@
- **`agent.step` / `plan` 写回**:参数名 `writeback` 遮蔽 `lib/writeback` import,导致 `writeback=True` 时 `method receiver must be an object map`;改为 `host_writeback_record`。金样 `agent-writeback-shadow`。
- **`ext/web` C0**:`admin=False` 不再挂载/保留 `/admin*`;可配 `admin_prefix` / `login_redirect` / `logout_redirect`;金样 `web-c0-admin-prefix`。
- **`ext/web` C1**:门禁段边界匹配(不再误伤 `/admin-publish`);`gate` 支持 `match` / `on_deny` / `exclude`;`auth` 默认 `on_deny=redirect` + `login_path`;金样 `web-c1-gates`。
- **`ext/web` C2**:`shell_css=full|minimal|off`;`layout=sidebar|stacked|bare|rail`;full 壳含小屏单列 media;金样 `web-c2-shell-layout`。
### Changed
- `build_step_context`:call site 提前到 task 之后;开场白强调 code-as-documentation。
@@ -67,6 +67,6 @@
---
## 6. 过渡期 workaround
## 6. 过渡期 → 已落地
继续用更高特异性 + `!important`;实现后主题应删除这类补丁,并在回归里断言壳字符串不出现。
**C2 已落地(2026-09):** `shell_css=full|minimal|off`;页面/应用可设;`full` 含 `@media (max-width:720px)` 单列。金样 `tests/ext/web-c2-shell-layout.mq.md`。
@@ -62,6 +62,6 @@
---
## 6. 过渡期 workaround
## 6. 过渡期 → 已落地
`shell_css=off`(实现后)或强力覆盖 `body.has-sidebar`;条件导航暂用 CSS `display` + 双份链接,或轻量 `theme.js`。
**C2 已落地(2026-09):** `layout=sidebar|stacked|bare|rail`;有 side 时 `stacked`/`bare` 不再强制 `has-sidebar`。金样同上。
+1 -1
View File
@@ -2,7 +2,7 @@
| | |
|---|---|
| 状态 | **C0–C1 done · C2–C4 planned** |
| 状态 | **C0–C2 done · C3–C4 planned** |
| 日期 | 2026-09-04 |
| 问题盘点 | [../../research/ext-web-customization-limits.md](../../research/ext-web-customization-limits.md) |
| 相关 | [../ext-web.md](../ext-web.md) · [../ext-web-net.md](../ext-web-net.md) · [../../roadmap/ext-web.md](../../roadmap/ext-web.md) |
+1 -1
View File
@@ -43,7 +43,7 @@
|------|------|------|
| **C0** | `admin` 关则不占路径;`admin_prefix` / 登录回跳可配 | **done** |
| **C1** | gate 匹配与未登录策略一致;段边界默认 admin gate | **done** |
| **C2** | `shell_css` + `layout` 松绑 | **planned** |
| **C2** | `shell_css` + `layout` 松绑 | **done** |
| **C3** | 样式 strict / 脚本 defer·version | **planned** |
| **C4** | 壳预设收口与条件导航(后续) | **planned** |
+23 -3
View File
@@ -179,9 +179,27 @@ Build a `render_list` effect: `{ render_list: { sel: { tag, items } } }`.
# page
+ `title`="Marqdo Web"
+ `intro`=""
+ `shell_css`=None
+ `layout`=None
> ensure_plugin
**> web_page_new title=`title` intro=`intro`**
**> web_page_new title=`title` intro=`intro` shell_css=`shell_css` layout=`layout`**
## shell_css
+ `mode`=full
Framework shell CSS mode for this page: `full` (default), `minimal` (vars only), or `off`/`none`.
*`out` = > table.put in=`self` at="shell_css" value=mode*
**out**
## layout
+ `layout`=sidebar
Page chrome layout: `sidebar` (default when a side slot exists), `stacked` (single column; no `has-sidebar` grid), `bare` (main only), or `rail`.
*`out` = > table.put in=`self` at="layout" value=layout*
**out**
## compose_components
+ `components`
@@ -568,11 +586,13 @@ Field table + rules table; submit writes through `# db`.
+ `admin_prefix`=/admin
+ `login_redirect`=None
+ `logout_redirect`=None
+ `shell_css`=None
+ `layout`=None
Construct an app. `admin=True` mounts the built-in CRUD UI under `admin_prefix` (default `/admin`). When `admin=False`, that prefix is **not** reserved — you may `route` your own pages there. Optional `login_redirect` / `logout_redirect` override post-auth landing (defaults: `{admin_prefix}` and `{admin_prefix}/login`).
Construct an app. `admin=True` mounts the built-in CRUD UI under `admin_prefix` (default `/admin`). When `admin=False`, that prefix is **not** reserved — you may `route` your own pages there. Optional `login_redirect` / `logout_redirect` override post-auth landing. Optional `shell_css` / `layout` become defaults for pages that do not set their own (see `page.shell_css` / `page.layout`).
> ensure_plugin
**> web_app_new page=`page` db=`db` admin=`admin` host=`host` port=`port` admin_prefix=`admin_prefix` login_redirect=`login_redirect` logout_redirect=`logout_redirect`**
**> web_app_new page=`page` db=`db` admin=`admin` host=`host` port=`port` admin_prefix=`admin_prefix` login_redirect=`login_redirect` logout_redirect=`logout_redirect` shell_css=`shell_css` layout=`layout`**
## route
+ `path`
+23 -3
View File
@@ -174,9 +174,27 @@ import table:lib/table.mq.md
# 页面
+ `标题`="站点"
+ `引言`=""
+ `壳样式`=None
+ `布局`=None
> 确保插件
**> web_page_new title=`标题` intro=`引言`**
**> web_page_new title=`标题` intro=`引言` shell_css=`壳样式` layout=`布局`**
## 壳样式
+ `模式`=full
框架壳 CSS:`full`(默认)/ `minimal`(仅变量)/ `off`。
*`out` = > table.put in=`自` at="shell_css" value=模式*
**out**
## 布局
+ `布局`=sidebar
页面壳:`sidebar`(有侧栏时默认双列)/ `stacked`(单列、不加 has-sidebar)/ `bare`(仅 main)/ `rail`。
*`out` = > table.put in=`自` at="layout" value=布局*
**out**
## 组件装配
+ `组件`
@@ -548,11 +566,13 @@ SEO / OpenGraph 元数据表(`|键|值|`)。如 `title`、`description`、`c
+ `后台前缀`=/admin
+ `登录回跳`=None
+ `登出回跳`=None
+ `壳样式`=None
+ `布局`=None
构造应用。`后台=真` 时在 `后台前缀`(默认 `/admin`)挂载内置 CRUD。`后台=假` 时该前缀**不再保留**,可自行 `路由` 到 `/admin…`。可选 `登录回跳` / `登出回跳`(默认分别为前缀本身与 `{前缀}/login`)。
构造应用。`后台=真` 时在 `后台前缀`(默认 `/admin`)挂载内置 CRUD。`后台=假` 时该前缀**不再保留**,可自行 `路由` 到 `/admin…`。可选 `登录回跳` / `登出回跳`。可选 `壳样式` / `布局` 作为未自设页面的默认(见 `页面.壳样式` / `页面.布局`)。
> 确保插件
**> web_app_new page=`页面` db=`数据库` admin=`后台` host=`主机` port=`端口` admin_prefix=`后台前缀` login_redirect=`登录回跳` logout_redirect=`登出回跳`**
**> web_app_new page=`页面` db=`数据库` admin=`后台` host=`主机` port=`端口` admin_prefix=`后台前缀` login_redirect=`登录回跳` logout_redirect=`登出回跳` shell_css=`壳样式` layout=`布局`**
## 路由
+ `路径`
+58 -4
View File
@@ -273,10 +273,17 @@ macro_rules! web_ffi {
web_ffi!(web_page_new, |args: &Value| {
let title = arg_str_opt(args, "title").unwrap_or("Marqdo Web");
let intro = arg_str_opt(args, "intro").unwrap_or("");
Ok(json!({
let mut out = json!({
"title": title,
"intro": intro,
}))
});
if let Some(s) = arg_str_opt(args, "shell_css").or_else(|| arg_str_opt(args, "壳样式")) {
out.as_object_mut().unwrap().insert("shell_css".into(), json!(s));
}
if let Some(s) = arg_str_opt(args, "layout").or_else(|| arg_str_opt(args, "布局")) {
out.as_object_mut().unwrap().insert("layout".into(), json!(s));
}
Ok(out)
});
web_ffi!(web_compose_components, |args: &Value| {
@@ -1053,6 +1060,12 @@ web_ffi!(web_app_new, |args: &Value| {
if let Some(v) = logout_redirect {
out.as_object_mut().unwrap().insert("logout_redirect".into(), json!(v));
}
if let Some(s) = arg_str_opt(args, "shell_css").or_else(|| arg_str_opt(args, "壳样式")) {
out.as_object_mut().unwrap().insert("shell_css".into(), json!(s));
}
if let Some(s) = arg_str_opt(args, "layout").or_else(|| arg_str_opt(args, "布局")) {
out.as_object_mut().unwrap().insert("layout".into(), json!(s));
}
Ok(out)
});
@@ -1628,6 +1641,33 @@ web_ffi!(web_db_table_info, |args: &Value| {
Ok(json!({ "columns": arr }))
});
fn stamp_page_shell(page: &mut Value, shell_css: Option<&str>, layout: Option<&str>) {
let Some(obj) = page.as_object_mut() else {
return;
};
if let Some(s) = shell_css {
let empty = obj
.get("shell_css")
.and_then(|v| v.as_str())
.unwrap_or("")
.is_empty();
if empty {
obj.insert("shell_css".into(), json!(s));
}
}
if let Some(s) = layout {
let empty = obj
.get("layout")
.and_then(|v| v.as_str())
.unwrap_or("")
.is_empty();
if empty {
obj.insert("layout".into(), json!(s));
}
}
}
web_ffi!(web_listen, |args: &Value| {
use std::collections::HashMap;
use std::path::PathBuf;
@@ -2009,6 +2049,20 @@ web_ffi!(web_listen, |args: &Value| {
.filter(|s| !s.is_empty())
.map(|s| s.to_string())
.unwrap_or_else(|| login_path.clone());
let app_shell = admin_cfg_app
.get("shell_css")
.or_else(|| admin_cfg_app.get("壳样式"))
.and_then(|v| v.as_str());
let app_layout = admin_cfg_app
.get("layout")
.or_else(|| admin_cfg_app.get("布局"))
.and_then(|v| v.as_str());
let mut page = page;
let mut routes = routes;
stamp_page_shell(&mut page, app_shell, app_layout);
for (_k, p) in routes.iter_mut() {
stamp_page_shell(p, app_shell, app_layout);
}
http::listen(
&page,
db_url.as_deref(),
@@ -2076,7 +2130,7 @@ pub unsafe extern "C" fn marqdo_plugin_init(host: *const MarqdoHostApi) -> c_int
}
let regs = [
("web_page_new", "title,intro", web_page_new as PluginFn),
("web_page_new", "title,intro,shell_css,layout", web_page_new as PluginFn),
(
"web_compose_components",
"page,components",
@@ -2248,7 +2302,7 @@ pub unsafe extern "C" fn marqdo_plugin_init(host: *const MarqdoHostApi) -> c_int
("web_db_list_tables", "url", web_db_list_tables as PluginFn),
(
"web_app_new",
"page,db,admin,host,port,admin_prefix,login_redirect,logout_redirect",
"page,db,admin,host,port,admin_prefix,login_redirect,logout_redirect,shell_css,layout",
web_app_new as PluginFn,
),
("web_app_route", "app,path,page", web_app_route as PluginFn),
+189 -27
View File
@@ -307,19 +307,35 @@ fn slot_class(args: &Value, slot: &str, base: &str) -> String {
}
}
const SHELL_CSS: &str = r#"
const SHELL_VARS: &str = r#"
:root { --ink:#1c1917; --muted:#57534e; --paper:#fafaf9; --line:#e7e5e4; --accent:#0f766e; }
body { margin:0; font-family: "IBM Plex Sans", "Noto Sans SC", sans-serif; background:var(--paper); color:var(--ink); display:grid; min-height:100vh; grid-template-rows:auto 1fr auto; }
body { margin:0; font-family: "IBM Plex Sans", "Noto Sans SC", sans-serif; background:var(--paper); color:var(--ink); }
a { color:var(--ink); text-decoration:none; }
a:hover { color:var(--accent); }
"#;
const SHELL_LAYOUT: &str = r#"
body { display:grid; min-height:100vh; grid-template-rows:auto 1fr auto; }
body.has-sidebar { grid-template-columns:14rem 1fr; grid-template-areas:"top top" "side main" "foot foot"; }
body.no-sidebar { grid-template-areas:"top" "main" "foot"; }
@media (max-width:720px) {
body.has-sidebar { grid-template-columns:1fr; grid-template-areas:"top" "main" "foot" "side"; }
body.has-sidebar aside.side { border-right:0; border-top:1px solid var(--line); }
}
body.layout-stacked { display:flex; flex-direction:column; min-height:100vh; }
body.layout-stacked header.topnav, body.layout-stacked aside.side, body.layout-stacked main.main, body.layout-stacked footer.foot { width:100%; }
body.layout-stacked aside.side { border-right:0; border-bottom:1px solid var(--line); }
body.layout-bare { display:block; min-height:100vh; }
body.layout-bare main.main { padding:1.5rem 1.25rem 2rem; }
header.topnav { grid-area:top; border-bottom:1px solid var(--line); padding:.85rem 1.25rem; background:#fff; }
aside.side { grid-area:side; border-right:1px solid var(--line); padding:1.25rem 1rem; background:#f5f5f4; }
main.main { grid-area:main; padding:1.5rem 1.25rem 2rem; }
footer.foot { grid-area:foot; border-top:1px solid var(--line); padding:.85rem 1.25rem; color:var(--muted); background:#fff; }
ul.nav, ul.side-nav, ul.foot-nav { list-style:none; margin:0; padding:0; display:flex; flex-wrap:wrap; gap:.35rem 1rem; }
ul.side-nav { flex-direction:column; }
a { color:var(--ink); text-decoration:none; }
a:hover { color:var(--accent); }
"#;
const SHELL_WIDGETS: &str = r#"
.content.cards { display:grid; gap:1rem; margin-top:1.25rem; grid-template-columns:repeat(auto-fill,minmax(16rem,1fr)); }
.content.cards article { background:#fff; border:1px solid var(--line); border-radius:6px; padding:1rem; }
.main-intro h1 { margin:0 0 .75rem; font-size:2rem; }
@@ -349,6 +365,52 @@ a:hover { color:var(--accent); }
.pagination .page-status { color:var(--muted); }
"#;
fn normalize_shell_css(raw: &str) -> &'static str {
match raw.trim().to_ascii_lowercase().as_str() {
"" | "full" | "default" => "full",
"minimal" | "min" | "vars" => "minimal",
"off" | "none" | "false" | "0" => "off",
_ => "full",
}
}
fn shell_css_for(mode: &str) -> String {
match normalize_shell_css(mode) {
"off" => String::new(),
"minimal" => SHELL_VARS.to_string(),
_ => format!("{SHELL_VARS}{SHELL_LAYOUT}{SHELL_WIDGETS}"),
}
}
fn normalize_layout(raw: &str) -> String {
match raw.trim().to_ascii_lowercase().as_str() {
"" | "auto" | "default" => String::new(),
"sidebar" | "side" => "sidebar".into(),
"stacked" | "stack" | "column" => "stacked".into(),
"bare" | "main" | "none" => "bare".into(),
"rail" => "rail".into(),
other => other.to_string(),
}
}
fn resolve_shell_css(args: &Value) -> String {
let raw = args
.get("shell_css")
.or_else(|| args.get("壳样式"))
.and_then(|v| v.as_str())
.unwrap_or("full");
shell_css_for(raw)
}
fn resolve_layout(args: &Value) -> String {
let raw = args
.get("layout")
.or_else(|| args.get("布局"))
.and_then(|v| v.as_str())
.unwrap_or("");
normalize_layout(raw)
}
fn head_html(args: &Value, default_title: &str) -> String {
let meta = args.get("meta").and_then(|v| v.as_object());
let page_title = meta
@@ -473,6 +535,8 @@ pub fn render_page_ex(
.get("styles_css")
.and_then(|v| v.as_str())
.unwrap_or("");
let shell = resolve_shell_css(args);
let layout = resolve_layout(args);
let parts = args
.get("parts")
.and_then(|v| v.as_object())
@@ -485,10 +549,32 @@ pub fn render_page_ex(
let (intro, items, total) = resolve_main(args, db_url);
let has_side = args.get("sidebar").is_some() || !side.is_empty();
let body_class = if has_side {
"has-sidebar"
} else {
"no-sidebar"
let bare = layout == "bare";
let body_class = match layout.as_str() {
"bare" => "layout-bare".to_string(),
"stacked" => "layout-stacked".to_string(),
"rail" => {
if has_side {
"has-rail has-sidebar".into()
} else {
"has-rail no-sidebar".into()
}
}
"sidebar" => {
if has_side {
"has-sidebar".into()
} else {
"no-sidebar".into()
}
}
"" => {
if has_side {
"has-sidebar".into()
} else {
"no-sidebar".into()
}
}
other => other.to_string(),
};
let mut main_html = String::new();
@@ -532,39 +618,61 @@ pub fn render_page_ex(
}
}
let style_block = if shell.is_empty() && extra.is_empty() {
String::new()
} else {
format!("<style>{shell}{extra}</style>")
};
let show_chrome = !bare;
let side_html = if show_chrome && has_side {
format!(
"<aside class=\"{}\"{}><span class=\"side-label\">侧栏</span>{}</aside>",
slot_class(args, "sidebar", "side"),
slot_attrs("sidebar", &parts, args),
render_ul(&side, "side-nav")
)
} else {
String::new()
};
let header_html = if show_chrome {
format!(
"<header class=\"{}\"{}>{}</header>",
slot_class(args, "nav", "topnav"),
slot_attrs("nav", &parts, args),
render_ul(&nav, "nav")
)
} else {
String::new()
};
let footer_html = if show_chrome {
format!(
"<footer class=\"{}\"{}>{}</footer>",
slot_class(args, "footer", "foot"),
slot_attrs("footer", &parts, args),
render_ul(&foot, "foot-nav")
)
} else {
String::new()
};
format!(
r#"<!DOCTYPE html>
<html lang="zh-CN"><head>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
{head}
<style>{SHELL_CSS}{extra}</style>
{style_block}
</head>
<body class="{body_class}">
<header class="{nav_class}"{nav_attrs}>{nav_ul}</header>
{header_html}
{side_html}
<main class="{main_class}"{main_attrs}>{main_html}</main>
<footer class="{foot_class}"{foot_attrs}>{foot_ul}</footer>
{footer_html}
</body></html>"#,
head = head_html(args, title),
nav_class = slot_class(args, "nav", "topnav"),
nav_attrs = slot_attrs("nav", &parts, args),
nav_ul = render_ul(&nav, "nav"),
side_html = if has_side {
format!(
"<aside class=\"{}\"{}><span class=\"side-label\">侧栏</span>{}</aside>",
slot_class(args, "sidebar", "side"),
slot_attrs("sidebar", &parts, args),
render_ul(&side, "side-nav")
)
} else {
String::new()
},
main_class = slot_class(args, "main", "main"),
main_attrs = slot_attrs("main", &parts, args),
foot_class = slot_class(args, "footer", "foot"),
foot_attrs = slot_attrs("footer", &parts, args),
foot_ul = render_ul(&foot, "foot-nav"),
)
}
@@ -704,3 +812,57 @@ fn render_article(it: &Map<String, Value>) -> String {
s.push_str("</article>");
s
}
#[cfg(test)]
mod shell_tests {
use super::*;
use serde_json::json;
#[test]
fn shell_off_omits_sidebar_grid() {
let page = json!({
"title": "t",
"shell_css": "off",
"layout": "stacked",
"sidebar": [{"label": "A", "href": "/a"}],
});
let html = render_page(&page, None, None);
assert!(html.contains("layout-stacked"));
assert!(!html.contains("has-sidebar"));
assert!(!html.contains("grid-template-columns:14rem"));
}
#[test]
fn shell_minimal_keeps_vars_not_cards() {
let page = json!({ "title": "t", "shell_css": "minimal" });
let html = render_page(&page, None, None);
assert!(html.contains("--ink:"));
assert!(!html.contains(".content.cards article"));
assert!(!html.contains("grid-template-columns:14rem"));
}
#[test]
fn layout_bare_skips_aside() {
let page = json!({
"title": "t",
"layout": "bare",
"sidebar": [{"label": "A", "href": "/a"}],
"nav": [{"label": "Home", "href": "/"}],
});
let html = render_page(&page, None, None);
assert!(html.contains("layout-bare"));
assert!(!html.contains("<aside"));
assert!(!html.contains("<header"));
}
#[test]
fn default_full_keeps_sidebar_grid() {
let page = json!({
"title": "t",
"sidebar": [{"label": "A", "href": "/a"}],
});
let html = render_page(&page, None, None);
assert!(html.contains("has-sidebar"));
assert!(html.contains("grid-template-columns:14rem"));
}
}
+60
View File
@@ -0,0 +1,60 @@
---
title: web C2 shell_css + layout
description: Offline render markers for shell modes and layouts.
import web:ext/web/web.mq.md
import json:lib/json.mq.md
import sys:lib/sys.mq.md
---
# main
`链` =
| 标签 | 链接 |
|------|------|
| Home | / |
| Desk | /desk |
*页 = > web.page title="c2" shell_css="off" layout="stacked"*
*页 = > json.set map=`页` key="nav" value=`链`*
*页 = > json.set map=`页` key="sidebar" value=`链`*
*html = > `页`.render*
*a = > split value=`html` sep="layout-stacked"*
*na = > len value=`a`*
*b = > split value=`html` sep="has-sidebar"*
*nb = > len value=`b`*
*c = > split value=`html` sep="grid-template-columns:14rem"*
*nc = > len value=`c`*
1. `na` > 1
1. `nb` == 1
1. `nc` == 1
> print text=stacked-off-ok
2. *
> print text=grid-still-present
> sys.exit code=1
2. *
> print text=has-sidebar-leak
> sys.exit code=1
2. *
> print text=stacked-missing
> sys.exit code=1
*裸 = > web.page title="bare" layout="bare" shell_css="minimal"*
*裸 = > json.set map=`裸` key="nav" value=`链`*
*裸 = > json.set map=`裸` key="sidebar" value=`链`*
*h2 = > `裸`.render*
*d = > split value=`h2` sep="<aside"*
*nd = > len value=`d`*
*e = > split value=`h2` sep="--ink:"*
*ne = > len value=`e`*
1. `nd` == 1
1. `ne` > 1
> print text=bare-minimal-ok
2. *
> print text=minimal-vars-missing
> sys.exit code=1
2. *
> print text=bare-aside-leak
> sys.exit code=1
> print text=c2-shell-ok