@promakeai/inspector 0.2.1 → 1.0.0

package/src/styles/global.css

@@ -0,0 +1,138 @@
+/* Inspector Canvas Global Styles */
+@import "./fonts.css";
+@import "./variables.css";
+
+/* Base scope for inspector */
+#inspector-canvas-root {
+  font-family: var(--font-family-sans);
+  font-size: 14px;
+  line-height: 1.5;
+  font-weight: 400;
+  letter-spacing: -0.01em;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+  text-rendering: optimizeLegibility;
+  position: fixed;
+  top: 0;
+  left: 0;
+  right: 0;
+  bottom: 0;
+  pointer-events: none;
+  z-index: var(--z-inspector-root);
+}
+
+/* Thin scrollbar for element tags */
+.inspector-element-tags::-webkit-scrollbar {
+  height: 4px;
+}
+
+.inspector-element-tags::-webkit-scrollbar-track {
+  background: transparent;
+}
+
+.inspector-element-tags::-webkit-scrollbar-thumb {
+  background: rgba(0, 0, 0, 0.2);
+  border-radius: 2px;
+}
+
+.inspector-element-tags::-webkit-scrollbar-thumb:hover {
+  background: rgba(0, 0, 0, 0.3);
+}
+
+/* Firefox */
+.inspector-element-tags {
+  scrollbar-width: thin;
+  scrollbar-color: rgba(0, 0, 0, 0.2) transparent;
+}
+
+/* When inspector is active, block all interactions with page */
+#inspector-canvas-root.inspector-active {
+  pointer-events: auto;
+}
+
+/* Backdrop when inspector is active */
+.inspector-backdrop {
+  position: fixed;
+  top: 0;
+  left: 0;
+  right: 0;
+  bottom: 0;
+  background: rgba(0, 0, 0, 0.01);
+  z-index: var(--z-inspector-backdrop);
+  pointer-events: auto;
+  cursor: default;
+  user-select: none;
+}
+
+/* Label specific fixes */
+#inspector-canvas-root label {
+  font-family: "Satoshi", var(--font-family-sans);
+  font-weight: 500;
+  letter-spacing: -0.01em;
+}
+
+/* Overlay styles */
+.inspector-overlay {
+  position: fixed;
+  pointer-events: none;
+  border: 3px solid var(--color-blue-500);
+  background: rgba(59, 130, 246, 0.1);
+  z-index: var(--z-inspector-overlay);
+  transition: all 0.1s ease;
+  display: none;
+}
+
+.inspector-overlay.active {
+  display: block;
+}
+
+.inspector-overlay.paused {
+  border-color: var(--color-green-500);
+  background: rgba(16, 185, 129, 0.1);
+}
+
+.inspector-overlay-child {
+  position: fixed;
+  pointer-events: none;
+  border: 1px dashed var(--color-blue-500);
+  background: rgba(59, 130, 246, 0.02);
+  z-index: var(--z-inspector-overlay);
+  transition: all 0.1s ease;
+  display: none;
+  opacity: 0.35;
+}
+
+.inspector-overlay-child.active {
+  display: block;
+}
+
+.inspector-element-tag {
+  transition: opacity 0.15s ease;
+}
+
+.inspector-element-tag:hover {
+  opacity: 0.85;
+}
+
+.inspector-element-tag:active {
+  opacity: 0.7;
+}
+
+/* Scrollbar styling for inspector elements */
+#inspector-canvas-root ::-webkit-scrollbar {
+  width: 6px;
+  height: 6px;
+}
+
+#inspector-canvas-root ::-webkit-scrollbar-track {
+  background: transparent;
+}
+
+#inspector-canvas-root ::-webkit-scrollbar-thumb {
+  background: var(--color-gray-300);
+  border-radius: var(--radius-sm);
+}
+
+#inspector-canvas-root ::-webkit-scrollbar-thumb:hover {
+  background: var(--color-gray-400);
+}

package/src/styles/variables.css

