@burdenoff/microfe-tours 2026.510.112

package/README.md

@@ -0,0 +1,342 @@
+# @burdenoff/microfe-tours
+
+> Product tours and interactive onboarding system for the Burdenoff platform
+
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue.svg)](https://www.typescriptlang.org/)
+[![React](https://img.shields.io/badge/React-19-61dafb.svg)](https://reactjs.org/)
+[![Vite](https://img.shields.io/badge/Vite-7-646cff.svg)](https://vitejs.dev/)
+
+## Overview
+
+The Tours microfrontend provides tools for creating interactive product tours and onboarding experiences. Build step-by-step guides, schedule tours for specific user segments, track engagement, and improve user adoption with data-driven insights.
+
+**Port:** `5155`
+**Module Type:** Tenant Module
+**API Gateway:** Port 4013
+
+## Features
+
+- **Tour Builder**
+  - Visual tour editor
+  - Drag-and-drop step sequencing
+  - Multi-step tours
+  - Branching logic
+  - Target element selection
+  - Position customization
+
+- **Step Types**
+  - Tooltip - Point to UI elements
+  - Modal - Full-screen overlay
+  - Highlight - Spotlight elements
+  - Announcement - Feature announcements
+  - Video - Embedded videos
+  - Custom - HTML content
+
+- **Media Library**
+  - Upload images and videos
+  - Media management
+  - Screenshot capture
+  - GIF support
+  - CDN integration
+
+- **Scheduling**
+  - Schedule tours for specific times
+  - Target user segments
+  - Trigger conditions
+  - Recurring schedules
+  - Time zone support
+
+- **Templates**
+  - Pre-built tour templates
+  - Industry-specific templates
+  - Clone and customize
+  - Template marketplace
+  - Version control
+
+- **Analytics**
+  - Tour completion rates
+  - Step-by-step analytics
+  - Drop-off points
+  - Time spent per step
+  - User engagement metrics
+  - A/B testing results
+
+## Installation
+
+```bash
+# Install dependencies
+bun install
+
+# Generate GraphQL types
+bun run codegen
+```
+
+## Development
+
+```bash
+# Start development server (port 5155)
+bun run dev
+
+# Run linter
+bun run lint
+
+# Format code
+bun run format
+
+# Type check
+bun run type:check
+
+# Build for production
+bun run build
+
+# Run all quality checks
+bun run sanity
+```
+
+## Project Structure
+
+```
+src/
+├── dev/                      # Development harness
+├── tours/                    # Main module
+│   ├── components/          # React components
+│   │   └── ui.tsx           # UI components
+│   ├── graphql/            # GraphQL operations
+│   │   └── operations/      # Queries/Mutations
+│   ├── hooks/              # Custom React hooks
+│   │   ├── useMediaLibrary.ts
+│   │   ├── useStepSequencer.ts
+│   │   ├── useTourAnalytics.ts
+│   │   ├── useTourBuilder.ts
+│   │   ├── useTourPreview.ts
+│   │   └── useToursList.ts
+│   ├── pages/              # Page components
+│   │   ├── AnalyticsDashboardPage.tsx
+│   │   ├── MediaLibraryPage.tsx
+│   │   ├── SchedulerPage.tsx
+│   │   ├── StepEditorPage.tsx
+│   │   ├── TemplateLibraryPage.tsx
+│   │   ├── TourBuilderPage.tsx
+│   │   ├── TourPreviewPage.tsx
+│   │   └── ToursListPage.tsx
+│   ├── providers/          # Context providers
+│   ├── store/              # State management
+│   ├── types/              # TypeScript types
+│   ├── utils/              # Utility functions
+│   └── README.md          # Module documentation
+```
+
+## GraphQL Operations
+
+### Queries
+- `getTours` - List all tours
+- `getTour` - Get tour details
+- `getTourAnalytics` - Get analytics data
+- `getTourTemplates` - List templates
+- `getTourMedia` - List media files
+
+### Mutations
+- `createTour` - Create new tour
+- `updateTour` - Update tour configuration
+- `deleteTour` - Remove a tour
+- `createTourFromTemplate` - Create from template
+- `syncTourSteps` - Update step sequence
+- `createTourMedia` - Upload media
+- `attachMediaToStep` - Attach media to step
+- `createTourSchedule` - Schedule tour
+
+## Configuration
+
+### Environment Variables
+
+```env
+VITE_API_GATEWAY_URL=http://localhost:4013/graphql
+VITE_TENANT_ID=your-tenant-id
+VITE_WORKSPACE_ID=your-workspace-id
+```
+
+### Integration with Shell
+
+```tsx
+import { ToursRoot } from '@burdenoff/microfe-tours';
+
+function App() {
+  return (
+    <ToursRoot
+      basePath="/tours"
+      navigate={navigate}
+      apiGatewayUrl="http://localhost:4013/graphql"
+      workspaceId="workspace-123"
+      currentUser={{
+        id: 'user-1',
+        email: 'admin@example.com',
+        firstName: 'Admin',
+        lastName: 'User',
+      }}
+    />
+  );
+}
+```
+
+## Tour Configuration
+
+### Basic Tour Structure
+```typescript
+{
+  name: "Welcome Tour",
+  description: "Onboarding for new users",
+  status: "PUBLISHED",
+  steps: [
+    {
+      title: "Welcome!",
+      content: "Let's get you started",
+      type: "modal",
+      order: 0
+    },
+    {
+      title: "Dashboard",
+      content: "This is your dashboard",
+      type: "tooltip",
+      target: "#dashboard",
+      position: "bottom",
+      order: 1
+    }
+  ]
+}
+```
+
+### Step Configuration
+```typescript
+{
+  title: "Step Title",
+  content: "Step description (supports HTML)",
+  type: "tooltip" | "modal" | "highlight",
+  target: "#element-selector",
+  position: "top" | "bottom" | "left" | "right",
+  primaryButton: {
+    text: "Next",
+    action: "next"
+  },
+  secondaryButton: {
+    text: "Skip",
+    action: "skip"
+  }
+}
+```
+
+## Tour Statuses
+
+- **Draft** - Being created/edited
+- **Published** - Live and active
+- **Archived** - No longer active
+- **Scheduled** - Will activate at scheduled time
+
+## Trigger Conditions
+
+Tours can be triggered by:
+- **Page Load** - Show on specific page
+- **Element Click** - Trigger on button click
+- **Time Delay** - Show after X seconds
+- **User Segment** - Target specific users
+- **Feature Flag** - Show when feature enabled
+- **Custom Event** - Custom JavaScript event
+
+## User Targeting
+
+Target tours to specific users:
+- New users (first login)
+- Role-based (admin, user, etc.)
+- Plan-based (free, pro, enterprise)
+- Location-based (country, timezone)
+- Custom attributes
+
+## Analytics Metrics
+
+| Metric | Description | Good Benchmark |
+|--------|-------------|----------------|
+| **Start Rate** | % who started tour | >40% |
+| **Completion Rate** | % who finished tour | >60% |
+| **Avg. Time** | Time to complete | 2-5 minutes |
+| **Drop-off Rate** | % who quit early | <30% |
+| **Skip Rate** | % who skipped steps | <20% |
+
+## Best Practices
+
+1. **Keep it Short**
+   - 3-7 steps ideal
+   - Under 5 minutes total
+   - One concept per step
+
+2. **Clear Navigation**
+   - Always show progress (Step 2 of 5)
+   - Provide "Skip" option
+   - Allow "Previous" navigation
+
+3. **Visual Elements**
+   - Use screenshots/GIFs
+   - Highlight important areas
+   - Keep text concise
+
+4. **Timing**
+   - Don't interrupt critical tasks
+   - Show at natural breakpoints
+   - Allow users to defer
+
+5. **Mobile Optimization**
+   - Test on mobile devices
+   - Use responsive positioning
+   - Simplify for small screens
+
+## Available Scripts
+
+| Script | Description |
+|--------|-------------|
+| `bun run dev` | Start development server |
+| `bun run build` | Build for production |
+| `bun run lint` | Run ESLint |
+| `bun run format` | Format with Prettier |
+| `bun run type:check` | TypeScript type checking |
+| `bun run codegen` | Generate GraphQL types |
+| `bun run sanity` | Run all quality checks |
+
+## Technology Stack
+
+- **Framework:** React 19 with TypeScript 5.9
+- **Build Tool:** Vite 7
+- **State Management:** Zustand 5
+- **GraphQL Client:** Apollo Client (planned)
+- **Styling:** Tailwind CSS v4
+- **UI Components:** Radix UI
+- **Icons:** Lucide React
+- **Routing:** React Router DOM 7
+
+## Use Cases
+
+- **User Onboarding** - Guide new users through key features
+- **Feature Announcements** - Introduce new features
+- **Product Updates** - Highlight changes and improvements
+- **Training** - Educate users on complex workflows
+- **Best Practices** - Share tips and tricks
+- **Compliance** - Guide through regulatory requirements
+
+## Template Categories
+
+- **Onboarding** - Welcome new users
+- **Feature Discovery** - Highlight features
+- **Workflow Guides** - Step-by-step processes
+- **Tips & Tricks** - Power user features
+- **Updates** - What's new announcements
+
+## Roadmap
+
+- [ ] A/B testing for tours
+- [ ] Interactive elements (forms, quizzes)
+- [ ] Advanced branching logic
+- [ ] Tour versioning
+- [ ] Multi-language support
+- [ ] Video tours
+- [ ] Voice-over support
+
+## License
+
+Proprietary - Copyright © 2025 Burdenoff Consultancy Services Pvt. Ltd.

package/dist/__tests__/setup.d.ts

@@ -0,0 +1,2 @@
+
+//# sourceMappingURL=setup.d.ts.map

package/dist/__tests__/setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../src/__tests__/setup.ts"],"names":[],"mappings":"AAAA,OAAO,2BAA2B,CAAC"}

package/dist/constants/featureFlags.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Tours feature flag keys.
+ *
+ * INVARIANT: keys here must match entries in `DEFAULT_PLATFORM_FLAGS` at
+ * `global-tenant-svc/src/modules/feature-flag/services/feature-flag.service.ts`.
+ * If a key is added/removed/renamed here, the backend seed must mirror the
+ * change (and vice versa) — otherwise the frontend falls through to the
+ * provider's `defaultEnabled` and the flag appears broken.
+ *
+ * Only genuinely incomplete features should have a flag. Features that are
+ * 100% E2E complete and stable must NOT be gated.
+ */
+export declare const TOURS_FEATURES: {
+    /** Gates the stable user-facing My Tours and My Progress surface. */
+    readonly USER: "tours.user";
+    /**
+     * Gates the Media Library page and its CRUD. The feature is Partial —
+     * `useMediaLibrary.uploadMedia` currently writes a hardcoded `storageUrl`
+     * because the real upload pipeline (S3/Ceph/pre-signed URL) is not yet
+     * implemented. The flag must remain until the pipeline lands.
+     */
+    readonly MEDIA: "tours.media";
+};
+export type ToursFeatureKey = (typeof TOURS_FEATURES)[keyof typeof TOURS_FEATURES];
+//# sourceMappingURL=featureFlags.d.ts.map

package/dist/constants/featureFlags.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"featureFlags.d.ts","sourceRoot":"","sources":["../../src/constants/featureFlags.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,cAAc;IACzB,qEAAqE;;IAErE;;;;;OAKG;;CAEK,CAAC;AAEX,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,OAAO,cAAc,CAAC,CAAC"}

package/dist/constants/featureFlags.js

@@ -0,0 +1,9 @@
+//#region src/constants/featureFlags.ts
+var e = {
+	USER: "tours.user",
+	MEDIA: "tours.media"
+};
+//#endregion
+export { e as TOURS_FEATURES };
+
+//# sourceMappingURL=featureFlags.js.map

package/dist/constants/featureFlags.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"featureFlags.js","names":[],"sources":["../../src/constants/featureFlags.ts"],"sourcesContent":["/**\n * Tours feature flag keys.\n *\n * INVARIANT: keys here must match entries in `DEFAULT_PLATFORM_FLAGS` at\n * `global-tenant-svc/src/modules/feature-flag/services/feature-flag.service.ts`.\n * If a key is added/removed/renamed here, the backend seed must mirror the\n * change (and vice versa) — otherwise the frontend falls through to the\n * provider's `defaultEnabled` and the flag appears broken.\n *\n * Only genuinely incomplete features should have a flag. Features that are\n * 100% E2E complete and stable must NOT be gated.\n */\nexport const TOURS_FEATURES = {\n  /** Gates the stable user-facing My Tours and My Progress surface. */\n  USER: 'tours.user',\n  /**\n   * Gates the Media Library page and its CRUD. The feature is Partial —\n   * `useMediaLibrary.uploadMedia` currently writes a hardcoded `storageUrl`\n   * because the real upload pipeline (S3/Ceph/pre-signed URL) is not yet\n   * implemented. The flag must remain until the pipeline lands.\n   */\n  MEDIA: 'tours.media',\n} as const;\n\nexport type ToursFeatureKey = (typeof TOURS_FEATURES)[keyof typeof TOURS_FEATURES];\n"],"mappings":";AAYA,IAAa,IAAiB;CAE5B,MAAM;CAON,OAAO;CACR"}

package/dist/constants/permissions.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Tours Permission Constants
+ *
+ * All permission strings for Tours resources.
+ * Use with fe-libs usePermissions hook: hasPermission(TOUR_PERMISSIONS.TOUR_CREATE)
+ *
+ * Resource types:
+ * - tour: list, read, create, update, delete, publish, archive, duplicate
+ * - tour-step: list, read, create, update, delete
+ * - tour-media: list, read, create, update, delete
+ * - tour-template: list, read, use
+ * - tour-analytics: list, read
+ * - tour-schedule: list, read, create, update, delete
+ */
+export declare const TOUR_PERMISSIONS: {
+    readonly TOUR_LIST: "tour:list";
+    readonly TOUR_READ: "tour:read";
+    readonly TOUR_CREATE: "tour:create";
+    readonly TOUR_UPDATE: "tour:update";
+    readonly TOUR_DELETE: "tour:delete";
+    readonly TOUR_PUBLISH: "tour:publish";
+    readonly TOUR_ARCHIVE: "tour:archive";
+    readonly TOUR_DUPLICATE: "tour:duplicate";
+    readonly TOUR_STEP_LIST: "tour-step:list";
+    readonly TOUR_STEP_READ: "tour-step:read";
+    readonly TOUR_STEP_CREATE: "tour-step:create";
+    readonly TOUR_STEP_UPDATE: "tour-step:update";
+    readonly TOUR_STEP_DELETE: "tour-step:delete";
+    readonly TOUR_MEDIA_LIST: "tour-media:list";
+    readonly TOUR_MEDIA_READ: "tour-media:read";
+    readonly TOUR_MEDIA_CREATE: "tour-media:create";
+    readonly TOUR_MEDIA_UPDATE: "tour-media:update";
+    readonly TOUR_MEDIA_DELETE: "tour-media:delete";
+    readonly TOUR_TEMPLATE_CREATE: "tour-template:create";
+    readonly TOUR_TEMPLATE_LIST: "tour-template:list";
+    readonly TOUR_TEMPLATE_READ: "tour-template:read";
+    readonly TOUR_TEMPLATE_USE: "tour-template:use";
+    readonly TOUR_TEMPLATE_UPDATE: "tour-template:update";
+    readonly TOUR_TEMPLATE_DELETE: "tour-template:delete";
+    readonly TOUR_ANALYTICS_LIST: "tour-analytics:list";
+    readonly TOUR_ANALYTICS_READ: "tour-analytics:read";
+    readonly TOUR_SCHEDULE_LIST: "tour-schedule:list";
+    readonly TOUR_SCHEDULE_READ: "tour-schedule:read";
+    readonly TOUR_SCHEDULE_CREATE: "tour-schedule:create";
+    readonly TOUR_SCHEDULE_UPDATE: "tour-schedule:update";
+    readonly TOUR_SCHEDULE_DELETE: "tour-schedule:delete";
+};
+export type TourPermission = (typeof TOUR_PERMISSIONS)[keyof typeof TOUR_PERMISSIONS];
+//# sourceMappingURL=permissions.d.ts.map

package/dist/constants/permissions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions.d.ts","sourceRoot":"","sources":["../../src/constants/permissions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2CnB,CAAC;AAEX,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,OAAO,gBAAgB,CAAC,CAAC"}

package/dist/constants/permissions.js

@@ -0,0 +1,38 @@
+//#region src/constants/permissions.ts
+var e = {
+	TOUR_LIST: "tour:list",
+	TOUR_READ: "tour:read",
+	TOUR_CREATE: "tour:create",
+	TOUR_UPDATE: "tour:update",
+	TOUR_DELETE: "tour:delete",
+	TOUR_PUBLISH: "tour:publish",
+	TOUR_ARCHIVE: "tour:archive",
+	TOUR_DUPLICATE: "tour:duplicate",
+	TOUR_STEP_LIST: "tour-step:list",
+	TOUR_STEP_READ: "tour-step:read",
+	TOUR_STEP_CREATE: "tour-step:create",
+	TOUR_STEP_UPDATE: "tour-step:update",
+	TOUR_STEP_DELETE: "tour-step:delete",
+	TOUR_MEDIA_LIST: "tour-media:list",
+	TOUR_MEDIA_READ: "tour-media:read",
+	TOUR_MEDIA_CREATE: "tour-media:create",
+	TOUR_MEDIA_UPDATE: "tour-media:update",
+	TOUR_MEDIA_DELETE: "tour-media:delete",
+	TOUR_TEMPLATE_CREATE: "tour-template:create",
+	TOUR_TEMPLATE_LIST: "tour-template:list",
+	TOUR_TEMPLATE_READ: "tour-template:read",
+	TOUR_TEMPLATE_USE: "tour-template:use",
+	TOUR_TEMPLATE_UPDATE: "tour-template:update",
+	TOUR_TEMPLATE_DELETE: "tour-template:delete",
+	TOUR_ANALYTICS_LIST: "tour-analytics:list",
+	TOUR_ANALYTICS_READ: "tour-analytics:read",
+	TOUR_SCHEDULE_LIST: "tour-schedule:list",
+	TOUR_SCHEDULE_READ: "tour-schedule:read",
+	TOUR_SCHEDULE_CREATE: "tour-schedule:create",
+	TOUR_SCHEDULE_UPDATE: "tour-schedule:update",
+	TOUR_SCHEDULE_DELETE: "tour-schedule:delete"
+};
+//#endregion
+export { e as TOUR_PERMISSIONS };
+
+//# sourceMappingURL=permissions.js.map

package/dist/constants/permissions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions.js","names":[],"sources":["../../src/constants/permissions.ts"],"sourcesContent":["/**\n * Tours Permission Constants\n *\n * All permission strings for Tours resources.\n * Use with fe-libs usePermissions hook: hasPermission(TOUR_PERMISSIONS.TOUR_CREATE)\n *\n * Resource types:\n * - tour: list, read, create, update, delete, publish, archive, duplicate\n * - tour-step: list, read, create, update, delete\n * - tour-media: list, read, create, update, delete\n * - tour-template: list, read, use\n * - tour-analytics: list, read\n * - tour-schedule: list, read, create, update, delete\n */\n\nexport const TOUR_PERMISSIONS = {\n  // Tour resources\n  TOUR_LIST: 'tour:list',\n  TOUR_READ: 'tour:read',\n  TOUR_CREATE: 'tour:create',\n  TOUR_UPDATE: 'tour:update',\n  TOUR_DELETE: 'tour:delete',\n  TOUR_PUBLISH: 'tour:publish',\n  TOUR_ARCHIVE: 'tour:archive',\n  TOUR_DUPLICATE: 'tour:duplicate',\n\n  // Tour step resources\n  TOUR_STEP_LIST: 'tour-step:list',\n  TOUR_STEP_READ: 'tour-step:read',\n  TOUR_STEP_CREATE: 'tour-step:create',\n  TOUR_STEP_UPDATE: 'tour-step:update',\n  TOUR_STEP_DELETE: 'tour-step:delete',\n\n  // Tour media resources\n  TOUR_MEDIA_LIST: 'tour-media:list',\n  TOUR_MEDIA_READ: 'tour-media:read',\n  TOUR_MEDIA_CREATE: 'tour-media:create',\n  TOUR_MEDIA_UPDATE: 'tour-media:update',\n  TOUR_MEDIA_DELETE: 'tour-media:delete',\n\n  // Tour template resources\n  TOUR_TEMPLATE_CREATE: 'tour-template:create',\n  TOUR_TEMPLATE_LIST: 'tour-template:list',\n  TOUR_TEMPLATE_READ: 'tour-template:read',\n  TOUR_TEMPLATE_USE: 'tour-template:use',\n  TOUR_TEMPLATE_UPDATE: 'tour-template:update',\n  TOUR_TEMPLATE_DELETE: 'tour-template:delete',\n\n  // Tour analytics resources\n  TOUR_ANALYTICS_LIST: 'tour-analytics:list',\n  TOUR_ANALYTICS_READ: 'tour-analytics:read',\n\n  // Tour schedule resources\n  TOUR_SCHEDULE_LIST: 'tour-schedule:list',\n  TOUR_SCHEDULE_READ: 'tour-schedule:read',\n  TOUR_SCHEDULE_CREATE: 'tour-schedule:create',\n  TOUR_SCHEDULE_UPDATE: 'tour-schedule:update',\n  TOUR_SCHEDULE_DELETE: 'tour-schedule:delete',\n} as const;\n\nexport type TourPermission = (typeof TOUR_PERMISSIONS)[keyof typeof TOUR_PERMISSIONS];\n"],"mappings":";AAeA,IAAa,IAAmB;CAE9B,WAAW;CACX,WAAW;CACX,aAAa;CACb,aAAa;CACb,aAAa;CACb,cAAc;CACd,cAAc;CACd,gBAAgB;CAGhB,gBAAgB;CAChB,gBAAgB;CAChB,kBAAkB;CAClB,kBAAkB;CAClB,kBAAkB;CAGlB,iBAAiB;CACjB,iBAAiB;CACjB,mBAAmB;CACnB,mBAAmB;CACnB,mBAAmB;CAGnB,sBAAsB;CACtB,oBAAoB;CACpB,oBAAoB;CACpB,mBAAmB;CACnB,sBAAsB;CACtB,sBAAsB;CAGtB,qBAAqB;CACrB,qBAAqB;CAGrB,oBAAoB;CACpB,oBAAoB;CACpB,sBAAsB;CACtB,sBAAsB;CACtB,sBAAsB;CACvB"}

package/dist/dev/main.d.ts

@@ -0,0 +1,2 @@
+
+//# sourceMappingURL=main.d.ts.map

package/dist/dev/main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/dev/main.tsx"],"names":[],"mappings":"AAYA,OAAO,cAAc,CAAC"}