@eifi1/ui-kit 0.33.0 → 0.34.0

package/dist/components/icon-button.d.ts

@@ -0,0 +1,300 @@
+import type { AnchorHTMLAttributes, ButtonHTMLAttributes, ReactElement, ReactNode, Ref } from "react";
+import { type TooltipSide } from "./tooltip.js";
+import type { KitLinkComponent } from "../i18n/kit-labels.js";
+import type { CommitScope } from "./write-lock.js";
+import { type DisabledReasonDisplay } from "./field-parts.js";
+import type { ButtonVariant } from "./button-look.js";
+export type IconButtonSize = "2xl" | "xl" | "lg" | "md" | "sm" | "xs" | "2xs";
+export type IconButtonTone = "default" | "muted" | "danger" | "warning" | "info" | "success" | "custom";
+export type IconButtonVariant = ButtonVariant | "overlay" | "shutter";
+/**
+ * The glyph's size in px, over the one the box size implies — see
+ * {@link IconButtonProps.glyphSize}.
+ */
+export type IconButtonGlyphSize = 12 | 14 | 16 | 20 | 24 | 28;
+export interface IconButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+    /** Any {@link ButtonVariant}; `overlay` — a round translucent disc for use over
+     *  an image (see `ICON_BUTTON_OVERLAY`); or `shutter` — a camera's release, a ringed
+     *  disc over the viewfinder (see `ICON_BUTTON_SHUTTER`; pair it with `size="2xl"`). */
+    variant?: IconButtonVariant;
+    /** Box size: 2xl = 64px with a 28px icon (a camera shutter), xl = 48px with a 24px
+     *  icon, lg = 44px (a phone's touch target), md = 36px (matches the top bar),
+     *  sm = 32px — all three with a 20px icon;
+     *  xs = 28px with a 16px icon (an action in a list row), 2xs = 24px with a 14px
+     *  icon (an action on a chip or a tab). `glyphSize` overrides the icon. */
+    size?: IconButtonSize;
+    /**
+     * The icon's size in px, when the box's own is not the one wanted. keksdose's sync
+     * chip (app/sync-status-indicator.tsx:142) is a 24px round chip round a 20px cloud —
+     * `size="2xs" glyphSize={20} shape="round"` — where `2xs` alone draws 14px. A number
+     * over a new size step because the box and the glyph are two independent choices; a
+     * step per combination (`"sm-lg"`) would have to be named for every one.
+     */
+    glyphSize?: IconButtonGlyphSize;
+    /**
+     * A small mark on the button's corner — the sync chip's 12px check over its cloud
+     * ("all good", feedback #67). Rendered OUTSIDE the `<button>`, in a wrapper beside
+     * it, so the box's `[&_svg]:size-*` rule that sizes the glyph does not blow the badge
+     * up to the glyph's size; a bare `<Check />` comes out 12px, on a
+     * `--bg-surface` disc that keeps it legible over the glyph. Decorative
+     * (`aria-hidden`): the name (`label` / `aria-label`) must already carry the state.
+     * With a badge, `className` still lands on the button; the wrapper is the flex item.
+     */
+    badge?: ReactNode;
+    /**
+     * `keep`: a disabled button keeps its full colour (no 50% drop) and an ordinary
+     * cursor. For a STATUS that is also an action — the sync chip shows "in sync" in
+     * green and refreshes on click, and is disabled while offline or syncing, when the
+     * state it shows matters most; dimmed it read as broken (keksdose wrote
+     * `disabled:cursor-default` by hand and left out the dimming). Default `dim`.
+     */
+    disabledStyle?: "dim" | "keep";
+    /**
+     * Fill the height of the flex row it stands in, keeping its width — the delete at
+     * the end of keksdose's split line (transaction-fields:162), level with the labelled
+     * fields beside it rather than floating at half their height. {@link Button}'s
+     * `stretch`; no effect outside a flex row. With a `label`, the tooltip's wrapper is
+     * what stretches.
+     */
+    stretch?: boolean;
+    /** `round`: a circle instead of the rounded square — a compact status chip in a top
+     *  bar (keksdose's sync indicator). `overlay` is always round. */
+    shape?: "square" | "round";
+    /**
+     * The colour of `tone="custom"`, as any CSS colour — a token (`var(--warning)`),
+     * ideally. Sets `--icon-button-tone` on the button, so passing a different one per
+     * state re-colours the glyph, its hover fill and its focus ring together. Passing it
+     * implies `tone="custom"`. Or leave it out and set the variable yourself from a class
+     * (`className="[--icon-button-tone:var(--success)]"`).
+     *
+     * Or a `{ light, dark }` pair, one colour per theme — keksdose: a raw colour that reads
+     * on the light surface (`#be123c`) is too dark on the dark one, and an inline style
+     * cannot say "in dark mode". See {@link IconButtonToneColor}.
+     */
+    toneColor?: IconButtonToneColor;
+    /** Glyph colour over the variant. `muted`: placeholder grey, full text colour on
+     *  hover. `danger`: the same grey at rest, `--danger` on hover and focus — for a
+     *  remove/delete that repeats down a list. `warning`: amber at rest — a flag that
+     *  wants attention. `info`: sky at rest — a notice-worthy but harmless action
+     *  (keksdose's reconcile). `success`: green at rest — a good state worth seeing.
+     *  `custom`: the colour of `toneColor` (see there). Default: the variant's own colours. See `quiet` for
+     *  turning a coloured tone's resting look the other way. */
+    tone?: IconButtonTone;
+    /**
+     * Whether a coloured tone (`danger`, `warning`, `info`) waits for the pointer:
+     * `true` is placeholder grey at rest and the tone's colour on hover and focus;
+     * `false` wears the tone's colour at rest. Left out, each tone keeps its own
+     * default — `danger` quiet, `warning` and `info` not. Ignored for `muted` (quiet by
+     * definition) and `default` (no tone).
+     *
+     * `quiet={false}` on `danger` is for a destructive action that stands ALONE, where
+     * hover-to-reveal hides it: keksdose's phone bulk bar (mobile-bulk-bar.tsx) has one
+     * "delete all" and a touch screen that never hovers, so it painted rose by hand.
+     * `quiet` on `warning`/`info` is the same switch the other way, for a flag repeated
+     * down a list. A boolean over the tone rather than a new tone (`danger-solid`) or an
+     * `emphasis` scale: there are exactly two resting looks, every coloured tone has
+     * both, and which one fits is a question about the SITE (alone or repeated, touch or
+     * pointer), not about the tone — so it is one switch the family shares.
+     */
+    quiet?: boolean;
+    /**
+     * Make it a toggle button. `true` sets `aria-pressed="true"` and draws the "on" look
+     * (brand glyph on the quiet brand fill); `false` sets `aria-pressed="false"` with the
+     * normal look, so a screen reader still hears a toggle that is off. Left out, it is
+     * an ordinary button with no `aria-pressed` — or whatever `aria-pressed` the caller
+     * passes. For keksdose's budget share toggle (budgets-page:291), which paints its own
+     * brand colour over a ghost button today. Keep the `aria-label` the same in both
+     * states ("Share budget"): the pressed state already says whether it is on.
+     */
+    pressed?: boolean;
+    /** Keep the click (and the Enter/Space that produces it) from reaching an
+     *  ancestor's handler — for an action inside a clickable table row or card.
+     *
+     *  **Not a licence to put this inside another `<button>`.** HTML forbids any
+     *  interactive content, and any element with a `tabindex`, inside a button — so
+     *  the `<span role="button" tabIndex={0}>` workaround is invalid too — and ARIA
+     *  makes a button's children presentational, so a screen reader flattens the
+     *  inner one into the outer one's name and it cannot be reached at all. Make the
+     *  row's main action a button that fills the row and put this one BESIDE it, on
+     *  top:
+     *
+     *  ```tsx
+     *  <div className="relative">
+     *    <button className="w-full pe-16 …" onClick={open}>…row…</button>
+     *    <div className="absolute inset-y-0 end-2 flex items-center gap-0.5">
+     *      <IconButton size="xs" tone="danger" aria-label="Delete" onClick={remove}>
+     *        <Trash2 />
+     *      </IconButton>
+     *    </div>
+     *  </div>
+     *  ```
+     *
+     *  The pair look exactly like the nested version, click exactly like it, and
+     *  are two tab stops a screen reader can tell apart. */
+    stopPropagation?: boolean;
+    /**
+     * The button's name, said once: it becomes the `aria-label` AND the text of a kit
+     * {@link Tooltip} round the button.
+     *
+     * Every app writes the pair by hand. lenkbank's nine icon actions all carry
+     * `aria-label={t(x)} title={t(x)}` (shared/lib/table-columns.tsx:103,
+     * projects-page.tsx:83, setpoint/segment-list.tsx:198/207, profile-bar.tsx:128/142,
+     * shortcut-dialog.tsx:815/857/1007) — and `title` is the browser's own tooltip,
+     * which shows late, never on focus and never on touch, and looks like no other
+     * label in the kit. kastlan's RowAction (shared/components/data-table/row-action.tsx)
+     * and keksdose's icon wrappers each exist to put a Tooltip round an IconButton.
+     *
+     * A caller's own `aria-label` still wins, for the rare name that should be longer
+     * than the bubble. The bubble is visual only: it would otherwise describe the button
+     * with its own name, and a screen reader would read the same word twice. Tooltip's
+     * default placement applies — in place, or portalled inside a scroll container —
+     * unless `tooltipPortal` says otherwise.
+     */
+    label?: string;
+    /**
+     * Show `label` as visible text beside the icon at Large and Extra large (0.32,
+     * docs/text-size-harmonization.md §4, §10.8). A reader who asked for bigger type is
+     * the one an unlabelled glyph fails, and on touch the tooltip never opens. Then there
+     * is no tooltip: the words are on the button.
+     *
+     * Default `true` — except for `variant="overlay"` and `"shutter"`, which sit ON a
+     * picture, and inside {@link CompactControls} (AppShell's top bar, `RowActions`'
+     * inline icons). `false`: the icon alone at every size, for an icon on content — a
+     * receipt overlay, a map's zoom, a viewfinder, a photo thumbnail. That must be rare;
+     * a dense row's actions belong in `RowActions`, which collapses them into a "⋯" menu
+     * at Large instead (§10.8). Normal never shows it. `tooltip={false}` (a universally
+     * read glyph, a dialog's ✕) keeps the icon alone too.
+     */
+    labelVisible?: boolean;
+    /** Show `label` as a tooltip. Default `true`; `false` keeps `label` as the
+     *  accessible name only — for a button whose glyph is universally read (a close ✕ in
+     *  a dialog header) or that already sits under a tooltip of its own. It also keeps the
+     *  label from showing as text at Large (see `labelVisible`). */
+    tooltip?: boolean;
+    /** Where the `label` tooltip opens. See {@link Tooltip}'s `side`. */
+    tooltipSide?: TooltipSide;
+    /** Passed to the `label` tooltip's `portal`. Left out, Tooltip decides (see there). */
+    tooltipPortal?: boolean;
+    /**
+     * Mount the `label` bubble only while it is up — {@link Tooltip}'s `lazy`. Default
+     * `true` since 0.16.0; `false` is the always-mounted in-place bubble of before.
+     *
+     * Why the label bubble can be lazy when Tooltip's default is not: this bubble
+     * describes nothing. It is wrapped round the button in a fragment precisely so that
+     * it is NOT the button's `aria-describedby` (it would repeat the button's own name),
+     * so there is no description for a lazy mount to take away — the name is the
+     * `aria-label` either way, read in browse mode and on focus alike. What the
+     * always-mounted bubble did do was sit in the DOM as a `role="tooltip"` node full of
+     * text: every IconButton in a row added one to `getAllByRole("tooltip")` and its label
+     * to the row's `textContent`, and two keksdose tests tripped over that (0.15.5 P6).
+     * The cost is the one {@link Tooltip}'s "Lazy in place" note names — a test that
+     * looked the bubble up without hovering now has to hover (or focus) first; pass
+     * `false` while it is migrated. A `disabledReason` bubble is unaffected: that one
+     * stays mounted as it was.
+     */
+    tooltipLazy?: boolean;
+    /**
+     * Busy — the action is in flight: the glyph is swapped for a spinner of the same
+     * size, the button is `aria-busy`, and clicks (and the Enter/Space and form
+     * submission they stand for) are swallowed, so a second press cannot start the
+     * action twice. {@link Button}'s `pending`, with the same contract: `aria-disabled`
+     * rather than `disabled`, so the button that was pressed keeps its focus. The name
+     * (`label` / `aria-label`) stays — `aria-busy` is what says it is working. A SWAP
+     * rather than Button's overlay: the box is square and fixed, so there is no width
+     * for the glyph to hold, and a spinner drawn over a glyph would be two marks in one
+     * 20px square.
+     */
+    pending?: boolean;
+    /**
+     * Why the action is not available — {@link Button}'s `disabledReason`, on the icon
+     * button: keksdose's accounts page cannot hide an account with a balance or delete
+     * one with bookings (accounts-page:879/913 — "hide requires zero", "delete blocked"),
+     * nor its budgets page delete the only budget (budgets-page:330), and each wrapped a
+     * natively disabled IconButton in a Tooltip that swaps its label for the reason — a
+     * bubble a keyboard never opens, since `disabled` leaves the tab order, and a reason
+     * a screen reader never hears.
+     *
+     * The same contract as Button's: `aria-disabled` instead of `disabled`, so it stays
+     * focusable and hoverable; clicks (and the Enter/Space they stand for) are swallowed
+     * — `stopPropagation` still applies, so a locked action in a clickable row does not
+     * open the row either; the reason shows in the kit {@link Tooltip} and is attached
+     * through `aria-describedby` as a `hidden` copy. The NAME stays `aria-label` /
+     * `label` — "Delete", described by "The active budget cannot be deleted" — and the
+     * bubble shows the reason in place of the label, since the glyph already says what
+     * the button is and the reason is the news. Shown even with `tooltip={false}`: a
+     * reason nobody can see is not one. Wins over `disabled`, as on Button.
+     *
+     * 0.32: at Large and on a touch screen the reason is a line under the button rather
+     * than a bubble — see `disabledReasonDisplay`.
+     */
+    disabledReason?: ReactNode;
+    /** Where `disabledReason` shows — {@link Button}'s `disabledReasonDisplay`. */
+    disabledReasonDisplay?: DisabledReasonDisplay;
+    /** This action COMMITS — {@link Button}'s `commit`: under a locked
+     *  {@link WriteLockProvider} it takes the `disabledReason` path with the lock's
+     *  reason. No effect without a lock. A {@link CommitScope} since 0.33. */
+    commit?: CommitScope;
+    /** The `<button>` element — a prop in React 19, as on {@link Button}. */
+    ref?: Ref<HTMLButtonElement>;
+    /** Only on the link form — see {@link IconButtonLinkProps}. */
+    href?: never;
+    renderLink?: never;
+    external?: never;
+    replace?: never;
+    reloadDocument?: never;
+}
+/**
+ * `<IconButton href>`: an icon-only LINK — keksdose F2 and kastlan 45, whose icon
+ * actions that navigate (a row's "open", a card's "edit" that goes to the edit page, a
+ * top bar's settings cog) were `<IconButton onClick={() => navigate(…)}>`: a button that
+ * changes the page, with no middle click, no "open in new tab" and no URL on hover.
+ *
+ * The same rule as {@link Button}'s `href` (see {@link ButtonLinkProps}): an in-app
+ * `href` goes through `renderLink`, else the provider's `linkComponent`; an external one
+ * or an in-page `#anchor` stays a plain `<a>`; `external` opens a new tab and says so to
+ * a screen reader; `replace` and `reloadDocument` as on Button. The look, the `label` →
+ * `aria-label` + Tooltip, the badge, `toneColor` and `stopPropagation` are the button's.
+ *
+ * `disabled` renders an inert `<a>` with no `href` — `role="link"`, `aria-disabled`, out
+ * of the tab order, dimmed — like Button's disabled link. `pressed`, `disabledReason` and
+ * `disabledStyle` are a button's and are typed out: a link is not a toggle, and a link
+ * that explains why it cannot be followed is a job for a disabled BUTTON.
+ */
+export interface IconButtonLinkProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, "type" | "href">, Pick<IconButtonProps, "variant" | "size" | "glyphSize" | "badge" | "stretch" | "shape" | "toneColor" | "tone" | "quiet" | "stopPropagation" | "label" | "labelVisible" | "tooltip" | "tooltipSide" | "tooltipPortal" | "tooltipLazy"> {
+    href: string;
+    /** See {@link ButtonLinkProps.renderLink}. */
+    renderLink?: KitLinkComponent;
+    /** See {@link ButtonLinkProps.external}. */
+    external?: boolean;
+    /** See {@link ButtonLinkProps.replace}. */
+    replace?: boolean;
+    /** See {@link ButtonLinkProps.reloadDocument}. */
+    reloadDocument?: boolean;
+    /** See {@link ButtonLinkProps.disabled}. */
+    disabled?: boolean;
+    ref?: Ref<HTMLAnchorElement>;
+    type?: never;
+    form?: never;
+    pressed?: never;
+    disabledReason?: never;
+    disabledReasonDisplay?: never;
+    commit?: never;
+    disabledStyle?: never;
+    pending?: never;
+}
+/**
+ * `toneColor`: one CSS colour, or one per theme.
+ *
+ * The pair is two custom properties on the element — `--icon-button-tone-light` and
+ * `--icon-button-tone-dark` — and a class that points `--icon-button-tone` at one or the
+ * other by the kit's `dark` variant (`.dark` on an ancestor, tokens.css), so the colour
+ * follows a theme switch in CSS alone, with no re-render and no JS reading the theme.
+ * Both values are any CSS colour; a token that already flips (`var(--warning)`) needs no
+ * pair.
+ */
+export type IconButtonToneColor = string | {
+    light: string;
+    dark: string;
+};
+export declare function IconButton(props: IconButtonLinkProps): ReactElement;
+export declare function IconButton(props: IconButtonProps): ReactElement;