@inglorious/ui 8.5.0 → 9.0.0

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/button.d.ts

@@ -22,7 +22,13 @@ export interface ButtonProps {
   ariaLabel?: string
   isAriaPressed?: boolean
   className?: string
-  onClick?: () => void
+  /** File types the picker offers, as in the native `accept` attribute */
+  accept?: string
+  /** Lets the picker select more than one file */
+  isMultiple?: boolean
+  onClick?: (event: MouseEvent) => void
+  /** Turns the button into a file picker; called with the chosen files */
+  onFileSelect?: (files: FileList) => void
   [key: string]: unknown
 }
 

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

package/types/navigation/menu.d.ts

@@ -1,5 +1,7 @@
 import type { TemplateResult } from "@inglorious/web"
 
+import type { ButtonProps } from "../controls/button"
+
 export interface MenuItem {
   id?: string | number
   value?: string | number
@@ -14,9 +16,23 @@ export interface MenuItem {
 }
 
 export interface MenuProps {
+  /** Required with `trigger`: it links the button to the menu. */
   id?: string
   type?: string
   isOpen?: boolean
+  /**
+   * Content of a button that opens the menu. With it, the menu is a popover
+   * anchored to the button; without it, the menu renders in place while open.
+   */
+  trigger?: TemplateResult | string | number
+  /** Extra props for the trigger button, such as `variant` or `ariaLabel`. */
+  triggerProps?: ButtonProps
+  /**
+   * Called with the new state when the browser opens or closes an anchored
+   * menu. Without it, the browser alone keeps the open state and `isOpen` is
+   * not applied.
+   */
+  onToggle?: (isOpen: boolean) => void
   items?: MenuItem[]
   isDense?: boolean
   className?: string
@@ -26,6 +42,7 @@ export interface MenuProps {
 
 export type MenuType = {
   render(props: MenuProps): TemplateResult | null
+  renderTrigger(props: MenuProps): TemplateResult
   renderMenu(props: MenuProps): TemplateResult | null
   renderItem(item: MenuItem, index: number, props: MenuProps): TemplateResult
 }

package/types/navigation/speed-dial.d.ts

@@ -18,6 +18,11 @@ export interface SpeedDialProps {
   ariaLabel?: string
   direction?: "up" | "down" | "left" | "right"
   actions?: SpeedDialAction[]
+  /**
+   * Called with the new state when the browser opens or closes the actions.
+   * Without it, the browser alone keeps the open state and `isOpen` is not
+   * applied.
+   */
   onToggle?: (isOpen: boolean) => void
   onAction?: (value: string | number, action: SpeedDialAction) => void
   [key: string]: unknown

package/types/surfaces/accordion.d.ts

@@ -15,6 +15,8 @@ export interface AccordionProps {
   id?: string
   type?: string
   className?: string
+  /** Items sharing a name close each other: at most one is open at a time. */
+  name?: string
   items?: AccordionItem[]
   onItemToggle?: (item: AccordionItem, index: number, expanded: boolean) => void
   [key: string]: unknown