stimulus-password-strength 0.1.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a0150f9398507c2a875986766bf55719e1301a68cc66a12591f1796354fc872f
+  data.tar.gz: c469c7ec416cff1eb8dcb78f3a0a5cdd961a9d60110a317e1f6d9836727b442d
+SHA512:
+  metadata.gz: dc3c6f68e8ede33665fec285d0079d4cee0020b823b441bc8be08ea25c638862b656746ab5c9b359be1d3e055346c4a639c5ce4d9249c7e073cacb6f0c454189
+  data.tar.gz: 8118612aa2c405d37dd6460a72aac666faec1317f8f6b0d98bcbcc6d039201f57a90fed64d36e3f4dcdd2e8fce198dae5abbdbca05ed8031869b19e62a50a420

data/.rubocop.yml

@@ -0,0 +1,41 @@
+AllCops:
+  TargetRubyVersion: 3.2
+  NewCops: enable
+  SuggestExtensions: false
+  Exclude:
+    - "test/tmp/**/*"
+
+Layout/LineLength:
+  Max: 150
+
+Metrics/AbcSize:
+  Enabled: false
+
+Metrics/BlockLength:
+  Exclude:
+    - "test/**/*"
+  Max: 30
+
+Metrics/CyclomaticComplexity:
+  Enabled: false
+
+Metrics/MethodLength:
+  Enabled: false
+
+Metrics/ModuleLength:
+  Enabled: false
+
+Metrics/PerceivedComplexity:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
+Style/FrozenStringLiteralComment:
+  Enabled: false
+
+Style/FormatStringToken:
+  Enabled: false
+
+Style/StringLiterals:
+  Enabled: false

data/AGENTS.md

@@ -0,0 +1,71 @@
+# AGENTS.md
+
+Use this file when an AI coding agent is integrating `stimulus-password-strength` into a host Rails app.
+
+## Goal
+
+Treat this gem as a UI layer for password UX, not as password security policy.
+
+The integration should:
+
+- reduce signup friction
+- keep the meter visible even with 1Password/LastPass overlays
+- preserve backend validation until the host app intentionally migrates it
+
+## Recommended Rollout
+
+1. Add the gem and run:
+
+```bash
+bundle install
+bin/rails generate stimulus_password_strength:install
+```
+
+2. Use the generated `PasswordPolicy` as the shared source of truth for backend rules and UI requirements.
+3. Replace the main password field with `password_strength_field`, passing `requirements: PasswordPolicy.requirements`.
+4. Update all user-facing password views. Minimum:
+   - signup / registration
+   - password reset / change password
+5. If the app has additional password-setting flows, update them too:
+   - invitation acceptance
+   - onboarding set password
+   - admin-created account activation
+   - forced password change
+6. Do not remove `password_confirmation` if the host app still requires it.
+7. Do not change backend validation during the first rollout unless validation is already wired to `PasswordPolicy`.
+8. Roll out the UI first, then decide separately whether to simplify backend policy.
+
+## Host App Checks
+
+Before changing any auth flow, verify:
+
+1. Does the app require `password_confirmation`?
+2. Does the app enforce regex rules such as uppercase/lowercase/digit?
+3. Are there custom validation messages that would drift from the new UI?
+4. Are there additional password flows outside signup and reset?
+5. Does the host app use a custom design system that should override helper classes?
+
+## What Not to Change Automatically
+
+1. Do not remove `password_confirmation` without reviewing validations, tests, and reset flow behavior.
+2. Do not change password policy just because the meter shows `good` or `strong`.
+3. Do not define `requirements` separately from `PasswordPolicy`.
+4. Do not hardcode hints such as `Must contain uppercase...` unless the backend actually enforces them.
+5. Do not assume Tailwind classes applied dynamically from JS will work in every host app.
+
+## Minimal Smoke Test
+
+1. Signup: weak password -> meter, toggle, and backend validation all behave correctly.
+2. Signup with 1Password/LastPass enabled: meter and requirements remain visible.
+3. Password reset: the same component behaves consistently in the second flow.
+4. Browser autofill: meter and requirements refresh after typing or autofill.
+5. Mobile viewport: toggle does not overlap text or password manager icons.
+
+## Policy Reminder
+
+This gem does not replace:
+
+- model validation
+- rate limiting
+- anti-abuse controls
+- password reset security