@@ -0,0 +1,151 @@
+:root {
+  /* Spacing scale */
+  --spacing-0: 0;
+  --spacing-0-5: 0.125rem;
+  --spacing-1: 0.25rem;
+  --spacing-1-5: 0.375rem;
+  --spacing-2: 0.5rem;
+  --spacing-2-5: 0.625rem;
+  --spacing-3: 0.75rem;
+  --spacing-3-5: 0.875rem;
+  --spacing-4: 1rem;
+  --spacing-5: 1.25rem;
+  --spacing-6: 1.5rem;
+  --spacing-7: 1.75rem;
+  --spacing-8: 2rem;
+  --spacing-9: 2.25rem;
+  --spacing-10: 2.5rem;
+  --spacing-12: 3rem;
+  --spacing-16: 4rem;
+  --spacing-20: 5rem;
+  --spacing-24: 6rem;
+  --spacing-32: 8rem;
+
+  /* Border radius */
+  --radius-none: 0;
+  --radius-sm: 0.375rem;
+  --radius-md: 0.5rem;
+  --radius-lg: 0.75rem;
+  --radius-xl: 1rem;
+  --radius-2xl: 1.5rem;
+  --radius-3xl: 2rem;
+  --radius-full: 9999px;
+
+  /* Font sizes */
+  --text-xs: 0.75rem;
+  --text-sm: 0.875rem;
+  --text-base: 1rem;
+  --text-lg: 1.125rem;
+  --text-xl: 1.25rem;
+  --text-2xl: 1.5rem;
+  --text-3xl: 1.875rem;
+
+  /* Line heights */
+  --leading-none: 1;
+  --leading-tight: 1.25;
+  --leading-normal: 1.5;
+  --leading-relaxed: 1.75;
+
+  /* Font weights */
+  --font-normal: 400;
+  --font-medium: 500;
+  --font-semibold: 600;
+  --font-bold: 700;
+
+  /* Shadows */
+  --shadow-xs: 0 1px 2px rgba(0, 0, 0, 0.05);
+  --shadow-sm: 0 1px 3px rgba(0, 0, 0, 0.1), 0 1px 2px rgba(0, 0, 0, 0.06);
+  --shadow-md: 0 4px 6px rgba(0, 0, 0, 0.1), 0 2px 4px rgba(0, 0, 0, 0.06);
+  --shadow-lg: 0 10px 15px rgba(0, 0, 0, 0.1), 0 4px 6px rgba(0, 0, 0, 0.05);
+  --shadow-xl: 0 20px 25px rgba(0, 0, 0, 0.1), 0 10px 10px rgba(0, 0, 0, 0.04);
+
+  /* Static colors (non-theme) */
+  --color-white: #ffffff;
+  --color-black: #000000;
+  --color-transparent: transparent;
+
+  /* Gray scale */
+  --color-gray-50: #f9fafb;
+  --color-gray-100: #f3f4f6;
+  --color-gray-200: #e5e7eb;
+  --color-gray-300: #d1d5db;
+  --color-gray-400: #9ca3af;
+  --color-gray-500: #6b7280;
+  --color-gray-600: #4b5563;
+  --color-gray-700: #374151;
+  --color-gray-800: #1f2937;
+  --color-gray-900: #111827;
+
+  /* Blue scale */
+  --color-blue-400: #60a5fa;
+  --color-blue-500: #3b82f6;
+  --color-blue-600: #2563eb;
+
+  /* Green scale */
+  --color-green-400: #4ade80;
+  --color-green-500: #22c55e;
+  --color-green-600: #16a34a;
+
+  /* Red scale */
+  --color-red-400: #f87171;
+  --color-red-500: #ef4444;
+  --color-red-600: #dc2626;
+
+  /* Z-index scale - Inspector must be above everything on the page */
+  --z-inspector-root: 2147483640;
+  --z-inspector-backdrop: 2147483641;
+  --z-inspector-overlay: 2147483642;
+  --z-inspector-controlbox: 2147483643;
+  --z-inspector-popover: 2147483644;
+  --z-inspector-tooltip: 2147483645;
+  
+  /* Legacy values for backwards compatibility */
+  --z-dropdown: 1000;
+  --z-sticky: 1020;
+  --z-fixed: 1030;
+  --z-modal-backdrop: 1040;
+  --z-modal: 1050;
+  --z-popover: var(--z-inspector-popover);
+  --z-tooltip: var(--z-inspector-tooltip);
+  --z-overlay: var(--z-inspector-overlay);
+  --z-max: var(--z-inspector-root);
+
+  /* Transitions */
+  --transition-fast: 150ms cubic-bezier(0.4, 0, 0.2, 1);
+  --transition-base: 200ms cubic-bezier(0.4, 0, 0.2, 1);
+  --transition-slow: 300ms cubic-bezier(0.4, 0, 0.2, 1);
+
+  /* Typography */
+  --text-xs: 0.75rem; /* 12px */
+  --text-sm: 0.875rem; /* 14px */
+  --text-base: 1rem; /* 16px */
+  --text-lg: 1.125rem; /* 18px */
+  --text-xl: 1.25rem; /* 20px */
+
+  --font-normal: 400;
+  --font-medium: 500;
+  --font-semibold: 600;
+  --font-bold: 700;
+
+  --letter-spacing-tight: -0.01em;
+  --letter-spacing-normal: 0;
+  --letter-spacing-wide: 0.025em;
+  --letter-spacing-widest: 0.1em;
+
+  --font-size-xs: 0.75rem;
+  --font-size-sm: 0.875rem;
+  --font-size-base: 1rem;
+  --font-size-xl: 1.25rem;
+
+  --font-weight-normal: 400;
+  --font-weight-medium: 500;
+  --font-weight-semibold: 600;
+  --font-weight-bold: 700;
+
+  /* Font families */
+  --font-family-sans: 'Satoshi', -apple-system, BlinkMacSystemFont, "Segoe UI", "Roboto",
+    "Oxygen", "Ubuntu", "Cantarell", "Fira Sans", "Droid Sans", "Helvetica Neue",
+    sans-serif;
+  --font-family-mono: ui-monospace, "SF Mono", "Monaco", "Cascadia Mono",
+    "Roboto Mono", "Courier New", monospace;
+}

