@motifx-community/ui 0.0.0-stage → 0.1.0-beta.0

package/dist/parts/icalendar/icalendar-moment.d.ts

@@ -0,0 +1,12 @@
+import type { ICalendarDate } from './icalendar-date';
+import type { ICalendarTimeZone } from './icalendar-time-zone';
+/**
+ * The moment a date of a file names. A UTC one is a moment already; a date only gives the wall
+ * clock time of its midnight (all-day events are the caller's). A zone is an IANA name, or else a
+ * `VTIMEZONE` of the file by that id; a floating time, or a zone neither knows, takes `fallback`
+ * (an IANA name, or `null` for the browser's own).
+ *
+ * @example
+ * icalendarMoment(event.start, calendar.timeZones, 'Europe/Istanbul')
+ */
+export declare function icalendarMoment(date: ICalendarDate, zones: readonly ICalendarTimeZone[], fallback: string | null): number;

package/dist/parts/icalendar/icalendar-observance.d.ts

@@ -0,0 +1,15 @@
+/** A `STANDARD` or `DAYLIGHT` part of a `VTIMEZONE`: the offset that holds from its onsets on. */
+export interface ICalendarObservance {
+    kind: 'standard' | 'daylight';
+    /** The first onset (`DTSTART`) as a wall clock time, in the offset before it. */
+    start: number;
+    /** Minutes east of UTC before and after an onset. */
+    offsetFrom: number;
+    offsetTo: number;
+    /** `TZNAME`; empty for none. */
+    name: string;
+    /** The `RRULE` of later onsets; empty for none. */
+    rule: string;
+    /** More onsets (`RDATE`) as wall clock times. */
+    dates: number[];
+}

package/dist/parts/icalendar/icalendar-property.d.ts

@@ -0,0 +1,9 @@
+/** A property of an iCalendar file as written: `NAME;PARAM=VALUE:value`. */
+export interface ICalendarProperty {
+    /** Upper case. */
+    name: string;
+    /** Parameters by upper case name, without the quotes around a value. */
+    params: Record<string, string>;
+    /** The value as written, still escaped. */
+    value: string;
+}

package/dist/parts/icalendar/icalendar-time-zone.d.ts

@@ -0,0 +1,7 @@
+import type { ICalendarObservance } from './icalendar-observance';
+/** A time zone (`VTIMEZONE`) written in an iCalendar file. */
+export interface ICalendarTimeZone {
+    /** `TZID`. */
+    id: string;
+    observances: ICalendarObservance[];
+}

package/dist/parts/icalendar/icalendar-write-options.d.ts

@@ -0,0 +1,15 @@
+import type { ICalendarEvent } from './icalendar-event';
+/** What `writeICalendar` writes. */
+export interface ICalendarWriteOptions {
+    events: ICalendarEvent[];
+    /** `X-WR-CALNAME`. */
+    name?: string;
+    /** Default `-//MotifJS//Scheduler//EN`. */
+    prodId?: string;
+    /** Default `PUBLISH`. */
+    method?: string;
+    /** IANA zones to write a `VTIMEZONE` for. Default: every IANA zone the events are written in. */
+    timeZones?: readonly string[];
+    /** `DTSTAMP` of the events without one. Default: now. */
+    stamp?: number;
+}

package/dist/parts/icalendar/icalendar.d.ts

@@ -0,0 +1,13 @@
+import type { ICalendarEvent } from './icalendar-event';
+import type { ICalendarTimeZone } from './icalendar-time-zone';
+/** What `parseICalendar` reads from a file; several calendars in one file are merged. */
+export interface ICalendar {
+    events: ICalendarEvent[];
+    timeZones: ICalendarTimeZone[];
+    /** `X-WR-CALNAME`. */
+    name: string;
+    /** `X-WR-TIMEZONE`. */
+    timeZone: string;
+    prodId: string;
+    method: string;
+}

package/dist/parts/icalendar/observance-moment.d.ts

