keystone_ui-blocks 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2a9effabb0c7a22247df585e2f60cf4ec1dfbd2256feeca4cfdeafc108bf170c
+  data.tar.gz: 01d24bf7544dbb1ab376e72edacf336f002b0ee815f13981fbe8cfacd1b196e5
+SHA512:
+  metadata.gz: 8ed0465e1674ddd075da1d207408dbeaa5e8d59c0e071a565efff1f0ddf2e02fc17a089132ed4e2cfdcda225b32a26758e5ffa9057c9e5743e03f38386d4ebd0
+  data.tar.gz: 62885b92e2be83b5a448b1f8c8d816d44ffa7637799270cefc0bc0b6a57b1df432330155be7ec530b6cfcc103f343f86bdc9b1e9f506bcd83e8e4ace0f10da77

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tyler Schneider
+
+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/app/assets/stylesheets/ks_blocks.css

@@ -0,0 +1,15 @@
+.ks-blocks-layout {
+  display: grid;
+  grid-template-columns: repeat(var(--ks-blocks-columns, 12), minmax(0, 1fr));
+  gap: var(--ks-blocks-gap, 10px);
+}
+
+@media (max-width: 640px) {
+  .ks-blocks-layout {
+    display: block;
+  }
+
+  .ks-blocks-layout > * + * {
+    margin-top: var(--ks-blocks-gap, 10px);
+  }
+}

data/lib/keystone_ui/blocks/engine.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "rails"
+
+module KeystoneUi
+  module Blocks
+    class Engine < ::Rails::Engine
+      engine_name "keystone_ui_blocks_engine"
+    end
+  end
+end

data/lib/keystone_ui/blocks/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module KeystoneUi
+  module Blocks
+    VERSION = "0.1.0"
+  end
+end

data/lib/keystone_ui/blocks.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require "keystone_ui/blocks/version"
+require "keystone_ui/blocks/engine"
+require "ks_blocks"

data/lib/keystone_ui-blocks.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "keystone_ui/blocks"

data/lib/ks_blocks/block_type.rb

@@ -0,0 +1,7 @@
+module KsBlocks
+  BlockType = Data.define(:key, :name, :width, :height, :min_width, :max_width, :min_height, :max_height, :resizable, :once, :full_width, :fixed, :description, :group, :fields) do
+    def initialize(key:, name:, width:, height:, min_width: 1, max_width: nil, min_height: 1, max_height: nil, resizable: true, once: false, full_width: false, fixed: false, description: nil, group: nil, fields: [])
+      super
+    end
+  end
+end

data/lib/ks_blocks/content_helper.rb

@@ -0,0 +1,9 @@
+module KsBlocks
+  module ContentHelper
+    def block_contents(blocks, &block)
+      tag.div(hidden: true, data: { block_contents: true }) do
+        safe_join(blocks.map { |placed| tag.div(capture(placed, &block), data: { block_content: placed["id"] }) })
+      end
+    end
+  end
+end

data/lib/ks_blocks/grid.rb

