From 155183eb309d2d16e7d0a242f1a46747d6fc9f65 Mon Sep 17 00:00:00 2001 From: cflmy Date: Fri, 4 Sep 2026 12:48:50 +0800 Subject: [PATCH] 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 --- CHANGELOG.md | 1 + .../ext-web-customization/02-shell-css.md | 4 +- .../05-page-shell-slots.md | 4 +- doc/design/ext-web-customization/README.md | 2 +- doc/roadmap/ext-web.md | 2 +- ext/web/web.mq.md | 26 ++- ext/web/网页.mq.md | 26 ++- plugins/web/src/lib.rs | 62 ++++- plugins/web/src/render.rs | 216 +++++++++++++++--- tests/ext/web-c2-shell-layout.mq.md | 60 +++++ 10 files changed, 360 insertions(+), 43 deletions(-) create mode 100644 tests/ext/web-c2-shell-layout.mq.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 11bca27..5672805 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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。 diff --git a/doc/design/ext-web-customization/02-shell-css.md b/doc/design/ext-web-customization/02-shell-css.md index 2ddd09f..7577f70 100644 --- a/doc/design/ext-web-customization/02-shell-css.md +++ b/doc/design/ext-web-customization/02-shell-css.md @@ -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`。 diff --git a/doc/design/ext-web-customization/05-page-shell-slots.md b/doc/design/ext-web-customization/05-page-shell-slots.md index 5d07d6b..6e42e3b 100644 --- a/doc/design/ext-web-customization/05-page-shell-slots.md +++ b/doc/design/ext-web-customization/05-page-shell-slots.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`。金样同上。 diff --git a/doc/design/ext-web-customization/README.md b/doc/design/ext-web-customization/README.md index 4f05112..4082fb2 100644 --- a/doc/design/ext-web-customization/README.md +++ b/doc/design/ext-web-customization/README.md @@ -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) | diff --git a/doc/roadmap/ext-web.md b/doc/roadmap/ext-web.md index 3016b22..7a02008 100644 --- a/doc/roadmap/ext-web.md +++ b/doc/roadmap/ext-web.md @@ -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** | diff --git a/ext/web/web.mq.md b/ext/web/web.mq.md index 196c2b2..8c35eba 100644 --- a/ext/web/web.mq.md +++ b/ext/web/web.mq.md @@ -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` diff --git a/ext/web/网页.mq.md b/ext/web/网页.mq.md index f693a70..38348d1 100644 --- a/ext/web/网页.mq.md +++ b/ext/web/网页.mq.md @@ -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=`布局`** ## 路由 + `路径` diff --git a/plugins/web/src/lib.rs b/plugins/web/src/lib.rs index e7f0613..0cb21ab 100644 --- a/plugins/web/src/lib.rs +++ b/plugins/web/src/lib.rs @@ -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), diff --git a/plugins/web/src/render.rs b/plugins/web/src/render.rs index 7729234..8ff6678 100644 --- a/plugins/web/src/render.rs +++ b/plugins/web/src/render.rs @@ -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!("") + }; + + let show_chrome = !bare; + let side_html = if show_chrome && has_side { + format!( + "", + 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!( + "
{}
", + slot_class(args, "nav", "topnav"), + slot_attrs("nav", &parts, args), + render_ul(&nav, "nav") + ) + } else { + String::new() + }; + let footer_html = if show_chrome { + format!( + "
{}
", + slot_class(args, "footer", "foot"), + slot_attrs("footer", &parts, args), + render_ul(&foot, "foot-nav") + ) + } else { + String::new() + }; + format!( r#" {head} - +{style_block} -
{nav_ul}
+{header_html} {side_html}
{main_html}
-
{foot_ul}
+{footer_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!( - "", - 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 { s.push_str(""); 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(" 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=" 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