number_flow 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3f31e242cb8f5c29ef2c788129623d60d4cdd3bf5ce65ea92060fde290c51ae5
+  data.tar.gz: 87473cf2e807ab5779e983130a99012063a8bde1d8507ef341a61e17dfdbb883
+SHA512:
+  metadata.gz: 517de85f88f290d45cd4037d6230f999512c42039fc65f71de607df1065698b17754b1bd82cafbbf5990818792809275ffc893d5c33460fda394a51a6dec72f0
+  data.tar.gz: 07ef80244873796464a53b19074a07606cc5b78a67b90df4756f3e50385ad575e8839953d3cc4da66de381c81086a736f4d72950cb8bbf7c3c1365862e72ba82

data/CHANGELOG.md

@@ -0,0 +1,18 @@
+# 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.1.0/)
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-02-23
+
+### Added
+- Initial release of `number_flow`.
+- Rails helper API: `number_flow_tag`.
+- Rails engine integration for helper and assets.
+- Stimulus controller and CSS assets shipped inside the gem.
+- Minitest suite for helper and integration contracts.
+

data/LICENSE.txt

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 David
+
+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,124 @@
+# NumberFlow
+
+Rails helper + Stimulus controller for smooth integer digit transitions inspired by [number-flow](https://github.com/barvian/number-flow).
+
+[![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.
+
+## Original Project
+
+This gem is inspired by and references the original Number Flow project by Barvian:
+- https://github.com/barvian/number-flow
+
+`number_flow` is a Ruby/Rails adaptation and is not an official package from the original project maintainers.
+
+## Installation
+
+```sh
+bundle add number_flow
+```
+
+Or:
+
+```sh
+gem install number_flow
+```
+
+## Rails Setup
+
+### 1) Ensure the gem stylesheet is loaded
+
+Add this in your layout (or import into your main stylesheet):
+
+```erb
+<%= stylesheet_link_tag "number_flow", "data-turbo-track": "reload" %>
+```
+
+### 2) Register the Stimulus controller
+
+With importmap (`config/importmap.rb`):
+
+```ruby
+pin "number_flow/controller", to: "number_flow/controller.js"
+```
+
+Then register in `app/javascript/controllers/index.js`:
+
+```js
+import { application } from "./application"
+import NumberFlowController from "number_flow/controller"
+
+application.register("number-flow", NumberFlowController)
+```
+
+## Usage
+
+Render a value:
+
+```erb
+<%= number_flow_tag(12_345) %>
+```
+
+Render with options:
+
+```erb
+<%= number_flow_tag(
+  12_345,
+  class: "kpi-value",
+  duration: 550,
+  easing: "ease-out",
+  stagger: 30,
+  grouping: true,
+  aria_label: "Current total users"
+) %>
+```
+
+Update from JavaScript:
+
+```js
+const element = document.querySelector("[data-controller='number-flow']")
+element.dispatchEvent(
+  new CustomEvent("number-flow:update", {
+    detail: { value: 12987 }
+  })
+)
+```
+
+## API
+
+### `number_flow_tag(value, **options)`
+
+Options:
+- `id:` DOM id
+- `class:` extra CSS classes
+- `duration:` animation duration in milliseconds (default: `400`)
+- `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`)
+- `aria_label:` explicit `aria-label`
+- `data:` additional data attributes merged into the root element
+
+## Accessibility
+
+- Root element uses `role="status"` and `aria-live="polite"`.
+- `prefers-reduced-motion: reduce` disables animated transitions while still updating values.
+
+## Error Handling
+
+`number_flow_tag` raises `ArgumentError` when `value` cannot be coerced into an integer.
+
+## Development
+
+```sh
+bundle exec rake test
+bundle exec rubocop
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on [GitHub](https://github.com/dpaluy/number_flow/issues).
+
+## License
+
+MIT. See `LICENSE.txt`.

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

@@ -0,0 +1,184 @@
+import { Controller } from "@hotwired/stimulus"
+
+const UPDATE_EVENT = "number-flow:update"
+
+export default class extends Controller {
+  static values = {
+    value: Number,
+    duration: Number,
+    easing: String,
+    stagger: Number,
+    grouping: Boolean
+  }
+
+  connect() {
+    this.handleUpdate = this.handleUpdate.bind(this)
+    this.reducedMotionMedia = window.matchMedia("(prefers-reduced-motion: reduce)")
+    this.element.addEventListener(UPDATE_EVENT, this.handleUpdate)
+
+    this.applyTimingVariables()
+    this.currentValue = this.initialValue()
+    this.currentParts = []
+    this.render(this.currentValue, false)
+  }
+
+  disconnect() {
+    this.element.removeEventListener(UPDATE_EVENT, this.handleUpdate)
+  }
+
+  valueValueChanged(nextValue, previousValue) {
+    if (previousValue === undefined) return
+
+    this.updateTo(nextValue)
+  }
+
+  handleUpdate(event) {
+    const nextValue = Number(event?.detail?.value)
+    if (!Number.isFinite(nextValue)) {
+      if (this.isDevelopmentEnv()) {
+        console.warn("[number_flow] Ignoring non-numeric number-flow:update payload.")
+      }
+      return
+    }
+
+    this.updateTo(Math.trunc(nextValue))
+  }
+
+  updateTo(nextValue) {
+    const normalized = Math.trunc(nextValue)
+    if (normalized === this.currentValue) return
+
+    this.applyTimingVariables()
+    this.render(normalized, !this.prefersReducedMotion())
+    this.currentValue = normalized
+    this.valueValue = normalized
+  }
+
+  render(value, animate) {
+    const previousDigits = this.currentParts.filter((part) => part.kind === "digit").map((part) => part.value)
+    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) => {
+      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
+    })
+
+    this.element.replaceChildren(fragment)
+    this.element.setAttribute("aria-label", this.formattedString(value))
+
+    if (animate && !this.prefersReducedMotion()) {
+      requestAnimationFrame(() => {
+        this.element.querySelectorAll(".nf__track--animated").forEach((track) => {
+          track.style.setProperty("--nf-current-digit", track.dataset.toDigit)
+        })
+      })
+    }
+
+    this.currentParts = nextParts
+  }
+
+  partsFor(value) {
+    return this.formattedString(value).split("").map((char) => {
+      if (/\d/.test(char)) {
+        return { kind: "digit", value: Number(char) }
+      }
+
+      return { kind: "separator", value: char }
+    })
+  }
+
+  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}`
+  }
+
+  buildDigitNode(fromDigit, toDigit, indexFromRight, animate) {
+    const digit = document.createElement("span")
+    digit.className = "nf__digit"
+    digit.dataset.digit = String(toDigit)
+    digit.style.setProperty("--nf-index-from-right", String(indexFromRight))
+
+    const track = document.createElement("span")
+    track.className = animate ? "nf__track nf__track--animated" : "nf__track"
+    track.dataset.toDigit = String(toDigit)
+    track.style.setProperty("--nf-from-digit", String(fromDigit))
+    track.style.setProperty("--nf-to-digit", String(toDigit))
+    track.style.setProperty("--nf-current-digit", String(animate ? fromDigit : toDigit))
+
+    for (let value = 0; value <= 9; value += 1) {
+      const cell = document.createElement("span")
+      cell.className = "nf__cell"
+      cell.setAttribute("aria-hidden", "true")
+      cell.textContent = String(value)
+      track.appendChild(cell)
+    }
+
+    digit.appendChild(track)
+    return digit
+  }
+
+  buildSeparatorNode(value) {
+    const separator = document.createElement("span")
+    separator.className = "nf__separator"
+    separator.setAttribute("aria-hidden", "true")
+    separator.textContent = value
+    return separator
+  }
+
+  applyTimingVariables() {
+    this.element.style.setProperty("--nf-duration", `${this.durationOrDefault()}ms`)
+    this.element.style.setProperty("--nf-easing", this.easingOrDefault())
+    this.element.style.setProperty("--nf-stagger", `${this.staggerOrDefault()}ms`)
+  }
+
+  initialValue() {
+    if (this.hasValueValue && Number.isFinite(this.valueValue)) {
+      return Math.trunc(this.valueValue)
+    }
+
+    const inlineValue = Number(this.element.getAttribute("data-number-flow-value-value"))
+    if (Number.isFinite(inlineValue)) {
+      return Math.trunc(inlineValue)
+    }
+
+    return 0
+  }
+
+  prefersReducedMotion() {
+    return this.reducedMotionMedia.matches
+  }
+
+  durationOrDefault() {
+    return this.hasDurationValue ? this.durationValue : 400
+  }
+
+  easingOrDefault() {
+    return this.hasEasingValue ? this.easingValue : "cubic-bezier(0.2, 0, 0, 1)"
+  }
+
+  staggerOrDefault() {
+    return this.hasStaggerValue ? this.staggerValue : 20
+  }
+
+  isDevelopmentEnv() {
+    return typeof document !== "undefined" && document.location?.hostname === "localhost"
+  }
+}
+

