Skip to content

feat(admin): make the admin simple to operate - #2

Merged
JasonYv merged 14 commits into
mainfrom
feat/admin-simple
Nov 21, 2026
Merged

JasonYv merged 14 commits into
mainfrom
feat/admin-simple

Conversation

@JasonYv

@JasonYv JasonYv commented Nov 21, 2026

Copy link
Copy Markdown
Collaborator

Implements docs/ADMIN_SIMPLE.md (phases 0–9): after signing in, the admin should be simple to operate, closer to mainstream CMS admins and less technical.

Changes

  • Overview home page: remaining setup steps (each with a "Set up" action), the latest inquiries and recently edited content.
  • Navigation by task: Overview and Inquiries on top; one entry per content kind (from the theme); Plugins moved under Settings. Page width follows the page (form / list / home / full), anchored left.
  • Content lists: status and language tabs, title search (q, escaped LIKE), a row menu (edit, view, copy URL, unpublish, delete), no Path column.
  • Writing-first editor: title field, a Markdown editor with a formatting toolbar, drag/paste image upload, a settings panel (summary, publish date, cover, tags, address). The front matter is preserved byte for byte when only the text changes; source editing lives in the ⋯ menu.
  • State-aware actions: Update/Unpublish for live content; unpublish and delete ask first.
  • Common case first: an advanced flag for theme and plugin fields ("More options"); inquiry plugin shows two settings up front; deployer details closed by default; API tokens moved to Advanced.
  • Inquiries read like an inbox: message column, status tabs, bulk actions only after selection, an empty-state sentence from the plugin catalog.
  • Theme options as lists: string[] and keyvalue option types; Atelier's three value|label ;; … options converted, legacy stored values still render the same.
  • Wording: plain wording across en/zh (e.g. Slug → URL slug / URL 别名).
  • Setup wizard: the site's main language starts from the theme's first locale.

Not done / deviations (ADMIN_SIMPLE §7.1)

  • No separate "Other content" entry; no "Publish now" for scheduled items; Atelier version not bumped (no asset changes).
  • Visual editor (Tiptap) was only measured, not adopted: 0/54 documents round-trip byte-identical, [[inquiry]] escaped in 8/22 pages, ~155 KiB gzip (§9.1). Decision deferred to 0.2.
  • The navigation editor described in ADMIN.md was never built; ADMIN.md now says so.

Verification

  • pnpm lint && pnpm typecheck && pnpm test && pnpm build && pnpm bundle:size && pnpm admin:size pass: 1510 unit tests; admin first load 168.0 KiB (limit 170); Worker 317.2 KiB.
  • pnpm test:e2e: 62 passed (new specs 22–24 for lists, editor front matter, home).

🤖 Generated with Claude Code

