coderabbitai

etc/lime-elements.api.md

@@ -907,13 +907,15 @@ export namespace Components {
     export interface LimelTooltip {
         "elementId": string;
         "helperLabel"?: string;
+        "hotkey"?: string;
         "label": string;
         "maxlength"?: number;
         "openDirection": OpenDirection;
     }
     // @internal
     export interface LimelTooltipContent {
         "helperLabel"?: string;
+        "hotkey"?: string;
         "label": string;
         "maxlength"?: number;
     }
@@ -3597,6 +3599,7 @@ export namespace JSX {
     export interface LimelTooltip {
         "elementId": string;
         "helperLabel"?: string;
+        "hotkey"?: string;
         "label": string;
         "maxlength"?: number;
         "openDirection"?: OpenDirection;
@@ -3609,6 +3612,8 @@ export namespace JSX {
         // (undocumented)
         "helperLabel": string;
         // (undocumented)
+        "hotkey": string;
+        // (undocumented)
         "label": string;
         // (undocumented)
         "maxlength": number;
@@ -3619,6 +3624,7 @@ export namespace JSX {
     // @internal
     export interface LimelTooltipContent {
         "helperLabel"?: string;
+        "hotkey"?: string;
         "label": string;
         "maxlength"?: number;
     }
@@ -3628,6 +3634,8 @@ export namespace JSX {
         // (undocumented)
         "helperLabel": string;
         // (undocumented)
+        "hotkey": string;
+        // (undocumented)
         "label": string;
         // (undocumented)
         "maxlength": number;

src/components/icon-button/icon-button.tsx

@@ -95,6 +95,7 @@ export class IconButton {
         return (
             <Host onClick={this.filterClickWhenDisabled}>
                 <button
+                    aria-label={this.label}
                     disabled={this.disabled}
                     id={this.tooltipId}
                     {...buttonAttributes}

src/components/tooltip/examples/tooltip-accessibility.tsx

@@ -0,0 +1,100 @@
+import { Component, h, Host } from '@stencil/core';
+
+/**
+ * Accessibility & the accessible name
+ *
+ * A tooltip is *supplementary* information — it is **not** a substitute for
+ * an [accessible name](https://developer.mozilla.org/en-US/docs/Glossary/Accessible_name)
+ * on the trigger element. Make sure every element the tooltip is attached to
+ * already has a name that assistive technologies can read.
+ *
+ * #### How the tooltip plugs into ARIA
+ *
+ * When you place `<limel-tooltip elementId="…">` next to a trigger, the
+ * component sets
+ * [`aria-describedby`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-describedby)
+ * on the element matching that id, pointing to the tooltip's content (which
+ * carries `role="tooltip"`). This follows the [WAI-ARIA Authoring Practices
+ * for the tooltip pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/).
+ *
+ * `aria-describedby` provides a *description*, not a *name*. If the trigger
+ * has no accessible name of its own, a screen reader will announce the
+ * description but there is nothing to describe — the control is unnamed.
+ * This is an accessibility bug in the trigger, not something the tooltip can
+ * fix.
+ *
+ * #### Where the name comes from, for each kind of trigger
+ *
+ * The three triggers below show how different lime-elements components get
+ * their accessible name:
+ *
+ * 1. **`limel-icon`** — the host is what the user focuses, so `aria-label`
+ *    on the host is the name.
+ * 2. **`limel-icon-button`** — the required `label` prop is rendered as
+ *    `aria-label` on the inner `<button>`, which makes it the accessible
+ *    name. The same prop also drives the component's built-in tooltip on
+ *    hover and focus, so this trigger does not need an external
+ *    `<limel-tooltip>` attached to it — it already has one. `icon.title` is
+ *    not a name source: it describes what the icon visually depicts (e.g.
+ *    icon={{ name: 'search', title: 'Magnifying glass' }})
+ *    and is announced as supplementary content. For
+ *    decorative icons inside a labelled button, leave it unset and the icon
+ *    will be marked `aria-hidden`.
+ * 3. **`limel-button`** — the visible `label` prop is rendered as text
+ *    inside the inner `<button>`, so the name is computed automatically from
+ *    that text content.
+ *
+ * #### Rules of thumb
+ *
+ * 1. Icon-only triggers must carry their own name, even if it duplicates the
+ *    tooltip's `label`. The tooltip is a visual hint for sighted hover/focus
+ *    users; the name is what screen reader users hear as the control's
+ *    identity.
+ * 2. Triggers with visible text already have a name. Keep the tooltip
+ *    focused on supplementary info like a keyboard shortcut via `hotkey`, or
+ *    extra context via `helperLabel`.
+ * 3. Don't use a tooltip where a label belongs. If the information is
+ *    essential to operating the control, put it in the UI directly. Don't
+ *    hide it behind hover.
+ *
+ * _Inspect the triggers below in the browser's DevTools Accessibility panel
+ * to see the computed name and description._
+ */
+@Component({
+    tag: 'limel-example-tooltip-accessibility',
+    shadow: true,
+    styleUrl: 'tooltip-max-character.scss',
+})
+export class TooltipAccessibilityExample {
+    public render() {
+        return (
+            <Host>
+                <limel-icon
+                    tabIndex={0}
+                    size="small"
+                    name="search"
+                    aria-label="Search"
+                    id="tooltip-a11y-0"
+                />
+                <limel-tooltip
+                    label="Search"
+                    hotkey="ctrl+f"
+                    elementId="tooltip-a11y-0"
+                />
+                <limel-icon-button
+                    elevated={true}
+                    icon="search"
+                    label="Search"
+                    helperLabel="Find on this page"
+                    id="tooltip-a11y-1"
+                />
+                <limel-button id="tooltip-a11y-2" icon="save" label="Save" />
+                <limel-tooltip
+                    label="Persist the current draft"
+                    hotkey="meta+s"
+                    elementId="tooltip-a11y-2"
+                />
+            </Host>
+        );
+    }
+}

src/components/tooltip/examples/tooltip-basic.tsx

@@ -2,6 +2,18 @@ import { Component, h } from '@stencil/core';
 
 /**
  * Basic example
+ * In order to display the tooltip, the tooltip element and its trigger element
+ * must be within the same document or document fragment (the same `shadowRoot`).
+ * Often, it's easiest to just place them next to each other like in the example
+ * below, but if you need to, you can place them differently.
+ *
+ * Since `limel-tooltip` is absolutely positioned, it will not occupy any
+ * space in the layout.
+ *
+ * ```html
+ * <limel-button icon="search" id="tooltip-example" />
+ * <limel-tooltip label="Search" elementId="tooltip-example" />
+ * ```
  */
 @Component({
     tag: 'limel-example-tooltip-basic',
@@ -13,7 +25,7 @@ export class TooltipBasicExample {
             <limel-button icon="search" id="tooltip-example" />,
             <limel-tooltip
                 label="Search"
-                helperLabel="alt + F"
+                helperLabel="Find on this page"
                 elementId="tooltip-example"
             />,
         ];

src/components/tooltip/examples/tooltip-hotkey.tsx

@@ -0,0 +1,62 @@
+import { Component, h, Host } from '@stencil/core';
+
+/**
+ * Visualizing a keyboard shortcut
+ *
+ * Use the `hotkey` property to render a keyboard shortcut inside the tooltip,
+ * next to the `label` (and the optional `helperLabel`). The keyboard shortcut
+ * that you will define will automatically have platform-aware glyphs.
+ * For example, `meta+c` renders as <kbd>⌘</kbd> <kbd>C</kbd> on macOS and
+ * as <kbd>⊞ Win</kbd> <kbd>+</kbd> <kbd>C</kbd> on Windows.
+ *
+ * :::important
+ * The `hotkey` property is for visualization purposes only.
+ * The tooltip does **not** listen for, or handle any keyboard events
+ * on its own. Catching the key combination and running
+ * the associated action is the responsibility of the consumer of the tooltip.
+ * :::
+ *
+ * :::note
+ * 1. `meta` means the Meta key.
+ *   It is rendered as <kbd>⌘</kbd> on Apple devices, and <kbd>⊞ Win</kbd> on
+ *   Windows/Linux. (`cmd`, `command`, `win`, `windows` are aliases for `meta`.)
+ *
+ *   If you want "primary modifier" hotkeys (e.g. <kbd>⌘</kbd> on macOS and
+ *   <kbd>Ctrl</kbd> on Windows/Linux), detect OS in your application and
+ *   provide different `hotkey` values.
+ *
+ *   `ctrl` means the Control key on all platforms.
+ *
+ * 2. All browsers and operating systems have some built-in hotkeys
+ *   that may conflict with your defined hotkeys.
+ *   For example, `cmd+p` is often used to print the current page.
+ *   Make sure to choose hotkeys that do not conflict with common browser
+ *   hotkeys, and user's expected behavior.
+ * :::
+ */
+@Component({
+    tag: 'limel-example-tooltip-hotkey',
+    shadow: true,
+    styleUrl: 'tooltip-max-character.scss',
+})
+export class TooltipHotkeyExample {
+    public render() {
+        return (
+            <Host>
+                <limel-button icon="save" id="tooltip-hotkey-1" />
+                <limel-tooltip
+                    label="Save"
+                    hotkey="ctrl+s"
+                    elementId="tooltip-hotkey-1"
+                />
+                <limel-button icon="save_all" id="tooltip-hotkey-2" />
+                <limel-tooltip
+                    label="Save as"
+                    helperLabel="Save with a new name or location"
+                    hotkey="meta+shift+s"
+                    elementId="tooltip-hotkey-2"
+                />
+            </Host>
+        );
+    }
+}

src/components/tooltip/examples/tooltip-max-character.scss

@@ -1,5 +1,6 @@
-:host(limel-example-tooltip-max-character) {
+:host {
     display: flex;
     gap: 1rem;
-    justify-content: space-between;
+    align-items: center;
+    justify-content: space-around;
 }

src/components/tooltip/tooltip-content.scss

@@ -1,39 +1,46 @@
 :host(limel-tooltip-content) {
+    box-sizing: border-box;
     display: flex;
+    align-items: center;
+    gap: 0.5rem 1rem;
 
     border-radius: 0.25rem;
     padding: 0.25rem 0.5rem;
+
+    font-size: var(--limel-theme-default-font-size);
+    line-height: normal;
+
     background-color: rgb(var(--contrast-1300));
-    box-shadow: var(--shadow-depth-16);
+    box-shadow: var(--shadow-depth-16), var(--shadow-brighten-edges-inside);
 }
 
-text {
-    font-size: var(--limel-theme-default-font-size); // 14px
-    line-height: 1.25;
-    display: flex;
-    column-gap: 1rem;
-
-    &.has-column-layout {
-        display: table-cell;
-        width: fit-content;
-        max-width: min(var(--tooltip-max-width-of-text), 80vw);
-        .label {
-            padding-bottom: 0.5rem;
-        }
-        .helper-label {
-            padding-bottom: 0.25rem;
-        }
+:host(.has-column-layout) {
+    flex-direction: column;
+    align-items: flex-start;
+    padding: 0.5rem;
+
+    max-width: min(var(--tooltip-max-width-of-text), 80vw);
+
+    .label,
+    .helper-label {
+        flex-grow: 1;
     }
 }
 
+.label,
+.helper-label {
+    min-width: 0;
+    min-height: 0;
+}
+
 .label {
     color: rgb(var(--contrast-200));
 }
 
 .helper-label {
     color: rgb(var(--contrast-800));
+}
 
-    &:empty {
-        display: none;
-    }
+limel-hotkey {
+    margin-right: -0.25rem;
 }

src/components/tooltip/tooltip-content.tsx

@@ -1,4 +1,5 @@
-import { Component, h, Prop } from '@stencil/core';
+import { Component, h, Host, Prop } from '@stencil/core';
+import { normalizeHotkeyString } from '../../util/hotkeys';
 
 /**
  * This component is used internally by `limel-tooltip`.
@@ -29,25 +30,53 @@ export class TooltipContent {
     @Prop({ reflect: true })
     maxlength?: number;
 
+    /**
+     * Read more in tooltip.tsx
+     */
+    @Prop({ reflect: true })
+    hotkey?: string;
+
     public render() {
         let isLabelsTextLong = false;
         if (this.helperLabel && this.maxlength) {
             isLabelsTextLong =
                 this.label.length + this.helperLabel.length > this.maxlength;
         }
 
-        const props: any = {};
-        if (this.maxlength) {
-            props.style = {
-                '--tooltip-max-width-of-text': `${this.maxlength}` + 'ch',
-            };
-        }
+        const style = this.maxlength
+            ? { '--tooltip-max-width-of-text': `${this.maxlength}ch` }
+            : undefined;
 
-        return [
-            <text class={{ 'has-column-layout': isLabelsTextLong }} {...props}>
+        return (
+            <Host
+                class={{ 'has-column-layout': isLabelsTextLong }}
+                style={style}
+            >
                 <div class="label">{this.label}</div>
-                <div class="helper-label">{this.helperLabel}</div>
-            </text>,
-        ];
+                {this.renderHelperLabel()}
+                {this.renderHotkey()}
+            </Host>
+        );
+    }
+
+    private renderHelperLabel() {
+        if (!this.helperLabel) {
+            return;
+        }
+
+        return <div class="helper-label">{this.helperLabel}</div>;
+    }
+
+    private renderHotkey() {
+        if (!this.hotkey) {
+            return;
+        }
+
+        const normalized = normalizeHotkeyString(this.hotkey);
+        if (!normalized) {
+            return;
+        }
+
+        return <limel-hotkey value={normalized} />;
     }
 }