data/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+## 0.1.2
+
+- switched gem packaging to `git ls-files`
+- added a lightweight RuboCop setup for the gem repository
+- simplified CI to a single `main.yml` workflow with Ruby lint, Ruby tests, and JS tests
+- aligned repository tooling with the release workflow used in `price_scanner`
+
+## 0.1.1
+
+- first public RubyGems release
+- English README for public consumers
+- agent-specific installation guidance moved to `AGENTS.md` and `CLAUDE.md`
+- CI reduced to the minimum useful cross-platform matrix: Ruby 3.2 on Linux and macOS
+- lockfile updated for Linux and generic Ruby platforms
+
+## 0.1.0
+
+- first public release candidate
+- Rails 8 engine with helper, partial, installer and importmap support
+- Stimulus password strength controller with show/hide toggle
+- vendored `zxcvbn.js` for host apps without Node
+- explicit `PasswordPolicy` pattern for syncing backend rules with UI requirements
+- Ruby tests for helper rendering, generator behavior and dummy app smoke flow
+- lightweight JS tests for controller behavior
+- public README rewritten in English
+- agent-specific integration instructions moved to `AGENTS.md` and `CLAUDE.md`

data/CLAUDE.md

@@ -0,0 +1,11 @@
+# CLAUDE.md
+
+For integration guidance, treat [AGENTS.md](AGENTS.md) as the canonical source.
+
+## Claude-Specific Notes
+
+1. Start with a UI-only rollout unless the host app explicitly asks to simplify backend password policy.
+2. Prefer using the generated `PasswordPolicy` as the source of truth for both model validation and gem requirements.
+3. Update every user-facing password flow, not just signup.
+4. If the host app still requires `password_confirmation`, keep it until validations and tests are migrated deliberately.
+5. After integration, run a smoke test for signup, password reset, autofill, and password manager overlay behavior.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Justyna Wojtczak
+
+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/PUBLISH_CHECKLIST.md

@@ -0,0 +1,82 @@
+# Publish Checklist
+
+## Goal
+
+Ship `stimulus-password-strength` as a reusable Rails 8+ gem with verified install path, stable UI API and enough automated coverage to publish safely.
+
+## Tasks
+
+### 1. Repo hygiene
+
+- [x] remove built gem artifact from version control flow
+- [x] ignore `node_modules` and built `.gem` files
+- [x] ensure gemspec ships README and LICENSE
+
+**DoD**
+- `git status` shows no accidental build outputs tracked
+- `.gitignore` blocks local artifacts
+- built gem includes docs/license files
+
+### 2. Public release metadata
+
+- [x] add release notes file
+- [x] enable RubyGems MFA metadata
+- [x] make README default to published install flow
+
+**DoD**
+- `CHANGELOG.md` exists
+- gemspec includes `rubygems_mfa_required`
+- README installation example does not depend on local `path:`
+
+### 3. Helper and rendering coverage
+
+- [x] test rendered markup from `password_strength_field`
+- [x] verify i18n labels and requirement serialization
+- [x] verify invalid requirement rules fail fast
+
+**DoD**
+- helper test covers main HTML contract consumed by Stimulus
+- tests assert both default and localized output
+- unsupported requirements raise a clear error
+
+### 4. Installer coverage
+
+- [x] test importmap pin insertion
+- [x] test Stimulus controller registration
+- [x] test initializer creation
+- [x] test `PasswordPolicy` template creation
+- [x] test idempotency
+
+**DoD**
+- generator test proves a fresh host app gets all required files
+- rerunning installer does not duplicate pins or controller registration
+
+### 5. Dummy app smoke test
+
+- [x] add minimal Rails dummy app
+- [x] render a form using the gem helper
+- [x] assert response contains the expected password field contract
+
+**DoD**
+- dummy app boots in test environment
+- integration test hits a real route and renders the component successfully
+
+### 6. JS behavior coverage
+
+- [x] add lightweight Node-based tests for the Stimulus controller
+- [x] test toggle behavior
+- [x] test requirement label transitions
+- [x] test hidden state for empty password
+
+**DoD**
+- JS tests run without bundling the host app
+- core controller UX behavior is covered by automation
+
+### 7. Verification
+
+- [x] run Ruby test suite
+- [x] run JS test suite
+
+**DoD**
+- both suites pass locally
+- release candidate is blocked only by product decisions, not missing test scaffolding

data/README.md