@@ -0,0 +1,7 @@
+import type { ICalendarObservance } from './icalendar-observance';
+/**
+ * The moment a wall clock time names in a zone written as observances: the one with the latest
+ * onset at or before it holds. A time the clock skips moves on by the gap; before every onset the
+ * offset before the first one holds. `null` when there are no observances.
+ */
+export declare function observanceMoment(observances: readonly ICalendarObservance[], wall: number): number | null;

package/dist/parts/icalendar/parse-icalendar.d.ts

@@ -0,0 +1,11 @@
+import type { ICalendar } from './icalendar';
+/**
+ * Reads an iCalendar file (RFC 5545): its events, the time zones it writes and its name. Several
+ * calendars in one file are merged; to-dos, journals, free/busy times and the blocks inside an
+ * event (alarms) are left out, and so are lines it cannot read. It never throws on a bad file.
+ *
+ * @example
+ * const calendar = parseICalendar(text);
+ * calendar.events[0].summary;
+ */
+export declare function parseICalendar(text: string): ICalendar;

package/dist/parts/icalendar/read-components.d.ts

@@ -0,0 +1,3 @@
+import type { ICalendarComponent } from './icalendar-component';
+/** The blocks of a file as a tree; lines that are not content lines, and properties outside any block, are left out. */
+export declare function readComponents(text: string): ICalendarComponent[];

package/dist/parts/icalendar/read-content-line.d.ts

@@ -0,0 +1,3 @@
+import type { ICalendarProperty } from './icalendar-property';
+/** A content line (`NAME;PARAM="a:b";OTHER=c:value`) split into its parts; `null` when it is not one. */
+export declare function readContentLine(line: string): ICalendarProperty | null;

package/dist/parts/icalendar/read-duration.d.ts

@@ -0,0 +1,5 @@
+/** A duration (`P1W`, `PT1H30M`, `-P1DT2H`) as whole days and the exact time beside them; `null` when it is none. */
+export declare function readDuration(text: string): {
+    days: number;
+    time: number;
+} | null;

package/dist/parts/icalendar/read-event.d.ts

@@ -0,0 +1,4 @@
+import type { ICalendarComponent } from './icalendar-component';
+import type { ICalendarEvent } from './icalendar-event';
+/** An event from its `VEVENT` block; `null` when it has no start it can read. */
+export declare function readEvent(component: ICalendarComponent): ICalendarEvent | null;

package/dist/parts/icalendar/read-icalendar-dates.d.ts

@@ -0,0 +1,4 @@
+import type { ICalendarDate } from './icalendar-date';
+import type { ICalendarProperty } from './icalendar-property';
+/** The dates of a date property (`DTSTART`, a comma list of `EXDATE`), with its `VALUE=DATE` and `TZID`; ones it cannot read are left out. */
+export declare function readICalendarDates(property: ICalendarProperty): ICalendarDate[];

package/dist/parts/icalendar/read-offset.d.ts

@@ -0,0 +1,2 @@
+/** An offset (`+0300`, `-0500`, `+053000`) in minutes east of UTC; `null` when it is none. */
+export declare function readOffset(text: string): number | null;

package/dist/parts/icalendar/read-time-zone.d.ts

@@ -0,0 +1,4 @@
+import type { ICalendarComponent } from './icalendar-component';
+import type { ICalendarTimeZone } from './icalendar-time-zone';
+/** A time zone from its `VTIMEZONE` block; `null` when it has no `TZID`. */
+export declare function readTimeZone(component: ICalendarComponent): ICalendarTimeZone | null;

package/dist/parts/icalendar/same-form.d.ts

@@ -0,0 +1,3 @@
+import type { ICalendarDate } from './icalendar-date';
+/** A date in the form of another (a date only, its zone, UTC or floating), turned through IANA zones where it can be; else its fields are kept. */
+export declare function sameForm(date: ICalendarDate, like: ICalendarDate): ICalendarDate;

