@ui-sdk/web 0.0.0-stage → 0.1.0-beta.1

package/docs/custom-parts.md

@@ -0,0 +1,91 @@
+# Custom Parts
+
+Choose a binding target and expose the state of a custom element.
+
+Start with the rating elements from [Rendering Primitives](./rendering.md). Add configuration to `createParts` when you need a different target or a public API.
+
+## Choose the Target
+
+By default, a part binds to its custom element. `target` chooses a child instead. `wrappedButton` finds a button or link; `wrappedChild("input")` finds an input.
+
+Bind to the native element that should own focus and keyboard behavior. Put its label and classes on that element too.
+
+## Expose API Methods
+
+The rating primitive has a `rate` method. Add it to the root's `api` list to let application code call it:
+
+```ts title="rating-web.ts"
+import { createParts, wrappedButton } from "@ui-sdk/web"
+import { rating } from "./rating"
+
+createParts(rating, {
+  root: { tag: "my-rating", api: ["rate"] },
+  star: { tag: "my-rating-star", target: wrappedButton, display: "contents" },
+})
+```
+
+Use this definition instead of the earlier one. Once the root is connected, `element.api.rate(3)` asks the primitive to change its value. Its callback and cancellation still apply. The element exposes only the methods you list.
+
+## Expose a Live Property
+
+A `state` mapping exposes a live getter and setter. Both call the primitive's API, so the primitive needs methods for reading and writing that value. The rating above only has `rate`; the built-in toggle has both `isPressed` and `setPressed`:
+
+```ts
+import { toggle } from "@ui-sdk/core/toggle"
+import { createParts, wrappedButton } from "@ui-sdk/web"
+
+createParts(toggle, {
+  root: {
+    tag: "my-toggle",
+    target: wrappedButton,
+    display: "contents",
+    state: {
+      pressed: {
+        get: (api) => api.isPressed(),
+        set: (api, value: boolean) => api.setPressed(value),
+      },
+    },
+    api: ["isPressed", "setPressed", "toggle"],
+  },
+})
+```
+
+```html
+<my-toggle><button>Bold</button></my-toggle>
+```
+
+The setter calls the primitive's API, so change callbacks and cancellation still apply. The `api` list exposes those methods on the element's controller.
+
+## Attributes and Properties
+
+The primitive's schema supplies the default conversion:
+
+| Kind                          | How It Reaches the Primitive                                   |
+| ----------------------------- | -------------------------------------------------------------- |
+| `string`, `number`, `boolean` | Parsed from an attribute.                                      |
+| `list`                        | A comma-separated attribute.                                   |
+| `value`                       | A JavaScript property, for objects and other rich values.      |
+| `callback`                    | A DOM event.                                                   |
+| `action`                      | A DOM event with `detail.waitUntil(promise)` for pending work. |
+
+A boolean attribute is on when present, unless its value is `"false"`. Defaults determine the value when the attribute is absent. `disabled` and `required` follow native controls, which treat them as on whenever present.
+
+Each attribute gets a property that reflects it. Name the booleans that are on by default in `defaults`, so their properties read `true` without the attribute and `false` writes `"false"`:
+
+```ts
+import { tabs } from "@ui-sdk/core/tabs"
+import { createParts, wrappedButton } from "@ui-sdk/web"
+
+createParts(tabs, {
+  root: { tag: "my-tabs", defaults: { loop: true } },
+  list: "my-tabs-list",
+  tab: { tag: "my-tabs-tab", target: wrappedButton },
+  panel: "my-tabs-panel",
+})
+```
+
+Use `kinds` to override a schema kind for an element and `properties` to add properties absent from the schema. `context(el)` on a child part can supply slot props from surrounding markup; explicit attributes and properties take precedence.
+
+## Compose a Popup
+
+A custom root can contain `ui-popover` or `ui-dialog`. Keep its `open` property in sync with your primitive and listen for `openchange`. That event doesn't bubble, so a listener on your root hears only the change you forward. [Compose Ours](./core.md#compose-ours) shows the pattern.

package/docs/first-component.md