package/src/styles.ts

@@ -0,0 +1,5 @@
+/**
+ * Import this file to load inspector styles
+ */
+import "./styles/global.css";
+

package/src/utils/colorUtils.ts

@@ -0,0 +1,133 @@
+/**
+ * Color utility functions for converting between formats
+ */
+
+/**
+ * Convert RGB color string to HEX format
+ * @example rgbToHex('rgb(255, 0, 0)') => '#ff0000'
+ */
+export function rgbToHex(rgb: string): string {
+  // Handle rgba as well
+  const match = rgb.match(/\d+/g);
+  if (!match || match.length < 3) return "#000000";
+
+  const r = parseInt(match[0]);
+  const g = parseInt(match[1]);
+  const b = parseInt(match[2]);
+
+  return "#" + [r, g, b].map((x) => x.toString(16).padStart(2, "0")).join("");
+}
+
+/**
+ * Convert HEX color to RGB format
+ * @example hexToRgb('#ff0000') => 'rgb(255, 0, 0)'
+ */
+export function hexToRgb(hex: string): string {
+  // Remove # if present
+  hex = hex.replace(/^#/, "");
+
+  // Parse hex values
+  const r = parseInt(hex.substring(0, 2), 16);
+  const g = parseInt(hex.substring(2, 4), 16);
+  const b = parseInt(hex.substring(4, 6), 16);
+
+  return `rgb(${r}, ${g}, ${b})`;
+}
+
+/**
+ * Convert HEX color to RGBA object
+ * @example hexToRgba('#ff0000') => { r: 255, g: 0, b: 0, a: 1 }
+ * @example hexToRgba('#f00') => { r: 255, g: 0, b: 0, a: 1 }
+ * @example hexToRgba('#ff000080') => { r: 255, g: 0, b: 0, a: 0.5 }
+ */
+export function hexToRgba(
+  hex: string
+): { r: number; g: number; b: number; a: number } | null {
+  // Remove # if present
+  hex = hex.replace(/^#/, "");
+
+  // Validate and normalize hex
+  if (/^[0-9A-Fa-f]{3}$/.test(hex)) {
+    // Expand 3-digit hex to 6-digit (e.g., 'f00' -> 'ff0000')
+    hex = hex
+      .split("")
+      .map((char) => char + char)
+      .join("");
+  } else if (!/^[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$/.test(hex)) {
+    // Must be 6 or 8 digits
+    return null;
+  }
+
+  // Parse RGB values
+  const r = parseInt(hex.substring(0, 2), 16);
+  const g = parseInt(hex.substring(2, 4), 16);
+  const b = parseInt(hex.substring(4, 6), 16);
+
+  // Parse alpha if present (8-digit hex)
+  let a = 1;
+  if (hex.length === 8) {
+    a = parseInt(hex.substring(6, 8), 16) / 255;
+  }
+
+  return { r, g, b, a };
+}
+
+/**
+ * Convert RGBA object to HEX format
+ * @example rgbaToHex({ r: 255, g: 0, b: 0, a: 1 }) => '#ff0000'
+ * @example rgbaToHex({ r: 255, g: 0, b: 0, a: 0.5 }) => '#ff000080'
+ */
+export function rgbaToHex(rgba: {
+  r: number;
+  g: number;
+  b: number;
+  a: number;
+}): string {
+  const r = Math.round(Math.max(0, Math.min(255, rgba.r)));
+  const g = Math.round(Math.max(0, Math.min(255, rgba.g)));
+  const b = Math.round(Math.max(0, Math.min(255, rgba.b)));
+  const a = Math.max(0, Math.min(1, rgba.a));
+
+  const toHex = (n: number) => n.toString(16).padStart(2, "0");
+
+  const hex = `#${toHex(r)}${toHex(g)}${toHex(b)}`;
+
+  // Only include alpha if not fully opaque
+  if (a < 1) {
+    const alphaHex = toHex(Math.round(a * 255));
+    return `${hex}${alphaHex}`;
+  }
+
+  return hex;
+}
+
+/**
+ * Validate if string is a valid hex color
+ */
+export function isValidHex(hex: string): boolean {
+  return /^#?[0-9A-Fa-f]{6}$/.test(hex);
+}
+
+/**
+ * Ensure color string has # prefix
+ */
+export function ensureHashPrefix(color: string): string {
+  if (color.startsWith("#")) return color;
+  if (/^[0-9A-Fa-f]{6}$/.test(color)) return "#" + color;
+  return color;
+}
+
+/**
+ * Get contrasting text color (black or white) for a background color
+ */
+export function getContrastColor(hexColor: string): string {
+  const color = hexColor.replace("#", "");
+  const r = parseInt(color.substring(0, 2), 16);
+  const g = parseInt(color.substring(2, 4), 16);
+  const b = parseInt(color.substring(4, 6), 16);
+
+  // Calculate luminance
+  const luminance = (0.299 * r + 0.587 * g + 0.114 * b) / 255;
+
+  return luminance > 0.5 ? "#000000" : "#ffffff";
+}

package/src/utils/elementNames.ts

@@ -0,0 +1,103 @@
+/**
+ * Element name mapping utilities
+ * Maps HTML tags to user-friendly names
+ */
+
+// Default English values for labels
+const DEFAULT_LABELS: Record<string, string> = {
+  elementContainer: "Container",
+  elementText: "Text",
+  elementImage: "Image",
+  elementButton: "Button",
+  elementLink: "Link",
+  elementInput: "Input",
+  elementTextArea: "TextArea",
+  elementHeading: "Heading",
+  elementParagraph: "Paragraph",
+  elementSection: "Section",
+  elementDefault: "Element",
+};
+
+// Track which labels have been warned about to avoid spam
+const warnedLabels = new Set<string>();
+
+/**
+ * Validates and retrieves a label with runtime warning for missing labels
+ */
+function validateLabel(
+  key: string,
+  labels: Record<string, string> | undefined,
+  defaultValue: string
+): string {
+  if (!labels || !labels[key]) {
+    // Only warn once per missing label
+    if (!warnedLabels.has(key)) {
+      console.warn(
+        `[Inspector] Missing label: "${key}". Using default: "${defaultValue}". ` +
+          `Please add this label to your InspectorLabels configuration.`
+      );
+      warnedLabels.add(key);
+    }
+    return defaultValue;
+  }
+  return labels[key];
+}
+
+export const getElementDisplayName = (
+  element: HTMLElement | Element,
+  labels?: Record<string, string>
+): string => {
+  if (!element || !element.tagName) {
+    return validateLabel(
+      "elementDefault",
+      labels,
+      DEFAULT_LABELS.elementDefault
+    );
+  }
+
+  const tagName = element.tagName.toLowerCase();
+
+  // Map HTML tags to label keys
+  const tagToLabelKey: Record<string, string> = {
+    div: "elementContainer",
+    span: "elementText",
+    img: "elementImage",
+    button: "elementButton",
+    a: "elementLink",
+    input: "elementInput",
+    textarea: "elementTextArea",
+    h1: "elementHeading",
+    h2: "elementHeading",
+    h3: "elementHeading",
+    h4: "elementHeading",
+    h5: "elementHeading",
+    h6: "elementHeading",
+    p: "elementParagraph",
+    section: "elementSection",
+  };
+
+  // Special cases that don't need labels
+  if (tagName === "svg" || tagName === "path") {
+    return "Icon";
+  }
+
+  const labelKey = tagToLabelKey[tagName];
+  if (labelKey) {
+    return validateLabel(labelKey, labels, DEFAULT_LABELS[labelKey]);
+  }
+
+  return validateLabel("elementDefault", labels, DEFAULT_LABELS.elementDefault);
+};
+
+export const getElementLabel = (
+  element: HTMLElement | Element,
+  labels?: Record<string, string>
+): string => {
+  if (!element || !element.tagName) {
+    return "Element";
+  }
+
+  const displayName = getElementDisplayName(element, labels);
+  const tagName = element.tagName.toLowerCase();
+  return `${displayName} (${tagName})`;
+};

package/src/utils/elementUtils.ts

@@ -0,0 +1,90 @@
+/**
+ * Element detection utilities for determining which style sections to show
+ */
+
+/**
+ * Determine if a specific section should be shown for an element
+ */
+export function shouldShowSection(
+  element: HTMLElement,
+  section: string
+): boolean {
+  const tagName = element.tagName.toLowerCase();
+
+  switch (section) {
+    case "layout":
+      // Show for all elements
+      return true;
+
+    case "display":
+      // Show for all elements
+      return true;
+
+    case "text":
+      // Hide for img, input, textarea, video, audio, canvas
+      if (
+        ["img", "input", "textarea", "video", "audio", "canvas", "svg"].includes(
+          tagName
+        )
+      ) {
+        return false;
+      }
+      // Show if element has text content or can contain text
+      return true;
+
+    case "image":
+      // Only show for img elements
+      return tagName === "img";
+
+    case "border":
+      // Show for all elements
+      return true;
+
+    case "spacing":
+      // Show for all elements
+      return true;
+
+    default:
+      return true;
+  }
+}
+
+/**
+ * Get element type for conditional rendering
+ */
+export function getElementType(element: HTMLElement): string {
+  return element.tagName.toLowerCase();
+}
+
+/**
+ * Check if element is a specific type
+ */
+export function isElementType(
+  element: HTMLElement,
+  type: string
+): boolean {
+  return element.tagName.toLowerCase() === type;
+}
+
+/**
+ * Check if element can have text content
+ */
+export function canHaveTextContent(element: HTMLElement): boolean {
+  const tagName = element.tagName.toLowerCase();
+  return !["img", "input", "video", "audio", "canvas"].includes(tagName);
+}
+
+/**
+ * Check if element is an image
+ */
+export function isImage(element: HTMLElement): boolean {
+  return element.tagName.toLowerCase() === "img";
+}
+
+/**
+ * Check if element is an anchor tag
+ */
+export function isAnchor(element: HTMLElement): boolean {
+  return element.tagName.toLowerCase() === "a";
+}
+