package/dist/parts/icalendar/short-zone-name.d.ts

@@ -0,0 +1,2 @@
+/** The short name `Intl` gives a zone at a moment (`CEST`, `EST`, `AEDT`); empty when it gives only an offset (`GMT+3`). */
+export declare function shortZoneName(zone: string, moment: number): string;

package/dist/parts/icalendar/time-zone-lines.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The `VTIMEZONE` of an IANA zone as content lines, from `Intl` only: every change of its offset
+ * from the start of `fromYear` to the end of `toYear`. Changes of one kind that fall on the same
+ * yearly rule in every year are written as one observance with an `RRULE`; others as observances
+ * with `RDATE`s. A zone that does not change writes one `STANDARD`.
+ *
+ * @example
+ * timeZoneLines('Europe/Berlin', 2026, 2027)
+ */
+export declare function timeZoneLines(name: string, fromYear: number, toYear: number): string[];

package/dist/parts/icalendar/unescape-text.d.ts

@@ -0,0 +1,2 @@
+/** A text value as it reads: `\n` (or `\N`) a new line, `\,` `\;` `\\` the sign itself. */
+export declare function unescapeText(value: string): string;

package/dist/parts/icalendar/unfold-lines.d.ts

@@ -0,0 +1,2 @@
+/** The content lines of a file: a leading BOM dropped, any line end (CRLF, LF, CR) taken, folded lines joined, empty ones left out. */
+export declare function unfoldLines(text: string): string[];

package/dist/parts/icalendar/write-icalendar.d.ts

@@ -0,0 +1,9 @@
+import type { ICalendarWriteOptions } from './icalendar-write-options';
+/**
+ * Writes events as an iCalendar file (RFC 5545): a `VTIMEZONE` for each zone, then one `VEVENT`
+ * per event. Text is escaped, lines are folded at 75 octets and end with CRLF.
+ *
+ * @example
+ * const text = writeICalendar({ events, name: 'Team', timeZones: ['Europe/Istanbul'] });
+ */
+export declare function writeICalendar(options: ICalendarWriteOptions): string;

package/dist/parts/list/OptionList.d.ts

