@elaraai/east-ui 1.0.4 → 1.0.5

package/dist/src/overlays/menu/index.d.ts

@@ -2,10 +2,10 @@
  * Copyright (c) 2025 Elara AI Pty Ltd
  * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
  */
-import { type ExprType, type SubtypeExprOrValue, StringType, BooleanType, ArrayType, OptionType, StructType } from "@elaraai/east";
+import { type ExprType, type SubtypeExprOrValue, StringType, ArrayType, OptionType, StructType } from "@elaraai/east";
 import { UIComponentType } from "../../component.js";
-import { MenuItemType, MenuStyleType, type MenuStyle } from "./types.js";
-export { MenuItemType, MenuStyleType, type MenuStyle, PlacementType, type PlacementLiteral, } from "./types.js";
+import { MenuItemType, MenuStyleType, type MenuItemOptions, type MenuStyle } from "./types.js";
+export { MenuItemType, MenuStyleType, type MenuItemOptions, type MenuStyle, PlacementType, type PlacementLiteral, } from "./types.js";
 /**
  * East StructType for Menu component.
  *
@@ -32,7 +32,7 @@ export type MenuType = typeof MenuType;
  *
  * @param value - Unique identifier for the item
  * @param label - Display text for the item
- * @param disabled - Whether the item is disabled
+ * @param options - Optional icon / accelerator / disabled / destructive fields
  * @returns An East expression representing the menu item
  *
  * @example
@@ -41,17 +41,44 @@ export type MenuType = typeof MenuType;
  * import { Menu, Button, UIComponentType } from "@elaraai/east-ui";
  *
  * const example = East.function([], UIComponentType, $ => {
- *     return Menu.Root(
- *         Button.Root("Actions"),
- *         [
- *             Menu.Item("edit", "Edit"),
- *             Menu.Item("delete", "Delete", true),
- *         ]
- *     );
+ *     return Menu.Root({
+ *         trigger: Button.Root("Actions"),
+ *         items: [
+ *             Menu.Item("edit", "Edit · rename", { icon: "pen" }),
+ *             Menu.Item("duplicate", "Duplicate", { icon: "copy", command: "⌘D" }),
+ *             Menu.Separator(),
+ *             Menu.Item("archive", "Archive", { icon: "trash", destructive: true }),
+ *         ],
+ *     });
  * });
  * ```
  */
-declare function createMenuItem(value: SubtypeExprOrValue<typeof StringType>, label: SubtypeExprOrValue<typeof StringType>, disabled?: SubtypeExprOrValue<typeof BooleanType>): ExprType<MenuItemType>;
+declare function createMenuItem(value: SubtypeExprOrValue<typeof StringType>, label: SubtypeExprOrValue<typeof StringType>, options?: MenuItemOptions): ExprType<MenuItemType>;
+/**
+ * Creates a menu group label — the uppercase mono eyebrow naming the
+ * section of items below it.
+ *
+ * @param label - Heading text — rendered uppercase in the mono eyebrow style
+ * @returns An East expression representing the group label
+ *
+ * @example
+ * ```ts
+ * import { East } from "@elaraai/east";
+ * import { Menu, Button, UIComponentType } from "@elaraai/east-ui";
+ *
+ * const example = East.function([], UIComponentType, $ => {
+ *     return Menu.Root({
+ *         trigger: Button.Root("Actions"),
+ *         items: [
+ *             Menu.GroupLabel("Actions"),
+ *             Menu.Item("edit", "Edit · rename", { icon: "pen" }),
+ *             Menu.Item("export", "Export CSV", { icon: "download" }),
+ *         ],
+ *     });
+ * });
+ * ```
+ */
+declare function createMenuGroupLabel(label: SubtypeExprOrValue<typeof StringType>): ExprType<MenuItemType>;
 /**
  * Creates a menu separator.
  *
@@ -78,9 +105,7 @@ declare function createMenuSeparator(): ExprType<MenuItemType>;
 /**
  * Creates a Menu component.
  *
- * @param trigger - The element that triggers the menu
- * @param items - Array of menu items
- * @param style - Optional style configuration
+ * @param options - Required `trigger` + `items`, optional visual style fields
  * @returns An East expression representing the Menu component
  *
  * @example
@@ -89,33 +114,37 @@ declare function createMenuSeparator(): ExprType<MenuItemType>;
  * import { Menu, Button, UIComponentType } from "@elaraai/east-ui";
  *
  * const example = East.function([], UIComponentType, $ => {
- *     return Menu.Root(
- *         Button.Root("Actions"),
- *         [
+ *     return Menu.Root({
+ *         trigger: Button.Root("Actions"),
+ *         items: [
  *             Menu.Item("edit", "Edit"),
  *             Menu.Separator(),
  *             Menu.Item("delete", "Delete"),
  *         ],
- *         { placement: "bottom-start" }
- *     );
+ *         placement: "bottom-start",
+ *     });
  * });
  * ```
  */