@@ -0,0 +1,182 @@
+# stimulus-password-strength
+
+Importmap-friendly password strength field for Rails 8+ with Stimulus, `zxcvbn`, and Tailwind-friendly markup.
+
+## Product Goal
+
+Reduce signup abandonment by improving password UX:
+
+- one password field with `show/hide`
+- real-time strength meter
+- requirements placed above the input so they stay visible with 1Password/LastPass overlays
+- no Node.js required in the host app
+- simpler signup flow while keeping security standards and sound UX practices
+
+## What the Gem Includes
+
+- Rails engine: `StimulusPasswordStrength::Engine`
+- Stimulus controller: `password-strength`
+- vendored `zxcvbn.js`
+- helper: `password_strength_field`
+- partial: `_field.html.erb`
+- installer: `rails g stimulus_password_strength:install`
+- default i18n files: `en`, `pl`
+
+## Installation
+
+Add the gem to your app:
+
+```ruby
+gem "stimulus-password-strength"
+```
+
+Then run:
+
+```bash
+bundle install
+bin/rails generate stimulus_password_strength:install
+```
+
+The installer:
+
+- adds importmap pins to `config/importmap.rb`
+- registers the controller in `app/javascript/controllers/index.js`
+- creates `config/initializers/stimulus_password_strength.rb`
+- creates `app/lib/password_policy.rb` as the single source of truth for the rules shown in the UI
+
+## Usage
+
+```erb
+<%= form_with(model: @user) do |form| %>
+  <%= password_strength_field form, :password,
+      placeholder: "Minimum 12 characters",
+      requirements: PasswordPolicy.requirements %>
+<% end %>
+```
+
+With custom labels:
+
+```erb
+<%= password_strength_field form, :password,
+    strength_labels: { weak: "Weak", fair: "Fair", good: "Good", strong: "Strong" },
+    toggle_labels: { show: "Show", hide: "Hide" } %>
+```
+
+## Password Policy
+
+The installer creates a sample [password_policy.rb.tt](/Users/justi/projects_prod/stimulus-password-strength/lib/generators/stimulus_password_strength/install/templates/password_policy.rb.tt) file that should become the shared source of truth for:
+
+- backend model validation
+- requirements rendered by the gem
+
+Example host app validation:
+
+```ruby
+# app/models/user.rb
+validates :password, length: { minimum: PasswordPolicy::MIN_LENGTH }, allow_nil: true
+```
+
+Example view usage:
+
+```erb
+<%= password_strength_field form, :password,
+    requirements: PasswordPolicy.requirements %>
+```
+
+`min_length` can use dynamic live copy from `PasswordPolicy`, for example:
+
+```ruby
+REQUIREMENTS = [
+  {
+    rule: :min_length,
+    value: MIN_LENGTH,
+    label: "At least #{MIN_LENGTH} characters",
+    remaining_singular: "Type 1 more character",
+    remaining_plural: "Type %{count} more characters",
+    met_label: "#{MIN_LENGTH}+ chars"
+  }
+].freeze
+```
+
+The gem does not try to infer rules from the model and does not add hidden fallbacks for `requirements`. The host app must pass policy explicitly from `PasswordPolicy`.
+
+## Configuration
+
+`config/initializers/stimulus_password_strength.rb`:
+
+```ruby
+StimulusPasswordStrength.configure do |config|
+  config.input_class = "w-full rounded-md border px-3 py-2 pr-16"
+  config.text_style = "min-width: 2.5rem; text-align: right; white-space: nowrap;"
+  config.status_row_class = "flex min-h-5 items-center gap-2"
+  config.requirements_style = "min-height: 1rem;"
+  config.requirement_pending_style = "color: #6b7280;"
+  config.requirement_met_style = "color: #047857;"
+  config.requirement_unmet_style = "color: #b91c1c;"
+
+  config.bar_colors = {
+    weak: "#f87171",
+    fair: "#fbbf24",
+    good: "#22c55e",
+    strong: "#059669"
+  }
+end
+```
+
+Adding more languages is standard Rails I18n: add another locale file in [config/locales](/Users/justi/projects_prod/stimulus-password-strength/config/locales).
+
+## Post-Install Checklist
+
+1. Signup: weak password -> backend validation still works.
+2. Signup: `requirements` match `PasswordPolicy` and model validation.
+3. Signup: `Show/Hide` toggle works on mobile and desktop.
+4. Password reset: meter, requirements, and toggle behave the same way as signup.
+5. Password autofill: the strength meter and requirements refresh correctly.
+6. JS or `zxcvbn` failure: the form still allows submission.
+7. i18n: `show/hide/weak/fair/good/strong` labels are correct for the current locale.
+
+## Agent Guidance
+
+If you are installing this gem through an AI coding agent, use:
+
+- [AGENTS.md](AGENTS.md) for general agent instructions
+- [CLAUDE.md](CLAUDE.md) for Claude-specific workflow notes
+
+These files cover rollout order, host-app validation checks, smoke tests, and what should not be changed automatically.
+
+## Example Adaptation: `linked_flow`
+
+The gem was also used in `../linked_flow` as an example of a more opinionated UX simplification:
+
+- signup and password reset work without `password_confirmation`
+- the UI uses `password_strength_field`
+- backend validation and UI both use a shared `PasswordPolicy` with minimum password length
+
+Recommended rollout order:
+
+1. Add the gem as UI-only.
+2. Switch signup and reset views to `password_strength_field`.
+3. Only then decide whether to simplify backend policy and business tests.
+
+## Nice Follow-Ups After `0.1.0`
+
+1. Generator for JS test scaffolding in the host app.
+2. Wider CI coverage for Rails `8.0` and `8.1`.
+3. `confirmation: true/false` helper option.
+4. Public analytics event documentation for signup funnel instrumentation.
+5. More examples for integrating with host app design systems.
+
+## Development
+
+```bash
+cd /Users/justi/projects_prod/stimulus-password-strength
+bundle install
+npm install
+bundle exec rake test
+npm test
+```
+
+## Release Hygiene
+
+- full publication checklist: [PUBLISH_CHECKLIST.md](PUBLISH_CHECKLIST.md)
+- change history: [CHANGELOG.md](CHANGELOG.md)

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+task default: :test

