@inglorious/ui 8.6.0 → 9.1.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/accordion.stories.js

@@ -12,6 +12,11 @@ export default {
       control: "object",
       description: "Accordion sections with title, content, and state flags.",
     },
+    name: {
+      control: "text",
+      description:
+        "Items sharing a name close each other: at most one is open at a time.",
+    },
     onItemToggle: { action: "onItemToggle" },
   },
   parameters: {
@@ -44,6 +49,10 @@ export const Default = {
   },
 }
 
+export const Exclusive = {
+  args: { ...Default.args, name: "settings" },
+}
+
 export const WithIcons = {
   args: {
     items: [

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,39 @@ 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) => {
+        // newState is what the browser says; an environment whose toggle
+        // event lacks it, such as jsdom, still has the element's own state.
+        const isOpen = event.newState
+          ? event.newState === "open"
+          : event.currentTarget.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/src/surfaces/card/card.stories.js

@@ -53,6 +53,12 @@ export default {
       options: ["none", "sm", "md", "lg", "xl"],
       description: "Footer padding preset.",
     },
+    variant: {
+      control: "select",
+      options: ["default", "sunk", "clear"],
+      description:
+        "The surface: raised, sunk into the page for content inside another surface, or clear.",
+    },
     isHoverable: {
       control: "boolean",
       description: "Enable hover visual feedback.",
@@ -97,6 +103,24 @@ export const WithFooter = {
   },
 }
 
+export const Sunk = {
+  args: {
+    title: "Sunk card",
+    subtitle: "Content inside another surface",
+    children: "Body content",
+    variant: "sunk",
+  },
+}
+
+export const Clear = {
+  args: {
+    title: "Clear card",
+    subtitle: "Groups content with no surface of its own",
+    children: "Body content",
+    variant: "clear",
+  },
+}
+
 export const Interactive = {
   args: {
     title: "Interactive Card",

package/src/surfaces/card/style.css

@@ -11,6 +11,21 @@
     transform var(--iw-transition-normal);
 }
 
+/* Set into the page rather than raised from it, for content grouped inside
+   another surface. */
+.iw-card-sunk {
+  background-color: var(--iw-color-bg-secondary, var(--iw-card-bg));
+  border-color: transparent;
+  box-shadow: none;
+}
+
+/* Only the grouping: no surface at all. */
+.iw-card-clear {
+  background-color: transparent;
+  border-color: transparent;
+  box-shadow: none;
+}
+
 .iw-card-hoverable:hover {
   box-shadow: var(--iw-card-shadow-hover);
 }

package/src/surfaces/card/template.js

@@ -30,6 +30,7 @@ export const Card = {
     const {
       type, // eslint-disable-line no-unused-vars
       element = "article",
+      variant = "default",
       isHoverable = false,
       isClickable = false,
       isFullWidth = false,
@@ -47,6 +48,7 @@ export const Card = {
 
     const classes = {
       "iw-card": true,
+      [`iw-card-${variant}`]: variant !== "default",
       "iw-card-hoverable": isHoverable || isClickable,
       "iw-card-clickable": isClickable,
       "iw-card-full-width": isFullWidth,

package/types/controls/button.d.ts

@@ -13,7 +13,7 @@ export interface ButtonProps {
     | "warning"
     | "error"
     | "info"
-  size?: "sm" | "md" | "lg"
+  size?: "xs" | "sm" | "md" | "lg"
   shape?: "rectangle" | "pill" | "round" | "square"
   isDisabled?: boolean
   isPressed?: boolean

package/types/controls/checkbox.d.ts

@@ -4,6 +4,8 @@ export interface CheckboxProps {
   id?: string
   name?: string
   label?: string
+  /** A line of detail under the label. */
+  description?: string
   isChecked?: boolean
   isDisabled?: boolean
   isRequired?: boolean

package/types/controls/radio-group.d.ts

@@ -2,6 +2,8 @@ import type { TemplateResult } from "@inglorious/web"
 
 export interface RadioOption {
   label: string
+  /** A line of detail under the label. */
+  description?: string
   value: string
   isDisabled?: boolean
   [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/controls/slider.d.ts

@@ -4,7 +4,8 @@ export interface SliderProps {
   id?: string
   name?: string
   label?: string
-  value?: number
+  /** One number, or `[low, high]` for a range with a thumb at each end. */
+  value?: number | [number, number]
   min?: number
   max?: number
   step?: number
@@ -12,7 +13,10 @@ export interface SliderProps {
   isDisabled?: boolean
   isValueVisible?: boolean
   isFullWidth?: boolean
-  onChange?: (value: number) => void
+  /** Draws a tick at every step, for a slider that moves in clear steps. */
+  hasMarks?: boolean
+  /** The new value, in the shape `value` has: a number, or `[low, high]`. */
+  onChange?: (value: number | [number, number]) => void
   [key: string]: unknown
 }
 

package/types/controls/switch.d.ts

@@ -4,6 +4,8 @@ export interface SwitchProps {
   id?: string
   name?: string
   label?: string
+  /** A line of detail under the label. */
+  description?: string
   isChecked?: boolean
   isDisabled?: boolean
   color?: "primary" | "secondary" | "success" | "warning" | "error" | "info"

package/types/data-display/chip.d.ts

@@ -3,6 +3,8 @@ import type { TemplateResult } from "@inglorious/web"
 export interface ChipProps {
   id?: string
   children?: TemplateResult | string | number
+  /** Shown before the label, such as an `Icon.render(...)`. Decorative. */
+  icon?: TemplateResult
   isRemovable?: boolean
   color?:
     | "default"

package/types/data-display/divider.d.ts

@@ -4,6 +4,8 @@ export interface DividerProps {
   id?: string
   orientation?: "horizontal" | "vertical"
   isInset?: boolean
+  /** Only visual: hidden from assistive tech, which otherwise announces a separator. */
+  isDecorative?: boolean
   [key: string]: unknown
 }
 

package/types/feedback/alert.d.ts

@@ -6,7 +6,7 @@ export interface AlertProps {
   title?: TemplateResult | string | number
   description?: TemplateResult | string | number
   children?: TemplateResult | string | number
-  severity?: "info" | "success" | "warning" | "error"
+  severity?: "info" | "success" | "warning" | "error" | "neutral"
   variant?: "filled" | "outlined"
   icon?: TemplateResult | string | number
   action?: TemplateResult | string | number

package/types/feedback/dialog.d.ts

@@ -4,6 +4,10 @@ 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
+  /** Its width: `"sm"`, `"md"` (default) or `"lg"`. */
+  size?: "sm" | "md" | "lg"
   title?: TemplateResult | string | number
   description?: TemplateResult | string | number
   children?: TemplateResult | string | number
@@ -15,7 +19,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/layout/flex.d.ts

@@ -16,7 +16,7 @@ export interface FlexProps {
   wrap?: "nowrap" | "wrap" | "wrap-reverse"
   justify?: "start" | "center" | "end" | "between" | "around" | "evenly"
   align?: "stretch" | "start" | "center" | "end" | "baseline"
-  gap?: "none" | "sm" | "md" | "lg" | "xl"
+  gap?: "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl"
   padding?: "none" | "sm" | "md" | "lg" | "xl"
   overflow?: "visible" | "hidden" | "clip" | "scroll" | "auto"
   isInline?: boolean

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

package/types/surfaces/card.d.ts

@@ -12,6 +12,11 @@ export interface CardProps {
     | "footer"
     | "nav"
     | "aside"
+  /**
+   * The surface: raised (`"default"`), `"sunk"` into the page for content
+   * inside another surface, or `"clear"` with none.
+   */
+  variant?: "default" | "sunk" | "clear"
   title?: TemplateResult | string | number
   subtitle?: TemplateResult | string | number
   header?: TemplateResult | string | number