@kubex/zinc 1.1.100 → 1.1.102

package/docs/pages/components/remarkd-editor.md

@@ -157,6 +157,65 @@ outgrows the 20rem cap set here."
 ></zn-remarkd-editor>
 ```
 
+### Actions
+
+The toolbar and the `/` slash menu are driven by one shared registry of actions, grouped
+under ten headings: **Text**, **Inline**, **Lists**, **Admonitions**, **Blocks**,
+**Structured**, **Media**, **Objects**, **Breaks**, and **Logic**. The toolbar shows as
+many groups as fit its width and folds the rest into an overflow menu; the slash menu
+carries every action regardless of width, and typing narrows it by label or keyword — so
+a folded toolbar group is never actually out of reach.
+
+{% raw %}
+
+```html:preview
+<zn-remarkd-editor value='{{button:action text="Get started" href=/}}
+
+{{video:dQw4w9WgXcQ source=youtube}}
+
+{{reflist}}'></zn-remarkd-editor>
+```
+
+{% endraw %}
+
+### Inline Formatting
+
+Inline actions — Strong, Emphasis, Code, Underline, Strikethrough, Highlight, and the
+rest of the Inline group — apply to the current selection inside the block being edited,
+so they only make sense while a block is open: the toolbar disables them until one is
+(the slash menu lists them regardless, since it can only ever open inside a block in the
+first place). Choosing one from the toolbar wraps the selection in its mark, or — with
+nothing selected — inserts a placeholder inside the mark with the placeholder selected so
+typing replaces it; from the slash menu it always inserts the full construct with the
+caret collapsed at the start of the placeholder, since there is no selection to wrap.
+Choosing the same action again on a selection that already carries the mark unwraps it
+rather than nesting a second one.
+
+```html:preview
+<zn-remarkd-editor value="Click into this block, select a word, then choose Strong or Emphasis from the toolbar."></zn-remarkd-editor>
+```
+
+### Variables and Conditionals
+
+The Logic group's actions insert document attributes (`:name: value`) and remarkd's
+conditional directives (`ifdef`, `ifndef`, `ifeval`) — but the editor only ever *marks*
+them, it never evaluates them: an attribute line renders as a chip, a `{name}` reference
+in surrounding text renders as a token, and an `ifdef`/`ifndef`/`ifeval` range renders as
+a labelled wrapper whose content stays visible regardless of whether the flag is defined.
+Evaluating conditionals belongs to the renderer the finished document is published
+through, not to this editor — showing both branches of an if/else here means neither one
+ever disappears while you're still editing it.
+
+```html:preview
+<zn-remarkd-editor value=":product: Remarkd
+
+This documents {product}.
+
+ifdef::beta[]
+Only for the beta.
+endif::[]"></zn-remarkd-editor>
+```
+
 ### Form Integration
 
 `zn-remarkd-editor` is a [form control](/getting-started/form-controls); its

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubex/zinc",
-  "version": "1.1.100",
+  "version": "1.1.102",
   "description": "A collection of web components for building web applications based off of @shoelace-style/Shoelace",
   "keywords": [
     "web components",

package/src/components/menu/menu.component.ts

@@ -8,8 +8,8 @@ import ZnIcon from "../icon";
 import ZnMenuItem from "../menu-item";
 import ZnTooltip from "../tooltip";
 
-import styles from './menu.scss';
 import { classMap } from "lit/directives/class-map.js";
+import styles from './menu.scss';
 
 interface NavItem {
   title: string;
@@ -44,6 +44,8 @@ interface NavItem {
  * @csspart base - The component's base wrapper.
  *
  * @cssproperty --example - An example CSS custom property.
+ * @cssproperty --zn-menu-max-height - Caps the menu's height and makes it scroll internally.
+ *  Unset (`none`) by default, so the menu grows to fit its items unless a consumer sets this.
  */
 export default class ZnMenu extends ZincElement {
   static styles: CSSResultGroup = unsafeCSS(styles);
@@ -101,6 +103,7 @@ export default class ZnMenu extends ZincElement {
   render() {
     return html`
       <div
+        part="base"
         class="${classMap({
           'menu': true,
           'menu--shell': this.variant === 'shell',

package/src/components/menu/menu.scss

@@ -8,6 +8,9 @@
   border-radius: var(--zn-border-radius);
   width: fit-content;
   min-width: var(--zn-size-spanel);
+  // Unconstrained by default — a consumer that needs the menu to scroll inside a bounded
+  // popup (rather than growing to fit all its items) sets this custom property.
+  max-height: var(--zn-menu-max-height, none);
   overflow: auto;
   overscroll-behavior: none;
   box-shadow: 0 4px 8px -4px rgba(33, 33, 33, 0.1);