@@ -0,0 +1,114 @@
+require "securerandom"
+require "ks_blocks/block_type"
+require "ks_blocks"
+
+module KsBlocks
+  class InvalidLayout < StandardError; end
+
+  module Grid
+    COLUMNS = 12
+    ROW_HEIGHT = 60
+    GAP = 10
+
+    module_function
+
+    def add(blocks, block_type, x: nil, y: nil, columns: COLUMNS)
+      refuse_second_use(blocks, block_type)
+      x, y = first_open_place(blocks, block_type, columns) if x.nil? || y.nil?
+      added = { "id" => SecureRandom.uuid, "type" => block_type.key.to_s, "x" => x, "y" => y, "w" => block_type.width, "h" => block_type.height }
+      (blocks + [ added ]).tap { |arranged| refuse_unfit(arranged, [ added["id"] ], columns, []) }
+    end
+
+    def place(blocks, positions, columns: COLUMNS, types: [])
+      placed = positions.index_by { |position| position["id"] }
+      blocks.map { |block| block.merge(placed.fetch(block["id"], {}).slice("x", "y", "w", "h")) }.tap { |arranged| refuse_unfit(arranged, placed.keys, columns, types, blocks.index_by { |block| block["id"] }) }
+    end
+
+    def refuse_unfit(blocks, moved_ids, columns, types = [], blocks_before = {})
+      blocks.select { |block| moved_ids.include?(block["id"]) }.each do |moved|
+        block_type = types.find { |registered| registered.key.to_s == moved["type"] }
+        refuse_resizing(moved, block_type, blocks_before[moved["id"]])
+        refuse_outside_limits(moved, block_type)
+        refuse_narrower_than_the_grid(moved, block_type, columns)
+        refuse_moving(moved, block_type, blocks_before[moved["id"]])
+        raise InvalidLayout, "#{named(moved)} must be at least one column wide and one row tall" if moved["w"] < 1 || moved["h"] < 1
+        raise InvalidLayout, "#{named(moved)} runs past the grid's last column" if moved["x"] + moved["w"] > columns
+      end
+      refuse_overlaps(blocks, moved_ids)
+    end
+
+    def refuse_overlaps(blocks, moved_ids)
+      blocks.select { |block| moved_ids.include?(block["id"]) }.each do |moved|
+        covered = blocks.find { |other| other["id"] != moved["id"] && overlaps?(other, moved["x"], moved["y"], moved["w"], moved["h"]) }
+        raise InvalidLayout, "#{named(moved)} overlaps #{named(covered)}" if covered
+      end
+    end
+
+    def refuse_moving(block, block_type, before)
+      return if block_type.nil? || !block_type.fixed || before.nil?
+      return if block["x"] == before["x"] && block["y"] == before["y"]
+
+      raise InvalidLayout, "#{named(block)} cannot be moved"
+    end
+
+    def refuse_narrower_than_the_grid(block, block_type, columns)
+      return if block_type.nil? || !block_type.full_width || block["w"] == columns
+
+      raise InvalidLayout, "#{named(block)} must span the full width"
+    end
+
+    def refuse_second_use(blocks, block_type)
+      return unless block_type.once && blocks.any? { |block| block["type"] == block_type.key.to_s }
+
+      raise InvalidLayout, "#{block_type.name} can only be used once"
+    end
+
+    def refuse_resizing(block, block_type, before)
+      return if block_type.nil? || block_type.resizable || before.nil?
+      return if block["w"] == before["w"] && block["h"] == before["h"]
+
+      raise InvalidLayout, "#{named(block)} cannot be resized"
+    end
+
+    def refuse_outside_limits(block, block_type)
+      return unless block_type
+
+      raise InvalidLayout, "#{named(block)} cannot be narrower than #{block_type.min_width} columns" if block["w"] < block_type.min_width
+      raise InvalidLayout, "#{named(block)} cannot be shorter than #{block_type.min_height} rows" if block["h"] < block_type.min_height
+      raise InvalidLayout, "#{named(block)} cannot be wider than #{block_type.max_width} columns" if block_type.max_width && block["w"] > block_type.max_width
+      raise InvalidLayout, "#{named(block)} cannot be taller than #{block_type.max_height} rows" if block_type.max_height && block["h"] > block_type.max_height
+    end
+
+    def named(block)
+      KsBlocks.registry.block_types.find { |block_type| block_type.key.to_s == block["type"] }&.name || block["type"]
+    end
+
+    def fill(blocks, id, content)
+      blocks.map { |block| block["id"] == id ? block.merge("content" => content) : block }
+    end
+
+    def remove(blocks, id, types: [])
+      refuse_removing(blocks.find { |block| block["id"] == id }, types)
+      blocks.reject { |block| block["id"] == id }
+    end
+
+    def refuse_removing(block, types)
+      return if block.nil?
+      return unless types.find { |registered| registered.key.to_s == block["type"] }&.fixed
+
+      raise InvalidLayout, "#{named(block)} cannot be removed"
+    end
+
+    def first_open_place(blocks, block_type, columns)
+      (0..).each do |y|
+        (0..columns - block_type.width).each do |x|
+          return [ x, y ] unless blocks.any? { |block| overlaps?(block, x, y, block_type.width, block_type.height) }
+        end
+      end
+    end
+
+    def overlaps?(block, x, y, width, height)
+      x < block["x"] + block["w"] && block["x"] < x + width && y < block["y"] + block["h"] && block["y"] < y + height
+    end
+  end
+end

