@geoffcox/sterling-svelte 2.0.2 → 2.0.4

package/dist/MenuButton.svelte

@@ -0,0 +1,156 @@
+<svelte:options runes={true} />
+
+<script lang="ts">
+  import { setContext, tick, type Snippet } from 'svelte';
+  import type { HTMLButtonAttributes } from 'svelte/elements';
+  import { clickOutside } from './actions/clickOutside';
+  import Button from './Button.svelte';
+  import Menu from './Menu.svelte';
+  import { MENU_ITEM_CONTEXT_KEY } from './MenuItem.constants';
+  import type { MenuItemContext } from './MenuItem.types';
+  import Popover from './Popover.svelte';
+  import type { PopoverPlacement } from './Popover.types';
+
+  const uuid = $props.id();
+
+  type Props = HTMLButtonAttributes & {
+    items: Snippet;
+    menuClass?: string;
+    onOpen?: (value: string) => void;
+    onClose?: (value: string) => void;
+    onSelect?: (value: string) => void;
+    open?: boolean | null | undefined;
+    popoverPlacement?: PopoverPlacement;
+    value?: string;
+  };
+
+  let {
+    children,
+    class: _class,
+    items,
+    menuClass,
+    open = $bindable(false),
+    onClose,
+    onOpen,
+    onSelect,
+    popoverPlacement = 'bottom-start',
+    value,
+    ...rest
+  }: Props = $props();
+
+  const instanceId = `MenuButton-${uuid}`;
+
+  let buttonRef: Button;
+  let openValues: string[] = $state([]);
+  let menuRef: Menu;
+  let menuId = $derived(`${value}-menu-${instanceId}`);
+  let prevOpen = $state(open);
+  let reference: HTMLDivElement | undefined = $state();
+
+  export const click = () => {
+    buttonRef?.click();
+  };
+
+  export const blur = () => {
+    buttonRef?.blur();
+  };
+
+  export const focus = (options?: FocusOptions) => {
+    buttonRef?.focus(options);
+  };
+
+  // update open based on openValues
+  $effect(() => {
+    open = openValues.length > 0;
+  });
+
+  // update openValues based on open
+  $effect(() => {
+    if (open) {
+      openValues = openValues.length > 0 ? openValues : ['menu-button'];
+    } else {
+      openValues = openValues.length === 0 ? openValues : [];
+    }
+  });
+
+  // focus when closing
+  $effect(() => {
+    if (!open && open !== prevOpen) {
+      focus();
+    }
+    prevOpen = open;
+  });
+
+  const onClick = async () => {
+    if (!open) {
+      openValues = ['menu-button'];
+      open = true;
+      await tick();
+      menuRef?.focusFirstMenuItem();
+    } else {
+      open = false;
+      openValues = [];
+    }
+  };
+
+  const closeAllMenus = () => {
+    openValues = [];
+    open = false;
+  };
+
+  const onClickOutside = (event: MouseEvent) => {
+    let element: HTMLElement | null = event.target as HTMLElement;
+    while (element) {
+      if (element.getAttribute('data-root-value') === value) {
+        return;
+      }
+      element = element.parentElement;
+    }
+    closeAllMenus?.();
+  };
+
+  // ----- Context ----- //
+
+  setContext<MenuItemContext>(MENU_ITEM_CONTEXT_KEY, {
+    depth: 1,
+    get openValues() {
+      return openValues;
+    },
+    set openValues(value: string[]) {
+      openValues = value;
+    },
+    rootValue: value,
+    closeContainingMenu: () => {
+      open = false;
+    },
+    onOpen,
+    onClose,
+    onSelect
+  });
+</script>
+
+<Button
+  bind:this={buttonRef}
+  aria-controls={menuId}
+  aria-expanded={!!open}
+  aria-haspopup={!!children}
+  aria-owns={menuId}
+  class={['sterling-menu-button', _class]}
+  data-value={value}
+  data-root-value={value}
+  {...rest}
+  onclick={onClick}
+>
+  <div
+    class="reference"
+    bind:this={reference}
+    use:clickOutside={{ onclickoutside: onClickOutside }}
+  >
+    {@render children?.()}
+  </div>
+  <Popover {reference} {open} placement={popoverPlacement}>
+    <Menu bind:this={menuRef} id={menuId} class={menuClass}>
+      {@render items?.()}
+    </Menu>
+  </Popover>
+</Button>

