From 6cdfb0cf2a1898a4dafabf8d6162702730054620 Mon Sep 17 00:00:00 2001 From: JasonYv <233965174+JasonYv@users.noreply.github.com> Date: Thu, 19 Nov 2026 05:11:29 -0800 Subject: [PATCH 01/14] =?UTF-8?q?fix(admin):=20call=20a=20slug=20"URL=20?= =?UTF-8?q?=E5=88=AB=E5=90=8D"=20in=20Simplified=20Chinese?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The owner's choice for the term left open in phase 2. The slug field's label and every sentence that names a slug say "URL 别名", in the admin's catalog (22 messages) and in Atelier's admin catalog. `{slug}` placeholders carry the value and are unchanged; the English is unchanged. admin:size 166.2 KiB first load. Co-Authored-By: Claude Opus 5.5 --- docs/ADMIN_I18N_AND_UI.md | 13 +++++---- src/admin/locales/zh-CN.po | 44 ++++++++++++++--------------- src/themes/atelier/admin/zh-CN.json | 2 +- 3 files changed, 31 insertions(+), 28 deletions(-) diff --git a/docs/ADMIN_I18N_AND_UI.md b/docs/ADMIN_I18N_AND_UI.md index a7dd3cd..391cf52 100644 --- a/docs/ADMIN_I18N_AND_UI.md +++ b/docs/ADMIN_I18N_AND_UI.md @@ -5,7 +5,7 @@ written ("按照建议来"): D1 A (Lingui), D2 B built as A first, D3 C, D4 C, D5 as an addition under plugin API 2, D6 unchanged, D7 the four rules, D8 C. §8 records each phase as built and what is still the owner's: Windows - and Linux screenshots, the real-site check, two wording questions. + and Linux screenshots, the real-site check, one wording question. - Date: 2026-11-12 - Asked for by the owner on 2026-11-12, in two parts: the admin and the setup wizard have no multilingual support, and the admin's interface needs @@ -548,7 +548,7 @@ Phase 2 as built (commits `bb278c7` to the commit adding this note): every two or three pages and confirmed the wording each time; the agreed terms are 邮箱, 标语, 部署 / 重新构建, 缓存清除令牌, 边缘缓存, 片段, 询盘, 密钥 (for both a Worker secret and an API key), API 令牌, 权限范围, 撤销, - 替代文本, 定时发布. + 替代文本, 定时发布, and (from 2026-11-19) URL 别名 for Slug. - English changed where it was wrong, and only there: "1 pages · 1 sample records" in the wizard (and `01-wizard`'s assertion), "used by 1 items", "1 image(s) missing" and similar became real plurals. @@ -898,9 +898,12 @@ Phase 5 as built: - `GETTING_STARTED.md` and its Chinese translation no longer tell the reader to type `en` and `zh` in the wizard. - **Not done, and the owner's:** screenshots on Windows and Linux (§5.5); - the real-site check on a deployed site; and two wording questions — - whether "Slug" becomes "URL 别名", and whether the wizard's main language - should start as English rather than as the interface language. + the real-site check on a deployed site; and whether the wizard's main + language should start as English rather than as the interface language. +- **After phase 5**, on 2026-11-19, the owner chose "URL 别名" for "Slug": + the field's label and every sentence that names a slug, in the admin's + catalog and in Atelier's admin catalog. `{slug}` placeholders, which carry + the value itself, are unchanged. ## 9. Risks and open questions diff --git a/src/admin/locales/zh-CN.po b/src/admin/locales/zh-CN.po index c26b662..d7a92de 100644 --- a/src/admin/locales/zh-CN.po +++ b/src/admin/locales/zh-CN.po @@ -27,7 +27,7 @@ msgstr "“{base}”是存储文件专用的路径,不能用作内容的基础 #. js-lingui-explicit-id #: src/admin/server-messages.catalog.ts msgid "server.settings.path_clash" -msgstr "“{from}”会移到“{to}”,而这个地址已被其他内容占用。请先修改其中一个的 slug。没有做任何改动。" +msgstr "“{from}”会移到“{to}”,而这个地址已被其他内容占用。请先修改其中一个的 URL 别名。没有做任何改动。" #. js-lingui-explicit-id #: src/admin/server-messages.catalog.ts @@ -45,7 +45,7 @@ msgstr "不支持“{type}”类型的文件。" #: src/admin/slug.ts msgid "\"{typed}\" has no Latin letters or digits to build a slug from. Type one using Latin characters, or clear the field to derive it from the title." -msgstr "“{typed}”里没有拉丁字母或数字,无法生成 slug。请用拉丁字符填写,或清空此栏,由标题自动生成。" +msgstr "“{typed}”里没有拉丁字母或数字,无法生成 URL 别名。请用拉丁字符填写,或清空此栏,由标题自动生成。" #: src/admin/pages/setup.tsx msgid "\"{wrong}\" is not a language code. Use one such as de or pt-BR." @@ -89,7 +89,7 @@ msgstr "{0}/{1} 个文件" #. js-lingui-explicit-id #: src/admin/server-messages.catalog.ts msgid "server.settings.slugs_stranded" -msgstr "{count, plural, other {有 # 个 slug 会以新设置分配给某个语言或内容类型的地址开头。请先修改它们。}}" +msgstr "{count, plural, other {有 # 个 URL 别名会以新设置分配给某个语言或内容类型的地址开头。请先修改它们。}}" #: src/admin/components/record-editor.tsx msgid "{count, plural, one {Applies to # selected row.} other {Applies to # selected rows.}}" @@ -142,7 +142,7 @@ msgstr "{panelLabel}详情" #. js-lingui-explicit-id #: src/admin/server-messages.catalog.ts msgid "server.content.path_taken" -msgstr "{path} 已是 {kind}“{slug}”({locale})的地址。请换一个 slug。" +msgstr "{path} 已是 {kind}“{slug}”({locale})的地址。请换一个 URL 别名。" #: src/admin/pages/plugins.tsx msgid "{pluginName} enabled" @@ -163,7 +163,7 @@ msgstr "{scripts, plural, other {注入 # 个脚本}}" #: src/admin/form/controls.tsx msgid "{target} slug" -msgstr "{target} 的 slug" +msgstr "{target} 的 URL 别名" #: src/admin/pages/settings-advanced.tsx msgid "{when} — after {cause}, Cloudflare answered HTTP {status}" @@ -214,22 +214,22 @@ msgstr "设置修改" #. js-lingui-explicit-id #: src/admin/server-messages.catalog.ts msgid "server.slug.list_page" -msgstr "slug 不能以“page/{page}”开头:那是列表第 {page} 页的地址。" +msgstr "URL 别名不能以“page/{page}”开头:那是列表第 {page} 页的地址。" #. js-lingui-explicit-id #: src/admin/server-messages.catalog.ts msgid "server.slug.kind_start" -msgstr "多段 slug 不能以“{first}/”开头:那是内容类型“{kind}”的地址。" +msgstr "多段 URL 别名不能以“{first}/”开头:那是内容类型“{kind}”的地址。" #. js-lingui-explicit-id #: src/admin/server-messages.catalog.ts msgid "server.slug.locale_start" -msgstr "多段 slug 不能以“{first}/”开头:那是语言“{first}”的前缀。" +msgstr "多段 URL 别名不能以“{first}/”开头:那是语言“{first}”的前缀。" #. js-lingui-explicit-id #: src/admin/server-messages.catalog.ts msgid "server.slug.reserved_start" -msgstr "多段 slug 不能以“{first}/”开头:站点自身会响应这个地址。" +msgstr "多段 URL 别名不能以“{first}/”开头:站点自身会响应这个地址。" #: src/admin/pages/setup.tsx msgid "A starter fills the site with real pages you can edit or delete. Skipping gives you an empty site." @@ -655,7 +655,7 @@ msgstr "删除失败。" #. js-lingui-explicit-id #: src/admin/server-messages.catalog.ts msgid "server.content.slug_underivable" -msgstr "无法自动生成 slug,请手动填写。" +msgstr "无法自动生成 URL 别名,请手动填写。" #: src/admin/pages/content-list.tsx msgid "Could not load content." @@ -1852,7 +1852,7 @@ msgstr "跳过" #: src/admin/pages/editor.tsx msgid "Slug" -msgstr "Slug" +msgstr "URL 别名" #. js-lingui-explicit-id #: src/admin/server-messages.catalog.ts @@ -2050,55 +2050,55 @@ msgstr "站点后台" #. js-lingui-explicit-id #: src/admin/server-messages.catalog.ts msgid "server.slug.no_latin" -msgstr "slug“{slug}”中没有拉丁字母或数字,无法生成目录名。请用拉丁字符填写。" +msgstr "URL 别名“{slug}”中没有拉丁字母或数字,无法生成目录名。请用拉丁字符填写。" #: src/admin/slug.ts msgid "The slug became \"{normalized}\", because a slug is also a folder name in an export." -msgstr "slug 已改为“{normalized}”,因为导出时 slug 也是目录名。" +msgstr "URL 别名已改为“{normalized}”,因为导出时 URL 别名也是目录名。" #: src/admin/slug.ts msgid "The slug became \"{normalized}\": a slug has at most {MAX_SLUG_SEGMENTS} segments." -msgstr "slug 已改为“{normalized}”:slug 最多 {MAX_SLUG_SEGMENTS} 段。" +msgstr "URL 别名已改为“{normalized}”:URL 别名最多 {MAX_SLUG_SEGMENTS} 段。" #. js-lingui-explicit-id #: src/admin/server-messages.catalog.ts msgid "server.slug.too_many_segments" -msgstr "slug 有 {count} 段,最多允许 {max} 段。" +msgstr "URL 别名有 {count} 段,最多允许 {max} 段。" #. js-lingui-explicit-id #: src/admin/server-messages.catalog.ts msgid "server.slug.too_many_segments_use" -msgstr "slug 有 {count} 段,最多允许 {max} 段。可改用“{use}”。" +msgstr "URL 别名有 {count} 段,最多允许 {max} 段。可改用“{use}”。" #. js-lingui-explicit-id #: src/admin/server-messages.catalog.ts msgid "server.slug.empty_segment" -msgstr "slug 中有空段:以“/”开头或结尾,或者包含“//”。" +msgstr "URL 别名中有空段:以“/”开头或结尾,或者包含“//”。" #. js-lingui-explicit-id #: src/admin/server-messages.catalog.ts msgid "server.slug.empty_segment_use" -msgstr "slug 中有空段:以“/”开头或结尾,或者包含“//”。可改用“{use}”。" +msgstr "URL 别名中有空段:以“/”开头或结尾,或者包含“//”。可改用“{use}”。" #. js-lingui-explicit-id #: src/admin/server-messages.catalog.ts msgid "server.slug.empty" -msgstr "slug 为空。" +msgstr "URL 别名为空。" #. js-lingui-explicit-id #: src/admin/server-messages.catalog.ts msgid "server.slug.empty_use" -msgstr "slug 为空。可改用“{use}”。" +msgstr "URL 别名为空。可改用“{use}”。" #. js-lingui-explicit-id #: src/admin/server-messages.catalog.ts msgid "server.slug.too_long" -msgstr "slug 超过了 {max} 个字符。" +msgstr "URL 别名超过了 {max} 个字符。" #. js-lingui-explicit-id #: src/admin/server-messages.catalog.ts msgid "server.slug.not_canonical_use" -msgstr "slug 只能使用小写拉丁字母、数字和单个连字符。可改用“{use}”。" +msgstr "URL 别名只能使用小写拉丁字母、数字和单个连字符。可改用“{use}”。" #: src/admin/pages/setup.tsx msgid "The starter is installed. Its pages can be edited or deleted like any other." diff --git a/src/themes/atelier/admin/zh-CN.json b/src/themes/atelier/admin/zh-CN.json index 203b357..9390bb1 100644 --- a/src/themes/atelier/admin/zh-CN.json +++ b/src/themes/atelier/admin/zh-CN.json @@ -11,7 +11,7 @@ "kinds.product.fields.lead_time.label": "交货期", "kinds.product.fields.specs.label": "性能参数", "kinds.product.fields.category.label": "产品系列", - "kinds.product.fields.category.help": "该产品所属系列的 slug。", + "kinds.product.fields.category.help": "该产品所属系列的 URL 别名。", "groups.Classification": "分类", "kinds.product.fields.gallery.label": "图库", "kinds.product.fields.gallery.help": "images/ 下的相对路径,以可滑动的图片条展示。", From c83be6718f77e4ecf59b6404ab4f1480055abb2f Mon Sep 17 00:00:00 2001 From: JasonYv <233965174+JasonYv@users.noreply.github.com> Date: Thu, 19 Nov 2026 08:13:24 -0800 Subject: [PATCH 02/14] fix(admin): update a live item instead of saving it back to a draft On an item already on the site the editor still offered "Save draft", which stored it as a draft and took the page off the site without a word: the safe-looking button for fixing a typo unpublished it (docs/ADMIN_SIMPLE.md, G1). The buttons now follow the status the server last stored. A published or scheduled item has "Update", which keeps it on the site, and "Unpublish", which asks first; a draft keeps "Save draft" and "Publish". 03-publish, 13-editor-untouched and 21-editor-layout press "Update" on a published item, which is the name that changed; 03-publish gains a test that a live page has no "Save draft", that declining the question sends nothing, and that accepting it takes the page off the site. admin:size 166.2 KiB first load. Co-Authored-By: Claude Opus 5.5 --- src/admin/locales/en.po | 12 ++++++ src/admin/locales/zh-CN.po | 12 ++++++ src/admin/pages/editor.tsx | 54 ++++++++++++++++++++++----- test/e2e/03-publish.spec.ts | 56 +++++++++++++++++++++++++++- test/e2e/13-editor-untouched.spec.ts | 5 ++- test/e2e/21-editor-layout.spec.ts | 3 +- 6 files changed, 128 insertions(+), 14 deletions(-) diff --git a/src/admin/locales/en.po b/src/admin/locales/en.po index ec945f8..c17f40a 100644 --- a/src/admin/locales/en.po +++ b/src/admin/locales/en.po @@ -1899,6 +1899,10 @@ msgstr "Tagline" msgid "Tagline in {taglineLanguage}" msgstr "Tagline in {taglineLanguage}" +#: src/admin/pages/editor.tsx +msgid "Take this off the site? It stays here as a draft, and visitors no longer see it." +msgstr "Take this off the site? It stays here as a draft, and visitors no longer see it." + #: src/admin/pages/plugins.tsx msgid "Technical details" msgstr "Technical details" @@ -2266,6 +2270,10 @@ msgstr "Unknown status filter." msgid "unknown type" msgstr "unknown type" +#: src/admin/pages/editor.tsx +msgid "Unpublish" +msgstr "Unpublish" + #: src/admin/pages/editor.tsx msgid "Unsaved" msgstr "Unsaved" @@ -2279,6 +2287,10 @@ msgstr "Unsupported file type. Accepted: jpg, png, gif, webp, avif, pdf, xlsx, d msgid "unused" msgstr "unused" +#: src/admin/pages/editor.tsx +msgid "Update" +msgstr "Update" + #: src/admin/pages/content-list.tsx msgid "Updated" msgstr "Updated" diff --git a/src/admin/locales/zh-CN.po b/src/admin/locales/zh-CN.po index d7a92de..da4639c 100644 --- a/src/admin/locales/zh-CN.po +++ b/src/admin/locales/zh-CN.po @@ -1899,6 +1899,10 @@ msgstr "标语" msgid "Tagline in {taglineLanguage}" msgstr "{taglineLanguage}标语" +#: src/admin/pages/editor.tsx +msgid "Take this off the site? It stays here as a draft, and visitors no longer see it." +msgstr "要从网站上撤下吗?它会作为草稿保留在这里,访客将看不到它。" + #: src/admin/pages/plugins.tsx msgid "Technical details" msgstr "技术细节" @@ -2266,6 +2270,10 @@ msgstr "未知的状态筛选条件。" msgid "unknown type" msgstr "未知类型" +#: src/admin/pages/editor.tsx +msgid "Unpublish" +msgstr "取消发布" + #: src/admin/pages/editor.tsx msgid "Unsaved" msgstr "未保存" @@ -2279,6 +2287,10 @@ msgstr "不支持的文件类型。支持:jpg、png、gif、webp、avif、pdf msgid "unused" msgstr "未使用" +#: src/admin/pages/editor.tsx +msgid "Update" +msgstr "更新" + #: src/admin/pages/content-list.tsx msgid "Updated" msgstr "更新时间" diff --git a/src/admin/pages/editor.tsx b/src/admin/pages/editor.tsx index cad666e..44138d2 100644 --- a/src/admin/pages/editor.tsx +++ b/src/admin/pages/editor.tsx @@ -196,6 +196,14 @@ function Editor({ const [busy, setBusy] = useState(false); // How the last save went out: a draft is saved but no visitor sees it. const [saved, setSaved] = useState<'draft' | 'published' | null>(null); + // The status the server last stored, which decides what the buttons say: + // an item on the site is updated or taken off it, never quietly turned + // back into a draft by a button that reads "Save draft" (ADMIN_SIMPLE.md, + // G1 and D6). + const [stored, setStored] = useState( + loaded?.status ?? null, + ); + const live = stored === 'published' || stored === 'scheduled'; const [preview, setPreview] = useState(''); const [missing, setMissing] = useState([]); const [fieldsOpen, setFieldsOpen] = useState(readFieldsOpen); @@ -375,6 +383,13 @@ function Editor({ // As stored, not as asked: a body too long to render safely is kept // as a draft, and a draft reaches no visitor. setSaved(result.status === 'draft' ? 'draft' : 'published'); + if ( + result.status === 'draft' || + result.status === 'published' || + result.status === 'scheduled' + ) { + setStored(result.status); + } // Every list it appears in, and its own record, are out of date. void client.invalidateQueries({ queryKey: keys.content }); // The save still succeeded — this is the server saying it skipped @@ -460,20 +475,41 @@ function Editor({ {saved !== null && !dirty ? ( ) : null} - + {live ? ( + + ) : ( + + )} ); diff --git a/test/e2e/03-publish.spec.ts b/test/e2e/03-publish.spec.ts index c25df94..a0064ed 100644 --- a/test/e2e/03-publish.spec.ts +++ b/test/e2e/03-publish.spec.ts @@ -26,7 +26,7 @@ const EDITED = 'The second body text, after an edit.'; */ async function saveWith( page: Page, - name: 'Publish' | 'Save draft', + name: 'Publish' | 'Save draft' | 'Update', ): Promise { const saved = page.waitForResponse( (response) => @@ -103,7 +103,8 @@ test('shows an edit on the public page, once the cache lets it', async ({ await expect(page.locator('.cm-content')).toContainText(BODY); await rewriteDocument(page, `---\ntitle: ${TITLE}\n---\n\n${EDITED}`); - await saveWith(page, 'Publish'); + // A page already on the site is updated, not published again (G1, D6). + await saveWith(page, 'Update'); // The save response above already proved the new text is stored; what is // left to prove is when a reader sees it. @@ -131,3 +132,54 @@ test('keeps a draft off the public site', async ({ page }) => { const response = await page.goto('/not-for-readers'); expect(response?.status()).toBe(404); }); + +test('a published page is updated or unpublished, never saved back to a draft', async ({ + page, +}) => { + await signIn(page); + await page.getByRole('button', { name: 'New' }).click(); + await page.getByRole('combobox', { name: /^Type/ }).selectOption('page'); + await page + .getByRole('textbox', { name: 'Title', exact: true }) + .fill('Live for now'); + await page.getByLabel('Slug', { exact: true }).fill('live-for-now'); + // Not fetched while live: that would put it in the edge cache, which with + // no purge token here keeps it for a minute (see the test above), and + // the 404 below would wait on the cache instead of on the save. + await saveWith(page, 'Publish'); + + // Once it is live, nothing reads "Save draft": the safe-looking button + // used to take the page off the site (docs/ADMIN_SIMPLE.md, G1). + await expect(page.getByRole('button', { name: 'Save draft' })).toHaveCount(0); + await expect(page.getByRole('button', { name: 'Update' })).toBeVisible(); + + // Taking it off asks first; declining sends nothing. + let posted = 0; + page.on('request', (request) => { + if ( + request.method() === 'POST' && + request.url().endsWith('/_mallok/api/content') + ) { + posted += 1; + } + }); + page.once('dialog', (dialog) => void dialog.dismiss()); + await page.getByRole('button', { name: 'Unpublish' }).click(); + await page.waitForTimeout(300); + expect(posted).toBe(0); + + page.once('dialog', (dialog) => void dialog.accept()); + const saved = page.waitForResponse( + (response) => + response.url().endsWith('/_mallok/api/content') && + response.request().method() === 'POST', + ); + await page.getByRole('button', { name: 'Unpublish' }).click(); + expect(((await (await saved).json()) as { status: string }).status).toBe( + 'draft', + ); + expect((await page.request.get('/live-for-now')).status()).toBe(404); + // A draft again, so the buttons are a draft's. + await expect(page.getByRole('button', { name: 'Publish' })).toBeVisible(); + await expect(page.getByRole('button', { name: 'Save draft' })).toBeVisible(); +}); diff --git a/test/e2e/13-editor-untouched.spec.ts b/test/e2e/13-editor-untouched.spec.ts index 85db615..6f60c11 100644 --- a/test/e2e/13-editor-untouched.spec.ts +++ b/test/e2e/13-editor-untouched.spec.ts @@ -71,14 +71,15 @@ test('an item that is opened and not edited is not unsaved, and saves as unchang await expect(page.getByText('Unsaved', { exact: true })).toHaveCount(0); } - // Still on the CRLF item, untouched. Publishing it stores nothing new: + // Still on the CRLF item, untouched and live, so its button is "Update" + // (G1, D6). Updating it stores nothing new: // the server compares bytes, and they are the bytes it already has. const saved = page.waitForResponse( (response) => response.url().endsWith('/_mallok/api/content') && response.request().method() === 'POST', ); - await page.getByRole('button', { name: 'Publish' }).click(); + await page.getByRole('button', { name: 'Update' }).click(); const answer = (await (await saved).json()) as { unchanged?: boolean }; expect(answer.unchanged).toBe(true); const stored = await page.request.get(`/_mallok/api/content/${crlf}`, { diff --git a/test/e2e/21-editor-layout.spec.ts b/test/e2e/21-editor-layout.spec.ts index 55aa28f..7028e3b 100644 --- a/test/e2e/21-editor-layout.spec.ts +++ b/test/e2e/21-editor-layout.spec.ts @@ -78,7 +78,8 @@ test('on a phone one pane is shown and the save buttons stay on screen', async ( await signIn(page); await openPublished(page); - const publish = page.getByRole('button', { name: 'Publish' }); + // A published item's primary button is "Update" (G1, D6). + const publish = page.getByRole('button', { name: 'Update' }); await expect(publish).toBeInViewport(); await clean(page, 'editor on a phone, fields'); From 5663c91f269db0e6608d261434b8a3d2117debee Mon Sep 17 00:00:00 2001 From: JasonYv <233965174+JasonYv@users.noreply.github.com> Date: Thu, 19 Nov 2026 08:13:49 -0800 Subject: [PATCH 03/14] docs: plan an admin that reads like a mainstream CMS MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit docs/ADMIN_SIMPLE.md, written with the owner after they found the admin too technical to operate: 25 findings from a screenshot tour, ranked by how much each hurts a non-technical operator; how WordPress, Shopify and Ghost handle the same screens; the target sidebar, lists, editor, home page and vocabulary; ten decisions; and phases 0–9. The owner took every recommendation. G1 and the "URL 别名" wording are already built. Co-Authored-By: Claude Opus 5.5 --- docs/ADMIN_SIMPLE.md | 872 +++++++++++++++++++++++++++++++++++++++++++ docs/README.md | 1 + 2 files changed, 873 insertions(+) create mode 100644 docs/ADMIN_SIMPLE.md diff --git a/docs/ADMIN_SIMPLE.md b/docs/ADMIN_SIMPLE.md new file mode 100644 index 0000000..0729f89 --- /dev/null +++ b/docs/ADMIN_SIMPLE.md @@ -0,0 +1,872 @@ +# A simpler admin: direction and plan + +- Status: **decided**. On 2026-11-19 the owner took every recommendation + in §4 as written ("可以 搞吧"): D1–D10 as recommended, D5 as option A + (assisted Markdown first, a Tiptap spike before anything more). Built so + far: G1 (`c83be67`), ahead of phase 4 because it unpublishes live pages; + G10's "URL 别名" (`6cdfb0c`). The width draft of §2.2 is superseded by D7 + and kept only as a stash. +- Date: 2026-11-19 +- Asked for by the owner on 2026-11-19: "我的目的就是,如果登录到 admin 后, + 操作要简单,参考主流的 CMS 后台,而不是那么极客。" Once signed in, operating + the admin should be simple, modelled on mainstream CMS admins, and not so + geeky. The owner asked for a direction for the whole admin, not a list of + single fixes. +- Measured at `ffec401` (`main`) plus the uncommitted draft on + `feat/admin-wide-lists` (five files, 13 lines; §2.2). +- Follows `ADMIN_I18N_AND_UI.md`, which translated the admin and fixed + findings U1–U20. Nothing done there is proposed again; where this plan + changes something that plan decided, it says so and makes it a decision. + +## 1. Goal + +1. A person who runs a trade company's site, reads Chinese, and is not a + developer can do the daily work — read an inquiry, add a product, fix a + sentence, publish a news item — without meeting a word or a control they + have to ask someone about. +2. The admin looks and behaves like the admins that person may already + know (WordPress, Shopify), in structure, not in decoration: a home + screen, lists by content type, a writing-first editor, settings that + show the common case first. +3. Everything that makes it "geeky" today is still reachable, one step + further away, for the person who deployed the site. + +Out of scope: the public site and its themes' templates; the CLI; new +content features beyond the ones named in §6 (revision history, multiple +users and roles, bulk edit, a navigation editor); a third interface +language; right-to-left layout; decoration (colours, illustration, brand). +A full visual editor is not in this plan's phases; whether to bring it +forward is decision D5. + +## 2. Where it is today + +### 2.1 The evidence, and its limits + +| Source | What it is | +| --- | --- | +| `.tmp/tour/` | 29 screenshots, 2026-11-19: the wizard (English), every admin page at 1440 px and 390 px in Simplified Chinese, the editor on a product and on a new item, the account menu. Starter `trade-b2b`, theme Atelier 2.5.2, content languages English and Chinese | +| `.tmp/wide/before`, `.tmp/wide/after` | 21 pairs for the uncommitted width draft, English interface, sidebar open and closed, 1280–2560 px | +| The code | `src/admin` (7,784 lines in `pages/` and `components/`), `src/worker/admin*.ts`, the inquiry plugin's and Atelier's manifests. A claim taken from code says so | +| `node scripts/admin-size.mjs` | Run on the existing build of 2026-11-19 07:13: **first load 166.3 KiB gzip of 170**, 478.6 KiB loaded on demand | + +Limits, so that nothing below is read as wider than it is: + +- **The tour was captured with the width draft applied.** In the images the + content list starts 291 px from the left at 1440 px and the settings + pages 339 px; on `main` both start at 339 px. +- **`login-1440.png` is not the sign-in page.** It shows the content list + in English. The sign-in page is not reviewed here. +- **Inquiries and Media were captured empty.** What a row looks like is + taken from the manifest and the code, not seen. +- The sidebar shows "目录条目" and "Catalog log". They belong to a test + plugin ("A test plugin: products with a price and variants") in the + instance that was photographed, not to a real site. +- Light scheme only; macOS only. + +### 2.2 The width draft, measured + +The shell centres one column (`mx-auto`) inside the area beside the +sidebar. On `main` the column is 68 rem (1,088 px). The draft adds a second +width, 90 rem (1,440 px), for the content list, Media and plugin panels, +and leaves forms at 68 rem. + +| Window, sidebar open | `main`: band left of the content | Draft: list pages | Draft: form pages | +| --- | ---: | ---: | ---: | +| 1440 px | 83 px | 35 px | 83 px | +| 1920 px | 323 px | 147 px | 323 px | +| 2560 px | 643 px | 467 px | 643 px | + +Computed from the classes in `shell.tsx` (256 px sidebar, `max-w-[68rem]` +or `max-w-[90rem]`, 35 px padding at these widths) and checked against the +images: 579 px and 403 px left edges at 1920 px, 723 px at 2560 px. + +Two things follow. The draft does remove the wrapped paths: at 1920 px the +longest path in the starter no longer breaks mid-word. But **it gives the +admin two left edges**: moving from Content to Settings shifts the heading +48 px at 1440 px and 176 px at 1920 px, and the band beside the sidebar is +still there, only narrower. The band comes from centring, not from the cap. +D7 proposes the alternative. + +### 2.3 What makes it geeky, ranked + +Severity is how much a finding hurts the operator of §1: **1** — it +misleads them or stops a daily task; **2** — it makes them hesitate, ask, +or learn a concept they should not need; **3** — it is noise. + +| # | Sev | Where | What is wrong | Evidence | +| --- | :-: | --- | --- | --- | +| G1 | 1 | Editor | **"Save draft" on a published item takes it off the site**, with no warning: the two buttons always send `status: 'draft'` or `'published'`. An operator fixing a typo who presses the safer-sounding button unpublishes the page. Every mainstream admin changes the button to "Update" once an item is live | Code: `pages/editor.tsx`, `save('draft')` | +| G2 | 1 | Editor | The centre of the editor is raw source, **front matter included**: line 1 is `---`, then `title:`, `lead_time:`, `specs:` as YAML, a second copy of what the field pane beside it already shows. A stray space in that block is a YAML error. This is the screen an operator uses most, and it opens as a code editor with line numbers | `editor-product-1440.png`, `editor-new-1440.png` | +| G3 | 1 | Editor | There is **no way to put an image into the body** except typing `![](images/…)`: the media picker opens only from a declared field. There is no formatting control of any kind; a heading is `##` | Code: `markdown-editor.tsx` has no toolbar, drop or paste handler; `pickMedia` is passed only to the form | +| G4 | 1 | Editor | **Publish date, cover image and tags cannot be set without writing YAML.** The form always offers Title and Description and then only what the theme declares; `date`, `cover` and `tags` are common fields of every item (`CONTENT_FORMAT.md §3.1`) and Atelier's article kind declares none. A news item cannot be scheduled from the form | Code: `specs` in `pages/editor.tsx`; `themes/atelier/theme.json` | +| G5 | 1 | Content list | **An item cannot be deleted from the admin.** The Worker has `DELETE /_mallok/api/content/`; no page calls it. The starter's 13 sample pages can be unpublished but never removed | Code: no `method: 'DELETE'` on content in `src/admin` | +| G6 | 1 | Content list | **No search.** With the starter the list is 13 rows; the owner's own sites publish news daily. `ADMIN.md §4` lists search; neither the page nor the API has it (the API filters by kind, language, slug and status) | Code: `admin-content.ts` | +| G7 | 1 | After sign-in | The first screen is a table of every item of every type. Nothing says what needs attention — a new inquiry, an inquiry form with no recipient address, no domain — or what to do first. A fresh site's most important fact, that inquiries go nowhere until a recipient is entered, is on the Plugins page under a required field | `content-1440.png`, `plugins-1440.png` | +| G8 | 2 | Content list | One list mixes six types (页面, 产品, 文章, 产品系列, 案例, 常见问题) behind a "类型" filter. This is the developer's model — one `content` table — not the operator's, who thinks "my products" and "my news". WordPress and Shopify give each type its own entry | `content-1440.png` | +| G9 | 2 | Content list | The **路径 column**: `/cases/heat-exchanger-plate-for-a-desalination-retrofit`, monospace, the widest column on the page, and the one that wrapped mid-word before the draft. It repeats the title in a form only a browser needs | `content-1440.png`, `wide/before/content-1920-open.png` | +| G10 | 2 | Editor | The first two controls of the editor are **类型** and **Slug** — still the English word in the Chinese interface (`zh-CN.po` maps "Slug" to "Slug"; the owner chose "URL 别名" on 2026-11-19 and it is not applied). The title, which is what the operator came to type, is a small field in the left pane | `editor-new-1440.png` | +| G11 | 2 | Editor | Three panes of 350 to 380 px each at 1440 px. The body wraps at about 40 characters; the preview shows the theme's phone layout; a product's five properties need scrolling. No pane is big enough for its job | `editor-product-1440.png` | +| G12 | 2 | Editor, 390 px | The bar — back link, type, Slug, status, date, "在站点上查看", language chips, pane tabs — takes the first 430 px. The first field starts below the middle of the screen | `editor-product-390.png` | +| G13 | 2 | Sidebar | The group is called **站点** and the first item under 设置 is also **站点**. **插件** sits beside 内容 and 媒体 although a deployment, not the operator, changes it. Every plugin panel has the same list icon. The breadcrumb for Inquiries reads "插件 › 询盘" and its subtitle "来自 询盘 插件。插件设置" — how it is built, not what it is | `inquiries-1440.png`, every page | +| G14 | 2 | Appearance | Three options are **typed as syntax**: "数据(数值\|名称 ;; 数值\|名称)", "认证(用逗号分隔)", "能力要点(标题\|说明 ;; 标题\|说明)". One wrong separator changes the home page. A "内容语言" select with one useful meaning sits above the first option. Below the form: "前台 JavaScript — 注入 1 个脚本", `/theme/atelier/2.5.2`, `assets/hero-carousel.js` | `settings-appearance-1440.png` | +| G15 | 2 | Plugins | The page opens with `src/plugins/` and `src/plugins/index.ts`. The inquiry settings are one flat list of nine in which "收件邮箱" (required, and the only one most sites need) has the same weight as "Turnstile 站点密钥", "Liquid 模板。可用变量:name、site_name…" and "ISO 3166-1 两位字母代码" | `plugins-1440.png` | +| G16 | 2 | Settings → Site | "默认语言不带 URL 前缀;其他语言都在 `//` 下提供", a checkbox "默认语言也加前缀(`/en/…`)" that moves every URL of the site, and "媒体域名" stand in the first settings page at the same level as the site's name | `settings-site-1440.png` | +| G17 | 2 | Media | The page introduces itself with "文件按原图的哈希值存储…" and, under the drop zone, "转换为 WebP,并按 480、960和1440 像素宽度上传。不支持 SVG——它可能携带脚本". Both are true and neither helps anyone upload a photo | `media-1440.png` | +| G18 | 2 | Account | Between the password form and the tokens: "密码使用 PBKDF2-SHA256 哈希,迭代 50,000 次…Cloudflare 免费计划 10 毫秒的 CPU 预算". Then API tokens with scopes printed as `content:write`, `media:write`. The menu entry is "账号与 API 令牌". An operator who wants to change a password reads all of it | `account-1440.png`, `account-menu-1440.png` | +| G19 | 2 | Everywhere | Content languages carry their code and a flag word: "英语(en)· 默认", "中文(zh)", in the list's filter, the editor's chips, Appearance and Site. The last plan chose name-and-code on purpose (its D7); seen in daily use it is the most frequent piece of code-like text in the admin | Every content screenshot | +| G20 | 2 | Inquiries | Empty, it says "这里还没有内容。" — the generic sentence — beside two disabled buttons. Nothing says where inquiries come from or that the recipient address is not set. From the manifest: a row shows name, email, country, status and time; **the message is not in the row** and needs the detail view | `inquiries-1440.png`; `plugins/inquiry/plugin.json` | +| G21 | 3 | Width | §2.2: a band beside the sidebar, and under the draft two left edges | `.tmp/wide` | +| G22 | 3 | Content list | Dates are all "2026年11月19日"; a list that is ordered by last change reads better as "今天 07:12". No thumbnail on a product row | `content-1440.png` | +| G23 | 3 | Settings | Ledes explain the architecture instead of the page: "点击保存即生效——无需重新构建或部署", "以下选项是运行时设置…主题本身属于源代码" | `settings-site-1440.png`, `settings-appearance-1440.png` | +| G24 | 3 | Email | "Resend API 密钥" with no word on what Resend is or where a key comes from. The warning below it is clear and should stay | `settings-email-1440.png` | +| G25 | 3 | Wizard | The first field a new owner types after the password is "Setup key — Printed once by `mallok create`"; step 4 says "Cloudflare's edge cache does not apply to it" in bold. Both are honest and required (`ADMIN.md §5`); the person at this screen is the one who deployed. The result screen opens the content list | `wizard-1-admin-1440.png`, `wizard-4-domain-1440.png` | + +**What already holds up**, and is kept: one-line standing notice; the +status badge, "Updated" and "View on site" in the editor; honest saved +messages; named content languages; empty states with one action; panels in +the sidebar; Advanced as the one place for infrastructure words; no page +scrolls sideways at 390 px. + +**The pattern.** Six of the seven severity-1 findings are in the editor +and the content list, and each is the same thing: the screen shows the +storage model (one table, a Markdown file with a YAML header, a status +column) instead of the task (write a page, publish it, find it again). +Measured against §3, the admin today sits with Strapi and Payload, which +are built for developers, and the owner is asking for WordPress and +Shopify. + +## 3. How mainstream admins handle the same screens + +Written from working knowledge of these products, not from a fresh review +of each: no screenshot was taken and no pixel measured for this section. +"Sure" marks what has been stable for years and is safe to design against; +"less sure" marks what may have changed or what is remembered loosely. +Phase 0 (§7) re-checks anything a decision turns on. + +| Screen | WordPress | Shopify | Ghost | Strapi / Payload | +| --- | --- | --- | --- | --- | +| After sign-in | A dashboard: "At a Glance" counts, recent activity, a quick draft, site health | Home: a setup guide with steps to complete on a new shop, then things needing attention | A dashboard of member and post figures | Straight to the content manager or a near-empty welcome page | +| Navigation | One entry per type: Posts, Pages, Media; then Appearance, Plugins, Settings | One entry per thing: Orders, Products, Customers, Content; Settings is a separate area opened from the foot of the sidebar | Posts, Pages, Tags, Members; Settings behind a gear | "Content Manager" listing collection types by their model names | +| List | Title, author, categories, date. **No slug or URL column.** Status as tabs above the table (All, Published, Drafts). A search box. Row actions on hover: Edit, Quick Edit, Trash, View. Columns chosen under "Screen Options" | Thumbnail, title, status badge, a few facts. Status as tabs (All, Active, Draft, Archived). Search and filters. No URL | Title, status, date; filters by status and tag | A table with configurable columns that by default includes the numeric id; filters built from field names | +| Editor | Title and body in one wide column; a settings sidebar on the right (status, URL, categories, featured image) that can be closed; the primary button is "Publish", then "Save" or "Update" once live; "Switch to draft" is a separate, explicit action | Main column: title, rich-text description, media, then the type's own fields as cards. Right column: status and organisation. **The URL is inside a "Search engine listing" card that is closed until "Edit" is pressed.** A save bar appears when something changed | Title and body alone, full width, nothing else on screen; a side panel slides in for URL, date, tags, excerpt; "Publish" opens a short confirmation flow; then "Update" and "Unpublish" | Every field of the model in a form, in schema order, with a right rail for status; the slug is an ordinary visible field | +| Settings | Sub-pages (General, Reading, Permalinks…), each a plain form with one save button; the permalink structure has its own page, apart from General | A separate area with its own menu; each page is cards, the common fields first | A searchable single page of cards | Split between project settings and plugin configuration | +| Media | A grid of thumbnails; clicking one opens its details (alt text, title); upload by drop anywhere | Files as a list with thumbnails; images are mostly added where they are used | No library; images are placed in the post | A grid with folders | +| Forms, inquiries | Not in core. Form plugins store entries in a list with a detail view (less sure of each plugin's layout) | Not in the basic product; a contact form sends email. Shopify Inbox is a chat-style list with a reading pane (less sure) | Not in core | None; a collection the developer defines | +| Width | Lists are fluid and left-aligned; forms are left-aligned with labels in a left column | A centred, capped page; index tables may go full width (the cap's value is not something measured here) | Centred and capped | Fluid | + +Wix and Squarespace are site builders: the operator edits the page in +place, and their content lists and form inboxes are secondary screens. +Less sure of their current layouts, and they are not used as a model for +any screen below — editing in place is a different product from Mallok's +(`PRODUCT_VISION.md §4`: themes are source). + +What the first three share, and Mallok lacks or does differently: + +1. A first screen that says what to do next. +2. A sidebar entry per content type. +3. A list with no address column, with search, with status as tabs. +4. An editor whose main column is the title and the body, with everything + that is not writing in a panel beside it. +5. The address as a closed-by-default detail, edited rarely. +6. A primary button that says what it will do to *this* item: Publish, + then Update. + +## 4. Decisions the owner has to make + +### D1 — The first screen after sign-in + +| | A. As today | B. A Home page: next steps and what is new | C. A dashboard with figures | +| --- | --- | --- | --- | +| Shows | The content list | Up to four unfinished setup steps, each a link; the newest rows of each plugin's list (inquiries); the five items edited last; shortcuts to add content | B plus visits, inquiry counts over time | +| New Worker code | None | None: it reads what the shell already loads (settings, health, plugins), `GET /content?limit=5`, each table panel's first rows, and `/diagnostics` | An analytics source Mallok does not have, and counting queries | +| First-load cost | None | A page loaded on demand; the shell gains one link | As B | + +**Recommended: B.** It answers G7 with data the admin already has. The +setup steps are derived, never stored: no custom domain +(`health.customDomain`), no email key or sender (`/diagnostics`), an +enabled plugin with an empty required setting (the inquiry recipient), no +content edited since the starter was installed. A step disappears when its +condition does, and the card disappears with the last one. C is not +recommended: Mallok records no visits, and `COUNT(*)` over inquiries is +the kind of query the budgets exist to prevent. + +### D2 — The sidebar + +| | A. As today | B. By what the operator works on | +| --- | --- | --- | +| Top | Content, Media, each panel, Plugins | Home; then each plugin panel (Inquiries) | +| Content | One "Content" entry, all types behind a filter | A "Content" group with **one entry per content type the theme declares**, by the theme's label, then Media | +| Settings | Site, Appearance, Email, Advanced | General (renamed from Site), Appearance, Email, Plugins, Advanced | +| Cost | — | The entries come from `GET /_mallok/api/theme`, which the shell already loads. A type the site has content of but the theme no longer declares needs a place (an "Other content" entry, shown only then) | + +**Recommended: B.** It is G8 and G13 in one change, and it is what +WordPress and Shopify do. The list page is the same page with the type +fixed by the address (`/content?kind=product` works today), so "New +Product" and the empty state already say the right thing. Plugins moves to +Settings because the operator can change only a switch and settings there, +and the page itself says installing one is a deployment. Atelier declares +six types; six entries and Media is a longer sidebar than today's, and +still shorter than a WordPress site's. + +### D3 — The address: path and slug + +| | A. As today | B. Out of the list; in the editor's panel, as an address | C. Hidden entirely | +| --- | --- | --- | --- | +| List | A Path column | No column. "View" in the row's actions opens the page; "Copy address" in its menu | As B | +| Editor | "Slug" in the top bar, first | In the settings panel, under "Search and address", shown as the whole address with only its last part editable: `example.com/products/` `[grade-5-titanium-bar]` | Generated from the title; never shown | +| Risk | — | None to data. The field keeps `slug.ts`'s rules and messages | A Chinese title has no Latin letters to build a slug from (`ADMIN.md §6.2`), so the operator must be able to type one | + +**Recommended: B.** C cannot work for this audience for the reason in the +table. The words follow §5.4: the field is "Web address" / "网址", and its +editable part is "URL 别名", the owner's choice of 2026-11-19. For a +new item with a title that yields no slug, the panel opens itself at that +field with today's explanation. + +### D4 — The editor's layout + +| | A. Three panes, as today | B. Writing-first | C. B, with the source one step away | +| --- | --- | --- | --- | +| Main column | Fields, source, preview side by side | The title as a large field, the body, then the type's own fields as cards (a product's specification, gallery, datasheet) | As B | +| Beside it | — | One panel: status and publishing, language versions, publish date, summary, cover, tags, address. It closes, and this browser remembers | As B | +| Preview | Always on, about 350 px | A "Preview" button swaps the panel for the preview; on a window of 1600 px or more both fit | As B | +| The YAML block | In the source, always | Not shown. The body editor holds the body only | Not shown by default; "Edit source" in the "More" menu opens today's whole-document editor | +| Who loses | The operator | Whoever pastes a document with front matter or fixes an unusual field by hand | No one | + +**Recommended: C.** B is what the owner asked for; C costs one menu item +more and keeps the promise that the Markdown is the operator's own file +(`PRODUCT_VISION.md §5.2`). The type's fields go in the main column, not +the panel, because for a product they *are* the content — Shopify's layout, +not Ghost's. Two things must hold and are tested (§8): an item opened and +closed is byte-identical, which means the hidden block is kept as the text +it was and re-serialised only when a field is edited, exactly as now; and +a field the theme does not declare is preserved. + +### D5 — Visual editing before 0.2 + +`ADMIN.md §14` and `PRODUCT_VISION.md §9` put the visual editor (Tiptap) in +0.2. Read on 2026-11-19: `@tiptap/core` and `@tiptap/markdown` are at +3.34.0 (npm, published 2026-11-13); Tiptap's Markdown page says the +extension "is a early release and can be subject to change or may have +edge cases that may not be supported yet", and does not say that a +document it parses and writes back is unchanged. **Its size in this +admin's build and its fidelity on Mallok's content are not measured.** + +| | A. Assisted Markdown now | B. Tiptap now | C. A, then a measured spike | +| --- | --- | --- | --- | +| What the operator gets | The body in a proportional face, no line numbers, headings and bold styled as they are typed; a toolbar (heading, bold, italic, list, link, quote, image, table) that inserts the syntax; images by button, drop and paste | True what-you-see-is-what-you-get | A now; B's facts before 0.2 is planned | +| New dependencies | None: CodeMirror's Markdown package is already loaded with the editor | Three or more packages through `TECH_STACK.md §11`, on an extension its authors call early | None until the spike reports | +| Risk to "Markdown is the truth" | None: the text is still what is typed | High until proven: a visual editor rewrites the whole body on save, so an untouched paragraph can change bytes; raw HTML, tables and reference links are the known hard cases | Contained in a throwaway branch | +| Still shows `##` and `**` | Yes, styled | No | Yes, until 0.2 | + +**Recommended: C.** A removes most of what G2 and G3 describe at no +dependency cost and no risk to the contract. The spike is one small phase +(§7, phase 8): load the starter's 13 pages and the owner's real articles +into Tiptap with its Markdown extension, write them back, and report how +many are byte-identical, how many differ only in whitespace, and what the +editor chunk weighs. With that number the owner can decide whether 0.2's +editor is Tiptap, and whether "unchanged unless edited" has to be relaxed +to "unchanged paragraphs are kept" — which is a change to +`CONTENT_FORMAT.md §3`, not to the admin. B today would be choosing that +change without the number. + +### D6 — What the buttons do to a live page + +| | A. As today | B. By the item's state | +| --- | --- | --- | +| A draft or a new item | Save draft · Publish | Save draft · **Publish** | +| A published item | Save draft (unpublishes) · Publish | **Update**. "Unpublish" and "Delete" are in the "More" menu, each with a confirmation that says what a visitor will see | +| A scheduled item | Save draft · Publish | **Update** · "Publish now" in the menu | +| Changes | — | Labels and one menu. The API is unchanged: Update sends `published`, Unpublish sends `draft`, Delete calls the existing route | + +**Recommended: B.** It is G1 and G5, the smallest change in this plan and +the one that stops an operator taking a page down by accident. What the +delete route does to the item's redirects, its translations and its +images' reference counts was not read for this proposal; the confirmation +must state it, so phase 4's first step is to read it and write the +sentence from what the code does. + +### D7 — Width and alignment + +| | A. Centred, 68 rem (`main`) | B. Centred, 90 rem for lists (the draft) | C. Left-aligned, capped by kind of page | D. Fluid | +| --- | --- | --- | --- | --- | +| Left edge | Moves with the window | Moves with the window **and** with the page | Fixed: the sidebar plus the page's padding, on every page at every width | Fixed | +| Band beside the sidebar at 1920 px | 323 px | 147 px on lists, 323 px on forms | **None** | None | +| Spare room | Split left and right | Split left and right | On the right only, where a page ends | None; rows stretch | +| A table row at 2560 px | 1,018 px | 1,370 px | 1,370 px (cap 90 rem) | 2,234 px: title and status are a screen apart | +| A form | Fields 42 rem in a 68 rem card | As A | Fields 42 rem; the card ends at 56 rem instead of running empty to 68 | Cards 2,234 px wide around 672 px fields | + +**Recommended: C.** The complaint was a band beside a centred column, and +only left alignment removes the band; the draft narrows it and adds a +second edge (§2.2). With D3 the list also loses its widest column, so the +pressure that produced the draft goes away. Lists and panels cap at +90 rem, forms at 56 rem, Home at 68 rem; the editor stays full width. The +standing notice takes the page's width, as now. This replaces the +uncommitted draft; its one good line — removing `max-w-72` from the path +cell — is moot once the column is gone. + +### D8 — Content languages in daily screens + +The last plan's D7 ruled that a content language always shows its name +and its code. That rule did its job — nobody confuses it with the +interface language — and G19 is its cost. + +| | A. Name and code everywhere (today) | B. Name alone in daily screens | +| --- | --- | --- | +| List, editor, Appearance | "英语(en)· 默认" | "English · 中文" as tabs; the main language first, unmarked | +| Settings → General → Languages | Name and code | Name and code, and "主要语言" on the main one | +| Two languages with one name (`zh`, `zh-TW`) | Told apart by code | The code is added to exactly those | +| A site with one language | The control is still drawn | No language control anywhere outside Settings | +| Contract | `ADMIN.md §4.3` as written | `§4.3` revised: one sentence | + +**Recommended: B.** The two languages stay apart by where they are chosen +(the interface language only in the account menu, the sign-in page and the +wizard), which was always the stronger of the four rules. + +### D9 — Showing the common case first in generated forms + +Forms for content types, theme options and plugin settings are generated +from manifests, so the admin cannot decide which inquiry setting is +advanced. The manifest has to say. + +| | A. Nothing | B. An optional `advanced: true` on a field | C. Decide in the admin, per plugin | +| --- | --- | --- | --- | +| Result | G15 stays | Fields so marked are drawn together, after the others, inside a closed "More options" block; a required field may not be marked | — | +| Contract | — | Additive to `theme.json` fields and options and to `plugin.json` settings; a manifest without it renders as today; validated at build time | **Not allowed**: themes and plugins ship no admin code, and the admin has none of theirs | + +**Recommended: B.** The inquiry plugin marks seven of its nine settings +(everything but the recipient and the autoreply switch), and its secret +moves into the same block. Atelier marks nothing; its problem is G14, +which is the next decision. + +### D10 — Two smaller questions + +**a. Theme options typed as syntax (G14).** Options allow six types +(`THEME_FORMAT.md §6`); a list of pairs has to be a string with `|` and +`;;`. Options: (A) leave it; (B) allow `string[]` and `keyvalue` in +options — both exist for content fields, with controls — and move +Atelier's three options to them, bumping its version and migrating stored +values in the theme's own reading code. **Recommended: B, as its own late +phase**, because it changes a theme contract and a released theme's +stored values, and needs the care that implies. + +**b. The interface language for a Chinese browser.** It already follows +the browser: `src/admin/i18n.ts` takes the stored choice, else the first +of `navigator.languages` it has a catalog for (`zh`, `zh-Hans-CN` and +`zh-TW` all find `zh-CN`), else English; after sign-in the account's +choice wins. **Nothing to build.** The open half is the reverse case the +last plan left with the owner: the wizard starts the site's *main content +language* as the interface language, so a Chinese-speaking owner setting +up an export site is offered Chinese as the site's main language. +**Recommended: start it as the first language the theme has a pack for +(English, for every official theme), whatever the interface language** — +which is also what `ADMIN.md §4.3` says in principle ("it never defaults +from a content language, nor they from it"). + +## 5. Constraints that do not move + +| Constraint | Source | What it means here | +| --- | --- | --- | +| `content.markdown` is the only truth; an item opened and closed is byte-identical | `CONTENT_FORMAT.md §3`, `ADMIN.md §6.2`, `13-editor-untouched.spec.ts` | D4 hides the front matter; it does not parse and rewrite it. D5's option A inserts text at the cursor and changes nothing else | +| Immediate and redeploy stay apart; installing is never a button | `PRODUCT_VISION.md §4`, `ADMIN.md §4.1`, `§10` | Plugins and Appearance keep their sentence, at the top, in plain words; the file paths move into a closed "For the person who deploys" block on the same page | +| Messages are honest | `ADMIN.md §5`, `§11` | The standing no-token notice stays on every page. Home's steps say "not set up yet", never "error". Unpublish and Delete say what a visitor will see | +| First load ≤ 170 KiB gzip | `ADMIN.md §13`, `pnpm admin:size` | **3.7 KiB of headroom** (166.3 measured). Home, the editor's new parts and the list's menu load with their pages. The shell gains links only. Each commit reports the number; the last plan lost 1.4 KiB to one shared import (`ADMIN_I18N_AND_UI.md §8`) | +| New dependencies go through the gate | `TECH_STACK.md §11` | Phases 1–7 add none. Phase 8 installs Tiptap in a throwaway branch only | +| Generated forms; no theme or plugin code in the admin | `ADMIN.md §7` | D9 and D10a change manifests, never add a per-plugin screen. Home lists panels generically | +| Infrastructure words only under Advanced | `ADMIN.md §2` | §6.5 lists every breach found and where it goes | +| No `COUNT(*)` in a list; list pages never read `markdown` | `CLAUDE.md`, `budget.test.ts` | Status tabs carry no counts. Search matches the title column only | +| Every SQL statement lives in `src/db` | `CLAUDE.md` | The search filter is a change there, with a worker test | +| Everything in the repository is English; `zh-CN` is a catalog | `CONVENTIONS.md` | New words are English in the source with `zh-CN` in the same commit; `pnpm i18n:check` fails otherwise | +| Browser tests find controls by English role and name | `test/e2e` | A renamed control changes its selector in the same commit, and the diff says why | +| No serious or critical axe violation, both languages | `05-accessibility.spec.ts` | Every new screen joins the scan | +| One change, one demonstrable path | `CLAUDE.md` | §7's commits | + +## 6. The direction + +### 6.1 Principles + +1. **The task, not the table.** A screen is named and shaped by what the + operator does there — Products, Inquiries, Write — not by what stores + it. +2. **The common case first; the rest one step away.** Nothing is removed. + What a daily operator does not need is closed, in a menu, or under + Advanced, and each has one fixed place (§6.5). +3. **Plain words in both languages.** If a word needs a developer to + explain it, it is replaced, or it moves to Advanced. +4. **One left edge.** Every page starts at the same place. +5. **A button says what it will do to this item.** +6. **Honesty is not negotiable and is not jargon.** A degraded state is + said in the operator's words where they are, with the technical reason + one link away. +7. **Familiar beats clever.** Where WordPress and Shopify agree, do that. + +### 6.2 Information architecture + +``` +[M] Titanium demo View site ↗ +───────────────────────────────────── +Home 概览 +Inquiries 询盘 ← each plugin list panel +───────────────────────────────────── +CONTENT 内容 + Pages 页面 ← one per type the + Products 产品 theme declares, + Product families 产品系列 by its label + Case studies 案例 + FAQ 常见问题 + News 文章 + Media 媒体 +───────────────────────────────────── +SETTINGS 设置 + General 基本设置 ← was "Site" + Appearance 外观 + Email 邮箱 + Plugins 插件 ← was beside Content + Advanced 高级 ← gains API tokens +───────────────────────────────────── +e2e@example.test ▾ Account · Colour scheme · + Interface language · Sign out +``` + +Changes to `ADMIN.md §4`: a Home section is added; Content is one group +with an entry per type; Plugins is listed under Settings; API tokens move +from Account to Advanced. The breadcrumb names the place only ("Inquiries", +"Products › Grade 5 titanium bar"); a panel's page drops "From the Inquiry +plugin" to a "Settings" link in its header. + +### 6.3 Key screens + +**Home** (D1). 68 rem. + +``` +Good morning [ Add ▾ ] + Product · News · Page +┌ Finish setting up ──────────────────────────────── 2 of 4 done ┐ +│ ○ Say where inquiries are sent Without this, no email │ +│ reaches you. [Set] │ +│ ○ Connect your domain Visitors still see a │ +│ preview address. [How] │ +│ ● Email sending is set up │ +│ ● Your first page is edited │ +└────────────────────────────────────────────────────────────────┘ +┌ New inquiries ───────────────────────────────── [All inquiries]┐ +│ Li Wei · Acme Metals · Germany Today 09:14 New │ +│ "We need 500 kg of Grade 5 bar, 40 mm, delivered to…" │ +│ … │ +│ (empty: "No inquiries yet. They appear here when a visitor │ +│ sends the form on your contact page.") │ +└────────────────────────────────────────────────────────────────┘ +┌ Recently edited ───────────────────────────────────────────────┐ +│ Grade 5 titanium bar Product Published Today 07:12 │ +│ Why titanium lead times… News Draft Yesterday │ +└────────────────────────────────────────────────────────────────┘ +``` + +The inquiries card is generic: for each enabled plugin, each of its `table` +panels that is not attached to a content type shows its five newest rows, +by the panel's own columns. A `records` panel (a catalogue, not an inbox) +is not shown. No count is drawn. + +**A content list** (D2, D3, D7). 90 rem, left-aligned. + +``` +Products [ Add product ] + + All Published Drafts Scheduled [ Search products… ] + English 中文 ← only with 2+ languages +┌──────────────────────────────────────────────────────────────────┐ +│ Title Status Last edited │ +├──────────────────────────────────────────────────────────────────┤ +│ Grade 9 titanium tube Published Today 07:12 ⋯ │ +│ Grade 2 titanium plate Published Yesterday ⋯ │ +│ Grade 5 titanium bar Draft 12 Nov ⋯ │ +└──────────────────────────────────────────────────────────────────┘ + ‹ Previous Next › + + ⋯ → Edit · View on site · Copy address · Unpublish · Delete + 390 px: title; status and date beneath it; ⋯ at the row's end. +``` + +No Type column inside a type's list; "Other content" keeps it. Status tabs +replace the Status select and carry no counts. The whole row opens the +editor. Search is by title, within the type and language shown. + +**The editor** (D4, D5, D6). + +``` +← Products Published · Saved 07:12 Preview ⋯ [ Update ] +────────────────────────────────────────────────────────────────────────── + English 中文 + Add a language version ┌ Page settings ┐ + │ Status │ + Grade 5 titanium bar ← the title, │ Published │ + ══════════════════════════════════ large │ 12 Nov 2026 ✎ │ + │ │ + H2 H3 B I • — 1. " Link Image Table │ Summary │ + ────────────────────────────────────────────── │ [ Ti-6Al-4V…] │ + Grade 5 accounts for roughly half of all titanium │ Shown in │ + in use. It holds its strength to 400 °C and │ lists and in │ + machines predictably… │ search results│ + │ │ + ## Delivery condition ← styled as a │ Cover image │ + Bar is supplied annealed unless… heading │ [ Choose… ] │ + │ Tags │ + ┌ Specification ───────────────────────────────┐ │ [ aerospace ×]│ + │ Grade [Ti-6Al-4V ] Standard [ASTM B348 ] │ │ │ + │ Form [Bar ▾] │ │ ▸ Search and │ + └──────────────────────────────────────────────┘ │ address │ + ┌ Properties ─────────────────────────────────┐ │ example.com/ │ + │ Density 4.43 g/cm³ Remove │ │ products/ │ + │ Tensile strength 895 MPa Remove │ │ [grade-5-…] │ + │ [ Add a row ] │ └────────────────┘ + └──────────────────────────────────────────────┘ + ┌ Gallery ─────────┐ ┌ Trade ──────────────────┐ + └──────────────────┘ └─────────────────────────┘ + + ⋯ → View on site · Edit source (Markdown) · Unpublish · Delete + Preview → swaps the panel for the page as visitors get it; both at ≥ 1600 px. + 390 px: title, toolbar, body, cards in one column; the panel is a sheet + behind "Settings"; a bar pinned to the bottom holds Preview and + the primary button. The top bar is one line: ← · status · ⋯. +``` + +The cards are the theme's `group`s, as declared; ungrouped fields form one +card named after the type. A new item's type comes from the list it was +opened from, so the Type select is gone from the bar (it stays, enabled +only before the first save, in the panel under "Search and address" for an +item opened from "Other content"). "N images missing" and "Unsaved" stay +beside the status. + +**Settings → General** (D8, D9, G16). 56 rem. + +``` +General +┌ Your site ─────────────────────────────────────────┐ +│ Site name [ Titanium demo ] │ +│ Tagline [ Titanium bar, plate and tube for… ] │ +│ English 中文 ← only with 2+ │ +│ [ Save ] │ +└────────────────────────────────────────────────────┘ +┌ Languages ─────────────────── Changes apply at once ┐ +│ English (en) Main language │ +│ 中文 (zh) [ Make main ] [ Remove ] │ +│ [ Add a language ▾ ] │ +└─────────────────────────────────────────────────────┘ +┌ Domain ─────────────────────────────────────────────┐ +│ Not connected yet. Visitors see a preview address, │ +│ search engines are asked not to list the site, and │ +│ pages load more slowly. How to connect ↗ │ +│ Your domain [ www.example.com ] │ +│ [ Save ] │ +│ ▸ More options │ +│ Address for images · Put the main language's │ +│ pages under /en/ too │ +└─────────────────────────────────────────────────────┘ +``` + +**Inquiries** (G20). 90 rem. Still drawn from the manifest. + +``` +Inquiries [ Settings ] [ Export ] + + New Replied Spam All [ Search… ] +┌──────────────────────────────────────────────────────────────────┐ +│ □ From Message Received │ +├──────────────────────────────────────────────────────────────────┤ +│ □ Li Wei · Acme Metals We need 500 kg of Grade 5… 09:14 New │ +│ □ J. Okafor Do you supply seamless… Yesterday │ +└──────────────────────────────────────────────────────────────────┘ + With rows selected: [ Mark replied ] [ Mark spam ] + + Opening a row: the whole message, company, phone, country, the page it + was sent from, and [ Reply by email ] (a mailto: link) · [ Mark replied ]. + Empty: "No inquiries yet. They appear here when a visitor sends the form + on your contact page." — and, while the recipient is empty, the same + step Home shows. +``` + +Three generic rules produce this from the manifest, none special to the +plugin: a filter on a field whose values the catalog names, with four +values or fewer, is drawn as tabs; bulk actions appear when a row is +selected instead of standing disabled; a detail field of type `email` +offers a mailto link. The inquiry plugin's own manifest changes its +columns to put the message in the row and gives its panel an empty +sentence through its catalog (a new optional key, `panels..empty`). + +### 6.4 Vocabulary + +| Today (English / zh-CN) | Proposed English | Proposed zh-CN | Where | +| --- | --- | --- | --- | +| Slug / Slug | Web address (the field); its editable part: "URL slug" | 网址;可编辑部分:URL 别名 | Editor panel | +| Path / 路径 | — (column removed); "Copy address" | 复制网址 | Lists | +| Content / 内容 (one list) | The type's label: Products, News… | 产品、文章… | Sidebar, list titles | +| New content / 新建内容 | Add product, Add page… | 添加产品、添加页面… | Lists, Home | +| Type / 类型 | Content type | 内容类型 | Only in "Other content" | +| Site / 站点 (group) | Content | 内容 | Sidebar group | +| Site / 站点 (settings) | General | 基本设置 | Sidebar, page title | +| — | Home | 概览 | Sidebar; not 首页, which is the site's home page | +| English (en), default / 英语(en)· 默认 | English; "Main language" in Settings | 英语;主要语言 | D8 | +| Content language / 内容语言 | Language (as tabs, no label) | — | Lists, editor | +| Create Chinese (zh) / 创建 中文(zh) | Add a language version | 添加语言版本 | Editor | +| Description — "Used as the meta description…" / 描述 | Summary — "Shown in lists and in search results. Empty uses the start of the text." | 摘要——显示在列表和搜索结果中。留空则取正文开头。 | Editor panel | +| Markdown (pane name) | Text | 正文 | Editor | +| Fields / 字段, Hide fields / 收起字段 | Page settings; Hide settings | 页面设置;收起设置 | Editor | +| Save draft · Publish (on a live item) | Update | 更新 | D6 | +| — | Unpublish; Delete | 取消发布;删除 | Editor and row menus | +| Updated / 更新时间 | Last edited | 最后编辑 | Lists | +| Custom domain / 自定义域名 | Your domain | 网站域名 | General | +| Media domain / 媒体域名 | Address for images | 图片地址 | General → More options | +| "Files are stored by the hash…" | "Photos and files used on your site." | 网站上用到的图片和文件。 | Media | +| "Plugins ship with the source…" | "Plugins are added by whoever deploys the site. Here you switch them on and set them up." | 插件由部署站点的人添加。在这里可以启用并设置它们。 | Plugins | +| Technical details / 技术细节 | For the person who deploys | 部署相关信息 | Plugins, Appearance | +| Account and API tokens / 账号与 API 令牌 | Account | 账号 | Account menu | +| "About password hashing: PBKDF2-SHA256…" | "Use a long password you use nowhere else. This site's hosting limits how strongly passwords can be protected." + "Details" | 请使用足够长、且不在别处使用的密码。受托管环境限制,本站对密码的保护强度有限。+“详细说明” | Account | +| "Nothing here yet." on Inquiries | The panel's own sentence (§6.3) | 还没有收到询盘。访客在联系页提交表单后,会显示在这里。 | Inquiries | + +Unchanged on purpose: 发布, 草稿, 定时发布, 询盘, 媒体, 外观, 邮箱, 插件, +高级, and every term in the glossary agreed on 2026-11-13. "Markdown" +remains a name the admin may say — in "Edit source (Markdown)", in +Advanced's backup card — because it is the format the operator's content +leaves in. + +### 6.5 What moves, and where to + +| Today, in plain view | Goes to | +| --- | --- | +| Front matter in the body editor | "More" → "Edit source (Markdown)" | +| Slug in the editor bar; Path column | Panel → "Search and address"; row menu → "Copy address" | +| Type select in the editor bar | Fixed by the list; in the panel only for "Other content" | +| Language codes | Settings → General → Languages | +| "Prefix the default language too", `//` | General → Domain → "More options" | +| Media domain | The same block | +| "Converted to WebP… 480, 960 and 1440… SVG" | Shown when a file is refused, as the reason; the sizes are in Advanced → Diagnostics | +| "Stored by the hash of the original" | Removed from the page; `ADMIN.md §8` keeps it | +| `src/plugins/`, `src/plugins/index.ts`, `ACTIVE_THEME`, `src/themes/index.ts` | "For the person who deploys", closed, on Plugins and Appearance. The sentence that a change needs a redeploy stays above it, open | +| Theme facts: client JavaScript, asset path, script list | The same closed block on Appearance; "This theme adds 1 script to the home page" stays open, in words | +| Inquiry: Turnstile keys, autoreply templates, blocked countries and keywords, thank-you path, own sender | "More options" on the plugin's card (D9) | +| PBKDF2 iterations and the CPU budget | "Details" under the password form. The plain warning stays open: `ADMIN.md §12` requires it to be said | +| API tokens and their scopes | Advanced → "API tokens" | +| "No rebuild, no deploy" ledes on Site, Appearance, Email | Removed. Advanced's "What applies immediately, what needs a deployment" card is the one place, as `ADMIN.md §11` asks | + +## 7. Phases + +Sizes are estimates: S under a day, M a few days, L a week or more. Each +numbered item is one commit and one thing the owner can see. The gate of +every commit is §8's; what is listed under a phase is added to it. + +### Phase 0 — Decisions and baseline (S) + +1. Record the owner's decisions in this file's status block. +2. Re-check what a decision turns on: the delete route's effects (D6); + whether a panel's `email` detail already renders a link. +3. Capture the baseline again from `main` without the draft, adding the + sign-in page, a seeded inbox and a seeded media library, in both + languages — the gaps of §2.1. + +**Gate:** decisions recorded; baseline images with the owner. + +### Phase 1 — One left edge (S), D7 + +1. The shell's column is left-aligned; pages declare `form`, `list`, `home` + or `full`. The uncommitted draft is dropped in favour of this. + +**Gate:** images at 1280, 1440, 1920 and 2560 px, sidebar open and closed, +and at 390 px, for a list, a form and the editor; `17-shell` passes. + +### Phase 2 — Words (S), §6.4 + +1. The catalog changes of §6.4 that need no layout change: the Slug label, + Summary, the Media and Plugins sentences, the account menu, the ledes. +2. The sidebar's group and "General"; the breadcrumb. + +**Gate:** images in both languages; every selector that changed is listed +in the commit; `pnpm i18n:check`. + +### Phase 3 — Lists like the ones people know (M), D2, D3 + +1. A sidebar entry per content type; the list takes its type from the + address; "Other content" when needed. +2. The Path column goes; a row menu brings Edit, View on site and Copy + address; "Last edited" is relative for the last seven days. +3. Status as tabs; the language as tabs, hidden with one language (D8). +4. Search by title: the `q` parameter in `src/db` and the Worker, with a + worker test and a query-count check; the box in the list. + +**Gate:** `03-publish`, `19-translation` and a new list spec pass; +`budget.test.ts` unchanged; images at both widths. + +### Phase 4 — The editor (L), D4, D5 option A, D6 + +Ordered so that each commit is safe to stop after. + +1. **Update, Unpublish, Delete** (D6), in the editor as it stands, and + Unpublish and Delete in the list's row menu. +2. Publish date, cover image and tags as always-present fields (G4). +3. Writing-first layout: the title, the body, the type's cards; the panel; + Preview as a toggle. The source pane shows the body only; "Edit source + (Markdown)" opens the whole document. +4. The body's look: proportional face, no line numbers, headings and + emphasis styled. +5. The toolbar: heading, bold, italic, lists, quote, link, table. +6. Images in the body: the toolbar's button opens the media picker and + inserts the reference; then drop and paste upload. +7. The 390 px layout. + +**Gate:** `13-editor-untouched` passes unchanged at every step — it is the +proof for D4; `21-editor-layout` is rewritten for the new layout with axe +at both widths; a new spec takes a published item through Update, +Unpublish and Delete and reads each confirmation; the editor chunk's size +is reported before and after; images to the owner after steps 1, 3 and 6. + +### Phase 5 — Home (M), D1 + +1. The page with "Recently edited" and the Add menu; sign-in and the + wizard's result land on it. +2. "Finish setting up", from the four derived conditions. +3. The newest rows of each table panel. + +**Gate:** a spec on a fresh database sees four steps, sets the recipient +and sees three; axe in both languages; first load reported — the page must +not be in it. + +### Phase 6 — Settings, plugins, account (M), D9 + +1. `advanced` in the three manifests' schemas, its build-time validation + and the "More options" block in the form generator; `THEME_FORMAT.md` + and `PLUGIN_API.md` revised in the same commit. +2. The inquiry plugin marks its fields; its `zh-CN` catalog follows. +3. General: the three cards of §6.3. +4. Plugins and Appearance: the plain sentence and the closed block. +5. Account: the plain password note with "Details"; tokens move to + Advanced. + +**Gate:** a core test for a manifest with and without the key, and for a +required field wrongly marked; `06-tokens`, `08-email-settings`, +`16-appearance`, `18-locale-prefix` pass with their selector changes +listed; images of each page, both languages, both widths. + +### Phase 7 — Inquiries (S–M) + +1. The three generic panel rules of §6.3: tabs for a small named filter, + bulk actions on selection, a mailto link on an `email` field. +2. The inquiry manifest: the message in the row; `panels..empty` in + plugin catalogs, documented in `PLUGIN_API.md §7.8`. + +**Gate:** `10-records-panel` and `14-failed-jobs` pass; images of a seeded +inbox and an empty one. + +### Phase 8 — Spike: what a visual editor would cost (S), D5 + +Throwaway branch; only §9's numbers merge. Tiptap with its Markdown +extension, fed the starter's pages and a sample of the owner's real +articles: how many come back byte-identical, how the rest differ, the +chunk's gzip size in this build, and whether raw HTML and tables survive. + +**Gate:** the numbers, and the owner's decision on 0.2's editor. + +### Phase 9 — Theme options as lists (M), D10a, and close (S) + +1. `string[]` and `keyvalue` as option types; Atelier's three options + move, with its version bumped and `pnpm themes:record` run. +2. `ADMIN.md` revised (§4, §4.3, §6.1, §10, §12 and a new Home section); + the CHANGELOG; `docs/zh-CN/`; the index entry in `docs/README.md`. + +**Gate:** a site saved with the old option strings renders the same home +page after the change, shown by a test; the six checks of §8. + +## 8. Verification + +- **Every commit:** `pnpm lint && pnpm typecheck && pnpm test && pnpm build + && pnpm bundle:size && pnpm admin:size`, then `pnpm test:e2e`. The + first-load figure goes in the commit message. +- **The content contract:** `13-editor-untouched` unchanged throughout + phase 4; a new test saves an item after editing only the body and + asserts the front-matter block's bytes did not change, and another after + editing one field asserts every undeclared field is still there. +- **Honesty:** specs read the Unpublish and Delete confirmations, the + no-token notice on Home, and a draft's save, which must not claim + visitors see it. +- **Both languages:** `05-accessibility` gains Home, a type's list and the + new editor, in English and Chinese; `pnpm i18n:check` in lint. +- **Budgets:** `budget.test.ts` unchanged; the search query has its own + count check. +- **The owner's eye:** before-and-after images per phase, in Chinese, at + 1440 px and 390 px, plus the widths of phase 1. No visual-regression + tooling is added. +- **The real test, once:** after phase 5, someone who has not seen the + admin adds a product with two photos, publishes it, fixes a typo in it + and answers an inquiry, with no help. Where they stop is the next list + of findings. This is the owner's to arrange. + +## 9. Measurements + +To be filled as phases run. At proposal time: + +| What | Value | How | +| --- | ---: | --- | +| First load | 166.3 KiB gzip of 170 | `node scripts/admin-size.mjs`, build of 2026-11-19 07:13, draft applied | +| Loaded on demand | 478.6 KiB gzip | The same run | +| Interface messages | 543, both languages | `grep -c '^msgid'` on `zh-CN.po` gives 544 with the header | +| Browser specs | 22 files (`00`–`21`) | `ls test/e2e` | +| Tiptap's size and fidelity here | **Not measured** | Phase 8 | +| Benchmarks in §3 | **Not measured**; from knowledge | — | + +## 10. Risks and open questions + +| Risk | Why it is real | What contains it | +| --- | --- | --- | +| Hiding the front matter breaks "byte-identical" | Splitting and rejoining a document is exactly where a newline goes missing | The block is carried as its original text; `13-editor-untouched` and two new tests gate every editor commit | +| The first load passes 170 KiB | 3.7 KiB left; the shell changes in phases 2, 3 and 5; one shared import cost 1.4 KiB last time | New screens are lazy pages; the figure is in every commit; a phase that cannot fit stops and reports rather than raising the budget | +| Browser tests are rewritten to fit | Phases 2–4 rename the controls the suite finds | One rename per commit, the selector's diff saying why; behaviour specs are not edited in a wording commit | +| "Simple" hides something an operator needs | Each closed block is a guess about what is rare | Nothing is removed, each thing has one place (§6.5), and the unaided test of §8 is the check | +| Delete loses data | There is no trash and no revision interface (`ADMIN.md §14`) | A confirmation that names what goes; Unpublish offered first in the same menu; Advanced's backup is unchanged. A trash is an open question | +| A long sidebar | A theme may declare many types | Six today. If a theme passes about eight, the group collapses; not built until one does | +| The toolbar raises expectations Markdown cannot meet | A toolbar looks like a word processor; the text still shows `**` | Styling in phase 4 step 4 softens it; D5's spike decides the rest | +| Chinese wording reads translated | §6.4's zh-CN is a proposal by a non-native process | The owner reviews each phase's images, as in the last plan; the glossary is extended as terms are agreed | +| Manifest additions fragment | `advanced`, `panels..empty`, two option types | All optional and additive under theme API 1 and plugin API 2; each documented in the commit that adds it | + +Conflicts between documents and code, found on the way and **not resolved +by this plan**: + +1. `ADMIN.md §4` lists a Navigation editor under Settings, and Advanced + tells the operator navigation changes at once. The admin has no screen + for it. For a non-technical operator the site's menu is a real need; + it is a feature, so it is outside this plan, and it is the first thing + to plan after it. +2. `ADMIN.md §7` says a `reference` field "opens the content picker"; the + control is a text input for the slug with a "Choose…" button only where + a picker is passed, and `reference[]` "has no control yet" + (`form/form.tsx`). Atelier's own help text reads "Slug of the category + this product belongs to." +3. `ADMIN.md §8` says the media library lists "unused media" separately; + the page marks each item "unused" in place. +4. The owner's choice of "URL 别名" for Slug (2026-11-19) is not in + `zh-CN.po`. + +Open questions: + +1. Should deleted content go to a trash for some days? It needs a column + or a status and a cron step, so it is a data-model question. +2. Should the sidebar show how many inquiries are new? It needs a count + the panel API does not give, and a rule that keeps it cheap. +3. Should a product row show a thumbnail? The list API returns no cover, + and list pages must stay within their query budget. +4. Does the reference field get a real picker in this plan (conflict 2)? + It would join phase 4. +5. Home's greeting and the order of its cards are taste; the proposed + order puts what blocks inquiries first. +6. Should "Edit source" be hidden entirely for an account that has never + used it, or always sit in the menu? Proposed: always there. +7. D10b changes what the wizard preselects. Is English the right start for + every site, or should the wizard ask without preselecting? + +## 11. Not in this plan + +- A visual editor; phase 8 only measures one. +- A navigation editor, revision history, a trash, bulk editing, multiple + users or roles. +- Visit statistics or any dashboard figure that needs counting. +- In-place editing of the public site, as Wix and Squarespace do. +- Installing or switching themes or plugins from the admin. +- Changes to the admin's colours, type or decoration beyond what the + layouts above need. +- A third interface language; Windows and Linux screenshots, still owed + from the last plan. diff --git a/docs/README.md b/docs/README.md index 1e95b45..4a339da 100644 --- a/docs/README.md +++ b/docs/README.md @@ -37,6 +37,7 @@ rest are the contracts for individual subsystems. | [CLI.md](CLI.md) | Commands, arguments, authentication, idempotence rules, exit codes, error-message rules | | [SEO_PERFORMANCE.md](SEO_PERFORMANCE.md) | The SEO output built into the core, hreflang, structured data, the performance budget and how it is measured | | [ADMIN_I18N_AND_UI.md](ADMIN_I18N_AND_UI.md) | Proposal: a selectable interface language for the admin and the setup wizard (English and Simplified Chinese first), the measured cost of the candidate libraries, how theme, plugin and Worker strings are covered, and a page-by-page review of the admin's interface with the decisions left to the owner | +| [ADMIN_SIMPLE.md](ADMIN_SIMPLE.md) | Plan: an admin that reads like a mainstream CMS for a non-technical operator — the findings ranked, how WordPress, Shopify and Ghost handle the same screens, the target layout and vocabulary, the owner's ten decisions and the phases | | [SECURITY.md](SECURITY.md) | Trust levels, credential handling and the encryption format, authentication, sanitisation, upload validation, error hygiene, and **what is deliberately not defended against** | ## Process documents From 43b4e1da3e1033f3e716f5e9a15c808ef2225f2e Mon Sep 17 00:00:00 2001 From: JasonYv <233965174+JasonYv@users.noreply.github.com> Date: Thu, 19 Nov 2026 08:40:49 -0800 Subject: [PATCH 04/14] feat(admin): start every page beside the sidebar, capped by its kind The shell centred a 68 rem column, so a wide window left a band of empty space beside the sidebar, and any page wider than the rest moved its left edge (docs/ADMIN_SIMPLE.md, D7). The column now starts beside the sidebar on every page, and the page says how far it reaches: a form 56 rem, a list (content, media, a plugin panel) 90 rem, home 68 rem, and the editor the whole window. What is left over is on the right. 17-shell checks that a form and a list share one left edge beside the sidebar at 1920 px and that a list reaches further; 21-editor-layout's comment names the new cap. admin:size 166.3 KiB first load. Co-Authored-By: Claude Opus 5.5 --- src/admin/app.tsx | 6 +++--- src/admin/components/page.tsx | 16 +++++++++++----- src/admin/components/shell.tsx | 8 ++++---- src/admin/pages/content-list.tsx | 2 +- src/admin/pages/media.tsx | 2 +- src/admin/pages/plugin-panel.tsx | 6 +++--- test/e2e/17-shell.spec.ts | 32 +++++++++++++++++++++++++++++++ test/e2e/21-editor-layout.spec.ts | 3 ++- 8 files changed, 57 insertions(+), 18 deletions(-) diff --git a/src/admin/app.tsx b/src/admin/app.tsx index 65ae1ed..3a57f27 100644 --- a/src/admin/app.tsx +++ b/src/admin/app.tsx @@ -68,7 +68,7 @@ function page(load: () => Promise): JSX.Element { */ function PageLoading(): JSX.Element { return ( -
+
Loading…
@@ -248,7 +248,7 @@ function Booting(): JSX.Element { function NotFound(): JSX.Element { return (
- +

@@ -283,7 +283,7 @@ function RouteError(): JSX.Element { ? error.message : ''; return ( -
+

This part of the admin could not be loaded. Check your connection and reload. diff --git a/src/admin/components/page.tsx b/src/admin/components/page.tsx index 6eb7eb3..05d4f17 100644 --- a/src/admin/components/page.tsx +++ b/src/admin/components/page.tsx @@ -26,18 +26,24 @@ import { * and one width (docs/ADMIN_I18N_AND_UI.md, U2); a form caps its own fields * instead (`Section`). * - * The page, not the shell, says how wide that column is: `width="full"` - * lets the shell's column span the window, for a page such as the editor - * that needs the room (U7). + * The column starts beside the sidebar on every page and at every width; + * what is left over is on the right, where a page ends + * (docs/ADMIN_SIMPLE.md, D7). The page, not the shell, says how far it + * reaches: a `form` stops at 56 rem, a `list` — a table or a grid — at + * 90 rem so a row stays readable end to end, `home` at 68 rem, and `full`, + * the editor, takes the window. */ +/** How far a page's column reaches (D7). */ +export type PageWidth = 'form' | 'list' | 'home' | 'full'; + export function Page({ children, className, - width = 'column', + width = 'form', }: { readonly children: ReactNode; readonly className?: string; - readonly width?: 'column' | 'full'; + readonly width?: PageWidth; }): JSX.Element { return (

{/* The notice inside the column, not across the window: it, the - page header and the page share one left edge (U2). A page that - asks for the full width (`Page width="full"`) widens the whole - column, the notice with it, so the edge stays shared. */} -
+ page header and the page share one left edge (U2). The column + starts beside the sidebar, never centred, and the page says how + far it reaches (`Page width`, D7), the notice with it. */} +
{children}
diff --git a/src/admin/pages/content-list.tsx b/src/admin/pages/content-list.tsx index 4d20d5f..3e9ac0b 100644 --- a/src/admin/pages/content-list.tsx +++ b/src/admin/pages/content-list.tsx @@ -129,7 +129,7 @@ export function ContentListPage(): JSX.Element { const language = nameOf(locale); return ( - + + +

Loading…

@@ -41,7 +41,7 @@ export function PluginPanelPage(): JSX.Element { } if (plugin === undefined || panel === undefined) { return ( - + No plugin in this build has a list at this address. @@ -52,7 +52,7 @@ export function PluginPanelPage(): JSX.Element { const pluginName = plugin.name; return ( - + { + // A centred column left a band beside the sidebar on a wide window, and + // moved the page's left edge from one page to the next + // (docs/ADMIN_SIMPLE.md, D7). + await page.setViewportSize({ width: 1920, height: 900 }); + await signIn(page); + const edges: Record = {}; + for (const [name, path] of [ + ['form', '/_mallok/app/settings'], + ['list', '/_mallok/app/media'], + ] as const) { + await page.goto(path); + const heading = page.getByRole('heading', { level: 1 }).first(); + await heading.waitFor(); + const column = page.locator('[data-page-width]').first(); + const box = await column.boundingBox(); + edges[name] = { left: box?.x ?? -1, width: box?.width ?? -1 }; + } + const sidebar = await page + .locator('[data-slot="sidebar-container"]') + .first() + .boundingBox(); + expect(edges.form?.left).toBe(edges.list?.left); + // Beside the sidebar: its width plus the column's padding, nothing more. + expect((edges.form?.left ?? 0) - (sidebar?.width ?? 0)).toBeLessThan(48); + // A form stops at 56 rem, a list at 90; neither spans a 1920 px window. + expect(edges.form?.width).toBeLessThan(edges.list?.width ?? 0); + expect(edges.list?.width).toBeLessThanOrEqual(1440); +}); diff --git a/test/e2e/21-editor-layout.spec.ts b/test/e2e/21-editor-layout.spec.ts index 7028e3b..33cc6c3 100644 --- a/test/e2e/21-editor-layout.spec.ts +++ b/test/e2e/21-editor-layout.spec.ts @@ -44,7 +44,8 @@ test('on a wide screen the editor fills the window and its fields fold', async ( await signIn(page); await openPublished(page); - // Wider than the 68 rem column every other page keeps (U7). + // Wider than any other page's column, which stops at 90 rem at most + // (U7, docs/ADMIN_SIMPLE.md D7). const panes = page.getByRole('region', { name: 'Fields, Markdown and preview', }); From 970351a9d5c4d0fbedfcb5eca4b324b8aa604c8d Mon Sep 17 00:00:00 2001 From: JasonYv <233965174+JasonYv@users.noreply.github.com> Date: Thu, 19 Nov 2026 08:43:00 -0800 Subject: [PATCH 05/14] feat(admin): say what things are for, and leave the plumbing out MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The words of docs/ADMIN_SIMPLE.md §6.4 that need no new layout: - The editor's "Slug" is "URL slug" (URL 别名) and "Description" is "Summary", with help that says where it shows. - Media introduces itself as the photos and files used on the site; the hash and the WebP widths are gone from the page, and a refused file still says why. - Site, Appearance and Email lose their "no rebuild, no deploy" ledes: Advanced is the one place that says what applies at once. Email says what Resend is and where its key comes from. - Settings → Site is "General"; its domains are "Your domain" and "Address for images". - The account menu's entry is "Account"; a plugin's "Technical details" are "For the person who deploys". - A plugin panel's breadcrumb is its own name, not "Plugins › …". Selectors changed for the renamed controls only: 03-publish and 19-translation find "URL slug", 17-shell "General" and "Account". admin:size reported in the phase's gate. Co-Authored-By: Claude Opus 5.5 --- src/admin/components/account-menu.tsx | 2 +- src/admin/components/media-library.tsx | 17 ------ src/admin/components/shell.tsx | 8 +-- src/admin/locales/en.po | 79 ++++++++++++------------- src/admin/locales/zh-CN.po | 79 ++++++++++++------------- src/admin/pages/editor.tsx | 6 +- src/admin/pages/media.tsx | 2 +- src/admin/pages/plugins.tsx | 2 +- src/admin/pages/settings-appearance.tsx | 2 +- src/admin/pages/settings-email.tsx | 2 +- src/admin/pages/settings-site.tsx | 11 ++-- test/e2e/03-publish.spec.ts | 6 +- test/e2e/17-shell.spec.ts | 4 +- test/e2e/19-translation.spec.ts | 4 +- 14 files changed, 97 insertions(+), 127 deletions(-) diff --git a/src/admin/components/account-menu.tsx b/src/admin/components/account-menu.tsx index 9bd63b0..59628d5 100644 --- a/src/admin/components/account-menu.tsx +++ b/src/admin/components/account-menu.tsx @@ -66,7 +66,7 @@ export function AccountMenu({ navigate('/account')}> - Account and API tokens + Account diff --git a/src/admin/components/media-library.tsx b/src/admin/components/media-library.tsx index 005f363..2d43638 100644 --- a/src/admin/components/media-library.tsx +++ b/src/admin/components/media-library.tsx @@ -23,7 +23,6 @@ import { } from '@/components/ui/dialog'; import { Input } from '@/components/ui/input'; import { ApiError, api } from '../api.js'; -import { formatNumber } from '../format.js'; import { relativePathFor, type UploadProgress, uploadFile } from '../media.js'; import { messageOf, notify } from '../notice.js'; import { keys, useSettings, useTheme } from '../queries.js'; @@ -58,16 +57,6 @@ export function MediaLibrary(props: MediaLibraryProps): JSX.Element { const active = useTheme(); const site = useSettings(); const client = useQueryClient(); - // A conjunction list, not a `unit` one: Chinese joins a unit list with no - // separator at all, so 480, 960 and 1440 read as "4809601440". Pixel widths - // are not grouped, like the numbers in a srcset. - const widths = new Intl.ListFormat(i18n.locale, { - type: 'conjunction', - }).format( - active.imageWidths.map((width) => - formatNumber(width, { useGrouping: false }), - ), - ); const listed = useQuery({ queryKey: [...keys.media, 'list', props.kind ?? 'all'], @@ -187,12 +176,6 @@ export function MediaLibrary(props: MediaLibraryProps): JSX.Element { )} -

- - Images are converted to WebP in your browser and uploaded at{' '} - {widths} pixels wide. SVG is not accepted — it can carry script. - -

{progress === null ? null : (

{progress.file}: {i18n._(STAGES[progress.stage])} diff --git a/src/admin/components/shell.tsx b/src/admin/components/shell.tsx index ae2229c..0123a57 100644 --- a/src/admin/components/shell.tsx +++ b/src/admin/components/shell.tsx @@ -97,7 +97,7 @@ const SITE: readonly NavItem[] = [ const SETTINGS: readonly NavItem[] = [ { - label: msg`Site`, + label: msg`General`, href: '/settings', icon: Settings2, active: (path) => path === '/settings', @@ -275,10 +275,8 @@ function crumbsFor( .find((plugin) => plugin.id === pluginId) ?.panels.find((entry) => entry.id === panelId); if (panel !== undefined) { - return [ - { label: msg`Plugins`, href: '/plugins' }, - { label: panel.label }, - ]; + // Named by what it is, not by how it is built (ADMIN_SIMPLE.md, G13). + return [{ label: panel.label }]; } } return [{ label: msg`Not found` }]; diff --git a/src/admin/locales/en.po b/src/admin/locales/en.po index c17f40a..df1646b 100644 --- a/src/admin/locales/en.po +++ b/src/admin/locales/en.po @@ -249,10 +249,6 @@ msgstr "About password hashing" msgid "Account" msgstr "Account" -#: src/admin/components/account-menu.tsx -msgid "Account and API tokens" -msgstr "Account and API tokens" - #. js-lingui-explicit-id #: src/admin/server-messages.catalog.ts msgid "server.auth.session_required" @@ -300,6 +296,10 @@ msgstr "Add row" msgid "Add the first one" msgstr "Add the first one" +#: src/admin/pages/settings-site.tsx +msgid "Address for images" +msgstr "Address for images" + #: src/admin/pages/setup.tsx msgid "Administrator" msgstr "Administrator" @@ -739,7 +739,6 @@ msgid "Current password" msgstr "Current password" #: src/admin/pages/settings-advanced.tsx -#: src/admin/pages/settings-site.tsx msgid "Custom domain" msgstr "Custom domain" @@ -783,10 +782,6 @@ msgstr "derived from the title" msgid "Describe the image" msgstr "Describe the image" -#: src/admin/pages/editor.tsx -msgid "Description" -msgstr "Description" - #: src/admin/components/plugin-panel.tsx msgid "Details" msgstr "Details" @@ -903,10 +898,6 @@ msgstr "Fields" msgid "Fields, Markdown and preview" msgstr "Fields, Markdown and preview" -#: src/admin/pages/media.tsx -msgid "Files are stored by the hash of the original, so uploading the same image twice costs nothing and never creates a duplicate." -msgstr "Files are stored by the hash of the original, so uploading the same image twice costs nothing and never creates a duplicate." - #: src/admin/pages/setup.tsx msgid "Finish setup" msgstr "Finish setup" @@ -915,6 +906,10 @@ msgstr "Finish setup" msgid "For a language not listed, comma separated. Languages can also be added later." msgstr "For a language not listed, comma separated. Languages can also be added later." +#: src/admin/pages/plugins.tsx +msgid "For the person who deploys" +msgstr "For the person who deploys" + #: src/admin/pages/settings-email.tsx msgid "From address" msgstr "From address" @@ -932,6 +927,11 @@ msgstr "From the {pluginName} plugin. Shared by every language of this item, and msgid "server.content.title_missing" msgstr "Front matter must include a non-empty \"title\"." +#: src/admin/components/shell.tsx +#: src/admin/pages/settings-site.tsx +msgid "General" +msgstr "General" + #. js-lingui-explicit-id #: src/admin/server-messages.catalog.ts msgid "server.account.ui_locale_invalid" @@ -949,9 +949,9 @@ msgstr "Hide fields" msgid "Hooks" msgstr "Hooks" -#: src/admin/components/media-library.tsx -msgid "Images are converted to WebP in your browser and uploaded at {widths} pixels wide. SVG is not accepted — it can carry script." -msgstr "Images are converted to WebP in your browser and uploaded at {widths} pixels wide. SVG is not accepted — it can carry script." +#: src/admin/pages/settings-appearance.tsx +msgid "How your theme looks: these options change the site as soon as you save." +msgstr "How your theme looks: these options change the site as soon as you save." #: src/admin/components/media-library.tsx msgid "In use. Remove the references first." @@ -1118,7 +1118,6 @@ msgid "Media" msgstr "Media" #: src/admin/pages/settings-advanced.tsx -#: src/admin/pages/settings-site.tsx msgid "Media domain" msgstr "Media domain" @@ -1408,10 +1407,6 @@ msgstr "Official" msgid "On" msgstr "On" -#: src/admin/pages/settings-email.tsx -msgid "One Resend key and one sender address for the whole site. Every plugin that sends email uses them, and a change applies to the next message — no rebuild, no deploy." -msgstr "One Resend key and one sender address for the whole site. Every plugin that sends email uses them, and a change applies to the next message — no rebuild, no deploy." - #: src/admin/pages/plugins.tsx msgid "Only at request time" msgstr "Only at request time" @@ -1477,6 +1472,10 @@ msgstr "Paste the value" msgid "Path" msgstr "Path" +#: src/admin/pages/media.tsx +msgid "Photos and files used on your site." +msgstr "Photos and files used on your site." + #: src/admin/pages/settings-advanced.tsx msgid "Plugin on/off switches, settings and secrets" msgstr "Plugin on/off switches, settings and secrets" @@ -1794,6 +1793,10 @@ msgstr "Show password" msgid "Shown by most themes under the site name, and as the home page description." msgstr "Shown by most themes under the site name, and as the home page description." +#: src/admin/pages/editor.tsx +msgid "Shown in lists and in search results. Empty uses the start of the text." +msgstr "Shown in lists and in search results. Empty uses the start of the text." + #: src/admin/pages/settings-site.tsx msgid "Shown on pages in {taglineLanguage}. Empty uses the tagline above." msgstr "Shown on pages in {taglineLanguage}. Empty uses the tagline above." @@ -1824,7 +1827,6 @@ msgid "Signing in…" msgstr "Signing in…" #: src/admin/components/shell.tsx -#: src/admin/pages/settings-site.tsx msgid "Site" msgstr "Site" @@ -1850,10 +1852,6 @@ msgstr "Site settings, languages, navigation" msgid "Skip" msgstr "Skip" -#: src/admin/pages/editor.tsx -msgid "Slug" -msgstr "Slug" - #. js-lingui-explicit-id #: src/admin/server-messages.catalog.ts msgid "server.plugins.fields_invalid" @@ -1883,6 +1881,10 @@ msgstr "Stored encrypted. It is never shown again, here or anywhere else." msgid "Stored encrypted. They are never shown again, here or anywhere else." msgstr "Stored encrypted. They are never shown again, here or anywhere else." +#: src/admin/pages/editor.tsx +msgid "Summary" +msgstr "Summary" + #: src/admin/media.ts msgid "SVG is not accepted: it can carry script. Export a PNG or WebP instead." msgstr "SVG is not accepted: it can carry script. Export a PNG or WebP instead." @@ -1903,10 +1905,6 @@ msgstr "Tagline in {taglineLanguage}" msgid "Take this off the site? It stays here as a draft, and visitors no longer see it." msgstr "Take this off the site? It stays here as a draft, and visitors no longer see it." -#: src/admin/pages/plugins.tsx -msgid "Technical details" -msgstr "Technical details" - #: src/admin/pages/plugins.tsx #: src/admin/pages/settings-email.tsx msgid "Test" @@ -2020,10 +2018,6 @@ msgstr "The media id must be a sha256 hex digest." msgid "server.account.password_short" msgstr "The new password must be at least {min} characters." -#: src/admin/pages/settings-appearance.tsx -msgid "The options below are runtime settings: saving takes effect without a rebuild. The theme itself is source code." -msgstr "The options below are runtime settings: saving takes effect without a rebuild. The theme itself is source code." - #. js-lingui-explicit-id #: src/admin/server-messages.catalog.ts msgid "server.media.body_empty" @@ -2143,10 +2137,6 @@ msgstr "Themes live in the source tree, not the database — they are compiled i msgid "There is no page at this address in the admin." msgstr "There is no page at this address in the admin." -#: src/admin/pages/settings-site.tsx -msgid "These are stored the moment you save — no rebuild, no deploy." -msgstr "These are stored the moment you save — no rebuild, no deploy." - #: src/admin/pages/settings-appearance.tsx msgid "These values apply to every language unless a language overrides them below." msgstr "These values apply to every language unless a language overrides them below." @@ -2312,6 +2302,10 @@ msgstr "Upload the original before its variants." msgid "uploading" msgstr "uploading" +#: src/admin/pages/editor.tsx +msgid "URL slug" +msgstr "URL slug" + #: src/admin/components/media-library.tsx msgid "Use" msgstr "Use" @@ -2329,10 +2323,6 @@ msgstr "Use an address such as hello@example.com or Acme ." msgid "used {0}×" msgstr "used {0}×" -#: src/admin/pages/editor.tsx -msgid "Used as the meta description and in listings. Derived from the body when empty." -msgstr "Used as the meta description and in listings. Derived from the body when empty." - #: src/admin/form/controls.tsx msgid "Value" msgstr "Value" @@ -2411,6 +2401,7 @@ msgstr "written for the \"{starterTheme}\" theme, but this build runs \"{activeT msgid "Yes" msgstr "Yes" +#: src/admin/pages/settings-site.tsx #: src/admin/pages/setup.tsx msgid "Your domain" msgstr "Your domain" @@ -2418,3 +2409,7 @@ msgstr "Your domain" #: src/admin/pages/setup.tsx msgid "Your site is ready" msgstr "Your site is ready" + +#: src/admin/pages/settings-email.tsx +msgid "Your site sends email through Resend, an email service; the key comes from your Resend account. Every plugin that sends email, inquiries included, uses this one sender and key." +msgstr "Your site sends email through Resend, an email service; the key comes from your Resend account. Every plugin that sends email, inquiries included, uses this one sender and key." diff --git a/src/admin/locales/zh-CN.po b/src/admin/locales/zh-CN.po index da4639c..2daa7d2 100644 --- a/src/admin/locales/zh-CN.po +++ b/src/admin/locales/zh-CN.po @@ -249,10 +249,6 @@ msgstr "关于密码哈希" msgid "Account" msgstr "账号" -#: src/admin/components/account-menu.tsx -msgid "Account and API tokens" -msgstr "账号与 API 令牌" - #. js-lingui-explicit-id #: src/admin/server-messages.catalog.ts msgid "server.auth.session_required" @@ -300,6 +296,10 @@ msgstr "添加一行" msgid "Add the first one" msgstr "添加第一条" +#: src/admin/pages/settings-site.tsx +msgid "Address for images" +msgstr "图片地址" + #: src/admin/pages/setup.tsx msgid "Administrator" msgstr "管理员" @@ -739,7 +739,6 @@ msgid "Current password" msgstr "当前密码" #: src/admin/pages/settings-advanced.tsx -#: src/admin/pages/settings-site.tsx msgid "Custom domain" msgstr "自定义域名" @@ -783,10 +782,6 @@ msgstr "由标题自动生成" msgid "Describe the image" msgstr "描述这张图片" -#: src/admin/pages/editor.tsx -msgid "Description" -msgstr "描述" - #: src/admin/components/plugin-panel.tsx msgid "Details" msgstr "详情" @@ -903,10 +898,6 @@ msgstr "字段" msgid "Fields, Markdown and preview" msgstr "字段、Markdown 与预览" -#: src/admin/pages/media.tsx -msgid "Files are stored by the hash of the original, so uploading the same image twice costs nothing and never creates a duplicate." -msgstr "文件按原图的哈希值存储,同一张图片上传两次不会产生额外开销,也不会出现重复。" - #: src/admin/pages/setup.tsx msgid "Finish setup" msgstr "完成设置" @@ -915,6 +906,10 @@ msgstr "完成设置" msgid "For a language not listed, comma separated. Languages can also be added later." msgstr "用于上面没有列出的语言,以逗号分隔。之后也可以再添加语言。" +#: src/admin/pages/plugins.tsx +msgid "For the person who deploys" +msgstr "部署相关信息" + #: src/admin/pages/settings-email.tsx msgid "From address" msgstr "发件地址" @@ -932,6 +927,11 @@ msgstr "来自 {pluginName} 插件。这条内容的所有语言版本共用这 msgid "server.content.title_missing" msgstr "Front matter 必须包含非空的 “title”。" +#: src/admin/components/shell.tsx +#: src/admin/pages/settings-site.tsx +msgid "General" +msgstr "基本设置" + #. js-lingui-explicit-id #: src/admin/server-messages.catalog.ts msgid "server.account.ui_locale_invalid" @@ -949,9 +949,9 @@ msgstr "收起字段" msgid "Hooks" msgstr "钩子" -#: src/admin/components/media-library.tsx -msgid "Images are converted to WebP in your browser and uploaded at {widths} pixels wide. SVG is not accepted — it can carry script." -msgstr "图片会在浏览器中转换为 WebP,并按 {widths} 像素宽度上传。不支持 SVG——它可能携带脚本。" +#: src/admin/pages/settings-appearance.tsx +msgid "How your theme looks: these options change the site as soon as you save." +msgstr "网站的外观:这些选项保存后立即在网站上生效。" #: src/admin/components/media-library.tsx msgid "In use. Remove the references first." @@ -1118,7 +1118,6 @@ msgid "Media" msgstr "媒体" #: src/admin/pages/settings-advanced.tsx -#: src/admin/pages/settings-site.tsx msgid "Media domain" msgstr "媒体域名" @@ -1408,10 +1407,6 @@ msgstr "官方" msgid "On" msgstr "开" -#: src/admin/pages/settings-email.tsx -msgid "One Resend key and one sender address for the whole site. Every plugin that sends email uses them, and a change applies to the next message — no rebuild, no deploy." -msgstr "整个站点共用一个 Resend 密钥和一个发件地址。所有发送邮件的插件都使用它们,修改后对下一封邮件生效——无需重新构建或部署。" - #: src/admin/pages/plugins.tsx msgid "Only at request time" msgstr "仅在请求时" @@ -1477,6 +1472,10 @@ msgstr "粘贴密钥值" msgid "Path" msgstr "路径" +#: src/admin/pages/media.tsx +msgid "Photos and files used on your site." +msgstr "网站上用到的图片和文件。" + #: src/admin/pages/settings-advanced.tsx msgid "Plugin on/off switches, settings and secrets" msgstr "插件的启用开关、设置和密钥" @@ -1794,6 +1793,10 @@ msgstr "显示密码" msgid "Shown by most themes under the site name, and as the home page description." msgstr "大多数主题会显示在站点名称下方,并用作首页描述。" +#: src/admin/pages/editor.tsx +msgid "Shown in lists and in search results. Empty uses the start of the text." +msgstr "显示在列表和搜索结果中。留空则取正文开头。" + #: src/admin/pages/settings-site.tsx msgid "Shown on pages in {taglineLanguage}. Empty uses the tagline above." msgstr "显示在{taglineLanguage}页面上。留空则使用上面的标语。" @@ -1824,7 +1827,6 @@ msgid "Signing in…" msgstr "正在登录…" #: src/admin/components/shell.tsx -#: src/admin/pages/settings-site.tsx msgid "Site" msgstr "站点" @@ -1850,10 +1852,6 @@ msgstr "站点设置、语言、导航" msgid "Skip" msgstr "跳过" -#: src/admin/pages/editor.tsx -msgid "Slug" -msgstr "URL 别名" - #. js-lingui-explicit-id #: src/admin/server-messages.catalog.ts msgid "server.plugins.fields_invalid" @@ -1883,6 +1881,10 @@ msgstr "加密保存。之后在这里或任何地方都不会再显示。" msgid "Stored encrypted. They are never shown again, here or anywhere else." msgstr "加密保存。之后在这里或任何地方都不会再显示。" +#: src/admin/pages/editor.tsx +msgid "Summary" +msgstr "摘要" + #: src/admin/media.ts msgid "SVG is not accepted: it can carry script. Export a PNG or WebP instead." msgstr "不支持 SVG:它可能携带脚本。请导出为 PNG 或 WebP。" @@ -1903,10 +1905,6 @@ msgstr "{taglineLanguage}标语" msgid "Take this off the site? It stays here as a draft, and visitors no longer see it." msgstr "要从网站上撤下吗?它会作为草稿保留在这里,访客将看不到它。" -#: src/admin/pages/plugins.tsx -msgid "Technical details" -msgstr "技术细节" - #: src/admin/pages/plugins.tsx #: src/admin/pages/settings-email.tsx msgid "Test" @@ -2020,10 +2018,6 @@ msgstr "媒体 ID 必须是十六进制的 sha256 摘要。" msgid "server.account.password_short" msgstr "新密码至少需要 {min} 个字符。" -#: src/admin/pages/settings-appearance.tsx -msgid "The options below are runtime settings: saving takes effect without a rebuild. The theme itself is source code." -msgstr "以下选项是运行时设置:保存后立即生效,无需重新构建。主题本身属于源代码。" - #. js-lingui-explicit-id #: src/admin/server-messages.catalog.ts msgid "server.media.body_empty" @@ -2143,10 +2137,6 @@ msgstr "主题位于源代码中,而不在数据库里——它们会被编译 msgid "There is no page at this address in the admin." msgstr "后台中没有这个地址对应的页面。" -#: src/admin/pages/settings-site.tsx -msgid "These are stored the moment you save — no rebuild, no deploy." -msgstr "点击保存即生效——无需重新构建或部署。" - #: src/admin/pages/settings-appearance.tsx msgid "These values apply to every language unless a language overrides them below." msgstr "这些值适用于所有语言,除非某个语言在下面单独设置。" @@ -2312,6 +2302,10 @@ msgstr "请先上传原图,再上传它的缩略图。" msgid "uploading" msgstr "正在上传" +#: src/admin/pages/editor.tsx +msgid "URL slug" +msgstr "URL 别名" + #: src/admin/components/media-library.tsx msgid "Use" msgstr "使用" @@ -2329,10 +2323,6 @@ msgstr "请使用 hello@example.com 或 Acme 这样的地址 msgid "used {0}×" msgstr "已引用 {0} 次" -#: src/admin/pages/editor.tsx -msgid "Used as the meta description and in listings. Derived from the body when empty." -msgstr "用作 meta 描述,也显示在列表中。留空则从正文中提取。" - #: src/admin/form/controls.tsx msgid "Value" msgstr "值" @@ -2411,6 +2401,7 @@ msgstr "为“{starterTheme}”主题编写,但当前构建使用的是“{act msgid "Yes" msgstr "是" +#: src/admin/pages/settings-site.tsx #: src/admin/pages/setup.tsx msgid "Your domain" msgstr "你的域名" @@ -2418,3 +2409,7 @@ msgstr "你的域名" #: src/admin/pages/setup.tsx msgid "Your site is ready" msgstr "站点已就绪" + +#: src/admin/pages/settings-email.tsx +msgid "Your site sends email through Resend, an email service; the key comes from your Resend account. Every plugin that sends email, inquiries included, uses this one sender and key." +msgstr "网站通过邮件服务 Resend 发送邮件,密钥在你的 Resend 账号里获取。询盘等所有需要发邮件的插件都使用这里的发件地址和密钥。" diff --git a/src/admin/pages/editor.tsx b/src/admin/pages/editor.tsx index 44138d2..263ed23 100644 --- a/src/admin/pages/editor.tsx +++ b/src/admin/pages/editor.tsx @@ -261,9 +261,9 @@ function Editor({ name: 'description', field: { type: 'text' as const, - label: t`Description`, + label: t`Summary`, required: false, - help: t`Used as the meta description and in listings. Derived from the body when empty.`, + help: t`Shown in lists and in search results. Empty uses the start of the text.`, }, }, ...toSpecs(declared), @@ -556,7 +556,7 @@ function Editor({ - Slug + URL slug diff --git a/src/admin/pages/plugins.tsx b/src/admin/pages/plugins.tsx index acac923..b49d011 100644 --- a/src/admin/pages/plugins.tsx +++ b/src/admin/pages/plugins.tsx @@ -395,7 +395,7 @@ function PluginCard({ to be shown; closed, because it is read once, not operated. */}

- Technical details + For the person who deploys
{specs.length === 0 ? null : ( diff --git a/src/admin/pages/settings-email.tsx b/src/admin/pages/settings-email.tsx index ef46537..ff49b72 100644 --- a/src/admin/pages/settings-email.tsx +++ b/src/admin/pages/settings-email.tsx @@ -122,7 +122,7 @@ export function EmailSettingsPage(): JSX.Element {
- + {/* What applies at once and what needs a deployment is said in one + place, Advanced (docs/ADMIN_SIMPLE.md §6.5), not on every page. */} +
void submit(event)} diff --git a/test/e2e/03-publish.spec.ts b/test/e2e/03-publish.spec.ts index a0064ed..c548918 100644 --- a/test/e2e/03-publish.spec.ts +++ b/test/e2e/03-publish.spec.ts @@ -74,7 +74,7 @@ test('writes and publishes a page that is immediately public', async ({ // `page` is one of the two kinds the core always has (docs/ARCHITECTURE §8). await page.getByRole('combobox', { name: /^Type/ }).selectOption('page'); await page.getByRole('textbox', { name: 'Title', exact: true }).fill(TITLE); - await page.getByLabel('Slug', { exact: true }).fill(SLUG); + await page.getByLabel('URL slug', { exact: true }).fill(SLUG); await appendBody(page, BODY); await saveWith(page, 'Publish'); @@ -125,7 +125,7 @@ test('keeps a draft off the public site', async ({ page }) => { await page .getByRole('textbox', { name: 'Title', exact: true }) .fill('Not for readers'); - await page.getByLabel('Slug', { exact: true }).fill('not-for-readers'); + await page.getByLabel('URL slug', { exact: true }).fill('not-for-readers'); await appendBody(page, 'This page is a draft and must stay invisible.'); await saveWith(page, 'Save draft'); @@ -142,7 +142,7 @@ test('a published page is updated or unpublished, never saved back to a draft', await page .getByRole('textbox', { name: 'Title', exact: true }) .fill('Live for now'); - await page.getByLabel('Slug', { exact: true }).fill('live-for-now'); + await page.getByLabel('URL slug', { exact: true }).fill('live-for-now'); // Not fetched while live: that would put it in the edge cache, which with // no purge token here keeps it for a minute (see the test above), and // the 404 below would wait on the cache instead of on the save. diff --git a/test/e2e/17-shell.spec.ts b/test/e2e/17-shell.spec.ts index de8470a..426f853 100644 --- a/test/e2e/17-shell.spec.ts +++ b/test/e2e/17-shell.spec.ts @@ -28,7 +28,7 @@ const SECTIONS = [ ['Content', '/_mallok/app/'], ['Media', '/_mallok/app/media'], ['Plugins', '/_mallok/app/plugins'], - ['Site', '/_mallok/app/settings'], + ['General', '/_mallok/app/settings'], ['Appearance', '/_mallok/app/settings/appearance'], ['Email', '/_mallok/app/settings/email'], ['Advanced', '/_mallok/app/settings/advanced'], @@ -132,7 +132,7 @@ test('the account menu opens from the keyboard and offers the account page', asy const menu = page.getByRole('menu'); await expect(menu).toBeVisible(); await clean(page, 'account menu open'); - await menu.getByRole('menuitem', { name: 'Account and API tokens' }).click(); + await menu.getByRole('menuitem', { name: 'Account' }).click(); await expect(page).toHaveURL('/_mallok/app/account'); }); diff --git a/test/e2e/19-translation.spec.ts b/test/e2e/19-translation.spec.ts index 0d818d6..4a4560a 100644 --- a/test/e2e/19-translation.spec.ts +++ b/test/e2e/19-translation.spec.ts @@ -37,7 +37,7 @@ test('a translation made from the language bar joins the original', async ({ await page .getByRole('textbox', { name: 'Title', exact: true }) .fill('Our mill'); - await page.getByLabel('Slug', { exact: true }).fill(`our-mill-${stamp}`); + await page.getByLabel('URL slug', { exact: true }).fill(`our-mill-${stamp}`); await page.getByRole('button', { name: 'Publish' }).click(); await expect(page).toHaveURL(/\/content\/(?!new)[^/?]+$/); const original = page.url().split('/content/')[1] ?? ''; @@ -58,7 +58,7 @@ test('a translation made from the language bar joins the original', async ({ await page .getByRole('textbox', { name: 'Title', exact: true }) .fill('关于工厂'); - await page.getByLabel('Slug', { exact: true }).fill(slug); + await page.getByLabel('URL slug', { exact: true }).fill(slug); const saved = page.waitForResponse( (response) => response.url().endsWith('/_mallok/api/content') && From 1447aa0503e989177309603eceeb003e685953b1 Mon Sep 17 00:00:00 2001 From: JasonYv <233965174+JasonYv@users.noreply.github.com> Date: Thu, 19 Nov 2026 09:03:06 -0800 Subject: [PATCH 06/14] feat(worker): search the admin's content list by title `GET /_mallok/api/content?q=` narrows the list to items whose title contains the words typed, with the other filters (docs/ADMIN_SIMPLE.md, G6). The match is `title LIKE ? ESCAPE '\'` in src/db, case-insensitive for Latin letters, with `%`, `_` and `\` taken literally; the list stays one query over summary columns with no count, and never reads the body. What is typed is trimmed and kept to 200 characters. Co-Authored-By: Claude Opus 5.5 --- src/db/queries.ts | 10 +++ src/worker/admin-content.ts | 6 ++ test/worker/content-search.test.ts | 108 +++++++++++++++++++++++++++++ 3 files changed, 124 insertions(+) create mode 100644 test/worker/content-search.test.ts diff --git a/src/db/queries.ts b/src/db/queries.ts index 583ffb4..3b38651 100644 --- a/src/db/queries.ts +++ b/src/db/queries.ts @@ -563,6 +563,12 @@ export interface ContentListFilter { /** Exact slug, for looking one item up by its natural key. */ readonly slug?: string; readonly status?: ContentRow['status']; + /** + * Words the title contains, as typed: matched case-insensitively for + * Latin letters, with `%`, `_` and `\` taken literally. The title column + * only — a list never reads the body (docs/ADMIN_SIMPLE.md, G6). + */ + readonly title?: string; readonly limit: number; readonly offset: number; } @@ -594,6 +600,10 @@ export async function listContent( clauses.push('slug = ?'); bindings.push(filter.slug); } + if (filter.title !== undefined && filter.title !== '') { + clauses.push("title LIKE ? ESCAPE '\\'"); + bindings.push(`%${filter.title.replace(/[\\%_]/g, '\\$&')}%`); + } const where = clauses.length === 0 ? '' : `WHERE ${clauses.join(' AND ')}`; const rows = await db .prepare( diff --git a/src/worker/admin-content.ts b/src/worker/admin-content.ts index 14e6359..581f7f8 100644 --- a/src/worker/admin-content.ts +++ b/src/worker/admin-content.ts @@ -105,6 +105,12 @@ export async function getContentList(env: Env, url: URL): Promise { ...optional('kind', url.searchParams.get('kind')), ...optional('locale', url.searchParams.get('locale')), ...optional('slug', url.searchParams.get('slug')), + // A search box's words, trimmed and kept to a sane length; the list + // stays one query with no count (docs/ADMIN_SIMPLE.md, G6). + ...optional( + 'title', + url.searchParams.get('q')?.trim().slice(0, 200) ?? null, + ), ...(status === null ? {} : { status }), limit, offset, diff --git a/test/worker/content-search.test.ts b/test/worker/content-search.test.ts new file mode 100644 index 0000000..5458fe3 --- /dev/null +++ b/test/worker/content-search.test.ts @@ -0,0 +1,108 @@ +import { SELF } from 'cloudflare:test'; +import { beforeAll, describe, expect, it } from 'vitest'; + +/** + * Searching the admin's content list by title (docs/ADMIN_SIMPLE.md, G6): + * `q` on `GET /_mallok/api/content` matches words in the title, with the + * other filters, and takes what is typed literally. + */ + +const ORIGIN = 'https://content-search.example'; +const EMAIL = 'search@example.com'; +const PASSWORD = 'a sufficiently long password'; + +let token = ''; + +async function api( + method: string, + path: string, + body?: unknown, +): Promise { + return SELF.fetch(`${ORIGIN}${path}`, { + method, + headers: { + authorization: `Bearer ${token}`, + 'content-type': 'application/json', + }, + ...(body === undefined ? {} : { body: JSON.stringify(body) }), + }); +} + +describe('searching content by title', () => { + beforeAll(async () => { + await SELF.fetch(`${ORIGIN}/`); + await SELF.fetch(`${ORIGIN}/_mallok/api/auth/bootstrap`, { + method: 'POST', + headers: { 'content-type': 'application/json' }, + body: JSON.stringify({ email: EMAIL, password: PASSWORD }), + }); + const session = await SELF.fetch(`${ORIGIN}/_mallok/api/auth/login`, { + method: 'POST', + headers: { 'content-type': 'application/json' }, + body: JSON.stringify({ email: EMAIL, password: PASSWORD }), + }); + const cookie = + (session.headers.get('set-cookie') ?? '').split(';')[0] ?? ''; + const { csrf } = (await session.json()) as { csrf: string }; + const minted = await SELF.fetch(`${ORIGIN}/_mallok/api/tokens`, { + method: 'POST', + headers: { + cookie, + 'x-mallok-csrf': csrf, + 'content-type': 'application/json', + }, + body: JSON.stringify({ name: 'search-test', scopes: ['content:write'] }), + }); + token = ((await minted.json()) as { token: string }).token; + for (const [kind, slug, title] of [ + ['page', 'grade-5-bar', 'Grade 5 titanium bar'], + ['page', 'grade-2-plate', 'Grade 2 titanium plate'], + ['article', 'bar-news', 'Why bar prices move'], + ['article', 'odd', '100% pure_titanium'], + ] as const) { + const saved = await api('POST', '/_mallok/api/content', { + kind, + slug, + markdown: `---\ntitle: ${title}\n---\n\nBody.`, + assets: {}, + }); + expect(saved.status).toBe(201); + } + }); + + async function titles(query: string): Promise { + const response = await api('GET', `/_mallok/api/content?${query}`); + expect(response.status).toBe(200); + const body = (await response.json()) as { items: { title: string }[] }; + return body.items.map((item) => item.title).sort(); + } + + it('finds words anywhere in the title, whatever their case', async () => { + expect(await titles('q=TITANIUM')).toEqual([ + '100% pure_titanium', + 'Grade 2 titanium plate', + 'Grade 5 titanium bar', + ]); + }); + + it('narrows with the other filters', async () => { + expect(await titles('q=bar&kind=page')).toEqual(['Grade 5 titanium bar']); + }); + + it('takes % and _ as typed, not as wildcards', async () => { + expect(await titles(`q=${encodeURIComponent('100%')}`)).toEqual([ + '100% pure_titanium', + ]); + expect(await titles(`q=${encodeURIComponent('e_t')}`)).toEqual([ + '100% pure_titanium', + ]); + expect(await titles(`q=${encodeURIComponent('%')}&kind=page`)).toEqual([]); + }); + + it('lists everything when the box is empty or blank', async () => { + expect(await titles('q=&kind=page')).toHaveLength(2); + expect( + await titles(`q=${encodeURIComponent(' ')}&kind=page`), + ).toHaveLength(2); + }); +}); From 2ef2d49d814ff3c55b139b9de016c0eb8d48552e Mon Sep 17 00:00:00 2001 From: JasonYv <233965174+JasonYv@users.noreply.github.com> Date: Thu, 19 Nov 2026 09:03:06 -0800 Subject: [PATCH 07/14] feat(admin): give each content type its own list, as mainstream admins do MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The sidebar lists one entry per content type the site has, by the theme's label and with an icon for the common ones, then Media; plugin panels such as Inquiries sit above them, and Plugins moves under Settings (docs/ADMIN_SIMPLE.md, D2). A type's list is the content list with the type in the address; with none it is "All content". The list reads like WordPress's and Shopify's (D3, D8; G6, G8, G9, G22): - no Path column; a row's menu has Edit, View on site and Copy address, which says it copied or shows the address; - no Type column inside one type's list; - status and the content language are tabs, the language by its name alone and absent on a one-language site; - a search box by title, kept in the address; - "Last edited" reads "Today 07:12", "Yesterday", "3 days ago", then the date; it lives in format-relative.ts so the shell does not carry it; - "Add Product" and the empty states name the type. The editor's address carries the type (`?kind=`), so the sidebar and the breadcrumb ("Product › Edit") know where it is, and its back button returns to that type's list. Selectors: 02-login reads "All content"; 03-publish, 05-accessibility and 19-translation press "Add content"; 11-lazy-remount and 13-editor-untouched open the Page list from the sidebar; 17-shell walks the Page and Product entries; 19-translation allows `?kind=` in the editor's address. 05-accessibility scans a type's list; a new 22-content-lists covers the entry, the tabs, the search and the menu. admin:size 167.9 KiB first load (+1.6): the dropdown menu now shared with the shell split react-remove-scroll into a chunk of its own, and the type icons are 0.6 of it. Co-Authored-By: Claude Opus 5.5 --- src/admin/components/content-language.tsx | 43 +++ src/admin/components/filter-tabs.tsx | 60 ++++ src/admin/components/shell.tsx | 167 +++++++---- src/admin/format-relative.ts | 41 +++ src/admin/locales/en.po | 89 ++++-- src/admin/locales/zh-CN.po | 89 ++++-- src/admin/pages/content-list.tsx | 322 ++++++++++++++-------- src/admin/pages/editor.tsx | 21 +- test/admin/format.test.ts | 26 ++ test/e2e/02-login.spec.ts | 5 +- test/e2e/03-publish.spec.ts | 6 +- test/e2e/05-accessibility.spec.ts | 4 +- test/e2e/11-lazy-remount.spec.ts | 6 +- test/e2e/13-editor-untouched.spec.ts | 6 +- test/e2e/17-shell.spec.ts | 4 +- test/e2e/19-translation.spec.ts | 11 +- test/e2e/22-content-lists.spec.ts | 97 +++++++ 17 files changed, 772 insertions(+), 225 deletions(-) create mode 100644 src/admin/components/filter-tabs.tsx create mode 100644 src/admin/format-relative.ts create mode 100644 test/e2e/22-content-lists.spec.ts diff --git a/src/admin/components/content-language.tsx b/src/admin/components/content-language.tsx index a1a27b7..2bf4725 100644 --- a/src/admin/components/content-language.tsx +++ b/src/admin/components/content-language.tsx @@ -71,6 +71,49 @@ export function useContentLanguageName(): (code: string) => string { }; } +/** + * Names the site's content languages for daily screens: the name alone — + * "English", "中文" — with the code added only to languages whose names + * would otherwise be the same, and to a code `Intl` cannot name + * (docs/ADMIN_SIMPLE.md, D8). Settings → General still shows every code. + */ +export function useShortLanguageNames( + locales: readonly string[], +): (code: string) => string { + const { i18n } = useLingui(); + const long = useContentLanguageName(); + const names = useMemo(() => { + let display: Intl.DisplayNames | null = null; + try { + display = new Intl.DisplayNames([i18n.locale], { type: 'language' }); + } catch { + display = null; + } + const nameOf = (code: string): string | undefined => { + try { + const name = display?.of(code); + return name === undefined || name.toLowerCase() === code.toLowerCase() + ? undefined + : name; + } catch { + return undefined; + } + }; + const counts = new Map(); + for (const code of locales) { + const name = nameOf(code) ?? code; + counts.set(name, (counts.get(name) ?? 0) + 1); + } + return { nameOf, counts }; + }, [i18n.locale, locales]); + return (code) => { + const name = names.nameOf(code); + return name === undefined || (names.counts.get(name) ?? 0) > 1 + ? long(code) + : name; + }; +} + /** * The options of a content-language select, named, without the select: for * a control that labels itself differently or picks more than one. diff --git a/src/admin/components/filter-tabs.tsx b/src/admin/components/filter-tabs.tsx new file mode 100644 index 0000000..b72d670 --- /dev/null +++ b/src/admin/components/filter-tabs.tsx @@ -0,0 +1,60 @@ +/** + * A short row of choices that narrows a list — All, Published, Drafts — as + * the tabs mainstream admins put above a table (docs/ADMIN_SIMPLE.md, D2 + * and §6.3). Each is a toggle button: one is pressed, and choosing another + * filters the list below it, which is not what an ARIA tab panel does. + */ + +import { cn } from 'cn'; +import type { JSX } from 'react'; + +/** A choice and the words that name it. */ +export interface FilterTab { + readonly value: string; + readonly label: string; +} + +export function FilterTabs({ + label, + tabs, + value, + onChange, + className, +}: { + /** What the choices are of, for assistive technology: "Status". */ + readonly label: string; + readonly tabs: readonly FilterTab[]; + readonly value: string; + readonly onChange: (value: string) => void; + readonly className?: string; +}): JSX.Element { + return ( +
+ {tabs.map((tab) => { + const pressed = tab.value === value; + return ( + + ); + })} +
+ ); +} diff --git a/src/admin/components/shell.tsx b/src/admin/components/shell.tsx index 0123a57..5b67f62 100644 --- a/src/admin/components/shell.tsx +++ b/src/admin/components/shell.tsx @@ -13,13 +13,18 @@ import { msg } from '@lingui/core/macro'; import { Trans, useLingui } from '@lingui/react/macro'; import { useQuery } from '@tanstack/react-query'; import { + Briefcase, ChevronsUpDown, + CircleHelp, Clock, ExternalLink, FileText, + FolderTree, Image, List, Mail, + Newspaper, + Package, Palette, Plug, Settings2, @@ -62,6 +67,7 @@ import { useLiveDelay, useSession, useSettings, + useTheme, } from '../queries.js'; import type { PluginInfo } from '../types.js'; @@ -70,30 +76,33 @@ interface NavItem { readonly label: MessageDescriptor | string; readonly href: string; readonly icon: typeof FileText; - /** Whether the item is the current section for `path`. */ - readonly active: (path: string) => boolean; + /** + * Whether the item is the current section for `path`, and for the + * content type the address names (`?kind=`), if any. + */ + readonly active: (path: string, kind: string) => boolean; } -const SITE: readonly NavItem[] = [ - { - label: msg`Content`, - href: '/', - icon: FileText, - active: (path) => path === '/' || path.startsWith('/content'), - }, - { - label: msg`Media`, - href: '/media', - icon: Image, - active: (path) => path === '/media', - }, - { - label: msg`Plugins`, - href: '/plugins', - icon: Plug, - active: (path) => path === '/plugins', - }, -]; +const MEDIA: NavItem = { + label: msg`Media`, + href: '/media', + icon: Image, + active: (path) => path === '/media', +}; + +/** + * Icons for the content types themes commonly declare; any other type is a + * document. Only a picture: the type is named by the theme's own label. + */ +const KIND_ICONS: Readonly> = { + product: Package, + article: Newspaper, + post: Newspaper, + news: Newspaper, + category: FolderTree, + case: Briefcase, + faq: CircleHelp, +}; const SETTINGS: readonly NavItem[] = [ { @@ -114,6 +123,14 @@ const SETTINGS: readonly NavItem[] = [ icon: Mail, active: (path) => path === '/settings/email', }, + { + // A switch and settings, not something the operator adds: installing + // a plugin is a deployment (docs/ADMIN_SIMPLE.md, D2). + label: msg`Plugins`, + href: '/plugins', + icon: Plug, + active: (path) => path === '/plugins', + }, { label: msg`Advanced`, href: '/settings/advanced', @@ -151,19 +168,23 @@ function NavGroup({ label, items, path, + kind, }: { - readonly label: string; + readonly label?: string; readonly items: readonly NavItem[]; readonly path: string; + readonly kind: string; }): JSX.Element { const { i18n } = useLingui(); return ( - {label} + {label === undefined ? null : ( + {label} + )} {items.map((item) => { - const active = item.active(path); + const active = item.active(path, kind); const label = typeof item.label === 'string' ? item.label : i18n._(item.label); return ( @@ -241,17 +262,24 @@ let toastsWanted = false; /** Where the current page sits: a section, and the page within it. */ function crumbsFor( path: string, + kind: string, + kindLabel: (id: string) => string, plugins: readonly PluginInfo[], ): readonly { readonly label: MessageDescriptor | string; readonly href?: string; }[] { + // A content type's list, or every type's when the address names none. + const list = + kind === '' + ? { label: msg`All content`, href: '/content' } + : { label: kindLabel(kind), href: `/content?kind=${kind}` }; if (path === '/' || path === '/content') { - return [{ label: msg`Content` }]; + return [{ label: list.label }]; } if (path.startsWith('/content/')) { return [ - { label: msg`Content`, href: '/' }, + list, { label: path === '/content/new' ? msg`New item` : msg`Edit` }, ]; } @@ -262,9 +290,8 @@ function crumbsFor( { label: setting.label }, ]; } - const area = SITE.find((item) => item.href === path); - if (area !== undefined) { - return [{ label: area.label }]; + if (path === MEDIA.href) { + return [{ label: MEDIA.label }]; } if (path === '/account') { return [{ label: msg`Account` }]; @@ -284,13 +311,17 @@ function crumbsFor( function PageBreadcrumb({ path, + kind, + kindLabel, plugins, }: { readonly path: string; + readonly kind: string; + readonly kindLabel: (id: string) => string; readonly plugins: readonly PluginInfo[]; }): JSX.Element { const { i18n } = useLingui(); - const crumbs = crumbsFor(path, plugins).map((crumb) => ({ + const crumbs = crumbsFor(path, kind, kindLabel, plugins).map((crumb) => ({ ...crumb, label: typeof crumb.label === 'string' ? crumb.label : i18n._(crumb.label), })); @@ -315,13 +346,13 @@ function PageBreadcrumb({ } /** - * The site's sections with each plugin panel between Media and Plugins: a - * list that is opened every day is a section, not the foot of a settings - * page (docs/ADMIN_I18N_AND_UI.md, U3). A panel attached to a content kind - * is in that kind's editor and is not listed. + * Each plugin panel that is a list of its own — Inquiries — at the top of + * the sidebar: it is what is opened every day (docs/ADMIN_I18N_AND_UI.md, + * U3; docs/ADMIN_SIMPLE.md, D2). A panel attached to a content type is in + * that type's editor and is not listed. */ -function siteItems(plugins: readonly PluginInfo[]): readonly NavItem[] { - const panels: NavItem[] = plugins.flatMap((plugin) => +function panelItems(plugins: readonly PluginInfo[]): readonly NavItem[] { + return plugins.flatMap((plugin) => plugin.panels .filter((panel) => panel.attachTo === undefined) .map((panel) => { @@ -334,10 +365,29 @@ function siteItems(plugins: readonly PluginInfo[]): readonly NavItem[] { }; }), ); - const [content, media, ...rest] = SITE; - return content === undefined || media === undefined - ? SITE - : [content, media, ...panels, ...rest]; +} + +/** + * One entry per content type the site has, by the theme's label, then + * Media: an operator works on "products" and "news", not on one table of + * everything (docs/ADMIN_SIMPLE.md, D2). A type the theme does not declare + * keeps its name, so nothing the site holds is out of reach. + */ +function contentItems( + kinds: readonly string[], + kindLabel: (id: string) => string, +): readonly NavItem[] { + return [ + ...kinds.map((kind) => ({ + label: kindLabel(kind), + href: `/content?kind=${kind}`, + icon: KIND_ICONS[kind] ?? FileText, + active: (path: string, current: string) => + (path === '/content' || path.startsWith('/content/')) && + current === kind, + })), + MEDIA, + ]; } export function Shell({ @@ -346,12 +396,19 @@ export function Shell({ readonly children: ReactNode; }): JSX.Element { // In-app, trailing slash or not: `/settings/` is the Site page too. - const path = useLocation().pathname.replace(/\/+$/, '') || '/'; + const location = useLocation(); + const path = location.pathname.replace(/\/+$/, '') || '/'; + // The content type a list or an editor is about, carried in its address. + const kind = new URLSearchParams(location.search).get('kind') ?? ''; + const site = useSettings(); + const theme = useTheme(); + const kindLabel = (id: string): string => theme.kinds[id]?.label ?? id; // A page reports a failure with `notify`; it is shown as a toast. const message = useNotice(); - const siteName = useSettings().name; + const siteName = site.name; // Loaded with the shell (`loadShell`); empty only if that request failed. const plugins = useQuery(pluginsQuery).data?.plugins ?? []; + const panels = panelItems(plugins); const { t } = useLingui(); if (message !== '') { toastsWanted = true; @@ -397,8 +454,21 @@ export function Shell({ - - + {panels.length === 0 ? null : ( + + )} + + @@ -418,7 +488,12 @@ export function Shell({ orientation="vertical" className="mr-2 data-[orientation=vertical]:h-4" /> - + {/* The notice inside the column, not across the window: it, the page header and the page share one left edge (U2). The column diff --git a/src/admin/format-relative.ts b/src/admin/format-relative.ts new file mode 100644 index 0000000..9f726db --- /dev/null +++ b/src/admin/format-relative.ts @@ -0,0 +1,41 @@ +/** + * Relative dates for lists of recent work. A module of its own, not part of + * `format.ts`: the shell imports that one, and what only lists use should + * not ride on the first load (docs/ADMIN.md §13). + */ + +import { i18n } from '@lingui/core'; +import { formatDate } from './format.js'; + +/** + * When something was last changed, the way a list of recent work reads: + * "Today 07:12", "Yesterday 18:40", "3 days ago" within the week, then the + * date (docs/ADMIN_SIMPLE.md, G22). Days are calendar days where the + * operator is, not 24-hour spans. + */ +export function formatLastEdited( + value: Date | string | number, + now: Date = new Date(), +): string { + const then = new Date(value); + const startOf = (date: Date): number => + new Date(date.getFullYear(), date.getMonth(), date.getDate()).getTime(); + const days = Math.round((startOf(now) - startOf(then)) / 86_400_000); + if (days < 0 || days > 6) { + return formatDate(then); + } + const relative = new Intl.RelativeTimeFormat(i18n.locale, { + numeric: 'auto', + }).format(-days, 'day'); + const word = + relative.charAt(0).toLocaleUpperCase(i18n.locale) + relative.slice(1); + if (days > 1) { + return word; + } + const time = new Intl.DateTimeFormat(i18n.locale, { + hour: '2-digit', + minute: '2-digit', + hourCycle: 'h23', + }).format(then); + return `${word} ${time}`; +} diff --git a/src/admin/locales/en.po b/src/admin/locales/en.po index df1646b..06006d7 100644 --- a/src/admin/locales/en.po +++ b/src/admin/locales/en.po @@ -173,10 +173,6 @@ msgstr "{when} — after {cause}, Cloudflare answered HTTP {status}" msgid "{when} — after {cause}, Cloudflare could not be reached" msgstr "{when} — after {cause}, Cloudflare could not be reached" -#: src/admin/pages/editor.tsx -msgid "← All content" -msgstr "← All content" - #: src/admin/pages/plugins.tsx msgid "<0>{panelLabel} is edited where it belongs: open any <1>{kind} in Content, and it is under the editor." msgstr "<0>{panelLabel} is edited where it belongs: open any <1>{kind} in Content, and it is under the editor." @@ -259,10 +255,23 @@ msgstr "Account changes require a browser session." msgid "Account menu" msgstr "Account menu" +#: src/admin/pages/content-list.tsx +msgid "Actions" +msgstr "Actions" + +#. placeholder {0}: item.title +#: src/admin/pages/content-list.tsx +msgid "Actions for {0}" +msgstr "Actions for {0}" + #: src/admin/pages/settings-advanced.tsx msgid "Active" msgstr "Active" +#: src/admin/pages/content-list.tsx +msgid "Add {typeName}" +msgstr "Add {typeName}" + #: src/admin/components/record-editor.tsx msgid "Add a row" msgstr "Add a row" @@ -276,6 +285,10 @@ msgstr "Add alt text" msgid "server.field.rows_required" msgstr "Add at least one row." +#: src/admin/pages/content-list.tsx +msgid "Add content" +msgstr "Add content" + #: src/admin/form/controls.tsx msgid "Add entry" msgstr "Add entry" @@ -292,6 +305,10 @@ msgstr "Add language" msgid "Add row" msgstr "Add row" +#: src/admin/pages/content-list.tsx +msgid "Add the first {typeName}" +msgstr "Add the first {typeName}" + #: src/admin/components/plugin-panel.tsx msgid "Add the first one" msgstr "Add the first one" @@ -318,6 +335,11 @@ msgstr "Affects cached pages" msgid "All" msgstr "All" +#: src/admin/components/shell.tsx +#: src/admin/pages/content-list.tsx +msgid "All content" +msgstr "All content" + #: src/admin/components/media-library.tsx msgid "already stored, skipped" msgstr "already stored, skipped" @@ -602,7 +624,6 @@ msgid "Configured" msgstr "Configured" #: src/admin/components/shell.tsx -#: src/admin/pages/content-list.tsx msgid "Content" msgstr "Content" @@ -631,10 +652,18 @@ msgstr "Continue" msgid "converting" msgstr "converting" +#: src/admin/pages/content-list.tsx +msgid "Copied {address}" +msgstr "Copied {address}" + #: src/admin/pages/account.tsx msgid "Copy" msgstr "Copy" +#: src/admin/pages/content-list.tsx +msgid "Copy address" +msgstr "Copy address" + #: src/admin/pages/account.tsx msgid "Could not change the password." msgstr "Could not change the password." @@ -643,6 +672,10 @@ msgstr "Could not change the password." msgid "Could not change." msgstr "Could not change." +#: src/admin/pages/content-list.tsx +msgid "Could not copy. The address is {address}" +msgstr "Could not copy. The address is {address}" + #: src/admin/pages/account.tsx msgid "Could not create." msgstr "Could not create." @@ -828,6 +861,7 @@ msgstr "Edge cache lifetime (seconds)" #: src/admin/components/plugin-panel.tsx #: src/admin/components/shell.tsx +#: src/admin/pages/content-list.tsx msgid "Edit" msgstr "Edit" @@ -1045,6 +1079,10 @@ msgstr "Key set, no site sender — only plugins with their own send" msgid "server.content.kind_disabled" msgstr "Kind \"{kind}\" is not enabled on this site." +#: src/admin/pages/content-list.tsx +msgid "Language" +msgstr "Language" + #: src/admin/pages/settings-site.tsx #: src/admin/pages/setup.tsx msgid "Language code" @@ -1058,6 +1096,10 @@ msgstr "Language to add" msgid "Languages" msgstr "Languages" +#: src/admin/pages/content-list.tsx +msgid "Last edited" +msgstr "Last edited" + #: src/admin/pages/settings-advanced.tsx msgid "Last failed purge" msgstr "Last failed purge" @@ -1234,14 +1276,6 @@ msgstr "Never used" msgid "New" msgstr "New" -#: src/admin/pages/content-list.tsx -msgid "New {filteredKind}" -msgstr "New {filteredKind}" - -#: src/admin/pages/content-list.tsx -msgid "New content" -msgstr "New content" - #: src/admin/components/shell.tsx msgid "New item" msgstr "New item" @@ -1468,10 +1502,6 @@ msgstr "Passwords are hashed with PBKDF2-SHA256 at {iterations} iterations. Curr msgid "Paste the value" msgstr "Paste the value" -#: src/admin/pages/content-list.tsx -msgid "Path" -msgstr "Path" - #: src/admin/pages/media.tsx msgid "Photos and files used on your site." msgstr "Photos and files used on your site." @@ -1683,6 +1713,18 @@ msgstr "Scopes" msgid "Search" msgstr "Search" +#: src/admin/pages/content-list.tsx +msgid "Search {typeName}…" +msgstr "Search {typeName}…" + +#: src/admin/pages/content-list.tsx +msgid "Search by title" +msgstr "Search by title" + +#: src/admin/pages/content-list.tsx +msgid "Search…" +msgstr "Search…" + #. js-lingui-explicit-id #: src/admin/server-messages.catalog.ts msgid "server.plugins.secret_not_string" @@ -1826,10 +1868,6 @@ msgstr "Sign-in failed." msgid "Signing in…" msgstr "Signing in…" -#: src/admin/components/shell.tsx -msgid "Site" -msgstr "Site" - #: src/admin/pages/setup.tsx msgid "Site and languages" msgstr "Site and languages" @@ -2133,6 +2171,10 @@ msgstr "Theme options this theme declares" msgid "Themes live in the source tree, not the database — they are compiled into the Worker. To switch, edit <0>ACTIVE_THEME in <1>src/themes/index.ts, then build and deploy again." msgstr "Themes live in the source tree, not the database — they are compiled into the Worker. To switch, edit <0>ACTIVE_THEME in <1>src/themes/index.ts, then build and deploy again." +#: src/admin/pages/content-list.tsx +msgid "There is no {typeName} yet." +msgstr "There is no {typeName} yet." + #: src/admin/app.tsx msgid "There is no page at this address in the admin." msgstr "There is no page at this address in the admin." @@ -2281,10 +2323,6 @@ msgstr "unused" msgid "Update" msgstr "Update" -#: src/admin/pages/content-list.tsx -msgid "Updated" -msgstr "Updated" - #: src/admin/pages/editor.tsx msgid "Updated <0>{updated}" msgstr "Updated <0>{updated}" @@ -2341,6 +2379,7 @@ msgstr "Variant width must be 1..{max}." msgid "server.media.variant_not_webp" msgstr "Variants must be WebP." +#: src/admin/pages/content-list.tsx #: src/admin/pages/editor.tsx msgid "View on site" msgstr "View on site" diff --git a/src/admin/locales/zh-CN.po b/src/admin/locales/zh-CN.po index 2daa7d2..54dde4b 100644 --- a/src/admin/locales/zh-CN.po +++ b/src/admin/locales/zh-CN.po @@ -173,10 +173,6 @@ msgstr "{when} — 由{cause}触发,Cloudflare 返回 HTTP {status}" msgid "{when} — after {cause}, Cloudflare could not be reached" msgstr "{when} — 由{cause}触发,无法连接 Cloudflare" -#: src/admin/pages/editor.tsx -msgid "← All content" -msgstr "← 全部内容" - #: src/admin/pages/plugins.tsx msgid "<0>{panelLabel} is edited where it belongs: open any <1>{kind} in Content, and it is under the editor." msgstr "<0>{panelLabel}:在所属内容中编辑——在“内容”里打开任意 <1>{kind},它就在编辑器下方。" @@ -259,10 +255,23 @@ msgstr "修改账号需要通过浏览器登录。" msgid "Account menu" msgstr "账号菜单" +#: src/admin/pages/content-list.tsx +msgid "Actions" +msgstr "操作" + +#. placeholder {0}: item.title +#: src/admin/pages/content-list.tsx +msgid "Actions for {0}" +msgstr "{0} 的操作" + #: src/admin/pages/settings-advanced.tsx msgid "Active" msgstr "已生效" +#: src/admin/pages/content-list.tsx +msgid "Add {typeName}" +msgstr "添加{typeName}" + #: src/admin/components/record-editor.tsx msgid "Add a row" msgstr "添加一行" @@ -276,6 +285,10 @@ msgstr "添加替代文本" msgid "server.field.rows_required" msgstr "请至少添加一行。" +#: src/admin/pages/content-list.tsx +msgid "Add content" +msgstr "添加内容" + #: src/admin/form/controls.tsx msgid "Add entry" msgstr "添加一项" @@ -292,6 +305,10 @@ msgstr "添加语言" msgid "Add row" msgstr "添加一行" +#: src/admin/pages/content-list.tsx +msgid "Add the first {typeName}" +msgstr "添加第一个{typeName}" + #: src/admin/components/plugin-panel.tsx msgid "Add the first one" msgstr "添加第一条" @@ -318,6 +335,11 @@ msgstr "影响缓存页面" msgid "All" msgstr "全部" +#: src/admin/components/shell.tsx +#: src/admin/pages/content-list.tsx +msgid "All content" +msgstr "全部内容" + #: src/admin/components/media-library.tsx msgid "already stored, skipped" msgstr "已存在,已跳过" @@ -602,7 +624,6 @@ msgid "Configured" msgstr "已配置" #: src/admin/components/shell.tsx -#: src/admin/pages/content-list.tsx msgid "Content" msgstr "内容" @@ -631,10 +652,18 @@ msgstr "继续" msgid "converting" msgstr "正在转换" +#: src/admin/pages/content-list.tsx +msgid "Copied {address}" +msgstr "已复制 {address}" + #: src/admin/pages/account.tsx msgid "Copy" msgstr "复制" +#: src/admin/pages/content-list.tsx +msgid "Copy address" +msgstr "复制网址" + #: src/admin/pages/account.tsx msgid "Could not change the password." msgstr "密码修改失败。" @@ -643,6 +672,10 @@ msgstr "密码修改失败。" msgid "Could not change." msgstr "修改失败。" +#: src/admin/pages/content-list.tsx +msgid "Could not copy. The address is {address}" +msgstr "无法复制。网址是 {address}" + #: src/admin/pages/account.tsx msgid "Could not create." msgstr "创建失败。" @@ -828,6 +861,7 @@ msgstr "边缘缓存有效期(秒)" #: src/admin/components/plugin-panel.tsx #: src/admin/components/shell.tsx +#: src/admin/pages/content-list.tsx msgid "Edit" msgstr "编辑" @@ -1045,6 +1079,10 @@ msgstr "已设置密钥,但没有站点发件地址 — 只有自带发件地 msgid "server.content.kind_disabled" msgstr "本站点未启用内容类型“{kind}”。" +#: src/admin/pages/content-list.tsx +msgid "Language" +msgstr "语言" + #: src/admin/pages/settings-site.tsx #: src/admin/pages/setup.tsx msgid "Language code" @@ -1058,6 +1096,10 @@ msgstr "要添加的语言" msgid "Languages" msgstr "语言" +#: src/admin/pages/content-list.tsx +msgid "Last edited" +msgstr "最后编辑" + #: src/admin/pages/settings-advanced.tsx msgid "Last failed purge" msgstr "最近一次清除失败" @@ -1234,14 +1276,6 @@ msgstr "从未使用" msgid "New" msgstr "新建" -#: src/admin/pages/content-list.tsx -msgid "New {filteredKind}" -msgstr "新建{filteredKind}" - -#: src/admin/pages/content-list.tsx -msgid "New content" -msgstr "新建内容" - #: src/admin/components/shell.tsx msgid "New item" msgstr "新建" @@ -1468,10 +1502,6 @@ msgstr "密码使用 PBKDF2-SHA256 哈希,迭代 {iterations} 次。目前的 msgid "Paste the value" msgstr "粘贴密钥值" -#: src/admin/pages/content-list.tsx -msgid "Path" -msgstr "路径" - #: src/admin/pages/media.tsx msgid "Photos and files used on your site." msgstr "网站上用到的图片和文件。" @@ -1683,6 +1713,18 @@ msgstr "权限范围" msgid "Search" msgstr "搜索" +#: src/admin/pages/content-list.tsx +msgid "Search {typeName}…" +msgstr "搜索{typeName}…" + +#: src/admin/pages/content-list.tsx +msgid "Search by title" +msgstr "按标题搜索" + +#: src/admin/pages/content-list.tsx +msgid "Search…" +msgstr "搜索…" + #. js-lingui-explicit-id #: src/admin/server-messages.catalog.ts msgid "server.plugins.secret_not_string" @@ -1826,10 +1868,6 @@ msgstr "登录失败。" msgid "Signing in…" msgstr "正在登录…" -#: src/admin/components/shell.tsx -msgid "Site" -msgstr "站点" - #: src/admin/pages/setup.tsx msgid "Site and languages" msgstr "站点与语言" @@ -2133,6 +2171,10 @@ msgstr "当前主题提供的主题选项" msgid "Themes live in the source tree, not the database — they are compiled into the Worker. To switch, edit <0>ACTIVE_THEME in <1>src/themes/index.ts, then build and deploy again." msgstr "主题位于源代码中,而不在数据库里——它们会被编译进 Worker。要更换主题,请修改 <1>src/themes/index.ts 中的 <0>ACTIVE_THEME,然后重新构建并部署。" +#: src/admin/pages/content-list.tsx +msgid "There is no {typeName} yet." +msgstr "还没有{typeName}。" + #: src/admin/app.tsx msgid "There is no page at this address in the admin." msgstr "后台中没有这个地址对应的页面。" @@ -2281,10 +2323,6 @@ msgstr "未使用" msgid "Update" msgstr "更新" -#: src/admin/pages/content-list.tsx -msgid "Updated" -msgstr "更新时间" - #: src/admin/pages/editor.tsx msgid "Updated <0>{updated}" msgstr "更新于 <0>{updated}" @@ -2341,6 +2379,7 @@ msgstr "缩略图宽度必须在 1 到 {max} 之间。" msgid "server.media.variant_not_webp" msgstr "缩略图必须是 WebP 格式。" +#: src/admin/pages/content-list.tsx #: src/admin/pages/editor.tsx msgid "View on site" msgstr "在站点上查看" diff --git a/src/admin/pages/content-list.tsx b/src/admin/pages/content-list.tsx index 3e9ac0b..f837570 100644 --- a/src/admin/pages/content-list.tsx +++ b/src/admin/pages/content-list.tsx @@ -1,27 +1,33 @@ /** - * All content, filterable by kind, locale and status (docs/ADMIN.md §4). + * A content type's list — Products, Pages, News — or, with no type in the + * address, every type's (docs/ADMIN.md §4, docs/ADMIN_SIMPLE.md §6.3). + * + * It reads like the lists of mainstream admins: the type is the sidebar + * entry the operator chose, status and language are tabs above the table, + * there is a search box, and a row's address is one "Copy address" away in + * its menu instead of being the widest column (D2, D3, D8; G6, G8, G9). * * Kinds a theme does not declare are marked rather than hidden: the content * and its URL survive a theme change, and the list has to say so - * (docs/THEME_FORMAT.md §5.3). - * - * Every value is shown as an operator reads it — a kind by the theme's - * label, a status by name, a date in the interface language — and a phone - * gets one row per item rather than a table that scrolls sideways - * (docs/ADMIN_I18N_AND_UI.md, U4–U6). + * (docs/THEME_FORMAT.md §5.3). A phone gets one row per item rather than a + * table that scrolls sideways (docs/ADMIN_I18N_AND_UI.md, U6). */ import { i18n } from '@lingui/core'; import { Trans, useLingui } from '@lingui/react/macro'; import { useQuery } from '@tanstack/react-query'; +import { MoreHorizontal, Search } from 'lucide-react'; import type { JSX } from 'react'; +import { useEffect, useState } from 'react'; import { Link, useNavigate, useSearchParams } from 'react-router'; import { Button } from '@/components/ui/button'; -import { Field, FieldLabel } from '@/components/ui/field'; import { - NativeSelect, - NativeSelectOption, -} from '@/components/ui/native-select'; + DropdownMenu, + DropdownMenuContent, + DropdownMenuItem, + DropdownMenuTrigger, +} from '@/components/ui/dropdown-menu'; +import { Input } from '@/components/ui/input'; import { Table, TableBody, @@ -31,23 +37,24 @@ import { TableRow, } from '@/components/ui/table'; import { api } from '../api.js'; -import { - ContentLanguageSelect, - useContentLanguageName, -} from '../components/content-language.js'; +import { useShortLanguageNames } from '../components/content-language.js'; import { ContentStatusBadge, STATUS_LABELS, } from '../components/content-status.js'; import { EmptyState } from '../components/empty-state.js'; +import { FilterTabs } from '../components/filter-tabs.js'; import { Page, PageHeader, StatusBadge } from '../components/page.js'; -import { formatDate } from '../format.js'; +import { formatLastEdited } from '../format-relative.js'; import { useReportError } from '../notice.js'; import { keys, useSettings, useTheme } from '../queries.js'; import type { ContentListItem } from '../types.js'; const PAGE = 25; +/** How long the search box waits after the last keystroke. */ +const SEARCH_DELAY_MS = 300; + export function ContentListPage(): JSX.Element { const { t } = useLingui(); const site = useSettings(); @@ -58,21 +65,26 @@ export function ContentListPage(): JSX.Element { const [search, setSearch] = useSearchParams(); const kind = search.get('kind') ?? ''; const status = search.get('status') ?? ''; + const words = search.get('q') ?? ''; const locale = search.get('locale') ?? site.defaultLocale; const offset = Number(search.get('offset') ?? 0) || 0; /** Changes one filter and goes back to the first page. */ const filter = (name: string, value: string): void => { - setSearch((previous) => { - const next = new URLSearchParams(previous); - if (value === '') { - next.delete(name); - } else { - next.set(name, value); - } - next.delete('offset'); - return next; - }); + setSearch( + (previous) => { + const next = new URLSearchParams(previous); + if (value === '') { + next.delete(name); + } else { + next.set(name, value); + } + next.delete('offset'); + return next; + }, + // Typing in the search box is not a page to go Back to. + { replace: name === 'q' }, + ); }; const page = (to: number): void => { setSearch((previous) => { @@ -86,6 +98,21 @@ export function ContentListPage(): JSX.Element { }); }; + // The box shows what is typed at once; the list follows a moment later. + const [typed, setTyped] = useState(words); + useEffect(() => { + setTyped(words); + }, [words]); + // `filter` is a fresh closure each render; the words are what matter. + // biome-ignore lint/correctness/useExhaustiveDependencies: see above + useEffect(() => { + if (typed.trim() === words) { + return; + } + const timer = setTimeout(() => filter('q', typed.trim()), SEARCH_DELAY_MS); + return () => clearTimeout(timer); + }, [typed, words]); + const query = new URLSearchParams({ limit: String(PAGE), offset: String(offset), @@ -97,6 +124,9 @@ export function ContentListPage(): JSX.Element { if (status !== '') { query.set('status', status); } + if (words !== '') { + query.set('q', words); + } const listed = useQuery({ queryKey: [...keys.content, 'list', query.toString()], queryFn: () => @@ -109,14 +139,14 @@ export function ContentListPage(): JSX.Element { const hasNext = listed.data?.hasNext ?? false; const loading = listed.isPending; - const kinds = Object.keys(site.kinds); - const nameOf = useContentLanguageName(); /** A kind by the theme's label; one the theme lacks keeps its id. */ const kindLabel = (id: string): string => active.kinds[id]?.label ?? id; - const filtered = kind !== '' || status !== ''; + const typeName = kind === '' ? '' : kindLabel(kind); + const languageName = useShortLanguageNames(site.locales); + const filtered = status !== '' || words !== ''; - // "New" says what it makes: the filtered kind when there is one. The - // editor opens in the list's language and, when filtered, that kind. + // "Add" says what it makes: this list's type when it has one. The editor + // opens in the list's language and type. const newQuery = new URLSearchParams({ locale }); if (kind !== '') { newQuery.set('kind', kind); @@ -124,66 +154,87 @@ export function ContentListPage(): JSX.Element { const createNew = (): void => { void navigate(`/content/new?${newQuery.toString()}`); }; - const filteredKind = kind === '' ? '' : kindLabel(kind); - const newLabel = kind === '' ? t`New content` : t`New ${filteredKind}`; - const language = nameOf(locale); + const addLabel = kind === '' ? t`Add content` : t`Add ${typeName}`; + const language = languageName(locale); + + // "Copy address" says it worked, or why not, where the operator is. + const [copied, setCopied] = useState(''); + const copyAddress = (item: ContentListItem): void => { + const address = new URL(item.path, window.location.origin).toString(); + void navigator.clipboard.writeText(address).then( + () => setCopied(t`Copied ${address}`), + () => setCopied(t`Could not copy. The address is ${address}`), + ); + }; + + const statusTabs = [ + { value: '', label: t`All` }, + ...Object.entries(STATUS_LABELS).map(([value, label]) => ({ + value, + label: i18n._(label), + })), + ]; + // The main language first, unmarked; no tabs at all for one language. + const languages = [ + site.defaultLocale, + ...site.locales.filter((code) => code !== site.defaultLocale), + ]; return ( - {newLabel} + {addLabel} } /> -
- - - Type - - filter('kind', event.currentTarget.value)} - > - {t`All`} - {kinds.map((entry) => ( - - {active.kinds[entry]?.label ?? entry} - - ))} - - - filter('locale', value)} - locales={site.locales} - defaultLocale={site.defaultLocale} - /> - - - Status - - +
+ filter('status', event.currentTarget.value)} - > - {t`All`} - {Object.entries(STATUS_LABELS).map(([value, label]) => ( - - {i18n._(label)} - - ))} - - + onChange={(value) => filter('status', value)} + /> +
+
+
+ {languages.length < 2 ? null : ( + ({ + value: code, + label: languageName(code), + }))} + value={locale} + onChange={(value) => + filter('locale', value === site.defaultLocale ? '' : value) + } + /> + )}
+ {copied === '' ? null : ( +

+ {copied} +

+ )} + {loading ? (

Loading… @@ -195,13 +246,16 @@ export function ContentListPage(): JSX.Element { @@ -213,14 +267,20 @@ export function ContentListPage(): JSX.Element { - Create the first page + {kind === '' ? ( + Create the first page + ) : ( + Add the first {typeName} + )} } > - {locale === site.defaultLocale ? ( + {locale !== site.defaultLocale ? ( + Nothing has been written in {language} yet. + ) : kind === '' ? ( This site has no content yet. ) : ( - Nothing has been written in {language} yet. + There is no {typeName} yet. )} ) : ( @@ -231,19 +291,23 @@ export function ContentListPage(): JSX.Element { Title - {/* Below `md` a row is the title with its type and status - under it; Path and Updated are left out on purpose (U6). */} - - Type - + {/* Only where types are mixed: inside a type's own list + the sidebar already says which it is. */} + {kind === '' ? ( + + Type + + ) : null} Status - Path + Last edited - - Updated + + + Actions + @@ -264,38 +328,72 @@ export function ContentListPage(): JSX.Element { ); const statusBadge = ; + const edited = ( + + ); + const editHref = `/content/${item.id}?kind=${encodeURIComponent(item.kind)}`; return ( {item.title} - {typeCell} + {kind === '' ? typeCell : null} {statusBadge} + {edited} - - {typeCell} - + {kind === '' ? ( + + {typeCell} + + ) : null} {statusBadge} - - - {item.path} - + + {edited} - - + + + + + + + + + Edit + + + {item.status === 'published' ? ( + + + View on site + + + ) : null} + copyAddress(item)}> + Copy address + + + ); diff --git a/src/admin/pages/editor.tsx b/src/admin/pages/editor.tsx index 263ed23..23fd55b 100644 --- a/src/admin/pages/editor.tsx +++ b/src/admin/pages/editor.tsx @@ -180,6 +180,8 @@ function Editor({ ? fresh.kind : (Object.keys(site.kinds)[0] ?? 'page')), ); + /** This type's list, named as the sidebar names it. */ + const listName = active.kinds[kind]?.label ?? kind; /** The language this item is written in. */ const locale = loaded?.locale ?? @@ -401,7 +403,9 @@ function Editor({ ); } if (loaded === null) { - navigate(`/content/${result.id}`, { replace: true }); + navigate(`/content/${result.id}?kind=${encodeURIComponent(kind)}`, { + replace: true, + }); } } catch (caught) { notify(caught instanceof ApiError ? caught.message : t`Could not save.`); @@ -524,14 +528,17 @@ function Editor({ @@ -847,7 +854,11 @@ function TranslationBar(props: { type="button" variant="outline" size="sm" - onClick={() => navigate(`/content/${slot.id}`)} + onClick={() => + navigate( + `/content/${slot.id}?kind=${encodeURIComponent(props.kind)}`, + ) + } > {slotLanguage} diff --git a/test/admin/format.test.ts b/test/admin/format.test.ts index c0b55a9..5b2d837 100644 --- a/test/admin/format.test.ts +++ b/test/admin/format.test.ts @@ -1,6 +1,7 @@ import { i18n } from '@lingui/core'; import { afterAll, describe, expect, it } from 'vitest'; import { formatDuration, formatNumber } from '../../src/admin/format.js'; +import { formatLastEdited } from '../../src/admin/format-relative.js'; /** * Formatting follows the interface language, never the machine's locale, @@ -25,4 +26,29 @@ describe('formatting in the interface language', () => { expect(formatDuration(300)).toBe('5分钟'); expect(formatNumber(600000)).toBe('600,000'); }); + + it('says when something was edited the way a list of recent work reads', () => { + const now = new Date(2026, 10, 19, 15, 0); + i18n.loadAndActivate({ locale: 'en', messages: {} }); + expect(formatLastEdited(new Date(2026, 10, 19, 7, 12), now)).toBe( + 'Today 07:12', + ); + expect(formatLastEdited(new Date(2026, 10, 18, 23, 59), now)).toBe( + 'Yesterday 23:59', + ); + expect(formatLastEdited(new Date(2026, 10, 16, 9, 0), now)).toBe( + '3 days ago', + ); + expect(formatLastEdited(new Date(2026, 10, 12, 9, 0), now)).toBe( + 'Nov 12, 2026', + ); + i18n.loadAndActivate({ locale: 'zh-CN', messages: {} }); + expect(formatLastEdited(new Date(2026, 10, 19, 7, 12), now)).toBe( + '今天 07:12', + ); + expect(formatLastEdited(new Date(2026, 10, 18, 8, 5), now)).toBe( + '昨天 08:05', + ); + expect(formatLastEdited(new Date(2026, 10, 16, 9, 0), now)).toBe('3天前'); + }); }); diff --git a/test/e2e/02-login.spec.ts b/test/e2e/02-login.spec.ts index 6480d05..c4625db 100644 --- a/test/e2e/02-login.spec.ts +++ b/test/e2e/02-login.spec.ts @@ -25,7 +25,10 @@ test('refuses the wrong password without saying which half was wrong', async ({ test('signs in and reaches the content list', async ({ page }) => { await signIn(page); - await expect(page.getByRole('heading', { name: 'Content' })).toBeVisible(); + // Every type's list, until Home exists (docs/ADMIN_SIMPLE.md, D1, D2). + await expect( + page.getByRole('heading', { name: 'All content' }), + ).toBeVisible(); // The starter's pages are there, so this is the real list and not an empty // shell that happens to render. await expect(page.getByRole('row').first()).toBeVisible(); diff --git a/test/e2e/03-publish.spec.ts b/test/e2e/03-publish.spec.ts index c548918..b5c8ee1 100644 --- a/test/e2e/03-publish.spec.ts +++ b/test/e2e/03-publish.spec.ts @@ -69,7 +69,7 @@ test('writes and publishes a page that is immediately public', async ({ page, }) => { await signIn(page); - await page.getByRole('button', { name: 'New' }).click(); + await page.getByRole('button', { name: 'Add content' }).click(); // `page` is one of the two kinds the core always has (docs/ARCHITECTURE §8). await page.getByRole('combobox', { name: /^Type/ }).selectOption('page'); @@ -119,7 +119,7 @@ test('shows an edit on the public page, once the cache lets it', async ({ test('keeps a draft off the public site', async ({ page }) => { await signIn(page); - await page.getByRole('button', { name: 'New' }).click(); + await page.getByRole('button', { name: 'Add content' }).click(); await page.getByRole('combobox', { name: /^Type/ }).selectOption('page'); await page @@ -137,7 +137,7 @@ test('a published page is updated or unpublished, never saved back to a draft', page, }) => { await signIn(page); - await page.getByRole('button', { name: 'New' }).click(); + await page.getByRole('button', { name: 'Add content' }).click(); await page.getByRole('combobox', { name: /^Type/ }).selectOption('page'); await page .getByRole('textbox', { name: 'Title', exact: true }) diff --git a/test/e2e/05-accessibility.spec.ts b/test/e2e/05-accessibility.spec.ts index 72501c7..8dd6fe2 100644 --- a/test/e2e/05-accessibility.spec.ts +++ b/test/e2e/05-accessibility.spec.ts @@ -92,6 +92,8 @@ async function scan( /** Every screen of the admin, scanned in each interface language. */ const ADMIN_SCREENS = [ ['content list', '/_mallok/app/'], + // A type's own list: status and language tabs, search, row menus (D2). + ['product list', '/_mallok/app/content?kind=product'], ['media', '/_mallok/app/media'], ['plugins', '/_mallok/app/plugins'], ['plugin panel', '/_mallok/app/plugins/inquiry/inquiries'], @@ -134,7 +136,7 @@ test.describe('the admin', () => { page, }) => { await signIn(page); - await page.getByRole('button', { name: 'New' }).click(); + await page.getByRole('button', { name: 'Add content' }).click(); await expect(page.locator('#fm-title')).toBeVisible(); // The form appears before the debounced preview is rendered. Scanning diff --git a/test/e2e/11-lazy-remount.spec.ts b/test/e2e/11-lazy-remount.spec.ts index c371533..fd6f64d 100644 --- a/test/e2e/11-lazy-remount.spec.ts +++ b/test/e2e/11-lazy-remount.spec.ts @@ -29,7 +29,11 @@ test('the editor opens for a second item in the same session', async ({ // Back to the list without a reload, then a different item: the editor // route mounts again with its code already loaded. - await page.getByRole('link', { name: 'Content' }).first().click(); + // The pages' list, from its sidebar entry (docs/ADMIN_SIMPLE.md, D2). + await page + .locator('[data-sidebar="sidebar"]') + .getByRole('link', { name: 'Page', exact: true }) + .click(); await expect(links.nth(1)).toBeVisible(); await links.nth(1).click(); await expect(page.locator('.cm-content')).toBeVisible(); diff --git a/test/e2e/13-editor-untouched.spec.ts b/test/e2e/13-editor-untouched.spec.ts index 6f60c11..cb5de40 100644 --- a/test/e2e/13-editor-untouched.spec.ts +++ b/test/e2e/13-editor-untouched.spec.ts @@ -19,7 +19,11 @@ const CRLF = /** Opens an item from inside the app, as a click in the list would. */ async function openInSession(page: Page, id: string): Promise { - await page.getByRole('link', { name: 'Content' }).first().click(); + // A type's list, from its sidebar entry (docs/ADMIN_SIMPLE.md, D2). + await page + .locator('[data-sidebar="sidebar"]') + .getByRole('link', { name: 'Page', exact: true }) + .click(); await expect( page.locator('a[href^="/_mallok/app/content/"]').first(), ).toBeVisible(); diff --git a/test/e2e/17-shell.spec.ts b/test/e2e/17-shell.spec.ts index 426f853..e55f533 100644 --- a/test/e2e/17-shell.spec.ts +++ b/test/e2e/17-shell.spec.ts @@ -25,7 +25,9 @@ async function clean(page: Page, label: string): Promise { } const SECTIONS = [ - ['Content', '/_mallok/app/'], + // One entry per content type (docs/ADMIN_SIMPLE.md, D2). + ['Page', '/_mallok/app/content?kind=page'], + ['Product', '/_mallok/app/content?kind=product'], ['Media', '/_mallok/app/media'], ['Plugins', '/_mallok/app/plugins'], ['General', '/_mallok/app/settings'], diff --git a/test/e2e/19-translation.spec.ts b/test/e2e/19-translation.spec.ts index 4a4560a..0f5b527 100644 --- a/test/e2e/19-translation.spec.ts +++ b/test/e2e/19-translation.spec.ts @@ -32,15 +32,16 @@ test('a translation made from the language bar joins the original', async ({ // An English page of its own: the starter's pages already have their // Chinese versions. const stamp = Date.now(); - await page.getByRole('button', { name: 'New' }).click(); + await page.getByRole('button', { name: 'Add content' }).click(); await page.getByRole('combobox', { name: /^Type/ }).selectOption('page'); await page .getByRole('textbox', { name: 'Title', exact: true }) .fill('Our mill'); await page.getByLabel('URL slug', { exact: true }).fill(`our-mill-${stamp}`); await page.getByRole('button', { name: 'Publish' }).click(); - await expect(page).toHaveURL(/\/content\/(?!new)[^/?]+$/); - const original = page.url().split('/content/')[1] ?? ''; + // The editor's address carries its type, for the sidebar (D2). + await expect(page).toHaveURL(/\/content\/(?!new)[^/?]+\?kind=page$/); + const original = page.url().split('/content/')[1]?.split('?')[0] ?? ''; const stored = await read(page, original); await page @@ -74,7 +75,9 @@ test('a translation made from the language bar joins the original', async ({ expect(translation.translationGroup).toBe(stored.translationGroup); // The editor is now on the new item, and its bar leads back. - await expect(page).toHaveURL(new RegExp(`/content/${created.id}$`)); + await expect(page).toHaveURL( + new RegExp(`/content/${created.id}\\?kind=page$`), + ); await expect( page .getByRole('navigation', { name: 'Translations' }) diff --git a/test/e2e/22-content-lists.spec.ts b/test/e2e/22-content-lists.spec.ts new file mode 100644 index 0000000..2126f69 --- /dev/null +++ b/test/e2e/22-content-lists.spec.ts @@ -0,0 +1,97 @@ +import { expect, test } from '@playwright/test'; +import { signIn } from './credentials.js'; + +/** + * A content type's list, as mainstream admins have it + * (docs/ADMIN_SIMPLE.md, D2, D3 and D8): one sidebar entry per type, status + * and language as tabs, a search by title, and a row's address in its menu + * rather than in a column. + */ + +test('a type has its own list, with tabs, search and a row menu', async ({ + page, + context, +}) => { + await context.grantPermissions(['clipboard-read', 'clipboard-write']); + await signIn(page); + const sidebar = page.locator('[data-sidebar="sidebar"]'); + await sidebar.getByRole('link', { name: 'Product', exact: true }).click(); + + await expect(page).toHaveURL(/\/_mallok\/app\/content\?kind=product$/); + await expect( + sidebar.getByRole('link', { name: 'Product', exact: true }), + ).toHaveAttribute('aria-current', 'page'); + await expect( + page.getByRole('heading', { level: 1, name: 'Product' }), + ).toBeVisible(); + await expect(page.getByRole('button', { name: 'Add Product' })).toBeVisible(); + // Inside one type's list neither the type nor the address is a column. + const table = page.getByRole('table'); + await expect(table.getByRole('columnheader', { name: 'Type' })).toHaveCount( + 0, + ); + await expect(table.getByRole('columnheader', { name: 'Path' })).toHaveCount( + 0, + ); + await expect( + table.getByRole('columnheader', { name: 'Last edited' }), + ).toBeVisible(); + await expect( + table.getByRole('link', { name: 'Grade 5 titanium bar' }), + ).toBeVisible(); + + // Search narrows by title, and the address keeps it. + await page + .getByRole('searchbox', { name: 'Search by title' }) + .fill('grade 5'); + await expect(page).toHaveURL(/q=grade\+5/); + await expect(table.getByRole('row')).toHaveCount(2); + await expect( + table.getByRole('link', { name: 'Grade 5 titanium bar' }), + ).toBeVisible(); + await page.getByRole('searchbox', { name: 'Search by title' }).fill(''); + await expect(page).not.toHaveURL(/q=/); + + // Status is a row of tabs; the starter has no drafts. + const status = page.getByRole('group', { name: 'Status' }); + await status.getByRole('button', { name: 'Draft' }).click(); + await expect(status.getByRole('button', { name: 'Draft' })).toHaveAttribute( + 'aria-pressed', + 'true', + ); + await expect(page.getByText(/matches these filters/)).toBeVisible(); + await page.getByRole('button', { name: 'Clear filters' }).click(); + await expect(page).toHaveURL(/\?kind=product$/); + + // The language by its name, without its code (D8). + const languages = page.getByRole('group', { name: 'Language' }); + await expect( + languages.getByRole('button', { name: 'English' }), + ).toHaveAttribute('aria-pressed', 'true'); + await languages.getByRole('button', { name: 'Chinese' }).click(); + await expect(page).toHaveURL(/locale=zh/); + await languages.getByRole('button', { name: 'English' }).click(); + + // A row's menu: edit, view, and the address to paste somewhere. + await page + .getByRole('button', { name: 'Actions for Grade 5 titanium bar' }) + .click(); + const menu = page.getByRole('menu'); + await expect(menu.getByRole('menuitem', { name: 'Edit' })).toBeVisible(); + await expect( + menu.getByRole('menuitem', { name: 'View on site' }), + ).toHaveAttribute('href', '/products/grade-5-titanium-bar'); + await menu.getByRole('menuitem', { name: 'Copy address' }).click(); + await expect( + page.getByRole('status').filter({ hasText: 'Copied' }), + ).toContainText('/products/grade-5-titanium-bar'); + + // The editor knows the list it came from. + await table.getByRole('link', { name: 'Grade 5 titanium bar' }).click(); + await expect(page).toHaveURL(/\/content\/[^/?]+\?kind=product$/); + await expect( + sidebar.getByRole('link', { name: 'Product', exact: true }), + ).toHaveAttribute('aria-current', 'page'); + await page.getByRole('button', { name: '← Product' }).click(); + await expect(page).toHaveURL(/\/content\?kind=product$/); +}); From f79e7341b14f56d6443e546cbc05ec1d2f0c24a2 Mon Sep 17 00:00:00 2001 From: JasonYv <233965174+JasonYv@users.noreply.github.com> Date: Thu, 19 Nov 2026 09:20:37 -0800 Subject: [PATCH 08/14] feat(admin): make the editor writing-first, with a toolbar and a panel MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The editor opened as three code panes, front matter first; an operator had to write YAML to set a date or a cover, type `![](images/…)` to show a photo, and could not delete a page (docs/ADMIN_SIMPLE.md, G1–G5, G10–G12; D4, D5 option A, D6). - The main column is the title, the text with a formatting toolbar (heading, bold, italic, lists, quote, link, image, table) and then the type's own fields as a card. The text shows the body only, in a proportional face with headings, quotes, emphasis, code and links drawn as they read; the `##` and `**` stay where they are typed. - One panel beside it holds what is not writing: the type of a new item, the summary, a publish date, a cover image, tags, and "Search and address" with the whole address and the URL slug. It closes to a rail and the browser remembers. - Images go into the text from the toolbar's media picker, or by dropping or pasting a file, which is uploaded as Media uploads it. - Preview is a button; at 1600 px and wider it opens beside the panel. - "More" holds View on site, "Edit source (Markdown)" — the whole stored document, as before — Unpublish and Delete. Both ask first and say what a visitor will see; Delete was read from the route: the row and its rendered copy go, images and other language versions stay, no redirect is written. The list's row menu has Unpublish and Delete too. - Language versions are named by language alone, "+ Chinese" to add one. - On a phone it is one column with the save buttons pinned at the bottom. The front matter is kept as the text it was: the body is joined back onto the original block, so an item opened and saved without a field edit is byte-identical; a field edit rewrites the block as before. 13-editor-untouched passes unchanged; a new 23-editor-content proves the block's bytes survive a text edit and undeclared keys a field edit. The More menu does not return focus to its button when it closes: an operator who chose "Edit source" and started typing lost the rest of the keystrokes to it, which 03-publish caught. Selectors: 03-publish edits the whole document through "Edit source" and reaches Unpublish and Delete through "More actions", reading both questions; 05-accessibility and 20-interface-language open the preview first; 12-attached-panel names the "Editor" region; 19-translation presses "Add the Chinese version" and finds "English"; 21-editor-layout is rewritten for the new layout with axe at 1440 and 390 px; 22 deletes and unpublishes from a row's menu. admin:size 168.0 KiB first load; the editor chunk is 34.9 KiB gzip and everything loaded on demand 484.4 KiB (+4.1). Co-Authored-By: Claude Opus 5.5 --- src/admin/components/markdown-editor.tsx | 264 ++++++++- src/admin/locales/en.po | 158 ++++- src/admin/locales/zh-CN.po | 158 ++++- src/admin/pages/content-list.tsx | 78 ++- src/admin/pages/editor.tsx | 712 +++++++++++++++++------ test/e2e/03-publish.spec.ts | 52 +- test/e2e/05-accessibility.spec.ts | 2 + test/e2e/12-attached-panel.spec.ts | 2 +- test/e2e/19-translation.spec.ts | 6 +- test/e2e/20-interface-language.spec.ts | 2 + test/e2e/21-editor-layout.spec.ts | 80 ++- test/e2e/22-content-lists.spec.ts | 45 ++ test/e2e/23-editor-content.spec.ts | 97 +++ 13 files changed, 1349 insertions(+), 307 deletions(-) create mode 100644 test/e2e/23-editor-content.spec.ts diff --git a/src/admin/components/markdown-editor.tsx b/src/admin/components/markdown-editor.tsx index 67cab18..d6d865e 100644 --- a/src/admin/components/markdown-editor.tsx +++ b/src/admin/components/markdown-editor.tsx @@ -17,9 +17,35 @@ import { useLingui } from '@lingui/react/macro'; import type { JSX } from 'react'; import { useEffect, useRef, useState } from 'react'; +/** + * What a toolbar can do to the text: each acts on the selection, or at the + * cursor, and changes nothing else (docs/ADMIN_SIMPLE.md, D5 option A). + */ +export interface MarkdownCommands { + /** Puts `before` and `after` around the selection, or `placeholder`. */ + readonly wrap: (before: string, after: string, placeholder: string) => void; + /** Starts every selected line with `prefix`; `1. ` counts up. */ + readonly prefixLines: (prefix: string) => void; + /** Puts `text` at the cursor, on lines of its own when `block` is set. */ + readonly insert: (text: string, block?: boolean) => void; +} + export interface MarkdownEditorProps { readonly value: string; readonly onChange: (value: string) => void; + /** + * `prose` is for writing: a proportional face, no line numbers, and + * headings and emphasis drawn as they will read. `source` is the whole + * document as it is stored (docs/ADMIN_SIMPLE.md, D4 and D5). + */ + readonly variant?: 'prose' | 'source'; + /** Called once the rich editor exists, with what a toolbar can ask of it. */ + readonly onReady?: (commands: MarkdownCommands) => void; + /** + * Files dropped or pasted into the text: uploaded by the caller, which + * answers with the relative path of each image it stored, in order. + */ + readonly onFiles?: (files: readonly File[]) => Promise; /** * Relative paths the body references but the bundle does not contain. Each * gets a marker on its own line — a missing file is a normal state, so it @@ -42,17 +68,62 @@ interface EditorHandle { */ function tokenTheme( editorView: typeof import('@codemirror/view').EditorView, + prose: boolean, ): ReturnType { return editorView.theme({ - '&': { - height: '100%', - fontSize: '14px', - color: 'var(--foreground)', - backgroundColor: 'var(--background)', - }, + ...(prose + ? { + '.cm-scroller': { + fontFamily: 'var(--font-sans)', + lineHeight: '1.75', + }, + '&': { + height: '100%', + fontSize: '16px', + color: 'var(--foreground)', + backgroundColor: 'var(--background)', + }, + '.cm-content': { + caretColor: 'var(--foreground)', + padding: '12px 0 48px', + }, + '.cm-line': { padding: '0 4px' }, + '.cm-md-h1': { fontSize: '1.6em', fontWeight: '700' }, + '.cm-md-h2': { fontSize: '1.35em', fontWeight: '700' }, + '.cm-md-h3, .cm-md-h4, .cm-md-h5, .cm-md-h6': { + fontSize: '1.15em', + fontWeight: '650', + }, + '.cm-md-quote': { + borderLeft: '3px solid var(--border)', + paddingLeft: '12px', + color: 'var(--muted-foreground)', + }, + '.cm-md-strong': { fontWeight: '700' }, + '.cm-md-em': { fontStyle: 'italic' }, + '.cm-md-code': { + fontFamily: 'var(--font-mono)', + fontSize: '0.9em', + backgroundColor: 'var(--muted)', + borderRadius: '4px', + }, + '.cm-md-link': { color: 'var(--primary)' }, + } + : { + '&': { + height: '100%', + fontSize: '14px', + color: 'var(--foreground)', + backgroundColor: 'var(--background)', + }, + }), '&.cm-focused': { outline: 'none' }, - '.cm-scroller': { fontFamily: 'var(--font-mono)' }, - '.cm-content': { caretColor: 'var(--foreground)' }, + ...(prose + ? {} + : { + '.cm-scroller': { fontFamily: 'var(--font-mono)' }, + '.cm-content': { caretColor: 'var(--foreground)' }, + }), '.cm-cursor, .cm-dropCursor': { borderLeftColor: 'var(--foreground)' }, '.cm-gutters': { color: 'var(--muted-foreground)', @@ -76,7 +147,8 @@ function tokenTheme( export function MarkdownEditor(props: MarkdownEditorProps): JSX.Element { const { t } = useLingui(); - const label = t`Markdown source`; + const prose = props.variant === 'prose'; + const label = prose ? t`Text` : t`Markdown source`; const host = useRef(null); const handle = useRef(null); const currentMissing = useRef([]); @@ -142,12 +214,72 @@ export function MarkdownEditor(props: MarkdownEditorProps): JSX.Element { }, provide: (field) => view.EditorView.decorations.from(field), }); + // Headings, quotes, emphasis, code and links drawn as they will read, + // from the text alone: the `##` and `**` stay where they are typed. + const proseField = state.StateField.define({ + create: (initial) => proseMarks(view, initial.doc.toString()), + update: (previous, transaction) => + transaction.docChanged + ? proseMarks(view, transaction.state.doc.toString()) + : previous, + provide: (field) => view.EditorView.decorations.from(field), + }); + const dropOrPaste = ( + files: readonly File[], + at: number | null, + editorView: import('@codemirror/view').EditorView, + ): boolean => { + const upload = latest.current.onFiles; + if (upload === undefined || files.length === 0) { + return false; + } + void upload(files).then((paths) => { + if (paths.length === 0) { + return; + } + const pos = at ?? editorView.state.selection.main.head; + const text = paths.map((path) => `![](${path})`).join('\n\n'); + editorView.dispatch({ + changes: { from: pos, insert: `\n${text}\n` }, + selection: { anchor: pos + text.length + 2 }, + }); + }); + return true; + }; const editor = new view.EditorView({ parent: host.current, state: state.EditorState.create({ doc: latest.current.value, extensions: [ - view.lineNumbers(), + ...(latest.current.variant === 'prose' + ? [ + proseField, + view.EditorView.domEventHandlers({ + drop: (event, editorView) => { + const files = Array.from(event.dataTransfer?.files ?? []); + const at = editorView.posAtCoords({ + x: event.clientX, + y: event.clientY, + }); + if (dropOrPaste(files, at, editorView)) { + event.preventDefault(); + return true; + } + return false; + }, + paste: (event, editorView) => { + const files = Array.from( + event.clipboardData?.files ?? [], + ); + if (dropOrPaste(files, null, editorView)) { + event.preventDefault(); + return true; + } + return false; + }, + }), + ] + : [view.lineNumbers()]), commands.history(), view.keymap.of([ ...commands.defaultKeymap, @@ -156,7 +288,7 @@ export function MarkdownEditor(props: MarkdownEditorProps): JSX.Element { lang.markdown(), missingField, view.EditorView.lineWrapping, - tokenTheme(view.EditorView), + tokenTheme(view.EditorView, latest.current.variant === 'prose'), // CodeMirror's editable element is a `role="textbox"` with no // label of its own, so a screen reader announced the whole // Markdown pane as an unnamed text box. The fallback textarea @@ -203,6 +335,51 @@ export function MarkdownEditor(props: MarkdownEditorProps): JSX.Element { }; setRich(true); handle.current.setMissing(latest.current.missing ?? []); + latest.current.onReady?.({ + wrap: (before, after, placeholder) => { + const range = editor.state.selection.main; + const selected = editor.state.sliceDoc(range.from, range.to); + const inner = selected === '' ? placeholder : selected; + editor.dispatch({ + changes: { + from: range.from, + to: range.to, + insert: `${before}${inner}${after}`, + }, + selection: { + anchor: range.from + before.length, + head: range.from + before.length + inner.length, + }, + }); + editor.focus(); + }, + prefixLines: (prefix) => { + const range = editor.state.selection.main; + const first = editor.state.doc.lineAt(range.from).number; + const last = editor.state.doc.lineAt(range.to).number; + const changes = []; + for (let number = first; number <= last; number++) { + const line = editor.state.doc.line(number); + const marker = + prefix === '1. ' ? `${number - first + 1}. ` : prefix; + changes.push({ from: line.from, insert: marker }); + } + editor.dispatch({ changes }); + editor.focus(); + }, + insert: (text, block = false) => { + const range = editor.state.selection.main; + const line = editor.state.doc.lineAt(range.from); + const before = + block && range.from > line.from ? '\n\n' : block ? '' : ''; + const insert = block ? `${before}${text}\n` : text; + editor.dispatch({ + changes: { from: range.from, to: range.to, insert }, + selection: { anchor: range.from + insert.length }, + }); + editor.focus(); + }, + }); })(); return () => { cancelled = true; @@ -238,7 +415,11 @@ export function MarkdownEditor(props: MarkdownEditorProps): JSX.Element { /> {rich ? null : (