domma-cms 1.16.1 → 1.16.2

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## [1.16.2] - 2026-10-29
+
+- Detailed (?) help for every Menu and Context Menu option, including card dropdown items, rails, floating panels, mobile behaviour, appearance, scope, placement and each supported context-menu action. Help opens on click or tap and supports keyboard dismissal.
+
 ## [1.16.1] - 2026-10-29
 
 - Menus: saving a menu that was changed somewhere else after you opened it (another tab, someone else, or by hand on the server) now warns you instead of quietly undoing that change. Choose to save over it, or load the latest version with your changes offered back as a draft. `GET /api/menus/:slug` returns a `revision`; `PUT` with it answers 409 when the menu has changed since.

package/admin/js/lib/context-menu-action-help.js

@@ -0,0 +1 @@
+export const CONTEXT_ACTION_HELP={navigate:"Open the destination entered in URL in the current browser tab. Use a site path for an internal page or an allowed full address for an external destination. This action does not depend on the element that was right-clicked. The item label and icon are set separately.",reload:"Reload the current page, like the browser Reload button. This refreshes the whole page rather than just a collection display. Any unsaved input may be lost according to the page own leave-page behaviour. No argument is needed.",back:"Go to the previous entry in the visitor browser history. This follows their browsing history, rather than a fixed parent page. The item is greyed out when there is no earlier history entry. Use Go to a URL instead when the destination must always be the same.",forward:"Move forward in the visitor browser history after they have navigated back. It is normally greyed out on an ordinary page load, because the browser does not expose a reliable forward-history position. No destination is configured here; it follows the visitor history.",print:"Open the browser print dialog for the current page. The visitor chooses the printer or a PDF destination where supported. Page print styles determine the printed layout. This does not automatically print, export collection data or save a document on the server.","copy-link":"Copy the current page URL to the clipboard, including its query string and fragment. This copies the address of the view, rather than the URL of a link under the pointer. The browser must allow clipboard access; a message reports whether copying succeeded.","site-search":"Open the built-in site search interface, whether its trigger is in the navbar or floating on the page. This searches the site rather than the nearest collection display. The item is greyed out when site search is unavailable. Configure its behaviour under Site Settings > Search.",copy:"Copy the currently selected text from the page or the editable field that was right-clicked. The item is greyed out when nothing is selected. It copies plain text rather than the entire entry or page. Clipboard access must be allowed by the browser.",cut:"Copy the selected text from the editable field that was right-clicked, then remove that selection from the field. The item is greyed out without a selection or outside an editable field. Read-only and disabled fields do not qualify. The text is removed only after clipboard copying succeeds.",paste:"Insert clipboard text at the selection or caret in the editable field that was right-clicked. This is unavailable outside editable fields. Browsers may refuse clipboard reads or ask for permission; if paste is blocked, the visitor is prompted to use Ctrl+V. It does not upload files or paste rich formatting.","select-all":"Select the contents of the editable field that was right-clicked. Outside a field, select the nearest collection region or page body. This selects text for a later operation; it does not automatically copy it, select collection records for a bulk action or change stored data.",filter:"Request filtering in the collection display that was right-clicked. The optional Field identifies a field to focus on; leave it empty for the display normal filter flow. This is greyed out outside a collection display. It affects the view, rather than changing or deleting entries.",search:"Open search for the collection display that was right-clicked. It narrows that display rather than searching the entire website. The item is greyed out outside a compatible collection display. No extra argument is needed. Use Open site search for a site-wide search interface.",sort:"Request sorting in the collection display that was right-clicked. The optional Field supplies the field name, such as price; leave it empty to use the display sorting flow. The item is greyed out outside a collection display. This changes presentation order, not the saved values in the entries.",export:"Request an export from the collection display that was right-clicked. Format supplies the requested export type, such as csv, subject to what that display supports. Leave it empty for its normal export choice. This is greyed out outside a collection display and does not export the entire website.","mark-as-spam":"Mark the collection entry under the right-click as spam. This requires an actual entry inside a collection display and permission to update collections. Flag field optionally supplies the marker field; leave it empty for the normal spam field. This writes to the entry. A red Destructive style alone does not add confirmation or permissions.","open-modal":"Render an existing content block and open it in a modal over the current page. Enter its saved Block name, such as contact-card. The block can provide content or a form without navigating away. It must be available to the visitor; this option does not create a new block.","run-action":"Run the saved CMS Action named by Action slug against the entry that was right-clicked. The click must be within an element carrying an entry ID. The visitor must be signed in and allowed by the Action Who can run it rule. The Action determines the changes made; choosing this menu item does not bypass its permissions."};