@@ -0,0 +1,88 @@
+# First Component
+
+Add a component to your page and style its state.
+
+Let's add a Bookmark toggle. Press it once to turn it on, then again to turn it off.
+
+If you haven't installed the packages yet, start with [Installation](./installation.md).
+
+This example uses a bundler that resolves package imports and compiles TypeScript, such as Vite. Keep `index.html` and `bookmark-button.ts` in the same folder.
+
+## Register the Component
+
+Create `bookmark-button.ts` and import the toggle entry:
+
+```ts title="bookmark-button.ts"
+import "@ui-sdk/web/toggle"
+```
+
+Importing the toggle entry registers `<ui-toggle>`. The custom element manages the wrapped button's pressed state and sets `aria-pressed` for screen readers. The native button handles Enter and Space.
+
+## Use It on Your Page
+
+Add this markup to `index.html`:
+
+```html title="index.html"
+<ui-toggle id="bookmark">
+  <button type="button">Bookmark</button>
+</ui-toggle>
+
+<script type="module" src="./bookmark-button.ts"></script>
+```
+
+Open your page. You should see a button labeled Bookmark. Next, add styles so you can tell when it is pressed.
+
+## Add Styles
+
+When the toggle is pressed, its button has a `data-pressed` attribute. Style the button inside `<ui-toggle>`.
+
+With Tailwind CSS configured in your app, add utility classes to the button. The `data-pressed:` variant applies while the toggle is pressed:
+
+```html title="index.html"
+<ui-toggle id="bookmark">
+  <button
+    type="button"
+    class="inline-flex h-8 items-center rounded-md border border-neutral-300 px-3 text-sm font-medium hover:bg-neutral-100 focus-visible:outline-2 focus-visible:outline-offset-2 data-pressed:bg-neutral-900 data-pressed:text-white"
+  >
+    Bookmark
+  </button>
+</ui-toggle>
+
+<script type="module" src="./bookmark-button.ts"></script>
+```
+
+Keep the component import in `bookmark-button.ts`:
+
+```ts title="bookmark-button.ts"
+import "@ui-sdk/web/toggle"
+```
+
+Try the styled toggle:
+
+```ts title="first-component.ts"
+import "@ui-sdk/web/toggle"
+
+function mount(root: HTMLElement) {
+  root.innerHTML = `
+    <ui-toggle>
+      <button type="button" data-variant="outline">
+        Bookmark
+      </button>
+    </ui-toggle>
+  `
+}
+
+export { mount }
+```
+
+Click Bookmark to turn it on or off. A filled background means it is on. You can also focus the button with Tab and press Enter or Space.
+
+Keep the label the same in both states. `aria-pressed` tells a screen reader whether the toggle is on.
+
+## Keep Going
+
+- [Toggle](./components/toggle.md) covers disabled states, controlled state, and groups of toggles.
+- [Components](./README.md) lists the other components you can add with the same install.
+- [Parts and Composition](./parts-and-composition.md) shows how to put a component with several parts together.
+- [State and Events](./state-and-events.md) shows how to read changes and control state from your app.
+- [Styling and Animation](./styling-and-animation.md) covers state attributes, CSS variables, and transitions.

package/docs/forms.md

