npm package: @piikeep/web-help
Description: A comprehensive, headless help system for React applications. Built with TypeScript for maximum flexibility.
Author: Charles de Jager
Latest version: 0.3.0

# 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):

```bash
npm install
```

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

```bash
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:

```bash
npm install buffer
```

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

```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:

```tsx
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:

```tsx
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:

```css
: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:

```tsx
<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:

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

## Development

Run the dev server:

```bash
npm run dev
```

Build for production:

```bash
npm run build
```

Preview the production build:

```bash
npm run preview
```

Lint the code:

```bash
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 <charles.de.jager@piikeep.pw>