@stsgs1980/fab-inspector 3.4.1

package/README.md

@@ -0,0 +1,146 @@
+# FabInspector
+
+Визуальный инспектор элементов для Next.js dev mode. Плавающая FAB-кнопка с draggable панелью в GitHub Dark Theme, подсветкой синтаксиса и box-model визуализацией.
+
+![React 19](https://img.shields.io/badge/React-19-61DAFB?style=flat-square&logo=react)
+![Next.js 15+](https://img.shields.io/badge/Next.js-15%2B-000000?style=flat-square&logo=nextdotjs)
+![License: MIT](https://img.shields.io/badge/License-MIT-green?style=flat-square)
+
+## Что делает
+
+При клике на любой DOM-элемент показывает:
+
+- Источник: файл и строка через `data-src` атрибут
+- CSS-классы, текст, CSS Path, HTML-код
+- Вычисленные стили (размер, шрифт, цвет)
+- Box Model: визуальная схема margin / border / padding / content
+- Сниппет исходного кода с подсветкой синтаксиса
+- Copy task context: структурированный промпт (файл + тег + текст)
+- Copy file:line в буфер обмена
+- Quick-copy в свёрнутой панели (тег + классы + текст)
+
+Панель по умолчанию свёрнута (только заголовок), раскрывается по клику на шеврон. Перетаскивается за заголовок.
+
+## Установка
+
+### npm / bun
+
+```bash
+bun add @stsgs1980/fab-inspector -D
+# или
+npm install @stsgs1980/fab-inspector -D
+```
+
+Peer dependencies (если ещё не стоят):
+
+```bash
+bun add framer-motion react-syntax-highlighter
+```
+
+### Подключение (одна команда)
+
+```bash
+npx @stsgs1980/fab-inspector init
+```
+
+CLI автоматически:
+- Создаёт `src/app/api/source/route.ts` (re-export GET из пакета)
+- Добавляет `import { SelectElementFab } from '@stsgs1980/fab-inspector'` в `src/app/layout.tsx`
+- Вставляет `<SelectElementFab />` перед `</body>`
+- Проверяет наличие peer dependencies
+
+Идемпотентно — безопасно запускать сколько угодно раз.
+
+### Ручная установка
+
+```tsx
+// src/app/layout.tsx:
+import { SelectElementFab } from '@stsgs1980/fab-inspector';
+// В JSX перед </body>:
+<SelectElementFab />
+```
+
+```ts
+// src/app/api/source/route.ts:
+export { GET } from '@stsgs1980/fab-inspector/api/source';
+```
+
+## Обновление
+
+```bash
+bun update @stsgs1980/fab-inspector
+# или
+npm update @stsgs1980/fab-inspector
+```
+
+## Использование
+
+### Режим инспекции
+
+- FAB-кнопка в правом нижнем углу включает режим инспекции
+- Клик по элементу показывает свёрнутую панель (тег, ID, файл:строка)
+- Шеврон раскрывает все секции
+- Esc закрывает инспектор
+- Панель перетаскивается за заголовок
+
+### Кнопки в заголовке панели
+
+| Кнопка | Действие | Доступна без `data-src` |
+|--------|----------|-------------------------|
+| Документ | Copy task context (файл, тег, текст) | нет |
+| Два прямоугольника | Copy file:line | нет |
+| Копировать | Quick-copy (тег + классы + текст) | **да** |
+| Шеврон | Свернуть / развернуть секции | да |
+| x | Закрыть панель | да |
+
+### data-src атрибут
+
+Для отображения источника добавьте `data-src` на JSX-элементы:
+
+```tsx
+<h1 data-src="src/components/sections/hero.tsx:12">Заголовок</h1>
+```
+
+Инспектор поднимается по DOM-дереву и найдёт ближайший `data-src`.
+
+> **Next.js 16 note:** Авто-проставление `data-src` через Turbopack plugin в Next.js 16 больше не работает (API `experimental.turbo.plugins` удалён). Проставляйте `data-src` вручную на ключевых элементах. SWC plugin для авто-разметки — в планах.
+
+## Конфигурация
+
+### Зависимости (peerDependencies)
+
+| Пакет | Версия |
+|-------|--------|
+| `framer-motion` | >= 11.0 |
+| `react-syntax-highlighter` | >= 15.0 |
+| `next` | >= 15.0 |
+| `react` | >= 19.0 |
+
+### Production safety
+
+- Пакет ставится в `devDependencies` — в production-bundle не попадает
+- Компонент `SelectElementFab` имеет dev-only guard: `if (process.env.NODE_ENV !== 'development') return null`
+- `sideEffects: false` — tree-shaking вырезает неиспользуемый код
+
+### API-роут `/api/source`
+
+Создаётся CLI `init` автоматически. Принимает `file`, `line`, `ctx` (контекст строк). Файл валидируется по белому списку директорий (`src/components/`, `src/app/`, `src/content/`, `src/hooks/`, `src/lib/`).
+
+## Структура модуля
+
+- `index.ts` — Barrel export
+- `types.ts` — Интерфейсы (ElementInfo, SourceInfo, BoxModel, SnippetData)
+- `select-element-fab.tsx` — Корневой composer
+- `inspector-fab.tsx` — FAB-кнопка
+- `inspector-panel.tsx` — Draggable сворачиваемая панель
+- `highlight-overlay.tsx` — Подсветка элемента
+- `panel-sections.tsx` — Секции панели (Source, Classes, Text, CSS Path, HTML, Styles, Snippet)
+- `box-model-section.tsx` — Box Model диаграмма
+- `use-element-inspector.ts` — Хук инспекции
+- `use-panel-drag.ts` — Хук перетаскивания
+- `api-source-route.ts` — GET handler для `/api/source`
+- `cli/init.mjs` — CLI `npx @stsgs1980/fab-inspector init`
+
+## License
+
+MIT

package/api-source-route.ts

@@ -0,0 +1,60 @@
+// Шаблон API-роута для установки.
+// В проекте-потребителе создайте src/app/api/source/route.ts:
+//   export { GET } from '@stsgs1980/fab-inspector/api/source';
+// Либо, если модуль подключён как локальный путь:
+//   export { GET } from '@/components/inspector/api-source-route';
+
+import { NextRequest, NextResponse } from 'next/server';
+import { readFile } from 'fs/promises';
+import { resolve } from 'path';
+
+// process.cwd() в Next.js = корень проекта-потребителя.
+// Никаких '..' — иначе путь уходит за пределы проекта и isAllowed() всегда false.
+const PROJECT_ROOT = process.cwd();
+const ALLOWED_PREFIXES = [
+  resolve(PROJECT_ROOT, 'src/components/'),
+  resolve(PROJECT_ROOT, 'src/app/'),
+  resolve(PROJECT_ROOT, 'src/content/'),
+  resolve(PROJECT_ROOT, 'src/hooks/'),
+  resolve(PROJECT_ROOT, 'src/lib/'),
+];
+
+function isAllowed(filePath: string): boolean {
+  const resolved = resolve(PROJECT_ROOT, filePath);
+  return ALLOWED_PREFIXES.some((prefix) => resolved.startsWith(prefix));
+}
+
+export async function GET(request: NextRequest) {
+  const { searchParams } = new URL(request.url);
+  const file = searchParams.get('file');
+  const line = parseInt(searchParams.get('line') || '1', 10);
+  const ctx = parseInt(searchParams.get('ctx') || '8', 10);
+
+  if (!file || !isAllowed(file)) {
+    return NextResponse.json({ error: 'File not allowed' }, { status: 403 });
+  }
+
+  try {
+    const filePath = resolve(PROJECT_ROOT, file);
+    const content = await readFile(filePath, 'utf-8');
+    const lines = content.split('\n');
+
+    const start = Math.max(0, line - 1 - ctx);
+    const end = Math.min(lines.length, line - 1 + ctx + 1);
+    const snippet = lines.slice(start, end);
+    const startLine = start + 1;
+
+    return NextResponse.json({
+      file,
+      line,
+      totalLines: lines.length,
+      snippet: {
+        startLine,
+        lines: snippet,
+        highlightLine: line,
+      },
+    });
+  } catch {
+    return NextResponse.json({ error: 'File not found' }, { status: 404 });
+  }
+}

package/box-model-section.tsx

@@ -0,0 +1,97 @@
+import type { BoxModel } from './types';
+
+function fmt(val: string): string {
+  if (val === '0px') return '0';
+  return val;
+}
+
+function BoxRow({
+  top,
+  right,
+  bottom,
+  left,
+  color,
+  bg,
+  label,
+  inner,
+}: {
+  top: string; right: string; bottom: string; left: string;
+  color: string; bg: string; label: string;
+  inner: React.ReactNode;
+}) {
+  const allSame = top === right && right === bottom && bottom === left;
+  const display = allSame ? fmt(top) : `${fmt(top)} ${fmt(right)} ${fmt(bottom)} ${fmt(left)}`;
+
+  return (
+    <div className="flex items-center gap-2 text-[10px] font-mono">
+      <span className="w-12 text-right text-[#8B949E] flex-shrink-0">{label}</span>
+      <div className="flex-1">
+        <div
+          className="border text-center py-1 text-[#E6EDF3] rounded-sm"
+          style={{ borderColor: color, backgroundColor: bg }}
+        >
+          {allSame ? (
+            <span>{display}</span>
+          ) : (
+            <div className="flex justify-between px-1">
+              <span>{fmt(top)}</span>
+              <span>{fmt(right)}</span>
+              <span>{fmt(bottom)}</span>
+              <span>{fmt(left)}</span>
+            </div>
+          )}
+          <div className="mt-1">{inner}</div>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+export function BoxModelSection({ boxModel }: { boxModel: BoxModel }) {
+  return (
+    <div className="px-4 py-2.5 border-b border-[#30363D]">
+      <div className="text-[11px] font-semibold text-[#8B949E] uppercase tracking-wider mb-2">
+        Box Model
+      </div>
+      <div className="flex flex-col gap-1.5">
+        <BoxRow
+          top={boxModel.marginTop}
+          right={boxModel.marginRight}
+          bottom={boxModel.marginBottom}
+          left={boxModel.marginLeft}
+          color="#D29922"
+          bg="rgba(210, 153, 34, 0.06)"
+          label="margin"
+          inner={
+            <BoxRow
+              top={boxModel.borderTop}
+              right={boxModel.borderRight}
+              bottom={boxModel.borderBottom}
+              left={boxModel.borderLeft}
+              color="#58A6FF"
+              bg="rgba(88, 166, 255, 0.06)"
+              label="border"
+              inner={
+                <BoxRow
+                  top={boxModel.paddingTop}
+                  right={boxModel.paddingRight}
+                  bottom={boxModel.paddingBottom}
+                  left={boxModel.paddingLeft}
+                  color="#3FB950"
+                  bg="rgba(63, 185, 80, 0.06)"
+                  label="padding"
+                  inner={
+                    <div className="text-center py-1 bg-[#0D1117] rounded-sm text-[#E6EDF3]">
+                      <div className="text-[9px] text-[#6E7681]">content</div>
+                      <div>{fmt(boxModel.width)} x {fmt(boxModel.height)}</div>
+                    </div>
+                  }
+                />
+              }
+            />
+          }
+        />
+      </div>
+    </div>
+  );
+}

package/cli/init.mjs

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+/**
+ * @stsgs1980/fab-inspector init
+ *
+ * Автоподключение инспектора в Next.js App Router проект.
+ * Создаёт API-роут /api/source и вставляет импорт + JSX в layout.tsx.
+ * Идемпотентно: безопасно запускать многократно.
+ *
+ * Использование:
+ *   bun add @stsgs1980/fab-inspector -D
+ *   npx @stsgs1980/fab-inspector init
+ */
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+const PKG = '@stsgs1980/fab-inspector';
+const IMPORT_LINE = `import { SelectElementFab } from '${PKG}';`;
+const ROUTE_REL = 'src/app/api/source/route.ts';
+const ROUTE_CONTENT = `// FabInspector source endpoint.
+// Handler живёт внутри npm-пакета — этот файл просто реэкспортирует его.
+// При обновлении пакета ничего менять тут не надо.
+export { GET } from '${PKG}/api/source';
+`;
+
+const LAYOUT_CANDIDATES = [
+  'src/app/layout.tsx',
+  'src/app/layout.ts',
+  'src/app/page.tsx',
+  'src/app/page.ts',
+];
+
+function findLayout(cwd) {
+  for (const f of LAYOUT_CANDIDATES) {
+    const p = resolve(cwd, f);
+    if (existsSync(p)) return p;
+  }
+  return null;
+}
+
+function ensureImport(code) {
+  if (code.includes('SelectElementFab')) return { code, added: false };
+  const lines = code.split('\n');
+  let lastImportIdx = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (/^import\s/.test(lines[i])) lastImportIdx = i;
+  }
+  if (lastImportIdx === -1) {
+    return { code: IMPORT_LINE + '\n' + code, added: true };
+  }
+  lines.splice(lastImportIdx + 1, 0, IMPORT_LINE);
+  return { code: lines.join('\n'), added: true };
+}
+
+function ensureJsx(code) {
+  if (code.includes('<SelectElementFab')) return { code, added: false };
+
+  // </body> — стандартный случай для App Router root layout
+  const bodyMatch = code.match(/^(\s*)<\/body>/m);
+  if (bodyMatch) {
+    const indent = bodyMatch[1];
+    const insertion = `${indent}  <SelectElementFab />\n${indent}</body>`;
+    return { code: code.replace(/^(\s*)<\/body>/m, insertion), added: true };
+  }
+
+  // </html> — если почему-то нет body
+  const htmlMatch = code.match(/^(\s*)<\/html>/m);
+  if (htmlMatch) {
+    const indent = htmlMatch[1];
+    const insertion = `${indent}  <SelectElementFab />\n${indent}</html>`;
+    return { code: code.replace(/^(\s*)<\/html>/m, insertion), added: true };
+  }
+
+  return { code, added: false };
+}
+
+function ensureRoute(cwd) {
+  const p = resolve(cwd, ROUTE_REL);
+  if (existsSync(p)) return false;
+  mkdirSync(resolve(cwd, 'src/app/api/source'), { recursive: true });
+  writeFileSync(p, ROUTE_CONTENT);
+  return true;
+}
+
+function detectMissingPeers(cwd) {
+  const pkgPath = resolve(cwd, 'package.json');
+  if (!existsSync(pkgPath)) return [];
+  const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+  const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+  const peers = ['framer-motion', 'react-syntax-highlighter'];
+  return peers.filter((p) => !deps[p]);
+}
+
+function main() {
+  const cwd = process.cwd();
+  console.log('');
+  console.log('  @stsgs1980/fab-inspector — init');
+  console.log('  --------------------------------');
+
+  const layout = findLayout(cwd);
+  if (!layout) {
+    console.error('  X  No src/app/layout.tsx or src/app/page.tsx found.');
+    console.error('     Run from the root of a Next.js App Router project.');
+    process.exit(1);
+  }
+
+  const relLayout = layout.replace(cwd + '/', '');
+  let code = readFileSync(layout, 'utf-8');
+
+  const importRes = ensureImport(code);
+  code = importRes.code;
+  const jsxRes = ensureJsx(code);
+  code = jsxRes.code;
+
+  if (importRes.added || jsxRes.added) {
+    writeFileSync(layout, code);
+    console.log(`  +  Updated ${relLayout}`);
+  } else {
+    console.log(`  ok Already wired: ${relLayout}`);
+  }
+
+  const created = ensureRoute(cwd);
+  console.log(created
+    ? `  +  Created ${ROUTE_REL}`
+    : `  ok Already exists: ${ROUTE_REL}`);
+
+  const missing = detectMissingPeers(cwd);
+  console.log('');
+  if (missing.length) {
+    console.log('  !  Peer dependencies missing:');
+    missing.forEach((p) => console.log(`        - ${p}`));
+    console.log('     Install them:');
+    console.log(`        bun add ${missing.join(' ')}`);
+    console.log('     (or: npm i ' + missing.join(' ') + ' -D)');
+  } else {
+    console.log('  ok Peer dependencies installed');
+  }
+
+  console.log('');
+  console.log('  Start dev server — FAB appears bottom-right.');
+  console.log('  Press Esc to close inspector.');
+  console.log('');
+}
+
+main();

package/highlight-overlay.tsx

@@ -0,0 +1,23 @@
+export function HighlightOverlay({
+  highlightBox,
+}: {
+  highlightBox: DOMRect;
+}) {
+  return (
+    <div
+      data-se-highlight
+      className="fixed pointer-events-none z-[90]"
+      style={{
+        top: highlightBox.top,
+        left: highlightBox.left,
+        width: highlightBox.width,
+        height: highlightBox.height,
+        border: '1px dashed #58A6FF',
+        backgroundColor: 'rgba(56, 139, 253, 0.06)',
+        borderRadius: '3px',
+        transition: 'all 0.1s ease-out',
+      }}
+      aria-hidden="true"
+    />
+  );
+}

package/index.ts

@@ -0,0 +1,10 @@
+export { SelectElementFab } from './select-element-fab';
+
+export type {
+  SourceInfo,
+  ElementInfo,
+  SnippetData,
+  BoxModel,
+} from './types';
+
+export { dataSrcPlugin } from './plugins/data-src-plugin';

package/inspector-fab.tsx

@@ -0,0 +1,63 @@
+import { motion, AnimatePresence } from 'framer-motion';
+
+export function InspectorFab({
+  active,
+  onToggle,
+  showTooltip,
+}: {
+  active: boolean;
+  onToggle: () => void;
+  showTooltip: boolean;
+}) {
+  return (
+    <>
+      <motion.button
+        data-se-fab
+        onClick={onToggle}
+        className={`
+          fixed bottom-6 right-6 z-[90] w-12 h-12 rounded-full
+          flex items-center justify-center
+          shadow-lg transition-all duration-200 cursor-pointer
+          focus:outline-none focus-visible:ring-2 focus-visible:ring-[#58A6FF] focus-visible:ring-offset-2 focus-visible:ring-offset-[#0D1117]
+          ${active
+            ? 'bg-[#1F6FEB] text-[#F0F6FC] shadow-[#1F6FEB]/30'
+            : 'bg-[#21262D] text-[#E6EDF3]/80 hover:bg-[#30363D] hover:text-[#E6EDF3] shadow-black/40'
+          }
+        `}
+        whileHover={{ scale: 1.08 }}
+        whileTap={{ scale: 0.95 }}
+        aria-label={active ? 'Закрыть инспектор элементов' : 'Открыть инспектор элементов'}
+        title={active ? 'Закрыть инспектор (Esc)' : 'Инспектор элементов'}
+      >
+        {active ? (
+          <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+            <path d="M18 6 6 18" />
+            <path d="m6 6 12 12" />
+          </svg>
+        ) : (
+          <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+            <path d="m19 19-14-14" />
+            <path d="m5 5 14 0" />
+            <path d="m5 5 0 14" />
+          </svg>
+        )}
+        <span className="absolute -top-1 -right-1 min-w-[16px] h-4 px-1 rounded-full bg-[#58A6FF] text-[#0D1117] text-[9px] font-bold flex items-center justify-center leading-none select-none">
+          3.4.1
+        </span>
+      </motion.button>
+
+      <AnimatePresence>
+        {showTooltip && (
+          <motion.div
+            initial={{ opacity: 0, y: 8 }}
+            animate={{ opacity: 1, y: 0 }}
+            exit={{ opacity: 0, y: 8 }}
+            className="fixed bottom-20 right-6 z-[90] bg-[#21262D] text-[#E6EDF3] text-xs px-3 py-1.5 rounded-lg shadow-lg border border-[#30363D] whitespace-nowrap pointer-events-none"
+          >
+            Кликните на элемент для инспекции
+          </motion.div>
+        )}
+      </AnimatePresence>
+    </>
+  );
+}