package/admin/js/lib/menu-item-help.js

@@ -0,0 +1 @@
+export const MENU_ITEM_HELP={Label:"The text visitors see for this menu item. Use a short, recognisable destination or action. This is independent of the URL and icon. A Tool may supply its own label until you customise it. Apply changes to this item, then Save the menu to keep them.",URL:"Where the item links: use a site path beginning with /, a # anchor, an https:// address or a mailto: address. Leave it empty for a parent that only groups sub-items. A Tool address identifies the Tool and is read-only here. Changing a label does not change its destination.",Icon:"Choose the symbol beside the label using Browse, or enter an icon name. A clear icon is particularly useful for rails that collapse to icons. Leaving it empty gives a text-only link. Choosing an icon does not affect the destination or who can see the item.",Visibility:"Choose who sees this item. Everyone and Public include logged-out visitors. A role and above includes more senior roles; Role only includes that role and the super-admin. Private is super-admin only. Permission is an additional gate and both must pass. Locked sidebar Tools keep their required visibility. Hiding a link does not secure its destination.",Permission:"Show this item only when the viewer holds the selected permission. This works alongside Visibility, so both checks must pass. Leaving it empty adds no item-specific permission gate. Tools retain their own permission and cannot have that requirement removed here. The destination still needs its own access controls.","Badge text":"Add a short badge beside the label, such as New or Beta. Leave it empty for no text badge. Badge count from can supply a live collection count instead of a fixed label. Keep the words short so the menu remains easy to scan; Badge colour changes the badge appearance.","Badge count from":"Choose a collection whose entry count supplies a live badge beside this item. This is useful for a navigation link to a collection. Leave it on None for no count. It changes the badge only, not the item destination or access permissions. A text badge can be supplied separately.","Badge colour":"Choose a theme colour for this item badge, or Custom for a fixed hex colour. Theme colours follow the active theme. Leaving it unset uses the normal badge styling. This has no effect unless the item has badge text or a count, and does not change the link text colour.","Render as":"Link uses the normal navigation link. Pill draws a rounded button-like item so a call to action stands out. Pill styling applies to top-level navbar items and reveals Pill style and Pill colour below. The destination, permissions and label remain the same whichever appearance you choose.","Pill style":"Filled gives a pill item a solid coloured surface. Outline uses a border with a quieter interior. This applies when Render as is Pill and is intended for top-level navbar items. Choose Pill colour separately, then check contrast with the navbar background and the label.","Pill colour":"Choose the colour of this item pill, using a theme colour or a fixed custom hex colour. It applies when Render as is Pill; it does not colour every item in the menu. Leaving it unset uses the normal pill styling. Text colour and highlight colour are separate controls.","Text colour":"Override this item label colour with a theme colour or a custom hex colour. Leave it unset to inherit the menu text colour. This affects the item rather than the whole bar, badge or card icon tile. Check readability against the bar surface in normal, hovered and selected states.","Hover effect":"Override the menu-wide pointer effect for this item. Use the menu default inherits the Behaviour tab; None explicitly turns the effect off for this item. Other choices add the named highlight while the pointer is over it. This is separate from the marker for the page currently being viewed. Colour change tints the text; Underline and Overline add a line below or above it; Background tint adds a coloured wash; Darkened darkens the item; Uppercase changes letter case; Grow enlarges it; Breathe pulses its scale; Glow adds a soft glow. None leaves it still.","When selected":"Choose how this item is marked when it points to the page being viewed. Use the menu default inherits the menu-wide selected effect; None explicitly removes it for this item. This helps visitors locate themselves in the navigation. It is separate from hover feedback and does not change the URL. Bold increases text weight; Underline and Overline add a line; Background tint adds a wash; Darkened darkens the link; Filled pill encloses it in a rounded surface. None removes the selected marker.","Highlight colour":"Override the colour used by this item hover and selected effects. Leave it empty to use the menu-wide highlight colour, or choose a theme colour or custom hex colour. This does not enable an effect by itself and is separate from Text colour, Pill colour and Badge colour.","CSS classes":"Add class names separated by spaces to this item outer list element, for example nav-cta push-right. Write the matching rules in Custom CSS; target its link with .nav-cta > a. Enter names without leading dots or CSS declarations. Menu-wide classes are set separately on the Behaviour tab.",Description:"A short supporting line beneath this item label inside a Cards dropdown. Use it to explain the destination without making the label long. It is not the menu administrative description. Leave it empty for a label-only entry. This field is used when Dropdown style is Cards on the Behaviour tab.","Tile colour":"Override the background colour of this item icon tile inside a Cards dropdown. The item choice wins over the menu-wide Icon tiles setting, including its rainbow sequence. Leave it unset to inherit that setting. This does not set the label, badge or card side-box colour.","Card heading":"A short heading above the entries in this top-level item Cards dropdown. It is shown in small capitals and is separate from the top-level navigation label. Leave it empty to omit the heading. This applies to the card panel, not the headings of nested groups.","Link text":"The visible words for the card heading link, such as View all services. Supply its destination in Link URL as well. This link belongs to the dropdown card header; it is separate from the parent navigation item URL. Leave both fields empty when the card does not need a header link.","Link URL":"The destination of the card header link. Pair it with Link text so the visitor has words to click. Use a site path or an allowed external destination. This does not change the parent menu item destination or any individual entry link inside the dropdown.",Columns:"Choose one to four columns for entries in this Cards dropdown. Automatic lets the layout choose. More columns can help a large menu scan quickly, but need space for labels and descriptions. This controls the dropdown card entries, not the site page grid or the footer layout.","Chip strip label":"Words introducing the compact links at the bottom of this Cards dropdown, such as Popular tools. Select Show as a small chip on the sub-items that should appear there. Leaving this label empty omits the introductory words. This is separate from a badge on an individual item.","Side box":"Add a feature box down the right side of this Cards dropdown, using a dark, light or theme-coloured surface. It can hold headings, points and a button, configured below. No side box hides it while leaving the rest of the card. Use it for a focused call to action or a short supporting message.","Box small heading":"A short introductory line above the side-box title, such as Free consultation. It is separate from the main card heading and only appears when the card side box is enabled. Leave it blank when the title needs no introduction. Keep it brief so the box remains easy to scan.","Box title":"The main headline in the card side box, such as See it live. It is separate from the navigation label and card heading. Use it to state the offer or purpose of the box. Supporting points and an optional button can be supplied below. This requires a Side box style.","Box points":"Add one short supporting point per line, up to six. These appear as a list in the card side box beneath its heading. Use them for benefits or useful facts and leave empty for no list. They do not create menu links; the optional button has its own destination.","Button text":"The words on the side-box call-to-action button, such as Book a demo. Supply Button URL as well so the button has a destination. This belongs to the card feature box, rather than the card header link or parent navigation item. Leave both button fields empty for no button.","Button URL":"The destination of the card side-box button. Pair it with Button text, using a site path or allowed external address. This changes the feature-box call to action only. It does not alter the card header link, parent item or other entries in the dropdown."};