JasonYv and others added 14 commits November 19, 2026 07:42
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 <noreply@anthropic.com>
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 <noreply@anthropic.com>
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 <noreply@anthropic.com>
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 <noreply@anthropic.com>
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 <noreply@anthropic.com>
`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 <noreply@anthropic.com>
…s do

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 <noreply@anthropic.com>
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 <noreply@anthropic.com>
The first screen after sign-in was a table of every item; nothing said
that inquiries go nowhere until a recipient is set, or what to do first
(docs/ADMIN_SIMPLE.md, G7, D1). Overview is the admin's home now, first
in the sidebar, and where sign-in and the wizard's last screen land:

- "Finish setting up", derived from what the admin already loads and
  never stored: a required plugin setting left empty (the inquiry
  recipient), a custom domain, email sending, and content edited since
  setup. Each says why it matters and links to where it is done; the
  card goes with the last one.
- Each enabled plugin's own lists (Inquiries), newest five rows by the
  panel's columns, with a link to the whole list.
- "Recently edited", the five items changed last, with "All content".
- An Add menu with one entry per content type.

No figure is counted. The page loads on demand; the shell gains one
link. The steps live in the component so the translation macro sees them.

Selectors: 02-login reads Overview and its recent list; 03-publish,
05-accessibility and 19-translation reach "Add content" from the list of
every type; 21-editor-layout opens a page from the Page list;
05-accessibility scans Overview and the content list; 17-shell walks
Overview. A new 24-home sees the steps, follows "Fill in" to the inquiry
recipient, saves it, and sees that step gone.

admin:size 168.4 KiB first load.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
What a daily operator needs comes first, in their words; the rest is one
click away and nothing is removed (docs/ADMIN_SIMPLE.md, D9, G14–G18).

- Manifests may mark a field, a theme option or a plugin setting
  `"advanced": true`. The form generator draws such fields after the
  others in a closed "More options" block. It is optional and additive;
  a required field may not be marked, and the manifest is refused if one
  is. THEME_FORMAT.md §5.2 and §6 and PLUGIN_API.md §4 say so; a core
  test covers a manifest with and without it and a wrongly marked one.
- The inquiry plugin marks seven of its nine settings, keeping the
  recipient and the autoreply switch in view; its one secret, optional,
  sits in a closed "Optional keys" block.
- Plugins opens with "Plugins are added by whoever deploys the site" and
  that a change applies at once; the source paths are in a closed "For
  the person who deploys" block. Appearance does the same with
  ACTIVE_THEME, the asset path and the script list; the theme's name,
  content types and whether it injects scripts stay in view.
- General keeps the site name, taglines and domain in view; the address
  for images, and the switch that prefixes the main language and moves
  every address, are under "More options".
- Account says "Use a long password you use nowhere else" with the
  PBKDF2 figures under "Details"; API tokens move to Advanced.

Selectors: 09-plugin-secret-remove opens "Optional keys"; 18-locale-prefix
opens the languages' "More options"; 06-tokens, 13-editor-untouched and
23-editor-content mint their token under Advanced; the AC-PLUGIN-07 unit
test reads the new heading, and still finds the paths and the
no-upload sentence.

admin:size 168.0 KiB first load.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A plugin's list now behaves the way mainstream inboxes do, by three
generic rules and nothing special to one plugin (docs/ADMIN_SIMPLE.md
§6.3, G20):

- A filter on a field whose values the catalog names, with four values
  or fewer, is a row of tabs — All, New, Replied, Spam — not a select.
- An action on rows appears once a row is chosen, after "N selected:",
  instead of standing disabled; a download is always there.
- A long text cell is one line; the detail view has all of it, and a
  field shown in both is listed once there. (An `email` column already
  offered a mail link, in the row and in the detail.)

The inquiry plugin puts the message in its row, and a plugin catalog may
name `panels.<id>.empty`, what the panel says while it has no rows
(PLUGIN_API.md §7.8). The inquiry plugin says where inquiries come from,
in English and Chinese; Overview's card uses the same sentence.

Tests: a core test for the new key, the zh-CN catalog test for the
message column and the sentence; 20-interface-language chooses a row
before it reads an action's name.

admin:size 168.1 KiB first load.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Phase 8's spike, run in a throwaway directory and never added to the
repository: Tiptap 3.33.0 with its Markdown extension round-tripped 54
documents. None came back byte-identical; eight of the site's 22 pages
lose their `[[inquiry]]` embed to escaping; the long documents change in
many small ways; tables survive and raw HTML does not. The five packages
are 155.2 KiB gzip. The numbers and what adopting it would take are in
ADMIN_SIMPLE.md §9.1, for the owner's decision on 0.2's editor.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Atelier asked for its certifications as "a, b, c" and its stats and
capability features as "value|label ;; value|label" typed into one box;
one wrong separator changed the home page (docs/ADMIN_SIMPLE.md, G14,
D10a). Theme options may now be `string[]` or `keyvalue`, with the
controls content fields already have, and Atelier's three options use
them; its templates iterate the lists as they do a product's specs.

A site that saved the old strings keeps them: `src/core/theme-options.ts`
reads a string stored for a list option as the list it meant, when the
page is rendered and when Appearance shows the form, so the home page is
the same before and after — a core test renders the old strings and the
new defaults and compares them. THEME_FORMAT.md §6 says so.

Atelier's version is unchanged: no file under `assets/` changed, which is
what the version marks; bumping it would only move every asset address.

A list control's rows now each have a name ("Certifications, item 1"):
05-accessibility found them unnamed once Appearance showed one.

admin:size 168.1 KiB first load.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…m the theme

ADMIN.md is revised for what docs/ADMIN_SIMPLE.md built: the sidebar by
what the operator works on, Overview (§4.4), a list per content type
(§4.5), content languages by name, the writing-first editor and its
buttons (§6.1, §6.2), the plugin page's blocks and inbox rules (§10),
tokens under Advanced and the plain password note (§11, §12), list
options on Appearance (§4.1), and the first load (§13). It also says that
the navigation editor it listed is not built.

The setup wizard's main language starts as the first language the theme
has words for — English for every official theme — instead of the
language the wizard is read in, which offered a Chinese-speaking owner
Chinese as an export site's main language (D10b). 01-wizard still reads
English as the default.

The CHANGELOG's [Unreleased] section gains the work; ADMIN_SIMPLE.md is
marked implemented, with §7.1 recording each phase as built, where it
departed from the plan, and what is still the owner's.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@JasonYv
JasonYv merged commit 6ead5db into main Nov 21, 2026
3 checks passed
@JasonYv
JasonYv deleted the feat/admin-simple branch November 21, 2026 12:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant