|
1 | | -<script> |
| 1 | +<script lang="ts"> |
2 | 2 | import CodeBlock from '$docs/components/CodeBlock/CodeBlock.svelte'; |
3 | 3 | import Example from './Example.svelte'; |
4 | 4 | import exampleCode from './Example.svelte?raw'; |
| 5 | + import Preview from '$docs/components/Preview/Preview.svelte'; |
5 | 6 | </script> |
6 | 7 |
|
7 | 8 | <div class="space-y-10"> |
| 9 | + <!-- Header --> |
8 | 10 | <header class="card card-gradient space-y-8"> |
9 | | - <h1 class="h1"> |
10 | | - <span>Tooltips</span> |
11 | | - </h1> |
| 11 | + <h1 class="h1"><span>Tooltips</span></h1> |
12 | 12 | <p> |
13 | | - A tooltip is a floating element that displays information related to an anchor element when it |
14 | | - receives keyboard focus or the mouse hovers over it. |
| 13 | + A tooltip is a floating element that displays information related to a button or anchor |
| 14 | + element when it receives keyboard focus or the mouse hovers over it. |
15 | 15 | </p> |
16 | | - <CodeBlock |
17 | | - code={`import { useFloating } from '@skeletonlabs/floatin-ui-svelte';`} |
18 | | - lang="typescript" |
19 | | - /> |
20 | 16 | </header> |
21 | 17 | <!-- Essentials --> |
22 | 18 | <section class="space-y-8"> |
|
32 | 28 | when the reference element receives keyboard focus, the tooltip opens. When the mouse |
33 | 29 | leaves, or the reference is blurred, the tooltip closes. |
34 | 30 | </li> |
35 | | - <li> |
36 | | - <span class="highlight">Dismissal</span>: When the user presses the |
| 31 | + <li class="opacity-50 line-through"> |
| 32 | + COMING SOON: <span class="highlight">Dismissal</span>: When the user presses the |
37 | 33 | <kbd class="kbd">esc</kbd> key while the tooltip is open, it closes. |
38 | 34 | </li> |
39 | 35 | <li> |
|
42 | 38 | </li> |
43 | 39 | </ul> |
44 | 40 | </section> |
| 41 | + <!-- Preview --> |
45 | 42 | <section class="space-y-8"> |
46 | | - <h2 class="h2">Examples</h2> |
47 | | - <p>Both of these examples have sections explaining them in-depth below.</p> |
48 | | - <div> |
49 | | - <Example /> |
50 | | - </div> |
| 43 | + <h2 class="h2">Example</h2> |
| 44 | + <p> |
| 45 | + This is a functional Tooltip that uses a combination of hooks and components, each of which is |
| 46 | + described in the sections below. |
| 47 | + </p> |
| 48 | + <Preview> |
| 49 | + {#snippet preview()}<Example />{/snippet} |
| 50 | + {#snippet code()}<CodeBlock code={exampleCode} lang="html" />{/snippet} |
| 51 | + </Preview> |
| 52 | + </section> |
| 53 | + <!-- Open State --> |
| 54 | + <section class="space-y-8"> |
| 55 | + <h2 class="h2">Open State</h2> |
| 56 | + <CodeBlock code={`let open = $state(false);`} lang="ts" /> |
| 57 | + <p> |
| 58 | + <code class="code">open</code> determines whether or not the tooltip is currently open on the screen. |
| 59 | + It is used for conditional rendering. |
| 60 | + </p> |
| 61 | + </section> |
| 62 | + <!-- useFloating Hook --> |
| 63 | + <section class="space-y-8"> |
| 64 | + <h2 class="h2">useFloating Hook</h2> |
| 65 | + <p> |
| 66 | + The <code class="code">useFloating()</code> Hook provides positioning and context for our tooltip. |
| 67 | + We need to pass it some information: |
| 68 | + </p> |
| 69 | + <CodeBlock code={`const floating = useFloating({ /* ...settings... */ });`} lang="ts" /> |
| 70 | + <ul class="list-disc list-outside translate-x-8 space-y-4"> |
| 71 | + <li> |
| 72 | + <code class="code">open</code>: The open state from our <code class="code">useState()</code> |
| 73 | + Hook above. |
| 74 | + </li> |
| 75 | + <li> |
| 76 | + <code class="code">onOpenChange</code>: A callback function that will be called when the |
| 77 | + tooltip is opened or closed. We’ll use this to update our <code class="code">open</code> state. |
| 78 | + </li> |
| 79 | + <li> |
| 80 | + <code class="code">middleware</code>: Import and pass middleware to the array that ensure |
| 81 | + the tooltip remains on the screen, no matter where it ends up being positioned. |
| 82 | + </li> |
| 83 | + <li> |
| 84 | + <code class="code">whileElementsMounted</code>: Ensure the tooltip remains anchored to the |
| 85 | + reference element by updating the position when necessary, only while both the reference and |
| 86 | + floating elements are mounted for performance. |
| 87 | + </li> |
| 88 | + </ul> |
51 | 89 | </section> |
| 90 | + <!-- Interaction Hooks --> |
52 | 91 | <section class="space-y-8"> |
53 | | - <h2 class="h2">Open state</h2> |
54 | | - <CodeBlock code={exampleCode} lang="html" /> |
| 92 | + <h2 class="h2">Interaction Hooks</h2> |
55 | 93 | <p> |
56 | | - <code class="code">isOpen</code> determines whether or not the tooltip is currently open on the |
57 | | - screen. It is used for conditional rendering. |
| 94 | + The <code class="code">useInteractions()</code> hooks returns an object containing keys of |
| 95 | + props that enable the tooltip to be opened, closed, or accessible to screen readers. Using the |
| 96 | + <code class="code">context</code> that was returned from the Hook, call the interaction Hooks. |
58 | 97 | </p> |
| 98 | + <CodeBlock |
| 99 | + code={` |
| 100 | +const hover = useHover(floating.context); |
| 101 | +const role = useRole(floating.context, { role: 'tooltip' }); |
| 102 | +const interactions = useInteractions([hover, role]); |
| 103 | + `} |
| 104 | + lang="ts" |
| 105 | + /> |
| 106 | + <ul class="list-disc list-outside translate-x-8 space-y-4"> |
| 107 | + <li> |
| 108 | + <code class="code">useHover()</code>: adds the ability to toggle the tooltip open or closed |
| 109 | + when the reference element is hovered over. The <code class="code">move</code> option is set |
| 110 | + to false so that |
| 111 | + <code class="code">mousemove</code> events are ignored. |
| 112 | + </li> |
| 113 | + <li class="opacity-50 line-through"> |
| 114 | + COMING SOON: <code class="code">useFocus()</code>: adds the ability to toggle the tooltip |
| 115 | + open or closed when the reference element is focused. |
| 116 | + </li> |
| 117 | + <li class="opacity-50 line-through"> |
| 118 | + COMING SOON: <code class="code">useDismiss()</code>: adds the ability to dismiss the tooltip |
| 119 | + when the user presses the <kbd class="kbd">esc</kbd> key. |
| 120 | + </li> |
| 121 | + <li> |
| 122 | + <code class="code">useRole()</code>: adds the correct ARIA attributes for a |
| 123 | + <code class="code">tooltip</code> to the tooltip and reference elements. |
| 124 | + </li> |
| 125 | + </ul> |
59 | 126 | </section> |
60 | | - <!-- |
61 | | - <p> |
62 | | - First, give the floating element initial CSS styles so that it becomes an |
63 | | - absolutely-positioned element that floats on top of the UI with layout ready for being |
64 | | - measured: |
65 | | - </p> |
66 | | - <p> |
67 | | - The <code class="code">-start</code> and <code class="code">-end</code> alignments are |
68 | | - <a href="/" class="anchor">logical</a> and will adapt to the writing direction (e.g. RTL) as expected. |
69 | | - </p> |
70 | | - <div class="alert"> |
71 | | - <h3 class="h3">Note</h3> |
| 127 | + <!-- Rendering --> |
| 128 | + <section class="space-y-8"> |
| 129 | + <h2 class="h2">Rendering</h2> |
| 130 | + <p>Now we have all the variables and Hooks set up, we can render out our elements.</p> |
| 131 | + <CodeBlock |
| 132 | + lang="html" |
| 133 | + code={` |
| 134 | +<!-- Reference Element --> |
| 135 | +<button bind:this={elemReference} {...interactions.getReferenceProps()}>Hover Me</button>\n |
| 136 | +<!-- Floating Element --> |
| 137 | +<div |
| 138 | + bind:this={elemFloating} |
| 139 | + style={floating.floatingStyles} |
| 140 | + {...interactions.getFloatingProps()} |
| 141 | + class="floating" |
| 142 | +> |
| 143 | + {#if open} |
| 144 | + <div> |
| 145 | + <p>This is the floating element</p> |
| 146 | + <FloatingArrow bind:ref={elemArrow} context={floating.context} /> |
| 147 | + </div> |
| 148 | + {/if} |
| 149 | +</div> |
| 150 | + `} |
| 151 | + /> |
72 | 152 | <p> |
73 | | - You aren’t limited to just these 12 placements though. <code class="code">offset</code> allows |
74 | | - you to create any placement. |
| 153 | + <code class="code">{`{...getReferenceProps()}`}</code> and |
| 154 | + <code class="code">{`{...getFloatingProps()}`}</code> spreads the props from the interaction |
| 155 | + Hooks onto the relevant elements. They contain props like |
| 156 | + <code class="code">onMouseEnter</code>, <code class="code">aria-describedby</code>, etc. |
75 | 157 | </p> |
76 | | - </div> --> |
| 158 | + </section> |
77 | 159 | </div> |
0 commit comments