feat(tooltip): add toggletip support with click-to-toggle behavior

packages/tooltip/README.md

@@ -47,6 +47,55 @@ const Tooltip = () => {
 };
 ```
 
+#### Toggletip Usage
+
+Toggletips provide click-to-toggle behavior following accessibility best practices:
+
+```jsx
+import { useTooltip } from '@zendeskgarden/container-tooltip';
+
+const Toggletip = () => {
+  const triggerRef = useRef(null);
+  const { isVisible, isAnnouncementReady, getTooltipProps, getTriggerProps } = useTooltip({
+    isToggletip: true,
+    triggerRef
+  });
+
+  const styles = {
+    background: '#1f73b7',
+    padding: '10px',
+    margin: '6px 0',
+    color: '#fff'
+  };
+
+  return (
+    <>
+      <div {...getTooltipProps({ style: styles })}>
+        {isAnnouncementReady && 'Toggletip content'}
+      </div>
+      <button {...getTriggerProps()}>Trigger</button>
+    </>
+  );
+};
+```
+
+**Key differences from tooltips:**
+
+- Opens/closes on click, not hover
+- Closes on outside clicks and Escape key
+- Trigger must be a button element with an accessible name (visible text or `aria-label`) so
+  keyboard and screen reader users can interact with it as expected
+- Uses `role="status"` for live region announcements
+- Use `isAnnouncementReady` to control when content is populated for screen reader
+  re-announcements
+
+**Content recommendations:**
+
+Toggletip content should ideally be text-only. When the toggletip opens, screen readers announce
+the text content via the `role="status"` live region. If the content includes interactive elements
+(buttons, links) or complex markup, screen readers will only announce the text portion. For complex
+interactive content, consider using a popover or dialog pattern instead.
+
 ### TooltipContainer
 
 ```jsx

packages/tooltip/demo/~patterns/patterns.stories.tsx

@@ -9,6 +9,7 @@ import React from 'react';
 import type { Meta, StoryObj } from '@storybook/react';
 import { FocusStory } from './stories/FocusStory';
 import { MenuStory } from './stories/MenuStory';
+import { ToggletipStory } from './stories/ToggletipStory';
 
 const meta: Meta = { title: 'Packages/Tooltip/[patterns]' };
 
@@ -23,3 +24,8 @@ export const Menu: StoryObj<typeof MenuStory> = {
   render: args => <MenuStory {...args} />,
   name: 'Menu'
 };
+
+export const Toggletip: StoryObj<typeof ToggletipStory> = {
+  render: args => <ToggletipStory {...args} />,
+  name: 'Toggletip'
+};

packages/tooltip/demo/~patterns/stories/ToggletipStory.tsx

@@ -0,0 +1,50 @@
+/**
+ * Copyright Zendesk, Inc.
+ *
+ * Use of this source code is governed under the Apache License, Version 2.0
+ * found at http://www.apache.org/licenses/LICENSE-2.0.
+ */
+
+import React, { useRef } from 'react';
+import { StoryFn } from '@storybook/react';
+import classNames from 'classnames';
+import { useTooltip } from '@zendeskgarden/container-tooltip';
+
+export const ToggletipStory: StoryFn = () => {
+  const triggerRef = useRef<HTMLButtonElement>(null);
+  const { getTooltipProps, getTriggerProps, isVisible, isAnnouncementReady } = useTooltip({
+    triggerRef,
+    isToggletip: true
+  });
+
+  return (
+    <div className="relative">
+      <span
+        className={classNames(
+          'absolute',
+          '-top-24',
+          'start-2',
+          'bg-grey-800',
+          'inline-block',
+          'mb-1',
+          'px-4',
+          'py-2',
+          'rounded-sm',
+          'text-sm',
+          'text-white',
+          isVisible ? 'visible' : 'invisible'
+        )}
+        {...getTooltipProps()}
+      >
+        {isAnnouncementReady ? 'Use this space to provide more context for your users.' : null}
+      </span>
+      <button
+        className="bg-grey-200 border border-solid cursor-pointer px-3 py-2 rounded"
+        {...getTriggerProps()}
+        type="button"
+      >
+        More information
+      </button>
+    </div>
+  );
+};