package/src/components/page/page.scss

@@ -14,6 +14,10 @@
   --zn-page-texture-size: auto;
   --zn-page-content-background: var(--zn-body);
   --zn-page-header-background: var(--zn-page-surface-background, var(--zn-page-background, var(--zn-body)));
+  // A modal shell overlays its own close button at --zn-base-gap from the page edge;
+  // these describe it so the header can keep clear of it.
+  --zn-page-closer-size: 36px;
+  --zn-page-closer-gap: var(--zn-spacing-x-small);
 }
 
 :host([panel]) {
@@ -151,6 +155,7 @@
     justify-content: space-between;
     gap: 2px;
     max-width: 100%;
+    min-width: 0;
     min-height: 36px;
 
     a {
@@ -168,14 +173,14 @@
     gap: var(--zn-spacing-x-small);
     min-height: 36px;
     flex-shrink: 1;
+    min-width: 0;
     max-width: 100%;
   }
 
   &__right {
     flex-grow: 1;
-    flex-shrink: 1;
+    flex-shrink: 0;
     overflow: hidden;
-    min-width: 20px;
   }
 
   &__caption {
@@ -198,6 +203,7 @@
   &__description {
     @include wc.text-style(subheading);
     display: block;
+    overflow-wrap: anywhere;
   }
 
   .breadcrumb {
@@ -367,6 +373,12 @@ zn-navbar {
   padding-inline: calc(var(--zn-gutter, 0) + var(--zn-base-gap, 0));
 }
 
+// The gutter shrinks to 0 on narrow containers, which would run the header actions
+// under the closer. Reserving the closer's own footprint holds the gap steady instead.
+:host([modal]) .header {
+  padding-inline-end: calc(var(--zn-base-gap, 0) + var(--zn-page-closer-size) + var(--zn-page-closer-gap));
+}
+
 :host zn-navbar {
   &::part(navbar) {
     padding-inline: calc(var(--zn-gutter, 0) + var(--zn-base-gap, 0));

package/src/components/remarkd-editor/actions.ts

@@ -0,0 +1,159 @@
+import type {SlashMenuItem} from '../slash-menu';
+
+export type ActionGroup =
+  'text' | 'lists' | 'admonitions' | 'blocks' | 'structured' | 'media' | 'objects' | 'breaks' | 'logic' | 'inline';
+
+/** What an inline action wraps the selection in. `after` defaults to `before`. */
+export interface InlineMark {
+  before: string;
+  after?: string;
+  placeholder?: string;
+}
+
+export interface EditorAction {
+  /** Stable id, used for toolbar keys and tests. */
+  key: string;
+  label: string;
+  icon: string;
+  group: ActionGroup;
+  /** Extra search terms for the slash menu, e.g. "bold" finds Strong. */
+  keywords?: string[];
+  /** Block actions: spliced in as a new block. */
+  prefix?: string;
+  /** Inline actions: applied to the selection in the open block. */
+  inline?: InlineMark;
+  /** Where the caret lands within `prefix`. Defaults to the end. */
+  caretOffset?: number;
+  /** Actions that open their own picker instead of inserting text. */
+  opens?: 'image' | 'include';
+}
+
+/** Toolbar order, most-used first — the last groups are the first to collapse. */
+export const ACTION_GROUPS: { id: ActionGroup; label: string }[] = [
+  {id: 'text', label: 'Text'},
+  // Bold/italic/code are the most-reached actions in any editor — kept right after Text so
+  // they are among the last groups to collapse, not the first.
+  {id: 'inline', label: 'Inline'},
+  {id: 'lists', label: 'Lists'},
+  {id: 'admonitions', label: 'Admonitions'},
+  {id: 'blocks', label: 'Blocks'},
+  {id: 'structured', label: 'Structured'},
+  {id: 'media', label: 'Media'},
+  {id: 'objects', label: 'Objects'},
+  {id: 'breaks', label: 'Breaks'},
+  {id: 'logic', label: 'Logic'},
+];
+
+export const EDITOR_ACTIONS: EditorAction[] = [
+  // Text
+  {key: 'text', label: 'Text', icon: 'text@lu', group: 'text', prefix: ''},
+  {key: 'paragraphs', label: 'Paragraph', icon: 'pilcrow@lu', group: 'text', prefix: ''},
+  {key: 'heading', label: 'Heading 1', icon: 'heading-1@lu', group: 'text', prefix: '# '},
+  {key: 'h2', label: 'Heading 2', icon: 'heading-2@lu', group: 'text', prefix: '## '},
+  {key: 'h3', label: 'Heading 3', icon: 'heading-3@lu', group: 'text', prefix: '### '},
+  {key: 'asciidoc-section', label: 'Section', icon: 'section@lu', group: 'text', prefix: '== '},
+  {key: 'attributes-title', label: 'Title', icon: 'captions@lu', group: 'text', prefix: '.'},
+
+  // Lists
+  {key: 'unordered-list', label: 'Bullet list', icon: 'list@lu', group: 'lists', prefix: '- ', keywords: ['bullet', 'ul']},
+  {key: 'ordered-list', label: 'Numbered list', icon: 'list-ordered@lu', group: 'lists', prefix: '1. ', keywords: ['ol']},
+  {key: 'checkboxes', label: 'Checklist', icon: 'list-todo@lu', group: 'lists', prefix: '- [ ] ', keywords: ['task', 'todo']},
+  {key: 'definition-list', label: 'Definition list', icon: 'book-a@lu', group: 'lists', prefix: 'Term:: Definition'},
+
+  // Admonitions
+  {key: 'admonition', label: 'Note', icon: 'info@lu', group: 'admonitions', prefix: 'NOTE: '},
+  {key: 'tip', label: 'Tip', icon: 'lightbulb@lu', group: 'admonitions', prefix: 'TIP: '},
+  {key: 'warning', label: 'Warning', icon: 'triangle-alert@lu', group: 'admonitions', prefix: 'WARNING: '},
+  {key: 'important', label: 'Important', icon: 'circle-alert@lu', group: 'admonitions', prefix: 'IMPORTANT: '},
+  {key: 'caution', label: 'Caution', icon: 'shield-alert@lu', group: 'admonitions', prefix: 'CAUTION: '},
+  {key: 'danger', label: 'Danger', icon: 'octagon-alert@lu', group: 'admonitions', prefix: 'DANGER: '},
+  {key: 'success', label: 'Success', icon: 'circle-check@lu', group: 'admonitions', prefix: 'SUCCESS: '},
+  {key: 'notice', label: 'Notice', icon: 'megaphone@lu', group: 'admonitions', prefix: 'NOTICE: '},
+
+  // Blocks — caretOffset lands inside the delimiters
+  {key: 'code-fence', label: 'Code', icon: 'code@lu', group: 'blocks', prefix: '```\n\n```', caretOffset: 4},
+  {key: 'blockquotes', label: 'Quote', icon: 'quote@lu', group: 'blocks', prefix: '____\n\n____', caretOffset: 5},
+  {key: 'verse', label: 'Verse', icon: 'feather@lu', group: 'blocks', prefix: '[verse]\n____\n\n____', caretOffset: 13},
+  {key: 'sidebar-block', label: 'Sidebar', icon: 'panel-right@lu', group: 'blocks', prefix: '****\n\n****', caretOffset: 5},
+  {key: 'example-block', label: 'Example', icon: 'square-dashed@lu', group: 'blocks', prefix: '====\n\n====', caretOffset: 5},
+  {key: 'literal-block', label: 'Literal', icon: 'file-code@lu', group: 'blocks', prefix: '....\n\n....', caretOffset: 5},
+  {key: 'listing-block', label: 'Listing', icon: 'terminal@lu', group: 'blocks', prefix: '----\n\n----', caretOffset: 5},
+  {key: 'generic-container', label: 'Container', icon: 'box@lu', group: 'blocks', prefix: '!!!!\n\n!!!!', caretOffset: 5},
+  {key: 'comments', label: 'Comment', icon: 'message-square-dashed@lu', group: 'blocks', prefix: '////\n\n////', caretOffset: 5},
+  {key: 'hardbreaks', label: 'Hard breaks', icon: 'wrap-text@lu', group: 'blocks', prefix: '[%hardbreaks]\n', keywords: ['line breaks']},
+
+  // Structured
+  {key: 'tabs', label: 'Tabs', icon: 'app-window@lu', group: 'structured', prefix: '_|_#first [name=First]\nFirst content', caretOffset: 16},
+  {key: 'steps', label: 'Steps', icon: 'list-checks@lu', group: 'structured', prefix: '_|- First step\nDo first', caretOffset: 4},
+  {key: 'callout-block', label: 'Callout', icon: 'message-square-code@lu', group: 'structured', prefix: '<1> '},
+
+  // Media
+  {key: 'asciidoc-image', label: 'Image', icon: 'image@lu', group: 'media', opens: 'image'},
+  {key: 'image-alignment', label: 'Aligned image', icon: 'image-plus@lu', group: 'media', prefix: '[.align-center]\nimage::file.png[Alt,640,480]', caretOffset: 23},
+  {key: 'video', label: 'Video', icon: 'video@lu', group: 'media', prefix: '{{video:ID source=youtube}}', caretOffset: 8},
+  {key: 'include', label: 'Include', icon: 'blocks@lu', group: 'media', opens: 'include'},
+  // The path placeholder is load-bearing: `t::partial::` with an empty path makes parse() throw.
+  {key: 'partial', label: 'Partial', icon: 'file-stack@lu', group: 'media', prefix: 't::partial::path/to/file.remarkd', caretOffset: 12},
+  {key: 'reference-list', label: 'Reference list', icon: 'book-marked@lu', group: 'media', prefix: '{{reflist}}'},
+
+  // Objects
+  {key: 'button-object', label: 'Button', icon: 'mouse-pointer-click@lu', group: 'objects', prefix: '{{button:action text="Label" href=/}}', caretOffset: 9},
+  {key: 'object-macros', label: 'Link object', icon: 'external-link@lu', group: 'objects', prefix: '{{link:https:// text=Label}}', caretOffset: 7},
+  {key: 'anchor', label: 'Anchor', icon: 'anchor@lu', group: 'objects', prefix: '{{anchor name=top}}', caretOffset: 14},
+  {key: 'meter', label: 'Meter', icon: 'gauge@lu', group: 'objects', prefix: '{{meter id=progress min=0 max=10 value=5}}', caretOffset: 11},
+  {key: 'object-attributes', label: 'Break object', icon: 'separator-horizontal@lu', group: 'objects', prefix: '{{br}}'},
+
+  // Breaks
+  {key: 'horizontal-rule', label: 'Divider', icon: 'minus@lu', group: 'breaks', prefix: '---', keywords: ['rule', 'hr']},
+  {key: 'page-break', label: 'Page break', icon: 'scissors-line-dashed@lu', group: 'breaks', prefix: '<<<'},
+  {key: 'line-continuation', label: 'Line continuation', icon: 'corner-down-left@lu', group: 'breaks', prefix: ' \\'},
+
+  // Logic — marked in the preview, never evaluated
+  {key: 'document-attributes', label: 'Variable', icon: 'variable@lu', group: 'logic', prefix: ':name: value', caretOffset: 1, keywords: ['attribute', 'variable']},
+  {key: 'conditionals', label: 'If defined', icon: 'git-branch@lu', group: 'logic', prefix: 'ifdef::flag[]\n\nendif::[]', caretOffset: 7},
+  {key: 'ifndef', label: 'If not defined', icon: 'git-branch-minus@lu', group: 'logic', prefix: 'ifndef::flag[]\n\nendif::[]', caretOffset: 8},
+  {key: 'iftrue', label: 'If true', icon: 'toggle-right@lu', group: 'logic', prefix: 'iftrue::flag[Shown]', caretOffset: 8},
+  {key: 'iffalse', label: 'If false', icon: 'toggle-left@lu', group: 'logic', prefix: 'iffalse::flag[Shown]', caretOffset: 9},
+  {key: 'ifempty', label: 'If empty', icon: 'square@lu', group: 'logic', prefix: 'ifempty::flag[Shown]', caretOffset: 9},
+  {key: 'ifnempty', label: 'If not empty', icon: 'square-check@lu', group: 'logic', prefix: 'ifnempty::flag[Shown]', caretOffset: 10},
+  {key: 'ifeval', label: 'If expression', icon: 'equal@lu', group: 'logic', prefix: 'ifeval::[1 > 0]\n\nendif::[]', caretOffset: 9},
+
+  // Inline — applied to the selection in the open block
+  {key: 'inline-formatting', label: 'Strong', icon: 'bold@lu', group: 'inline', keywords: ['bold'], inline: {before: '**', placeholder: 'text'}},
+  {key: 'emphasis', label: 'Emphasis', icon: 'italic@lu', group: 'inline', keywords: ['italic'], inline: {before: '__', placeholder: 'text'}},
+  {key: 'inline-code', label: 'Code', icon: 'square-code@lu', group: 'inline', inline: {before: '`', placeholder: 'code'}},
+  {key: 'underline', label: 'Underline', icon: 'underline@lu', group: 'inline', inline: {before: '___', placeholder: 'text'}},
+  {key: 'strike', label: 'Strikethrough', icon: 'strikethrough@lu', group: 'inline', keywords: ['delete'], inline: {before: '~~', placeholder: 'text'}},
+  {key: 'highlight', label: 'Highlight', icon: 'highlighter@lu', group: 'inline', keywords: ['mark'], inline: {before: '#', placeholder: 'text'}},
+  {key: 'subscript', label: 'Subscript', icon: 'subscript@lu', group: 'inline', inline: {before: '~', placeholder: '2'}},
+  {key: 'superscript', label: 'Superscript', icon: 'superscript@lu', group: 'inline', inline: {before: '^', placeholder: '2'}},
+  {key: 'keyboard', label: 'Keyboard', icon: 'keyboard@lu', group: 'inline', keywords: ['kbd', 'shortcut'], inline: {before: 'kbd:[', after: ']', placeholder: 'Ctrl+C'}},
+  {key: 'footnote', label: 'Footnote', icon: 'asterisk@lu', group: 'inline', inline: {before: 'footnote:[', after: ']', placeholder: 'Note'}},
+  {key: 'tooltip', label: 'Tooltip', icon: 'message-circle-question-mark@lu', group: 'inline', keywords: ['term'], inline: {before: '{', after: '}(Explanation)', placeholder: 'Term'}},
+  {key: 'cross-reference', label: 'Cross reference', icon: 'link-2@lu', group: 'inline', keywords: ['xref'], inline: {before: '<<', after: '>>', placeholder: 'section,Label'}},
+  {key: 'links-and-images', label: 'Link', icon: 'link@lu', group: 'inline', inline: {before: '[', after: '](https://)', placeholder: 'Label'}},
+  {key: 'passthrough', label: 'Passthrough', icon: 'shield@lu', group: 'inline', keywords: ['raw', 'literal'], inline: {before: 'pass:[', after: ']', placeholder: 'raw'}},
+  {key: 'curly-bang-passthrough', label: 'Literal braces', icon: 'braces@lu', group: 'inline', inline: {before: '{!', after: '!}', placeholder: 'raw'}},
+];
+
+/** The registry as slash menu entries. Picker actions insert nothing; the menu emits their action id. */
+export function slashItems(actions: EditorAction[]): SlashMenuItem[] {
+  const label = (id: ActionGroup) => ACTION_GROUPS.find(group => group.id === id)?.label;
+  return actions.map(action => {
+    if (action.opens) {
+      return {label: action.label, icon: action.icon, action: action.opens, group: label(action.group), keywords: action.keywords};
+    }
+    // Inline actions have no textarea selection to wrap from the slash menu, so insert the
+    // whole construct with the caret at the placeholder — a bare `before` would leave the
+    // mark unclosed (`**` with nothing selected to wrap).
+    const {before, after = before, placeholder = ''} = action.inline ?? {before: action.prefix ?? ''};
+    return {
+      label: action.label,
+      icon: action.icon,
+      group: label(action.group),
+      keywords: action.keywords,
+      value: action.inline ? before + placeholder + after : before,
+      caretOffset: action.inline ? before.length : action.caretOffset,
+    };
+  });
+}

package/src/components/remarkd-editor/feature-keys.ts

@@ -0,0 +1,17 @@
+/**
+ * The remarkd feature fixtures, from `node_modules/remarkd-js/requirements/features/`.
+ * Regenerate with: ls node_modules/remarkd-js/requirements/features
+ */
+export const FEATURE_KEYS: string[] = [
+  'accordion', 'admonition', 'asciidoc-image', 'asciidoc-section', 'attributes-title', 'autolink',
+  'blockquotes', 'button-object', 'callout-block', 'checkboxes', 'code-fence', 'comments',
+  'conditionals', 'conditionals-advanced', 'cross-reference', 'curly-bang-passthrough',
+  'definition-list', 'document-attributes', 'emoji-aliases', 'example-block', 'footnote',
+  'generic-container', 'hardbreaks', 'heading', 'highlight', 'horizontal-rule', 'id-block',
+  'image-alignment', 'include', 'inline-advanced', 'inline-formatting', 'keyboard',
+  'line-continuation', 'links-and-images', 'listing-block', 'literal-block', 'object-attributes',
+  'object-fallbacks', 'object-macros', 'ordered-list', 'page-break', 'paragraphs', 'partial',
+  'passthrough', 'pros-cons', 'reference-list', 'sidebar-block', 'smart-quotes', 'steps',
+  'subscript', 'superscript', 'table', 'tabs', 'tooltip', 'typographic-symbols',
+  'unordered-list', 'url-formatting-chars', 'verse', 'video',
+];