@sirendesign/markup 1.0.0

package/README.md

@@ -0,0 +1,329 @@
+# @siren/markup
+
+A powerful web markup and feedback tool for collecting visual feedback from clients and account managers. Similar to [marker.io](https://marker.io), this tool provides an easy-to-use widget for capturing screenshots, adding annotations, and managing feedback items.
+
+## ✨ New: Firebase Integration
+
+**Multi-tenant feedback with authentication and real-time sync!** See [FIREBASE_SETUP.md](./FIREBASE_SETUP.md) for complete setup instructions.
+
+- 🔒 **User Authentication** - Email/password authentication via Firebase
+- ☁️ **Cloud Storage** - Feedback stored in Firestore with real-time sync
+- 🏢 **Multi-Tenancy** - Each website/project has isolated feedback
+- 🔄 **Real-time Updates** - Changes sync instantly across all devices
+- 👥 **User Tracking** - Know who submitted each ticket
+
+## Features
+
+- 📸 **Screenshot Capture** - Capture full-page screenshots with one click
+- ✏️ **Annotation Tools** - Add arrows, rectangles, circles, highlights, text, and freehand drawings
+- ✂️ **Copy Amendments** - Track text changes with before/after comparison
+- 💬 **Feedback Management** - Create, view, and manage feedback items
+- 🏷️ **Tags & Priority** - Organize feedback with custom tags and priority levels
+- 📊 **Status Tracking** - Track feedback status (Open, In Progress, Resolved, Closed)
+- 💾 **Local or Cloud Storage** - Works offline or with Firebase sync
+- 🔌 **API Integration** - Optional API endpoint for server-side storage
+- ⌨️ **Keyboard Shortcuts** - Quick access with customizable shortcuts
+- 🎨 **Customizable** - Theming, labels, and position options
+
+## Installation
+
+```bash
+npm install @siren/markup firebase
+# or
+yarn add @siren/markup firebase
+# or
+pnpm add @siren/markup firebase
+```
+
+Note: `firebase` is included as a peer dependency if you want to use authentication and cloud sync.
+
+## Quick Start
+
+### Basic Setup (Local Storage)
+
+```tsx
+import { MarkupWidget } from '@siren/markup';
+import '@siren/markup/dist/styles.css';
+
+function App() {
+  return (
+    <div>
+      <YourApp />
+      
+      <MarkupWidget
+        config={{
+          projectId: 'my-project',
+          primaryColor: '#6366f1',
+        }}
+      />
+    </div>
+  );
+}
+```
+
+### With Firebase (Authentication & Cloud Sync)
+
+```tsx
+import { MarkupWidget, initFirebase } from '@siren/markup';
+import '@siren/markup/dist/styles.css';
+
+// 1. Create .env in YOUR app (not the npm package):
+//    VITE_FIREBASE_API_KEY=...
+//    VITE_FIREBASE_AUTH_DOMAIN=...
+//    etc.
+
+// 2. YOUR app reads .env and calls initFirebase once
+initFirebase({
+  apiKey: import.meta.env.VITE_FIREBASE_API_KEY,
+  authDomain: import.meta.env.VITE_FIREBASE_AUTH_DOMAIN,
+  projectId: import.meta.env.VITE_FIREBASE_PROJECT_ID,
+  storageBucket: import.meta.env.VITE_FIREBASE_STORAGE_BUCKET,
+  messagingSenderId: import.meta.env.VITE_FIREBASE_MESSAGING_SENDER_ID,
+  appId: import.meta.env.VITE_FIREBASE_APP_ID,
+});
+
+function App() {
+  return (
+    <div>
+      <YourApp />
+      
+      <MarkupWidget config={{ projectId: 'my-website-prod' }} />
+    </div>
+  );
+}
+```
+
+**With Firebase enabled:**
+- ✅ Users must sign in to submit feedback
+- ✅ Feedback syncs across devices in real-time
+- ✅ Each `projectId` has isolated feedback
+- ✅ Track who submitted each ticket
+
+See [FIREBASE_SETUP.md](./FIREBASE_SETUP.md) for complete setup instructions.
+
+### Next.js App Router
+
+For Next.js 13+ with the App Router, create a client component:
+
+```tsx
+// components/FeedbackWidget.tsx
+'use client';
+
+import { MarkupWidget } from '@siren/markup';
+import '@siren/markup/dist/styles.css';
+
+export default function FeedbackWidget() {
+  return (
+    <MarkupWidget
+      config={{
+        projectId: 'my-project',
+          id: 'user-123',
+          name: 'John Doe',
+          email: 'john@example.com',
+        },
+      }}
+    />
+  );
+}
+```
+
+Then use it in your layout:
+
+```tsx
+// app/layout.tsx
+import FeedbackWidget from '@/components/FeedbackWidget';
+
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        {children}
+        <FeedbackWidget />
+      </body>
+    </html>
+  );
+}
+```
+
+## Configuration Options
+
+```typescript
+interface MarkupConfig {
+  // Required: Project identifier
+  projectId: string;
+  
+  // User information (optional)
+  user?: {
+    id: string;
+    name: string;
+    email: string;
+    avatar?: string;
+    role?: 'admin' | 'developer' | 'client' | 'account-manager';
+  };
+  
+  // API endpoint for storing feedback (uses local storage if not provided)
+  apiEndpoint?: string;
+  
+  // API key for authentication
+  apiKey?: string;
+  
+  // Widget position (default: 'bottom-right')
+  position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+  
+  // Primary color (default: '#6366f1')
+  primaryColor?: string;
+  
+  // Whether widget opens by default
+  defaultOpen?: boolean;
+  
+  // Keyboard shortcut (default: 'ctrl+shift+m')
+  shortcut?: string;
+  
+  // Custom labels
+  labels?: {
+    widgetButton?: string;
+    feedbackTitle?: string;
+    submitButton?: string;
+    cancelButton?: string;
+  };
+  
+  // Callback when feedback is submitted
+  onSubmit?: (feedback: FeedbackItem) => void | Promise<void>;
+  
+  // Callback when status changes
+  onStatusChange?: (feedbackId: string, status: FeedbackStatus) => void | Promise<void>;
+  
+  // Tags available for feedback
+  availableTags?: string[];
+  
+  // Team members for assignment
+  teamMembers?: UserInfo[];
+}
+```
+
+## API Integration
+
+To store feedback on your server, provide an `apiEndpoint`:
+
+```tsx
+<MarkupWidget
+  config={{
+    projectId: 'my-project',
+    apiEndpoint: 'https://api.yourserver.com',
+    apiKey: 'your-api-key',
+    onSubmit: async (feedback) => {
+      // Custom handling after submission
+      console.log('Feedback submitted:', feedback);
+    },
+  }}
+/>
+```
+
+### Expected API Endpoints
+
+If you provide an `apiEndpoint`, implement these endpoints:
+
+- `GET /projects/:projectId/feedback` - List all feedback
+- `POST /projects/:projectId/feedback` - Create feedback
+- `PATCH /projects/:projectId/feedback/:id` - Update feedback
+- `DELETE /projects/:projectId/feedback/:id` - Delete feedback
+- `POST /projects/:projectId/feedback/:id/comments` - Add comment
+- `POST /projects/:projectId/upload` - Upload screenshot (returns `{ url: string }`)
+
+## Using the Store Directly
+
+Access the feedback store for custom integrations:
+
+```tsx
+import { useMarkupStore } from '@company/markup';
+
+function AdminDashboard() {
+  const { feedbackItems, updateFeedbackItem } = useMarkupStore();
+  
+  const openItems = feedbackItems.filter(item => item.status === 'open');
+  
+  return (
+    <div>
+      <h2>Open Feedback ({openItems.length})</h2>
+      {openItems.map(item => (
+        <div key={item.id}>
+          <h3>{item.title}</h3>
+          <button onClick={() => updateFeedbackItem(item.id, { status: 'in-progress' })}>
+            Start Working
+          </button>
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+## Customization
+
+### Custom Styling
+
+Override CSS variables for custom theming:
+
+```css
+.markup-widget {
+  --markup-primary: #your-brand-color;
+  --markup-primary-hover: #your-brand-color-darker;
+  --markup-bg: #ffffff;
+  --markup-bg-secondary: #f3f4f6;
+  --markup-border: #e5e7eb;
+  --markup-text: #1f2937;
+  --markup-text-secondary: #6b7280;
+  --markup-radius: 12px;
+}
+```
+
+### Custom Labels
+
+```tsx
+<MarkupWidget
+  config={{
+    projectId: 'my-project',
+    labels: {
+      widgetButton: 'Report Issue',
+      feedbackTitle: 'Submit Feedback',
+      submitButton: 'Send',
+      cancelButton: 'Close',
+    },
+  }}
+/>
+```
+
+## Types
+
+```typescript
+import type {
+  FeedbackItem,
+  FeedbackStatus,
+  FeedbackPriority,
+  Annotation,
+  AnnotationType,
+  UserInfo,
+  Comment,
+  MarkupConfig,
+} from '@company/markup';
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build the package
+npm run build
+
+# Watch mode for development
+npm run dev
+
+# Type check
+npm run type-check
+```
+
+## License
+
+MIT

package/dist/components/AnnotationOverlay.d.ts

@@ -0,0 +1,9 @@
+import React from 'react';
+import type { Annotation } from '../types';
+interface AnnotationOverlayProps {
+    screenshot: string;
+    onComplete: (annotations: Annotation[], screenshot: string) => void;
+    onCancel: () => void;
+}
+export declare const AnnotationOverlay: React.FC<AnnotationOverlayProps>;
+export default AnnotationOverlay;

package/dist/components/AuthForm.d.ts

@@ -0,0 +1,5 @@
+interface AuthFormProps {
+    onSuccess: () => void;
+}
+export declare const AuthForm: ({ onSuccess }: AuthFormProps) => import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/DebugPanel.d.ts

@@ -0,0 +1 @@
+export declare const DebugPanel: () => import("react/jsx-runtime").JSX.Element;

package/dist/components/FeedbackDetail.d.ts

@@ -0,0 +1,10 @@
+import React from "react";
+import type { FeedbackItem } from "../types";
+interface FeedbackDetailProps {
+    feedback: FeedbackItem;
+    onBack: () => void;
+    onDelete?: (id: string) => void;
+    onUpdate?: (feedback: FeedbackItem) => void;
+}
+export declare const FeedbackDetail: React.FC<FeedbackDetailProps>;
+export default FeedbackDetail;

package/dist/components/FeedbackForm.d.ts

@@ -0,0 +1,8 @@
+import React from "react";
+import type { FeedbackItem } from "../types";
+interface FeedbackFormProps {
+    onSubmit: (feedback: FeedbackItem) => void;
+    onCancel: () => void;
+}
+export declare const FeedbackForm: React.FC<FeedbackFormProps>;
+export default FeedbackForm;

package/dist/components/FeedbackList.d.ts

@@ -0,0 +1,8 @@
+import React from "react";
+import type { FeedbackItem } from "../types";
+interface FeedbackListProps {
+    feedbackItems: FeedbackItem[];
+    onSelectFeedback: (feedback: FeedbackItem) => void;
+}
+export declare const FeedbackList: React.FC<FeedbackListProps>;
+export default FeedbackList;

package/dist/components/Icons.d.ts

@@ -0,0 +1,36 @@
+import React from 'react';
+interface IconProps extends React.SVGProps<SVGSVGElement> {
+    className?: string;
+}
+export declare const MessageIcon: React.FC<IconProps>;
+export declare const CloseIcon: React.FC<IconProps>;
+export declare const CameraIcon: React.FC<IconProps>;
+export declare const ArrowIcon: React.FC<IconProps>;
+export declare const RectangleIcon: React.FC<IconProps>;
+export declare const CircleIcon: React.FC<IconProps>;
+export declare const TextIcon: React.FC<IconProps>;
+export declare const HighlightIcon: React.FC<IconProps>;
+export declare const PencilIcon: React.FC<IconProps>;
+export declare const UndoIcon: React.FC<IconProps>;
+export declare const CheckIcon: React.FC<IconProps>;
+export declare const BackIcon: React.FC<IconProps>;
+export declare const TrashIcon: React.FC<IconProps>;
+export declare const DownloadIcon: React.FC<IconProps>;
+export declare const EditIcon: React.FC<IconProps>;
+export declare const ClockIcon: React.FC<IconProps>;
+export declare const LinkIcon: React.FC<IconProps>;
+export declare const InboxIcon: React.FC<IconProps>;
+export declare const SendIcon: React.FC<IconProps>;
+export declare const SettingsIcon: React.FC<IconProps>;
+export declare const PlusIcon: React.FC<IconProps>;
+export declare const FilterIcon: React.FC<IconProps>;
+export declare const ExternalLinkIcon: React.FC<IconProps>;
+export declare const SquareIcon: React.FC<IconProps>;
+export declare const ArrowRightIcon: React.FC<IconProps>;
+export declare const TypeIcon: React.FC<IconProps>;
+export declare const ArrowLeftIcon: React.FC<IconProps>;
+export declare const UserIcon: React.FC<IconProps>;
+export declare const ZoomInIcon: React.FC<IconProps>;
+export declare const CalendarIcon: React.FC<IconProps>;
+export declare const ChevronRightIcon: React.FC<IconProps>;
+export {};

package/dist/components/MarkupWidget.d.ts

@@ -0,0 +1,7 @@
+import React from "react";
+import type { MarkupConfig } from "../types";
+export interface MarkupWidgetProps {
+    config?: Partial<MarkupConfig>;
+}
+export declare const MarkupWidget: React.FC<MarkupWidgetProps>;
+export default MarkupWidget;

package/dist/components/index.d.ts

@@ -0,0 +1,6 @@
+export { MarkupWidget, default } from './MarkupWidget';
+export { FeedbackForm } from './FeedbackForm';
+export { FeedbackList } from './FeedbackList';
+export { FeedbackDetail } from './FeedbackDetail';
+export { AnnotationOverlay } from './AnnotationOverlay';
+export { DebugPanel } from './DebugPanel';

package/dist/hooks/index.d.ts

@@ -0,0 +1 @@
+export { useMarkup, default } from './useMarkup';

package/dist/hooks/useFirebaseSync.d.ts

@@ -0,0 +1 @@
+export declare const useFirebaseSync: () => void;

package/dist/hooks/useMarkup.d.ts

@@ -0,0 +1,21 @@
+import type { FeedbackItem, MarkupConfig } from '../types';
+interface UseMarkupOptions {
+    config: MarkupConfig;
+    syncWithServer?: boolean;
+}
+export declare function useMarkup({ config, syncWithServer }: UseMarkupOptions): {
+    isOpen: boolean;
+    feedbackItems: FeedbackItem[];
+    selectedFeedback: FeedbackItem | null;
+    openWidget: () => void;
+    closeWidget: () => void;
+    toggleWidget: () => void;
+    submitFeedback: (feedback: Omit<FeedbackItem, "id" | "createdAt" | "updatedAt">) => Promise<FeedbackItem>;
+    updateFeedback: (id: string, updates: Partial<FeedbackItem>) => Promise<void>;
+    deleteFeedback: (id: string) => Promise<void>;
+    selectFeedback: (feedback: FeedbackItem | null) => void;
+    openCount: number;
+    inProgressCount: number;
+    resolvedCount: number;
+};
+export default useMarkup;

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { MarkupWidget, default } from './components';
+export { FeedbackForm, FeedbackList, FeedbackDetail, AnnotationOverlay } from './components';
+export { useMarkup } from './hooks';
+export { useMarkupStore } from './store';
+export type { FeedbackStatus, FeedbackPriority, AnnotationType, Annotation, PageMetadata, FeedbackItem, UserInfo, Comment, MarkupConfig, MarkupState, MarkupActions, MarkupStore, } from './types';
+export { captureScreenshot, getPageMetadata, getElementSelector, generateId, formatDate, getStatusColor, getPriorityColor, downloadScreenshot, copyToClipboard, MarkupAPI, } from './utils';
+export { initFirebase } from './initFirebase';
+export type { FirebaseConfig } from './initFirebase';