-declare function createMenu(trigger: SubtypeExprOrValue<UIComponentType>, items: SubtypeExprOrValue<ArrayType<MenuItemType>>, style?: MenuStyle): ExprType<UIComponentType>;
+export interface MenuOptions extends MenuStyle {
+    /** The element that triggers the menu — required. */
+    trigger: SubtypeExprOrValue<UIComponentType>;
+    /** Array of menu items created with `Menu.Item` / `Menu.Separator` — required. */
+    items: SubtypeExprOrValue<ArrayType<MenuItemType>>;
+}
+declare function createMenu(options: MenuOptions): ExprType<UIComponentType>;
 /**
  * Menu component namespace.
  *
  * @remarks
  * Menu provides a dropdown menu triggered by a UI element.
- * Use `Menu.Root(trigger, items, style)` to create a menu, `Menu.Item(value, label)` for items, and `Menu.Separator()` for dividers.
+ * Use `Menu.Root({ trigger, items, ... })` to create a menu, `Menu.Item(value, label)` for items, and `Menu.Separator()` for dividers.
  */
 export declare const Menu: {
     /**
      * Creates a Menu component with a trigger and menu items.
      *
-     * @param trigger - The element that triggers the menu
-     * @param items - Array of menu items
-     * @param style - Optional style configuration
+     * @param options - Required `trigger` + `items`, optional visual style fields
      * @returns An East expression representing the Menu component
      *
      * @remarks
@@ -128,14 +157,14 @@ export declare const Menu: {
      * import { Menu, Button, UIComponentType } from "@elaraai/east-ui";
      *
      * const example = East.function([], UIComponentType, $ => {
-     *     return Menu.Root(
-     *         Button.Root("Actions"),
-     *         [
+     *     return Menu.Root({
+     *         trigger: Button.Root("Actions"),
+     *         items: [
      *             Menu.Item("edit", "Edit"),
      *             Menu.Separator(),
      *             Menu.Item("delete", "Delete"),
-     *         ]
-     *     );
+     *         ],
+     *     });
      * });
      * ```
      */
@@ -145,12 +174,15 @@ export declare const Menu: {
      *
      * @param value - Unique identifier for the item
      * @param label - Display text for the item
-     * @param disabled - Whether the item is disabled
+     * @param options - Optional icon / accelerator / disabled / destructive fields
      * @returns An East expression representing the menu item
      *
      * @remarks
      * Menu items are clickable entries within a Menu. Each item has a unique
-     * value for identification and a label for display.
+     * value for identification and a label for display. Items can carry a
+     * leading Font Awesome solid icon, a right-aligned keyboard accelerator,
+     * and a destructive flag (negative ink — place destructive items at the
+     * bottom, after a separator).
      *
      * @example
      * ```ts
@@ -158,17 +190,49 @@ export declare const Menu: {
      * import { Menu, Button, UIComponentType } from "@elaraai/east-ui";
      *
      * const example = East.function([], UIComponentType, $ => {
-     *     return Menu.Root(
-     *         Button.Root("Actions"),
-     *         [
-     *             Menu.Item("edit", "Edit"),
-     *             Menu.Item("delete", "Delete", true), // disabled
-     *         ]
-     *     );
+     *     return Menu.Root({
+     *         trigger: Button.Root("Actions"),
+     *         items: [
+     *             Menu.Item("edit", "Edit · rename", { icon: "pen" }),
+     *             Menu.Item("duplicate", "Duplicate", { icon: "copy", command: "⌘D" }),
+     *             Menu.Item("save", "Save", { disabled: true }),
+     *             Menu.Separator(),
+     *             Menu.Item("archive", "Archive", { icon: "trash", destructive: true }),
+     *         ],
+     *     });
      * });
      * ```
      */
     readonly Item: typeof createMenuItem;
+    /**
+     * Creates a menu group label — the uppercase mono eyebrow naming the
+     * section of items below it.
+     *
+     * @param label - Heading text — rendered uppercase in the mono eyebrow style
+     * @returns An East expression representing the group label
+     *
+     * @remarks
+     * Use a group label to head a run of related items, in the same mono
+     * uppercase eyebrow style used across the spec.
+     *
+     * @example
+     * ```ts
+     * import { East } from "@elaraai/east";
+     * import { Menu, Button, UIComponentType } from "@elaraai/east-ui";
+     *
+     * const example = East.function([], UIComponentType, $ => {
+     *     return Menu.Root({
+     *         trigger: Button.Root("Actions"),
+     *         items: [
+     *             Menu.GroupLabel("Actions"),
+     *             Menu.Item("edit", "Edit · rename", { icon: "pen" }),
+     *             Menu.Item("export", "Export CSV", { icon: "download" }),
+     *         ],
+     *     });
+     * });
+     * ```
+     */
+    readonly GroupLabel: typeof createMenuGroupLabel;
     /**
      * Creates a menu separator for visual grouping.
      *
@@ -219,16 +283,24 @@ export declare const Menu: {
          * Menu item variant type.
          *
          * @remarks
-         * Menu items can be either an Item (clickable menu entry) or a Separator (visual divider).
+         * Menu items can be an Item (clickable menu entry), a GroupLabel
+         * (uppercase mono eyebrow heading), or a Separator (visual divider).
          *
-         * @property Item - A clickable menu item with value, label, and optional disabled state
+         * @property Item - A clickable menu item with value, label, and optional icon / accelerator / disabled / destructive state
+         * @property GroupLabel - An uppercase eyebrow heading for the items that follow
          * @property Separator - A visual separator between menu items
          */
         readonly Item: import("@elaraai/east").VariantType<{
             readonly Item: StructType<{
                 readonly value: StringType;
                 readonly label: StringType;
-                readonly disabled: OptionType<BooleanType>;
+                readonly disabled: OptionType<import("@elaraai/east").BooleanType>;
+                readonly icon: OptionType<StringType>;
+                readonly command: OptionType<StringType>;
+                readonly destructive: OptionType<import("@elaraai/east").BooleanType>;
+            }>;
+            readonly GroupLabel: StructType<{
+                readonly label: StringType;
             }>;
             readonly Separator: import("@elaraai/east").NullType;
         }>;

package/dist/src/overlays/menu/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/overlays/menu/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACH,KAAK,QAAQ,EACb,KAAK,kBAAkB,EAGvB,UAAU,EACV,WAAW,EACX,SAAS,EACT,UAAU,EACV,UAAU,EACb,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EACH,YAAY,EACZ,aAAa,EACb,KAAK,SAAS,EAEjB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACH,YAAY,EACZ,aAAa,EACb,KAAK,SAAS,EACd,aAAa,EACb,KAAK,gBAAgB,GACxB,MAAM,YAAY,CAAC;AAMpB;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,QAAQ,EAAE,UAAU,CAAC;IAC9B,OAAO,EAAE,eAAe,CAAC;IACzB,KAAK,EAAE,SAAS,CAAC,YAAY,CAAC,CAAC;IAC/B,KAAK,EAAE,UAAU,CAAC,aAAa,CAAC,CAAC;CACpC,CAIC,CAAC;AAEH;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,OAAO,QAAQ,CAAC;AAMvC;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,iBAAS,cAAc,CACnB,KAAK,EAAE,kBAAkB,CAAC,OAAO,UAAU,CAAC,EAC5C,KAAK,EAAE,kBAAkB,CAAC,OAAO,UAAU,CAAC,EAC5C,QAAQ,CAAC,EAAE,kBAAkB,CAAC,OAAO,WAAW,CAAC,GAClD,QAAQ,CAAC,YAAY,CAAC,CAMxB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,iBAAS,mBAAmB,IAAI,QAAQ,CAAC,YAAY,CAAC,CAErD;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,iBAAS,UAAU,CACf,OAAO,EAAE,kBAAkB,CAAC,eAAe,CAAC,EAC5C,KAAK,EAAE,kBAAkB,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC,EAClD,KAAK,CAAC,EAAE,SAAS,GAClB,QAAQ,CAAC,eAAe,CAAC,CAkB3B;AAMD;;;;;;GAMG;AACH,eAAO,MAAM,IAAI;IACb;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;;IAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;;IAEH;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;;;QAGC;;;;;;;;;;;WAWG;;qBArPE,eAAe;mBACjB,SAAS,CAAC,YAAY,CAAC;mBACvB,UAAU,CAAC,aAAa,CAAC;;QAqP5B;;;;;;;;WAQG;;;;;;;;;QAEH;;;;;;;WAOG;;;;;;;;;;;;;;;;;QAEH;;;;;;;;;;;;;;;;;;;WAmBG;;;;;;;;;;;;;;;;CAGD,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/overlays/menu/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACH,KAAK,QAAQ,EACb,KAAK,kBAAkB,EAKvB,UAAU,EACV,SAAS,EACT,UAAU,EACV,UAAU,EACb,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EACH,YAAY,EACZ,aAAa,EACb,KAAK,eAAe,EACpB,KAAK,SAAS,EAEjB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACH,YAAY,EACZ,aAAa,EACb,KAAK,eAAe,EACpB,KAAK,SAAS,EACd,aAAa,EACb,KAAK,gBAAgB,GACxB,MAAM,YAAY,CAAC;AAMpB;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,QAAQ,EAAE,UAAU,CAAC;IAC9B,OAAO,EAAE,eAAe,CAAC;IACzB,KAAK,EAAE,SAAS,CAAC,YAAY,CAAC,CAAC;IAC/B,KAAK,EAAE,UAAU,CAAC,aAAa,CAAC,CAAC;CACpC,CAIC,CAAC;AAEH;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,OAAO,QAAQ,CAAC;AAMvC;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,iBAAS,cAAc,CACnB,KAAK,EAAE,kBAAkB,CAAC,OAAO,UAAU,CAAC,EAC5C,KAAK,EAAE,kBAAkB,CAAC,OAAO,UAAU,CAAC,EAC5C,OAAO,CAAC,EAAE,eAAe,GAC1B,QAAQ,CAAC,YAAY,CAAC,CASxB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,iBAAS,oBAAoB,CACzB,KAAK,EAAE,kBAAkB,CAAC,OAAO,UAAU,CAAC,GAC7C,QAAQ,CAAC,YAAY,CAAC,CAIxB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,iBAAS,mBAAmB,IAAI,QAAQ,CAAC,YAAY,CAAC,CAErD;AAMD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,WAAY,SAAQ,SAAS;IAC1C,qDAAqD;IACrD,OAAO,EAAE,kBAAkB,CAAC,eAAe,CAAC,CAAC;IAC7C,kFAAkF;IAClF,KAAK,EAAE,kBAAkB,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC,CAAC;CACtD;AAED,iBAAS,UAAU,CACf,OAAO,EAAE,WAAW,GACrB,QAAQ,CAAC,eAAe,CAAC,CAoB3B;AAMD;;;;;;GAMG;AACH,eAAO,MAAM,IAAI;IACb;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;;IAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;;IAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;;IAEH;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;;;QAGC;;;;;;;;;;;WAWG;;qBAhUE,eAAe;mBACjB,SAAS,CAAC,YAAY,CAAC;mBACvB,UAAU,CAAC,aAAa,CAAC;;QAgU5B;;;;;;;;;;WAUG;;;;;;;;;;;;;;;QAEH;;;;;;;WAOG;;;;;;;;;;;;;;;;;QAEH;;;;;;;;;;;;;;;;;;;WAmBG;;;;;;;;;;;;;;;;CAGD,CAAC"}

package/dist/src/overlays/menu/index.js

@@ -2,7 +2,7 @@
  * Copyright (c) 2025 Elara AI Pty Ltd
  * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
  */
-import { East, variant, StringType, BooleanType, ArrayType, OptionType, StructType, } from "@elaraai/east";
+import { East, variant, some, none, StringType, ArrayType, OptionType, StructType, } from "@elaraai/east";
 import { UIComponentType } from "../../component.js";
 import { MenuItemType, MenuStyleType, PlacementType, } from "./types.js";
 // Re-export types
@@ -35,7 +35,7 @@ export const MenuType = StructType({
  *
  * @param value - Unique identifier for the item
  * @param label - Display text for the item
- * @param disabled - Whether the item is disabled
+ * @param options - Optional icon / accelerator / disabled / destructive fields
  * @returns An East expression representing the menu item
  *
  * @example
@@ -44,27 +44,34 @@ export const MenuType = StructType({
  * import { Menu, Button, UIComponentType } from "@elaraai/east-ui";
  *
  * const example = East.function([], UIComponentType, $ => {
- *     return Menu.Root(
- *         Button.Root("Actions"),
- *         [
- *             Menu.Item("edit", "Edit"),
- *             Menu.Item("delete", "Delete", true),
- *         ]
- *     );
+ *     return Menu.Root({
+ *         trigger: Button.Root("Actions"),
+ *         items: [
+ *             Menu.Item("edit", "Edit · rename", { icon: "pen" }),
+ *             Menu.Item("duplicate", "Duplicate", { icon: "copy", command: "⌘D" }),
+ *             Menu.Separator(),
+ *             Menu.Item("archive", "Archive", { icon: "trash", destructive: true }),
+ *         ],
+ *     });
  * });
  * ```
  */
-function createMenuItem(value, label, disabled) {
+function createMenuItem(value, label, options) {
     return East.value(variant("Item", {
         value: value,
         label: label,
-        disabled: disabled !== undefined ? variant("some", disabled) : variant("none", null),
+        disabled: options?.disabled !== undefined ? some(options.disabled) : none,
+        icon: options?.icon !== undefined ? some(options.icon) : none,
+        command: options?.command !== undefined ? some(options.command) : none,
+        destructive: options?.destructive !== undefined ? some(options.destructive) : none,
     }), MenuItemType);
 }
 /**
- * Creates a menu separator.
+ * Creates a menu group label — the uppercase mono eyebrow naming the
+ * section of items below it.
  *
- * @returns An East expression representing a menu separator
+ * @param label - Heading text — rendered uppercase in the mono eyebrow style
+ * @returns An East expression representing the group label
  *
  * @example
  * ```ts
@@ -72,30 +79,26 @@ function createMenuItem(value, label, disabled) {
  * import { Menu, Button, UIComponentType } from "@elaraai/east-ui";
  *
  * const example = East.function([], UIComponentType, $ => {
- *     return Menu.Root(
- *         Button.Root("File"),
- *         [
- *             Menu.Item("new", "New"),
- *             Menu.Separator(),
- *             Menu.Item("exit", "Exit"),
- *         ]
- *     );
+ *     return Menu.Root({
+ *         trigger: Button.Root("Actions"),
+ *         items: [
+ *             Menu.GroupLabel("Actions"),
+ *             Menu.Item("edit", "Edit · rename", { icon: "pen" }),
+ *             Menu.Item("export", "Export CSV", { icon: "download" }),
+ *         ],
+ *     });
  * });
  * ```
  */
-function createMenuSeparator() {
-    return East.value(variant("Separator", null), MenuItemType);
+function createMenuGroupLabel(label) {
+    return East.value(variant("GroupLabel", {
+        label: label,
+    }), MenuItemType);
 }
-// ============================================================================
-// Menu Factory
-// ============================================================================
 /**
- * Creates a Menu component.
+ * Creates a menu separator.
  *
- * @param trigger - The element that triggers the menu
- * @param items - Array of menu items
- * @param style - Optional style configuration
- * @returns An East expression representing the Menu component
+ * @returns An East expression representing a menu separator
  *
  * @example
  * ```ts
@@ -104,32 +107,35 @@ function createMenuSeparator() {
  *
  * const example = East.function([], UIComponentType, $ => {
  *     return Menu.Root(
- *         Button.Root("Actions"),
+ *         Button.Root("File"),
  *         [
- *             Menu.Item("edit", "Edit"),
+ *             Menu.Item("new", "New"),
  *             Menu.Separator(),
- *             Menu.Item("delete", "Delete"),
- *         ],
- *         { placement: "bottom-start" }
+ *             Menu.Item("exit", "Exit"),
+ *         ]
  *     );
  * });
  * ```
  */
-function createMenu(trigger, items, style) {
-    const placementValue = style?.placement
+function createMenuSeparator() {
+    return East.value(variant("Separator", null), MenuItemType);
+}
+function createMenu(options) {
+    const { trigger, items, ...style } = options;
+    const placementValue = style.placement
         ? (typeof style.placement === "string"
             ? East.value(variant(style.placement, null), PlacementType)
             : style.placement)
         : undefined;
     const styleValue = placementValue !== undefined
         ? East.value({
-            placement: variant("some", placementValue),
+            placement: some(placementValue),
         }, MenuStyleType)
         : undefined;
     return East.value(variant("Menu", {
         trigger: trigger,
         items: items,
-        style: styleValue ? variant("some", styleValue) : variant("none", null),
+        style: styleValue ? some(styleValue) : none,
     }), UIComponentType);
 }
 // ============================================================================
@@ -140,15 +146,13 @@ function createMenu(trigger, items, style) {
  *
  * @remarks
  * Menu provides a dropdown menu triggered by a UI element.
- * Use `Menu.Root(trigger, items, style)` to create a menu, `Menu.Item(value, label)` for items, and `Menu.Separator()` for dividers.
+ * Use `Menu.Root({ trigger, items, ... })` to create a menu, `Menu.Item(value, label)` for items, and `Menu.Separator()` for dividers.
  */
 export const Menu = {
     /**
      * Creates a Menu component with a trigger and menu items.
      *
-     * @param trigger - The element that triggers the menu
-     * @param items - Array of menu items
-     * @param style - Optional style configuration
+     * @param options - Required `trigger` + `items`, optional visual style fields
      * @returns An East expression representing the Menu component
      *
      * @remarks
@@ -161,14 +165,14 @@ export const Menu = {
      * import { Menu, Button, UIComponentType } from "@elaraai/east-ui";
      *
      * const example = East.function([], UIComponentType, $ => {
-     *     return Menu.Root(
-     *         Button.Root("Actions"),
-     *         [
+     *     return Menu.Root({
+     *         trigger: Button.Root("Actions"),
+     *         items: [
      *             Menu.Item("edit", "Edit"),
      *             Menu.Separator(),
      *             Menu.Item("delete", "Delete"),
-     *         ]
-     *     );
+     *         ],
+     *     });
      * });
      * ```
      */
@@ -178,12 +182,15 @@ export const Menu = {
      *
      * @param value - Unique identifier for the item
      * @param label - Display text for the item
-     * @param disabled - Whether the item is disabled
+     * @param options - Optional icon / accelerator / disabled / destructive fields
      * @returns An East expression representing the menu item
      *
      * @remarks
      * Menu items are clickable entries within a Menu. Each item has a unique
-     * value for identification and a label for display.
+     * value for identification and a label for display. Items can carry a
+     * leading Font Awesome solid icon, a right-aligned keyboard accelerator,
+     * and a destructive flag (negative ink — place destructive items at the
+     * bottom, after a separator).
      *
      * @example
      * ```ts
@@ -191,17 +198,49 @@ export const Menu = {
      * import { Menu, Button, UIComponentType } from "@elaraai/east-ui";
      *
      * const example = East.function([], UIComponentType, $ => {
-     *     return Menu.Root(
-     *         Button.Root("Actions"),
-     *         [
-     *             Menu.Item("edit", "Edit"),
-     *             Menu.Item("delete", "Delete", true), // disabled
-     *         ]
-     *     );
+     *     return Menu.Root({
+     *         trigger: Button.Root("Actions"),
+     *         items: [
+     *             Menu.Item("edit", "Edit · rename", { icon: "pen" }),
+     *             Menu.Item("duplicate", "Duplicate", { icon: "copy", command: "⌘D" }),
+     *             Menu.Item("save", "Save", { disabled: true }),
+     *             Menu.Separator(),
+     *             Menu.Item("archive", "Archive", { icon: "trash", destructive: true }),
+     *         ],
+     *     });
      * });
      * ```
      */
     Item: createMenuItem,
+    /**
+     * Creates a menu group label — the uppercase mono eyebrow naming the
+     * section of items below it.
+     *
+     * @param label - Heading text — rendered uppercase in the mono eyebrow style
+     * @returns An East expression representing the group label
+     *
+     * @remarks
+     * Use a group label to head a run of related items, in the same mono
+     * uppercase eyebrow style used across the spec.
+     *
+     * @example
+     * ```ts
+     * import { East } from "@elaraai/east";
+     * import { Menu, Button, UIComponentType } from "@elaraai/east-ui";
+     *
+     * const example = East.function([], UIComponentType, $ => {
+     *     return Menu.Root({
+     *         trigger: Button.Root("Actions"),
+     *         items: [
+     *             Menu.GroupLabel("Actions"),
+     *             Menu.Item("edit", "Edit · rename", { icon: "pen" }),
+     *             Menu.Item("export", "Export CSV", { icon: "download" }),
+     *         ],
+     *     });
+     * });
+     * ```
+     */
+    GroupLabel: createMenuGroupLabel,
     /**
      * Creates a menu separator for visual grouping.
      *
@@ -248,9 +287,11 @@ export const Menu = {
          * Menu item variant type.
          *
          * @remarks
-         * Menu items can be either an Item (clickable menu entry) or a Separator (visual divider).
+         * Menu items can be an Item (clickable menu entry), a GroupLabel
+         * (uppercase mono eyebrow heading), or a Separator (visual divider).
          *
-         * @property Item - A clickable menu item with value, label, and optional disabled state
+         * @property Item - A clickable menu item with value, label, and optional icon / accelerator / disabled / destructive state
+         * @property GroupLabel - An uppercase eyebrow heading for the items that follow
          * @property Separator - A visual separator between menu items
          */
         Item: MenuItemType,

package/dist/src/overlays/menu/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/overlays/menu/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/overlays/menu/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAGH,IAAI,EACJ,OAAO,EACP,IAAI,EACJ,IAAI,EACJ,UAAU,EACV,SAAS,EACT,UAAU,EACV,UAAU,GACb,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EACH,YAAY,EACZ,aAAa,EAGb,aAAa,GAChB,MAAM,YAAY,CAAC;AAEpB,kBAAkB;AAClB,OAAO,EACH,YAAY,EACZ,aAAa,EAGb,aAAa,GAEhB,MAAM,YAAY,CAAC;AAEpB,+EAA+E;AAC/E,YAAY;AACZ,+EAA+E;AAE/E;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,QAAQ,GAIhB,UAAU,CAAC;IACZ,OAAO,EAAE,eAAe;IACxB,KAAK,EAAE,SAAS,CAAC,YAAY,CAAC;IAC9B,KAAK,EAAE,UAAU,CAAC,aAAa,CAAC;CACnC,CAAC,CAAC;AAOH,+EAA+E;AAC/E,sBAAsB;AACtB,+EAA+E;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,SAAS,cAAc,CACnB,KAA4C,EAC5C,KAA4C,EAC5C,OAAyB;IAEzB,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE;QAC9B,KAAK,EAAE,KAAK;QACZ,KAAK,EAAE,KAAK;QACZ,QAAQ,EAAE,OAAO,EAAE,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI;QACzE,IAAI,EAAE,OAAO,EAAE,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI;QAC7D,OAAO,EAAE,OAAO,EAAE,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI;QACtE,WAAW,EAAE,OAAO,EAAE,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,IAAI;KACrF,CAAC,EAAE,YAAY,CAAC,CAAC;AACtB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,SAAS,oBAAoB,CACzB,KAA4C;IAE5C,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,YAAY,EAAE;QACpC,KAAK,EAAE,KAAK;KACf,CAAC,EAAE,YAAY,CAAC,CAAC;AACtB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,SAAS,mBAAmB;IACxB,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,WAAW,EAAE,IAAI,CAAC,EAAE,YAAY,CAAC,CAAC;AAChE,CAAC;AAqCD,SAAS,UAAU,CACf,OAAoB;IAEpB,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,KAAK,EAAE,GAAG,OAAO,CAAC;IAE7C,MAAM,cAAc,GAAG,KAAK,CAAC,SAAS;QAClC,CAAC,CAAC,CAAC,OAAO,KAAK,CAAC,SAAS,KAAK,QAAQ;YAClC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,SAAS,EAAE,IAAI,CAAC,EAAE,aAAa,CAAC;YAC3D,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC;QACtB,CAAC,CAAC,SAAS,CAAC;IAEhB,MAAM,UAAU,GAAG,cAAc,KAAK,SAAS;QAC3C,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC;YACT,SAAS,EAAE,IAAI,CAAC,cAAc,CAAC;SAClC,EAAE,aAAa,CAAC;QACjB,CAAC,CAAC,SAAS,CAAC;IAEhB,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE;QAC9B,OAAO,EAAE,OAAO;QAChB,KAAK,EAAE,KAAK;QACZ,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,IAAI;KAC9C,CAAC,EAAE,eAAe,CAAC,CAAC;AACzB,CAAC;AAED,+EAA+E;AAC/E,wBAAwB;AACxB,+EAA+E;AAE/E;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG;IAChB;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,IAAI,EAAE,UAAU;IAChB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,IAAI,EAAE,cAAc;IACpB;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,UAAU,EAAE,oBAAoB;IAChC;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,SAAS,EAAE,mBAAmB;IAC9B,KAAK,EAAE;QACH;;;;;;;;;;;WAWG;QACH,IAAI,EAAE,QAAQ;QACd;;;;;;;;;;WAUG;QACH,IAAI,EAAE,YAAY;QAClB;;;;;;;WAOG;QACH,KAAK,EAAE,aAAa;QACpB;;;;;;;;;;;;;;;;;;;WAmBG;QACH,SAAS,EAAE,aAAa;KAC3B;CACK,CAAC"}

package/dist/src/overlays/menu/types.d.ts

@@ -2,16 +2,21 @@
  * Copyright (c) 2025 Elara AI Pty Ltd
  * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
  */
-import { type SubtypeExprOrValue, OptionType, StructType, StringType, NullType, BooleanType, VariantType } from "@elaraai/east";
+import { type ExprType, type SubtypeExprOrValue, OptionType, StructType, StringType, NullType, BooleanType, VariantType } from "@elaraai/east";
 import { PlacementType, type PlacementLiteral } from "../tooltip/types.js";
+import { type IconName } from "../../display/icon/types.js";
 export { PlacementType, type PlacementLiteral } from "../tooltip/types.js";
 /**
  * Menu item variant type.
  *
  * @remarks
- * Menu items can be either an Item (clickable menu entry) or a Separator (visual divider).
+ * Menu items can be an Item (clickable menu entry), a GroupLabel (uppercase
+ * mono eyebrow naming the section below it), or a Separator (visual divider).
+ * Destructive items render in the negative ink and belong at the bottom of
+ * the menu, after a separator.
  *
- * @property Item - A clickable menu item with value, label, and optional disabled state
+ * @property Item - A clickable menu item with value, label, and optional icon / accelerator / disabled / destructive state
+ * @property GroupLabel - An uppercase eyebrow heading for the items that follow
  * @property Separator - A visual separator between menu items
  */
 export declare const MenuItemType: VariantType<{
@@ -23,6 +28,17 @@ export declare const MenuItemType: VariantType<{
         readonly label: StringType;
         /** Whether the item is disabled */
         readonly disabled: OptionType<BooleanType>;
+        /** Font Awesome solid icon name rendered before the label (e.g. `"pen"`, `"copy"`) */
+        readonly icon: OptionType<StringType>;
+        /** Keyboard accelerator shown right-aligned in mono (e.g. `"⌘D"`) */
+        readonly command: OptionType<StringType>;
+        /** Whether the action is destructive — renders in the negative ink */
+        readonly destructive: OptionType<BooleanType>;
+    }>;
+    /** An uppercase eyebrow heading for the items that follow */
+    readonly GroupLabel: StructType<{
+        /** Heading text — rendered uppercase in the mono eyebrow style */
+        readonly label: StringType;
     }>;
     /** A visual separator between items */
     readonly Separator: NullType;
@@ -31,6 +47,24 @@ export declare const MenuItemType: VariantType<{
  * Type representing the MenuItem structure.
  */
 export type MenuItemType = typeof MenuItemType;
+/**
+ * TypeScript interface for the optional fields of a menu item.
+ *
+ * @property disabled - Whether the item is disabled
+ * @property icon - Font Awesome solid icon name rendered before the label
+ * @property command - Keyboard accelerator shown right-aligned in mono
+ * @property destructive - Whether the action is destructive (negative ink)
+ */
+export interface MenuItemOptions {
+    /** Whether the item is disabled */
+    disabled?: SubtypeExprOrValue<typeof BooleanType>;
+    /** Font Awesome solid icon name rendered before the label (the icon set is `fas`-only per the spec) */
+    icon?: IconName | ExprType<StringType>;
+    /** Keyboard accelerator shown right-aligned in mono (e.g. `"⌘D"`) */
+    command?: SubtypeExprOrValue<typeof StringType>;
+    /** Whether the action is destructive — renders in the negative ink */
+    destructive?: SubtypeExprOrValue<typeof BooleanType>;
+}
 /**
  * Visual-only style struct for Menu.
  *

package/dist/src/overlays/menu/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/overlays/menu/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACH,KAAK,kBAAkB,EACvB,UAAU,EACV,UAAU,EACV,UAAU,EACV,QAAQ,EACR,WAAW,EACX,WAAW,EACd,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,aAAa,EAAE,KAAK,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAG3E,OAAO,EAAE,aAAa,EAAE,KAAK,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAM3E;;;;;;;;GAQG;AACH,eAAO,MAAM,YAAY;IACrB,4BAA4B;;QAExB,qCAAqC;;QAErC,gCAAgC;;QAEhC,mCAAmC;;;IAKvC,uCAAuC;;EAEzC,CAAC;AAEH;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,OAAO,YAAY,CAAC;AAM/C;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;EAExB,CAAC;AAEH;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,OAAO,aAAa,CAAC;AAMjD;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACtB,yDAAyD;IACzD,SAAS,CAAC,EAAE,kBAAkB,CAAC,aAAa,CAAC,GAAG,gBAAgB,CAAC;CACpE"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/overlays/menu/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACH,KAAK,QAAQ,EACb,KAAK,kBAAkB,EACvB,UAAU,EACV,UAAU,EACV,UAAU,EACV,QAAQ,EACR,WAAW,EACX,WAAW,EACd,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,aAAa,EAAE,KAAK,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC3E,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AAG5D,OAAO,EAAE,aAAa,EAAE,KAAK,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAM3E;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,YAAY;IACrB,4BAA4B;;QAExB,qCAAqC;;QAErC,gCAAgC;;QAEhC,mCAAmC;;QAEnC,sFAAsF;;QAEtF,qEAAqE;;QAErE,sEAAsE;;;IAG1E,6DAA6D;;QAEzD,kEAAkE;;;IAGtE,uCAAuC;;EAEzC,CAAC;AAEH;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,OAAO,YAAY,CAAC;AAE/C;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC5B,mCAAmC;IACnC,QAAQ,CAAC,EAAE,kBAAkB,CAAC,OAAO,WAAW,CAAC,CAAC;IAClD,uGAAuG;IACvG,IAAI,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC,UAAU,CAAC,CAAC;IACvC,qEAAqE;IACrE,OAAO,CAAC,EAAE,kBAAkB,CAAC,OAAO,UAAU,CAAC,CAAC;IAChD,sEAAsE;IACtE,WAAW,CAAC,EAAE,kBAAkB,CAAC,OAAO,WAAW,CAAC,CAAC;CACxD;AAMD;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;EAExB,CAAC;AAEH;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,OAAO,aAAa,CAAC;AAMjD;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACtB,yDAAyD;IACzD,SAAS,CAAC,EAAE,kBAAkB,CAAC,aAAa,CAAC,GAAG,gBAAgB,CAAC;CACpE"}