data/app/assets/stylesheets/number_flow.css

@@ -0,0 +1,56 @@
+.nf {
+  --nf-duration: 400ms;
+  --nf-easing: cubic-bezier(0.2, 0, 0, 1);
+  --nf-stagger: 20ms;
+  --nf-digit-height: 1em;
+  --nf-gap: 0.04em;
+
+  display: inline-flex;
+  align-items: flex-end;
+  gap: var(--nf-gap);
+  line-height: 1;
+  white-space: nowrap;
+  font-variant-numeric: tabular-nums;
+}
+
+.nf__digit,
+.nf__separator {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  height: var(--nf-digit-height);
+}
+
+.nf__digit {
+  position: relative;
+  width: 0.68em;
+  overflow: hidden;
+}
+
+.nf__track {
+  display: flex;
+  flex-direction: column;
+  transform: translateY(calc(var(--nf-current-digit, 0) * var(--nf-digit-height) * -1));
+  will-change: transform;
+}
+
+.nf__track--animated {
+  transition-property: transform;
+  transition-duration: var(--nf-duration);
+  transition-timing-function: var(--nf-easing);
+  transition-delay: calc(var(--nf-stagger) * var(--nf-index-from-right, 0));
+}
+
+.nf__cell {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  height: var(--nf-digit-height);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .nf__track--animated {
+    transition: none;
+  }
+}
+

