highlite 0.1.0

data/lib/highlite/engine.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Highlite
+  class Engine < ::Rails::Engine
+    isolate_namespace Highlite
+
+    initializer "highlite.assets" do |app|
+      if app.config.respond_to?(:assets)
+        app.config.assets.paths << root.join("app/assets/stylesheets")
+        app.config.assets.paths << root.join("app/javascript")
+      end
+    end
+
+    initializer "highlite.importmap", before: "importmap" do |app|
+      if app.config.respond_to?(:importmap)
+        app.config.importmap.paths << root.join("config/importmap.rb")
+      end
+    end
+
+    initializer "highlite.helpers" do
+      ActiveSupport.on_load(:action_controller_base) do
+        helper Highlite::ApplicationHelper
+      end
+    end
+  end
+end

data/lib/highlite/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Highlite
+  VERSION = "0.1.0"
+end

data/lib/highlite.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative "highlite/version"
+require_relative "highlite/configuration"
+require_relative "highlite/engine" if defined?(Rails)
+
+module Highlite
+  class Error < StandardError; end
+
+  def self.configure
+    yield Configuration.instance
+  end
+
+  def self.configuration
+    Configuration.instance
+  end
+end

data/sig/highlite.rbs

@@ -0,0 +1,4 @@
+module Highlite
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

data/tasks/todo.md

