@justeattakeaway/pie-tooltip 0.1.1 → 0.3.0

package/dist/react.d.ts

@@ -1,21 +1,177 @@
+import { ComponentDefaultProps } from '@justeattakeaway/pie-webc-core';
 import { CSSResult } from 'lit';
 import { PieElement } from '@justeattakeaway/pie-webc-core/src/internals/PieElement';
+import { PropertyValues } from 'lit';
 import * as React_2 from 'react';
-import { TemplateResult } from 'lit-html';
+import { TemplateResult } from 'lit';
 
-export declare const PieTooltip: React_2.ForwardRefExoticComponent<React_2.PropsWithChildren<Omit<React_2.PropsWithoutRef<TooltipProps>, "children">> & React_2.RefAttributes<PieTooltip_2> & ReactBaseType>;
+declare type AriaProps = {
+    /**
+     * The accessible name for the close button. Required whenever `isDismissible` is set.
+     */
+    close?: string;
+    /**
+     * The accessible name for the panel in dialog mode. Only used when `heading` is not provided.
+     */
+    label?: string;
+};
+
+export declare const componentClass = "c-tooltip";
+
+export declare const componentSelector = "pie-tooltip";
+
+export declare type DefaultProps = ComponentDefaultProps<TooltipProps, keyof Omit<TooltipProps, 'trigger' | 'heading' | 'aria' | 'triggers'>>;
+
+export declare const defaultProps: DefaultProps;
+
+export declare const headingLevels: readonly ["h2", "h3", "h4", "h5", "h6"];
+
+/**
+ * The two patterns the panel can present as. Inferred from the `action` slot rather than
+ * configured: an empty `action` slot is a tooltip, a filled one is a non-modal dialog.
+ */
+export declare const modes: readonly ["tooltip", "dialog"];
+
+export declare const ON_TOOLTIP_CLOSE_EVENT = "pie-tooltip-close";
+
+export declare const ON_TOOLTIP_OPEN_EVENT = "pie-tooltip-open";
+
+export declare const PieTooltip: React_2.ForwardRefExoticComponent<React_2.PropsWithChildren<Omit<React_2.PropsWithoutRef<TooltipProps>, "children">> & React_2.RefAttributes<PieTooltip_2> & PieTooltipEvents & ReactBaseType>;
 
 /**
  * @tagname pie-tooltip
+ * @event {Event} pie-tooltip-open - When a configured trigger asks for the panel. Set `isOpen` to `true` in response.
+ * @event {Event} pie-tooltip-close - When the close button is clicked, or a configured trigger asks to dismiss the panel. Set `isOpen` to `false` in response.
+ * @slot content - The descriptive content of the panel. Must not contain focusable elements.
+ * @slot action - An optional slot for interactive content such as a `pie-button`. Filling this slot switches the panel to a non-modal dialog.
  */
 declare class PieTooltip_2 extends PieElement implements TooltipProps {
-    render(): TemplateResult<1>;
+    trigger: TooltipProps['trigger'];
+    isOpen: boolean;
+    position: "top" | "top-start" | "top-end" | "bottom" | "bottom-start" | "bottom-end" | "left" | "left-start" | "left-end" | "right" | "right-start" | "right-end";
+    size: "default" | "fit-to-content" | "fill-container";
+    variant: "default" | "inverse";
+    type: "default" | "icon";
+    isDismissible: boolean;
+    heading: TooltipProps['heading'];
+    headingLevel: "h2" | "h3" | "h4" | "h5" | "h6";
+    aria: TooltipProps['aria'];
+    triggers: TooltipProps['triggers'];
+    private _assignedActionElements;
+    private _originElement;
+    private _hasActionContent;
+    private _isPositioned;
+    private _isAnchorVisible;
+    private _clippedTriggerElement;
+    private _triggerClippers;
+    private _triggerTrackingController;
+    private _interactionController;
+    private _directionObserver;
+    private _triggerObserver;
+    private _reanchorFrame;
+    private _shouldResolveOverlayMode;
+    private _hoverCloseTimer;
     static styles: CSSResult;
+    private get _mode();
+    protected firstUpdated(): void;
+    protected updated(changedProperties: PropertyValues<this>): void;
+    disconnectedCallback(): void;
+    private startTrackingTrigger;
+    private stopTrackingTrigger;
+    private resolveMode;
+    private resolveOverlayMode;
+    private projectOverTrigger;
+    private _refreshTriggerClippers;
+    private handleCloseButtonClick;
+    private _getTriggerElement;
+    private _requestOpen;
+    private _requestClose;
+    private _startHoverCloseTimer;
+    private _cancelHoverCloseTimer;
+    private _rebuildInteractionListeners;
+    private _teardownInteractionListeners;
+    private renderHeading;
+    private renderCloseButton;
+    render(): TemplateResult;
 }
 