data/lib/number_flow/engine.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+begin
+  require 'active_support/core_ext/module/delegation'
+  require 'rails/engine'
+rescue LoadError
+  # Rails is not available in this runtime.
+end
+
+module NumberFlow
+  if defined?(Rails)
+    class Engine < ::Rails::Engine
+      initializer 'number_flow.action_view' do
+        ActiveSupport.on_load(:action_view) do
+          include NumberFlow::Helper
+        end
+      end
+
+      initializer 'number_flow.assets.precompile' do |app|
+        next unless app.config.respond_to?(:assets)
+
+        app.config.assets.precompile += %w[number_flow.css number_flow/controller.js]
+      end
+    end
+  end
+end

data/lib/number_flow/helper.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module NumberFlow
+  # View helper that renders number-flow compatible markup.
+  module Helper
+    DEFAULT_DURATION = 400
+    DEFAULT_EASING = 'cubic-bezier(0.2, 0, 0, 1)'
+    DEFAULT_STAGGER = 20
+
+    def number_flow_tag(
+      value,
+      id: nil,
+      duration: DEFAULT_DURATION,
+      easing: DEFAULT_EASING,
+      stagger: DEFAULT_STAGGER,
+      grouping: false,
+      aria_label: nil,
+      data: {},
+      **html_options
+    )
+      normalized_value = Integer(value)
+      formatted_value = format_integer(normalized_value, grouping: grouping)
+      css_class = html_options.delete(:class)
+      extra_data = html_options.delete(:data)
+
+      root_options = {
+        id: id,
+        role: 'status',
+        class: ['nf', css_class].compact.join(' '),
+        aria: {
+          live: 'polite',
+          label: aria_label || formatted_value
+        },
+        data: merged_data_attributes(
+          {
+            controller: 'number-flow',
+            number_flow_value_value: normalized_value,
+            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
+          },
+          normalize_data_hash(data),
+          normalize_data_hash(extra_data)
+        )
+      }.merge(html_options.compact)
+
+      content_tag(:span, **root_options) do
+        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'
+    end
+
+    private
+
+    def build_character_fragment(char)
+      if char.match?(/\d/)
+        build_digit_fragment(char.to_i)
+      else
+        content_tag(:span, char, class: 'nf__separator', 'aria-hidden': 'true')
+      end
+    end
+
+    def build_digit_fragment(digit)
+      cells = safe_join(
+        (0..9).map do |value|
+          content_tag(:span, value.to_s, class: 'nf__cell', 'aria-hidden': 'true')
+        end
+      )
+
+      content_tag(:span, class: 'nf__digit', data: { digit: digit }) do
+        content_tag(
+          :span,
+          cells,
+          class: 'nf__track',
+          data: { to_digit: digit },
+          style: "--nf-current-digit: #{digit}; --nf-from-digit: #{digit}; --nf-to-digit: #{digit};"
+        )
+      end
+    end
+
+    def format_integer(value, grouping:)
+      sign = value.negative? ? '-' : ''
+      digits = value.abs.to_s
+      grouped = grouping ? digits.reverse.scan(/.{1,3}/).join(',').reverse : digits
+      "#{sign}#{grouped}"
+    end
+
+    def merged_data_attributes(*hashes)
+      hashes.each_with_object({}) do |hash, merged|
+        hash.each { |key, value| merged[key.to_sym] = value unless value.nil? }
+      end
+    end
+
+    def normalize_data_hash(data)
+      return {} unless data.respond_to?(:each)
+
+      data.transform_keys do |key|
+        key.to_s.tr('-', '_').to_sym
+      end
+    end
+  end
+end

data/lib/number_flow/version.rb

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

data/lib/number_flow.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative 'number_flow/version'
+require_relative 'number_flow/helper'
+require_relative 'number_flow/engine'
+
+module NumberFlow
+  class Error < StandardError; end
+end

metadata

@@ -0,0 +1,87 @@
+--- !ruby/object:Gem::Specification
+name: number_flow
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- dpaluy
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: actionview
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 8.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 8.1.0
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 8.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !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.
+email:
+- dpaluy@users.noreply.github.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- app/assets/javascripts/number_flow/controller.js
+- app/assets/stylesheets/number_flow.css
+- lib/number_flow.rb
+- lib/number_flow/engine.rb
+- lib/number_flow/helper.rb
+- lib/number_flow/version.rb
+homepage: https://github.com/dpaluy/number_flow#readme
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+  homepage_uri: https://github.com/dpaluy/number_flow#readme
+  documentation_uri: https://rubydoc.info/gems/number_flow
+  source_code_uri: https://github.com/dpaluy/number_flow
+  changelog_uri: https://github.com/dpaluy/number_flow/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/dpaluy/number_flow/issues
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.4.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Rails helper + Stimulus digit flow transitions for integers.
+test_files: []