package/admin/js/templates/context-menu-editor.html

@@ -41,31 +41,31 @@
                     <div class="cmx-grid">
                         <div>
                             <label class="form-label" for="ctx-name">Name <span class="text-danger">*</span>
-                                <span data-help="Your label for this menu in the admin list. Visitors never see it."></span></label>
+                                <span data-help-title="Name" data-help="Give the context menu a recognisable name for the admin list and editor. Visitors do not see this name in the right-click menu. It is separate from the visible text of each item. Use a name that describes the region and purpose, such as Product card actions."></span></label>
                             <input class="form-input" id="ctx-name" type="text" maxlength="80" placeholder="Entry actions" data-model="name.value">
                             <small class="cmx-err" data-bind-hidden="!err.value.name" data-bind-text="err.value.name"></small>
                         </div>
                         <div>
                             <label class="form-label" for="ctx-slug">Slug
-                                <span data-help="The filename this menu is saved as. Made from the name as you type; fixed once created, because the file is the record."></span></label>
+                                <span data-help-title="Slug" data-help="The unique filename used to save this menu. A slug is suggested from its name while you create it, and uses lowercase letters, digits and hyphens. It is fixed after creation because it identifies the saved record. Changing the display name later does not rename this file."></span></label>
                             <input class="form-input font-mono" id="ctx-slug" type="text" maxlength="64" placeholder="entry-actions" data-model="slug.value" data-bind-disabled="notNew">
                             <small class="cmx-err" data-bind-hidden="!err.value.slug" data-bind-text="err.value.slug"></small>
                             <small class="cmx-hint" data-bind-hidden="!notNew">Fixed - it is the file's name.</small>
                         </div>
                         <div class="cmx-wide">
                             <label class="form-label" for="ctx-selector">Container selector <span class="text-danger">*</span>