data/app/javascript/stimulus_password_strength_controller.js

@@ -0,0 +1,193 @@
+import { Controller } from "@hotwired/stimulus"
+
+export default class extends Controller {
+  static targets = ["input", "toggle", "statusRow", "strengthTrack", "strengthBar", "strengthText", "requirement", "showIcon", "hideIcon"]
+
+  connect() {
+    this.syncToggleState()
+    this.evaluate()
+    this.loadZxcvbn()
+  }
+
+  async loadZxcvbn() {
+    try {
+      const mod = await import("zxcvbn")
+      this.zxcvbn = mod.default || mod
+      this.evaluate()
+    } catch (error) {
+      this.zxcvbn = null
+    }
+  }
+
+  toggle() {
+    const isPassword = this.inputTarget.type === "password"
+    this.inputTarget.type = isPassword ? "text" : "password"
+    this.syncToggleState()
+  }
+
+  evaluate() {
+    const password = this.inputTarget.value
+
+    if (password.length === 0) {
+      this.statusRowTarget.style.visibility = "hidden"
+      this.strengthTrackTarget.style.visibility = "hidden"
+      this.strengthBarTarget.style.width = "0%"
+      this.strengthBarTarget.style.backgroundColor = ""
+      this.strengthTextTarget.textContent = ""
+      this.strengthTextTarget.style.color = ""
+      this.updateRequirements(password)
+      return
+    }
+
+    this.statusRowTarget.style.visibility = "visible"
+    this.strengthTrackTarget.style.visibility = "visible"
+    const score = this.scoreFor(password)
+    const widths = [10, 25, 50, 75, 100]
+    const labels = ["weak", "weak", "fair", "good", "strong"]
+
+    this.strengthBarTarget.style.width = `${widths[score]}%`
+    this.strengthBarTarget.className = this.barClasses()
+    this.strengthBarTarget.style.backgroundColor = this.barColor(score)
+    this.strengthTextTarget.textContent = this.label(labels[score])
+    this.strengthTextTarget.className = this.textClasses()
+    this.strengthTextTarget.style.color = this.textColor(score)
+    this.updateRequirements(password)
+  }
+
+  scoreFor(password) {
+    if (this.zxcvbn) {
+      return this.zxcvbn(password).score
+    }
+
+    // Fallback when zxcvbn cannot be loaded (offline/asset issue).
+    let score = 0
+    if (password.length >= 8) score += 1
+    if (password.length >= 12) score += 1
+    if (/[A-Z]/.test(password) && /[a-z]/.test(password)) score += 1
+    if (/\d/.test(password) || /[^A-Za-z0-9]/.test(password)) score += 1
+    return Math.min(score, 4)
+  }
+
+  label(key) {
+    const map = {
+      weak: this.element.dataset.passwordStrengthWeakLabel,
+      fair: this.element.dataset.passwordStrengthFairLabel,
+      good: this.element.dataset.passwordStrengthGoodLabel,
+      strong: this.element.dataset.passwordStrengthStrongLabel
+    }
+
+    return map[key] || key
+  }
+
+  barClasses() {
+    return this.element.dataset.passwordStrengthBarBaseClass || "h-full rounded-full transition-all duration-300"
+  }
+
+  textClasses() {
+    return this.element.dataset.passwordStrengthTextBaseClass || "text-xs"
+  }
+
+  barColor(score) {
+    const colors = [
+      this.element.dataset.passwordStrengthWeakBarColor || "#f87171",
+      this.element.dataset.passwordStrengthWeakBarColor || "#f87171",
+      this.element.dataset.passwordStrengthFairBarColor || "#fbbf24",
+      this.element.dataset.passwordStrengthGoodBarColor || "#22c55e",
+      this.element.dataset.passwordStrengthStrongBarColor || "#059669"
+    ]
+
+    return colors[score]
+  }
+
+  textColor(score) {
+    const colors = [
+      this.element.dataset.passwordStrengthWeakTextColor || "#ef4444",
+      this.element.dataset.passwordStrengthWeakTextColor || "#ef4444",
+      this.element.dataset.passwordStrengthFairTextColor || "#d97706",
+      this.element.dataset.passwordStrengthGoodTextColor || "#16a34a",
+      this.element.dataset.passwordStrengthStrongTextColor || "#047857"
+    ]
+
+    return colors[score]
+  }
+
+  syncToggleState() {
+    const isPassword = this.inputTarget.type === "password"
+    const label = isPassword
+      ? this.toggleTarget.dataset.showLabel
+      : this.toggleTarget.dataset.hideLabel
+
+    this.toggleTarget.setAttribute("aria-label", label)
+    this.toggleTarget.setAttribute("title", label)
+
+    if (this.hasShowIconTarget) this.showIconTarget.hidden = !isPassword
+    if (this.hasHideIconTarget) this.hideIconTarget.hidden = isPassword
+  }
+
+  updateRequirements(password) {
+    this.requirementTargets.forEach((element) => {
+      const isMet = this.requirementMet(element, password)
+
+      if (password.length === 0) {
+        element.setAttribute("aria-hidden", "false")
+        element.innerHTML = this.escapeHtml(element.dataset.label)
+        element.style.cssText = `${element.dataset.pendingStyle}; visibility: visible;`
+        return
+      }
+
+      element.setAttribute("aria-hidden", "false")
+      element.innerHTML = isMet
+        ? this.metRequirementMarkup(element)
+        : this.escapeHtml(this.requirementLabel(element, password))
+      element.style.cssText = isMet
+        ? `${element.dataset.metStyle}; visibility: visible;`
+        : `${element.dataset.unmetStyle}; visibility: visible;`
+    })
+  }
+
+  requirementMet(element, password) {
+    switch (element.dataset.rule) {
+      case "min_length":
+        return password.length >= Number(element.dataset.value)
+      case "uppercase":
+        return /[A-Z]/.test(password)
+      default:
+        return false
+    }
+  }
+
+  requirementLabel(element, password) {
+    switch (element.dataset.rule) {
+      case "min_length": {
+        const required = Number(element.dataset.value)
+        const remaining = Math.max(required - password.length, 0)
+
+        if (remaining === 1 && element.dataset.remainingSingular) {
+          return element.dataset.remainingSingular
+        }
+
+        if (remaining > 1 && element.dataset.remainingPlural) {
+          return element.dataset.remainingPlural.replace("%{count}", remaining)
+        }
+
+        return element.dataset.label
+      }
+      default:
+        return element.dataset.label
+    }
+  }
+
+  metRequirementMarkup(element) {
+    const label = this.escapeHtml(element.dataset.metLabel || element.dataset.label)
+    return `<span style="display: inline-flex; align-items: center; gap: 0.25rem;"><span aria-hidden="true">✓</span><span>${label}</span></span>`
+  }
+
+  escapeHtml(value) {
+    return String(value)
+      .replaceAll("&", "&amp;")
+      .replaceAll("<", "&lt;")
+      .replaceAll(">", "&gt;")
+      .replaceAll('"', "&quot;")
+      .replaceAll("'", "&#39;")
+  }
+}