formblocks 0.1.0

data/lib/formblocks/configuration.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Formblocks
+  # Host-tunable settings. Everything has a safe default, so a fresh install
+  # works with zero configuration; the hooks below let an app decide who may
+  # build forms, which tenant they belong to, and what happens on submit.
+  class Configuration
+    # The gem's own admin layout. Compared against, so DashboardController can
+    # tell "the host left this alone" from "the host chose this".
+    DEFAULT_ADMIN_LAYOUT = 'formblocks/application'
+
+    # Your product's name, shown in page titles ("Contact form · Nusii") and
+    # as the alt text of a logo. nil resolves to the Rails application name.
+    attr_accessor :app_name
+
+    # Per-request gate for the builder, responses and settings. Defaults to
+    # development only — override it before deploying, e.g. with an admin check.
+    attr_accessor :authorize_admin
+
+    # Layout used by the admin pages. Override this to render the builder
+    # inside your app's admin shell, e.g. "admin/application".
+    attr_accessor :admin_layout
+
+    # The controller the ADMIN inherits from, as a String so it resolves
+    # lazily. Default: a plain 'ActionController::Base', where
+    # `authorize_admin` is the only gate. Name the controller your own admin
+    # already inherits from and the builder adopts that whole stack — layout,
+    # helpers, authentication, request context.
+    #
+    # Only the admin uses it. The public form pages stay on the engine's own
+    # controller, so an admin base controller here can never demand a staff
+    # session from a visitor filling in a form.
+    attr_accessor :base_controller_class
+
+    # Resolve the current tenant (optional, for multi-tenant apps). Return an
+    # opaque key — a GlobalID, an id, a subdomain, a slug — or nil. Receives
+    # the request. nil (the default) is a single, global collection. Forms,
+    # responses and the settings all scope to whatever this returns.
+    attr_accessor :tenant
+
+    # Called with each saved Formblocks::Response — notify Slack, send an
+    # email, create a lead. Runs inline after save; keep it fast or hand off
+    # to a job.
+    attr_accessor :on_submit
+
+    # Logo and image-block uploads. Requires Active Storage in the host; set
+    # false to hide every upload even when Active Storage is loaded.
+    attr_accessor :attachments
+    attr_accessor :max_upload_size
+
+    # The Active Storage service that stores uploads — form logos, the global
+    # logo, image blocks — as a service name from the host's
+    # config/storage.yml (e.g. a dedicated bucket or folder, or an entry with
+    # provider options like Cloudinary's folder/tags). nil, the default, uses
+    # the environment's default service. Read when the models load, so set it
+    # in an initializer.
+    attr_accessor :storage_service
+
+    # Per-IP throttle for the public submit endpoint, as keyword arguments for
+    # Rails' rate limiter. Read once when the controller loads — set it in an
+    # initializer. nil disables throttling.
+    attr_accessor :rate_limit
+
+    # Brand defaults when neither the form nor the settings page set a color.
+    attr_accessor :default_primary_color, :default_button_text_color
+
+    # Where the admin engine is mounted, and where public forms live. Both are
+    # written by `mount_formblocks`; set them here only if you mount manually.
+    attr_accessor :mount_path, :public_path
+
+    # Form templates offered on the "New form" page, keyed by an identifier.
+    # See Formblocks::Templates for the built-in ones and the definition shape.
+    attr_reader :templates
+
+    def initialize
+      @app_name = nil
+      @authorize_admin = ->(_request) { Rails.env.development? }
+      @admin_layout = DEFAULT_ADMIN_LAYOUT
+      @base_controller_class = 'ActionController::Base'
+      @tenant = ->(_request) {}
+      @on_submit = ->(_response) {}
+      @attachments = true
+      @max_upload_size = 5 * 1024 * 1024
+      @storage_service = nil
+      @rate_limit = { to: 10, within: 60 }
+      @default_primary_color = '#111827'
+      @default_button_text_color = '#ffffff'
+      @mount_path = '/forms'
+      @public_path = '/f'
+      @templates = Templates.builtin
+    end
+  end
+end