+declare type PieTooltipEvents = {
+    onPieTooltipOpen?: (event: Event) => void;
+    onPieTooltipClose?: (event: Event) => void;
+};
+
+export declare const positions: readonly ["top", "top-start", "top-end", "bottom", "bottom-start", "bottom-end", "left", "left-start", "left-end", "right", "right-start", "right-end"];
+
 declare type ReactBaseType = React_2.HTMLAttributes<HTMLElement>;
 
+export declare const sizes: readonly ["default", "fit-to-content", "fill-container"];
+
+export declare type TooltipMode = typeof modes[number];
+
 export declare interface TooltipProps {
+    /**
+     * The `id` of the element the panel is anchored to. The trigger lives elsewhere in the
+     * DOM and is never slotted into the tooltip.
+     */
+    trigger?: string;
+    /**
+     * When true, the panel is visible. The component never writes to this property: the
+     * consumer owns it and updates it in response to the close event.
+     */
+    isOpen?: boolean;
+    /**
+     * The side of the trigger the panel sits on, and its alignment along the cross axis.
+     */
+    position?: typeof positions[number];
+    /**
+     * How the panel sizes itself. `default` is a fixed 280px and wraps, `fit-to-content` is as
+     * wide as its content, and `fill-container` matches the inline size of the trigger's parent
+     * element. Not applied when `type` is `icon`.
+     */
+    size?: typeof sizes[number];
+    /**
+     * The colour treatment of the panel. `default` is the dark panel, `inverse` the light one.
+     */
+    variant?: typeof variants[number];
+    /**
+     * The presentation of the panel. `icon` is the compact treatment intended for icon triggers:
+     * it has no arrow and is always as wide as its content, so `size` and `--tooltip-width` have
+     * no effect on it.
+     */
+    type?: typeof types[number];
+    /**
+     * When true, a close button is rendered inside the panel.
+     */
+    isDismissible?: boolean;
+    /**
+     * The text to display in the panel's heading. In dialog mode this also provides the
+     * panel's accessible name.
+     */
+    heading?: string;
+    /**
+     * The HTML heading tag to use for the panel's heading. Can be h2-h6.
+     */
+    headingLevel?: typeof headingLevels[number];
+    /**
+     * The ARIA labels used for various parts of the tooltip.
+     */
+    aria?: AriaProps;
+    /**
+     * Which interactions request that the panel opens and closes. The component never opens or
+     * closes itself: a configured interaction emits `pie-tooltip-open` or `pie-tooltip-close`
+     * and the consumer decides whether to honour it by setting `isOpen`. Empty by default, so
+     * no interaction is watched at all. Configure `hover` and `focus` together for keyboard
+     * reachability, and `click` for pointer users.
+     */
+    triggers?: Array<TooltipTrigger>;
 }
 
+export declare type TooltipTrigger = typeof triggers[number];
+
+export declare const triggers: readonly ["hover", "focus", "click"];
+
+export declare const types: readonly ["default", "icon"];
+
+export declare const variants: readonly ["default", "inverse"];
+
 export { }

package/dist/react.js

@@ -1,13 +1,31 @@
 import * as o from "react";
