- ClayJS
- Reference
- Plugins
- menu
menu
The menu plugin: an Edit switch and a menu for people who can edit, with undo, AI, the CMS, SEO, sharing details and an API to add your own items.
The menu plugin gives someone who can edit a way back into editing without the keyboard. Ask for it by name: ?plugins=menu.
What it draws#
A small dock in a corner, shown only to someone who can edit: a grip, an Edit switch that changes mode in one click through clay.setMode, and claygoo opening a menu. Everything it draws is clay="editor-ui", so nothing from it reaches the saved file, a sync frame, the dirty check or undo. It lives inside a shadow root, so the document’s own CSS cannot restyle it.
It loads in view mode too. Without it, ClayJS still answers Cmd+Shift+E (Ctrl+Shift+E elsewhere) for anyone who can edit, and the first time such a person opens the document it shows a note naming that shortcut. A document can build its own control instead; mark it clay-mode-toggle and the note stays away. A visitor’s draft gets neither, since a draft has nothing to switch.
Visitors never see it. A document that doesn’t want it leaves menu out of its plugins list. ?plugins=cms brings menu automatically, so a page that has its own control adds exclude=menu to the script URL.
Moving it#
Drag the grip to any corner, or focus it and use the arrow keys. The corner is remembered for this document in this browser.
The items#
The menu keeps a fixed order, whichever plugin loads first. Each item appears only when the page can use it:
| Item | Shown when |
|---|---|
| Undo and Redo | The page loads the undo plugin. They are greyed out in view mode and when there is nothing to undo or redo. |
| Open the CMS (Edit content) | The page loads the cms plugin and declares CMS rules. |
| Ask AI… (Cmd+J or Ctrl+J) | The page loads the ai-edit plugin. |
| Open the code editor | The host offers it, see For host authors. |
| SEO settings… | Always. |
| Who’s here | The host runs presence and someone else is here, or you can change the name your edits are signed with. |
| Keep Variant B, remove the others… | The document has two or more looks and you are in edit mode. |
| Duplicate as a new page | The host offers it. |
| Download a copy | Always. In edit mode the file is what a save would send now, unsaved edits included; in view mode it is the saved file. |
| Version history… | The host offers it. |
Choosing the CMS or Ask AI in view mode switches to edit first. If the switch needs a reload, the item runs once the page is back; if the switch is refused, the menu says why.
The host’s pages (code editor, duplicate, version history) open in a new tab, so unsaved work in this one stays put.
The footer names a starter template copy’s version. It says “This doc is at latest version” only after the check confirmed it, shows “Version x.y.z” when it could not tell, and offers the upgrade when there is one.
Who’s here#
Who’s here opens a panel listing the people on this document, with a count of anyone the host does not name. When the name your edits are signed with was chosen in this browser, Change lets you rename it in place.
A page that wants the faces always visible adds clay-menu-roster to <html>:
<html clay-menu-roster>
The roster then sits beside the dock and opens the same panel. Without the attribute the corner stays clear. Either way, the old corner roster is not drawn while the menu is on the page.
Looks#
A document can carry several looks for the same markup. Each look is one <style clay-variant> block in <head>, named by its value. The saved look is the first block without media="not all"; every other block carries that attribute, so the browser ignores it:
<style>/* show and hide rules every look shares */</style>
<style clay-variant="A">/* the saved look */</style>
<style clay-variant="B" media="not all">/* another look */</style>
<style clay-variant="C" media="not all">/* another look */</style>
With two or more blocks, ClayJS loads the menu for anyone who can edit, even when menu is not in the plugins list. A switcher sits left of the Edit switch, and left of the roster when the roster is shown: ‹ Variant B (2/3) ›. Visitors never see it, and they always get the saved look.
- In view mode the arrows preview a look without saving anything: the preview is an
editor-uicopy of that block, and the saved look is switched off in the CSSOM, not in the file. Use this look switches to edit and saves the previewed look. - In edit mode the arrows change the saved look. The choice moves
media="not all"from one block to another, so it saves, syncs and undoes like any other edit. - Keep (and the menu item Keep Variant B, remove the others…) asks first, then deletes the other looks and removes
clay-variantandmediafrom the kept block. The switcher goes away for good. Undo brings the looks back during the same edit session, and version history keeps them after that.
A script reads and drives the looks through clay.variants:
| Member | What it does |
|---|---|
list() | [{ name, label, active }], one per block, in document order. |
active | The saved look’s name. |
shown | The look on screen, which differs from active during a view-mode preview. |
preview(name) | Shows a look without saving; preview(null) returns to the saved look. |
choose(name) | Makes a look the saved one. Edit mode only: otherwise it returns { ok: false, code: "not-editing" }. |
keep() | Asks, then keeps the saved look and deletes the others. Resolves { ok: true }, or { ok: false, code: "cancelled" } when the dialog is closed. |
An unknown name returns { ok: false, code: "unknown-variant" }. Every change of look fires clay:variant-change on document with { active, shown } in detail. A <canvas> that reads its colours from custom properties draws again on that event.
A look changes how things look, never what is shown: keep show and hide rules in the first <style>, which every look shares, and give each element a class that names what it is, so every look has something to style.
SEO settings#
SEO settings… opens a full-width panel at the top of the page that pushes the document down, so nothing it covers is out of reach. It lets you control how the document appears in search results and shared link previews without editing <head> tags by hand.
The fields come first: Title and Description (with character counters at 60 and 160), Preview title, Preview description and Preview image. More search and social fields holds Canonical URL (a localhost address is refused with “A localhost address cannot be a canonical URL.”), Language, Image alt text, Site name, Social handle, and the Show in search results and Let search engines follow links checkboxes. It opens itself when an error or a conflict is inside it. Where the host supports uploads, Preview image has an upload button, and on hyperclay.com it notes “Uploaded images are public to anyone with the link.”; otherwise it asks you to “Paste the address of an image on the web.”
A link preview beside the fields shows the shared link’s image, title, description and host (taken from the canonical URL, or the current host when none is set).
On a page document (article[data-page]), Title follows the document’s first heading. Typing a title switches it to custom mode and writes <meta name="clay-seo-title-mode" content="custom"> to the head. Use the first heading then hands the title back to the first heading.
Opening or cancelling the panel changes nothing in the document. Done writes the head fields in one step through clay.undo.commit when the undo plugin is loaded. Cancel or Escape closes it.
While it is open, the panel’s height is published as --clay-seo-height. A full-viewport app whose body does not scroll subtracts it so its bottom stays reachable:
.app { height: calc(100dvh - var(--clay-seo-height, 0px)); }
Add your own items#
clay.menu.addItem({ id, label, run, badge, keys, disabled, href }) adds a menu item. Your items go in their own section above the footer, in the order you add them. A duplicate id replaces the earlier item in place, and clay.menu.removeItem(id) takes it away.
keysshows a shortcut beside the label. It only labels the item; the shortcut itself is yours to handle.disabledgreys it out and skips it with the arrow keys.hrefmakes it a link that opens in a new tab.badgeputs a dot on claygoo.
clay.menu.open() and clay.menu.close() drive the list from your own code. clay.menu.note(text) shows a short note beside claygoo for a few seconds; the plugin uses it to say why something was refused.
Across a mode change#
The menu has no lease of its own. It reads the mode at the moment something happens, on a document that switches without a reload as well as on one that reloads.
The Edit switch follows the committed mode, not the click. Every commit fires clay:modechange and the switch reads its state then, so a change that came from the keyboard, from another plugin’s lease, or from a page this menu did not start still lands on it. The switch is busy until the answer arrives, and a refused change puts it back and says why (Leaving edit).
The menu mounts when canEdit turns true, which the page announces as clay:capabilitychange. A document that gains the capability after boot gets the menu without a reload.
The SEO panel is read-only in view: its text fields are read-only and its checkboxes disabled, Done closes it without writing, and Edit these settings asks for edit mode. That button writes the reopen-seo receipt only for the reload path; a live entry keeps the page and the panel where they are.
For host authors#
The code editor, duplicate, version history, export and show-in-folder items come from the host. Add an actions object to the document block of GET /_/meta, naming only the pages this caller may open:
{
"document": {
"actions": {
"codeEditor": { "href": "/_/edit/notes/today.html" },
"versions": { "href": "/_/versions/notes/today.html" },
"duplicate": { "href": "/_/copy/notes/today.html" }
}
}
}
Each href resolves against the page and must be http: or https:; anything else is ignored. A host without the block shows none of them.
An action can ask the host to do something instead of opening a page. Name a same-origin URL with post:
{
"document": {
"actions": {
"reveal": { "post": "/_/reveal" },
"export": { "post": "/_/export" },
"versions": { "post": "/_/versions-folder" }
}
}
}
The menu sends a POST with the page’s cookies and a Document-URL header naming the page, and reads a JSON answer. { "ok": true } is done. { "ok": true, "href": "..." } also opens that address in a new tab, which is how a duplicate shows its copy. { "ok": false, "message": "..." } shows the message beside claygoo. A post on another origin is ignored.
The five names are codeEditor, duplicate, versions, export and reveal. The reveal item reads Show in Finder on a Mac, Show in Explorer on Windows, and Show in folder elsewhere. HTML Clay offers reveal, versions and export; Hyperclay Local offers all five. Answer it per caller, the same way the rest of the document block is answered, so the menu never offers a page that then refuses.