stimulus-password-strength 0.1.2 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a0150f9398507c2a875986766bf55719e1301a68cc66a12591f1796354fc872f
-  data.tar.gz: c469c7ec416cff1eb8dcb78f3a0a5cdd961a9d60110a317e1f6d9836727b442d
+  metadata.gz: 680420b026742db8f17192cf372b51fa045aa79a23551709f11eed0875ce2f61
+  data.tar.gz: 451f9156e8c9c49ea463161cfd0b7a8f00b6e21387e15f2b50300dbaee0dfc2c
 SHA512:
-  metadata.gz: dc3c6f68e8ede33665fec285d0079d4cee0020b823b441bc8be08ea25c638862b656746ab5c9b359be1d3e055346c4a639c5ce4d9249c7e073cacb6f0c454189
-  data.tar.gz: 8118612aa2c405d37dd6460a72aac666faec1317f8f6b0d98bcbcc6d039201f57a90fed64d36e3f4dcdd2e8fce198dae5abbdbca05ed8031869b19e62a50a420
+  metadata.gz: dfed9354d3578d4b0588081883fc37c66f003556379f1e13af8290b9248fd61d169364c1b59eae8d8d64dfb6e8f1caf16aa86866eb662fb8ecbb40b0b53f2ceb
+  data.tar.gz: ca2d4ca534ad631e78bb5deed5a996c9b8f8d82b7ab45f76e3419eb816bdf7c8525a73035b9a43167d05a4e374fe37414dfd7b7e964a6a191cc40cd3e7929233

data/AGENTS.md

@@ -4,13 +4,38 @@ Use this file when an AI coding agent is integrating `stimulus-password-strength
 
 ## Goal
 
-Treat this gem as a UI layer for password UX, not as password security policy.
+Treat this gem as a password UX simplification tool. Its purpose is to help the host app reduce signup friction while keeping backend security intentional.
 
 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
+- make simplification decisions explicit instead of silently preserving legacy friction
+
+## Required Decision Prompts
+
+Before integrating the gem into an existing app, inspect the current auth flow and ask the user explicit product/security questions when friction is detected.
+
+At minimum, ask about:
+
+1. `password_confirmation`
+   - Example: `I detected password_confirmation in signup/reset. Do you want to keep it for compatibility, or simplify to a single password field with the gem's show/hide toggle?`
+2. Complex password policy
+   - Example: `I detected uppercase/lowercase/digit/special-char rules. Do you want to keep that policy, or simplify to a length-first policy and align the UI + backend?`
+   - If the user wants signup simplification, explicitly recommend reviewing whether composition rules can be removed in favor of a longer minimum length.
+   - Example: `I detected composition rules such as uppercase/digit/special character requirements. These usually add friction and reduce conversion. Do you want to replace them with a longer minimum length and remove the composition rules? The gem still gives users a password strength meter, so they can create a stronger, more memorable password instead of a forced hard-to-remember character mix.`
+3. Existing custom password UI
+   - Example: `I detected a custom password meter/toggle/controller. Do you want a full migration to the gem, or a partial rollout first?`
+4. Tests coupled to the old implementation
+   - Example: `I detected tests tied to custom password markup or password_confirmation. Do you want me to migrate them now to the new UX contract?`
+5. Rollout scope
+   - Example: `Do you want UI-only adoption first, or do you want the gem rollout to also simplify the auth flow in the same change?`
+6. Extra signup fields
+   - Example: `I detected a required username field during signup. If the app does not truly need usernames, do you want to simplify the form to just email + password? Extra fields usually increase signup time and abandonment risk.`
+7. Browser-level required validation
+   - Example: `I detected that some signup fields are not marked as required in the HTML. Do you want me to align the form with backend-required fields so users get immediate browser validation feedback?`
+
+Do not make these simplification decisions silently. Detect them, explain the tradeoff, and ask.
 
 ## Recommended Rollout
 
@@ -31,9 +56,12 @@ bin/rails generate stimulus_password_strength:install
    - 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.