-import { createComponent as t } from "@lit/react";
-import { PieTooltip as e } from "./index.js";
-const i = t({
+import { createComponent as e } from "@lit/react";
+import { PieTooltip as t } from "./index.js";
+import { ON_TOOLTIP_CLOSE_EVENT as r, ON_TOOLTIP_OPEN_EVENT as m, componentClass as T, componentSelector as P, defaultProps as c, headingLevels as O, modes as N, positions as E, sizes as _, triggers as f, types as C, variants as d } from "./index.js";
+const i = e({
   displayName: "PieTooltip",
-  elementClass: e,
+  elementClass: t,
   react: o,
   tagName: "pie-tooltip",
-  events: {}
-}), m = i;
+  events: {
+    onPieTooltipOpen: "pie-tooltip-open",
+    // When a configured trigger asks for the panel. Set `isOpen` to `true` in response.
+    onPieTooltipClose: "pie-tooltip-close"
+    // When the close button is clicked, or a configured trigger asks to dismiss the panel. Set `isOpen` to `false` in response.
+  }
+}), l = i;
 export {
-  m as PieTooltip
+  r as ON_TOOLTIP_CLOSE_EVENT,
+  m as ON_TOOLTIP_OPEN_EVENT,
+  l as PieTooltip,
+  T as componentClass,
+  P as componentSelector,
+  c as defaultProps,
+  O as headingLevels,
+  N as modes,
+  E as positions,
+  _ as sizes,
+  f as triggers,
+  C as types,
+  d as variants
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@justeattakeaway/pie-tooltip",
   "description": "PIE Design System Tooltip built using Web Components",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "type": "module",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -36,11 +36,13 @@
   "license": "Apache-2.0",
   "devDependencies": {
     "@justeattakeaway/pie-components-config": "0.21.4",
-    "@justeattakeaway/pie-css": "1.8.0",
-    "@justeattakeaway/pie-monorepo-utils": "0.9.9"
+    "@justeattakeaway/pie-css": "1.9.0",
+    "@justeattakeaway/pie-monorepo-utils": "0.9.10"
   },
   "dependencies": {
-    "@justeattakeaway/pie-webc-core": "21.0.0"
+    "@justeattakeaway/pie-icon-button": "2.7.35",
+    "@justeattakeaway/pie-icons-webc": "1.29.4",
+    "@justeattakeaway/pie-webc-core": "22.0.0"
   },
   "customElements": "custom-elements.json",
   "sideEffects": [

package/src/defs.ts

@@ -1,3 +1,129 @@
-// TODO - please remove the eslint disable comment below when you add props to this interface
-// eslint-disable-next-line @typescript-eslint/no-empty-interface
-export interface TooltipProps {}
+import { type ComponentDefaultProps } from '@justeattakeaway/pie-webc-core';
+
+export const positions = [
+    'top',
+    'top-start',
+    'top-end',
+    'bottom',
+    'bottom-start',
+    'bottom-end',
+    'left',
+    'left-start',
+    'left-end',
+    'right',
+    'right-start',
+    'right-end',
+] as const;
+
+export const sizes = ['default', 'fit-to-content', 'fill-container'] as const;
+export const variants = ['default', 'inverse'] as const;
+export const types = ['default', 'icon'] as const;
+export const headingLevels = ['h2', 'h3', 'h4', 'h5', 'h6'] as const;
+export const triggers = ['hover', 'focus', 'click'] as const;
+
+/**
+ * The two patterns the panel can present as. Inferred from the `action` slot rather than
+ * configured: an empty `action` slot is a tooltip, a filled one is a non-modal dialog.
+ */
+export const modes = ['tooltip', 'dialog'] as const;
+
+export type TooltipMode = typeof modes[number];
+export type TooltipTrigger = typeof triggers[number];
+
+type AriaProps = {
+    /**
+     * The accessible name for the close button. Required whenever `isDismissible` is set.
+     */
+    close?: string;
+
+    /**
+     * The accessible name for the panel in dialog mode. Only used when `heading` is not provided.
+     */
+    label?: string;
+};
+
+export interface TooltipProps {
+    /**
+     * The `id` of the element the panel is anchored to. The trigger lives elsewhere in the
+     * DOM and is never slotted into the tooltip.
+     */
+    trigger?: string;
+
+    /**
+     * When true, the panel is visible. The component never writes to this property: the
+     * consumer owns it and updates it in response to the close event.
+     */
+    isOpen?: boolean;
+
+    /**
+     * The side of the trigger the panel sits on, and its alignment along the cross axis.
+     */
+    position?: typeof positions[number];
+
+    /**
+     * How the panel sizes itself. `default` is a fixed 280px and wraps, `fit-to-content` is as
+     * wide as its content, and `fill-container` matches the inline size of the trigger's parent
+     * element. Not applied when `type` is `icon`.
+     */
+    size?: typeof sizes[number];
+
+    /**
+     * The colour treatment of the panel. `default` is the dark panel, `inverse` the light one.
+     */
+    variant?: typeof variants[number];
+
+    /**
+     * The presentation of the panel. `icon` is the compact treatment intended for icon triggers:
+     * it has no arrow and is always as wide as its content, so `size` and `--tooltip-width` have
+     * no effect on it.
+     */
+    type?: typeof types[number];
+
+    /**
+     * When true, a close button is rendered inside the panel.
+     */
+    isDismissible?: boolean;
+
+    /**
+     * The text to display in the panel's heading. In dialog mode this also provides the
+     * panel's accessible name.
+     */
+    heading?: string;
+
+    /**
+     * The HTML heading tag to use for the panel's heading. Can be h2-h6.
+     */
+    headingLevel?: typeof headingLevels[number];
+
+    /**
+     * The ARIA labels used for various parts of the tooltip.
+     */
+    aria?: AriaProps;
+
+    /**
+     * Which interactions request that the panel opens and closes. The component never opens or
+     * closes itself: a configured interaction emits `pie-tooltip-open` or `pie-tooltip-close`
+     * and the consumer decides whether to honour it by setting `isOpen`. Empty by default, so
+     * no interaction is watched at all. Configure `hover` and `focus` together for keyboard
+     * reachability, and `click` for pointer users.
+     */
+    triggers?: Array<TooltipTrigger>;
+}
+
+export const componentSelector = 'pie-tooltip';
+export const componentClass = 'c-tooltip';
+
+export const ON_TOOLTIP_OPEN_EVENT = `${componentSelector}-open`;
+export const ON_TOOLTIP_CLOSE_EVENT = `${componentSelector}-close`;
+
+export type DefaultProps = ComponentDefaultProps<TooltipProps, keyof Omit<TooltipProps, 'trigger' | 'heading' | 'aria' | 'triggers'>>;
+
+export const defaultProps: DefaultProps = {
+    isOpen: false,
+    position: 'top',
+    size: 'default',
+    variant: 'default',
+    type: 'default',
+    isDismissible: false,
+    headingLevel: 'h2',
+};