@hazem3500/komo 0.0.0-stage → 0.8.0

package/src/types.ts

@@ -0,0 +1,153 @@
+export interface Identity {
+  id: string;
+  name: string;
+  verified: boolean;
+  avatarUrl?: string;
+  accentColor?: string;
+}
+
+export interface Anchor {
+  /** A manually moved indicator keeps its own position instead of joining a stack. */
+  unstacked?: boolean;
+  selector: string;
+  text: string;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  pageX: number;
+  pageY: number;
+  viewportWidth: number;
+  source?: string;
+  /** Optional public target details; old anchors remain valid without them. */
+  context?: {
+    tag?: string;
+    role?: string;
+    label?: string;
+    nearby?: string;
+    classes?: string;
+    selectedText?: string;
+    styles?: string;
+    scope?: string;
+  };
+}
+
+export interface Comment {
+  id: string;
+  body: string;
+  author: Identity;
+  createdAt: number;
+  editedAt: number | null;
+  reactions: Record<string, string[]>;
+}
+
+export interface Thread {
+  id: string;
+  page: string;
+  anchor: Anchor;
+  resolved: boolean;
+  resolvedBy: Identity | null;
+  createdAt: number;
+  updatedAt: number;
+  /** Reviewer-defined labels used to group related feedback. */
+  tags?: string[];
+  comments: Comment[];
+}
+
+export interface OnboardingOptions {
+  /** Temporary first-run setup inside the consuming site. Generated by the CLI. */
+  inProject?: boolean;
+  /** Suggested deployed sites shown for owner approval during first-run setup. */
+  sites?: string[];
+  invite?: string;
+  code?: string;
+  workspace?: string;
+  claimKey?: string;
+  site?: string;
+}
+
+/**
+ * Keyboard shortcuts as a key with optional Ctrl, Alt, Shift, or Meta
+ * modifiers, e.g. "M" or "Shift+J". Set false to disable one. Escape and Tab
+ * are reserved.
+ */
+export interface KomoShortcuts {
+  /** Toggle comment mode. Defaults to "C". */
+  comment?: string | false;
+  /** Return to browsing. Defaults to "V". */
+  browse?: string | false;
+  /** Toggle Design mode. Defaults to "D". Has no effect when features.designMode is false. */
+  design?: string | false;
+  /** Restore a dismissed toolbar. Defaults to "Shift+K". */
+  restore?: string | false;
+}
+
+/** Optional review features. Each defaults to true; false removes it from the UI. */
+export interface KomoFeatures {
+  /** Design mode inspector, style previews, and design proposals. */
+  designMode?: boolean;
+  /** Thread group tags: add them while writing a comment or on an open thread; shown in the sidebar. */
+  tags?: boolean;
+}
+
+export interface CommentsOptions {
+  /** Used by the hosted setup screen to reuse the sidebar account UI. */
+  onboarding?: OnboardingOptions;
+  /** Shared API URL. Never put a private credential here. */
+  endpoint: string;
+  /** Repository identifier, normally owner/repository. */
+  repo: string;
+  branch: string;
+  /** Public project key registered in the API configuration. */
+  project: string;
+  enabled?: boolean;
+  /** Hide the toolbar until controller.open() or the restore shortcut is used. Defaults to true. */
+  showToolbar?: boolean;
+  /** Override or disable the review keyboard shortcuts. */
+  shortcuts?: KomoShortcuts;
+  /** Turn optional features off, e.g. { designMode: false, tags: false }. */
+  features?: KomoFeatures;
+  /**
+   * Sidebar presentation when the review opens. "edge" (default) is a floating,
+   * draggable sidebar that parks off and peeks from the viewport edge while
+   * closed. "background" frames the site and shows the sidebar in the scaled
+   * review sheet. Users can switch Floating and Frame from the Account panel;
+   * that choice is remembered per project. Compact viewports always use a bottom
+   * Drawer, retaining the desktop preference when the viewport grows.
+   */
+  sidebar?: "background" | "edge";
+  /** Hide the drawer away from the pointer. Defaults to true. */
+  autoHideDrawer?: boolean;
+  /** Center the default drawer position within this element. */
+  drawerContainer?: HTMLElement;
+  /** Mounted content root for Frame. Defaults to a sole body content element; otherwise Floating only. */
+  pageRoot?: HTMLElement;
+  /** Resolve an anchor to a repository-relative source path. */
+  source?: (element: Element) => string | undefined;
+  /** Defaults to GitHub's source viewer. */
+  sourceUrl?: (source: string, branch: string) => string;
+  /** Defaults to location.pathname; query strings are not stored. */
+  page?: () => string;
+  pollInterval?: number;
+  /** Full emoji JSON URL; fetched only when choosing another emoji. */
+  emojiDataSource?: string;
+  /** Opt-in trusted parent domain. Every sibling host can receive the session. */
+  sessionDomain?: string;
+  /** Canonical API identity for trusted gateways to the same service. Defaults to endpoint. */
+  sessionEndpoint?: string;
+}
+
+export interface CommentsController {
+  /** Open a new comment anchored to an element. */
+  comment(element: Element): void;
+  destroy(): void;
+  open(): void;
+  close(): void;
+  refresh(): Promise<void>;
+}
+
+export interface AccountUsage {
+  hosted: boolean;
+  projects: { used: number; limit: number | null } | null;
+  comments: { used: number; limit: number | null };
+}