// src/elements/icon-button.ts /** * ``: the icon button as a custom element. It has no text, so * `aria-label` is its accessible name. * * With `toggle`, the `selected` attribute is the default state and the * `selected` property the live one: the attribute moves the state until the * user or script changes it. A click dispatches `change` with `{ selected, value }` * from the host, as `` and `` do. The `toggle` event * 0.10 dispatched beside it, which clashed with the native ToggleEvent, is * gone in material 3.0.0. * `type="submit"` and `type="reset"` act on the host's form. * * Parts: `icon-button`, `icon`, `ripple`. * * The host carries `data-mtrl-icon-button` whenever it is connected: its * prefix-independent marker, which another element's `::slotted()` rules can * match where they cannot spell the tag (`ElementSpec.marker`). * * @module elements */ import createIconButton from "../components/icon-button"; import type { IconButtonChangePayload, IconButtonComponent, IconButtonConfig } from "../components/icon-button/types"; import { defineElement, type DefineOptions, type ElementInstance, type ElementSpec } from "./define"; import { buttonForm, submitOnClick, typeAttribute } from "./form-button"; const iconButtonSpec = { name: "icon-button", // No aria-label given is an empty one: the factory then sets none. create: (config) => createIconButton({ ariaLabel: "", ...(config as Partial), type: "button" }), styles: ["icon-button"], // The zero-width first item stretches to the control's height, so the // host's baseline is its bottom edge, as the pre-upgrade box's is. hostStyles: ":host{display:inline-flex;vertical-align:middle}:host::before{content:'';align-self:stretch;width:0}", // The toolbar's sheet pins a directly slotted host's morph targets through // `::slotted([data-mtrl-icon-button])`: the tag is the page's choice of // prefix, the marker is this library's, and the size selectors beside it // stay live for a size changed after insertion. marker: "data-mtrl-icon-button", attributes: { variant: { type: "string", config: "variant", update: (c, v) => void c.setVariant(String(v ?? "standard")) }, size: { type: "string", config: "size", update: (c, v) => void c.setSize(String(v ?? "s")) }, shape: { type: "string", config: "shape", update: (c, v) => void c.setShape(String(v ?? "round")) }, width: { type: "string", config: "width", update: (c, v) => void c.setWidth(String(v ?? "default")) }, disabled: { type: "boolean", config: "disabled", update: (c, v) => void (v ? c.disable() : c.enable()) }, /** Markup (HTML). Not sanitized by default: see Markup and sanitizing. */ icon: { type: "string", config: "icon", update: (c, v) => void c.setIcon(String(v ?? "")) }, /** Markup (HTML), shown while `toggle` and `selected`. Not sanitized by default: see Markup and sanitizing. */ "selected-icon": { type: "string", config: "selectedIcon", update: (c, v) => void c.setSelectedIcon(String(v ?? "")), }, toggle: { type: "boolean", config: "toggle" }, selected: { type: "boolean", config: "selected", update: (c, v) => void (v ? c.select() : c.deselect()) }, value: { type: "string", config: "value", update: (c, v) => void c.setValue(String(v ?? "")) }, type: typeAttribute, "aria-label": { type: "string", config: "ariaLabel", update: (c, v) => void c.setAriaLabel(String(v ?? "")) }, }, properties: { selected: { get: (c) => c.isSelected(), set: (c, v) => void (v ? c.select() : c.deselect()), config: "selected", }, }, methods: ["select", "deselect", "toggleSelected"] as const, model: "selected" as const, events: { // The factory's emitter `change`. change: { detail: (payload) => { const { selected, value } = payload as IconButtonChangePayload; return { selected, value }; }, }, }, form: buttonForm(), setup: submitOnClick, } satisfies ElementSpec; export const iconButtonElement = defineElement(iconButtonSpec); export type IconButtonSpec = typeof iconButtonSpec; /** `` as a ref or a query returns it. */ export type IconButtonElement = ElementInstance; /** Registers `` (or ``). */ export const defineIconButton = (options?: DefineOptions): string => iconButtonElement.define(options); declare global { /** `document.querySelector("m-…")` and `createElement` return the element's type (the default prefix). */ interface HTMLElementTagNameMap { "m-icon-button": IconButtonElement; } }