@elsapiens/help

Components for in-app help, documentation, and keyboard shortcuts.

Installation

npm install @elsapiens/help @elsapiens/ui @elsapiens/utils @elsapiens/providers
# or
pnpm add @elsapiens/help @elsapiens/ui @elsapiens/utils @elsapiens/providers

Features

• Help icons and tooltips
• Side panel with help content
• Help topic search
• Keyboard shortcuts reference panel
• Markdown content support

Usage

HelpIcon

Trigger help for specific topics:

import { HelpIcon } from '@elsapiens/help';

// Basic usage
<label>
  Email <HelpIcon topicId="form-email" />
</label>

// With custom size
<HelpIcon topicId="getting-started" size="lg" />

// With position
<HelpIcon topicId="feature-x" position="left" />

Props:

| Prop | Type | Default | Description | |------|------|---------|-------------| | topicId | string | - | Help topic ID | | size | 'sm' \| 'md' \| 'lg' | 'md' | Icon size | | position | string | 'right' | Popover position | | className | string | - | Additional classes |

HelpTooltip

Show help content in a tooltip:

import { HelpTooltip } from '@elsapiens/help';

<HelpTooltip topicId="api-key">
  <span>API Key</span>
</HelpTooltip>

// With custom content
<HelpTooltip
  content="Your API key is used for authentication"
  learnMoreUrl="/docs/api-keys"
>
  <InfoIcon />
</HelpTooltip>

Props:

| Prop | Type | Default | Description | |------|------|---------|-------------| | topicId | string | - | Help topic ID | | content | string | - | Custom content | | learnMoreUrl | string | - | Documentation link | | children | ReactNode | - | Trigger element |

HelpPanel

Side panel for detailed help content:

import { HelpPanel } from '@elsapiens/help';
import { useHelp } from '@elsapiens/providers';

function App() {
  const { isOpen, closeHelp, currentTopic } = useHelp();

  return (
    <>
      <MainContent />
      <HelpPanel
        isOpen={isOpen}
        onClose={closeHelp}
        topic={currentTopic}
      />
    </>
  );
}

Props:

| Prop | Type | Default | Description | |------|------|---------|-------------| | isOpen | boolean | - | Panel visibility | | onClose | function | - | Close handler | | topic | HelpTopic | - | Current topic | | position | 'left' \| 'right' | 'right' | Panel position | | width | string | '400px' | Panel width |

HelpSearch

Search interface for help topics:

import { HelpSearch } from '@elsapiens/help';

<HelpSearch
  onSelect={(topic) => openHelpPanel(topic)}
  placeholder="Search help..."
/>

// With categories filter
<HelpSearch
  categories={['getting-started', 'features']}
  onSelect={handleSelect}
/>

Props:

| Prop | Type | Default | Description | |------|------|---------|-------------| | onSelect | function | - | Topic selection handler | | placeholder | string | 'Search...' | Input placeholder | | categories | string[] | - | Filter by categories | | maxResults | number | 10 | Maximum results | | className | string | - | Additional classes |

ShortcutHelpPanel

Display keyboard shortcuts reference:

import { ShortcutHelpPanel } from '@elsapiens/help';

// Basic usage
<ShortcutHelpPanel />

// With custom trigger
<ShortcutHelpPanel
  trigger={<Button>Keyboard Shortcuts</Button>}
/>

// Filtered by category
<ShortcutHelpPanel categories={['navigation', 'editing']} />

Props:

| Prop | Type | Default | Description | |------|------|---------|-------------| | trigger | ReactNode | - | Custom trigger element | | categories | string[] | - | Filter categories | | className | string | - | Additional classes |

Registering Help Topics

import { HelpProvider, useHelp } from '@elsapiens/providers';

// In your app setup
function App() {
  const { registerTopic } = useHelp();

  useEffect(() => {
    registerTopic({
      id: 'getting-started',
      title: 'Getting Started',
      summary: 'Learn the basics of using the application',
      content: `
# Getting Started

Welcome to our application! This guide will help you get started.

## First Steps

1. Create your account
2. Set up your profile
3. Explore the dashboard

## Need Help?

Contact support at [email protected]
      `,
      category: 'basics',
      tags: ['intro', 'tutorial', 'beginner'],
    });
  }, []);

  return <YourApp />;
}

Complete Example

import {
  HelpIcon,
  HelpTooltip,
  HelpPanel,
  HelpSearch,
  ShortcutHelpPanel,
} from '@elsapiens/help';
import { HelpProvider, useHelp } from '@elsapiens/providers';
import { Button } from '@elsapiens/ui';

function App() {
  return (
    <HelpProvider>
      <MainApp />
    </HelpProvider>
  );
}

function MainApp() {
  const { isOpen, closeHelp, openHelp, currentTopic } = useHelp();

  return (
    <div className="flex">
      {/* Main content */}
      <main className="flex-1 p-6">
        {/* Form with help */}
        <form>
          <div className="mb-4">
            <label className="flex items-center gap-2">
              API Key
              <HelpIcon topicId="api-key" />
            </label>
            <input type="text" />
          </div>

          <div className="mb-4">
            <HelpTooltip topicId="webhook-url">
              <label>Webhook URL</label>
            </HelpTooltip>
            <input type="url" />
          </div>
        </form>

        {/* Help search in header */}
        <header className="flex justify-between">
          <HelpSearch onSelect={(topic) => openHelp(topic.id)} />
          <ShortcutHelpPanel />
        </header>
      </main>

      {/* Help panel */}
      <HelpPanel
        isOpen={isOpen}
        onClose={closeHelp}
        topic={currentTopic}
      />
    </div>
  );
}

Help Topic Type

interface HelpTopic {
  id: string;
  title: string;
  summary: string;        // Short description for tooltips
  content?: string;       // Full markdown content
  category?: string;
  tags?: string[];
  relatedTopics?: string[];
  externalLinks?: {
    label: string;
    url: string;
  }[];
}

License

MIT