@@ -0,0 +1,88 @@
+import { Component, type Event as MotifEvent } from '@motifx/core';
+import type { IconSource } from '../../core/icon-source';
+import type { ItemSource } from './item-source';
+import type { ListMove } from './list-move';
+import type { OptionChosenEventArgs } from './option-chosen-event-args';
+/**
+ * The options of a drop-down, a combo box or a list box (`role="listbox"`). The owner gives the
+ * items and how to read them, says which are selected, and moves the highlight from its own keys
+ * (`handleKey`); the owner's element points to the highlighted option with `aria-activedescendant`.
+ * Long lists draw only the rows in view; with an `ItemSource` rows may load while they come into view.
+ */
+export declare class OptionList<T = unknown> extends Component<HTMLDivElement> {
+    static elementTag: string;
+    textOf: (item: T) => string;
+    enabledOf: (item: T) => boolean;
+    iconOf: ((item: T) => IconSource | undefined) | null;
+    groupOf: ((item: T) => string | undefined) | null;
+    /** Draws an option's content instead of its text; may return a cleanup. */
+    draw: ((item: T, host: HTMLElement) => (() => void) | void) | null;
+    isSelected: (item: T) => boolean;
+    /** Check marks in front of the options and `aria-multiselectable`. */
+    multiple: boolean;
+    /** Lists with more rows than this draw only the ones in view. */
+    windowFrom: number;
+    /** Rows drawn above and below the visible ones in a long list. */
+    extraRows: number;
+    /** Milliseconds within which typed letters join one search. */
+    typingDelay: number;
+    /** What an empty list says; `uiLocale`'s "No items" by default. */
+    emptyText: (() => string) | null;
+    private size;
+    private itemAt;
+    private ensure;
+    /** With groups: the headers between the items. Without: one row per item. */
+    private rows;
+    private active;
+    private rowHeight;
+    private drawn;
+    private releases;
+    private typed;
+    private typedAt;
+    private frame;
+    private readonly baseId;
+    private readonly empty;
+    private readonly chosenEmitter;
+    readonly onChosen: MotifEvent<OptionChosenEventArgs<T>>;
+    onConfigured(): void;
+    /** The items as they are now; give them again after they changed. */
+    setItems(given: readonly T[]): void;
+    /** Items that load while they come into view (no groups). */
+    setSource(source: ItemSource<T>): void;
+    /** Draws the rows in view again, e.g. after some loaded. */
+    redraw(): void;
+    get count(): number;
+    get activeIndex(): number;
+    get activeItem(): T | undefined;
+    itemOf(index: number): T | undefined;
+    /** The id of an option's element, for `aria-activedescendant`. */
+    idOf(index: number): string;
+    /** Draws the selection again, after it changed. */
+    refresh(): void;
+    setActive(index: number, scroll?: boolean): void;
+    /** Moves the highlight over enabled options; returns the new index. */
+    move(how: ListMove): number;
+    /** The next enabled option whose text starts with what was typed lately; -1 when none. */
+    typeAhead(key: string): number;
+    /** The list keys: arrows, Home, End, Page Up, Page Down, Enter. Returns whether it used the key. */
+    handleKey(e: KeyboardEvent): boolean;
+    private get rowCount();
+    private rowAt;
+    private get windowed();
+    /** An item not loaded yet can be highlighted; it loads when it comes into view. */
+    private nextEnabled;
+    private drawAll;
+    /** In a long list: two empty blocks stand for the rows out of view. */
+    private drawWindow;
+    private space;
+    private measure;
+    private rowOf;
+    private scrollTo;
+    private optionElement;
+    private headerElement;
+    private itemElement;
+    private markSelected;
+    private indexOf;
+    private clicked;
+    private release;
+}

package/dist/parts/list/item-field.d.ts

@@ -0,0 +1,2 @@
+/** Where an item keeps something (its text, its value): a property name or a function. */
+export type ItemField<T> = string | ((item: T) => unknown);

package/dist/parts/list/item-own-value.d.ts

@@ -0,0 +1,2 @@
+/** An item's value when no value field is given: its `value` field, else the item itself. Read untracked. */
+export declare function itemOwnValue(item: unknown): unknown;

package/dist/parts/list/item-source.d.ts

@@ -0,0 +1,8 @@
+/** Items that may load while they are looked at: a count, the item at an index once loaded, and where the view is. */
+export interface ItemSource<T> {
+    readonly count: number;
+    /** `undefined` while not loaded yet. */
+    at(index: number): T | undefined;
+    /** The view shows `first` up to `end`: load them. */
+    ensure?(first: number, end: number): void;
+}

package/dist/parts/list/list-move.d.ts

@@ -0,0 +1,2 @@
+/** Where the highlight goes: a number of options, or a jump. */
+export type ListMove = number | 'first' | 'last' | 'page-up' | 'page-down';

package/dist/parts/list/option-chosen-event-args.d.ts

@@ -0,0 +1,5 @@
+export interface OptionChosenEventArgs<T> {
+    item: T;
+    index: number;
+    event: Event;
+}

package/dist/parts/list/read-item-field.d.ts

@@ -0,0 +1,6 @@
+import type { ItemField } from './item-field';
+/**
+ * Reads `field` of `item`, untracked; a primitive item is its own value and text. A `Bind` there is called and
+ * followed. A field given as a function reads the item itself, so it runs untracked too.
+ */
+export declare function readItemField<T>(item: T, field: ItemField<T> | undefined, fallback: string): unknown;

package/dist/parts/mask/InputMask.d.ts