package/dist/MenuButton.svelte.d.ts

@@ -0,0 +1,20 @@
+import { type Snippet } from 'svelte';
+import type { HTMLButtonAttributes } from 'svelte/elements';
+import type { PopoverPlacement } from './Popover.types';
+type Props = HTMLButtonAttributes & {
+    items: Snippet;
+    menuClass?: string;
+    onOpen?: (value: string) => void;
+    onClose?: (value: string) => void;
+    onSelect?: (value: string) => void;
+    open?: boolean | null | undefined;
+    popoverPlacement?: PopoverPlacement;
+    value?: string;
+};
+declare const MenuButton: import("svelte").Component<Props, {
+    click: () => void;
+    blur: () => void;
+    focus: (options?: FocusOptions) => void;
+}, "open">;
+type MenuButton = ReturnType<typeof MenuButton>;
+export default MenuButton;

package/dist/MenuItem.constants.d.ts

@@ -0,0 +1,2 @@
+export declare const MENU_ITEM_CONTEXT_KEY = "sterlingMenuItem";
+export declare const MENU_ITEM_ROLES: readonly ["menuitem", "menuitemcheckbox", "menuitemradio"];

package/dist/MenuItem.constants.js

@@ -0,0 +1,2 @@
+export const MENU_ITEM_CONTEXT_KEY = 'sterlingMenuItem';
+export const MENU_ITEM_ROLES = ['menuitem', 'menuitemcheckbox', 'menuitemradio'];

package/dist/MenuItem.svelte

