Skip to content

Build your personal knowledge base with Trilium Notes

12.5 KB
Raw Blame
import "./OverlayControlGroup.css";

import clsx from "clsx";
import { type ComponentChildren, createContext, type HTMLAttributes } from "preact";
import { useContext, useMemo, useRef } from "preact/hooks";

import { t } from "../../services/i18n";
import { formatShortcut, joinShortcut } from "../../services/keyboard_shortcut_display";
import type { ActionButtonProps } from "./ActionButton";
import Dropdown, { DropdownPanel, type DropdownProps } from "./Dropdown";
import { useStaticTooltip } from "./hooks";

/**
 * Where a group stands over what it is put on: which edge of it, and where along that edge. A group
 * pinned to a side edge stands at the middle of it, which is where a vertical rail goes.
 */
export type OverlayPlacement = `${"top" | "bottom"}-${"start" | "center" | "end"}` | `middle-${"start" | "end"}`;

interface OverlayControlGroupProps {
    /**
     * Which corner — or middle of which edge — the group is pinned to, over the nearest positioned
     * ancestor. How much room it keeps from the edges is the caller's to name, through
     * `--overlay-group-inset` or one of its per-edge forms, and so is what the group stands above
     * (`z-index`), that being about the company it keeps rather than about the group. Left out, the
     * group is laid out in the flow like anything else and placing it is the caller's business
     * entirely.
     */
    placement?: OverlayPlacement;
    /** What is peculiar to this group, styled by whoever puts it there. */
    className?: string;
    /**
     * Which way the buttons' tooltips open. Follows the placement by default — away from the edge the
     * group is pinned to — and is only worth passing for a group placed by hand.
     */
    titlePosition?: ActionButtonProps["titlePosition"];
    /**
     * Stacks the buttons into a column instead of a row, for a rail down one side of the content.
     * The rounding of the two ends follows the column, and the tooltips open sideways.
     */
    vertical?: boolean;
    /**
     * Keeps a press on the group from reaching what it stands on, for a group over a canvas that is
     * dragged: a map would otherwise take a press on a button for the start of a drag.
     */
    overCanvas?: boolean;
    children: ComponentChildren;
}

/**
 * A run of buttons standing over content, joined edge to edge into one segmented chip: the image
 * viewer's zoom steps, and the like.
 *
 * The surface, the seams and the rounding of the two ends are the theme's to give (see the overlay
 * buttons in theme-next/forms.css). The standing is the group's own, and comes with it
 * (OverlayControlGroup.css): a group names the corner it is pinned to (see {@link OverlayPlacement})
 * rather than each site pinning itself afresh. What is left to the caller is the room to keep from
 * the edges and what the group stands above, both handed over as properties — the first because a
 * map in fullscreen keeps clear of what the screen keeps for itself, the second because it is about
 * what else is in that corner.
 *
 * Not to be confused with {@link OverlayToolbar}, the other thing that floats over content: that one
 * is a bar of separate buttons on a pane of glass, and it brings its own surface with it. This is a
 * single chip with no gaps, and it is what the app's zoom and navigation controls are built from.
 */
export default function OverlayControlGroup({ placement, className, titlePosition, vertical, overCanvas, children }: OverlayControlGroupProps) {
    return (
        <div
            className={clsx("tn-overlay-control-group", className)}
            data-placement={placement}
            data-orientation={vertical ? "vertical" : undefined}
            onMouseDown={overCanvas ? (e) => e.stopPropagation() : undefined}
        >
            <TooltipDirection.Provider value={titlePosition ?? tooltipDirectionFor(placement, vertical)}>
                {children}
            </TooltipDirection.Provider>
        </div>
    );
}

/**
 * Which way a group's tooltips open, given where it stands: away from the edge it is pinned to, so
 * that a group at the head of the content does not open its tooltips off the top of it. A vertical
 * group is pinned to a side edge, so its tooltips open sideways instead. A group placed by hand is
 * taken to stand at the foot, which is where all but one of them do.
 */
