qr_forge 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 379423936d868bc8e4589d3483cc412c1bd6ec85bd6b9ae82e9ad58dfeb03903
-  data.tar.gz: 815cf224b5876c0222e8449b5edcbcc35d4f00c53d800f0a4cddb54d31f42735
+  metadata.gz: 39cc8a8482cee2898925eab861d71d2a96e778d61d34e3e3e6d2774f8ec3fa95
+  data.tar.gz: d217725f654c5b08ee9e7addb7d04f04a8b7e9495b2809210c5ead98e933deb2
 SHA512:
-  metadata.gz: 75c947677801f0d3d4469d3544206f9f3d0755ef90444b2eec312cf6373a0a2e10661d86a7f97d574ff69d05accb797299699d9bfd6f517b74130ecfe5393765
-  data.tar.gz: b31403d7730bb7f2bca48f237b8e99fd1a96414c470e24485164dd6046990e337a385bae68eb8832cff3cb2504b3fccdf0ffb5553b91a5d8bc70c7037e0bc10a
+  metadata.gz: cc85e4a4f63070f81e69d2a7c715b17a9fccb5dd19469a4a72dd37ebfb40245b073b79e2a35357b5b0edfb73ca812f32be6651cf7afb496fc0af419093b87c9e
+  data.tar.gz: 48a38d7344bdc09748a0bd546a3466f4e403a90611ef85d40c6f9418cbf569f18b7c797d4dae346e8b192d14ed6ae836020bceddc51a855e1dc700b2dfa70540

data/README.md

