number_flow 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a4f1f61448b85a4aa44d8fa3956899b594d490f6af920018652e149ae35ebd5d
-  data.tar.gz: b5e694d0edad03f5cd73dc17f5b3f0e3518bbcf809748f403f1ec1763d303b55
+  metadata.gz: 4b0cf284b80b9ebdd51127edf90746a9bf77e4f6c323f8dcd3917757ea82600f
+  data.tar.gz: 3f254dfe37f23d253477ab5bb574f0f76f982e82de16f36c6385102946991dc0
 SHA512:
-  metadata.gz: 97efbebd67b86c36be60d33a557ea03009cbda3939f828ec1e328674a51643ab47369789bbb3337ad27016d7f9dd4f8cbd494c432572ae6ac8b8244fac86ea04
-  data.tar.gz: c3a9afd1531ba668775bfa1876ead4899ac0225810327f5da99c2d2e6932c73c7edcb18885b7760c9af23c59193bd265221d7b34929e6ef465c235f979c09e07
+  metadata.gz: 69d1fdc102f5c9b2a751c8988a4276e263bf8f9a289fb517db2d54750676fbda4fcf6eda6d70aaa1f3a2786f56938949023f13927918d2d4822007d3e5bbd31a
+  data.tar.gz: 6ef6f8f6f2f3a4627a1ebbc0192180df55a9a6387bff5649f12aac5d0e1eec65051636cdf5669b84b9fa3790b8f5b865804b8270848f3e7fbfd9c50b23e6e3c5

data/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-07-13
+
+### Added
+- Decimal and fractional number animations with configurable precision and rollover behavior.
+- Locale-aware number formatting powered by `Intl.NumberFormat`.
+- Optional `NumberFlow::Component` integration and a Vite installer generator.
+- Chromium/Cuprite browser coverage and continuous integration for browser behavior.
+
+### Changed
+- Improved negative-number and reduced-motion animation behavior.
+- Documented the decision to keep Number Flow distributed as a Ruby gem.
+
 ## [0.1.2] - 2026-07-12
 
 ### Changed

data/README.md

@@ -1,7 +1,8 @@
 # NumberFlow
 