data/lib/formblocks/engine.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Formblocks
+  class Engine < ::Rails::Engine
+    isolate_namespace Formblocks
+
+    rake_tasks do
+      load File.expand_path('../tasks/formblocks_tasks.rake', __dir__)
+    end
+
+    # The public form pages are drawn on the HOST's route set, not the
+    # engine's, so they can live at a path of the host's choosing that is
+    # separate from the admin mount. `mount_formblocks` does both in one line.
+    #
+    # The mount is named `formblocks` on purpose: the engine's views reach
+    # their own assets through that proxy even when a request came in through
+    # a host route (the public pages) or a host layout.
+    initializer 'formblocks.routing' do
+      ActionDispatch::Routing::Mapper.include(Module.new do
+        def mount_formblocks(at: Formblocks.config.mount_path, public_at: Formblocks.config.public_path, **options)
+          Formblocks.config.mount_path = at
+          Formblocks.config.public_path = public_at
+          mount Formblocks::Engine, at:, as: :formblocks, **options
+
+          public_at = public_at.to_s.chomp('/')
+          get "#{public_at}/:slug", to: 'formblocks/public/forms#show', as: :formblocks_form
+          post "#{public_at}/:slug", to: 'formblocks/public/forms#create'
+          get "#{public_at}/:slug/thanks", to: 'formblocks/public/forms#thanks', as: :formblocks_form_thanks
+        end
+      end)
+    end
+  end
+end

data/lib/formblocks/seeds.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Formblocks
+  # Demo data for trying the gem out: three forms built from the built-in
+  # templates — two published, with a few responses each, and one draft.
+  # Idempotent: running it again refreshes the same forms (found by slug)
+  # instead of duplicating them.
+  module Seeds
+    SLUGS = { 'contact' => 'demo-contact', 'lead' => 'demo-lead-capture', 'feedback' => 'demo-feedback' }.freeze
+
+    RESPONSES = {
+      'demo-contact' => [
+        { 'your_name' => 'Ada Lovelace', 'email_address' => 'ada@example.com',
+          'message' => 'Could you send over the enterprise pricing?' },
+        { 'your_name' => 'Grace Hopper', 'email_address' => 'grace@example.com',
+          'message' => "Loved the demo.\nWhen does the API ship?" }
+      ],
+      'demo-lead-capture' => [
+        { 'full_name' => 'Linus Torvalds', 'work_email' => 'linus@example.com', 'team_size' => 'Just me',
+          'send_me_product_updates_by_email' => '1' },
+        { 'full_name' => 'Margaret Hamilton', 'work_email' => 'margaret@example.com',
+          'phone_number' => '+1 617 555 0100', 'company_website' => 'https://apollo.example', 'team_size' => '51+',
+          'what_are_you_hoping_to_solve' => 'Onboarding for a distributed team.' },
+        { 'full_name' => 'Ken Thompson', 'work_email' => 'ken@example.com', 'team_size' => '2–10' }
+      ]
+    }.freeze
+
+    def self.load!(tenant: nil)
+      forms = SLUGS.to_h do |template, slug|
+        definition = Templates.builtin.fetch(template)
+        form = Form.find_by(slug:) || Form.from_template(definition, tenant:).tap { |f| f.slug = slug }
+        form.tenant = tenant
+        form.save!
+        template == 'feedback' ? form.unpublish! : form.publish!
+        [slug, form]
+      end
+
+      responses = RESPONSES.flat_map do |slug, answers_list|
+        form = forms.fetch(slug)
+        form.responses.destroy_all
+        answers_list.map do |answers|
+          form.responses.new(page_url: 'https://example.com/pricing', locale: 'en',
+                             user_agent: 'Mozilla/5.0 (demo)').fill(answers).tap(&:save!)
+        end
+      end
+
+      { forms: forms.values, responses: }
+    end
+  end
+end