-                                <span data-help-title="Container selector" data-help="A CSS selector for the region, e.g. #product-grid, .entry-card or main. Right-clicks anywhere inside it are offered to this menu. body, html, * and :root are refused, because they would swallow every other menu on the page."></span></label>
+                                <span data-help-title="Container selector" data-help="Enter a CSS selector for the region that should answer a right-click, such as #product-grid, .entry-card or main. The selector must match real elements on the public page. The innermost matching context menu wins when regions overlap. Whole-document selectors such as body, html, * and :root are refused so other menus remain usable."></span></label>
                             <input class="form-input font-mono" id="ctx-selector" type="text" placeholder="#product-grid" data-model="selector.value">
                             <small class="cmx-err" data-bind-hidden="!err.value.selector" data-bind-text="err.value.selector"></small>
                         </div>
                         <div>
                             <label class="form-label" for="ctx-match">Match <small class="cmx-hint-inline">(optional)</small>
-                                <span data-help="Narrows it: only claim the click when it landed on something matching this, e.g. [data-entry-id] to answer on rows but not the space between them. Blank means the whole container."></span></label>
+                                <span data-help-title="Match (optional)" data-help="Optionally narrow the active part of the container with another CSS selector, such as [data-entry-id] for entry rows. Right-clicks on matching elements or their contents can open the menu; the gaps between them do not. Leave this blank to use the entire container. This does not change the page scope."></span></label>
                             <input class="form-input font-mono" id="ctx-match" type="text" placeholder="[data-entry-id]" data-model="match.value">
                         </div>
                         <div>
                             <label class="form-label" for="ctx-exclude">Exclude <small class="cmx-hint-inline">(optional)</small>
-                                <span data-help="Holes in the region. A right-click on one of these falls through to whatever encloses it - useful for links and inputs, where the browser's own menu is more use."></span></label>
+                                <span data-help-title="Exclude (optional)" data-help="Enter CSS selectors for elements inside the container that should not open this menu, for example a, button, input. A right-click there can fall through to an enclosing context menu or the browser menu. Use this to preserve link and text-editing actions. Leave it blank when the whole matched region should answer."></span></label>
                             <input class="form-input font-mono" id="ctx-exclude" type="text" placeholder="a, button, input" data-model="exclude.value">
                         </div>
                     </div>