@@ -0,0 +1,41 @@
+import type { InputMaskOptions } from './input-mask-options';
+/**
+ * Keeps what is typed into an `<input>` in the shape of a mask. Typing, deleting and pasting
+ * follow the mask and the caret skips the fixed characters. An `input` event is fired after
+ * every change.
+ *
+ * @example
+ * const phone = new InputMask(input, { mask: '(000) 000 00 00' });
+ * phone.raw; // '5321234567'
+ */
+export declare class InputMask {
+    readonly input: HTMLInputElement;
+    private text;
+    private options;
+    private writing;
+    private readonly abort;
+    constructor(input: HTMLInputElement, options: InputMaskOptions);
+    /** The typed characters only: `5321234567`. */
+    get raw(): string;
+    /** With the fixed characters: `(532) 123 45 67`. */
+    get formatted(): string;
+    get complete(): boolean;
+    get empty(): boolean;
+    setRaw(raw: string): void;
+    setFormatted(text: string): void;
+    /** `value` in the shape of the mask, without changing the input. */
+    conform(value: string, formatted?: boolean): string;
+    /** What was typed stays where it still fits. */
+    update(options: InputMaskOptions): void;
+    destroy(): void;
+    private create;
+    private get hasFocus();
+    private beforeInput;
+    /** The browser changed the text by itself: autofill, an input method, undo. */
+    private afterInput;
+    private takeInput;
+    private announce;
+    private show;
+    private focused;
+    private clampCaret;
+}

package/dist/parts/mask/MaskedText.d.ts

@@ -0,0 +1,38 @@
+import type { MaskSlot } from './mask-slot';
+/**
+ * The characters typed into a mask, and the edits on them. Positions are positions in the shown
+ * text, where every place of the mask is one character.
+ */
+export declare class MaskedText {
+    readonly slots: readonly MaskSlot[];
+    readonly placeholder: string;
+    private chars;
+    /** Where each place to fill is shown. */
+    private readonly places;
+    constructor(slots: readonly MaskSlot[], placeholder?: string);
+    get raw(): string;
+    get empty(): boolean;
+    /** Every place that may not stay empty is filled. */
+    get complete(): boolean;
+    /** The whole mask: typed characters, fixed ones and placeholders. */
+    get text(): string;
+    /** The typed characters with the fixed ones between them, without trailing placeholders. */
+    get formatted(): string;
+    setRaw(raw: string): void;
+    /** Takes text that may hold the fixed characters too, e.g. a pasted `(532) 123 45 67`. */
+    setText(text: string): void;
+    /** Where the k-th typed character is shown; past the last place, the end. */
+    positionOf(k: number): number;
+    /** The caret stops at the first empty place. */
+    clamp(position: number): number;
+    /** Replaces the selection with typed or pasted text and returns the new caret position. */
+    insert(from: number, to: number, text: string): number;
+    deleteBackward(from: number, to: number): number;
+    deleteForward(from: number, to: number): number;
+    private remove;
+    private countBefore;
+    /** Characters that moved to a place they do not fit are dropped. */
+    private refit;
+    /** Places `text` from position `from` on, skipping what does not fit; `literals` lets it hold the fixed characters. */
+    private fit;
+}

package/dist/parts/mask/input-mask-options.d.ts

@@ -0,0 +1,11 @@
+import type { MaskChar } from './mask-char';
+export interface InputMaskOptions {
+    /** `(000) 000 00 00`; see `maskChars` for the characters a mask knows. */
+    mask: string;
+    /** Your own mask characters: `{ H: /[0-9a-f]/i }`. */
+    chars?: Readonly<Record<string, MaskChar>>;
+    /** Shown in the places not filled yet. Default `_`. */
+    placeholder?: string;
+    /** `focus` (default): an empty mask shows only while the input has focus. */
+    showMask?: 'always' | 'focus';
+}

package/dist/parts/mask/mask-char.d.ts

@@ -0,0 +1,4 @@
+export type MaskChar = RegExp | {
+    test: RegExp;
+    transform?: 'upper' | 'lower';
+};