function tooltipDirectionFor(placement: OverlayPlacement | undefined, vertical: boolean | undefined): ActionButtonProps["titlePosition"] {
    if (vertical) {
        return placement?.endsWith("-end") ? "left" : "right";
    }

    return placement?.startsWith("top-") ? "bottom" : "top";
}

interface OverlayControlButtonProps extends Pick<HTMLAttributes<HTMLButtonElement>, "onClick" | "aria-label"> {
    /** What the button does, said on hover. Where the button wears nothing to read, it is its name too. */
    title?: string;
    /** The boxicons name of the mark it wears (`bx-plus-circle`). */
    icon?: string;
    /** What stands inside the button: the words it wears, or the value it shows. */
    text?: ComponentChildren;
    /** Extra class for whatever is peculiar to this one button. */
    className?: string;
    /** Shown held down, for a button standing for a choice in force. */
    active?: boolean;
    disabled?: boolean;
    /** Overrides the direction the group hands down, for a button placed unlike its neighbours. */
    titlePosition?: ActionButtonProps["titlePosition"];
    /** A key that does what the button does, as `formatShortcut()` reads it, named after the title. */
    shortcut?: string;
}

/**
 * A button on such a group, in one of two shapes: a mark, drawn at an icon's width, or something to
 * read, drawn at a word's. Given both, the mark stands beside the words — as a child rather than as a
 * class on the button, the boxicons class setting the icon font on whatever wears it and the words
 * beside it being meant to stay words.
 *
 * What it is called follows from that: a button wearing words is named by them, and one wearing only a
 * mark by its title, so that a title saying more at length never speaks over the words on the face of
 * the button. Where what it wears is neither — a keycap, a glyph standing for itself — say so with a
 * plain `aria-label`.
 *
 * Its tooltip opens the way the group it stands on says, so that a group at the foot of the content
 * does not open its tooltips off the bottom edge, and never flips to a side, where it would cover the
 * neighbouring buttons. A `shortcut` follows the title in the tooltip only.
 */
export function OverlayControlButton(props: OverlayControlButtonProps) {
    const { title, icon, text, className, active, disabled, titlePosition, shortcut, ...restProps } = props;
    const buttonRef = useRef<HTMLButtonElement>(null);
    const groupDirection = useContext(TooltipDirection);
    const placement = titlePosition ?? groupDirection;
    const hasText = "text" in props;
    const tooltip = title && shortcut ? `${title} (${joinShortcut(formatShortcut(shortcut))})` : title;

    // Memoized so the tooltip is only rebuilt when what it says (or where it opens) actually changes,
    // rather than on every render of the group.
    const tooltipConfig = useMemo(
        () => ({ title: tooltip, placement, fallbackPlacements: placement && [ placement ] }),
        [ tooltip, placement ]
    );
    useStaticTooltip(buttonRef, tooltipConfig);

    return (
        <button
            ref={buttonRef}
            // Driven by its onClick, so it must never act as a form's implicit submit button
            // (a <button> defaults to type="submit").
            type="button"
            className={clsx(hasText ? "tn-overlay-text-button" : [ "tn-overlay-icon-button bx", icon ], active && "active", className)}
            // A caller passing one of its own wins, for a face that is neither words nor a mark.
            aria-label={hasText ? undefined : title}
            disabled={disabled}
            {...restProps}
        >
            {hasText && icon && <span className={clsx("bx", icon)} aria-hidden="true" />}
            {text}
        </button>
    );
}

interface OverlayControlDropdownProps extends Pick<DropdownProps, "children" | "disabled" | "mobileBottomSheet"> {
    /** What the button opens, said on hover; it is also the button's name. */
    title: string;
    /** The boxicons name of the mark it wears (`bx-palette`). */
    icon: string;
    /** Opens a {@link DropdownPanel}, for a picker or a form, instead of a menu. */
    panel?: boolean;
}