+6. If the host app has legacy friction such as `password_confirmation` or complex regex policy, ask whether that friction should be removed as part of this rollout.
+7. If the user chooses simplification, migrate backend validation, views, and tests together so the UX and policy stay aligned.
+8. If the user chooses compatibility, keep the existing policy but still move the UI to the gem.
+9. When simplification is chosen, prefer proposing a longer minimum length over uppercase/digit/special-character composition rules.
+10. Explain that the strength meter remains in place, so the user still gets guidance toward a strong password without being forced into brittle, hard-to-remember character patterns.
+11. Review whether signup can be reduced to just email + password. If `username` is not a real product requirement, recommend removing it.
 
 ## Host App Checks
 
@@ -44,14 +72,31 @@ Before changing any auth flow, verify:
 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?
+6. Are user-facing required fields also marked as `required` in the HTML where appropriate?
 
-## What Not to Change Automatically
+## What Not to Change Silently
 
-1. Do not remove `password_confirmation` without reviewing validations, tests, and reset flow behavior.
+1. Do not remove `password_confirmation` without confirming that simplification is desired and then updating 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.
+6. Do not rely only on backend validation when the browser can provide immediate required-field feedback safely.
+
+## Simplification Heuristic
+
+If the app has obvious signup friction and the user has not stated a preference yet, lead with a recommendation to simplify:
+
+1. Prefer one password field over `password_confirmation` when the host app can support it.
+2. Prefer a length-first policy over composition rules when the product goal is conversion and the host app allows policy changes.
+3. If composition rules exist, ask whether they should be replaced with a sufficiently long minimum length rather than kept by default.
+4. When recommending that change, explain that the gem's strength meter still guides the user toward a hard-to-crack password while allowing more memorable passphrase-style choices.
+5. Prefer one shared `PasswordPolicy` for backend validation and gem requirements.
+6. Prefer behavior-based tests over markup-coupled tests.
+7. If signup asks for `username`, ask whether it is truly required. If not, recommend reducing the form to email + password.
+8. Ensure user-facing required fields are marked with the HTML `required` attribute when that matches backend expectations.
+
+Then ask for confirmation before changing policy or contract.
 
 ## Minimal Smoke Test
 

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.1.4
+
+- fixed a rendering bug where the password strength bar could stay visually hidden even though the label updated
+- moved critical strength-bar and requirement layout fallbacks into inline styles so host-app Tailwind overrides cannot collapse the bar height or visibility
+- preserved requirement base typography when pending/met/unmet states are updated in Stimulus
+- expanded test coverage for the new style fallback properties and visible-bar behavior
+
+## 0.1.3
+
+- clarified the public README around adaptive usage modes: UI-only integration vs conversion-focused signup simplification
+- expanded `AGENTS.md` and `CLAUDE.md` so coding agents screen the host app before integration and ask explicit questions about password confirmation, composition rules, extra signup fields, and HTML `required` support
+- documented the recommended simplification path: length-first password policy, one password field with show/hide, and email + password only when extra signup fields are not true product requirements
+
 ## 0.1.2
 
 - switched gem packaging to `git ls-files`

data/CLAUDE.md

@@ -4,8 +4,13 @@ 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.
+1. Detect auth friction before changing code: `password_confirmation`, regex-heavy policy, custom password UI, and tests coupled to old markup.
+2. Ask explicit decision questions before assuming compatibility mode. This gem is meant to simplify auth UX, not only replace markup.
+3. If the app has uppercase/digit/special-character rules and the user wants simplification, ask whether they should be replaced with a longer minimum length to reduce signup friction.
+4. When making that recommendation, explain that the gem still provides a strength meter, so users are guided toward stronger and more memorable passwords instead of forced character patterns.
+5. If signup includes `username`, ask whether it is truly needed. If not, recommend reducing the form to email + password.
+6. Check whether user-facing required fields are also marked with the HTML `required` attribute so the browser can assist with validation immediately.
+7. If the user wants simplification, migrate policy, views, and tests together instead of doing UI-only halfway changes.
+8. Prefer using the generated `PasswordPolicy` as the source of truth for both model validation and gem requirements.
+9. Update every user-facing password flow, not just signup.
+10. After integration, run a smoke test for signup, password reset, autofill, and password manager overlay behavior.

data/README.md

@@ -2,6 +2,8 @@
 
 Importmap-friendly password strength field for Rails 8+ with Stimulus, `zxcvbn`, and Tailwind-friendly markup.
 
+Use it either as a drop-in password UX upgrade or as part of a broader signup simplification rollout. The same gem can support a conservative integration that only adds the strength meter and toggle, or a conversion-focused integration that helps remove unnecessary auth friction such as password confirmation, composition rules, or extra signup fields.
+
 ## Product Goal
 
 Reduce signup abandonment by improving password UX:
@@ -12,6 +14,11 @@ Reduce signup abandonment by improving password UX:
 - no Node.js required in the host app
 - simpler signup flow while keeping security standards and sound UX practices
 
+This gem is intentionally adaptive. Depending on the host app and the user's product goal, it can be used in two valid modes:
+
+- UI integration only: add the password strength meter, requirements, and show/hide toggle while keeping the existing auth policy
+- conversion-focused simplification: use the gem rollout to simplify the signup flow, reduce unnecessary password friction, and improve registration completion
+
 ## What the Gem Includes
 
 - Rails engine: `StimulusPasswordStrength::Engine`
@@ -135,6 +142,42 @@ Adding more languages is standard Rails I18n: add another locale file in [config
 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.
 
+## Migrating from Custom Password UI
+
+If the host app already has its own password strength UI, this is a migration, not a fresh install.
+
+Typical signs:
+
+- a custom Stimulus controller such as `password_field_controller.js`
+- manual strength bar markup in signup or reset views
+- a custom `zxcvbn` pin in `config/importmap.rb`
+- tests tied to old DOM details such as `data-testid="password-input"`
+
+Recommended migration order:
+
+1. Add the gem and run the installer.
+2. Move the real password rule into `PasswordPolicy`.
+3. Replace the custom password markup with `password_strength_field` in:
+   - signup / registration
+   - password reset / change password
+4. Remove the old password-specific Stimulus controller and its registration from `app/javascript/controllers/index.js`.
+5. Remove duplicate importmap pins if the app already pinned `zxcvbn` or a custom password controller setup.
+6. Update tests to target user-facing behavior, not the old internal DOM structure.
+
+For example, prefer:
+
+```ruby
+fill_in "Password", with: "SecurePass123!"
+```
+
+instead of a selector tied to the old implementation:
+
+```ruby
+find("[data-testid='password-input']").fill_in with: "SecurePass123!"
+```
+
+After migration, there should be only one password UI implementation in the app: the gem-based one.
+
 ## Agent Guidance
 
 If you are installing this gem through an AI coding agent, use:
@@ -142,7 +185,7 @@ 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.
+These files contain agent-specific project screening, rollout, and simplification guidance. They tell the agent how to inspect the host app, which questions to ask before changing auth UX, and how to choose between compatibility mode and conversion-focused simplification. Keep that logic there, not in this README.
 
 ## Example Adaptation: `linked_flow`
 
@@ -152,20 +195,6 @@ The gem was also used in `../linked_flow` as an example of a more opinionated UX
 - 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
@@ -175,8 +204,3 @@ 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/app/javascript/stimulus_password_strength_controller.js

@@ -31,6 +31,7 @@ export default class extends Controller {
     if (password.length === 0) {
       this.statusRowTarget.style.visibility = "hidden"
       this.strengthTrackTarget.style.visibility = "hidden"
+      this.strengthBarTarget.style.visibility = "hidden"
       this.strengthBarTarget.style.width = "0%"
       this.strengthBarTarget.style.backgroundColor = ""
       this.strengthTextTarget.textContent = ""
@@ -41,6 +42,7 @@ export default class extends Controller {
 
     this.statusRowTarget.style.visibility = "visible"
     this.strengthTrackTarget.style.visibility = "visible"
+    this.strengthBarTarget.style.visibility = "visible"
     const score = this.scoreFor(password)
     const widths = [10, 25, 50, 75, 100]
     const labels = ["weak", "weak", "fair", "good", "strong"]
@@ -131,7 +133,7 @@ export default class extends Controller {
       if (password.length === 0) {
         element.setAttribute("aria-hidden", "false")
         element.innerHTML = this.escapeHtml(element.dataset.label)
-        element.style.cssText = `${element.dataset.pendingStyle}; visibility: visible;`
+        element.style.cssText = `${element.dataset.baseStyle}; ${element.dataset.pendingStyle}; visibility: visible;`
         return
       }
 
@@ -140,8 +142,8 @@ export default class extends Controller {
         ? this.metRequirementMarkup(element)
         : this.escapeHtml(this.requirementLabel(element, password))
       element.style.cssText = isMet
-        ? `${element.dataset.metStyle}; visibility: visible;`
-        : `${element.dataset.unmetStyle}; visibility: visible;`
+        ? `${element.dataset.baseStyle}; ${element.dataset.metStyle}; visibility: visible;`
+        : `${element.dataset.baseStyle}; ${element.dataset.unmetStyle}; visibility: visible;`
     })
   }
 

data/app/views/stimulus_password_strength/_field.html.erb

@@ -18,7 +18,7 @@
     <div class="<%= label_row_class %>">
       <%= form.label attribute, label, class: label_class %>
 
-      <div class="<%= header_aux_class %>">
+      <div class="<%= header_aux_class %>" style="<%= header_aux_style %>">
         <% if requirements.any? %>
           <div class="<%= requirements_class %>" style="<%= requirements_style %>">
             <% requirements.each do |requirement| %>
@@ -32,8 +32,9 @@
                  data-pending-style="<%= requirement_pending_style %>"
                  data-met-style="<%= requirement_met_style %>"
                  data-unmet-style="<%= requirement_unmet_style %>"
+                 data-base-style="<%= requirement_style %>"
                  class="<%= requirement_class %>"
-                 style="<%= requirement_pending_style %>"><%= requirement[:label] %></p>
+                 style="<%= requirement_style %>; <%= requirement_pending_style %>"><%= requirement[:label] %></p>
             <% end %>
           </div>
         <% end %>
@@ -41,8 +42,8 @@
     </div>
 
     <div data-password-strength-target="statusRow" class="<%= status_row_class %>" style="<%= status_row_style %>; visibility: hidden;">
-      <div data-password-strength-target="strengthTrack" class="<%= bar_track_class %>" style="visibility: hidden;">
-        <div data-password-strength-target="strengthBar" class="<%= bar_base_class %>" style="width: 0%"></div>
+      <div data-password-strength-target="strengthTrack" class="<%= bar_track_class %>" style="<%= bar_track_style %>">
+        <div data-password-strength-target="strengthBar" class="<%= bar_base_class %>" style="<%= bar_style %>; width: 0%"></div>
       </div>
 
       <p data-password-strength-target="strengthText" class="<%= text_base_class %>" style="<%= text_style %>" aria-live="polite"></p>
@@ -61,15 +62,16 @@
              data-pending-style="<%= requirement_pending_style %>"
              data-met-style="<%= requirement_met_style %>"
              data-unmet-style="<%= requirement_unmet_style %>"
+             data-base-style="<%= requirement_style %>"
              class="<%= requirement_class %>"
-             style="<%= requirement_pending_style %>"><%= requirement[:label] %></p>
+             style="<%= requirement_style %>; <%= requirement_pending_style %>"><%= requirement[:label] %></p>
         <% end %>
       </div>
     <% end %>
 
     <div data-password-strength-target="statusRow" class="<%= status_row_class %>" style="<%= status_row_style %>; visibility: hidden;">
-      <div data-password-strength-target="strengthTrack" class="<%= bar_track_class %>" style="visibility: hidden;">
-        <div data-password-strength-target="strengthBar" class="<%= bar_base_class %>" style="width: 0%"></div>
+      <div data-password-strength-target="strengthTrack" class="<%= bar_track_class %>" style="<%= bar_track_style %>">
+        <div data-password-strength-target="strengthBar" class="<%= bar_base_class %>" style="<%= bar_style %>; width: 0%"></div>
       </div>
 
       <p data-password-strength-target="strengthText" class="<%= text_base_class %>" style="<%= text_style %>" aria-live="polite"></p>

data/lib/stimulus_password_strength/configuration.rb

@@ -6,15 +6,19 @@ module StimulusPasswordStrength
                   :label_row_class,
                   :label_class,
                   :header_aux_class,
+                  :header_aux_style,
                   :status_row_class,
                   :status_row_style,
                   :requirements_class,
                   :requirements_style,
                   :requirement_class,
+                  :requirement_style,
                   :input_class,
                   :toggle_class,
                   :bar_track_class,
+                  :bar_track_style,
                   :bar_base_class,
+                  :bar_style,
                   :text_base_class,
                   :text_style,
                   :hint_class,
@@ -29,17 +33,21 @@ module StimulusPasswordStrength
       @label_row_class = "flex items-end justify-between gap-3"
       @label_class = "block text-sm font-medium text-gray-700"
       @header_aux_class = "flex justify-end"
+      @header_aux_style = "display: flex; justify-content: flex-end; align-items: center;"
       @status_row_class = "flex min-h-5 items-center gap-2"
-      @status_row_style = "min-height: 1rem;"
+      @status_row_style = "display: flex; align-items: center; gap: 0.5rem; min-height: 1rem;"
       @requirements_class = "flex justify-end gap-2"
-      @requirements_style = "min-height: 1rem;"
+      @requirements_style = "display: flex; justify-content: flex-end; align-items: center; gap: 0.5rem; min-height: 1rem;"
       @requirement_class = "text-xs text-right leading-tight"
+      @requirement_style = "font-size: 0.75rem; line-height: 1rem; text-align: right;"
       @input_class = "w-full rounded-xl border border-gray-300 px-4 py-3 pr-16 shadow-sm focus:border-blue-500 focus:ring-2 focus:ring-blue-200"
       @toggle_class = "absolute right-3 top-1/2 -translate-y-1/2 cursor-pointer text-xs font-medium text-gray-500 hover:text-gray-700"
       @bar_track_class = "h-1.5 w-20 overflow-hidden rounded-full bg-gray-100"
+      @bar_track_style = "height: 0.375rem; width: 5rem; overflow: hidden; border-radius: 9999px; background-color: #f3f4f6; visibility: hidden; flex-shrink: 0;"
       @bar_base_class = "h-full rounded-full transition-all duration-300"
+      @bar_style = "display: block; height: 100%; border-radius: 9999px; visibility: hidden; transition: width 300ms ease, background-color 300ms ease;"
       @text_base_class = "text-xs"
-      @text_style = "min-width: 2.5rem; text-align: right; white-space: nowrap;"
+      @text_style = "display: block; min-width: 2.5rem; text-align: right; white-space: nowrap;"
       @hint_class = "mt-1 text-xs text-gray-500"
       @requirement_pending_style = "color: #6b7280;"
       @requirement_met_style = "color: #047857;"

data/lib/stimulus_password_strength/helper.rb

@@ -16,14 +16,18 @@ module StimulusPasswordStrength
       label_row_class = options.delete(:label_row_class) || config.label_row_class
       label_class = options.delete(:label_class) || config.label_class
       header_aux_class = options.delete(:header_aux_class) || config.header_aux_class
+      header_aux_style = options.delete(:header_aux_style) || config.header_aux_style
       status_row_class = options.delete(:status_row_class) || config.status_row_class
       status_row_style = options.delete(:status_row_style) || config.status_row_style
       requirements_class = options.delete(:requirements_class) || config.requirements_class
       requirements_style = options.delete(:requirements_style) || config.requirements_style
       requirement_class = options.delete(:requirement_class) || config.requirement_class
+      requirement_style = options.delete(:requirement_style) || config.requirement_style
       toggle_class = options.delete(:toggle_class) || config.toggle_class
       bar_track_class = options.delete(:bar_track_class) || config.bar_track_class
+      bar_track_style = options.delete(:bar_track_style) || config.bar_track_style
       bar_base_class = options.delete(:bar_base_class) || config.bar_base_class
+      bar_style = options.delete(:bar_style) || config.bar_style
       text_base_class = options.delete(:text_base_class) || config.text_base_class
       text_style = options.delete(:text_style) || config.text_style
       hint_class = options.delete(:hint_class) || config.hint_class
@@ -46,14 +50,18 @@ module StimulusPasswordStrength
         label_row_class: label_row_class,
         label_class: label_class,
         header_aux_class: header_aux_class,
+        header_aux_style: header_aux_style,
         status_row_class: status_row_class,
         status_row_style: status_row_style,
         requirements_class: requirements_class,
         requirements_style: requirements_style,
         requirement_class: requirement_class,
+        requirement_style: requirement_style,
         toggle_class: toggle_class,
         bar_track_class: bar_track_class,
+        bar_track_style: bar_track_style,
         bar_base_class: bar_base_class,
+        bar_style: bar_style,
         text_base_class: text_base_class,
         text_style: text_style,
         hint_class: hint_class,

data/lib/stimulus_password_strength/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module StimulusPasswordStrength
-  VERSION = "0.1.2"
+  VERSION = "0.1.4"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: stimulus-password-strength
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.4
 platform: ruby
 authors:
 - Justyna Wojtczak