@inglorious/ui 8.6.0 → 9.0.0

package/src/navigation/menu/template.js

@@ -4,40 +4,76 @@
  * @typedef {import('@inglorious/web').TemplateResult} TemplateResult
  */
 
-import { html } from "@inglorious/web"
+import { html, nothing } from "@inglorious/web"
 import { classMap } from "@inglorious/web/directives/class-map"
 import { ref } from "@inglorious/web/directives/ref"
 
+import { Button } from "../../controls/button/index.js"
+import { anchorName } from "../../shared/anchor.js"
 import { applyElementProps } from "../../shared/apply-element-props.js"
+import { syncPopover } from "../../shared/top-layer.js"
 
 export const Menu = {
   /**
    * Main entrypoint for a menu list. Delegates to the base renderer for overrides.
    * Menus render selectable items and optional dividers.
+   * With a `trigger`, the menu is a native popover anchored to a button that
+   * opens it: the browser places it, flipping it to stay on screen, and closes
+   * it on Esc, a press outside, or a pick.
    * @param {MenuProps} props
    * @returns {TemplateResult | null}
    */
   render(props) {
-    return this.renderMenu(props)
+    if (!props.trigger) return this.renderMenu(props)
+    return html`${this.renderTrigger(props)}${this.renderMenu(props)}`
   },
 
   /**
-   * Renders the menu container and iterates items when open.
-   * Each item is delegated to `renderItem`.
+   * Renders the button that opens an anchored menu. It is the popover's
+   * `commandfor` invoker, so the browser toggles the menu from it and does
+   * not count a press on it as a press outside.
+   * @param {MenuProps} props
+   * @returns {TemplateResult}
+   */
+  renderTrigger(props) {
+    const { id, isOpen = false, trigger, triggerProps, onToggle } = props
+
+    return Button.render({
+      variant: "ghost",
+      ...triggerProps,
+      children: trigger,
+      commandfor: id,
+      command: "toggle-popover",
+      "aria-haspopup": "menu",
+      // Left to the browser when it alone keeps the open state.
+      "aria-expanded": onToggle ? String(isOpen) : undefined,
+      style: `anchor-name: ${anchorName(id)}`,
+    })
+  },
+
+  /**
+   * Renders the menu container and iterates items.
+   * Each item is delegated to `renderItem`. An inline menu is only rendered
+   * while open; an anchored one stays in the page as a hidden popover.
    * @param {MenuProps} props
    * @returns {TemplateResult | null}
    */
   renderMenu(props) {
     const {
       type, // eslint-disable-line no-unused-vars
+      id,
       isOpen = false,
       items = [],
       isDense = false,
       className = "",
+      trigger,
+      triggerProps, // eslint-disable-line no-unused-vars
+      onToggle,
+      onItemClick, // eslint-disable-line no-unused-vars
       ...rest
     } = props
 
-    if (!isOpen) return null
+    if (!trigger && !isOpen) return null
 
     const extraClasses = Object.fromEntries(
       className
@@ -47,13 +83,27 @@ export const Menu = {
     )
 
     return html`<div
+      id=${id || nothing}
       class=${classMap({
         "iw-menu": true,
         "iw-menu-dense": isDense,
         ...extraClasses,
       })}
       role="menu"
-      ${ref((el) => applyElementProps(el, rest))}
+      popover=${trigger ? "auto" : nothing}
+      style=${trigger ? `position-anchor: ${anchorName(id)}` : nothing}
+      ${ref((element) => {
+        if (!element) return
+        applyElementProps(element, rest)
+        // Without onToggle the browser alone opens and closes it.
+        if (trigger && onToggle) {
+          syncPopover(element, {
+            isOpen,
+            onOpen: () => onToggle(true),
+            onClose: () => onToggle(false),
+          })
+        }
+      })}
     >
       ${items.map((item, index) => this.renderItem(item, index, props))}
     </div>`
@@ -72,6 +122,7 @@ export const Menu = {
       return html`<div class="iw-menu-divider" role="separator"></div>`
     }
 
+    // In an anchored menu each item also hides the popover once picked.
     return html`<button
       type="button"
       class=${classMap({
@@ -79,6 +130,8 @@ export const Menu = {
         "iw-menu-item-selected": item.isSelected,
       })}
       role="menuitem"
+      commandfor=${props.trigger ? props.id : nothing}
+      command=${props.trigger ? "hide-popover" : nothing}
       ?disabled=${item.isDisabled}
       @click=${() => {
         item.onClick?.(item.value ?? index)

package/src/navigation/speed-dial/style.css

@@ -1,22 +1,49 @@
+/* The actions are a popover anchored to the trigger and placed on the side
+   `direction` names. The browser's popover box is centred in the viewport,
+   so its insets and box are reset; its hidden state has to be restated,
+   because the display below outranks it. */
 .iw-speed-dial {
+  anchor-scope: --iw-speed-dial;
   display: inline-flex;
-  flex-direction: column;
-  align-items: center;
-  gap: var(--iw-space-2);
+}
+
+.iw-speed-dial-trigger {
+  anchor-name: --iw-speed-dial;
 }
 
 .iw-speed-dial-actions {
+  position-anchor: --iw-speed-dial;
+  position-area: top;
+  inset: auto;
+  margin: 0 0 var(--iw-space-2);
+  padding: 0;
+  border: 0;
+  overflow: visible;
+  background: transparent;
   display: inline-flex;
   flex-direction: column;
+  align-items: center;
   gap: var(--iw-space-2);
+
+  &:not(:popover-open) {
+    display: none;
+  }
 }
 
 .iw-speed-dial-down .iw-speed-dial-actions {
-  order: 1;
+  position-area: bottom;
+  margin: var(--iw-space-2) 0 0;
+}
+
+.iw-speed-dial-left .iw-speed-dial-actions {
+  position-area: left;
+  margin: 0 var(--iw-space-2) 0 0;
+  flex-direction: row;
 }
 
-.iw-speed-dial-left .iw-speed-dial-actions,
 .iw-speed-dial-right .iw-speed-dial-actions {
+  position-area: right;
+  margin: 0 0 0 var(--iw-space-2);
   flex-direction: row;
 }
 

package/src/navigation/speed-dial/template.js

@@ -4,8 +4,11 @@
  * @typedef {import('@inglorious/web').TemplateResult} TemplateResult
  */
 
-import { html } from "@inglorious/web"
+import { html, nothing } from "@inglorious/web"
 import { classMap } from "@inglorious/web/directives/class-map"
+import { ref } from "@inglorious/web/directives/ref"
+
+import { syncPopover } from "../../shared/top-layer.js"
 
 export const SpeedDial = {
   /**
@@ -19,8 +22,10 @@ export const SpeedDial = {
   },
 
   /**
-   * Renders the speed dial container, trigger, and optional actions list.
+   * Renders the speed dial container, trigger, and actions list.
    * Actions are delegated to `renderAction`.
+   * The actions are a native popover anchored to the trigger, which toggles
+   * it as its invoker: Esc, a press outside or an action closes it.
    * @param {SpeedDialProps} props
    * @returns {TemplateResult}
    */
@@ -31,6 +36,7 @@ export const SpeedDial = {
       icon = "+",
       ariaLabel = "Speed dial",
       actions = [],
+      onToggle,
     } = props
 
     return html`<div
@@ -39,24 +45,36 @@ export const SpeedDial = {
         [`iw-speed-dial-${direction}`]: true,
         "iw-speed-dial-open": isOpen,
       })}
+      ${ref((element) => {
+        if (!element) return
+        const trigger = element.querySelector(".iw-speed-dial-trigger")
+        const popover = element.querySelector(".iw-speed-dial-actions")
+        // A property, not `commandfor`, so the link needs no id.
+        trigger.commandForElement = popover
+        // Without onToggle the browser alone opens and closes it.
+        if (onToggle) {
+          syncPopover(popover, {
+            isOpen,
+            onOpen: () => onToggle(true),
+            onClose: () => onToggle(false),
+          })
+        }
+      })}
     >
-      ${
-        isOpen
-          ? html`<div class="iw-speed-dial-actions">
-              ${actions.map((action, index) =>
-                this.renderAction(action, index, props),
-              )}
-            </div>`
-          : null
-      }
       <button
         type="button"
         class="iw-speed-dial-trigger"
         aria-label=${ariaLabel}
-        @click=${() => props.onToggle?.(!isOpen)}
+        aria-expanded=${onToggle ? String(isOpen) : nothing}
+        command="toggle-popover"
       >
         ${icon}
       </button>
+      <div class="iw-speed-dial-actions" popover="auto">
+        ${actions.map((action, index) =>
+          this.renderAction(action, index, props),
+        )}
+      </div>
     </div>`
   },
 
@@ -72,6 +90,17 @@ export const SpeedDial = {
     return html`<button
       type="button"
       class="iw-speed-dial-action"
+      command="hide-popover"
+      ${ref((element) => {
+        // Hides the popover once the action runs, like a menu item. Linked a
+        // microtask later: a new action is still outside the popover when its
+        // ref runs.
+        if (element) {
+          queueMicrotask(() => {
+            element.commandForElement = element.parentElement
+          })
+        }
+      })}
       aria-label=${action.label ?? `Speed dial action ${index + 1}`}
       ?disabled=${action.isDisabled}
       @click=${() => {

package/src/navigation/tabs/template.js

@@ -4,7 +4,7 @@
  * @typedef {import('@inglorious/web').TemplateResult} TemplateResult
  */
 
-import { html } from "@inglorious/web"
+import { html, nothing } from "@inglorious/web"
 import { classMap } from "@inglorious/web/directives/class-map"
 
 export const Tabs = {
@@ -40,6 +40,7 @@ export const Tabs = {
           "iw-tabs-full-width": isFullWidth,
         })}
         role="tablist"
+        @keydown=${moveBetweenTabs}
       >
         ${items.map((item, index) =>
           this.renderTab(item, index, { ...props, value }),
@@ -47,7 +48,7 @@ export const Tabs = {
       </div>
       ${this.renderPanel(
         items.find((item, index) => (item.value ?? index) === value) ?? null,
-        props,
+        { ...props, value },
       )}
     </div>`
   },
@@ -63,15 +64,24 @@ export const Tabs = {
   renderTab(item, index, props) {
     const tabValue = item.value ?? index
     const selected = tabValue === props.value
+    // Only one tab is in the Tab order, and the arrow keys move between them:
+    // the selected tab, or the first one while none is.
+    const hasSelection = props.items.some(
+      (other, otherIndex) => (other.value ?? otherIndex) === props.value,
+    )
+    const isTabStop = selected || (!hasSelection && index === 0)
 
     return html`<button
       type="button"
       role="tab"
+      id=${props.id ? `${props.id}-tab-${tabValue}` : nothing}
       class=${classMap({
         "iw-tab": true,
         "iw-tab-selected": selected,
       })}
       aria-selected=${selected ? "true" : "false"}
+      aria-controls=${props.id && selected ? `${props.id}-panel` : nothing}
+      tabindex=${isTabStop ? 0 : -1}
       ?disabled=${item.isDisabled}
       @click=${() => {
         item.onClick?.(tabValue)
@@ -89,8 +99,46 @@ export const Tabs = {
    * @param {TabItem | null} item
    * @returns {TemplateResult | null}
    */
-  renderPanel(item) {
+  renderPanel(item, props) {
     if (!item?.panel) return null
-    return html`<div class="iw-tab-panel" role="tabpanel">${item.panel}</div>`
+    const { id, value } = props ?? {}
+    return html`<div
+      id=${id ? `${id}-panel` : nothing}
+      class="iw-tab-panel"
+      role="tabpanel"
+      aria-labelledby=${id ? `${id}-tab-${value}` : nothing}
+    >
+      ${item.panel}
+    </div>`
   },
 }
+
+/**
+ * Arrow keys move to the previous or next tab and select it, wrapping at
+ * either end; Home and End jump to the first and last. Left and right swap in
+ * a right-to-left page, where the tabs run the other way.
+ * @param {KeyboardEvent} event
+ */
+function moveBetweenTabs(event) {
+  const tabs = [
+    ...event.currentTarget.querySelectorAll('[role="tab"]:not(:disabled)'),
+  ]
+  const current = tabs.indexOf(event.target)
+  if (current === -1) return
+
+  const isRtl = getComputedStyle(event.currentTarget).direction === "rtl"
+  const forward = isRtl ? "ArrowLeft" : "ArrowRight"
+  const backward = isRtl ? "ArrowRight" : "ArrowLeft"
+
+  let next
+  if (event.key === forward) next = (current + 1) % tabs.length
+  else if (event.key === backward)
+    next = (current - 1 + tabs.length) % tabs.length
+  else if (event.key === "Home") next = 0
+  else if (event.key === "End") next = tabs.length - 1
+  else return
+
+  event.preventDefault()
+  tabs[next].focus()
+  tabs[next].click()
+}

package/src/shared/anchor.js

@@ -0,0 +1,11 @@
+/**
+ * The CSS anchor name that ties a popover to the element it opens from.
+ * Set as `anchor-name` on the trigger and `position-anchor` on the popover,
+ * so the browser positions the popover against it, flipping when it runs out
+ * of room. Built from the popover's id, which is unique on the page.
+ * @param {string} id
+ * @returns {string}
+ */
+export function anchorName(id) {
+  return `--iw-anchor-${String(id).replace(/[^\w-]/g, "-")}`
+}

package/src/shared/top-layer.js

@@ -0,0 +1,83 @@
+/**
+ * Native `<dialog>` and `popover` elements keep their own open state, while the
+ * components that use them are driven by an `isOpen` prop from the store. These
+ * helpers run from a `ref` on every render and keep the two in step: the prop
+ * opens and closes the element, and a change the browser makes on its own
+ * (Esc, a light dismiss, a `method="dialog"` form, a `commandfor` invoker) is
+ * reported through `onClose` or `onOpen` so the store can catch up.
+ *
+ * The browser fires `close` and `toggle` after the fact, so the handler tells
+ * the two apart by the latest props: a change the props asked for finds
+ * `isOpen` already matching, and only one they did not ask for is reported.
+ */
+
+/**
+ * Latest props per element. The listener is added once, and reads the props
+ * from here so it never calls an `onClose` captured by an earlier render.
+ * @type {WeakMap<Element, { isOpen: boolean, isModal?: boolean, onOpen?: () => void, onClose?: () => void }>}
+ */
+const latestProps = new WeakMap()
+
+/**
+ * Opens or closes a `<dialog>` to match `isOpen`.
+ * @param {HTMLDialogElement | undefined} element
+ * @param {{ isOpen: boolean, isModal?: boolean, onClose?: () => void }} props
+ */
+export function syncDialog(element, props) {
+  if (!element) return
+  track(element, props, "close", () => false)
+  whenConnected(element, () => {
+    const { isOpen, isModal = true } = latestProps.get(element)
+    if (isOpen && !element.open) {
+      if (isModal) element.showModal()
+      else element.show()
+    }
+    if (!isOpen && element.open) element.close()
+  })
+}
+
+/**
+ * Shows or hides a `popover` element to match `isOpen`. Showing an open
+ * popover and hiding a closed one are no-ops, so no state check is needed.
+ * @param {HTMLElement | undefined} element
+ * @param {{ isOpen: boolean, onOpen?: () => void, onClose?: () => void }} props
+ */
+export function syncPopover(element, props) {
+  if (!element) return
+  track(element, props, "toggle", (event) => event.newState === "open")
+  whenConnected(element, () => {
+    if (!element.popover) return
+    if (latestProps.get(element).isOpen) element.showPopover()
+    else element.hidePopover()
+  })
+}
+
+/**
+ * @param {Element} element
+ * @param {object} props
+ * @param {string} eventName
+ * @param {(event: Event) => boolean} isOpenAfter whether the event left it open
+ */
+function track(element, props, eventName, isOpenAfter) {
+  const isTracked = latestProps.has(element)
+  latestProps.set(element, props)
+  if (isTracked) return
+
+  element.addEventListener(eventName, (event) => {
+    const latest = latestProps.get(element)
+    const isOpen = isOpenAfter(event)
+    if (isOpen === latest.isOpen) return
+    if (isOpen) latest.onOpen?.()
+    else latest.onClose?.()
+  })
+}
+
+/**
+ * A ref runs while a new template is still in its fragment, and neither
+ * `showModal()` nor `showPopover()` works on an element outside the document.
+ * The fragment is inserted synchronously after, so a microtask is late enough.
+ */
+function whenConnected(element, callback) {
+  if (element.isConnected) callback()
+  else queueMicrotask(() => element.isConnected && callback())
+}

package/src/surfaces/accordion/style.css

@@ -11,20 +11,27 @@
   border-top: 1px solid var(--iw-color-border);
 }
 
+/* A <summary>: flex drops the browser's disclosure marker, and the caret
+   stands in for it. */
 .iw-accordion-trigger {
-  width: 100%;
-  border: 0 none;
-  background: transparent;
-  color: inherit;
   padding: var(--iw-space-3) var(--iw-space-4);
   display: flex;
   align-items: center;
   gap: var(--iw-space-2);
-  text-align: left;
+  text-align: start;
   cursor: pointer;
+
+  &::-webkit-details-marker {
+    display: none;
+  }
+}
+
+.iw-accordion-item-disabled .iw-accordion-trigger {
+  cursor: default;
 }
 
-.iw-accordion-trigger:hover:enabled {
+.iw-accordion-item:not(.iw-accordion-item-disabled)
+  .iw-accordion-trigger:hover {
   background: color-mix(
     in srgb,
     var(--iw-color-surface-hover) 75%,
@@ -50,7 +57,7 @@
   color: var(--iw-color-text-muted, var(--iw-color-text));
 }
 
-.iw-accordion-item-expanded .iw-accordion-caret {
+.iw-accordion-item[open] .iw-accordion-caret {
   transform: rotate(180deg);
 }
 

package/src/surfaces/accordion/template.js

@@ -4,7 +4,7 @@
  * @typedef {import('@inglorious/web').TemplateResult} TemplateResult
  */
 
-import { html } from "@inglorious/web"
+import { html, nothing } from "@inglorious/web"
 import { classMap } from "@inglorious/web/directives/class-map"
 import { ref } from "@inglorious/web/directives/ref"
 
@@ -30,8 +30,10 @@ export const Accordion = {
   renderAccordion(props) {
     const {
       type, // eslint-disable-line no-unused-vars
+      name, // eslint-disable-line no-unused-vars
       items = [],
       className = "",
+      onItemToggle, // eslint-disable-line no-unused-vars
       ...rest
     } = props
 
@@ -54,8 +56,11 @@ export const Accordion = {
   },
 
   /**
-   * Renders a single accordion item with trigger and panel content.
-   * Handles expand/collapse behavior and item-level callbacks.
+   * Renders a single accordion item as a native `<details>`, whose `<summary>`
+   * is the trigger. The browser opens and closes it, keeps the panel's
+   * content findable (find-in-page opens the item that holds a match), and,
+   * when the accordion has a `name`, closes the other items as one opens.
+   * Each change is reported so the store can follow.
    * @param {AccordionItem} item
    * @param {number} index
    * @param {AccordionProps} props
@@ -71,33 +76,35 @@ export const Accordion = {
       icon,
     } = item
 
-    return html`<section
+    return html`<details
       class=${classMap({
         "iw-accordion-item": true,
         "iw-accordion-item-expanded": isExpanded,
         "iw-accordion-item-disabled": isDisabled,
       })}
+      name=${props.name || nothing}
+      .open=${isExpanded}
+      @toggle=${(event) => {
+        const isOpen = event.newState === "open"
+        // Also fires when isExpanded opened it, which needs no report.
+        if (isOpen === isExpanded) return
+        onToggle?.(item, index, isOpen)
+        props.onItemToggle?.(item, index, isOpen)
+      }}
     >
-      <button
+      <summary
         class="iw-accordion-trigger"
-        type="button"
-        aria-expanded=${isExpanded}
-        ?disabled=${isDisabled}
-        @click=${() => {
-          if (isDisabled) return
-          onToggle?.(item, index, !isExpanded)
-          props.onItemToggle?.(item, index, !isExpanded)
+        aria-disabled=${isDisabled ? "true" : nothing}
+        @click=${(event) => {
+          // A summary cannot be disabled, so its toggle is refused instead.
+          if (isDisabled) event.preventDefault()
         }}
       >
         ${icon ? html`<span class="iw-accordion-icon">${icon}</span>` : null}
         <span class="iw-accordion-title">${title}</span>
-        <span class="iw-accordion-caret">▾</span>
-      </button>
-      ${
-        isExpanded
-          ? html`<div class="iw-accordion-panel">${content}</div>`
-          : null
-      }
-    </section>`
+        <span class="iw-accordion-caret" aria-hidden="true">▾</span>
+      </summary>
+      <div class="iw-accordion-panel">${content}</div>
+    </details>`
   },
 }

package/types/controls/rating.d.ts

@@ -2,6 +2,8 @@ import type { TemplateResult } from "@inglorious/web"
 
 export interface RatingProps {
   id?: string
+  /** Groups the radios and names the value in a form. Falls back to `id`. */
+  name?: string
   value?: number
   max?: number
   isDisabled?: boolean
@@ -10,6 +12,8 @@ export interface RatingProps {
   emptySymbol?: string
   onChange?: (value: number) => void
   size?: "sm" | "md" | "lg"
+  /** Names the group for assistive tech. Defaults to "Rating". */
+  ariaLabel?: string
 }
 
 export type RatingType = {

package/types/feedback/dialog.d.ts

@@ -4,6 +4,8 @@ export interface DialogProps {
   id?: string
   type?: string
   isOpen?: boolean
+  /** Modal by default; `false` shows the dialog in place, with the page still usable. */
+  isModal?: boolean
   title?: TemplateResult | string | number
   description?: TemplateResult | string | number
   children?: TemplateResult | string | number
@@ -15,7 +17,7 @@ export interface DialogProps {
 }
 
 export type DialogType = {
-  render(props: DialogProps): TemplateResult | null
+  render(props: DialogProps): TemplateResult
 }
 
 export declare const Dialog: DialogType

package/types/feedback/progress.d.ts

@@ -15,6 +15,8 @@ export interface ProgressProps {
     | "info"
   size?: number
   thickness?: number
+  /** Names the indicator for assistive tech, e.g. "Uploading photo". */
+  ariaLabel?: string
   className?: string
   [key: string]: unknown
 }

package/types/navigation/drawer.d.ts

@@ -5,19 +5,24 @@ export interface DrawerProps {
   type?: string
   isOpen?: boolean
   anchor?: "left" | "right" | "top" | "bottom"
-  variant?: "temporary" | "persistent" | "permanent" | "responsive"
-  breakpoint?: "sm" | "md" | "lg" | "xl"
+  /**
+   * When the drawer overlays the page as a popover: `responsive` (default)
+   * below 64rem and docked above, `temporary` at every width, `permanent` never.
+   */
+  variant?: "responsive" | "temporary" | "permanent"
+  isHidden?: boolean
   isCollapsed?: boolean
   title?: TemplateResult | string | number
   children?: TemplateResult | string | number
   hasBackdrop?: boolean
   className?: string
   onClose?: () => void
+  onCollapseToggle?: () => void
   [key: string]: unknown
 }
 
 export type DrawerType = {
-  render(props: DrawerProps): TemplateResult | null
+  render(props: DrawerProps): TemplateResult
 }
 
 export declare const Drawer: DrawerType