/**
 * A button on such a group that opens a menu, or a panel with `panel`. The popup and the tooltip open
 * away from the edge that the group is pinned to, and the tooltip never flips to a side.
 */
export function OverlayControlDropdown({ title, icon, panel, ...props }: OverlayControlDropdownProps) {
    const direction = useContext(TooltipDirection);
    const titleOptions = useMemo(() => ({ fallbackPlacements: direction && [ direction ] }), [ direction ]);
    const Toggle = panel ? DropdownPanel : Dropdown;
    return (
        <Toggle
            {...props}
            className="tn-overlay-control-dropdown"
            buttonClassName={clsx("tn-overlay-icon-button bx", icon)}
            buttonProps={{ "aria-label": title }}
            title={title}
            titlePosition={direction}
            titleOptions={titleOptions}
            placement={direction}
            hideToggleArrow
            noSelectButtonStyle
            bareButton
        />
    );
}

interface OverlayFullscreenButtonProps {
    /** Whether what the button stands over has the screen to itself. */
    isFullscreen: boolean;
    /** Gives it the screen, or takes it back. */
    onToggle: () => void;
}

/**
 * The button that gives what the group stands over the whole screen, and takes it back again — its
 * mark and what it is called both naming the way out once it is in. Every such button in the app says
 * the same two things, so it says them here rather than once per map.
 *
 * The state is handed to it rather than read: {@link useFullscreen} is what follows the browser, and
 * a caller may have to wrap it — the mind map takes the middle of its view before the change so as to
 * put it back after (see `useMapFullscreen`), which no button could do on its behalf.
 */
export function OverlayFullscreenButton({ isFullscreen, onToggle }: OverlayFullscreenButtonProps) {
    return (
        <OverlayControlButton
            title={isFullscreen ? t("common.exit_fullscreen") : t("common.fullscreen")}
            icon={isFullscreen ? "bx-exit-fullscreen" : "bx-fullscreen"}
            onClick={() => onToggle()}
        />
    );
}

interface ZoomControlsProps {
    /**
     * The scale to show between the two steps, as a percentage. What 100% means is the caller's
     * choice: native resolution in `ImageViewer`, the fitted view in `SvgSplitEditor`, natural size
     * in the mind map. Omit it to render the two steps with no readout, as the geo map does — a
     * MapLibre zoom level means nothing as a percentage.
     */
    percent?: number;
    /** Disables the matching step. Pass `false` once the scale has reached a bound. */
    canZoomIn?: boolean;
    canZoomOut?: boolean;
    onZoomIn: () => void;
    onZoomOut: () => void;
    /** Runs when the readout is clicked, so it is only needed alongside `percent`. */
    onReset?: () => void;
}

/**
 * Renders the three zoom controls — out, the readout, in — for an {@link OverlayControlGroup} to
 * hold.
 *
 * Buttons rather than a group of their own, because the geo map and mind map toolbars put them in
 * one group beside a tilt, a recenter and a fullscreen button.
 */
export function ZoomControls({ percent, canZoomIn = true, canZoomOut = true, onZoomIn, onZoomOut, onReset }: ZoomControlsProps) {
    return (
        <>
            <OverlayControlButton
                title={t("zoom_controls.zoom_out")}
                icon="bx-minus-circle"
                disabled={!canZoomOut}
                onClick={onZoomOut}
            />
            {percent !== undefined && (
                <OverlayControlButton
                    title={t("zoom_controls.reset")}
                    text={`${Math.round(percent)}%`}
                    onClick={onReset}
                />
            )}
            <OverlayControlButton
                title={t("zoom_controls.zoom_in")}
                icon="bx-plus-circle"
                disabled={!canZoomIn}
                onClick={onZoomIn}
            />
        </>
    );
}

/** Which way the tooltips on a group open, handed down by the group rather than repeated on each button. */
const TooltipDirection = createContext<ActionButtonProps["titlePosition"]>("top");