@@ -1,39 +1,195 @@
-# QrForge
+# !! Docs are still being written !! #
+![output](https://github.com/user-attachments/assets/71edb1aa-2182-4cd3-bb28-ec4f71336029)
 
-TODO: Delete this and the text below, and describe your gem
+An example of the output of QR Forge
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/qr_forge`. To experiment with that code, run `bin/console` for an interactive prompt.
+# QR Forge
 
-## Installation
+This library is a QR Code renderer that lets you customize almost every aspect of a QR Code. From module design to a logo, this library is meant to be design-extensible, which means you can render your own components such as modules, the outer eyes and inner eyes etc. in your own custom SVG shapes.
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+# Installation
 
-Install the gem and add to the application's Gemfile by executing:
+```shell 
+gem install qr_forge
+```
+
+or if using bundler
+
+```shell
+bundle add qr_forge
+```
+
+Note: To export in the PNG format you will also want to install vips on your machine
 
-```bash
-bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+```shell
+brew install vips
 ```
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+# Usage
 
-```bash
-gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+To create a QR Code you can simply do the following:
+
+```ruby
+QrForge::Forge.build(text: "https://yourlinkhere.com")
+```
+
+If you want an (SVG) QRCode fast, that's all there is to it. Everything else is covered by default values, however, you can tweak anything you want, which we will go through in the next section.
+
+## Configuration
+
+The library tries to provide sensible defaults, but defaults can be subjective, so the following shows a configuration object that you can pass to the QR Code.
+
+```ruby
+QrForge::Forge.build(
+  text: "https://www.google.com",
+  config: {
+    qr: { version: 10 },
+    components: { inner_eye: QrForge::Components::EyeInner::Square },
+    design: {
+      size: 800,
+      colors: { module: 'blue', outer_eye: 'cyan', inner_eye: 'skyblue' },
+      image: Base64.strict_encode64(...)
+    },
+    output: { format: :png }
+  }
+)
 ```
 
-## Usage
+##### QR
+
+This hash provides details to the underlying QR code generator (see: https://github.com/whomwah/rqrcode_core).
+
+_version_ dictates the module count or size of the QR Code and how much data it can hold. It does not necessarily dictate the dimensions, however, it will be unreadable if you choose too small of a size, but a larger QR code version. (see: https://www.qrcode.com/en/about/version.html)
 
-TODO: Write usage instructions here
+##### Components
 
-## Development
+This hash can have up to 3 components:
+- outer_eye
+<img width="77" alt="Screenshot 2025-06-17 at 1 23 39 AM" src="https://github.com/user-attachments/assets/ccef3f08-cc4b-43c7-95b4-8d6c707f5f5a" />
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+- inner_eye
+<img width="77" alt="Screenshot 2025-06-17 at 1 24 22 AM" src="https://github.com/user-attachments/assets/c21bb175-00c2-4179-a20a-4e505ad37df1" />
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+- module
+<img width="216" alt="Screenshot 2025-06-17 at 1 25 24 AM" src="https://github.com/user-attachments/assets/f670d5fd-e2dc-42cc-9bff-d77a51d65fa1" />
 
-## Contributing
+This is what the circle outer_eye component looks like:
+
+```ruby
+# frozen_string_literal: true
+
+module QrForge
+  module Components
+    module EyeOuter
+      class Circle < ForgeComponent
+        DEFAULT_STROKE_WIDTH = 1.0
+
+        # @see ForgeComponent#draw
+        # Draws a circle that fills the full 'area' box, inset by half the stroke so it
+        # never overlaps the modules beneath.
+        def draw(y:, x:, quiet_zone:, area:, color: "black", **_)
+          stroke_width = DEFAULT_STROKE_WIDTH
+
+          # Radius = (full width of box – one stroke) / 2
+          r = (area - stroke_width) / 2.0
+
+          # Center of the N×N box (plus quiet_zone offset)
+          cx = x + quiet_zone + (area / 2.0)
+          cy = y + quiet_zone + (area / 2.0)
+
+          @xml_builder.circle(
+            cx: cx,
+            cy: cy,
+            r: r,
+            'stroke-width': stroke_width,
+            stroke: color,
+            fill: "transparent",
+            test_id: @test_id
+          )
+        end
+      end
+    end
+  end
+end
+```
+
+And the square for comparison:
+
+```ruby
+# frozen_string_literal: true
+
+module QrForge
+  module Components
+    module EyeOuter
+      class Square < ForgeComponent
+        # @see ForgeComponent#draw
+        def draw(y:, x:, quiet_zone:, area:, color: "black", **_)
+          x += quiet_zone
+          y += quiet_zone
+
+          # Draw the outer black square (7x7)
+          @xml_builder.rect(
+            x:,
+            y:,
+            width: area,
+            height: area,
+            fill: color
+          )
+
+          # Draw the inner (cutout) square (5x5) to create the finder pattern
+          inset = 1
+          inner = area - 2
+
+          @xml_builder.rect(
+            x: x + inset,
+            y: y + inset,
+            width: inner,
+            height: inner,
+            fill: color,
+            test_id: @test_id
+          )
+        end
+      end
+    end
+  end
+end
+```
+
+All components must inherit from the base ForgeComponent. You can look at that to see what is available to be used (this is on the roadmap to allow more design variations).
+
+If you create your own designs, follow the same pattern and pass them into the components config. It will merge them with the default components, so if you only want to change one or two of the components, but not all three, you can!
+
+##### Design
+
+```
+size: 800
+```
+
+This sets the width and height of the svg. I recommend that you set this to a higher value than you plan to use as the SVG will scale well without needing to use any image processing like vips. If you do want to use your own strategies for image processing, I still recommend a higher size and do with the SVG as you wish.
+
+```
+colors: { module: 'blue', outer_eye: 'cyan', inner_eye: 'skyblue' }
+```
+
+This will set the fill or stroke appropriately for the respective component.
+
+``` 
+image: ...
+```
+
+A base64 encoded image that will be placed in the center of your QR Code. This scales with the version of the QR Code and is strictly set as to make sure that we do not remove more data that can be recovered through the error correcting algorithms.
+
+##### Output
+
+```
+output: { format: :png }})
+```
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/qr_forge.
+This will use vips to process the svg and return it as a PNG. If you want to do your own image processing, you can leave this off as the default is the raw SVG string.
 
-## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+## Roadmap
+- Color gradients for components
+- More data types i.e. wifi, passkey etc.
+- Image background and shape improvements
+- More default component selections

data/lib/qr_forge/forge.rb

@@ -4,21 +4,25 @@ module QrForge
   #
   # Entry point for building QRCodes
   class Forge
-    def initialize(text:, config:)
+    def initialize(data:, type:, config:)
       version = config.dig(:qr, :version)
 
-      @data = QrForge::QrData.new(text:, version:)
+      @data = QrForge::QrData.new(text: QrForge::Payload.build(data:, type:).to_s, version:)
       @renderer = QrForge::Renderer.new(qr_data: @data, config:)
       @exporter = QrForge::Exporter.new(config:)
     end
 
     #
     # Builds a QR code with the given parameters.
-    # @param text [String] The text/data to encode in the QR code
-    # @param size [Integer] The size of the QR code in modules [1-40]
+    # @param data [String, Hash] The data to encode in the QR code. This can be a string or a hash for specific payloads.
+    # @param type [Symbol] The type of QR code to build (e.g., :plain, :url)
+    # @param config [Hash] Configuration options for the QR code, including design and export settings.
+    #   - `:qr` - QR code specific settings (e.g., version).
+    #   - `:design` - Design specific settings (e.g., colors, shapes).
+    #   - `:output` - Export specific settings (e.g., format).
     # @return [String, StringIO] The SVG or PNG representation of the QR code
-    def self.build(text:, config: {})
-      new(text:, config:).build
+    def self.build(data:, type: :url, config: {})
+      new(data:, type:, config:).build
     end
 
     def build

data/lib/qr_forge/payload.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module QrForge
+  #
+  # Payload is a factory class that builds different types of payloads based on the provided type and data.
+  # It will validate the payload data (based on the type) and return a string representation of the payload.
+  class Payload
+    PAYLOAD_TYPES = {
+      wifi: ::QrForge::Payloads::Wifi,
+      plain: ::QrForge::Payloads::PlainText,
+      url: ::QrForge::Payloads::Url,
+      geo: ::QrForge::Payloads::Geo,
+      phone: ::QrForge::Payloads::Phone
+    }.freeze
+
+    #
+    # Builds a payload based on the type and data provided.
+    # @param type [Symbol] The type of payload to build (e.g., :url, :wifi).
+    # @param data [String, Hash] The data to encode in the payload.
+    # @return [String] The string representation of the payload.
+    def self.build(type:, data:)
+      klass = PAYLOAD_TYPES[type.to_sym]
+
+      raise ArgumentError "Invalid payload type: #{type}" unless klass
+
+      payload = case data
+                when Hash
+                  klass.new(**data)
+                when String
+                  klass.new(data)
+                else
+                  raise ArgumentError, "Invalid data type: #{data.class}. Expected Hash or String."
+                end
+
+      payload.validate!
+      payload
+    end
+  end
+end

data/lib/qr_forge/payloads/geo.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+puts "[Geo] file loaded"
+
+module QrForge
+  module Payloads
+    #
+    # Represents a geo lat/long payload
+    # @example return "geo:40.712776,-74.005974"
+    class Geo
+      def initialize(latitude:, longitude:)
+        @latitude = latitude
+        @longitude = longitude
+      end
+
+      def to_s
+        "geo:#{@latitude},#{@longitude}"
+      end
+
+      #
+      # Validates that the passed latitude and longitude are within valid ranges.
+      def validate!
+        return if (-90..90).cover?(@latitude.to_f) && (-180..180).cover?(@longitude.to_f)
+
+        raise PayloadValidationError, "Latitude or longitude out of range"
+      end
+    end
+  end
+end

data/lib/qr_forge/payloads/phone.rb

@@ -0,0 +1,35 @@
+require 'uri'
+
+module QrForge
+  module Payloads
+    #
+    # Represents a telephone payload
+    # @example return "https://example.com" or "http://example.com"
+    class Phone
+
+      def initialize(phone_number)
+        @phone_number = phone_number
+      end
+
+      def to_s
+        "tel:#{@phone_number}"
+      end
+
+      #
+      # Validates that the passed phone number is in a valid format.
+      # @example
+      #   valid phones:
+      #     +919367788755
+      #     8989829304
+      #     +16308520397
+      #     786-307-3615
+      #     555.555.5555
+      def validate!
+        # credit: https://ihateregex.io/expr/phone/
+        return if @phone_number =~ /^[+]?[(]?[0-9]{3}[)]?[-\s.]?[0-9]{3}[-\s.]?[0-9]{4,6}$/
+
+        raise PayloadValidationError, "Invalid phone number format"
+      end
+    end
+  end
+end

data/lib/qr_forge/payloads/plain_text.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module QrForge
+  module Payloads
+    #
+    # Represents a plain text payload
+    # @example return "Hello, World!"
+    class PlainText
+      def initialize(text)
+        @text = text
+      end
+
+      def to_s
+        @text
+      end
+
+      #
+      # Validates that the passed data is a string.
+      def validate!
+        raise PayloadValidationError, "Must be a valid string" unless @text.is_a?(String)
+        raise PayloadValidationError, "String cannot be empty" if @text.empty?
+      end
+    end
+  end
+end

data/lib/qr_forge/payloads/url.rb

@@ -0,0 +1,31 @@
+require 'uri'
+
+module QrForge
+  module Payloads
+    #
+    # Represents a URL payload
+    # @example return "https://example.com" or "http://example.com"
+    class Url
+
+      def initialize(url)
+        @url = url
+      end
+
+      def to_s
+        @url
+      end
+
+      #
+      # Validates that the passed url is a valid HTTP or HTTPS URL.
+      def validate!
+        uri = URI.parse(@url)
+
+        unless uri.is_a?(::URI::HTTP) || uri.is_a?(::URI::HTTPS)
+          raise PayloadValidationError, "Must be a valid HTTP/HTTPS URL"
+        end
+      rescue ::URI::InvalidURIError
+        raise PayloadValidationError, "Invalid URL syntax"
+      end
+    end
+  end
+end

data/lib/qr_forge/payloads/wifi.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module QrForge
+  module Payloads
+    # Represents a Wi-Fi network payload
+    # @example returns WIFI:T:<encryption>;S:<ssid>;P:<password>;H:<hidden>;;
+    class Wifi
+      VALID_ENCRYPTIONS = %w[WEP WPA WPA2 WPA3].freeze
+      NO_PASSWORD_ENCRYPTION = "NOPASS"
+
+      def initialize(encryption:, ssid:, password: nil, hidden: false)
+        @encryption = encryption.upcase
+        @ssid = ssid
+        @password = password
+        @hidden = hidden
+      end
+
+      #
+      # Encryption type for the Wi-Fi network.
+      # @return [String, nil] The encryption type or nil if no password is set.
+      def encryption_type
+        "T:#{@encryption}" unless @encryption == NO_PASSWORD_ENCRYPTION
+      end
+
+      #
+      # SSID of the Wi-Fi network.
+      # @return [String] The SSID
+      def ssid
+        "S:#{escape(@ssid)}"
+      end
+
+      #
+      # Password for the Wi-Fi network.
+      # @return [String, nil] The password or nil if no password is set.
+      def password
+        "P:#{escape(@password)}" if @password && @encryption != NO_PASSWORD_ENCRYPTION
+      end
+
+      #
+      # Indicates if the Wi-Fi network is hidden
+      # @return [String, nil] "H:true" if hidden, nil otherwise
+      def hidden
+        "H:true" unless @hidden.nil? || @hidden == false
+      end
+
+      #
+      # Returns the parts of the Wi-Fi payload as an array.
+      # @return [Array<String>] The parts of the Wi-Fi payload
+      def parts
+        parts = []
+        parts << ssid
+        parts << encryption_type
+        parts << password
+        parts << hidden
+
+        parts.compact
+      end
+
+      def to_s
+        "WIFI:#{parts.join(";")};;"
+      end
+
+      #
+      # Validates the Wi-Fi payload data.
+      # @raise [PayloadValidationError] if the SSID is blank or if the password is required but not provided.
+      # @raise [PayloadValidationError] if the encryption type is invalid.
+      def validate!
+        raise PayloadValidationError, "SSID is required" if blank?(@ssid)
+
+        if @encryption != NO_PASSWORD_ENCRYPTION && blank?(@password)
+          raise PayloadValidationError, "Password is required for #{@encryption} networks"
+        end
+
+        return if VALID_ENCRYPTIONS.include?(@encryption) || @encryption == NO_PASSWORD_ENCRYPTION
+
+        raise PayloadValidationError, "Invalid encryption: #{@encryption}"
+      end
+
+      private
+
+      #
+      # Escapes special characters in the Wi-Fi payload.
+      # @param str [String, NilClass] The string to escape
+      # @return [String] The escaped string
+      def escape(str)
+        return "" if blank?(str)
+
+        # https://github.com/zxing/zxing/wiki/Barcode-Contents#wi-fi-network-config-android-ios-11
+        # Escape characters: \ ; , : " as they are valid in SSID but are used as delimiters in the payload format
+        str.to_s.gsub(/([\\;,:"])/) { "\\#{::Regexp.last_match(1)}" }
+      end
+
+      #
+      # Checks if a value is blank.
+      # @param val [String, nil] The value to check
+      # @return [Boolean] true if the value is blank, false otherwise
+      def blank?(val)
+        val.nil? || val.strip == ""
+      end
+    end
+  end
+end

data/lib/qr_forge/payloads.rb

@@ -0,0 +1,5 @@
+module QrForge
+  module Payloads
+    class PayloadValidationError < StandardError; end
+  end
+end

data/lib/qr_forge/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module QrForge
-  VERSION = "1.0.0"
+  VERSION = "1.1.0"
 end

data/lib/qr_forge.rb

@@ -1,7 +1,16 @@
 # frozen_string_literal: true
 
 require "zeitwerk"
-loader = Zeitwerk::Loader.for_gem
-loader.setup
 
-module QrForge;end
+# Entry point for the QrForge gem.
+module QrForge
+  def self.loader
+    @loader ||= Zeitwerk::Loader.for_gem.tap do |loader|
+      loader.tag = "qr_forge"
+      loader.inflector = Zeitwerk::GemInflector.new(__FILE__)
+      loader.setup
+    end
+  end
+
+  loader
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: qr_forge
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Keegankb93
@@ -116,6 +116,13 @@ files:
 - lib/qr_forge/exporter.rb
 - lib/qr_forge/forge.rb
 - lib/qr_forge/layout.rb
+- lib/qr_forge/payload.rb
+- lib/qr_forge/payloads.rb
+- lib/qr_forge/payloads/geo.rb
+- lib/qr_forge/payloads/phone.rb
+- lib/qr_forge/payloads/plain_text.rb
+- lib/qr_forge/payloads/url.rb
+- lib/qr_forge/payloads/wifi.rb
 - lib/qr_forge/qr_data.rb
 - lib/qr_forge/renderer.rb
 - lib/qr_forge/version.rb