bard-tag_field 0.5.1 → 0.5.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 63dcbc22c1ab61723177f5ae24d9ce800ce276274491a390b0495c17352c519c
-  data.tar.gz: 91e3c318345b56a48bcea2b48903ddd16f684c2ae098f8a416ce0fec0d14cc0e
+  metadata.gz: 7e9614b18c1daff3040d38c34016dd8d67e6badd0342fcd60892b2cd03d90a43
+  data.tar.gz: c268ec956862e6f28ab3f114b115a75904b6cc2f4b2feb7c3aab723ba46c2171
 SHA512:
-  metadata.gz: f2565d04096d161a991258f0b8a0c796775be897c7a4710c16ba169e5807562a044ede61f2ad5d5a1f975efbb4e887718e16730862b2ab3fddd0952b8ecd6604
-  data.tar.gz: ae2bc2e85a57311e5a2a472346665459cae033bb8b44900fdfb1df0043bd3e92a349de2162bfe289515905cff74f4a54b44ec85f06cc765728190922c99b6087
+  metadata.gz: 940b9e4abc58c41ed6c653bc425d644e6ba77d1c5e061d6b33c354f3ae9b2d9986da51b889b20a2645a65f457ffa16ddac7ac7c2332c5c07f30fabfa1190c6d8
+  data.tar.gz: 25fbd8883e9bc53b1fa57427f6186d0f551c0c39b5e34fd623e475e806636ef89673785f68eeae5e25b544a98132fb586c0ef40919bb16bfae6a0cc45b1c9462

data/CLAUDE.md