data/lib/formblocks/templates.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Formblocks
+  # Form templates offered on the "New form" page. A template is a plain hash:
+  #
+  #   {
+  #     title: 'Contact form',
+  #     description: 'Name, email and a message.',
+  #     pages: [
+  #       { button_text: 'Send',
+  #         blocks: [
+  #           { type: 'heading', content: 'Get in touch' },
+  #           { type: 'email', label: 'Email', required: true }
+  #         ] }
+  #     ],
+  #     thank_you: { blocks: [{ type: 'heading', content: 'Thanks!' }] }
+  #   }
+  #
+  # `type` is a block kind (see Formblocks::Block.kinds); the other keys are
+  # block attributes. Hosts add their own with
+  # `Formblocks.config.templates['webinar'] = { ... }` and remove a built-in
+  # with `Formblocks.config.templates.delete('contact')`.
+  module Templates
+    def self.builtin
+      {
+        'contact' => {
+          title: 'Contact form',
+          description: 'Name, email and a message. The classic.',
+          pages: [
+            { button_text: 'Send message',
+              blocks: [
+                { type: 'heading', content: 'Get in touch' },
+                { type: 'paragraph', content: 'Leave us a message and we will get back to you within a day.' },
+                { type: 'name', label: 'Your name', required: true },
+                { type: 'email', label: 'Email address', required: true },
+                { type: 'textarea', label: 'Message', required: true, placeholder: 'How can we help?' }
+              ] }
+          ],
+          thank_you: {
+            blocks: [
+              { type: 'heading', content: 'Thanks for reaching out!' },
+              { type: 'paragraph', content: 'We have received your message and will reply soon.' }
+            ]
+          }
+        },
+        'lead' => {
+          title: 'Lead capture',
+          description: 'Two steps: contact details first, then a few qualifying questions.',
+          pages: [
+            { button_text: 'Continue',
+              blocks: [
+                { type: 'heading', content: 'Request a demo' },
+                { type: 'name', label: 'Full name', required: true },
+                { type: 'email', label: 'Work email', required: true },
+                { type: 'phone', label: 'Phone number' },
+                { type: 'url', label: 'Company website' }
+              ] },
+            { button_text: 'Request demo',
+              blocks: [
+                { type: 'heading', content: 'A bit about your team' },
+                { type: 'radio_group', label: 'Team size', required: true,
+                  options: ['Just me', '2–10', '11–50', '51+'] },
+                { type: 'textarea', label: 'What are you hoping to solve?' },
+                { type: 'checkbox', label: 'Send me product updates by email' }
+              ] }
+          ],
+          thank_you: {
+            blocks: [
+              { type: 'heading', content: 'Thank you!' },
+              { type: 'paragraph', content: 'We will be in touch shortly to schedule your demo.' }
+            ]
+          }
+        },
+        'feedback' => {
+          title: 'Feedback survey',
+          description: 'A quick rating and an open comment.',
+          pages: [
+            { button_text: 'Send feedback',
+              blocks: [
+                { type: 'heading', content: 'How are we doing?' },
+                { type: 'radio_group', label: 'How satisfied are you?', required: true,
+                  options: ['Very satisfied', 'Satisfied', 'Neutral', 'Unsatisfied', 'Very unsatisfied'] },
+                { type: 'textarea', label: 'What could we do better?' },
+                { type: 'email', label: 'Email, if you would like a reply' }
+              ] }
+          ],
+          thank_you: {
+            blocks: [
+              { type: 'heading', content: 'Thanks for your feedback!' },
+              { type: 'paragraph', content: 'Every answer helps us improve.' }
+            ]
+          }
+        }
+      }
+    end
+  end
+end

data/lib/formblocks/version.rb

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