@@ -0,0 +1,431 @@
+<svelte:options runes={true} />
+
+<script lang="ts">
+  import { getContext, setContext, tick, type Snippet } from 'svelte';
+  import type {
+    HTMLButtonAttributes,
+    KeyboardEventHandler,
+    MouseEventHandler
+  } from 'svelte/elements';
+  import Menu from './Menu.svelte';
+  import { MENU_BAR_CONTEXT_KEY } from './MenuBar.constants';
+  import type { MenuBarContext } from './MenuBar.types';
+  import { MENU_ITEM_CONTEXT_KEY } from './MenuItem.constants';
+  import type { MenuItemContext, MenuItemRole } from './MenuItem.types';
+  import { isElementEnabledMenuItem } from './MenuItem.utils';
+  import Popover from './Popover.svelte';
+  import { usingKeyboard } from './mediaQueries/usingKeyboard';
+
+  const uuid = $props.id();
+
+  type Props = HTMLButtonAttributes & {
+    checked?: boolean | null;
+    item?: Snippet;
+    menuClass?: string;
+    onClose?: (value: string) => void;
+    onOpen?: (value: string) => void;
+    onSelect?: (value: string) => void;
+    role?: MenuItemRole;
+    shortcut?: string | Snippet;
+    text?: string | Snippet;
+    value: string;
+  };
+
+  let {
+    checked,
+    children,
+    class: _class,
+    disabled,
+    item,
+    menuClass,
+    onClose,
+    onOpen,
+    onSelect,
+    role = 'menuitem',
+    text,
+    shortcut,
+    value,
+    ...rest
+  }: Props = $props();
+
+  const menuItemContext = getContext<MenuItemContext>(MENU_ITEM_CONTEXT_KEY) || {};
+
+  const menuBarContext = getContext<MenuBarContext>(MENU_BAR_CONTEXT_KEY) || {};
+
+  const instanceId = `MenuItem-${uuid}`;
+
+  let displayId = $derived(`${value}-display-${instanceId}`);
+  let open = $derived(menuItemContext.openValues?.includes(value));
+  let prevOpen = $state(menuItemContext.openValues?.includes(value));
+  let menuId = $derived(`${value}-menu-${instanceId}`);
+
+  let menuItemRef: HTMLButtonElement | undefined = $state();
+  let menuRef: Menu | undefined = $state();
+
+  //#region methods
+
+  export const blur = () => {
+    menuItemRef?.blur();
+  };
+
+  export const click = () => {
+    menuItemRef?.click();
+  };
+
+  export const focus = (options?: FocusOptions) => {
+    menuItemRef?.focus(options);
+  };
+
+  //#endregion
+
+  //#region events
+
+  const raiseClose = (value: string) => {
+    onClose?.(value);
+    menuItemContext.onClose?.(value);
+  };
+
+  const raiseOpen = (value: string) => {
+    onOpen?.(value);
+    menuItemContext.onOpen?.(value);
+  };
+
+  const raiseSelect = (value: string) => {
+    onSelect?.(value);
+    menuItemContext.onSelect?.(value);
+  };
+
+  $effect(() => {
+    if (open !== prevOpen) {
+      open ? raiseOpen(value) : raiseClose(value);
+    }
+    prevOpen = open;
+  });
+
+  //#endregion
+
+  //#region focus
+
+  const focusPreviousMenuItem = () => {
+    let candidate =
+      menuItemRef?.previousElementSibling || menuItemRef?.parentElement?.lastElementChild;
+    while (candidate && !isElementEnabledMenuItem(candidate)) {
+      candidate = candidate.previousElementSibling || menuItemRef?.parentElement?.lastElementChild;
+
+      if (candidate === menuItemRef) {
+        return false;
+      }
+    }
+    (candidate as HTMLElement)?.focus();
+    return !!candidate;
+  };
+
+  const focusNextMenuItem = () => {
+    let candidate =
+      menuItemRef?.nextElementSibling || menuItemRef?.parentElement?.firstElementChild;
+    while (candidate && !isElementEnabledMenuItem(candidate)) {
+      candidate = candidate.nextElementSibling || menuItemRef?.parentElement?.firstElementChild;
+
+      if (candidate === menuItemRef) {
+        return false;
+      }
+    }
+    (candidate as HTMLElement)?.focus();
+    return !!candidate;
+  };
+
+  //#endregion
+
+  //#region open/close
+
+  // opens the menu for this menu item
+  const openMenu = () => {
+    if (!menuItemContext.openValues.includes(value)) {
+      // slice to depth to close any sibling menus that are open
+      menuItemContext.openValues = [
+        ...menuItemContext.openValues.slice(0, menuItemContext.depth),
+        value
+      ];
+    }
+  };
+
+  // closes the menu for this menu item
+  const closeMenu = async () => {
+    const index = menuItemContext.openValues.indexOf(value);
+    if (index !== -1) {
+      menuItemContext.openValues = [...menuItemContext.openValues.slice(0, index)];
+      await tick();
+      menuItemRef?.focus();
+    }
+  };
+
+  const closeAllMenus = () => {
+    menuItemContext.openValues = [];
+  };
+
+  //#endregion
+
+  //#region event handlers
+
+  const onKeyDown: KeyboardEventHandler<HTMLButtonElement> = async (event) => {
+    if (!disabled && !event.altKey && !event.ctrlKey && !event.shiftKey) {
+      switch (event.key) {
+        case 'ArrowDown':
+          // ARIA menubar/menuitem:
+          // If the currently focused menuitem has a submenu,
+          // opens the submenu and places focus on the first item in the submenu.
+          if (menuItemContext.isMenuBarItem && children) {
+            openMenu();
+            setTimeout(async () => {
+              await tick();
+              menuRef?.focusFirstMenuItem();
+            }, 10);
+            event.preventDefault();
+            event.stopPropagation();
+            return false;
+          }
+
+          if (!menuItemContext.isMenuBarItem) {
+            // ARIA menuitem:
+            // Moves focus to the next item, optionally wrapping from the last to the first.
+            focusNextMenuItem();
+            event.preventDefault();
+            event.stopPropagation();
+            return false;
+          }
+          break;
+        case 'ArrowLeft':
+          // ARIA menubar/menuitem:
+          // Moves focus to the previous item, optionally wrapping from the first to the last.
+          if (menuItemContext.isMenuBarItem) {
+            focusPreviousMenuItem();
+            event.preventDefault();
+            event.stopPropagation();
+            return false;
+          }
+
+          // ARIA menuitem:
+          // When focus is in a submenu of an item in a menu,
+          // closes the submenu and returns focus to the parent menuitem.
+          if (menuItemContext.depth && menuItemContext.depth > 1) {
+            menuItemContext.closeContainingMenu?.();
+            event.preventDefault();
+            event.stopPropagation();
+            return false;
+          }
+
+          // ARIA menubar/menuitem:
+          // When focus is in a submenu of an item in a menubar,
+          // closes the submenu,
+          // moves focus to the previous item in the menubar,
+          // and,
+          // if focus is now on a menuitem with a submenu,
+          // either opens the submenu of that menuitem without moving focus into the submenu,
+          // or opens the submenu of that menuitem and places focus on the first item in the submenu.
+          menuBarContext.openPreviousMenuBarItem?.();
+          event.preventDefault();
+          event.stopPropagation();
+          return false;
+        case 'ArrowRight':
+          // ARIA menubar:
+          // Moves focus to the next item, optionally wrapping from the last to the first.
+          if (menuItemContext.isMenuBarItem) {
+            focusNextMenuItem();
+            event.preventDefault();
+            event.stopPropagation();
+            return false;
+          }
+
+          // ARIA menuitem:
+          // When focus is in a menu and on a menuitem that has a submenu,
+          // opens the submenu and places focus on its first item
+          if (children) {
+            openMenu();
+            setTimeout(async () => {
+              await tick();
+              menuRef?.focusFirstMenuItem();
+            }, 10);
+            event.preventDefault();
+            event.stopPropagation();
+            return false;
+          }
+
+          // ARIA menubar/menuitem:
+          // When focus is in a menu and on an item that does not have a submenu,
+          // closes the submenu and any parent menus,
+          // moves focus to the next item in the menubar,
+          // and,
+          // if focus is now on a menuitem with a submenu,
+          // either opens the submenu of that menuitem without moving focus into the submenu,
+          // or opens the submenu of that menuitem and places focus on the first item in the submenu.
+          if (menuBarContext.openNextMenuBarItem) {
+            menuBarContext.openNextMenuBarItem();
+            event.preventDefault();
+            event.stopPropagation();
+            return false;
+          }
+          break;
+        case 'ArrowUp':
+          // ARIA menubar/menuitem:
+          // If the currently focused menuitem has a submenu,
+          // opens the submenu and places focus on the last item in the submenu.
+          if (menuItemContext.isMenuBarItem && children) {
+            openMenu();
+            setTimeout(async () => {
+              await tick();
+              menuRef?.focusLastMenuItem();
+            }, 10);
+            event.preventDefault();
+            event.stopPropagation();
+            return false;
+          }
+
+          // ARIA menuitem:
+          // Moves focus to the previous item, optionally wrapping from the first to the last.
+          if (!menuItemContext.isMenuBarItem) {
+            focusPreviousMenuItem();
+            event.preventDefault();
+            event.stopPropagation();
+            return false;
+          }
+          break;
+        case 'Escape':
+          // ARIA menuitem:
+          // Close the menu that contains focus and return focus to the element or context,
+          // e.g., menu button or parent menuitem, from which the menu was opened.
+          // open = false;
+          closeAllMenus();
+          event.preventDefault();
+          event.stopPropagation();
+          return false;
+      }
+    }
+    rest.onkeydown?.(event);
+  };
+
+  const onMouseEnter: MouseEventHandler<HTMLButtonElement> = (event) => {
+    menuItemRef?.focus();
+    rest.onmouseenter?.(event);
+  };
+
+  const onClick: MouseEventHandler<HTMLButtonElement> = (event) => {
+    if (!disabled) {
+      if (children) {
+        if (!menuItemContext.openValues.includes(value)) {
+          openMenu();
+          if ($usingKeyboard) {
+            setTimeout(async () => {
+              await tick();
+              menuRef?.focusFirstMenuItem();
+            }, 10);
+          }
+        } else {
+          closeMenu();
+        }
+        event.preventDefault();
+        event.stopPropagation();
+        return false;
+      } else {
+        raiseSelect(value);
+        closeAllMenus();
+        event.preventDefault();
+        event.stopPropagation();
+        return false;
+      }
+    }
+    rest.onclick?.(event);
+  };
+
+  //#endregion
+
+  //#region set context
+  let menuItemChildContext: MenuItemContext = {
+    isMenuBarItem: false,
+    get openValues() {
+      return menuItemContext.openValues;
+    },
+    set openValues(value: string[]) {
+      menuItemContext.openValues = value;
+    },
+    rootValue: menuItemContext.rootValue || value,
+    depth: menuItemContext.depth ? menuItemContext.depth + 1 : 1,
+    closeContainingMenu: closeMenu,
+    onOpen: raiseOpen,
+    onClose: raiseClose,
+    onSelect: raiseSelect
+  };
+
+  setContext<MenuItemContext>(MENU_ITEM_CONTEXT_KEY, menuItemChildContext);
+
+  //#endregion
+</script>
+
+{#snippet renderDefaultItem()}
+  <div class="default-item sterling-menu-item-display" class:disabled>
+    <div
+      class="check"
+      class:checkmark={role === 'menuitemcheckbox'}
+      class:bullet={role === 'menuitemradio'}
+      class:checked
+    ></div>
+    <div class="content">
+      {#if text}
+        {#if typeof text === 'string'}
+          {text}
+        {:else}
+          {@render text()}
+        {/if}
+      {/if}
+    </div>
+    <div class="shortcut">
+      {#if shortcut}
+        {#if typeof shortcut === 'string'}
+          {shortcut}
+        {:else}
+          {@render shortcut()}
+        {/if}
+      {/if}
+    </div>
+    <div class="chevron" class:has-children={!menuItemContext.isMenuBarItem && !!children}></div>
+  </div>
+{/snippet}
+
+<button
+  bind:this={menuItemRef}
+  aria-controls={menuId}
+  aria-disabled={disabled}
+  aria-expanded={open}
+  aria-haspopup={!!children}
+  aria-owns={menuId}
+  class={['sterling-menu-item', _class]}
+  class:using-keyboard={usingKeyboard}
+  data-value={value}
+  data-root-value={menuItemContext.rootValue}
+  {disabled}
+  {role}
+  tabindex={0}
+  type="button"
+  {...rest}
+  onclick={onClick}
+  onkeydown={onKeyDown}
+  onmouseenter={onMouseEnter}
+>
+  <div class="item" id={displayId}>
+    {#if item}
+      {@render item()}
+    {:else}
+      {@render renderDefaultItem()}
+    {/if}
+  </div>
+  {#if menuItemRef && open && children}
+    <Popover
+      reference={menuItemRef}
+      placement={menuItemContext.isMenuBarItem ? 'bottom-start' : 'right-start'}
+      {open}
+    >
+      <Menu bind:this={menuRef} id={menuId} class={menuClass}>
+        {@render children()}
+      </Menu>
+    </Popover>
+  {/if}
+</button>

package/dist/MenuItem.svelte.d.ts

@@ -0,0 +1,22 @@
+import { type Snippet } from 'svelte';
+import type { HTMLButtonAttributes } from 'svelte/elements';
+import type { MenuItemRole } from './MenuItem.types';
+type Props = HTMLButtonAttributes & {
+    checked?: boolean | null;
+    item?: Snippet;
+    menuClass?: string;
+    onClose?: (value: string) => void;
+    onOpen?: (value: string) => void;
+    onSelect?: (value: string) => void;
+    role?: MenuItemRole;
+    shortcut?: string | Snippet;
+    text?: string | Snippet;
+    value: string;
+};
+declare const MenuItem: import("svelte").Component<Props, {
+    blur: () => void;
+    click: () => void;
+    focus: (options?: FocusOptions) => void;
+}, "">;
+type MenuItem = ReturnType<typeof MenuItem>;
+export default MenuItem;

package/dist/MenuItem.types.d.ts

@@ -0,0 +1,20 @@
+import type { MENU_ITEM_ROLES } from './MenuItem.constants';
+type MenuItemRoleTuple = typeof MENU_ITEM_ROLES;
+export type MenuItemRole = MenuItemRoleTuple[number];
+export type MenuItemRegistration = {
+    value: string;
+    open: () => void;
+    close: () => void;
+    focus: () => void;
+};
+export type MenuItemContext = {
+    isMenuBarItem?: boolean;
+    openValues: string[];
+    rootValue?: string;
+    depth?: number;
+    closeContainingMenu?: () => void;
+    onOpen?: (value: string) => void;
+    onClose?: (value: string) => void;
+    onSelect?: (value: string) => void;
+};
+export {};

package/dist/MenuItem.types.js

@@ -0,0 +1 @@
+export {};

package/dist/MenuItem.utils.d.ts

@@ -0,0 +1,7 @@
+import type { MenuItemRegistration } from './MenuItem.types';
+export declare const focusPreviousChild: (children: MenuItemRegistration[], currentValue: string) => void;
+export declare const focusNextChild: (children: MenuItemRegistration[], currentValue: string) => void;
+export declare const focusFirstChild: (children: MenuItemRegistration[]) => void;
+export declare const focusLastChild: (children: MenuItemRegistration[]) => void;
+export declare const isElementMenuItem: (candidate: Element | null | undefined) => boolean;
+export declare const isElementEnabledMenuItem: (candidate: Element | null | undefined) => boolean;

package/dist/MenuItem.utils.js

@@ -0,0 +1,36 @@
+export const focusPreviousChild = (children, currentValue) => {
+    const index = children?.findIndex((menuItem) => menuItem.value === currentValue);
+    if (index !== -1) {
+        const focusIndex = index === 0 ? children.length - 1 : index - 1;
+        children[focusIndex].focus();
+    }
+};
+export const focusNextChild = (children, currentValue) => {
+    const index = children?.findIndex((menuItem) => menuItem.value === currentValue);
+    if (index !== -1) {
+        const focusIndex = (index + 1) % children.length;
+        children[focusIndex].focus();
+    }
+};
+export const focusFirstChild = (children) => {
+    children?.[0]?.focus();
+};
+export const focusLastChild = (children) => {
+    children?.[children.length - 1]?.focus();
+};
+export const isElementMenuItem = (candidate) => {
+    if (!candidate)
+        return false;
+    const dataValue = candidate?.getAttribute('data-value');
+    const role = candidate?.getAttribute('role');
+    return ((role === 'menuitem' || role === 'menuitemcheckbox' || role === 'menuitemradio') &&
+        dataValue !== null &&
+        dataValue !== undefined);
+};
+export const isElementEnabledMenuItem = (candidate) => {
+    if (!isElementMenuItem(candidate)) {
+        return false;
+    }
+    const disabled = candidate?.getAttribute('disabled');
+    return disabled === null || disabled === 'false';
+};