-Rails helper + Stimulus controller for smooth integer digit transitions inspired by [number-flow](https://github.com/barvian/number-flow).
+Rails helper + Stimulus controller for smooth number digit transitions (integers, decimals, locale-aware) inspired by [number-flow](https://github.com/barvian/number-flow).
 
+[![CI](https://github.com/dpaluy/number_flow/actions/workflows/ci.yml/badge.svg)](https://github.com/dpaluy/number_flow/actions/workflows/ci.yml)
 [![Gem Version](https://badge.fury.io/rb/number_flow.svg)](https://badge.fury.io/rb/number_flow)
 
 `number_flow` ships both CSS and JavaScript assets inside the gem, so you do not need a separate npm package.
@@ -37,6 +38,8 @@ Add this in your layout (or import into your main stylesheet):
 
 ### 2) Register the Stimulus controller
 
+#### Sprockets / Importmap
+
 With importmap (`config/importmap.rb`):
 
 ```ruby
@@ -52,25 +55,56 @@ import NumberFlowController from "number_flow/controller"
 application.register("number-flow", NumberFlowController)
 ```
 
+#### Vite Rails
+
+Use the built-in generator to copy assets into `app/frontend/`:
+
+```sh
+rails g number_flow:install --vite
+```
+
+This copies:
+- `controller.js` → `app/frontend/controllers/number_flow_controller.js`
+- `number_flow.css` → `app/frontend/stylesheets/number_flow.css`
+
+If `app/frontend/entrypoints/application.js` exists, the controller import and registration are appended automatically (idempotent — re-running won't duplicate).
+
+Without `--vite`, the generator prints the Sprockets/importmap setup instructions above.
+
 ## Usage
 
-Render a value:
+Render an integer:
 
 ```erb
 <%= number_flow_tag(12_345) %>
 ```
 
+Render a decimal with precision:
+
+```erb
+<%= number_flow_tag(12.34, precision: 2) %>
+```
+
+Locale-aware formatting (uses `Intl.NumberFormat` on the client):
+
+```erb
+<%= number_flow_tag(1234.5, precision: 1, locale: "de-DE", grouping: true) %>
+<!-- renders as 1.234,5 -->
+```
+
 Render with options:
 
 ```erb
 <%= number_flow_tag(
-  12_345,
+  12_345.67,
+  precision: 2,
   class: "kpi-value",
   duration: 550,
   easing: "ease-out",
   stagger: 30,
   grouping: true,
-  aria_label: "Current total users"
+  locale: "en-US",
+  aria_label: "Current total revenue"
 ) %>
 ```
 
@@ -80,7 +114,7 @@ Update from JavaScript:
 const element = document.querySelector("[data-controller='number-flow']")
 element.dispatchEvent(
   new CustomEvent("number-flow:update", {
-    detail: { value: 12987 }
+    detail: { value: 12987.50 }
   })
 )
 ```
@@ -96,9 +130,21 @@ Options:
 - `easing:` CSS easing function (default: `cubic-bezier(0.2, 0, 0, 1)`)
 - `stagger:` per-digit delay in milliseconds (default: `20`)
 - `grouping:` show thousands separators (default: `false`)
+- `precision:` number of decimal digits (default: `0` — integer mode)
+- `locale:` BCP 47 locale tag for formatting (default: `nil` → browser default)
 - `aria_label:` explicit `aria-label`
 - `data:` additional data attributes merged into the root element
 
+## Optional ViewComponent Wrapper
+
+If your app uses [ViewComponent](https://github.com/github/view_component), `NumberFlow::Component` is available as a thin wrapper:
+
+```erb
+<%= render(NumberFlow::Component.new(value: 42, precision: 2)) %>
+```
+
+The component is only defined when the `view_component` gem is present. The gem does **not** add `view_component` as a runtime dependency. Add it to your app's Gemfile to use the component API.
+
 ## Accessibility
 
 - Root element uses `role="status"` and `aria-live="polite"`.
@@ -106,7 +152,17 @@ Options:
 
 ## Error Handling
 
-`number_flow_tag` raises `ArgumentError` when `value` cannot be coerced into an integer.
+`number_flow_tag` raises `ArgumentError` when `value` cannot be coerced into a numeric value.
+
+## Why No npm Package?
+
+**Decision: gem-only distribution.** The Stimulus controller consumes data attributes (`data-number-flow-value-value`, `data-number-flow-precision-value`, etc.) that are emitted by the Ruby helper. The JS is not standalone — it depends on the gem's markup contract. Publishing to npm would:
+
+1. **Double maintenance** for no standalone value — two version tracks, two release workflows, two changelogs.
+2. **Not solve a real problem** — Vite/importmap integration (via the install generator) already covers asset resolution without npm.
+3. **Conflict with positioning** — the gem already markets gem-only as a feature.
+
+**Revisit trigger:** if a framework-agnostic core (pure formatting + DOM, no Rails-helper coupling) is extracted, or if community demand materializes for importing the controller from `@dpaluy/number_flow` in a non-Rails context. Until then: won't ship.
 
 ## Development
 
@@ -115,6 +171,12 @@ bundle exec rake test
 bundle exec rubocop
 ```
 
+Browser system tests require Chrome/Chromium:
+
+```sh
+RUN_SYSTEM_TESTS=true bundle exec rake test
+```
+
 ## Contributing
 
 Bug reports and pull requests are welcome on [GitHub](https://github.com/dpaluy/number_flow/issues).

data/app/assets/javascripts/number_flow/controller.js

@@ -8,7 +8,9 @@ export default class extends Controller {
     duration: Number,
     easing: String,
     stagger: Number,
-    grouping: Boolean
+    grouping: Boolean,
+    precision: Number,
+    locale: String
   }
 
   connect() {
@@ -41,41 +43,33 @@ export default class extends Controller {
       return
     }
 
-    this.updateTo(Math.trunc(nextValue))
+    this.updateTo(nextValue)
   }
 
   updateTo(nextValue) {
-    const normalized = Math.trunc(nextValue)
-    if (normalized === this.currentValue) return
+    if (nextValue === this.currentValue) return
+    if (!this.currentParts) return // Guard: not yet connected
 
     this.applyTimingVariables()
-    this.render(normalized, !this.prefersReducedMotion())
-    this.currentValue = normalized
-    this.valueValue = normalized
+    this.render(nextValue, !this.prefersReducedMotion())
+    this.currentValue = nextValue
+    this.valueValue = nextValue
   }
 
   render(value, animate) {
-    const previousDigits = this.currentParts.filter((part) => part.kind === "digit").map((part) => part.value)
+    const previousParts = this.currentParts
     const nextParts = this.partsFor(value)
-    const nextDigits = nextParts.filter((part) => part.kind === "digit").map((part) => part.value)
-
-    let digitIndex = 0
-    const totalDigits = nextDigits.length
     const fragment = document.createDocumentFragment()
 
-    nextParts.forEach((part) => {
+    nextParts.forEach((part, index) => {
       if (part.kind === "separator") {
         fragment.appendChild(this.buildSeparatorNode(part.value))
         return
       }
 
-      const remaining = totalDigits - digitIndex
-      const previousIndex = previousDigits.length - remaining
-      const fromDigit = previousIndex >= 0 ? previousDigits[previousIndex] : 0
-      const toDigit = part.value
-      const indexFromRight = totalDigits - digitIndex - 1
-      fragment.appendChild(this.buildDigitNode(fromDigit, toDigit, indexFromRight, animate))
-      digitIndex += 1
+      const { fromDigit } = this.alignDigit(previousParts, nextParts, index)
+      const indexFromRight = nextParts.length - index - 1
+      fragment.appendChild(this.buildDigitNode(fromDigit, part.value, indexFromRight, animate))
     })
 
     this.element.replaceChildren(fragment)
@@ -92,6 +86,20 @@ export default class extends Controller {
     this.currentParts = nextParts
   }
 
+  alignDigit(previousParts, nextParts, currentIndex) {
+    const nextDigits = nextParts.filter((p) => p.kind === "digit")
+    const previousDigits = previousParts.filter((p) => p.kind === "digit")
+
+    const currentDigitIndex = nextParts.slice(0, currentIndex).filter((p) => p.kind === "digit").length
+    const remaining = nextDigits.length - currentDigitIndex
+    const previousIndex = previousDigits.length - remaining
+
+    const fromDigit = previousIndex >= 0 ? previousDigits[previousIndex].value : 0
+    const toDigit = nextParts[currentIndex].value
+
+    return { fromDigit, toDigit }
+  }
+
   partsFor(value) {
     return this.formattedString(value).split("").map((char) => {
       if (/\d/.test(char)) {
@@ -103,10 +111,14 @@ export default class extends Controller {
   }
 
   formattedString(value) {
-    const sign = value < 0 ? "-" : ""
-    const digits = Math.abs(value).toString()
-    const groupedDigits = this.groupingValue ? digits.replace(/\B(?=(\d{3})+(?!\d))/g, ",") : digits
-    return `${sign}${groupedDigits}`
+    const formatter = new Intl.NumberFormat(this.localeValue || undefined, {
+      useGrouping: this.groupingValue,
+      minimumFractionDigits: this.precisionValue,
+      maximumFractionDigits: this.precisionValue
+    })
+
+    const formatted = formatter.format(Math.abs(value))
+    return value < 0 ? `-${formatted}` : formatted
   }
 
   buildDigitNode(fromDigit, toDigit, indexFromRight, animate) {
@@ -150,19 +162,19 @@ export default class extends Controller {
 
   initialValue() {
     if (this.hasValueValue && Number.isFinite(this.valueValue)) {
-      return Math.trunc(this.valueValue)
+      return this.valueValue
     }
 
     const inlineValue = Number(this.element.getAttribute("data-number-flow-value-value"))
     if (Number.isFinite(inlineValue)) {
-      return Math.trunc(inlineValue)
+      return inlineValue
     }
 
     return 0
   }
 
   prefersReducedMotion() {
-    return this.reducedMotionMedia.matches
+    return this.reducedMotionMedia?.matches === true
   }
 
   durationOrDefault() {
@@ -170,7 +182,7 @@ export default class extends Controller {
   }
 
   easingOrDefault() {
-    return this.hasEasingValue ? this.easingValue : "cubic-bezier(0.2, 0, 0, 1)"
+    return this.hasEasingValue ? this.easingValue : "cubic-bezier(0.2, 0, 1)"
   }
 
   staggerOrDefault() {
@@ -181,4 +193,3 @@ export default class extends Controller {
     return typeof document !== "undefined" && document.location?.hostname === "localhost"
   }
 }
-

data/app/components/number_flow/component.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require 'number_flow/helper'
+
+begin
+  require 'view_component'
+rescue LoadError
+  # ViewComponent is not installed — Component is not defined.
+end
+
+module NumberFlow
+  # Optional ViewComponent wrapper around the +number_flow_tag+ helper.
+  # Only defined when the +view_component+ gem is available, so the gem
+  # never forces a hard dependency.
+  if defined?(::ViewComponent)
+    class Component < ::ViewComponent::Base
+      include NumberFlow::Helper
+
+      def initialize(value:, **options)
+        @value = value
+        @options = options
+        super()
+      end
+
+      def call
+        number_flow_tag(@value, **@options)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+require 'rails/generators/base'
+
+module NumberFlow
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      desc 'Install NumberFlow for your asset pipeline (Sprockets, importmap, or Vite Rails).'
+
+      class_option :vite, type: :boolean, default: false,
+                          desc: 'Copy controller and stylesheet into app/frontend for Vite Rails'
+
+      source_root File.expand_path('../../../..', __dir__)
+
+      CONTROLLER_SOURCE = 'app/assets/javascripts/number_flow/controller.js'
+      CSS_SOURCE = 'app/assets/stylesheets/number_flow.css'
+      VITE_CONTROLLER_TARGET = 'app/frontend/controllers/number_flow_controller.js'
+      VITE_CSS_TARGET = 'app/frontend/stylesheets/number_flow.css'
+      VITE_ENTRYPOINT = 'app/frontend/entrypoints/application.js'
+
+      def install
+        if options[:vite]
+          install_vite
+        else
+          install_standard
+        end
+      end
+
+      private
+
+      def install_vite
+        say_status('info', 'Installing NumberFlow for Vite Rails', :blue)
+
+        copy_file(CONTROLLER_SOURCE, VITE_CONTROLLER_TARGET)
+        copy_file(CSS_SOURCE, VITE_CSS_TARGET)
+        register_stimulus_controller
+      end
+
+      def install_standard
+        say_status('info', 'NumberFlow assets are served from the gem (Sprockets/importmap).', :blue)
+        say('')
+        say('1. Load the stylesheet in your layout:')
+        say('   <%= stylesheet_link_tag "number_flow", "data-turbo-track": "reload" %>')
+        say('')
+        say('2. Pin the controller (config/importmap.rb):')
+        say('   pin "number_flow/controller", to: "number_flow/controller.js"')
+        say('')
+        say('3. Register in app/javascript/controllers/index.js:')
+        say('   import NumberFlowController from "number_flow/controller"')
+        say('   application.register("number-flow", NumberFlowController)')
+      end
+
+      def register_stimulus_controller
+        return unless File.exist?(File.expand_path(VITE_ENTRYPOINT, destination_root))
+
+        entrypoint_path = File.expand_path(VITE_ENTRYPOINT, destination_root)
+        content = File.read(entrypoint_path)
+
+        import_line = 'import NumberFlowController from "../controllers/number_flow_controller"'
+        register_line = 'application.register("number-flow", NumberFlowController)'
+
+        return if content.include?(import_line)
+
+        inject_into_file(VITE_ENTRYPOINT, "  #{import_line}\n", after: /import application from.*\n/)
+
+        unless content.include?(register_line)
+          inject_into_file(VITE_ENTRYPOINT, "  #{register_line}\n",
+                           after: /application = Application\.start.*\n/)
+        end
+
+        say_status('create', "#{VITE_ENTRYPOINT} (updated)", :green)
+      end
+    end
+  end
+end

data/lib/number_flow/helper.rb

@@ -14,12 +14,14 @@ module NumberFlow
       easing: DEFAULT_EASING,
       stagger: DEFAULT_STAGGER,
       grouping: false,
+      precision: 0,
+      locale: nil,
       aria_label: nil,
       data: {},
       **html_options
     )
-      normalized_value = Integer(value)
-      formatted_value = format_integer(normalized_value, grouping: grouping)
+      normalized_value = coerce_number(value)
+      formatted_value = format_number(normalized_value, precision: precision, grouping: grouping, locale: locale)
       css_class = html_options.delete(:class)
       extra_data = html_options.delete(:data)
 
@@ -38,7 +40,9 @@ module NumberFlow
             number_flow_duration_value: Integer(duration),
             number_flow_easing_value: easing.to_s,
             number_flow_stagger_value: Integer(stagger),
-            number_flow_grouping_value: grouping == true
+            number_flow_grouping_value: grouping == true,
+            number_flow_precision_value: precision.positive? ? Integer(precision) : nil,
+            number_flow_locale_value: locale
           },
           normalize_data_hash(data),
           normalize_data_hash(extra_data)
@@ -49,11 +53,22 @@ module NumberFlow
         safe_join(formatted_value.chars.map { |char| build_character_fragment(char) })
       end
     rescue ArgumentError, TypeError
-      raise ArgumentError, 'number_flow_tag expects an integer-compatible value'
+      raise ArgumentError, 'number_flow_tag expects a numeric value'
     end
 
     private
 
+    def coerce_number(value)
+      case value
+      when Integer, Float
+        value
+      when String
+        Float(value)
+      else
+        value.respond_to?(:to_f) ? Float(value.to_f) : (raise ArgumentError)
+      end
+    end
+
     def build_character_fragment(char)
       if char.match?(/\d/)
         build_digit_fragment(char.to_i)
@@ -80,11 +95,40 @@ module NumberFlow
       end
     end
 
-    def format_integer(value, grouping:)
+    def format_number(value, precision:, grouping:, locale:)
       sign = value.negative? ? '-' : ''
-      digits = value.abs.to_s
-      grouped = grouping ? digits.reverse.scan(/.{1,3}/).join(',').reverse : digits
-      "#{sign}#{grouped}"
+      abs_value = value.abs
+      decimal_sep = locale_decimal_separator(locale)
+      group_sep = locale_group_separator(locale)
+
+      if precision.positive?
+        integer_part = Integer(abs_value.floor)
+        fraction = format('%.0f', (abs_value - integer_part) * (10**precision)).rjust(precision, '0')
+        number_str = "#{group_digits(integer_part, grouping, group_sep)}#{decimal_sep}#{fraction}"
+      else
+        number_str = group_digits(Integer(abs_value), grouping, group_sep)
+      end
+
+      "#{sign}#{number_str}"
+    end
+
+    def group_digits(integer, grouping, separator)
+      digits = integer.to_s
+      return digits unless grouping
+
+      digits.reverse.scan(/.{1,3}/).join(separator).reverse
+    end
+
+    def locale_decimal_separator(locale)
+      return ',' if locale && !locale.start_with?('en')
+
+      '.'
+    end
+
+    def locale_group_separator(locale)
+      return '.' if locale && !locale.start_with?('en')
+
+      ','
     end
 
     def merged_data_attributes(*hashes)

data/lib/number_flow/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module NumberFlow
-  VERSION = '0.1.2'
+  VERSION = '0.2.0'
 end

data/lib/number_flow.rb

@@ -7,3 +7,19 @@ require_relative 'number_flow/engine'
 module NumberFlow
   class Error < StandardError; end
 end
+
+# Load optional ViewComponent wrapper if the gem is present.
+begin
+  require 'view_component'
+  require_relative '../app/components/number_flow/component'
+rescue LoadError
+  # ViewComponent is not installed — Component stays undefined.
+end
+
+# Load Rails generators when Rails is available.
+begin
+  require 'rails'
+  require_relative 'generators/number_flow/install/install_generator'
+rescue LoadError
+  # Rails is not available — generators are not loaded.
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: number_flow
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - dpaluy
@@ -37,8 +37,8 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 8.1.0
-description: NumberFlow provides a Rails helper and Stimulus controller for smooth
-  integer digit transitions using gem-shipped CSS and JavaScript assets.
+description: NumberFlow provides a Rails helper and Stimulus controller for smooth,
+  locale-aware number transitions using gem-shipped CSS and JavaScript assets.
 email:
 - dpaluy@users.noreply.github.com
 executables: []
@@ -53,6 +53,8 @@ files:
 - README.md
 - app/assets/javascripts/number_flow/controller.js
 - app/assets/stylesheets/number_flow.css
+- app/components/number_flow/component.rb
+- lib/generators/number_flow/install/install_generator.rb
 - lib/number_flow.rb
 - lib/number_flow/engine.rb
 - lib/number_flow/helper.rb
@@ -83,5 +85,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.9
 specification_version: 4
-summary: Rails helper + Stimulus digit flow transitions for integers.
+summary: Rails helper + Stimulus transitions for animated numbers.
 test_files: []