@@ -76,7 +76,7 @@
                     <div class="cmx-grid">
                         <div class="cmx-wide">
                             <label class="form-label" for="ctx-inherit">When nested inside another menu
-                                <span data-help="Show my items, then theirs puts the outer menu's items after yours; the reverse puts them before; Show only my items hides the outer menu's."></span></label>
+                                <span data-help-title="When nested inside another menu" data-help="Choose what happens when this context menu is nested inside another menu region. Show my items, then theirs puts this menu first and the outer menu afterwards. Show their items, then mine reverses that order. Show only my items excludes the outer menu. The innermost matching menu still decides how the click is handled."></span></label>
                             <select class="form-select" id="ctx-inherit" data-model="inherit.value">
                                 <option value="append">Show my items, then theirs (default)</option>
                                 <option value="prepend">Show their items, then mine</option>
@@ -85,7 +85,7 @@
                         </div>
                         <div class="cmx-setting cmx-wide">
                             <label class="form-label" for="ctx-enabled">Enabled
-                                <span data-help="Off parks a menu without deleting it. A disabled menu is never sent to the browser."></span></label>
+                                <span data-help-title="Enabled" data-help="Switch this menu on or off without deleting its settings or items. An off menu is not sent to public pages and cannot answer right-clicks. Other matching menus or the browser menu can still respond. Save after changing this switch. The list also offers an on/off action for an existing menu."></span></label>
                             <input type="checkbox" class="form-switch" id="ctx-enabled" data-model="enabled.value">
                         </div>
                     </div>
@@ -116,7 +116,7 @@
                     <div class="cmx-grid">
                         <div>
                             <label class="form-label" for="ctx-accent">Accent
-                                <span data-help="Tints the border and the hover wash. Labels keep the theme's text colour so they stay readable."></span></label>
+                                <span data-help-title="Accent" data-help="Choose a theme colour for the menu border and the wash behind a hovered item. Primary is the main accent; Success, Danger, Warning and Info use those semantic theme colours. Labels keep the normal theme text colour. Leave Theme default selected to inherit the site styling. This does not make an action destructive."></span></label>
                             <select class="form-select" id="ctx-accent" data-model="accent.value">
                                 <option value="">Theme default</option>
                                 <option value="primary">Primary</option>
@@ -128,7 +128,8 @@
                             <small class="cmx-err" data-bind-hidden="!err.value.accent" data-bind-text="err.value.accent"></small>
                         </div>
                         <div>
-                            <label class="form-label" for="ctx-radius">Corner radius</label>
+                            <label class="form-label" for="ctx-radius">Corner radius
+                                <span data-help-title="Corner radius" data-help="Choose the rounding of the menu panel corners. Square removes rounding; Small through Extra large increase it. Default uses the component styling supplied by the theme. This only changes appearance, not item grouping or click behaviour. Use the preview to compare the panel against its shadow and surface."></span></label>
                             <select class="form-select" id="ctx-radius" data-model="radius.value">
                                 <option value="">Default</option>
                                 <option value="none">Square</option>
@@ -139,7 +140,8 @@
                             </select>
                         </div>
                         <div>
-                            <label class="form-label" for="ctx-transition">Transition</label>
+                            <label class="form-label" for="ctx-transition">Transition
+                                <span data-help-title="Transition" data-help="Choose how the context menu appears when opened. Default uses a scale effect; Fade changes opacity; Slide moves the panel into place; None opens it immediately. This changes the opening presentation, not what the items do. Use a restrained effect for menus visitors open frequently."></span></label>
                             <select class="form-select" id="ctx-transition" data-model="transition.value">
                                 <option value="">Default (scale)</option>
                                 <option value="fade">Fade</option>
@@ -148,7 +150,8 @@
                             </select>
                         </div>
                         <div>