data/lib/formblocks.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require 'turbo-rails'
+require 'stimulus-rails'
+
+require 'formblocks/version'
+require 'formblocks/configuration'
+require 'formblocks/assets'
+require 'formblocks/templates'
+require 'formblocks/seeds'
+require 'formblocks/engine'
+
+# Formblocks: a block-based form builder for Rails. Forms are built from
+# blocks (content and inputs) spread over pages, published at a public URL,
+# and their responses land in your own database with a dashboard and CSV export.
+module Formblocks
+  class << self
+    def config
+      @config ||= Configuration.new
+    end
+
+    def configure
+      yield config
+    end
+
+    # The class the admin controllers inherit from. Resolved on every call
+    # rather than memoized, so a host that reassigns base_controller_class in
+    # a reloadable initializer is not pinned to a stale, unloaded constant.
+    def base_controller
+      config.base_controller_class.to_s.constantize
+    end
+
+    # Can this request use the builder and read responses? Checked by every
+    # admin action, and by the public page to allow previews of drafts.
+    def admin?(request)
+      !!config.authorize_admin.call(request)
+    end
+
+    # The tenant key for this request, or nil for the single global collection.
+    # Normalized to a string so `where(tenant:)` is consistent whether the
+    # resolver returns a GlobalID, an integer id, or a slug.
+    def tenant(request)
+      config.tenant.call(request).presence&.to_s
+    end
+
+    # Forms belonging to a host record, keyed by its GlobalID.
+    def for(record)
+      Form.for_tenant(tenant_key_for(record))
+    end
+
+    # The product name for titles and alt text: config.app_name, else the
+    # Rails application's module name, verbatim ("Nusii", "SupeRails").
+    def app_name
+      config.app_name.presence || rails_app_name
+    end
+
+    # Logo and image uploads need Active Storage loaded in the host.
+    def attachments?
+      config.attachments && defined?(::ActiveStorage) ? true : false
+    end
+
+    private
+
+    def rails_app_name
+      Rails.application.class.module_parent_name
+    rescue StandardError
+      'this app'
+    end
+
+    def tenant_key_for(record)
+      record.respond_to?(:to_gid) ? record.to_gid.to_s : record.to_s
+    end
+  end
+end

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+require 'rails/generators/active_record'
+require_relative '../migration_helpers'
+
+module Formblocks
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+      include MigrationHelpers
+
+      source_root File.expand_path('templates', __dir__)
+
+      desc 'Installs formblocks: config initializer, migration, and routes.'
+
+      class_option :mount_path, type: :string, default: '/forms',
+                                desc: 'Where the admin (builder, responses, settings) is mounted'
+      class_option :public_path, type: :string, default: '/f',
+                                 desc: 'Where published forms are served'
+
+      def create_initializer
+        template 'initializer.rb.tt', 'config/initializers/formblocks.rb'
+      end
+
+      def create_migration_file
+        migration_template 'create_formblocks_tables.rb.tt',
+                           'db/migrate/create_formblocks_tables.rb'
+      end
+
+      def mount_engine
+        route %(mount_formblocks at: "#{options[:mount_path]}", public_at: "#{options[:public_path]}")
+      end
+
+      def post_install
+        say "\nformblocks installed. Run `bin/rails db:migrate`.", :green
+        say "Build forms at #{options[:mount_path]} (development only until you set config.authorize_admin)."
+        say "Published forms are served at #{options[:public_path]}/<slug>."
+        say "Logo and image uploads need Active Storage: `bin/rails active_storage:install` if you have not.\n"
+      end
+    end
+  end
+end

data/lib/generators/formblocks/install/templates/create_formblocks_tables.rb.tt

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+class CreateFormblocksTables < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :formblocks_settings<%= primary_key_type_option %> do |t|
+      t.string :tenant # opaque per-tenant key; nil = single global collection
+      t.string :primary_color
+      t.string :button_text_color
+
+      t.timestamps
+    end
+    add_index :formblocks_settings, :tenant, unique: true
+
+    create_table :formblocks_forms<%= primary_key_type_option %> do |t|
+      t.string :title, null: false
+      t.string :slug, null: false
+      t.datetime :published_at
+      t.string :primary_color
+      t.string :button_text_color
+      t.string :tenant
+      t.integer :responses_count, null: false, default: 0
+
+      t.timestamps
+    end
+    add_index :formblocks_forms, :slug, unique: true
+    add_index :formblocks_forms, :tenant
+
+    create_table :formblocks_pages<%= primary_key_type_option %> do |t|
+      t.references :form, null: false<%= foreign_key_type_option %>, foreign_key: { to_table: :formblocks_forms }
+      t.string :kind, null: false, default: 'step'
+      t.integer :position, null: false, default: 0
+      t.string :button_text
+
+      t.timestamps
+    end
+
+    create_table :formblocks_blocks<%= primary_key_type_option %> do |t|
+      t.references :page, null: false<%= foreign_key_type_option %>, foreign_key: { to_table: :formblocks_pages }
+      t.string :type, null: false
+      t.integer :position, null: false, default: 0
+      t.string :key
+      t.string :label
+      t.string :placeholder
+      t.text :help_text
+      t.text :content
+      t.boolean :required, null: false, default: false
+      t.json :options
+      t.json :settings
+
+      t.timestamps
+    end
+
+    create_table :formblocks_responses<%= primary_key_type_option %> do |t|
+      t.references :form, null: false<%= foreign_key_type_option %>, foreign_key: { to_table: :formblocks_forms }
+      t.string :tenant
+      t.json :answers
+      t.string :page_url
+      t.string :user_agent
+      t.string :locale
+
+      t.timestamps
+    end
+    add_index :formblocks_responses, %i[tenant created_at]
+  end
+end