@@ -0,0 +1,129 @@
+# Highlite Gem — Build Plan
+
+## Overview
+
+A Ruby gem (Rails engine) that provides a full-featured PDF viewer with highlighting, modeled after [react-pdf-highlighter-plus](https://react-pdf-highlighter-plus-demo.vercel.app/pdf-demo). Built for Rails 8 + Hotwire (Stimulus) + Tailwind CSS + Import Maps.
+
+## Architecture
+
+### Three-panel layout
+- **Left sidebar** (gem-owned): Outline tab (TOC from PDF metadata) + Pages tab (thumbnails)
+- **Center** (gem-owned): PDF.js canvas rendering + text layer + highlight overlay
+- **Right sidebar** (default + overridable): Highlights list with search, grouped by page. Users can replace with their own partial.
+
+### Key design decisions
+- **Stimulus controllers** dispatch custom events (`highlite:highlight-created`, etc.) so host apps can react
+- **Right sidebar override** — ships a default highlights panel, but host apps can provide their own partial at `app/views/highlite/_right_sidebar.html.erb` which takes precedence (Rails engine view override convention)
+- **PDF.js via CDN** (jsdelivr) — pinned in engine's importmap config, no npm required
+- **localStorage by default** for highlight persistence, with an optional `Highlightable` model concern for server-side storage
+- **tailwindcss-ruby** (`flavorjones/tailwindcss-ruby`) — compiles Tailwind CSS within the gem so the host app doesn't need Tailwind installed (but works great if they do)
+- **CSS strategy** — gem ships a pre-compiled CSS file built with tailwindcss-ruby during development; the host app includes it via `stylesheet_link_tag "highlite/viewer"`
+
+### Stimulus event API (dispatched on the viewer element)
+```
+highlite:document-loaded   { detail: { pageCount, title, outline } }
+highlite:page-changed      { detail: { page, totalPages } }
+highlite:highlight-created  { detail: { id, page, type, color, text, rects } }
+highlite:highlight-removed  { detail: { id } }
+highlite:highlight-selected { detail: { id, page } }
+highlite:highlights-cleared { detail: { page } }  // null page = all
+```
+
+## Directory structure
+
+```
+highlite/
+├── highlite.gemspec
+├── Gemfile
+├── Rakefile
+├── README.md
+├── lib/
+│   ├── highlite.rb                        # Main entry + autoload
+│   ├── highlite/
+│   │   ├── version.rb
+│   │   ├── engine.rb                             # Rails engine config + importmap
+│   │   └── configuration.rb                      # Config DSL (pdf.js version, colors, etc.)
+│   └── generators/
+│       └── highlite/
+│           └── install/
+│               ├── install_generator.rb           # rails g highlite:install
+│               └── templates/
+│                   ├── initializer.rb.tt
+│                   └── _right_sidebar.html.erb.tt # Override template
+├── app/
+│   ├── assets/
+│   │   └── stylesheets/
+│   │       └── highlite/
+│   │           └── viewer.css                     # Minimal required styles (text layer, etc.)
+│   ├── javascript/
+│   │   └── highlite/
+│   │       ├── index.js                           # Registers all controllers with Stimulus
+│   │       ├── controllers/
+│   │       │   ├── viewer_controller.js           # PDF.js rendering, zoom, scroll
+│   │       │   ├── highlight_controller.js        # Drawing + managing highlights
+│   │       │   ├── sidebar_controller.js          # Left sidebar (outline + pages tabs)
+│   │       │   └── highlights_panel_controller.js # Right sidebar (default highlight list)
+│   │       └── lib/
+│   │           ├── pdf_renderer.js                # PDF.js wrapper (load, render, text layer)
+│   │           └── highlight_store.js             # State management + localStorage
+│   ├── helpers/
+│   │   └── highlite/
+│   │       └── application_helper.rb              # highlite_viewer helper method
+│   └── views/
+│       └── highlite/
+│           ├── _viewer.html.erb                   # Main 3-panel layout
+│           ├── _toolbar.html.erb                  # Top bar (zoom, export, change PDF)
+│           ├── _left_sidebar.html.erb             # Outline + Pages tabs
+│           ├── _right_sidebar.html.erb            # Default highlights panel
+│           └── _floating_toolbar.html.erb         # Annotation tool buttons
+└── spec/
+    ├── spec_helper.rb
+    └── lib/
+        └── highlite_spec.rb
+```
+
+## Build tasks
+
+### Phase 1: Foundation
+- [ ] 1.1 Set up gemspec with correct dependencies (rails >= 7.1, importmap-rails)
+- [ ] 1.2 Create Rails engine (Highlite::Engine) with importmap config
+- [ ] 1.3 Create Configuration class (pdf_js_version, default_colors, toolbar_tools, right_sidebar_partial)
+- [ ] 1.4 Create install generator (initializer + optional sidebar override template)
+- [ ] 1.5 Create viewer helper method: `highlite_viewer(url:, document_id:, **options)`
+
+### Phase 2: Core JavaScript — PDF Viewer
+- [ ] 2.1 Build pdf_renderer.js — PDF.js wrapper (load document, render page to canvas, text layer, get outline, render thumbnail)
+- [ ] 2.2 Build viewer_controller.js — Stimulus controller (renders PDF, handles zoom [Auto/fit/%, +, -], page scroll tracking, keyboard nav)
+- [ ] 2.3 Build highlight_store.js — State manager (add/remove/update/query highlights, localStorage read/write, event dispatch)
+
+### Phase 3: Highlighting
+- [ ] 3.1 Build highlight_controller.js — Text selection highlighting (capture Selection API ranges → rects, apply color)
+- [ ] 3.2 Add area/rectangle highlighting mode (mousedown→drag→mouseup drawing)
+- [ ] 3.3 Highlight rendering (colored overlay divs with mix-blend-mode: multiply)
+- [ ] 3.4 Highlight interaction (click to select, right-click to remove, hover effect)
+- [ ] 3.5 Multiple highlight colors (toolbar color picker)
+
+### Phase 4: Left Sidebar
+- [ ] 4.1 Build sidebar_controller.js — Tab switching (Outline / Pages)
+- [ ] 4.2 Outline tab — Extract TOC from PDF metadata, render hierarchical tree, click-to-navigate, blue dots for pages with highlights
+- [ ] 4.3 Pages tab — Render page thumbnails (small canvas), active page border, click-to-navigate, page counter
+
+### Phase 5: Right Sidebar (Default + Override)
+- [ ] 5.1 Build highlights_panel_controller.js — Lists highlights grouped by page, search/filter, clear all
+- [ ] 5.2 Build _right_sidebar.html.erb — Default partial with highlight cards (type badge, quoted text, page link)
+- [ ] 5.3 Implement override mechanism — check for app/views/highlite/_right_sidebar.html.erb in host app, fall back to gem default
+
+### Phase 6: Toolbar & Polish
+- [ ] 6.1 Build _toolbar.html.erb — Top bar (zoom controls, page info)
+- [ ] 6.2 Build _floating_toolbar.html.erb — Vertical tool buttons (select, text highlight, area highlight, colors)
+- [ ] 6.3 Keyboard shortcuts (Ctrl+Z undo, Escape deselect, arrow keys for pages)
+
+### Phase 7: Views & Integration
+- [ ] 7.1 Build _viewer.html.erb — Main layout composing all panels
+- [ ] 7.2 Build viewer.css — Required styles (text layer positioning, highlight blending, sidebar transitions)
+- [ ] 7.3 Wire helper method to render the viewer partial with all options
+- [ ] 7.4 Write README with usage examples, configuration, and override instructions
+
+### Phase 8: Testing
+- [ ] 8.1 RSpec tests for engine loading, configuration, helper output
+- [ ] 8.2 Generator tests (install generator creates expected files)

data/test/dummy/Rakefile

@@ -0,0 +1,3 @@
+require_relative "config/boot"
+require "rails/all"
+require "rake"

data/test/dummy/app/controllers/application_controller.rb

@@ -0,0 +1,2 @@
+class ApplicationController < ActionController::Base
+end

data/test/dummy/app/controllers/documents_controller.rb

@@ -0,0 +1,6 @@
+class DocumentsController < ApplicationController
+  def show
+    @pdf_url = "/convention-over-configuration.pdf"
+    @document_id = "convention-over-configuration"
+  end
+end

data/test/dummy/app/javascript/application.js

@@ -0,0 +1 @@
+import "highlite"

data/test/dummy/app/views/documents/show.html.erb

@@ -0,0 +1 @@
+<%= highlite_viewer(url: @pdf_url, document_id: @document_id) %>

data/test/dummy/app/views/layouts/application.html.erb

@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Highlite Test</title>
+  <meta name="viewport" content="width=device-width,initial-scale=1">
+  <script src="https://cdn.tailwindcss.com"></script>
+  <%= stylesheet_link_tag "highlite/viewer" %>
+  <%= javascript_importmap_tags %>
+</head>
+<body>
+  <%= yield %>
+</body>
+</html>

data/test/dummy/bin/rails

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+APP_PATH = File.expand_path("../config/application", __dir__)
+require_relative "../config/boot"
+require "rails/commands"

data/test/dummy/config/application.rb

@@ -0,0 +1,15 @@
+require_relative "boot"
+
+require "action_controller/railtie"
+require "action_view/railtie"
+require "propshaft"
+require "importmap-rails"
+require "highlite"
+
+module Dummy
+  class Application < Rails::Application
+    config.load_defaults Rails::VERSION::STRING.to_f
+    config.eager_load = false
+    config.secret_key_base = "test-secret-key-base-for-dummy-app"
+  end
+end

data/test/dummy/config/boot.rb

@@ -0,0 +1,2 @@
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../../Gemfile", __dir__)
+require "bundler/setup"

data/test/dummy/config/environment.rb

@@ -0,0 +1,2 @@
+require_relative "application"
+Rails.application.initialize!

data/test/dummy/config/importmap.rb

@@ -0,0 +1,3 @@
+pin "application"
+pin "@hotwired/stimulus", to: "https://cdn.jsdelivr.net/npm/@hotwired/stimulus@3.2.2/dist/stimulus.js"
+pin "highlite", to: "highlite/index.js"

data/test/dummy/config/routes.rb

@@ -0,0 +1,3 @@
+Rails.application.routes.draw do
+  root "documents#show"
+end

data/test/dummy/config.ru

@@ -0,0 +1,2 @@
+require_relative "config/environment"
+run Rails.application

metadata

@@ -0,0 +1,117 @@
+--- !ruby/object:Gem::Specification
+name: highlite
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Nathan Jones
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: importmap-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: A Rails engine that wraps PDF.js to provide a full-featured PDF viewer
+  with text and area highlighting, powered by Stimulus controllers and Tailwind CSS.
+  Includes a three-panel layout with outline/thumbnails sidebar, highlight management,
+  and an overridable right sidebar for custom integrations.
+email:
+- natejones@hey.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".claude/commands/publish.md"
+- README.md
+- Rakefile
+- app/assets/stylesheets/highlite/viewer.css
+- app/helpers/highlite/application_helper.rb
+- app/javascript/highlite/controllers/.keep
+- app/javascript/highlite/controllers/highlight_controller.js
+- app/javascript/highlite/controllers/highlights_panel_controller.js
+- app/javascript/highlite/controllers/sidebar_controller.js
+- app/javascript/highlite/controllers/viewer_controller.js
+- app/javascript/highlite/index.js
+- app/javascript/highlite/lib/.keep
+- app/javascript/highlite/lib/highlight_store.js
+- app/javascript/highlite/lib/pdf_renderer.js
+- app/views/highlite/_floating_toolbar.html.erb
+- app/views/highlite/_left_sidebar.html.erb
+- app/views/highlite/_right_sidebar.html.erb
+- app/views/highlite/_toolbar.html.erb
+- app/views/highlite/_viewer.html.erb
+- config/importmap.rb
+- lib/generators/highlite/install/install_generator.rb
+- lib/generators/highlite/install/templates/_right_sidebar.html.erb.tt
+- lib/generators/highlite/install/templates/initializer.rb.tt
+- lib/highlite.rb
+- lib/highlite/configuration.rb
+- lib/highlite/engine.rb
+- lib/highlite/version.rb
+- sig/highlite.rbs
+- tasks/todo.md
+- test/dummy/Rakefile
+- test/dummy/app/controllers/application_controller.rb
+- test/dummy/app/controllers/documents_controller.rb
+- test/dummy/app/javascript/application.js
+- test/dummy/app/views/documents/show.html.erb
+- test/dummy/app/views/layouts/application.html.erb
+- test/dummy/bin/rails
+- test/dummy/config.ru
+- test/dummy/config/application.rb
+- test/dummy/config/boot.rb
+- test/dummy/config/environment.rb
+- test/dummy/config/importmap.rb
+- test/dummy/config/routes.rb
+- test/dummy/public/convention-over-configuration.pdf
+homepage: https://github.com/nathanjones/highlite
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/nathanjones/highlite
+  source_code_uri: https://github.com/nathanjones/highlite
+  changelog_uri: https://github.com/nathanjones/highlite/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Rails engine providing a PDF viewer with text and area highlighting
+test_files: []