package/dist/parts/mask/mask-chars.d.ts

@@ -0,0 +1,3 @@
+import type { MaskChar } from './mask-char';
+/** `0` a digit, `9` a digit that may stay empty, `a` a letter, `*` a letter or a digit. */
+export declare const maskChars: Readonly<Record<string, MaskChar>>;

package/dist/parts/mask/mask-slot.d.ts

@@ -0,0 +1,8 @@
+/** One place of a parsed mask: a fixed character or one the user types. */
+export type MaskSlot = {
+    literal: string;
+} | {
+    test: RegExp;
+    optional: boolean;
+    transform?: 'upper' | 'lower';
+};

package/dist/parts/mask/parse-mask.d.ts

@@ -0,0 +1,4 @@
+import type { MaskChar } from './mask-char';
+import type { MaskSlot } from './mask-slot';
+/** `(000) 000 00 00` → its places. `\` makes the next character fixed. */
+export declare function parseMask(mask: string, chars?: Readonly<Record<string, MaskChar>>): MaskSlot[];

package/dist/parts/menu/MenuList.d.ts

@@ -0,0 +1,74 @@
+import { Component, type Bind, type ComponentBase, type Event as MotifEvent } from '@motifx/core';
+import type { MenuItem } from './menu-item';
+import type { MenuItemClickEventArgs } from './menu-item-click-event-args';
+/**
+ * A list of commands (`role="menu"`). Up and Down move between the items and wrap around, Home
+ * and End go to the ends, a letter goes to the next item that starts with it, an item's `&` key
+ * chooses it, Enter and Space choose the focused one. A disabled item can be reached but not chosen.
+ * An item with `items` opens a submenu at its side: Right (Left in a right-to-left page), Enter or
+ * Space open it, Left closes it again, and pointing at the item opens it after `hoverDelay`.
+ */
+export declare class MenuList extends Component<HTMLDivElement> {
+    static elementTag: string;
+    /** The component the menu belongs to; reported with every chosen item. */
+    source: ComponentBase | null;
+    /** Pointing at an item opens its submenu (and pointing elsewhere closes it) after `hoverDelay`. */
+    openOnHover: boolean;
+    /** Milliseconds the pointer rests on an item before its submenu opens or closes. */
+    hoverDelay: number;
+    /** The menu this one is a submenu of. */
+    parentList: MenuList | null;
+    /** Keeps the column for a mark or an icon when no item has one, so the texts line up with a menu beside it. */
+    markColumn: boolean;
+    /** A checked item keeps its icon: the mark gets a column of its own, before the icons. */
+    markBesideIcon: boolean;
+    /** How a chosen radio item is marked: a dot, or a check (when a dot means something else in the menu). */
+    radioMark: 'dot' | 'check';
+    /** An item with `items` opens its submenu at its side; `false` reports it as chosen instead, for an owner that shows the submenu itself. */
+    openSubmenus: boolean;
+    private given;
+    private entries;
+    private releases;
+    private stopDrawing;
+    private sub;
+    private hoverTimer;
+    private hoverEntry;
+    private pointerFocus;
+    private readonly chosenEmitter;
+    /** An item was chosen, here or in a submenu. The owner closes the menu, then runs the item's `click`. */
+    readonly onChosen: MotifEvent<MenuItemClickEventArgs>;
+    onConfigured(): void;
+    /**
+     * Shows the visible ones of `items`, and draws them again when a function in an item reads something that
+     * changes, or on `reState()`. The items and their fields are read as they are: after changing them in place,
+     * call `refresh`.
+     */
+    setItems(items: Bind<readonly MenuItem[]>): void;
+    /** Reads the items again, and those of an open submenu: after they were changed in place. */
+    refresh(): void;
+    get itemCount(): number;
+    /** The open submenu's list, `null` while none is open. */
+    get submenu(): MenuList | null;
+    /** Focuses the first or the last item; `false` when there is none. */
+    focusItem(which: 'first' | 'last'): boolean;
+    /** Focuses the menu itself, with no item highlighted: what a menu opened by the pointer does. Down then goes to the first item. */
+    focusList(): void;
+    /** Closes the open submenu, and the ones it opened. */
+    closeSubmenu(): void;
+    private draw;
+    private itemElement;
+    private clear;
+    private entryOf;
+    private onClick;
+    private choose;
+    private openSubmenu;
+    private showSubmenu;
+    private createSubmenu;
+    /** The popup this list is shown in. */
+    private hostPopup;
+    private onPointerMove;
+    private cancelHover;
+    /** The keys move to another item: an open submenu of another one closes (the pointer waits for its delay). */
+    private onFocusIn;
+    private onKeyDown;
+}