data/lib/generators/formblocks/install/templates/initializer.rb.tt

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+Formblocks.configure do |config|
+  # Your product's name, shown in page titles ("Contact form · Nusii") and
+  # as the alt text of your logo. Defaults to your Rails application name.
+  # config.app_name = "My App"
+
+  # Who can build forms, read responses and change settings at the mount
+  # path. Receives the raw request. Defaults to development only — the admin
+  # answers 403 everywhere else until you override this.
+  #
+  # Devise / Warden:
+  # config.authorize_admin = ->(request) { request.env["warden"]&.user&.admin? }
+  #
+  # Rails 8 built-in auth (bin/rails generate authentication):
+  # config.authorize_admin = lambda do |request|
+  #   token = request.cookies["session_id"]
+  #   Session.find_signed(token)&.user&.admin? if token
+  # end
+  #
+  # Two ways to put the builder inside an admin you already have.
+  #
+  # The layout only — the gem's controllers, your shell:
+  # config.admin_layout = "admin/application"
+  #
+  # Or the whole stack. Name the controller your own admin inherits from and
+  # the builder picks up its layout, helpers, authentication and any request
+  # context its before_actions set up. Only the admin inherits it; the public
+  # form pages stay on the engine's own controller.
+  # config.base_controller_class = "Admin::BaseController"
+
+  # Multi-tenancy (optional). Scope forms, responses and settings to a
+  # tenant — each Account/Organization its own set of forms. Return an
+  # opaque key (nil = one global collection, the default). A GlobalID is the
+  # recommended key; an id, subdomain or slug work too.
+  # config.tenant = ->(request) { Current.account&.to_gid&.to_s }
+
+  # Called with each saved Formblocks::Response — notify Slack, send an
+  # email, create a lead. `response.answers` is a hash keyed by block key
+  # ("email", "name", ...); `response.form` is the form it came from.
+  # config.on_submit = ->(response) {}
+
+  # Logo and image uploads (requires Active Storage).
+  # config.attachments = true
+  # config.max_upload_size = 5.megabytes
+
+  # Store uploads (logos, image blocks) on a specific Active Storage service
+  # from config/storage.yml — e.g. a dedicated bucket or folder, or a service
+  # entry carrying provider options like Cloudinary's `folder:` / `tags:` —
+  # to keep form media apart from the rest of your library. Default: your
+  # environment's default service.
+  # config.storage_service = :formblocks
+
+  # Brand defaults, used when neither the form nor the settings page set one.
+  # config.default_primary_color = "#111827"
+  # config.default_button_text_color = "#ffffff"
+
+  # Form templates on the "New form" page. Add your own or drop a built-in.
+  # config.templates["webinar"] = { title: "Webinar signup", pages: [...] }
+  # config.templates.delete("feedback")
+
+  # Per-IP throttle for the public submit endpoint. nil disables it.
+  # config.rate_limit = { to: 10, within: 1.minute }
+
+  # Paths, written by `mount_formblocks` in routes.rb. Set these only if you
+  # mount the engine manually.
+  # config.mount_path = "<%= options[:mount_path] %>"
+  # config.public_path = "<%= options[:public_path] %>"
+end

data/lib/generators/formblocks/migration_helpers.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Formblocks
+  module Generators
+    # Shared bits every migration-writing generator needs.
+    module MigrationHelpers
+      private
+
+      def migration_version
+        "[#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}]"
+      end
+
+      # Follow the host's own key type instead of forcing bigint. An app that
+      # keys its models with uuids sets this, and its
+      # `active_storage_attachments.record_id` is then a uuid column — bigint
+      # tables here could never take a logo or image attachment.
+      #
+      # Same lookup Rails' own Active Storage, Action Text and Action Mailbox
+      # migrations do, so a host that set it once gets consistent tables from
+      # all of them. Rendered as a `create_table` option rather than a bare
+      # value, because a template is expanded at generate time.
+      def primary_key_type_option
+        type = primary_key_type
+        type ? ", id: :#{type}" : ''
+      end
+
+      # The matching option for `t.references`, so foreign keys point at the
+      # right column type.
+      def foreign_key_type_option
+        type = primary_key_type
+        type ? ", type: :#{type}" : ''
+      end
+
+      def primary_key_type
+        config = Rails.configuration.generators
+        config.options[config.orm][:primary_key_type]
+      end
+    end
+  end
+end

data/lib/tasks/formblocks_tasks.rake

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+namespace :formblocks do
+  desc 'Create or refresh formblocks demo data: three template forms and a few responses'
+  task seed_demo: :environment do
+    result = Formblocks::Seeds.load!
+    puts "Seeded #{result[:forms].size} forms and #{result[:responses].size} responses."
+    result[:forms].each { |form| puts "  #{form.status.ljust(9)} #{form.title} (#{form.slug})" }
+  end
+end