d2d-feedbackkit 0.0.0

package/src/source.ts

@@ -0,0 +1,248 @@
+import type { FeedbackLocatorSourceMetadata } from "./types";
+
+export const feedbackLocatorDataAttribute = "data-feedback-locator-id";
+export const feedbackLocatorDataKey = "__FEEDBACK_LOCATOR_DATA__";
+const locatorJsDataAttribute = "data-locatorjs-id";
+
+export type FeedbackLocatorSourceLocation = {
+  start: {
+    line: number;
+    column: number;
+  };
+  end: {
+    line: number;
+    column: number;
+  };
+};
+
+export type FeedbackLocatorComponentInfo = {
+  name: string;
+  loc: FeedbackLocatorSourceLocation;
+};
+
+export type FeedbackLocatorExpressionInfo = {
+  name: string;
+  loc: FeedbackLocatorSourceLocation;
+  componentId: number | null;
+};
+
+export type FeedbackLocatorFileStorage = {
+  filePath: string;
+  projectPath: string;
+  expressions: FeedbackLocatorExpressionInfo[];
+  components: FeedbackLocatorComponentInfo[];
+};
+
+type LocatorJsComponentInfo = {
+  name: string;
+  loc?: FeedbackLocatorSourceLocation | null;
+};
+
+type LocatorJsExpressionInfo = {
+  name: string;
+  loc: FeedbackLocatorSourceLocation;
+  wrappingComponentId: number | null;
+};
+
+type LocatorJsFileStorage = {
+  filePath?: string;
+  projectPath?: string;
+  expressions?: LocatorJsExpressionInfo[];
+  components?: LocatorJsComponentInfo[];
+};
+
+declare global {
+  interface Window {
+    __FEEDBACK_LOCATOR_DATA__?: Record<string, FeedbackLocatorFileStorage>;
+    __LOCATOR_DATA__?: Record<string, LocatorJsFileStorage>;
+  }
+}
+
+export function parseFeedbackLocatorId(locatorId: string) {
+  const separatorIndex = locatorId.lastIndexOf("::");
+
+  if (separatorIndex === -1) {
+    throw new Error("feedback locator id is malformed");
+  }
+
+  const fileKey = locatorId.slice(0, separatorIndex);
+  const expressionId = locatorId.slice(separatorIndex + 2);
+
+  if (!fileKey || !expressionId) {
+    throw new Error("feedback locator id is malformed");
+  }
+
+  return {
+    fileKey,
+    expressionIndex: Number(expressionId),
+  };
+}
+
+export function getFeedbackLocatorSourceForElement(
+  target: HTMLElement,
+): FeedbackLocatorSourceMetadata | null {
+  const found = target.closest(`[${feedbackLocatorDataAttribute}]`);
+
+  if (!(found instanceof HTMLElement)) {
+    return getLocatorJsSourceForElement(target);
+  }
+
+  const locatorId = found.dataset.feedbackLocatorId;
+  if (!locatorId || typeof window === "undefined") {
+    return getLocatorJsSourceForElement(target);
+  }
+
+  const { fileKey, expressionIndex } = parseFeedbackLocatorId(locatorId);
+  const fileData = window.__FEEDBACK_LOCATOR_DATA__?.[fileKey];
+  const expression = fileData?.expressions[expressionIndex];
+
+  if (!fileData || !expression) {
+    return getLocatorJsSourceForElement(found);
+  }
+
+  const component = getFeedbackLocatorComponent(fileData, expression.componentId);
+  const locatorJsComponent = component
+    ? null
+    : getLocatorJsComponentForElement(found);
+  const ancestorComponent =
+    component || locatorJsComponent ? null : getAncestorComponentForElement(found);
+  const resolvedComponent = component ?? locatorJsComponent ?? ancestorComponent;
+
+  return {
+    locatorId,
+    filePath: fileData.filePath,
+    elementName: expression.name,
+    componentName: resolvedComponent?.name ?? null,
+    line: expression.loc.start.line,
+    column: expression.loc.start.column + 1,
+    componentLine: resolvedComponent?.line ?? null,
+    componentColumn: resolvedComponent?.column ?? null,
+  };
+}
+
+function getLocatorJsSourceForElement(
+  target: HTMLElement,
+): FeedbackLocatorSourceMetadata | null {
+  const found = target.closest(`[${locatorJsDataAttribute}]`);
+
+  if (!(found instanceof HTMLElement) || typeof window === "undefined") {
+    return null;
+  }
+
+  const locatorId = found.getAttribute(locatorJsDataAttribute);
+  if (!locatorId) {
+    return null;
+  }
+
+  const { fileKey, expressionIndex } = parseFeedbackLocatorId(locatorId);
+  const fileData = window.__LOCATOR_DATA__?.[fileKey];
+  const expression = fileData?.expressions?.[expressionIndex];
+
+  if (!fileData || !expression) {
+    return null;
+  }
+
+  const component = getLocatorJsComponentForElement(found);
+
+  return {
+    locatorId,
+    filePath: toLocatorJsFilePath(fileData, fileKey),
+    elementName: expression.name,
+    componentName: component?.name ?? null,
+    line: expression.loc.start.line,
+    column: expression.loc.start.column + 1,
+    componentLine: component?.line ?? null,
+    componentColumn: component?.column ?? null,
+  };
+}
+
+function toLocatorJsFilePath(fileData: LocatorJsFileStorage, fileKey: string) {
+  const filePath = fileData.filePath ?? fileKey;
+  const projectPath = fileData.projectPath;
+
+  if (projectPath && filePath.startsWith(projectPath)) {
+    return filePath.slice(projectPath.length).replace(/^\//, "");
+  }
+
+  return filePath.replace(/^\//, "");
+}
+
+function getFeedbackLocatorComponent(
+  fileData: FeedbackLocatorFileStorage,
+  componentId: number | null,
+) {
+  if (componentId === null) {
+    return null;
+  }
+
+  const component = fileData.components[componentId];
+  if (!component) {
+    return null;
+  }
+
+  return {
+    name: component.name,
+    line: component.loc.start.line,
+    column: component.loc.start.column + 1,
+  };
+}
+
+function getAncestorComponentForElement(element: HTMLElement) {
+  let parent = element.parentElement;
+
+  while (parent) {
+    const locatorId = parent.getAttribute(feedbackLocatorDataAttribute);
+    if (locatorId) {
+      const component = getFeedbackLocatorComponentForLocatorId(locatorId);
+      if (component) {
+        return component;
+      }
+    }
+
+    parent = parent.parentElement;
+  }
+
+  return null;
+}
+
+function getFeedbackLocatorComponentForLocatorId(locatorId: string) {
+  const { fileKey, expressionIndex } = parseFeedbackLocatorId(locatorId);
+  const fileData = window.__FEEDBACK_LOCATOR_DATA__?.[fileKey];
+  const expression = fileData?.expressions[expressionIndex];
+
+  if (!fileData || !expression) {
+    return null;
+  }
+
+  return getFeedbackLocatorComponent(fileData, expression.componentId);
+}
+
+function getLocatorJsComponentForElement(element: HTMLElement) {
+  const locatorJsId = element.getAttribute(locatorJsDataAttribute);
+  if (!locatorJsId) {
+    return null;
+  }
+
+  const { fileKey, expressionIndex } = parseFeedbackLocatorId(locatorJsId);
+  const fileData = window.__LOCATOR_DATA__?.[fileKey];
+  const expression = fileData?.expressions?.[expressionIndex];
+  const componentId = expression?.wrappingComponentId;
+
+  if (componentId === null || componentId === undefined) {
+    return null;
+  }
+
+  const component = fileData?.components?.[componentId];
+  if (!component) {
+    return null;
+  }
+
+  return {
+    name: component.name,
+    line: component.loc?.start.line ?? null,
+    column:
+      component.loc?.start.column !== undefined
+        ? component.loc.start.column + 1
+        : null,
+  };
+}

package/src/types.ts

@@ -0,0 +1,218 @@
+export type FeedbackLocatorHotkey = {
+  key: string;
+  ctrl?: boolean;
+  shift?: boolean;
+  alt?: boolean;
+  meta?: boolean;
+};
+
+export type FeedbackLocatorPoint = {
+  x: number;
+  y: number;
+};
+
+export type FeedbackLocatorBounds = {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  top: number;
+  right: number;
+  bottom: number;
+  left: number;
+};
+
+export type FeedbackLocatorSourceMetadata = {
+  locatorId: string;
+  filePath: string;
+  elementName: string;
+  componentName: string | null;
+  line: number;
+  column: number;
+  componentLine: number | null;
+  componentColumn: number | null;
+};
+
+export type FeedbackLocatorElementMetadata = {
+  tagName: string;
+  id: string | null;
+  className: string | null;
+  role: string | null;
+  ariaLabel: string | null;
+  name: string | null;
+  text: string | null;
+  bounds: FeedbackLocatorBounds;
+};
+
+export type FeedbackLocatorBrowserMetadata = {
+  userAgent: string;
+  language: string;
+  platform: string;
+  timezone: string;
+};
+
+export type FeedbackLocatorViewportMetadata = {
+  width: number;
+  height: number;
+  devicePixelRatio: number;
+};
+
+export type FeedbackLocatorContextEntry = {
+  key: string;
+  data: unknown;
+};
+
+export type FeedbackLocatorContextProviderInput = {
+  targetElement: HTMLElement;
+};
+
+export type FeedbackLocatorContextProvider = (
+  input?: FeedbackLocatorContextProviderInput,
+) =>
+  | FeedbackLocatorContextEntry
+  | FeedbackLocatorContextEntry[]
+  | null
+  | undefined
+  | Promise<FeedbackLocatorContextEntry | FeedbackLocatorContextEntry[] | null | undefined>;
+
+export type FeedbackLocatorScopedContextCollector = (
+  input: FeedbackLocatorContextProviderInput,
+) => unknown | Promise<unknown>;
+
+export type FeedbackLocatorContextScope =
+  | HTMLElement
+  | (() => HTMLElement | null | undefined)
+  | null
+  | undefined;
+
+export type FeedbackLocatorContextRegistration =
+  | FeedbackLocatorScopedContextCollector
+  | {
+      scope?: FeedbackLocatorContextScope;
+      collect: FeedbackLocatorScopedContextCollector;
+    };
+
+export type FeedbackLocatorContextPreview = {
+  context: Record<string, unknown>;
+  contextErrors: string[];
+};
+
+export type FeedbackLocatorAsset = {
+  name: string;
+  url: string;
+  contentType: string;
+  size: number;
+};
+
+export type FeedbackLocatorMetadata = {
+  id: string;
+  appKey: string;
+  appName: string;
+  prompt: string;
+  createdAt: string;
+  url: string;
+  route: string;
+  browser: FeedbackLocatorBrowserMetadata;
+  viewport: FeedbackLocatorViewportMetadata;
+  element: FeedbackLocatorElementMetadata;
+  source: FeedbackLocatorSourceMetadata | null;
+  context: Record<string, unknown>;
+  contextErrors: string[];
+  assets?: {
+    screenshotUrl?: string;
+    annotatedScreenshotUrl?: string;
+    recording?: FeedbackLocatorAsset;
+    attachments?: FeedbackLocatorAsset[];
+    contextAttachments?: FeedbackLocatorAsset[];
+  };
+};
+
+export type FeedbackLocatorSubmitInput = {
+  formData: FormData;
+  metadata: FeedbackLocatorMetadata;
+  originalScreenshot: Blob;
+  annotatedScreenshot?: Blob;
+  recording?: File;
+  attachments?: File[];
+};
+
+export type FeedbackLocatorLinearIssueReference = {
+  issueId: string;
+  issueIdentifier: string;
+  issueTitle: string;
+  issueUrl: string;
+};
+
+export type FeedbackLocatorSubmitResult = FeedbackLocatorLinearIssueReference;
+
+export type FeedbackLocatorAgentSessionResult = {
+  sessionId: string;
+  sessionTitle: string;
+  sessionUrl: string;
+  prompt: string;
+};
+
+export type FeedbackLocatorCodexThreadResult = {
+  threadId: string;
+  threadTitle: string;
+  prompt: string;
+  status: "started";
+  linearIssue?: FeedbackLocatorLinearIssueReference;
+};
+
+export type FeedbackLocatorOpenCodeThreadResult = {
+  sessionId: string;
+  sessionTitle: string;
+  prompt: string;
+  status: "started" | "completed";
+  stdout?: string;
+  stderr?: string;
+  linearIssue?: FeedbackLocatorLinearIssueReference;
+};
+
+export type FeedbackLocatorSourceCollector = (
+  target: HTMLElement,
+) => FeedbackLocatorSourceMetadata | null;
+
+export type FeedbackLocatorConfig = {
+  appKey: string;
+  appName: string;
+  submitFeedback: (
+    input: FeedbackLocatorSubmitInput,
+  ) => Promise<FeedbackLocatorSubmitResult>;
+  startAgentSession?: (
+    input: FeedbackLocatorSubmitInput,
+  ) => Promise<FeedbackLocatorAgentSessionResult>;
+  startCodexThread?: (
+    input: FeedbackLocatorSubmitInput,
+  ) => Promise<FeedbackLocatorCodexThreadResult>;
+  startOpenCodeThread?: (
+    input: FeedbackLocatorSubmitInput,
+  ) => Promise<FeedbackLocatorOpenCodeThreadResult>;
+  contextProviders?: FeedbackLocatorContextProvider[];
+  hotkey?: FeedbackLocatorHotkey;
+  sourceCollector?: FeedbackLocatorSourceCollector;
+};
+
+export type FeedbackLocator = {
+  config: Required<Pick<FeedbackLocatorConfig, "appKey" | "appName" | "submitFeedback">> &
+    Pick<
+      FeedbackLocatorConfig,
+      | "contextProviders"
+      | "hotkey"
+      | "sourceCollector"
+      | "startAgentSession"
+      | "startCodexThread"
+      | "startOpenCodeThread"
+    >;
+  registerContext: (
+    key: string,
+    registration: FeedbackLocatorContextRegistration,
+  ) => () => void;
+  collectContext: (input: FeedbackLocatorContextProviderInput) => Promise<FeedbackLocatorContextPreview>;
+  createMetadata: (input: {
+    prompt: string;
+    targetElement: HTMLElement;
+    source: FeedbackLocatorSourceMetadata | null;
+  }) => Promise<FeedbackLocatorMetadata>;
+};

package/src/vite-plugin.ts

@@ -0,0 +1,3 @@
+export { default } from "./babel";
+export { default as feedbackKitBabelPlugin } from "./babel";
+export * from "./source";

package/src/web-component.tsx

@@ -0,0 +1,114 @@
+import { render } from "solid-js/web";
+import { FeedbackLocatorRoot } from "./solid";
+import type { FeedbackLocator } from "./types";
+
+export type FeedbackLocatorCustomElementOptions = {
+  tagName?: string;
+  shadowRoot?: boolean;
+  styles?: string | string[];
+};
+
+export type FeedbackLocatorCustomElement = HTMLElement & {
+  locator: FeedbackLocator | null;
+};
+
+export const defaultFeedbackLocatorElementName = "d2d-feedbackkit";
+
+export function defineFeedbackLocatorElement(
+  options: FeedbackLocatorCustomElementOptions = {},
+) {
+  const tagName = options.tagName ?? defaultFeedbackLocatorElementName;
+  const existing = customElements.get(tagName);
+
+  if (existing) {
+    return existing as CustomElementConstructor;
+  }
+
+  class FeedbackKitElement extends HTMLElement {
+    #locator: FeedbackLocator | null = null;
+    #dispose: (() => void) | undefined;
+    #mount: HTMLElement | undefined;
+
+    get locator() {
+      return this.#locator;
+    }
+
+    set locator(locator: FeedbackLocator | null) {
+      this.#locator = locator;
+      this.#render();
+    }
+
+    connectedCallback() {
+      this.#render();
+    }
+
+    disconnectedCallback() {
+      this.#dispose?.();
+      this.#dispose = undefined;
+    }
+
+    #render() {
+      if (!this.isConnected || !this.#locator) {
+        return;
+      }
+
+      this.#dispose?.();
+      this.#dispose = undefined;
+      this.#mount = this.#mount ?? this.#createMount();
+      this.#mount.replaceChildren();
+      this.#dispose = render(
+        () => <FeedbackLocatorRoot locator={this.#locator!} />,
+        this.#mount,
+      );
+    }
+
+    #createMount() {
+      if (!options.shadowRoot) {
+        return this;
+      }
+
+      const root = this.shadowRoot ?? this.attachShadow({ mode: "open" });
+      const styles = Array.isArray(options.styles)
+        ? options.styles
+        : options.styles
+          ? [options.styles]
+          : [];
+
+      for (const styleText of styles) {
+        const style = document.createElement("style");
+        style.textContent = styleText;
+        root.append(style);
+      }
+
+      const mount = document.createElement("div");
+      root.append(mount);
+      return mount;
+    }
+  }
+
+  customElements.define(tagName, FeedbackKitElement);
+  return FeedbackKitElement;
+}
+
+export function mountFeedbackLocatorElement(
+  locator: FeedbackLocator,
+  options: FeedbackLocatorCustomElementOptions & { target?: HTMLElement } = {},
+) {
+  const tagName = options.tagName ?? defaultFeedbackLocatorElementName;
+  defineFeedbackLocatorElement(options);
+
+  const element = document.createElement(tagName) as FeedbackLocatorCustomElement;
+  element.locator = locator;
+  (options.target ?? document.body).append(element);
+
+  return {
+    element,
+    dispose: () => element.remove(),
+  };
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "d2d-feedbackkit": FeedbackLocatorCustomElement;
+  }
+}

package/src/widget.tsx

@@ -0,0 +1 @@
+export { FeedbackLocatorRoot } from "./solid";