- `;
- }
-}
+#### `destroy(): void`
+
+Clean up and remove all walkthrough elements.
+
+```typescript
+tour.destroy();
```
-## Instance Methods
-
-### Navigation Methods
-
-```javascript
-// Basic navigation
-tour.start() // Start the walkthrough
-tour.next() // Go to next step
-tour.prev() // Go to previous step
-tour.goTo(index) // Jump to specific step (0-based)
-tour.finish() // Complete the walkthrough
-tour.close() // Close without completing
-tour.destroy() // Clean up and remove
-
-// Advanced navigation
-tour.restart() // Restart from beginning
-tour.pause() // Pause the walkthrough
-tour.resume() // Resume paused walkthrough
+#### `scanForAttributeSteps(): void`
+
+Scan the DOM for elements with walkthrough attributes.
+
+```typescript
+tour.scanForAttributeSteps();
```
-### State Methods
-
-```javascript
-// Current state
-tour.getCurrentStep() // Get current step object
-tour.getCurrentIndex() // Get current step index (0-based)
-tour.getTotalSteps() // Get total number of steps
-tour.getProgress() // Get progress percentage (0-100)
-
-// Status checks
-tour.isActive() // Check if walkthrough is running
-tour.isPaused() // Check if walkthrough is paused
-tour.isFinished() // Check if walkthrough completed
-tour.canNext() // Check if can go to next step
-tour.canPrev() // Check if can go to previous step
+#### `configure(config: WalkthroughConfig): void`
+
+Configure the walkthrough with steps, options, callbacks, and templates.
+
+```typescript
+tour.configure({
+ steps: [...],
+ options: {...},
+ callbacks: {...}
+});
```
-### Configuration Methods
-
-```javascript
-// Update options
-tour.setOptions(options) // Update configuration options
-tour.getOptions() // Get current options
-
-// Step management
-tour.addStep(step, index?) // Add step at index (default: end)
-tour.removeStep(index) // Remove step at index
-tour.updateStep(index, step) // Update step at index
-tour.getStep(index) // Get step at index
+### Static Helper Methods
+
+#### `walkthrough.start(steps, options?)`
+
+Quick start method.
+
+```typescript
+import { walkthrough } from '@walkthroughjs/core';
+
+walkthrough.start([
+ { element: '.header', title: 'Header' }
+], {
+ progressColor: '#667eea'
+});
```
-### Event Methods
-
-```javascript
-// Event listeners
-tour.on(event, callback) // Add event listener
-tour.off(event, callback?) // Remove event listener
-tour.emit(event, ...args) // Emit custom event
-
-// Available events
-tour.on('start', (tour) => {})
-tour.on('step', (step, index) => {})
-tour.on('next', (step, index) => {})
-tour.on('prev', (step, index) => {})
-tour.on('finish', (tour) => {})
-tour.on('close', (tour) => {})
+#### `walkthrough.fromAttributes(options?)`
+
+Create from HTML attributes.
+
+```typescript
+const tour = walkthrough.fromAttributes({
+ progressColor: '#667eea'
+});
```
-## Utility Methods
+#### `walkthrough.fromJSON(config)`
-### Element Utilities
+Create from JSON configuration.
-```javascript
-// Element helpers
-walkthrough.utils.getElement(selector) // Get DOM element
-walkthrough.utils.isVisible(element) // Check if element visible
-walkthrough.utils.scrollToElement(element) // Scroll element into view
-walkthrough.utils.getElementPosition(element) // Get element position
+```typescript
+const tour = walkthrough.fromJSON({
+ steps: [...],
+ options: {...}
+});
```
-### Storage Utilities
+## Callbacks
+
+### Event Lifecycle
-```javascript
-// Progress storage
-walkthrough.storage.save(key, data) // Save to localStorage
-walkthrough.storage.load(key) // Load from localStorage
-walkthrough.storage.remove(key) // Remove from localStorage
-walkthrough.storage.clear() // Clear all walkthrough data
+```typescript
+tour.configure({
+ callbacks: {
+ // Called when tour starts
+ onStart: () => {
+ console.log('Tour started!');
+ },
+
+ // Called on each step
+ onStep: (step, index) => {
+ console.log(`Now on step ${index + 1}: ${step.title}`);
+ analytics.track('walkthrough_step', { step: index });
+ },
+
+ // Called when tour finishes normally
+ onFinish: () => {
+ console.log('Tour completed!');
+ analytics.track('walkthrough_completed');
+ },
+
+ // Called when tour ends (finish or skip)
+ onEnd: () => {
+ console.log('Tour ended');
+ }
+ }
+});
```
-### Animation Utilities
+## Utilities
+
+The library includes several utility functions (internal use, but exported):
+
+### `easeInOut(t: number): number`
+
+Easing function for animations.
+
+### `throttle(func: T, limit: number)`
+
+Throttle function execution.
+
+### `adjustColor(color: string, amount: number): string`
+
+Adjust color brightness.
+
+### `scrollToElement(element, offset, duration, callback)`
+
+Smooth scroll to element.
+
+## TypeScript Usage Examples
+
+### Basic TypeScript Setup
+
+```typescript
+import { Walkthrough, WalkthroughOptions, WalkthroughStep } from '@walkthroughjs/core';
+
+const steps: WalkthroughStep[] = [
+ {
+ element: '#feature-1',
+ title: 'Feature 1',
+ text: 'Description of feature 1',
+ position: 'bottom'
+ },
+ {
+ element: document.querySelector('.feature-2') as HTMLElement,
+ title: 'Feature 2',
+ text: 'Description of feature 2',
+ position: 'top'
+ }
+];
+
+const options: WalkthroughOptions = {
+ progressColor: '#667eea',
+ showProgress: true,
+ keyboard: true
+};
+
+const tour = new Walkthrough(options);
+tour.configure({ steps });
+tour.start();
+```
+
+### With Full Type Safety
+
+```typescript
+import type {
+ WalkthroughConfig,
+ WalkthroughCallbacks,
+ WalkthroughStep
+} from '@walkthroughjs/core';
+
+const callbacks: WalkthroughCallbacks = {
+ onStart: () => console.log('Started'),
+ onStep: (step: WalkthroughStep, index: number) => {
+ console.log(`Step ${index}: ${step.title}`);
+ },
+ onFinish: () => console.log('Finished')
+};
+
+const config: WalkthroughConfig = {
+ steps: [
+ { element: '.step-1', title: 'Step 1' }
+ ],
+ options: {
+ progressColor: '#4CAF50'
+ },
+ callbacks
+};
+```
-```javascript
-// Animation helpers
-walkthrough.animate.fadeIn(element, duration)
-walkthrough.animate.fadeOut(element, duration)
-walkthrough.animate.slideIn(element, direction, duration)
-walkthrough.animate.slideOut(element, direction, duration)
+## Default Values
+
+All options have sensible defaults:
+
+```typescript
+{
+ overlayColor: 'rgba(0, 0, 0, 0.5)',
+ highlightPadding: 10,
+ animationDuration: 300,
+ scrollDuration: 500,
+ scrollOffset: 100,
+ zIndex: 99999,
+ popupWidth: 380,
+ popupOffset: 15,
+ popupClass: 'wt-popup',
+ showProgress: true,
+ progressColor: '#4CAF50',
+ showButtons: true,
+ showSkip: true,
+ skipText: 'Skip',
+ prevText: '← Previous',
+ nextText: 'Next →',
+ finishText: 'Finish',
+ keyboard: true,
+ escapeToExit: true,
+ arrowNavigation: true,
+ cookieName: 'walkthrough_progress',
+ cookieExpiry: 30,
+ rememberProgress: false,
+ closeOnOverlay: true,
+ autoStart: false,
+ startDelay: 0,
+ attributePrefix: 'wt',
+ stepAttribute: 'step',
+ titleAttribute: 'title',
+ textAttribute: 'text',
+ positionAttribute: 'position'
+}
```
-## Error Handling
-
-```javascript
-try {
- const tour = walkthrough.fromJSON(config);
- tour.start();
-} catch (error) {
- if (error instanceof walkthrough.WalkthroughError) {
- console.error('Walkthrough error:', error.message);
- } else {
- console.error('Unexpected error:', error);
- }
-}
-
-// Error types
-walkthrough.WalkthroughError // Base error class
-walkthrough.ConfigurationError // Configuration issues
-walkthrough.ElementNotFoundError // Target element not found
-walkthrough.ValidationError // Step validation failed
-```
\ No newline at end of file
diff --git a/README.md b/README.md
index 8f7fe96..e5b95f6 100644
--- a/README.md
+++ b/README.md
@@ -1,13 +1,15 @@
-# Walkthrough.js
+# WalkthroughJS - TypeScript Edition
-Create beautiful, interactive tutorials and onboarding experiences for your web applications with zero dependencies.
+Create beautiful, interactive tutorials and onboarding experiences for your web applications with zero dependencies. Now fully rewritten in TypeScript with modern tooling!
-[Live Demo](https://ronanarm.github.io/WalkthroughJS/demo/)
-
-  
+[](https://www.npmjs.com/package/@walkthroughjs/core)
+[](https://www.gnu.org/licenses/lgpl-3.0)
+[](https://www.typescriptlang.org/)
## ✨ Features
+- **🔷 TypeScript First** - Full type safety and IntelliSense support
+- **📦 Modern Build** - ESM and CJS support with tsup
- **🎨 Beautiful Design** - Modern, polished UI with smooth animations
- **⌨️ Keyboard Navigation** - Full support for arrow keys, Enter, and Escape
- **📱 Responsive** - Works perfectly on all screen sizes and devices
@@ -17,282 +19,277 @@ Create beautiful, interactive tutorials and onboarding experiences for your web
- **🎨 Customizable** - Colors, positions, templates, and styling options
- **⚡ Multiple Setup Methods** - HTML attributes, JSON config, or quick start
- **🧩 Custom Templates** - Complete control over popup HTML structure
+- **0️⃣ Zero Dependencies** - Lightweight and fast
-## 🚀 Quick Start
+## 📦 Installation
-### 1\. Include the Library
+### NPM (Recommended)
-#### A\. Local
-```html
-
+```bash
+npm install @walkthroughjs/core
```
-#### B\. UNPKG CDN
-```html
-
-```
+### Yarn
-#### C\. jsDelivr CDN
-```html
-
+```bash
+yarn add @walkthroughjs/core
```
-#### D\. NPM (Preferred)
+### PNPM
+
```bash
-npm install @ronanarm/walkthroughjs
+pnpm add @walkthroughjs/core
```
-### 2\. Add Data Attributes (Easiest Method)
+## 🚀 Quick Start
+
+### TypeScript/JavaScript Module
+
+```typescript
+import { walkthrough } from '@walkthroughjs/core';
+
+// Quick start method
+walkthrough.start([
+ {
+ element: '.welcome-section',
+ title: 'Welcome! 👋',
+ text: 'Let me show you around.',
+ position: 'bottom'
+ },
+ {
+ element: '#main-button',
+ title: 'Main Action',
+ text: 'Click here to get started.',
+ position: 'top'
+ }
+]);
+```
-```HTML
-
- Content to highlight
-
-
-
+### Using TypeScript Class
+
+```typescript
+import { Walkthrough, WalkthroughOptions } from '@walkthroughjs/core';
+
+const options: WalkthroughOptions = {
+ progressColor: '#667eea',
+ showProgress: true,
+ rememberProgress: true
+};
+
+const tour = new Walkthrough(options);
+
+tour.configure({
+ steps: [
+ {
+ element: '.feature-1',
+ title: 'Feature 1',
+ text: 'This is an amazing feature.'
+ }
+ ],
+ callbacks: {
+ onStart: () => console.log('Tour started!'),
+ onFinish: () => console.log('Tour completed!')
+ }
+});
+
+tour.start();
```
-### 3\. Start the Walkthrough
+### HTML Attributes Method
-```javascript
-// Start from HTML attributes
-const tour = walkthrough.fromAttributes();
-tour.start();
+```html
+
+ Content to highlight
+
+
+
+
+
```
-## 📖 Usage Methods
+## 📚 API Reference
-### Method 1: HTML Data Attributes
+### `walkthrough.start(steps, options?)`
-The simplest way to add walkthroughs. Just add data attributes to your HTML elements:
+Quick start method to create and start a walkthrough immediately.
-```HTML
-
- Dashboard Content
-
-
-
+```typescript
+walkthrough.start([
+ { element: '.header', title: 'Header', text: 'This is the header' }
+], {
+ progressColor: '#28a745',
+ showProgress: true
+});
+```
+
+### `walkthrough.fromAttributes(options?)`
+
+Creates a walkthrough from HTML data attributes.
+
+```typescript
+const tour = walkthrough.fromAttributes({
+ progressColor: '#667eea',
+ rememberProgress: false
+});
+tour.start();
+```
+
+### `walkthrough.fromJSON(config)`
+
+Creates a walkthrough from a JSON configuration object.
+
+```typescript
+const tour = walkthrough.fromJSON({
+ steps: [...],
+ options: {...},
+ callbacks: {...}
+});
+tour.start();
```
-### Method 2: JSON Configuration
-
-Use JavaScript objects for programmatic control:
-
-```javascript
-const tour = walkthrough.fromJSON({
- steps: [
- {
- element: '.header',
- title: 'Navigation',
- text: 'This is your main navigation area',
- position: 'bottom'
- },
- {
- element: '#sidebar',
- title: 'Sidebar',
- text: 'Access tools and settings here',
- position: 'right',
- nextText: 'Got it! →'
- }
- ],
- options: {
- progressColor: '#764ba2',
- highlightPadding: 15,
- animationDuration: 400
- },
- callbacks: {
- onStart: () => console.log('Tour started'),
- onFinish: () => console.log('Tour completed')
- }
-});
+### Configuration Options
+
+```typescript
+interface WalkthroughOptions {
+ // Visual
+ overlayColor?: string; // Default: 'rgba(0, 0, 0, 0.5)'
+ highlightPadding?: number; // Default: 10
+ animationDuration?: number; // Default: 300
+ progressColor?: string; // Default: '#4CAF50'
+
+ // Progress
+ showProgress?: boolean; // Default: true
-tour.start();
+ // Buttons
+ showButtons?: boolean; // Default: true
+ showSkip?: boolean; // Default: true
+ skipText?: string; // Default: 'Skip'
+ prevText?: string; // Default: '← Previous'
+ nextText?: string; // Default: 'Next →'
+ finishText?: string; // Default: 'Finish'
+
+ // Keyboard
+ keyboard?: boolean; // Default: true
+ escapeToExit?: boolean; // Default: true
+ arrowNavigation?: boolean; // Default: true
+
+ // Storage
+ rememberProgress?: boolean; // Default: false
+ cookieName?: string; // Default: 'walkthrough_progress'
+
+ // Behavior
+ closeOnOverlay?: boolean; // Default: true
+ autoStart?: boolean; // Default: false
+}
```
-### Method 3: Quick Start
-
-Perfect for rapid prototyping:
-
-```javascript
-walkthrough.start([
- {
- element: '.feature',
- title: 'New Feature',
- text: 'Check out this new feature!',
- position: 'bottom'
- }
-], {
- progressColor: '#28a745',
- onFinish: () => alert('Tour complete!')
-});
+### Step Configuration
+
+```typescript
+interface WalkthroughStep {
+ element: string | HTMLElement; // Target element
+ title?: string; // Step title
+ text?: string; // Step description
+ position?: 'top' | 'bottom' | 'left' | 'right'; // Popup position
+}
```
-## 🎛️ Configuration Options
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `progressColor` | string | `'#007bff'` | Color of the progress indicator |
-| `highlightPadding` | number | `10` | Padding around highlighted elements |
-| `animationDuration` | number | `300` | Animation duration in milliseconds |
-| `rememberProgress` | boolean | `true` | Remember user's progress in localStorage |
-| `showProgress` | boolean | `true` | Show step progress indicator |
-| `allowClose` | boolean | `true` | Allow users to close the walkthrough |
-| `backdrop` | boolean | `true` | Show backdrop overlay |
-| `backdropColor` | string | `'rgba(0,0,0,0.5)'` | Backdrop overlay color |
-
-## 📍 Position Options
-
-- `'top'` - Above the element
-- `'bottom'` - Below the element
-- `'left'` - To the left of the element
-- `'right'` - To the right of the element
-- `'center'` - Centered on screen
-
-## 🎨 Custom Templates
-
-Take full control of the popup HTML:
-
-```javascript
-const tour = walkthrough.fromJSON({
- steps: [...],
- templates: {
- popup: (step, index, total) => {
- const isLast = index === total - 1;
- return `
-
-
${step.title}
-
${step.text}
-
- ${index > 0 ? `` : ''}
-
-
-
- `;
- }
- }
-});
+### Callbacks
+
+```typescript
+tour.configure({
+ callbacks: {
+ onStart: () => console.log('Started'),
+ onStep: (step, index) => console.log(`Step ${index}`),
+ onFinish: () => console.log('Finished'),
+ onEnd: () => console.log('Ended')
+ }
+});
```
-## 🔌 Event Callbacks
-
-```javascript
-const tour = walkthrough.fromJSON({
- steps: [...],
- callbacks: {
- onStart: () => {
- console.log('Walkthrough started');
- },
- onStep: (step, index) => {
- console.log(`Now on step ${index + 1}: ${step.title}`);
- },
- onNext: (step, index) => {
- console.log('Moving to next step');
- },
- onPrev: (step, index) => {
- console.log('Moving to previous step');
- },
- onFinish: () => {
- console.log('Walkthrough completed');
- },
- onClose: () => {
- console.log('Walkthrough closed');
- }
- }
-});
+### Methods
+
+```typescript
+const tour = new Walkthrough();
+
+tour.start(); // Start the walkthrough
+tour.next(); // Go to next step
+tour.prev(); // Go to previous step
+tour.finish(); // Finish the walkthrough
+tour.end(); // End/close the walkthrough
+tour.destroy(); // Clean up and remove all elements
```
-## 🎮 API Methods
+## 🎨 Customization
-```javascript
- const tour = walkthrough.fromJSON({...});
-
-// Control methods
-tour.start(); // Start the walkthrough
-tour.next(); // Go to next step
-tour.prev(); // Go to previous step
-tour.goTo(stepIndex); // Jump to specific step
-tour.finish(); // Complete the walkthrough
-tour.close(); // Close without completing
-tour.destroy(); // Clean up and remove
-
-// State methods
-tour.getCurrentStep(); // Get current step object
-tour.getCurrentIndex(); // Get current step index
-tour.getTotalSteps(); // Get total number of steps
-tour.isActive(); // Check if walkthrough is running
+### Custom Colors
+
+```typescript
+const tour = new Walkthrough({
+ progressColor: '#667eea',
+ overlayColor: 'rgba(0, 0, 0, 0.7)'
+});
+```
+
+### Custom Templates
+
+```typescript
+tour.configure({
+ templates: {
+ popup: (step, index, total) => `
+
+
${step.title}
+
${step.text}
+
Step ${index + 1} of ${total}
+
+ `
+ }
+});
```
-## ⌨️ Keyboard Navigation
+## 🔧 Development
-- **→ / ↓** - Next step
-- **← / ↑** - Previous step
-- **Enter** - Next step
-- **Escape** - Close walkthrough
-- **Home** - Go to first step
-- **End** - Go to last step
+```bash
+# Install dependencies
+npm install
-## 🎯 HTML Data Attributes Reference
+# Development mode (watch)
+npm run dev
-| Attribute | Description | Example |
-|-----------|-------------|---------|
-| `data-wt-step` | Step number (required) | `data-wt-step="1"` |
-| `data-wt-title` | Step title | `data-wt-title="Welcome"` |
-| `data-wt-text` | Step description | `data-wt-text="This is the main menu"` |
-| `data-wt-position` | Popup position | `data-wt-position="bottom"` |
-| `data-wt-next-text` | Custom next button text | `data-wt-next-text="Continue →"` |
-| `data-wt-prev-text` | Custom previous button text | `data-wt-prev-text="← Back"` |
+# Build for production
+npm run build
-## 🌟 Examples
+# Lint
+npm run lint
-Check out the demo files for comprehensive examples of all features and configuration methods.
-- [demo-quickstart.html](/src/demo-quickstart.html)
-- [demo-attributes.html](/src/demo-attributes.html)
-- [demo-json.html](/src/demo-json.html)
-- [demo-custom-template.html](/src/demo-custom-template.html)
+# Format code
+npm run format
-## 📄 License
+# Type check
+npm run type-check
+```
-LGPL License - see [LICENSE](LICENSE.md) file for details.
+## 📝 License
+
+LGPL-3.0-or-later
## 🤝 Contributing
-Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details.
+Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+
+## 🙏 Credits
-## 📞 Support
+Originally created by Ronan Armstrong, rebuilt in TypeScript by Benjamin Rast.
-- 🐛 Issues: [GitHub Issues](https://github.com/yourusername/walkthrough-js/issues)
-- 💬 Discussions: [GitHub Discussions](https://github.com/yourusername/walkthrough-js/discussions)
diff --git a/demo/demo-typescript.html b/demo/demo-typescript.html
new file mode 100644
index 0000000..cf83d3b
--- /dev/null
+++ b/demo/demo-typescript.html
@@ -0,0 +1,305 @@
+
+
+
+
+
+ WalkthroughJS TypeScript Demo
+
+
+
+
+
+
+ WalkthroughJS
+
+
TypeScript Edition - Interactive Product Tours Made Easy
+
+
+
+
Try Different Demos
+
+
+
+
+
+
+
+
+
Key Features
+
+
+
🔷 TypeScript First
+
Full type safety with excellent IDE support and IntelliSense
+
+
+
📦 Modern Build
+
ESM and CJS support with tree-shaking capabilities
+
+
+
⌨️ Keyboard Nav
+
Arrow keys, Enter, and Escape support out of the box
+
+
+
🎨 Customizable
+
Easy theming with custom colors and templates
+
+
+
💾 Progress Tracking
+
Remember user progress across sessions
+
+
+
0️⃣ Zero Deps
+
No dependencies means smaller bundle size
+
+
+
+
+
+
Quick Example
+
+
+import { walkthrough } from '@walkthroughjs/core';
+
+// Quick start
+walkthrough.start([
+ {
+ element: '.welcome-section',
+ title: 'Welcome! 👋',
+ text: 'Let me show you around.',
+ position: 'bottom'
+ }
+]);
+
+