data/lib/ks_blocks/layout.rb

@@ -0,0 +1,37 @@
+require "active_support/concern"
+require "ks_blocks"
+require "ks_blocks/grid"
+
+module KsBlocks
+  module Layout
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def block_layout(column, kind: :blocks, columns: Grid::COLUMNS, row_height: Grid::ROW_HEIGHT, gap: Grid::GAP)
+        define_method(:add_block) do |block_type, x: nil, y: nil|
+          update!(column => Grid.add(public_send(column), block_type, x: x, y: y, columns: columns))
+        end
+
+        define_method(:place_blocks) do |positions, version: nil|
+          raise InvalidLayout, "This layout changed since it was last drawn" if version && version != KsBlocks.version_of(public_send(column))
+
+          update!(column => Grid.place(public_send(column), positions, columns: columns, types: KsBlocks.registry.block_types(kind: kind)))
+        end
+
+        define_method(:fill_block) do |id, content|
+          update!(column => Grid.fill(public_send(column), id, content))
+        end
+
+        define_method(:remove_block) do |id|
+          update!(column => Grid.remove(public_send(column), id, types: KsBlocks.registry.block_types(kind: kind)))
+        end
+
+        define_method(:block_layout_kind) { kind }
+
+        define_method(:layout_data) do
+          KsBlocks.layout_data(public_send(column), kind: kind, grid: { columns: columns, row_height: row_height, gap: gap })
+        end
+      end
+    end
+  end
+end

data/lib/ks_blocks/layout_endpoints.rb

@@ -0,0 +1,51 @@
+require "active_support/concern"
+require "ks_blocks"
+require "ks_blocks/grid"
+
+module KsBlocks
+  module LayoutEndpoints
+    extend ActiveSupport::Concern
+
+    included do
+      rescue_from KsBlocks::InvalidLayout do |refusal|
+        render json: { error: refusal.message }, status: :unprocessable_entity
+      end
+    end
+
+    def layout
+      data = block_layout_record.layout_data
+      render json: data.merge(contents: block_contents(data[:blocks]))
+    end
+
+    def add_block
+      block_type = KsBlocks.registry.block_types(kind: block_layout_record.block_layout_kind).find { |registered| registered.key.to_s == params[:type] }
+      raise InvalidLayout, "No block type is registered as #{params[:type]}" unless block_type
+
+      block_layout_record.add_block(block_type, x: params[:x], y: params[:y])
+      head :no_content
+    end
+
+    def fill_block
+      block_layout_record.fill_block(params[:block_id], params.require(:content).permit!.to_h)
+      head :no_content
+    end
+
+    def remove_block
+      block_layout_record.remove_block(params[:block_id])
+      head :no_content
+    end
+
+    def block_contents(blocks)
+      blocks.to_h { |block| [ block["id"], block_content(block) ] }.compact
+    end
+
+    def block_content(_block)
+      nil
+    end
+
+    def place_blocks
+      block_layout_record.place_blocks(params.require(:layout).map { |position| position.permit(:id, :x, :y, :w, :h).to_h }, version: params[:version])
+      head :no_content
+    end
+  end
+end

data/lib/ks_blocks/layout_helper.rb

