PIIKeep Web Help

A small TypeScript React component library and utilities to add contextual help to React apps. Built with Vite, ESLint, and TypeScript. Intended to provide a provider, UI components and hooks to show contextual help, tooltips, and guided help flows.

Features

• TypeScript-first React components and hooks
• Lightweight, framework-agnostic styles (customizable)
• Integrates with existing component libraries
• Vite-based development server and build

Install

For local development (this repo):

npm install

To publish/use as a package, add as a dependency:

npm install @piikeep/web-help
# or
yarn add @piikeep/web-help

Browser Environment Setup

When using manifest-based content loading in the browser, you need to include a Buffer polyfill for the gray-matter library:

npm install buffer

Then add this to your application entry point (e.g., main.tsx):

// Polyfill Buffer for gray-matter library
import { Buffer } from 'buffer';
globalThis.Buffer = Buffer;

This is required for parsing Markdown frontmatter in browser environments.

Usage

Basic Setup

Example usage in a React + TypeScript app:

import React from 'react';
import { createRoot } from 'react-dom/client';
import { HelpProvider, HelpTrigger, useHelp } from '@piikeep/web-help';

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

function Main() {
  const { openHelp } = useHelp();

  return (
    <>
      <h1>My App</h1>
      <button onClick={() => openHelp('getting-started')}>Help</button>
      <HelpTrigger id='getting-started'>
        <p>Tips and guidance for getting started...</p>
      </HelpTrigger>
    </>
  );
}

createRoot(document.getElementById('root')!).render(<App />);

Styling

The library is completely headless and provides no default styling. You have three options:

Option 1: Use Baseline CSS (Recommended for Getting Started)

Import the provided baseline stylesheet for a ready-to-use design:

import '@piikeep/web-help/baseline.css';

The baseline CSS includes:

• Semantic CSS variables for easy theming (colors, spacing, shadows, etc.)
• Dark mode support via [data-theme='dark']
• Responsive layouts for mobile and desktop
• All help component styles (navigation, search, breadcrumbs, pagination, etc.)

Customize the theme by overriding CSS variables:

:root {
  --help-color-primary: #ff6b6b;
  --help-color-primary-hover: #ff5252;
  --help-radius-md: 12px;
  /* See baseline.css for all available variables */
}

Option 2: Bring Your Own Styles

All components use semantic class names and data attributes:

<div className='help-page' data-loading={isLoading}>
  <nav className='help-navigation'>
    <button className='help-nav-button' data-active={isActive}>
      {/* Your content */}
    </button>
  </nav>
</div>

Style with your preferred approach (Tailwind, CSS-in-JS, CSS Modules, etc.).

Option 3: Use Tailwind or Other Utility Classes

Pass className props to override default classes:

<HelpPage
  className='flex gap-4 p-8'
  sidebarClassName='w-64 border-r'
  mainClassName='flex-1'
/>

Development

Run the dev server:

npm run dev

Build for production:

npm run build

Preview the production build:

npm run preview

Lint the code:

npm run lint

Project structure (example)

• src/ — source components and hooks
• dist/ — build output (after npm run build)
• public/ — static assets
• package.json — scripts and dependencies
• tsconfig.json — TypeScript config
• .eslintrc.* — ESLint config

Contributing

• Open an issue for feature requests or bugs.
• Fork, make changes on a feature branch, run lint/build, and submit a PR.
• Follow existing code style and add unit tests for new features.

Security Considerations

This library uses gray-matter for parsing frontmatter in markdown files. Gray-matter uses eval internally for YAML parsing. This is safe when:

• Processing trusted markdown content from your own codebase
• Using the CLI tools to generate content
• Not parsing user-submitted markdown in production

For user-generated content, implement server-side validation and sanitization.

License

MIT — see LICENSE file.

Author

Charles de Jager [email protected]