mycowriter 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3cced08d1171031840e8c3fe3464a16cf344ef8665540a9ac879bbc985509beb
+  data.tar.gz: 296ff6a5870048603ed5d9a9e712fc51b9b8865f77fb26de7f54707235377435
+SHA512:
+  metadata.gz: 8bdbaac7edd4d193639c5e0ac78d55a7898ee3de5233ac759955f1bb8b173618fc4eb181216baec09c68c699d0ba75b8a1eafbf096c8ea19c713c3625a073735
+  data.tar.gz: 01140af242628c80ae50b695c12e0138f11dd0d7adfb3abab55993f88b7936ec6f4ed630642a03910496f225a50d891611840db5acc18d9f6bca062b80a48ed3

data/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.1] - 2025-02-20
+
+### Changed
+- **BREAKING:** Changed default `min_characters` from 3 to 4 to reduce false matches
+- Replaced `case_sensitive` config with `require_uppercase` (default: true)
+- Updated JavaScript controller to validate uppercase first letter for genus names
+- Genus names must now start with uppercase letter (e.g., "Agaricus" not "agaricus")
+
+### Added
+- Optional migration generator: `rails generate mycowriter:mb_lists_migration`
+- Comprehensive MycoBank data download and import instructions in README
+- Uppercase validation with helpful user feedback
+- Configuration option `require_uppercase` to enforce genus name capitalization
+- Example import script for MycoBank MBList.xlsx data
+
+### Fixed
+- Prevented constant autocomplete triggers from lowercase input
+- Improved user feedback messages for validation errors
+
+## [0.1.0] - 2025-02-20
+
+### Added
+- Initial release
+- Real-time autocomplete for genus and species names
+- Token-based UI with visual pills and remove buttons
+- Debounced search (150ms delay)
+- MycoBank data integration via mb_lists table
+- Configurable minimum characters and results limit
+- Support for both mb_lists table and custom Genus/Species models
+- Automatic genus filtering for species autocomplete
+- AJAX save/delete for associations
+- Comprehensive documentation and usage examples

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Will Johnston
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,231 @@
+# Mycowriter
+
+Intelligent taxonomic autocomplete for genus and species names in Rails applications. Mycowriter provides real-time autocomplete functionality matching against MycoBank taxonomic data, perfect for mycology, biology, and taxonomy-focused applications.
+
+## Features
+
+- 🔍 **Real-time autocomplete** for genus and species names
+- 🏷️ **Token-based UI** with visual pills and remove buttons
+- ⚡ **Debounced search** (150ms) for optimal performance
+- 🎯 **Smart validation** - default 4 characters minimum, uppercase first letter
+- 📊 **MycoBank integration** via mb_lists table
+- 🔧 **Highly configurable** via initializer
+- 🎨 **Framework agnostic** - works with any CSS framework
+- ♿ **Accessible** with ARIA labels and keyboard support
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'mycowriter'
+```
+
+And then execute:
+
+```bash
+bundle install
+rails generate mycowriter:install
+```
+
+The generator will:
+- Create an initializer at `config/initializers/mycowriter.rb`
+- Mount the engine in your `config/routes.rb`
+- Display setup instructions
+
+## Requirements
+
+### Database Schema
+
+**Option 1: Use the optional migration generator (recommended for new projects)**
+
+```bash
+rails generate mycowriter:mb_lists_migration
+rails db:migrate
+```
+
+This creates the `mb_lists` table with proper indexes and character encoding for taxonomic data.
+
+**Option 2: Use your own Genus/Species models**
+
+Mycowriter will automatically detect and use existing `Genus` and `Species` models in your application. No migration needed!
+
+### Getting MycoBank Data
+
+After creating the `mb_lists` table, you need to populate it with taxonomic data:
+
+1. **Download MycoBank MBList file:**
+   - Visit: https://www.mycobank.org/page/Simple%20names%20search
+   - Or direct download: https://www.mycobank.org/MBList.xlsx
+   - File contains comprehensive fungal taxonomic data
+
+2. **Import the data:**
+
+```ruby
+# Example import script using 'roo' gem
+require 'roo'
+
+xlsx = Roo::Spreadsheet.open('MBList.xlsx')
+xlsx.sheet(0).each_row_streaming(offset: 1) do |row|
+  MbList.create!(
+    mblist_id: row[0]&.value,
+    taxon_name: row[1]&.value,
+    authors: row[2]&.value,
+    rank_name: row[3]&.value,
+    year_of_effective_publication: row[4]&.value,
+    name_status: row[5]&.value,
+    mycobank_number: row[6]&.value,
+    hyperlink: row[7]&.value,
+    classification: row[8]&.value,
+    current_name: row[9]&.value,
+    synonymy: row[10]&.value
+  )
+end
+```
+
+3. **License Requirements (IMPORTANT):**
+
+MycoBank data is licensed under **Creative Commons CC BY-NC-ND**:
+- **BY (Attribution):** Must credit MycoBank
+- **NC (Non-Commercial):** Non-commercial use only
+- **ND (No Derivatives):** Use data in unadapted form
+
+**Required Attribution:**
+> "MBList taxonomic data provided by MycoBank (www.mycobank.org)"
+
+### JavaScript Setup
+
+Register the Stimulus controller in your `app/javascript/controllers/application.js`:
+
+```javascript
+import { application } from "./application"
+import MycowriterAutocomplete from "mycowriter/autocomplete_controller"
+
+application.register("mycowriter--autocomplete", MycowriterAutocomplete)
+```
+
+## Usage
+
+### Basic Genus Autocomplete
+
+```erb
+<div data-controller="mycowriter--autocomplete"
+     data-mycowriter--autocomplete-url-value="<%= mycowriter.genera_autocomplete_path %>"
+     data-mycowriter--autocomplete-kind-value="genera"
+     data-mycowriter--autocomplete-mushroom-id-value="<%= @mushroom.id %>">
+
+  <input type="text"
+         data-mycowriter--autocomplete-target="input"
+         placeholder="Type genus name (e.g., Agaricus)..."
+         minlength="4"
+         class="form-input" />
+
+  <ul data-mycowriter--autocomplete-target="dropdown"
+      class="hidden absolute bg-white border shadow-lg"></ul>
+
+  <div data-mycowriter--autocomplete-target="list"
+       class="flex flex-wrap mt-2"></div>
+
+  <input type="hidden"
+         data-mycowriter--autocomplete-target="hiddenIds"
+         name="mushroom[genus_ids]" />
+</div>
+```
+
+### Species Autocomplete (with Genus Filter)
+
+```erb
+<div data-controller="mycowriter--autocomplete"
+     data-mycowriter--autocomplete-url-value="<%= mycowriter.species_autocomplete_path %>"
+     data-mycowriter--autocomplete-kind-value="species"
+     data-mycowriter--autocomplete-mushroom-id-value="<%= @mushroom.id %>">
+
+  <input type="text"
+         data-mycowriter--autocomplete-target="input"
+         placeholder="Type species name..."
+         minlength="4" />
+
+  <ul data-mycowriter--autocomplete-target="dropdown" class="hidden"></ul>
+  <div data-mycowriter--autocomplete-target="list"></div>
+</div>
+```
+
+## Configuration
+
+Configure Mycowriter in `config/initializers/mycowriter.rb`:
+
+```ruby
+Mycowriter.configure do |config|
+  # Minimum number of characters before autocomplete triggers (default: 4)
+  config.min_characters = 4
+
+  # Require uppercase first letter for genus names (default: true)
+  # Genus names always start with capital letter (e.g., Agaricus, not agaricus)
+  config.require_uppercase = true
+
+  # Maximum number of results to return (default: 20)
+  config.results_limit = 20
+end
+```
+
+## Data Targets
+
+The Stimulus controller expects these targets:
+
+- `input` - The text input field
+- `dropdown` - Container for autocomplete suggestions
+- `list` - Container for selected tokens (pills)
+- `hiddenIds` - Hidden input to store selected IDs
+- `loader` (optional) - Loading indicator
+
+## Data Values
+
+- `url` - API endpoint for autocomplete
+- `min` - Minimum characters (default: 3)
+- `mushroomId` - ID for filtering related records
+- `kind` - Type of autocomplete (genera, species, trees, plants)
+
+## Routes
+
+The gem provides these routes:
+
+```ruby
+GET /mycowriter/autocomplete/genera   # Genus autocomplete
+GET /mycowriter/autocomplete/species  # Species autocomplete
+```
+
+## Integration with Pundit/Devise
+
+The gem automatically skips authentication and authorization checks for the autocomplete endpoints. This is configured in the initializer and can be customized.
+
+## Data Attribution
+
+This gem is designed to work with MycoBank taxonomic data:
+
+**MycoBank License:** Creative Commons CC BY-NC-ND
+- **BY (Attribution):** Credit must be given to MycoBank
+- **NC (Non-Commercial):** Non-commercial use only
+- **ND (No Derivatives):** Data used in unadapted form only
+
+**Attribution:** MBList taxonomic data provided by MycoBank (www.mycobank.org)
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/mrdbidwill/mycowriter.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Links
+
+- **Website:** https://mycowriter.com
+- **Source Code:** https://github.com/mrdbidwill/mycowriter
+- **Documentation:** https://mycowriter.com/docs
+- **MycoBank:** https://www.mycobank.org

data/app/controllers/mycowriter/autocomplete_controller.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Mycowriter
+  class AutocompleteController < ApplicationController
+    skip_after_action :verify_authorized, raise: false
+    skip_before_action :authenticate_user!, raise: false if respond_to?(:authenticate_user!)
+
+    # GET /mycowriter/autocomplete/genera.json?q=aga
+    def genera
+      query = params[:q].to_s.strip
+      results = if query.length >= Mycowriter.min_characters
+                  # Check if the host app has a Genus model
+                  if defined?(::Genus)
+                    ::Genus
+                      .where("name LIKE ?", "#{::Genus.sanitize_sql_like(query)}%")
+                      .select(:id, :name)
+                      .order(:name)
+                      .limit(Mycowriter.results_limit)
+                      .map { |g| { id: g.id, name: g.name } }
+                  else
+                    # Fallback to mb_lists table
+                    autocomplete_from_mb_lists(query, rank: 'genus')
+                  end
+                else
+                  []
+                end
+      render json: results
+    end
+
+    # GET /mycowriter/autocomplete/species.json?q=placo&mushroom_id=1
+    def species
+      query = params[:q].to_s.strip
+      mushroom_id = params[:mushroom_id]
+
+      results = if query.length >= Mycowriter.min_characters
+                  # Check if the host app has a Species model
+                  if defined?(::Species)
+                    scope = ::Species.where("name LIKE ?", "%#{::Species.sanitize_sql_like(query)}%")
+
+                    # Filter by selected genera for this mushroom
+                    if mushroom_id.present? && defined?(::Mushroom)
+                      mushroom = ::Mushroom.find_by(id: mushroom_id)
+                      if mushroom && mushroom.respond_to?(:genera) && mushroom.genera.any?
+                        genera_ids = mushroom.genera.pluck(:id)
+                        scope = scope.where(genera_id: genera_ids)
+                      end
+                    end
+
+                    # Use includes to eager load genera and avoid N+1 queries
+                    species_results = scope
+                      .includes(:genus)
+                      .select(:id, :name, :genera_id)
+                      .order(:name)
+                      .limit(Mycowriter.results_limit)
+
+                    species_results.map do |sp|
+                      genus_label = sp.respond_to?(:genus) && sp.genus ? "#{sp.genus.name} " : ""
+                      { id: sp.id, name: "#{genus_label}#{sp.name}" }
+                    end
+                  else
+                    # Fallback to mb_lists table
+                    autocomplete_from_mb_lists(query, rank: 'species')
+                  end
+                else
+                  []
+                end
+      render json: results
+    end
+
+    private
+
+    # Fallback method to search mb_lists table if host app doesn't have Genus/Species models
+    def autocomplete_from_mb_lists(query, rank: nil)
+      return [] unless defined?(::MbList)
+
+      scope = ::MbList.where("taxon_name LIKE ?", "#{::MbList.sanitize_sql_like(query)}%")
+      scope = scope.where(rank_name: rank) if rank.present?
+
+      scope
+        .select(:id, :taxon_name)
+        .order(:taxon_name)
+        .limit(Mycowriter.results_limit)
+        .map { |m| { id: m.id, name: m.taxon_name } }
+    end
+  end
+end

data/app/javascript/mycowriter/autocomplete_controller.js

@@ -0,0 +1,270 @@
+import { Controller } from "@hotwired/stimulus"
+
+// Mycowriter Autocomplete Controller
+// Provides token-based autocomplete for genus/species names
+//
+// Usage: Attach data-controller="mycowriter--autocomplete" and appropriate data attributes.
+// Requirements: An autocomplete endpoint that returns [{id, name}] in JSON.
+
+export default class extends Controller {
+    static targets = [
+        "input", "dropdown", "list", "hiddenIds", "loader"
+    ]
+    static values = {
+        url: String,
+        min: { type: Number, default: 4 },
+        mushroomId: String,
+        kind: String,
+        requireUppercase: { type: Boolean, default: true }
+    }
+
+    connect() {
+        this.selected = new Map()
+        this.debounceTimer = null
+        this.inputTarget.addEventListener("input", this.onInput.bind(this))
+        this.inputTarget.addEventListener("focus", this.onInput.bind(this))
+        this.listTarget.querySelectorAll("[data-token-id]").forEach(el => {
+            this.selected.set(el.dataset.tokenId, el.textContent.trim())
+        })
+        this.dropdownTarget.addEventListener("click", this.onDropdownClick.bind(this))
+    }
+
+    onInput() {
+        clearTimeout(this.debounceTimer)
+        let query = this.inputTarget.value.trim()
+
+        const minLength = parseInt(this.inputTarget.getAttribute("minlength")) || this.minValue
+
+        // Check for uppercase requirement (genus names start with capital letter)
+        if(this.requireUppercaseValue && query.length > 0 && query[0] !== query[0].toUpperCase()) {
+            this.dropdownTarget.innerHTML = `<li class='px-3 py-2 text-sm text-gray-400'>Genus names start with uppercase (e.g., Agaricus)</li>`
+            this.dropdownTarget.classList.remove("hidden")
+            return
+        }
+
+        // Show immediate feedback
+        if(query.length > 0 && query.length < minLength) {
+            this.dropdownTarget.innerHTML = `<li class='px-3 py-2 text-sm text-gray-400'>Type ${minLength - query.length} more character(s)...</li>`
+            this.dropdownTarget.classList.remove("hidden")
+            return
+        }
+
+        if(query.length < minLength) {
+            this.hideDropdown()
+            return
+        }
+
+        // Show loading immediately before debounce
+        this.showLoader()
+        this.debounceTimer = setTimeout(() => {
+            this.autocomplete(query)
+        }, 150)
+    }
+
+    autocomplete(query) {
+        this.showLoader()
+        const url = new URL(this.urlValue, window.location.origin)
+        url.searchParams.append("q", query)
+
+        // For species autocomplete, pass mushroom_id to filter by selected genera
+        if(this.kindValue === "species" && this.hasMushroomIdValue) {
+            url.searchParams.append("mushroom_id", this.mushroomIdValue)
+        }
+
+        fetch(url, { headers: {"Accept": "application/json"} })
+            .then(r => r.json())
+            .then(items => {
+                this.renderDropdown(items)
+            })
+            .catch(_err => this.hideDropdown())
+            .finally(() => this.hideLoader())
+    }
+
+    renderDropdown(items) {
+        if(!items.length) {
+            this.dropdownTarget.innerHTML = "<li class='px-3 py-2 text-sm text-gray-400'>No results</li>"
+            this.dropdownTarget.classList.remove("hidden")
+            return
+        }
+        this.dropdownTarget.innerHTML = items
+            .map(item =>
+                `<li class="hover:bg-blue-100 cursor-pointer px-3 py-2"
+             data-id="${item.id}"
+             data-label="${item.name}">
+          ${item.name}
+        </li>`
+            ).join("")
+        this.dropdownTarget.classList.remove("hidden")
+    }
+
+    hideDropdown() {
+        this.dropdownTarget.classList.add("hidden")
+        this.dropdownTarget.innerHTML = ""
+    }
+
+    showLoader() {
+        if(this.hasLoaderTarget) this.loaderTarget.classList.remove("hidden")
+    }
+    hideLoader() {
+        if(this.hasLoaderTarget) this.loaderTarget.classList.add("hidden")
+    }
+
+    onDropdownClick(e) {
+        const li = e.target.closest("li[data-id]")
+        if(!li) return
+        const id = li.dataset.id
+        const label = li.dataset.label
+        if(this.selected.has(id)) {
+            this.hideDropdown()
+            this.inputTarget.value = ""
+            return
+        }
+        this.createToken({id, label})
+        this.hideDropdown()
+        this.inputTarget.value = ""
+        this.inputTarget.focus()
+        // Save via AJAX
+        this.saveToken(id, label)
+    }
+
+    createToken({id, label}) {
+        if(this.selected.has(id)) return
+        this.selected.set(id, label)
+        // Create pill
+        const pill = document.createElement("span")
+        pill.className = "inline-flex items-center bg-gray-200 rounded px-2 py-0.5 text-sm mr-1 mb-1"
+        pill.setAttribute("data-token-id", id)
+        pill.innerHTML = `
+      ${label}
+      <button type="button" class="ml-1 text-gray-600 hover:text-red-600" aria-label="Remove" data-action="mycowriter--autocomplete#removeToken" data-id="${id}">&times;</button>
+    `
+        this.listTarget.appendChild(pill)
+        this.updateHiddenIds()
+    }
+
+    removeToken(e) {
+        const id = e.target.dataset.id
+        const pill = this.listTarget.querySelector(`[data-token-id="${id}"]`)
+        const itemName = pill ? pill.textContent.trim().replace('×', '').trim() : 'this item'
+
+        // Show confirmation dialog
+        if (!confirm(`Remove ${itemName}?`)) {
+            return
+        }
+
+        // Remove via AJAX first, then update UI on success
+        this.deleteToken(id, () => {
+            // Success callback
+            this.selected.delete(id)
+            if(pill) pill.remove()
+            this.updateHiddenIds()
+        }, () => {
+            // Error callback - pill stays in place
+        })
+    }
+
+    updateHiddenIds() {
+        if(this.hasHiddenIdsTarget) {
+            this.hiddenIdsTarget.value = Array.from(this.selected.keys()).join(",")
+        }
+    }
+
+    // AJAX save for genus, species, tree, or plant association
+    saveToken(id, label) {
+        const kind = this.kindValue
+        const mushroomId = this.mushroomIdValue
+        if(!kind || !mushroomId) return
+        let route, body
+        if(kind=="genera") {
+            route = `/genus_mushrooms.json`
+            body = JSON.stringify({genus_mushroom: {mushroom_id: mushroomId, genus_id: id}})
+        } else if (kind=="species") {
+            route = `/mushroom_species.json`
+            body = JSON.stringify({mushroom_species: {mushroom_id: mushroomId, species_id: id}})
+        } else if (kind=="trees") {
+            route = `/mushroom_trees.json`
+            body = JSON.stringify({mushroom_tree: {mushroom_id: mushroomId, tree_id: id}})
+        } else if (kind=="plants") {
+            route = `/mushroom_plants.json`
+            body = JSON.stringify({mushroom_plant: {mushroom_id: mushroomId, plant_id: id}})
+        } else {
+            return
+        }
+        fetch(route, {
+            method: "POST",
+            headers: { "Content-Type": "application/json", "Accept": "application/json", "X-CSRF-Token": this.csrfToken() },
+            body: body
+        }).then(resp => {
+            if(!resp.ok) {
+                return resp.json().then(data => {
+                    throw new Error(data.errors ? data.errors.join(", ") : "Save failed")
+                })
+            }
+            // Optionally: visual feedback
+        }).catch(err => {
+            // Remove pill if failed
+            this.removePillById(id)
+            alert(err.message || "Failed to add. Please try again.")
+        })
+    }
+
+    deleteToken(id, onSuccess, onError) {
+        const kind = this.kindValue
+        const mushroomId = this.mushroomIdValue
+        if(!kind || !mushroomId) {
+            if(onError) onError()
+            return
+        }
+        let route
+        if(kind=="genera") {
+            route = `/genus_mushrooms/destroy_by_relation.json?mushroom_id=${mushroomId}&genus_id=${id}`
+        } else if (kind=="species") {
+            route = `/mushroom_species/destroy_by_relation.json?mushroom_id=${mushroomId}&species_id=${id}`
+        } else if (kind=="trees") {
+            route = `/mushroom_trees/destroy_by_relation.json?mushroom_id=${mushroomId}&tree_id=${id}`
+        } else if (kind=="plants") {
+            route = `/mushroom_plants/destroy_by_relation.json?mushroom_id=${mushroomId}&plant_id=${id}`
+        } else {
+            if(onError) onError()
+            return
+        }
+        fetch(route, {
+            method: "DELETE",
+            headers: {"Accept": "application/json", "X-CSRF-Token": this.csrfToken()}
+        }).then(resp => {
+            if(!resp.ok) {
+                // Try to get the response text to see what's actually being returned
+                return resp.text().then(text => {
+                    console.error('Delete failed. Status:', resp.status, 'Response:', text)
+                    try {
+                        const data = JSON.parse(text)
+                        throw new Error(data.message || `Delete failed (${resp.status})`)
+                    } catch(e) {
+                        throw new Error(`Delete failed (${resp.status}): ${text.substring(0, 100)}`)
+                    }
+                })
+            }
+            return resp.json()
+        }).then(_data => {
+            // Success
+            console.log('Delete successful')
+            if(onSuccess) onSuccess()
+        }).catch(err => {
+            console.error('Delete error:', err)
+            alert(err.message || "Failed to remove. Please try again.")
+            if(onError) onError()
+        })
+    }
+
+    removePillById(id) {
+        const pill = this.listTarget.querySelector(`[data-token-id="${id}"]`)
+        if(pill) pill.remove()
+        this.selected.delete(id)
+        this.updateHiddenIds()
+    }
+
+    csrfToken() {
+        const meta = document.querySelector('meta[name=csrf-token]')
+        return meta && meta.content
+    }
+}

data/config/routes.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+Mycowriter::Engine.routes.draw do
+  get "autocomplete/genera", to: "autocomplete#genera", as: :genera_autocomplete, defaults: { format: :json }
+  get "autocomplete/species", to: "autocomplete#species", as: :species_autocomplete, defaults: { format: :json }
+end

data/lib/generators/mycowriter/install/README

@@ -0,0 +1,40 @@
+===============================================================================
+
+Mycowriter has been installed successfully!
+
+Next steps:
+
+1. Run database migrations if you haven't already:
+   rails db:migrate
+
+2. Ensure you have the mb_lists table in your database with taxonomic data.
+   The gem expects a table with at least these columns:
+   - id
+   - taxon_name
+   - rank_name (optional, for filtering by taxonomic rank)
+
+3. Import your controller in app/javascript/controllers/application.js:
+
+   import MycowriterAutocomplete from "mycowriter/autocomplete_controller"
+   application.register("mycowriter--autocomplete", MycowriterAutocomplete)
+
+4. Use the autocomplete in your views:
+
+   <div data-controller="mycowriter--autocomplete"
+        data-mycowriter--autocomplete-url-value="/mycowriter/autocomplete/genera"
+        data-mycowriter--autocomplete-kind-value="genera"
+        data-mycowriter--autocomplete-mushroom-id-value="<%= @mushroom.id %>">
+
+     <input type="text"
+            data-mycowriter--autocomplete-target="input"
+            placeholder="Type genus name..." />
+
+     <ul data-mycowriter--autocomplete-target="dropdown" class="hidden"></ul>
+     <div data-mycowriter--autocomplete-target="list"></div>
+   </div>
+
+5. Configure Mycowriter in config/initializers/mycowriter.rb
+
+For more information, visit https://mycowriter.com
+
+===============================================================================

data/lib/generators/mycowriter/install/install_generator.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Mycowriter
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates Mycowriter initializer and mounts the engine"
+
+      def copy_initializer
+        template "mycowriter.rb", "config/initializers/mycowriter.rb"
+      end
+
+      def add_route
+        route 'mount Mycowriter::Engine => "/mycowriter"'
+      end
+
+      def show_readme
+        readme "README" if behavior == :invoke
+      end
+    end
+  end
+end

data/lib/generators/mycowriter/install/templates/mycowriter.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# Mycowriter configuration
+Mycowriter.configure do |config|
+  # Minimum number of characters required before autocomplete triggers
+  # Default: 4 (prevents excessive matches like "a", "ag", "aga")
+  config.min_characters = 4
+
+  # Require uppercase first letter for genus names
+  # Default: true (genus names always start with capital letter: Agaricus, not agaricus)
+  config.require_uppercase = true
+
+  # Maximum number of results to return
+  # Default: 20
+  config.results_limit = 20
+end
+
+# Skip Pundit authorization and Devise authentication for Mycowriter engine controllers
+# This ensures the autocomplete functionality works without requiring user authentication
+Rails.application.config.to_prepare do
+  Mycowriter::AutocompleteController.class_eval do
+    skip_after_action :verify_authorized, raise: false
+    skip_after_action :verify_policy_scoped, raise: false
+    skip_before_action :authenticate_user!, raise: false if respond_to?(:authenticate_user!)
+  end
+end

data/lib/generators/mycowriter/mb_lists_migration/README

@@ -0,0 +1,55 @@
+===============================================================================
+
+Migration for mb_lists table created successfully!
+
+Next steps:
+
+1. Run the migration:
+   rails db:migrate
+
+2. Download MycoBank data:
+
+   Visit: https://www.mycobank.org/page/Simple%20names%20search
+
+   Or use direct download link:
+   https://www.mycobank.org/MBList.xlsx
+
+   The MBList file contains comprehensive taxonomic data for fungi.
+
+3. Import the data into your database:
+
+   You can use a rake task or script to import the Excel file.
+   Example approach:
+
+   - Save the file as CSV
+   - Use the 'roo' gem to read Excel files
+   - Import into mb_lists table
+
+   Sample import code:
+
+   require 'roo'
+   xlsx = Roo::Spreadsheet.open('path/to/MBList.xlsx')
+   xlsx.each_row_streaming(offset: 1) do |row|
+     MbList.create!(
+       taxon_name: row[0]&.value,
+       rank_name: row[1]&.value,
+       authors: row[2]&.value,
+       # ... map other columns
+     )
+   end
+
+4. MycoBank License Requirements:
+
+   Creative Commons CC BY-NC-ND
+   - Attribution: Credit must be given to MycoBank
+   - Non-Commercial: Non-commercial use only
+   - No Derivatives: Data used in unadapted form only
+
+   Required Attribution:
+   "MBList taxonomic data provided by MycoBank (www.mycobank.org)"
+
+For more information:
+- MycoBank: https://www.mycobank.org
+- Mycowriter gem: https://github.com/mrdbidwill/mycowriter
+
+===============================================================================

data/lib/generators/mycowriter/mb_lists_migration/mb_lists_migration_generator.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Mycowriter
+  module Generators
+    class MbListsMigrationGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates migration for mb_lists table to store MycoBank taxonomic data"
+
+      def self.next_migration_number(dirname)
+        next_migration_number = current_migration_number(dirname) + 1
+        ActiveRecord::Migration.next_migration_number(next_migration_number)
+      end
+
+      def copy_migration
+        migration_template "create_mb_lists.rb", "db/migrate/create_mb_lists.rb"
+      end
+
+      def show_readme
+        readme "README" if behavior == :invoke
+      end
+    end
+  end
+end

data/lib/generators/mycowriter/mb_lists_migration/templates/create_mb_lists.rb

@@ -0,0 +1,39 @@
+class CreateMbLists < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :mb_lists do |t|
+      t.text :mblist_id
+      t.text :taxon_name
+      t.text :authors
+      t.text :rank_name
+      t.text :year_of_effective_publication
+      t.text :name_status
+      t.text :mycobank_number
+      t.text :hyperlink
+      t.text :classification
+      t.text :current_name
+      t.text :synonymy
+      t.timestamps
+    end
+
+    # Set character encoding for UTF-8 support (MySQL/MariaDB)
+    execute <<-SQL
+      ALTER TABLE mb_lists
+      CONVERT TO CHARACTER SET utf8mb4
+      COLLATE utf8mb4_0900_as_cs;
+    SQL
+
+    # Add indexes for performance
+    add_index :mb_lists, [:taxon_name, :rank_name],
+              name: "index_mblists_on_taxon_name_and_rank_name",
+              length: { taxon_name: 255, rank_name: 255 }
+    add_index :mb_lists, :taxon_name,
+              name: "index_mblists_on_taxon_name",
+              length: 255
+    add_index :mb_lists, :rank_name,
+              name: "index_mblists_on_rank_name",
+              length: 255
+    add_index :mb_lists, :name_status,
+              name: "index_mblists_on_name_status",
+              length: 255
+  end
+end

data/lib/mycowriter/engine.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Mycowriter
+  class Engine < ::Rails::Engine
+    isolate_namespace Mycowriter
+
+    config.generators do |g|
+      g.test_framework :rspec
+      g.fixture_replacement :factory_bot
+      g.factory_bot dir: 'spec/factories'
+    end
+  end
+end

data/lib/mycowriter/version.rb

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

data/lib/mycowriter.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "mycowriter/version"
+require "mycowriter/engine"
+
+module Mycowriter
+  # Configuration options
+  mattr_accessor :min_characters
+  @@min_characters = 4
+
+  mattr_accessor :require_uppercase
+  @@require_uppercase = true
+
+  mattr_accessor :results_limit
+  @@results_limit = 20
+
+  def self.configure
+    yield self
+  end
+end

metadata

@@ -0,0 +1,89 @@
+--- !ruby/object:Gem::Specification
+name: mycowriter
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Will Johnston
+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.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: Mycowriter provides real-time autocomplete functionality for genus and
+  species names, matching against MycoBank taxonomic data. Perfect for mycology, biology,
+  and taxonomy-focused applications.
+email:
+- mrdbidwill@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- app/controllers/mycowriter/autocomplete_controller.rb
+- app/javascript/mycowriter/autocomplete_controller.js
+- config/routes.rb
+- lib/generators/mycowriter/install/README
+- lib/generators/mycowriter/install/install_generator.rb
+- lib/generators/mycowriter/install/templates/mycowriter.rb
+- lib/generators/mycowriter/mb_lists_migration/README
+- lib/generators/mycowriter/mb_lists_migration/mb_lists_migration_generator.rb
+- lib/generators/mycowriter/mb_lists_migration/templates/create_mb_lists.rb
+- lib/mycowriter.rb
+- lib/mycowriter/engine.rb
+- lib/mycowriter/version.rb
+homepage: https://mycowriter.com
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://mycowriter.com
+  source_code_uri: https://github.com/mrdbidwill/mycowriter
+  changelog_uri: https://github.com/mrdbidwill/mycowriter/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.1
+specification_version: 4
+summary: Intelligent taxonomic autocomplete for genus and species names in Rails applications
+test_files: []