package/dist/parts/menu/line-after.d.ts

@@ -0,0 +1,4 @@
+import type { MenuItem } from './menu-item';
+/** Marks a menu item the kit made: the next item shown starts a group. */
+export declare function lineAfter<T extends MenuItem>(item: T): T;
+export declare function hasLineAfter(item: MenuItem): boolean;

package/dist/parts/menu/menu-item-click-event-args.d.ts

@@ -0,0 +1,10 @@
+import type { ComponentBase } from '@motifx/core';
+import type { MenuItem } from './menu-item';
+/** What a chosen menu item reports. */
+export interface MenuItemClickEventArgs {
+    item: MenuItem;
+    /** The component whose menu it is, e.g. the button. */
+    source: ComponentBase;
+    /** The click or key press that chose it. */
+    event: Event;
+}

package/dist/parts/menu/menu-item.d.ts

@@ -0,0 +1,37 @@
+import type { Bind } from '@motifx/core';
+import type { IconSource } from '../../core/icon-source';
+import type { MenuItemClickEventArgs } from './menu-item-click-event-args';
+/**
+ * One command of a menu. Every field but `click` and `data` is a value or a function: a function
+ * is followed, so the item changes in the open menu when what it reads changes.
+ */
+export interface MenuItem {
+    /** The label; `&` marks the key that chooses it while the menu is open (`&Copy`), `&&` is a literal `&`. */
+    text: Bind<string>;
+    /** An image address, an element or a component; a function is called each time the item is drawn. */
+    icon?: Bind<IconSource | null | undefined>;
+    /** Shown as a tooltip. */
+    hint?: Bind<string>;
+    /** `false` keeps the item in the menu, dimmed, and it cannot be chosen. Default `true`. */
+    enabled?: Bind<boolean>;
+    /** `false` leaves the item out. Default `true`. */
+    visible?: Bind<boolean>;
+    /** Given, the item shows a check mark when `true` (a `menuitemcheckbox`); `undefined` makes it a plain item again. */
+    checked?: Bind<boolean | undefined>;
+    /** Items of the same group are choices of one setting (`menuitemradio`): the one whose `checked` is `true` shows a dot. */
+    group?: Bind<string>;
+    /** A key combination shown at the end of the item (`Ctrl+S`); only shown, the app registers the key itself. */
+    shortcut?: Bind<string>;
+    /** A second, dimmer text after the label: what tells the item apart, such as a folder. It is part of the item's name. */
+    description?: Bind<string>;
+    /** A submenu, opened at the side of the item. */
+    items?: Bind<readonly MenuItem[]>;
+    /** The colour of the item, by what it does (`danger` for a deletion). Default `'standard'`. */
+    tone?: Bind<'standard' | 'accent' | 'success' | 'caution' | 'danger'>;
+    /** A line before the item, to group the commands. */
+    beginGroup?: Bind<boolean>;
+    /** Runs when the item is chosen, after the menu closed. */
+    click?: (e: MenuItemClickEventArgs) => void;
+    /** The app's own value for the item. */
+    data?: unknown;
+}