@@ -0,0 +1,23 @@
+require "ks_blocks"
+require "ks_blocks/grid"
+
+module KsBlocks
+  module LayoutHelper
+    def block_layout(blocks, columns: Grid::COLUMNS, gap: Grid::GAP, kind: nil, &block)
+      tag.div(class: "ks-blocks-layout", style: "--ks-blocks-columns: #{columns}; --ks-blocks-gap: #{gap}px") do
+        safe_join(block_layout_shown(blocks, kind).map { |placed| block_layout_block(placed, &block) })
+      end
+    end
+
+    private
+
+    def block_layout_shown(blocks, kind)
+      shown = kind.nil? ? blocks : blocks.select { |placed| KsBlocks.registry.block_types(kind: kind).any? { |block_type| block_type.key.to_s == placed["type"] } }
+      shown.sort_by { |placed| [ placed["y"], placed["x"] ] }
+    end
+
+    def block_layout_block(placed, &block)
+      tag.div(capture(placed, &block), data: { block: placed["id"] }, style: "grid-column: #{placed['x'] + 1} / span #{placed['w']}; grid-row: #{placed['y'] + 1} / span #{placed['h']}")
+    end
+  end
+end

data/lib/ks_blocks/registry.rb

@@ -0,0 +1,17 @@
+require "ks_blocks/block_type"
+
+module KsBlocks
+  class Registry
+    def initialize
+      @block_types = {}
+    end
+
+    def register(block_type, kind: :blocks)
+      @block_types[[ kind.to_sym, block_type.key.to_sym ]] = block_type
+    end
+
+    def block_types(kind: :blocks)
+      @block_types.filter_map { |(registered_kind, _key), block_type| block_type if registered_kind == kind.to_sym }
+    end
+  end
+end

data/lib/ks_blocks.rb

@@ -0,0 +1,23 @@
+require "digest"
+require "json"
+require "ks_blocks/registry"
+
+module KsBlocks
+  class << self
+    def block(key, name:, width:, height:, kind: :blocks, **limits)
+      registry.register(BlockType.new(key: key, name: name, width: width, height: height, **limits), kind: kind)
+    end
+
+    def layout_data(blocks, kind: :blocks, grid: {})
+      { block_types: registry.block_types(kind: kind).map(&:to_h), blocks: blocks, version: version_of(blocks), grid: grid }
+    end
+
+    def version_of(blocks)
+      Digest::SHA256.hexdigest(JSON.generate(blocks))
+    end
+
+    def registry
+      @registry ||= Registry.new
+    end
+  end
+end

metadata

@@ -0,0 +1,119 @@
+--- !ruby/object:Gem::Specification
+name: keystone_ui-blocks
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Tyler Schneider
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-09-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: actionview
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: keystone_ui-react
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.2
+description: Block types a host registers, a layout its own record keeps, and a grid
+  a designer arranges blocks on, following keystone_ui's design.
+email:
+- tylercschneider@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- app/assets/stylesheets/ks_blocks.css
+- lib/keystone_ui-blocks.rb
+- lib/keystone_ui/blocks.rb
+- lib/keystone_ui/blocks/engine.rb
+- lib/keystone_ui/blocks/version.rb
+- lib/ks_blocks.rb
+- lib/ks_blocks/block_type.rb
+- lib/ks_blocks/content_helper.rb
+- lib/ks_blocks/grid.rb
+- lib/ks_blocks/layout.rb
+- lib/ks_blocks/layout_endpoints.rb
+- lib/ks_blocks/layout_helper.rb
+- lib/ks_blocks/registry.rb
+homepage: https://github.com/DYB-Development/keystone_ui-blocks
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/DYB-Development/keystone_ui-blocks
+  changelog_uri: https://github.com/DYB-Development/keystone_ui-blocks/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/DYB-Development/keystone_ui-blocks/issues
+  documentation_uri: https://github.com/DYB-Development/keystone_ui-blocks#readme
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.16
+signing_key:
+specification_version: 4
+summary: A drag-and-drop block grid for Rails engine gems.
+test_files: []