@@ -10,8 +10,8 @@ This is a Rails form helper gem that provides `tag_field` for creating interacti
 - `lib/bard/tag_field/form_builder.rb` - Rails form builder integration that handles method signature variants (like Rails' `select` helper)
 - `lib/bard/tag_field/field.rb` - Core field rendering logic, extends `ActionView::Helpers::Tags::TextField`
 - `lib/bard/tag_field.rb` - Rails Engine that auto-registers the form builder and precompiles JavaScript assets
-- `input-tag/` - JavaScript build directory using Rollup to bundle the `@botandrose/input-tag` package with Bun
-- `app/assets/javascripts/input-tag.js` - Compiled JavaScript output for Rails asset pipeline
+- `input-tag/` - The @botandrose/input-tag custom element source (standalone package)
+- `app/assets/javascripts/input-tag.js` - Symlink to `input-tag/dist/input-tag.js` for Rails asset pipeline
 
 ## Development Commands
 
@@ -34,7 +34,7 @@ bundle exec appraisal install
 # Build JavaScript assets (required before running tests or releasing)
 cd input-tag && bun run build
 
-# Install Bun dependencies
+# Install bun dependencies
 cd input-tag && bun install
 
 # Clean compiled assets
@@ -96,13 +96,14 @@ Test setup includes a mock Rails application (TestApp) initialized in spec/spec_
 
 ## JavaScript Build Process
 
-The gem bundles the `@botandrose/input-tag` package using Rollup with Bun:
-1. Source: `input-tag/index.js` imports from `@botandrose/input-tag`
+The `input-tag/` directory contains the standalone @botandrose/input-tag custom element:
+1. Source: `input-tag/src/input-tag.js`
 2. Build: `cd input-tag && bun run build` runs Rollup
-3. Output: `app/assets/javascripts/input-tag.js` for Rails asset pipeline
-4. The Engine precompiles this asset (lib/bard/tag_field.rb:11)
+3. Output: `input-tag/dist/input-tag.js` (bundled with dependencies)
+4. Symlink: `app/assets/javascripts/input-tag.js` -> `../../../input-tag/dist/input-tag.js`
+5. The Engine precompiles this asset (lib/bard/tag_field.rb:11)
 
-**Important:** Always rebuild JavaScript assets after updating the `@botandrose/input-tag` dependency.
+**Important:** Run `cd input-tag && bun run build` after making changes to input-tag source.
 
 ## Multi-Rails Version Support
 

data/Rakefile

@@ -14,7 +14,7 @@ task :build_js do
   sh "cd input-tag && bun run build"
 end
 
-desc "Install Bun dependencies"
+desc "Install bun dependencies"
 task :install_deps do
   sh "cd input-tag && bun install"
 end

data/app/assets/javascripts/input-tag.js

@@ -0,0 +1 @@
+../../../input-tag/dist/input-tag.js

data/input-tag/.gitignore

@@ -1,2 +1,6 @@
-node_modules
-
+/node_modules/
+/coverage
+/dist
+/tmp/*
+!tmp/.gitkeep
+.idea

data/input-tag/CLAUDE.md

@@ -0,0 +1,87 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is `@botandrose/input-tag`, a declarative, framework-agnostic custom element for tag input with autocomplete functionality. The project consists of:
+
+- A form-associated custom element (`input-tag`) with shadow DOM encapsulation
+- Integration with the third-party `taggle` library (modified) for tag management
+- Autocomplete functionality via the `autocompleter` library and HTML datalist elements
+- Comprehensive cross-browser testing using Web Test Runner
+
+## Key Commands
+
+**Testing:**
+```bash
+npm test                 # Run tests once (default browser)
+npm run test:watch       # Run tests in watch mode
+npm run test:all         # Run tests across all browsers (chromium, firefox, webkit)
+npm run test:chrome      # Run tests in Chrome/Chromium only
+npm run test:firefox     # Run tests in Firefox only
+npm run test:webkit      # Run tests in Safari/WebKit only
+npm run test:coverage    # Run tests with coverage report
+npm run test:ci          # CI mode with fail-only plugin
+```
+
+**Single test execution:**
+Web Test Runner supports filtering via `--grep` flag:
+```bash
+npm test -- --grep "should add tags"
+npm run test:watch -- --grep "autocomplete"
+```
+
+## Architecture
+
+**Core Components:**
+- `src/input-tag.js` - Main custom element class with form integration, event handling, and autocomplete setup
+- `src/taggle.js` - Modified version of Taggle library for tag UI management and interactions
+- `TagOption` class - Custom element for individual tag rendering with shadow DOM
+
+**Key Architectural Patterns:**
+- Form-associated custom elements using ElementInternals API for native form integration
+- Shadow DOM encapsulation for both the main element and individual tags
+- Event-driven architecture with `change` and `update` events
+- Declarative configuration via HTML attributes (`multiple`, `required`, `list`)
+- Integration with HTML datalist elements for autocomplete suggestions
+
+**State Management:**
+- Tags stored internally in the taggle instance
+- Form value synchronized via ElementInternals
+- Autocomplete suggestions managed by external `autocompleter` library
+- Pre-existing `<tag-option>` elements parsed and converted to initial tags
+
+## Testing Structure
+
+Tests are categorized by functionality in separate files:
+- `input-tag.test.js` - Smoke tests and basic element creation
+- `basic-functionality.test.js` - Tag CRUD operations, single/multiple modes
+- `form-integration.test.js` - Form association, validation, reset, FormData
+- `events.test.js` - Event firing, bubbling, timing, and cleanup
+- `autocomplete.test.js` - Datalist integration and suggestion behavior
+- `edge-cases.test.js` - Empty inputs, duplicates, special characters, memory leaks
+- `api-methods.test.js` - Public method validation and error handling
+- `dom-mutation.test.js` - Dynamic DOM changes and element lifecycle
+- `value-label-separation.test.js` - Handling value/label pairs in options
+- `nested-datalist.test.js` - Complex datalist scenarios
+
+**Test Utilities:**
+- `test/lib/test-utils.js` - Shared helpers like `setupGlobalTestHooks()` and `waitForElement()`
+- `test/lib/fail-only.mjs` - Plugin preventing `it.only` tests in CI
+
+## Important Implementation Details
+
+**Form Integration:**
+Uses ElementInternals API for native form association, validation, and reset handling. The element automatically registers with forms and participates in form submission.
+
+**Event System:**
+- `change` events fire when tag collection changes (like native form elements)
+- `update` events provide granular detail about individual tag additions/removals
+- Events properly bubble through shadow DOM boundaries
+
+**Browser Compatibility:**
+Tested across Chromium, Firefox, and WebKit. Uses Web Test Runner with Playwright for cross-browser testing. Special handling for Android keyboards (comma key behavior).
+
+**Memory Management:**
+Tests include memory leak prevention checks, especially for autocomplete functionality and event listeners in shadow DOM.

data/input-tag/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Bot & Rose
+
+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/input-tag/README.md

@@ -0,0 +1,135 @@
+# @botandrose/input-tag
+
+A declarative, framework-agnostic custom element for tag input with optional autocomplete functionality.
+
+Built with appreciation on the excellent foundation of [Taggle.js](https://github.com/okcoker/taggle.js) by Sean Coker.
+
+## Installation
+
+```bash
+npm install @botandrose/input-tag
+```
+
+## Usage
+
+Import the custom element:
+
+```javascript
+import "@botandrose/input-tag"
+```
+
+Then use it in your HTML:
+
+```html
+<input-tag name="tags" multiple>
+  <tag-option value="javascript">JavaScript</tag-option>
+  <tag-option value="typescript">TypeScript</tag-option>
+</input-tag>
+
+<datalist id="suggestions">
+  <option value="react">React</option>
+  <option value="vue">Vue</option>
+  <option value="angular">Angular</option>
+</datalist>
+
+<input-tag name="frameworks" list="suggestions" multiple></input-tag>
+```
+
+## Features
+
+- Form-associated custom element with full form integration
+- Autocomplete support via datalist or custom options
+- Multiple/single value modes
+- Real-time validation
+- Accessible keyboard navigation
+- Shadow DOM encapsulation
+- Framework-agnostic
+
+## API
+
+### Attributes
+
+- `name`: Form field name
+- `multiple`: Allow multiple tags (default: single tag mode)
+- `required`: Make field required
+- `list`: ID of datalist for autocomplete suggestions
+
+### Properties
+
+- `value`: Get/set tag values - returns **array** when `multiple`, **string** when single mode
+- `tags`: Get current tag values as array (read-only)
+- `options`: Get available autocomplete options from datalist
+- `form`: Reference to associated form element
+- `name`: Get the name attribute value
+
+### Events
+
+- `change`: Fired when tag values change
+- `update`: Fired when individual tags are added/removed with detail `{tag, isNew}`
+
+### Methods
+
+#### Tag Management
+- `add(tag | tags[])`: Add single tag or array of tags
+- `remove(tag)`: Remove specific tag by value
+- `removeAll()`: Clear all tags
+- `has(tag)`: Check if tag exists
+- `addAt(tag, index)`: Add tag at specific position
+
+#### Form Integration
+- `reset()`: Clear all tags and input field
+- `checkValidity()`: Check if field passes validation
+- `reportValidity()`: Check validity and show validation UI
+
+#### Interaction
+- `focus()`: Focus the input field
+- `disable()`: Disable the input
+- `enable()`: Enable the input
+
+### JavaScript API Example
+
+```javascript
+// Multiple mode
+const multipleTag = document.querySelector('input-tag[multiple]')
+
+// Add tags
+multipleTag.add('react')
+multipleTag.add(['vue', 'angular'])
+
+// Get current tags
+console.log(multipleTag.value) // ['react', 'vue', 'angular'] - returns array
+console.log(multipleTag.tags)  // ['react', 'vue', 'angular'] - also array
+
+// Set all tags at once
+multipleTag.value = ['new', 'tags'] // accepts array
+
+// Single mode
+const singleTag = document.querySelector('input-tag:not([multiple])')
+
+// Set single tag
+singleTag.value = 'selected-tag' // accepts string
+
+// Get current tag
+console.log(singleTag.value) // 'selected-tag' - returns string
+console.log(singleTag.tags)  // ['selected-tag'] - always array
+
+// Backward compatibility: arrays still work in single mode
+singleTag.value = ['another-tag'] // accepts array, uses first item
+console.log(singleTag.value) // 'another-tag' - still returns string
+
+// Form validation
+if (!singleTag.checkValidity()) {
+  singleTag.reportValidity()
+}
+```
+
+## Testing
+
+```bash
+npm test
+npm run test:all
+```
+
+## License
+
+MIT

data/input-tag/TESTING.md

@@ -0,0 +1,99 @@
+# Testing Guide
+
+This project uses Web Test Runner for testing across multiple browsers.
+
+## Running Tests
+
+```bash
+# Run tests once
+npm test
+
+# Run tests in watch mode
+npm run test:watch
+
+# Run tests in specific browsers
+npm run test:chrome
+npm run test:firefox
+npm run test:webkit
+
+# Run tests in all browsers
+npm run test:all
+
+# Run tests with coverage
+npm run test:coverage
+
+# CI mode (fail-only)
+npm run test:ci
+```
+
+## Test Structure
+
+Tests are organized in the `test/` directory with one file per category:
+
+- `test/input-tag.test.js` - Smoke tests for basic functionality
+- `test/basic-functionality.test.js` - Tag creation, removal, single/multiple modes
+- `test/form-integration.test.js` - Form association, validation, reset behavior
+- `test/events.test.js` - Change and update event handling, bubbling, timing
+- `test/autocomplete.test.js` - Datalist integration, filtering, selection
+- `test/edge-cases.test.js` - Empty strings, duplicates, special characters, memory leaks
+- `test/api-methods.test.js` - Public methods, validation, property getters
+- `test/lib/test-utils.js` - Shared test utilities and helpers
+- `test/lib/fail-only.mjs` - Plugin to prevent `it.only` in CI
+
+## Test Categories
+
+### Basic Tag Functionality (`basic-functionality.test.js`)
+- Adding and removing tags programmatically
+- Single vs multiple tag mode behavior
+- Tag display and value management
+- Pre-existing tag-option initialization
+- Maximum tag limits and validation
+
+### Form Integration (`form-integration.test.js`)
+- Form association with ElementInternals
+- HTML validation (required attribute, checkValidity)
+- Form reset behavior and event handling
+- FormData integration for form submission
+- Custom validity and validation messages
+
+### Events (`events.test.js`)
+- Change event firing on tag modifications
+- Update events with detailed tag information
+- Event bubbling and composition across shadow DOM
+- Focus and blur event handling
+- Event timing, sequence, and cleanup
+
+### Autocomplete (`autocomplete.test.js`)
+- Datalist integration and option reading
+- Suggestion filtering and selection behavior
+- Multiple datalist scenarios and switching
+- Missing datalist handling
+- Autocomplete UI interaction and positioning
+
+### Edge Cases (`edge-cases.test.js`)
+- Empty string and whitespace-only input handling
+- Duplicate tag prevention (exact, case-insensitive, whitespace)
+- Very long tag names and input handling
+- Special characters, Unicode, and HTML-like content
+- Rapid input changes and memory leak prevention
+- Invalid HTML scenarios and malformed elements
+- Android keyboard support (comma behavior)
+
+### API Methods (`api-methods.test.js`)
+- Focus method and input targeting
+- Reset method and state clearing
+- Validation methods (checkValidity, reportValidity)
+- Value getter and setter with event handling
+- Property getters (form, name, options)
+- Error handling for invalid parameters
+
+## Browser Compatibility
+
+Tests run on:
+- Chromium (Chrome/Edge)
+- Firefox
+- WebKit (Safari)
+
+## Coverage
+
+Coverage reports are generated in the `coverage/` directory when running `npm run test:coverage`.