Merge pull request #20 from svelte-plugins/add-prop-driven-visibility

refactor(tooltips): add show prop to interface for manual control of showing/hiding

Author: dysfunc

README.md

@@ -42,14 +42,15 @@ Checkout out my <u use:tooltip={{ content: 'Hello World!' }}>tooltip</u>
 ### Props
 | Prop         | Description                                                         | Value                                           |
 | :----------- | :------------------------------------------------------------------ | :---------------------------------------------- |
-| action       | The action that triggers the tooltip (hover | click)                | `string` (default: `hover`)                     |
+| action       | The action that triggers the tooltip (hover | click | prop)         | `string` (default: `hover`)                     |
 | animation    | The animation to apply to the tooltip                               | `string` (default: ``)                          |
 | arrow        | If `false`, the tooltip arrow will not be shown.                    | `boolean` (default: `true`)                     |
 | autoPosition | Adjust tooltip position if viewport clipping occurs                 | `string` (default: `false`)                     |
 | content      | The string or object containing componentref and props              | `string` | `object` component (default: ``)     |
 | maxWidth     | The max allowable width of the tooltip content                      | `number` (default: `200`)                       |
 | position     | The position where the tooltip should appear relative to its parent | `string` (default: `top`)                       |
 | theme        | The CSS theme class name                                            | `string` (default: ``)                          |
+| show         | Allows you to manually control the tooltip visibility               | `boolean` (default: `false`)                    |
 | style        | The object containing theme variable overrides                      | `object` (default: `null`)                      |
 
 #### Using components as content

docs/src/App.svelte

@@ -2,6 +2,8 @@
   import Prism from 'svelte-prismjs';
   import { Tooltip, tooltip } from '@svelte-plugins/tooltips';
 	import ComponentAsContent from './ComponentAsContent.svelte';
+
+  let showTooltip = false;
 </script>
 
 <main>
@@ -54,7 +56,7 @@
   </div>
 
 	<div class="example">