-                            <label class="form-label" for="ctx-shadow">Shadow</label>
+                            <label class="form-label" for="ctx-shadow">Shadow
+                                <span data-help-title="Shadow" data-help="Choose the depth of the shadow behind the menu panel. None removes it; Small through Extra large give increasing separation from the page beneath. Default follows the component styling. This only affects appearance. Check the preview against your theme to keep the menu edge clear without making it distracting."></span></label>
                             <select class="form-select" id="ctx-shadow" data-model="shadow.value">
                                 <option value="">Default</option>
                                 <option value="none">None</option>
@@ -159,7 +162,8 @@
                             </select>
                         </div>
                         <div>
-                            <label class="form-label" for="ctx-density">Density</label>
+                            <label class="form-label" for="ctx-density">Density
+                                <span data-help-title="Density" data-help="Comfortable gives each context-menu item more space. Compact reduces row spacing so more actions fit in a smaller panel. This does not shorten labels or remove items. Comfortable is easier to scan and target; Compact can suit a longer menu. Review the preview before saving."></span></label>
                             <select class="form-select" id="ctx-density" data-model="density.value">
                                 <option value="">Comfortable</option>
                                 <option value="compact">Compact</option>
@@ -167,13 +171,13 @@
                         </div>
                         <div>
                             <label class="form-label" for="ctx-opacity">Opacity
-                                <span data-help="Below 100 the panel lets the page show through, with a blurred backdrop; text stays fully opaque. Much under 80 gets hard to read over busy content."></span></label>
+                                <span data-help-title="Opacity" data-help="Set the panel surface opacity from 20 to 100 percent. At 100 the panel is solid; lower values allow page content to show through with a blurred backdrop. Text stays fully opaque. Values much below 80 can be difficult to read over busy content. Leave it empty for the normal solid surface."></span></label>
                             <input class="form-input" id="ctx-opacity" type="number" min="20" max="100" placeholder="100" data-model="opacity.value">
                             <small class="cmx-err" data-bind-hidden="!err.value.opacity" data-bind-text="err.value.opacity"></small>
                         </div>
                         <div>
                             <label class="form-label" for="ctx-class">CSS classes
-                                <span data-help-title="CSS classes" data-help="Your own class names, separated by spaces, added to the menu panel - style them in Custom CSS. Each item can carry classes of its own too, in its editor."></span></label>
+                                <span data-help-title="CSS classes" data-help="Add your own CSS class names, separated by spaces, to the context-menu panel. Write the matching rules in Custom CSS. Enter names without leading dots, for example product-actions compact-menu. This does not add styles by itself. Individual items have a separate CSS classes field for more targeted styling."></span></label>
                             <input class="form-input" id="ctx-class" type="text" placeholder="brand-menu" autocomplete="off" spellcheck="false" data-model="className.value">
                         </div>
                     </div>
@@ -188,12 +192,12 @@
                     <div class="cmx-grid">
                         <div>
                             <label class="form-label" for="ctx-pages">Pages
-                                <span data-help="Comma separated URL paths. A trailing /* covers everything under it, so /shop/* covers the whole shop. Blank means every page."></span></label>
+                                <span data-help-title="Pages" data-help="Enter comma-separated URL paths or trailing wildcard patterns, for example /about, /shop/*. A trailing /* matches pages beneath that path. These rules add page matches alongside any project rules. Leave both Pages and Projects empty for site-wide availability. A page must still contain an element matching the Container selector before the menu can open."></span></label>
                             <input class="form-input font-mono" id="ctx-pages" type="text" placeholder="/shop/*, /about" data-model="pages.value">
                         </div>
                         <div>
                             <label class="form-label" for="ctx-projects">Projects
-                                <span data-help="Comma separated project slugs. The menu then applies only to pages belonging to those projects."></span></label>
+                                <span data-help-title="Projects" data-help="Enter comma-separated project slugs, such as core, shop. Pages belonging to any listed project can receive this menu; page-path rules can provide additional matches. Leave both scope fields empty to allow every page. This scope controls where the menu is available, rather than visitor permissions or which element is right-clicked."></span></label>
                             <input class="form-input font-mono" id="ctx-projects" type="text" placeholder="core, shop" data-model="projects.value">
                         </div>
                     </div>