@@ -0,0 +1,125 @@
+# Forms
+
+Submit custom element values, label controls, and show validation errors.
+
+Give a control a `name` to include its value in a form. Once their modules load, controls such as Checkbox and Select participate in submission, validation, and reset through the browser’s form-associated custom element APIs.
+
+## Submit a Value
+
+```ts
+import "@ui-sdk/web/checkbox"
+```
+
+```html
+<form action="/preferences" method="post">
+  <label
+    ><ui-checkbox name="updates" value="yes" default-checked></ui-checkbox>
+    Email me updates</label
+  >
+  <button type="submit">Save</button>
+  <button type="reset">Reset</button>
+</form>
+```
+
+The checkbox submits `updates=yes` when checked. Reset restores its default value.
+
+On controls that support them, `required`, `disabled`, `read-only`, and `form` follow native conventions. The elements expose `validity`, `checkValidity()`, and `setCustomValidity()`.
+
+## Respond to a Reset
+
+A reset also fires `checkedchange` when it requests a different value. You can use the same listener for clicks and resets:
+
+```html
+<form>
+  <label>
+    <ui-checkbox name="updates" value="yes" default-checked></ui-checkbox>
+    Email me updates
+  </label>
+  <button type="reset">Reset</button>
+  <output id="reason">No change yet</output>
+</form>
+```
+
+```ts
+import "@ui-sdk/web/checkbox"
+
+const checkbox = document.querySelector("ui-checkbox")!
+const reason = document.querySelector("#reason")!
+
+checkbox.addEventListener("checkedchange", (event) => {
+  reason.textContent = event.detail.reason
+})
+```
+
+Run the script after the markup exists. Uncheck the box, then press Reset: `default-checked` restores `true`, and the output reads `reset`. If the checkbox is already at its default, no change event is needed.
+
+The element owns its live state. If your application mirrors `checked` elsewhere, update that state from `checkedchange` too.
+
+## Label and Validate a Field
+
+`ui-field` finds the control inside it and connects the label, description, and error:
+
+```ts
+import "@ui-sdk/web/field"
+import "@ui-sdk/web/input"
+```
+
+```html
+<ui-field name="email">
+  <ui-field-label>Email</ui-field-label>
+  <ui-input>
+    <input type="email" required />
+  </ui-input>
+  <ui-field-description>We'll only use it for receipts.</ui-field-description>
+  <ui-field-error></ui-field-error>
+</ui-field>
+```
+
+The control is one of ours, such as `ui-input`, `ui-textarea`, `ui-checkbox` or `ui-select`. [Field](./components/field.md) shows the supported controls.
+
+## Handle a Submission
+
+On a normal submit, the browser checks constraints such as `required` and `type="email"` before running your listener.
+
+Your server may still reject a valid-looking value. Set the field’s `invalid` property to `true` and show the server’s message. When the user edits the field, clear the message and set `invalid` back to `undefined` so the field uses native validation again. This example expects a `/api/preferences` endpoint:
+
+```html
+<form>
+  <ui-field name="email">
+    <ui-field-label>Email</ui-field-label>
+    <ui-input>
+      <input type="email" required />
+    </ui-input>
+    <ui-field-error></ui-field-error>
+  </ui-field>
+  <button type="submit">Save</button>
+</form>
+```
+
+```ts
+import "@ui-sdk/web/field"
+import "@ui-sdk/web/input"
+
+const form = document.querySelector("form")!
+const field = form.querySelector("ui-field")!
+const error = form.querySelector("ui-field-error")!
+
+form.addEventListener("submit", async (event) => {
+  event.preventDefault()
+  const response = await fetch("/api/preferences", {
+    method: "POST",
+    body: new FormData(form),
+  })
+  field.invalid = response.ok ? undefined : true
+  error.textContent = response.ok ? "" : "That email is already taken."
+})
+
+form.addEventListener("input", () => {
+  field.invalid = undefined
+  error.textContent = ""
+})
+```
+
+An empty `<ui-field-error>` shows the browser's own message, so clearing the text brings it back. Without a listener, the native form submits normally.
+
+For a form that must work before component scripts load, see [Server Rendering](./server-rendering.md#before-upgrade).

package/docs/installation.md

@@ -0,0 +1,141 @@
+# Installation
+
+Install UI SDK and register its custom elements.
+
+Use these components in an app that supports custom elements. The examples use a bundler, such as Vite, to resolve package imports.
+
+## Install the Packages
+
+```bash
+npm install @ui-sdk/web @ui-sdk/core
+```
+
+`@ui-sdk/web` provides the custom elements. `@ui-sdk/core` provides their behavior and is a peer dependency. Install both so the components and any helpers you use share one copy of the core.
+
+## Register a Component
+
+Import each component from its own entry to register its tags:
+
+```ts
+import "@ui-sdk/web/button"
+import "@ui-sdk/web/toggle"
+```
+
+A dialog has separate tags for its trigger, content, and title. One import registers them all:
+
+```ts
+import "@ui-sdk/web/dialog"
+```
+
+Load these imports from your app's browser entry. The root entry, `@ui-sdk/web`, exports helpers and types but registers no elements. Each [component page](./README.md) shows the tags you can use.
+
+## Without a Build Step
+
+A plain HTML page can load the components from ui-sdk.dev, with nothing to install. Add one script, and each component loads the first time its tags appear on the page:
+
+```html
+<script type="module" src="https://ui-sdk.dev/web@0.js"></script>
+
+<ui-toggle><button>Bold</button></ui-toggle>
+```
+
+`@0` follows the newest 0.x release. To keep a page on one release, use its exact version, like `web@0.4.1.js`. For a quick test, `web.js` with no version follows the newest release of all.
+
+To have an agent build the page, ask it to read web.md first. It's these docs in one file, written for a page that loads `web.js` and `web.css`.
+
+Each component also has its own file, named like its import, if you'd rather list them:
+
+```html
+<script type="module" src="https://ui-sdk.dev/web@0/toggle.js"></script>
+```
+
+To host the files yourself, copy the `browser` folder from the `@ui-sdk/web` package into your site. It holds `web.js` and the `web` folder it loads from, so keep the two side by side. Browsers only run module scripts from a server, so open the page through one, not from a file on disk.
+
+### Build Your Own
+
+`core.js` has every behavior from `@ui-sdk/core`, along with `definePrimitive` and `createParts`. Import it to build a component we don't ship, on the same page as ours. This one is a small grid of cells you can move through with the arrow keys and select with Shift:
+
+```html
+<script type="module">
+  import {
+    createCellRange,
+    createGridFocus,
+    createParts,
+    definePrimitive,
+  } from "https://ui-sdk.dev/web@0/core.js"
+
+  const sheet = definePrimitive({
+    name: "sheet",
+    options: { rows: "number", cols: "number" },
+    state: () => ({ active: null, range: null }),
+    api: (context) => {
+      const rows = () => context.options().rows
+      const cols = () => context.options().cols
+      const grid = createGridFocus(context, { key: "active", rows, cols })
+      return {
+        grid,
+        range: createCellRange(context, { key: "range", grid, rows, cols }),
+      }
+    },
+    slots: (slot) => ({
+      root: slot({ attrs: () => ({ role: "grid" }) }),
+      row: slot({ attrs: () => ({ role: "row" }) }),
+      cell: slot({
+        props: { row: "number", col: "number" },
+        attrs: (state, { props, api }) => ({
+          role: "gridcell",
+          tabindex: api.grid.tabIndex(state, props),
+          ...api.range.cellAttrs(state, props),
+        }),
+        on: {
+          keydown: (event, { api }) => api.range.keydown(event),
+          pointerdown: (event, { api, props }) =>
+            api.range.pointerdown(event, props),
+        },
+        bind: (el, { api, props }) => api.range.bind(el, props),
+      }),
+    }),
+  })
+
+  createParts(sheet, {
+    root: "my-sheet",
+    row: "my-sheet-row",
+    cell: "my-sheet-cell",
+  })
+</script>
+
+<my-sheet rows="2" cols="2" aria-label="Numbers">
+  <my-sheet-row>
+    <my-sheet-cell row="0" col="0">4</my-sheet-cell>
+    <my-sheet-cell row="0" col="1">8</my-sheet-cell>
+  </my-sheet-row>
+  <my-sheet-row>
+    <my-sheet-cell row="1" col="0">15</my-sheet-cell>
+    <my-sheet-cell row="1" col="1">16</my-sheet-cell>
+  </my-sheet-row>
+</my-sheet>
+```
+
+Selected cells get `aria-selected` and `data-selected` to style. [Compose Behaviors](./core.md#compose-behaviors) walks through building a primitive, and [Rendering Primitives](./rendering.md) covers `createParts`. `core.js` shares its files with the components, so a page that uses both loads that code once.
+
+## Add Your Styles
+
+Components use light DOM and are unstyled, so you style them with your app's CSS or with Tailwind CSS. [Styling and Animation](./styling-and-animation.md) covers both.
+
+You can render your first component without setting up a provider, a portal root, or a UI SDK stylesheet. CSS Modules need a bundler that imports a class-name map.
+
+For right-to-left layouts, set `dir="rtl"` on the page or a container. Use logical CSS properties, such as `padding-inline-start`, in your styles. [Server Rendering](./server-rendering.md) covers markup before the elements upgrade.
+
+## Editor Support
+
+The package includes `custom-elements.json`, which describes its tags, attributes, properties, and events. Tools that support custom element manifests can read it.
+
+For HTML completion in VS Code, add this to your workspace settings:
+
+```json title=".vscode/settings.json"
+{ "html.customData": ["./node_modules/@ui-sdk/web/html-custom-data.json"] }
+```
+
+Component imports also register element types with TypeScript. For example, importing `@ui-sdk/web/toggle` gives `document.querySelector("ui-toggle")` its element type.
+
+Continue with [First Component](./first-component.md) to add a working toggle to your page.

package/docs/introduction.md

@@ -0,0 +1,32 @@
+# Introduction
+
+Use unstyled custom elements with keyboard, focus, and screen reader support built in.
+
+These docs cover ui-sdk in Web Components. Using another framework? See React, Vue, Svelte or Solid. To build your own components from behaviors, see [Core](./core.md).
+
+`@ui-sdk/web` gives you components such as Select, Dialog, and Tabs as custom elements, built on ui-sdk's behaviors. They handle interactions, focus, and ARIA attributes. You write the HTML and styles.
+
+Import the components you need to register their tags, add them to your page, and style them with your own CSS.
+
+## Quick Start
+
+Copy this prompt into your agent:
+
+```text prompt
+Set up ui-sdk in this Web Components project. Each component registers its tags when you import its entry, like @ui-sdk/web/dialog.
+
+1. Install @ui-sdk/web and @ui-sdk/core with the project's package manager.
+2. Add a note to AGENTS.md, creating it if needed: before using ui-sdk, follow the ui-sdk skill if it's installed, and read node_modules/@ui-sdk/web/docs/llms.txt. To build a new component, also search node_modules/@ui-sdk/web/docs/core.md by heading, and read rendering.md next to it.
+3. If you support skills, run: npx skills add vercel-labs/ui --skill ui-sdk
+```
+
+It installs ui-sdk and points your `AGENTS.md` at the docs that ship with the packages.
+
+## Set It Up Yourself
+
+- [Installation](./installation.md): Install the packages and register their custom elements.
+- [First Component](./first-component.md): Add and style your first component.
+
+## Explore the Components
+
+The [Using Components guides](./parts-and-composition.md) cover patterns the components share, such as composing parts, handling state, and styling.

package/docs/lists-and-menus.md

@@ -0,0 +1,166 @@
+# Lists and Menus
+
+Supply options as data, load them from a server, and define menu actions.
+
+Select, Combobox, Autocomplete, and Listbox accept items as a property. Use this when your choices already come from an array. You can also write their item parts in HTML.
+
+## Start with Strings
+
+```html
+<ui-select>
+  <ui-select-trigger
+    ><button aria-label="Fruit">
+      <ui-select-value placeholder="Choose a fruit"></ui-select-value></button
+  ></ui-select-trigger>
+  <ui-select-content>
+    <ui-select-list></ui-select-list>
+  </ui-select-content>
+</ui-select>
+```
+
+```ts
+import "@ui-sdk/web/select"
+
+const select = document.querySelector("ui-select")!
+select.items = ["Apple", "Banana", "Pear"]
+```
+
+Each string is both its value and its label. For different values and labels, use `{ value: "apple", label: "Apple" }`. Items can also have `disabled` and `keywords`.
+
+Group choices with `{ type: "group", label, items }`, or separate them with `{ type: "separator" }`. Annotate the array with `ListData` and your editor checks every entry where you write it:
+
+```ts
+import type { ListData } from "@ui-sdk/core/select"
+
+const plans: ListData = [
+  { value: "free", label: "Free" },
+  { value: "pro", label: "Pro" },
+  { type: "separator" },
+  {
+    type: "group",
+    label: "Contact sales",
+    items: [{ value: "enterprise", label: "Enterprise" }],
+  },
+]
+```
+
+For object values, set the `itemToValue` and `itemToLabel` properties, and write the type as `ListData<Plan>`. [Select](./components/select.md) has complete examples.
+
+Trigger Menu uses a `triggers` property for its trigger definitions; see [Trigger Menu](./components/trigger-menu.md).
+
+## Search and Load Items
+
+The `filter` attribute chooses a matching mode, such as `filter="startsWith"`. Assign a function to the `filter` property for your own matching. [Async Options](./utilities/async-options.md) covers loading from a server.
+
+Data lists can virtualize large collections.
+
+## Define a Menu
+
+```html
+<ui-menu>
+  <ui-menu-trigger><button>File</button></ui-menu-trigger>
+</ui-menu>
+```
+
+```ts
+import "@ui-sdk/web/menu"
+import type { MenuData } from "@ui-sdk/web"
+
+const fileMenu: MenuData = [
+  { value: "open", label: "Open", shortcut: "mod+o" },
+  { type: "separator" },
+  {
+    type: "submenu",
+    label: "Share",
+    items: [{ value: "email", label: "Email" }],
+  },
+]
+
+const menu = document.querySelector("ui-menu")!
+menu.items = fileMenu
+menu.addEventListener("action", (event) => console.log(event.detail.value))
+```
+
+A plain string is an action whose value and label are the string. [Menu](./components/menu.md) covers checkbox items and radio groups. Commands use `CommandData` and trigger menus `TriggerMenuData`, the same entries with fields of their own, and trees `TreeItemData[]`.
+
+## Style Parts from Data
+
+Parts rendered from data start out bare, with no classes. To style them, put a `<template>` inside the element and write each part there once, the way you want it to look. Every part the element renders is a copy of the part with the same tag in its template, classes and content included.
+
+```html
+<ui-select default-value="pro">
+  <ui-select-trigger>
+    <button><ui-select-value></ui-select-value></button>
+  </ui-select-trigger>
+  <template>
+    <ui-select-content class="rounded-2xl bg-white p-1 shadow-lg">
+      <ui-select-group>
+        <ui-select-group-label
+          class="px-2 py-1 text-xs text-neutral-500"
+        ></ui-select-group-label>
+        <ui-select-item
+          class="relative flex items-center rounded-xl py-1.5 ps-2 pe-8 data-highlighted:bg-neutral-100"
+        >
+          <ui-select-item-indicator class="absolute end-2"
+            >✓</ui-select-item-indicator
+          >
+        </ui-select-item>
+      </ui-select-group>
+      <ui-select-separator
+        class="-mx-1 my-1 h-px bg-neutral-200"
+      ></ui-select-separator>
+    </ui-select-content>
+  </template>
+</ui-select>
+```
+
+```ts
+const select = document.querySelector("ui-select")!
+select.items = plans
+```
+
+The element looks up each part by its tag, so the template only needs one of each, nested however reads best. Parts you leave out of it render bare.
+
+- **Containers copy only themselves.** The content, the list, a group or a submenu's content takes the template's classes, and the data fills it.
+- **Items copy everything inside them.** An indicator, an icon or a shortcut you put in the template's item shows in every item.
+- **The label goes in the text part.** When the template's item has one, like `<ui-select-item-text>`, the label goes there, so you can style what a search matched with classes like `[&_mark]:font-semibold`. Without one, the label comes first in the item.
+
+Select, Combobox, Autocomplete, Command, Listbox and Trigger Menu copy their content, list, groups, group labels, items and separators. A combobox with chips copies its chip too, with the remove button you write inside it:
+
+```html
+<template>
+  <ui-combobox-chip
+    class="flex items-center gap-1 rounded-2xl bg-neutral-200 ps-1.5 pe-0.5 text-xs"
+  >
+    <ui-combobox-chip-remove>
+      <button type="button" class="opacity-50 hover:opacity-100">×</button>
+    </ui-combobox-chip-remove>
+  </ui-combobox-chip>
+</template>
+```
+
+A menu copies its content, items, checkbox items, radio items, groups, group labels, separators, submenu triggers and submenu content. Put the check in the template's checkbox item and the chevron in its submenu trigger.
+
+A tree copies its items, indicators, checkboxes, labels and groups. A branch gets the indicator, and every item gets the checkbox when the tree is `checkable`. A link item's label becomes an `<a>` that takes the label's classes.
+
+```html
+<ui-tree aria-label="Groceries">
+  <template>
+    <ui-tree-item class="flex flex-wrap items-center">
+      <ui-tree-item-indicator
+        class="size-4 before:content-['›'] data-expanded:rotate-90"
+      ></ui-tree-item-indicator>
+      <ui-tree-item-label
+        class="flex-1 rounded-xl px-2 data-selected:bg-neutral-100"
+      ></ui-tree-item-label>
+      <ui-tree-group class="basis-full ps-4"></ui-tree-group>
+    </ui-tree-item>
+  </template>
+</ui-tree>
+```
+
+## Keys and Shortcuts
+
+`loop` controls whether arrow keys wrap around a list. Components that support `orientation` use it to choose the navigation axis.
+
+A trigger's `shortcut="mod+k"` opens it from elsewhere on the page. Data menus run item shortcuts while closed; a menu item written in HTML only displays its shortcut. [Shortcuts](./utilities/shortcuts.md) covers registering your own.