-		<p>This tooltip should appear to the <u use:tooltip={{ content: { component: ComponentAsContent, props: { title: 'Title from props' }}, position: 'left', style: { backgroundColor: 'blue' } }}>left</u> and render the passed component as the tooltip content.</p>
+		<p>This tooltip should appear to the <u use:tooltip={{ content: { component: ComponentAsContent, props: { title: 'Title from props' }}, position: 'left', animation: 'slide', style: { backgroundColor: 'blue' } }}>left</u> and render the passed component as the tooltip content.</p>
     <Prism showLineNumbers={true} code={`
 <script>
   import ComponentAsContent from './ComponentAsContent.svelte';
@@ -86,6 +88,35 @@
 		This tooltip should appear on the <Tooltip content="<b>Tooltip Top</b><p>This is an example of using HTML and content wrapping.</p>" position="top" animation="slide" arrow={false}><i>top</i></Tooltip> when you hover.
 	</div>
 
+  <div class="example">
+		This tooltip should appear <Tooltip content="<b>Tooltip Top</b><p>This is an example of using the 'show' prop.</p>" position="top" animation="slide" bind:show={showTooltip} autoPosition arrow={false} action="prop">on top</Tooltip> when the show button is clicked
+      <button on:click={() => (showTooltip = true)}>Show</button>
+      <button on:click={() => (showTooltip = false)}>Hide</button>
+
+  <Prism showLineNumbers={true} code={`
+
+<script>
+  import { Tooltip } from '@svelte-plugins/tooltips';
+
+  let showTooltip = false;
+</script>
+
+<Tooltip
+  content="<b>Tooltip Top</b><p>This is an example of using the 'show' prop.</p>"
+  position="top"
+  animation="slide"
+  bind:show={showTooltip}
+  autoPosition
+  arrow={false}
+  action="prop">
+  Should show here
+</Tooltip>
+
+<button on:click={() => (showTooltip = true)}>Show</button>
+<button on:click={() => (showTooltip = false)}>Hide</button>
+`} />
+  </div>
+
 	<div class="example">
 		<p>
       This tooltip should appear to the
@@ -94,8 +125,9 @@
         position="right"
         action="click"
         theme="tooltip-theme">
-        <b>right</b> when clicked.
+        <b>right</b>
       </Tooltip>
+      when clicked.
     </p>
     <Prism showLineNumbers={true} code={`
 <Tooltip

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@svelte-plugins/tooltips",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "license": "MIT",
   "description": "A simple tooltip action and component designed for Svelte.",
   "author": "Kieran Boyle (https://github.com/dysfunc)",

package.json

@@ -10,6 +10,7 @@ exports[`Components: Tooltip should render the component 1`] = `
       Hello World!
       
     </div>
+    
   </div>
 </body>
 `;

src/action-tooltip.snap.js

@@ -5,57 +5,76 @@
   import { formatVariableKey, getMinWidth, isInViewport } from './helpers';
   import { inverse } from './constants';
 
+  /** @type {'hover' | 'click' | 'prop' | string} */
   export let action = 'hover';
+
+  /** @type {string | {component: any, props?: Record<string, any>}} */
   export let content = '';
+
+  /** @type {'left' | string} */
   export let align = 'left';
+
+  /** @type {'top' | string} */
   export let position = 'top';
+
+  /** @type {number} */
   export let maxWidth = 200;
-  /**
-   * @type {{ [x: string]: any; } | null}
-   */
-   export let style = null;
+
+  /** @type {Record<string, string> | null} */
+  export let style = null;
+
+  /** @type {string} */
   export let theme = '';
+
+  /** @type {string} */
   export let animation = '';
+
+  /** @type {boolean} */
   export let arrow = true;
+
+  /** @type {boolean} */
   export let autoPosition = false;
 
-  /**
-   * @type {HTMLDivElement | null}
-   */
-  let ref = null;
+  /** @type {boolean} */
+  export let show = false;
+
+  /** @type {HTMLDivElement | null} */
+  let tooltipRef = null;
+
+  /** @type {number} */
   let minWidth = 0;
-  /**
-   * @type {{ $destroy: () => void; } | null}
-   */
+
+  /** @type {any} */
   let component = null;
-  /**
-   * @type {string | null}
-   */
+
+  /** @type {string | null} */
   let animationEffect = null;
-  let show = false;
 
-  onMount(() => {
-    const delay = animation ? 200 : 0;
+  /** @type {boolean} */
+  let visible = false;
 
-    if (ref !== null) {
+  const delay = animation ? 200 : 0;
+
+  onMount(() => {
+    if (tooltipRef !== null) {
       if (isComponent && !component) {
         // @ts-ignore
-        component = new content.component({ target: ref, props: { action, ...content.props } });
+        component = new content.component({ target: tooltipRef, props: { action, ...content.props } });
       }
 
-      minWidth = getMinWidth(ref, maxWidth);
+      minWidth = getMinWidth(tooltipRef, maxWidth);
 
       if (style && typeof style === 'object') {
         for (let prop in style) {
           const key = formatVariableKey(prop);
           const value = style[prop];
 
-          ref.style.setProperty(`--tooltip-${key}`, value);
+          tooltipRef.style.setProperty(`--tooltip-${key}`, value);
         }
       }
     }
 
-    if (autoPosition && !isInViewport(ref)) {
+    if (autoPosition && !isInViewport(tooltipRef)) {
       // @ts-ignore
       position = inverse[position];
     }
@@ -64,7 +83,7 @@
       animationEffect = animation;
     }
 
-    setTimeout(() => (show = true), delay);
+    setTimeout(() => (visible = true), delay);
   });
 
   onDestroy(() => {
@@ -75,13 +94,14 @@
   });
 
   $: isComponent = typeof content === 'object';
+  $: tooltipRef && show ? setTimeout(() => (visible = true), delay) : (visible = false);
 </script>
 
 {#if content}
   <div
-    bind:this={ref}
+    bind:this={tooltipRef}
     class="tooltip animation-{animationEffect} {position} {theme}"
-    class:show
+    class:show={visible}
     class:arrowless={!arrow}
     style="min-width: {minWidth}px; max-width: {maxWidth}px; text-align: {align};"
   >

src/action-tooltip.svelte

@@ -2,53 +2,70 @@ import type { SvelteComponentTyped } from 'svelte';
 
 export interface ComponentProps {
   /**
-   * The content of the tooltip.
-   * @default ''
+   * The action to trigger the tooltip
+   * @default 'hover'
    */
-  content?: string;
+  action: 'hover' | 'click' | 'prop' | string;
 
   /**
-   * The position of the tooltip.
-   * Allowed values are 'top', 'bottom', 'left' or 'right'.
-   * @default 'top'
+   * The alignment of the tooltip.
+   * @default 'left'
    */
-  position?: string;
+  align?: 'left' | 'right' | 'center' | string;
 
   /**
-   * The maximum width of the tooltip.
-   * @default 200
+   * The animation style of the tooltip.
+   * @default ''
    */
-  maxWidth?: number;
+  animation?: string;
 
   /**
-   * The style of the tooltip.
-   * @default null
+   * Whether to show the arrow of the tooltip.
+   * @default true
    */
-  style?: undefined;
+  arrow?: boolean;
 
   /**
-   * The theme of the tooltip.
-   * @default ''
+   * Whether to automatically position the tooltip when clipping occurs.
+   * @default false
    */
-  theme?: string;
+  autoPosition?: boolean;
 
   /**
-   * The animation style of the tooltip.
+   * The content of the tooltip.
    * @default ''
    */
-  animation?: string;
+  content?: string;
 
   /**
-   * Whether to show the arrow of the tooltip.
-   * @default true
+   * The maximum width of the tooltip.
+   * @default 200
    */
-  arrow?: boolean;
+  maxWidth?: number;
 
   /**
-   * Whether to automatically position the tooltip.
+   * The position of the tooltip.
+   * @default 'top'
+   */
+  position?: 'bottom' | 'left' | 'right' | 'top' | string;
+
+  /**
+   * Control the visibility of the tooltip.
    * @default false
    */
-  autoPosition?: boolean;
+  show?: boolean;
+
+  /**
+   * The style of the tooltip.
+   * @default null
+   */
+  style?: undefined;
+
+  /**
+   * The theme of the tooltip.
+   * @default ''
+   */
+  theme?: string;
 }
 
 export default class Component extends SvelteComponentTyped<

src/action-tooltip.svelte.d.ts

@@ -1,7 +1,6 @@
 import Tooltip from './action-tooltip.svelte';
 
 export const tooltip = (element, props) => {
-
   let component = null;
   let title = element.getAttribute('title');
   let action = props?.action || element.getAttribute('action') || 'hover';
@@ -17,13 +16,13 @@ export const tooltip = (element, props) => {
 
   const onClick = () => {
     if (component) {
-      onMouseLeave();
+      onHide();
     } else {
-      onMouseEnter();
+      onShow();
     }
   };
 
-  const onMouseEnter = () => {
+  const onShow = () => {
     if (!component) {
       component = new Tooltip({
         target: element,
@@ -32,7 +31,7 @@ export const tooltip = (element, props) => {
     }
   };
 
-  const onMouseLeave = () => {
+  const onHide = () => {
     if (component) {
       component.$destroy();
       component = null;
@@ -45,25 +44,31 @@ export const tooltip = (element, props) => {
 
       if (action === 'click') {
         element.addEventListener('click', onClick);
-      } else {
-        element.addEventListener('mouseenter', onMouseEnter);
-        element.addEventListener('mouseleave', onMouseLeave);
+      }
+
+      if (action === 'hover') {
+        element.addEventListener('mouseenter', onShow);
+        element.addEventListener('mouseleave', onHide);
       }
     }
   }
 
   const removeListeners = () => {
     if (element !== null) {
       element.removeEventListener('click', onClick);
-      element.removeEventListener('mouseenter', onMouseEnter);
-      element.removeEventListener('mouseleave', onMouseLeave);
+      element.removeEventListener('mouseenter', onShow);
+      element.removeEventListener('mouseleave', onHide);
     }
   };
 
   addListeners();
 
   element.style.position = 'relative';
 
+  if (props.show) {
+    onShow();
+  }
+
   return {
     destroy() {
       removeListeners();

src/action.js

@@ -1 +1,2 @@
-export { default } from "./tooltip.svelte";
+export { default as Tooltip } from './tooltip.svelte';
+export { tooltip } from './action';

src/index.d.ts

@@ -5,53 +5,72 @@
   import { formatVariableKey, getMinWidth, isInViewport } from './helpers';
   import { inverse } from './constants';
 
+  /** @type {'hover' | 'click' | 'prop' | string} */
   export let action = 'hover';
+
+  /** @type {string | {component: any, props?: Record<string, any>}} */
   export let content = '';
+
+  /** @type {'left' | 'center' | 'right' | string} */
   export let align = 'left';
+
+  /** @type {'top' | 'bottom' | 'left' | 'right' | string} */
   export let position = 'top';
+
+  /** @type {number} */
   export let maxWidth = 200;
-  /**
-   * @type {{ [x: string]: any; } | null}
-   */
+
+  /** @type {{ [x: string]: any; } | null} */
   export let style = null;
+
+  /** @type {string} */
   export let theme = '';
+
+  /** @type {string} */
   export let animation = '';
+
+  /** @type {boolean} */
   export let arrow = true;
+
+  /** @type {boolean} */
   export let autoPosition = false;
 
-  /**
-   * @type {HTMLSpanElement | null}
-   */
+  /** @type {boolean} */
+  export let show = false;
+
+  /** @type {HTMLSpanElement | null} */
   let containerRef = null;
-  /**
-   * @type {HTMLDivElement | null}
-   */
+
+  /** @type {HTMLDivElement | null} */
   let tooltipRef = null;
+
+  /** @type {number} */
   let minWidth = 0;
-  /**
-   * @type {{ $destroy: () => void; } | null}
-   */
+
+  /** @type {{ $destroy: () => void; } | null} */
   let component = null;
+
+  /** @type {'top' | string} */
   let initialPosition = position;
-  /**
-   * @type {string | null}
-   */
+
+  /** @type {string | null} */
   let animationEffect = null;
-  let show = false;
-  /**
-   * @type {number | null | undefined}
-   */
+
+  /** @type {number | null} */
   let timer = null;
 
+  /** @type {boolean} */
+  let visible = false;
+
   const onClick = () => {
-    if (show) {
-      onMouseLeave();
+    if (visible) {
+      onHide();
     } else {
-      onMouseEnter();
+      onShow();
     }
   };
 
-  const onMouseEnter = () => {
+  const onShow = () => {
     const delay = animation ? 200 : 0;
 
     if (autoPosition && !isInViewport(tooltipRef)) {
@@ -63,11 +82,11 @@
       animationEffect = animation;
     }
 
-    timer = setTimeout(() => (show = true), delay);
+    timer = setTimeout(() => (visible = true), delay);
   };
 
-  const onMouseLeave = () => {
-    show = false;
+  const onHide = () => {
+    visible = false;
     position = initialPosition;
     animationEffect = null;
 
@@ -86,17 +105,17 @@
       }
 
       if (action === 'hover') {
-        containerRef.addEventListener('mouseenter', onMouseEnter);
-        containerRef.addEventListener('mouseleave', onMouseLeave);
+        containerRef.addEventListener('mouseenter', onShow);
+        containerRef.addEventListener('mouseleave', onHide);
       }
     }
   }
 
   const removeListeners = () => {
     if (containerRef !== null) {
       containerRef.removeEventListener('click', onClick);
-      containerRef.removeEventListener('mouseenter', onMouseEnter);
-      containerRef.removeEventListener('mouseleave', onMouseLeave);
+      containerRef.removeEventListener('mouseenter', onShow);
+      containerRef.removeEventListener('mouseleave', onHide);
     }
   };
 
@@ -137,6 +156,7 @@
 
   $: isComponent = typeof content === 'object';
   $: action, addListeners();
+  $: tooltipRef && show ? onShow() : onHide();
 </script>
 
 {#if content}
@@ -146,7 +166,7 @@
         bind:this={tooltipRef}
         class="tooltip animation-{animationEffect} {position} {theme}"
         class:arrowless={!arrow}
-        class:show
+        class:show={visible}
         style="min-width: {minWidth}px; max-width: {maxWidth}px; text-align: {align};"
       >
         {#if !isComponent}

src/tooltip.svelte

@@ -2,53 +2,70 @@ import type { SvelteComponentTyped } from 'svelte';
 
 export interface ComponentProps {
   /**
-   * The content of the tooltip.
-   * @default ''
+   * The action to trigger the tooltip
+   * @default 'hover'
    */
-  content?: string;
+  action: 'hover' | 'click' | 'prop' | string;
 
   /**
-   * The position of the tooltip.
-   * Allowed values are 'top', 'bottom', 'left' or 'right'.
-   * @default 'top'
+   * The alignment of the tooltip.
+   * @default 'left'
    */
-  position?: string;
+  align?: 'left' | 'right' | 'center' | string;
 
   /**
-   * The maximum width of the tooltip.
-   * @default 200
+   * The animation style of the tooltip.
+   * @default ''
    */
-  maxWidth?: number;
+  animation?: string;
 
   /**
-   * The style of the tooltip.
-   * @default null
+   * Whether to show the arrow of the tooltip.
+   * @default true
    */
-  style?: undefined;
+  arrow?: boolean;
 
   /**
-   * The theme of the tooltip.
-   * @default ''
+   * Whether to automatically position the tooltip when clipping occurs.
+   * @default false
    */
-  theme?: string;
+  autoPosition?: boolean;
 
   /**
-   * The animation style of the tooltip.
+   * The content of the tooltip.
    * @default ''
    */
-  animation?: string;
+  content?: string;
 
   /**
-   * Whether to show the arrow of the tooltip.
-   * @default true
+   * The maximum width of the tooltip.
+   * @default 200
    */
-  arrow?: boolean;
+  maxWidth?: number;
 
   /**
-   * Whether to automatically position the tooltip.
+   * The position of the tooltip.
+   * @default 'top'
+   */
+  position?: 'bottom' | 'left' | 'right' | 'top' | string;
+
+  /**
+   * Control the visibility of the tooltip.
    * @default false
    */
-  autoPosition?: boolean;
+  show?: boolean;
+
+  /**
+   * The style of the tooltip.
+   * @default null
+   */
+  style?: undefined;
+
+  /**
+   * The theme of the tooltip.
+   * @default ''
+   */
+  theme?: string;
 }
 
 export default class Component extends SvelteComponentTyped<