pads 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: be715c4688e1f082e10af7c2385da9247d79f28bbb2eddb72df8b8815dce4731
-  data.tar.gz: dbc239568a2d963a89fdde625c8c5ba43ff92265f35d209dda9689dca312a5a0
+  metadata.gz: ef83cd4cd517c8201f18b8208a6adb8ca42d5dadef3e810c5007822662768b1f
+  data.tar.gz: 77a457197b5c98ec963a95b2f62a6b9e1e59a2d69cdfd268112279e280248df5
 SHA512:
-  metadata.gz: f6d64adf601c1470c62c2e6fb98f20588a0a4b22bd7c79af1272f7351eef6d9f99844ff92292dc644f8004c983fb48d2c44bba97126d10b4be20a1583f5c92f4
-  data.tar.gz: 203534cc26d0b207657765665c6444ae44a506b23510e325f5b4f953549ab242f7e216d333df48b86591646cd3c3cb65425db2828d60ce60df01d2b8842366ba
+  metadata.gz: 48cd6de1372be26d55b682c4de3ad1119c6855b588190f05ea1c9ce4b34412a15ccc851c760e8e8e388a5dd786f596b93e21bac9975f0c9011bc9d33e166101d
+  data.tar.gz: 98939e84ce761264920b1a039ff62dd50fd31ee8a2c497b55467ede72a505f1a7ea7a163d6a181e6b2f005c956e83637c25d8ad890dc792ea42df1150cd72d20

data/.rubocop.yml

@@ -1,13 +1,43 @@
 AllCops:
   TargetRubyVersion: 2.6
+  NewCops: enable
+
+Style/Alias:
+  EnforcedStyle: prefer_alias
+
+Style/BlockDelimiters:
+  Exclude:
+    - spec/**/*_spec.rb
 
 Style/StringLiterals:
   Enabled: true
-  EnforcedStyle: double_quotes
+  EnforcedStyle: single_quotes
 
 Style/StringLiteralsInInterpolation:
   Enabled: true
-  EnforcedStyle: double_quotes
+  EnforcedStyle: single_quotes
 
 Layout/LineLength:
   Max: 120
+
+Layout/HashAlignment:
+  EnforcedColonStyle: table
+  EnforcedHashRocketStyle: table
+
+Lint/AmbiguousBlockAssociation:
+  Enabled: false
+
+Lint/AmbiguousOperator:
+  Enabled: false
+
+Metrics/BlockLength:
+  IgnoredMethods:
+    - describe
+    - it
+
+Metrics/MethodLength:
+  Max: 12
+
+Naming/MethodName:
+  IgnoredPatterns:
+    - !ruby/regexp /^([A-Z][a-z]*)+$/

data/.ruby-version

@@ -1 +1 @@
-3.1.0
+2.6.8

data/Gemfile

@@ -1,12 +1,14 @@
 # frozen_string_literal: true
 
-source "https://rubygems.org"
+source 'https://rubygems.org'
 
 # Specify your gem's dependencies in pads.gemspec
 gemspec
 
-gem "rake", "~> 13.0"
+gem 'rake', '~> 13.0'
 
-gem "rspec", "~> 3.0"
+gem 'rspec', '~> 3.0'
 
-gem "rubocop", "~> 1.21"
+gem 'rubocop', '~> 1.21'
+gem 'rubocop-rake'
+gem 'rubocop-rspec'

data/Gemfile.lock

@@ -1,13 +1,15 @@
 PATH
   remote: .
   specs:
-    pads (0.1.0)
+    pads (1.0.0)
+      interop (~> 0.3.1)
 
 GEM
   remote: https://rubygems.org/
   specs:
     ast (2.4.2)
     diff-lcs (1.5.0)
+    interop (0.3.1)
     parallel (1.21.0)
     parser (3.1.1.0)
       ast (~> 2.4.1)
@@ -39,18 +41,26 @@ GEM
       unicode-display_width (>= 1.4.0, < 3.0)
     rubocop-ast (1.16.0)
       parser (>= 3.1.1.0)
+    rubocop-rake (0.6.0)
+      rubocop (~> 1.0)
+    rubocop-rspec (2.9.0)
+      rubocop (~> 1.19)
     ruby-progressbar (1.11.0)
     unicode-display_width (2.1.0)
 
 PLATFORMS
+  x86_64-darwin-19
   x86_64-darwin-20
   x86_64-darwin-21
+  x86_64-linux
 
 DEPENDENCIES
   pads!
   rake (~> 13.0)
   rspec (~> 3.0)
   rubocop (~> 1.21)
+  rubocop-rake
+  rubocop-rspec
 
 BUNDLED WITH
    2.3.5

data/README.md

@@ -1,8 +1,6 @@
 # Pads
 
-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/pads`. To experiment with that code, run `bin/console` for an interactive prompt.
-
-TODO: Delete this and the text above, and describe your gem
+Provide pads to the Pads macOS app.
 
 ## Installation
 
@@ -22,7 +20,7 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+Check the examples.
 
 ## Development
 
@@ -32,7 +30,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/pads. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/pads/blob/master/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at https://github.com/hx/pads. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/hx/pads/blob/master/CODE_OF_CONDUCT.md).
 
 ## License
 
@@ -40,4 +38,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the Pads project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/pads/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the Pads project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/hx/pads/blob/master/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
 
 RSpec::Core::RakeTask.new(:spec)
 
-require "rubocop/rake_task"
+require 'rubocop/rake_task'
 
 RuboCop::RakeTask.new
 

data/lib/pads/client/local_resolver.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require 'pathname'
+require 'socket'
+require 'json'
+
+module Pads
+  class Client
+    # Creates raw connections based on the macOS app's configuration.
+    class LocalResolver
+      APP_CONTAINER_SUFFIX = 'Library/Containers/hx.pads/Data'
+      LISTENERS_PATH       = '.pads/listeners.json'
+
+      def initialize(home: Dir.home)
+        @home = Pathname(home)
+      end
+
+      def connect
+        errors = []
+        each_config do |type, config|
+          conn, error = __send__(:"try_#{type}", config)
+          return conn if conn
+
+          errors << error
+        end
+        raise errors.compact.first || 'Unable to connect to local server'
+      end
+
+      private
+
+      def each_config
+        %w[unix tcp].each do |type|
+          parsed_listeners.each do |listeners|
+            listeners[type]&.each do |config|
+              yield type, config
+            end
+          end
+        end
+      end
+
+      # @return [Array<Hash>]
+      def parsed_listeners
+        listeners_path_candidates
+          .map do |path|
+            next unless path.exist?
+
+            JSON.parse path.readlines.delete_if { |l| l.start_with? '//' }.join
+          end
+          .compact
+      end
+
+      # @return [Array<Pathname>]
+      def listeners_path_candidates
+        [
+          @home + LISTENERS_PATH,                        # Regular app version
+          @home + APP_CONTAINER_SUFFIX + LISTENERS_PATH  # Sandboxed (app store) app version
+        ]
+      end
+
+      def try_unix(config)
+        try { UNIXSocket.new Pathname(config.fetch('path')).to_s }
+      end
+
+      def try_tcp(config)
+        try { TCPSocket.new config.fetch('host', '127.0.0.1'), config.fetch('port') }
+      end
+
+      def try
+        [yield, nil]
+      rescue StandardError => e
+        [nil, e]
+      end
+    end
+  end
+end

data/lib/pads/client/pad.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require 'pads/events/dispatcher'
+require 'pads/mutable_pad_state'
+
+module Pads
+  class Client
+    # Proxy to a Client for a specific pad
+    class Pad < MutablePadState
+      attr_reader :events, :pad_id
+
+      def initialize(pad_id, client, &on_destroy)
+        @pad_id     = pad_id
+        @client     = client
+        @on_destroy = on_destroy
+        @events     = Events::Dispatcher.new
+
+        super()
+      end
+
+      def destroy
+        call :destroy_pad
+        @client = nil
+        @on_destroy.call
+        @on_destroy = nil
+      end
+
+      def title=(new_title)
+        call :set_pad_title, new_title.to_s
+        super
+      end
+
+      def subtitle=(new_subtitle)
+        call :set_pad_subtitle, new_subtitle.to_s
+        super
+      end
+
+      def activity=(fraction)
+        call :set_pad_activity, transform_activity(fraction)
+        super
+      end
+
+      def clickable=(clickable)
+        call :set_pad_clickable, clickable ? true : false
+        super
+      end
+
+      def buttons=(buttons)
+        call :set_pad_buttons, buttons&.map { |i| { label: i.to_s } } || []
+        super
+      end
+
+      def is_drop_target=(is_drop_target)
+        call :set_pad_is_drop_target, is_drop_target ? true : false
+        super
+      end
+
+      def on_pad_clicked(&handler)
+        @events.on :pad_clicked, &handler
+      end
+
+      # @yieldparam [Pads::Events::ButtonClicked]
+      def on_button_clicked(&handler)
+        @events.on :button_clicked, &handler
+      end
+
+      # @yieldparam [Pads::Events::FilesDropped]
+      def on_files_dropped(&handler)
+        @events.on :files_dropped, &handler
+      end
+
+      alias == equal?
+
+      private
+
+      def call(class_name, arg = nil)
+        raise 'Pad was destroyed' unless @client
+
+        @client.call class_name, Hx::Interop::ContentType::JSON.encode(arg), pad_id: @pad_id
+      end
+
+      def transform_activity(fraction_or_bool)
+        case fraction_or_bool
+        when true, false, nil
+          { busy: fraction_or_bool == true, progress: nil }
+        when Numeric
+          { busy: false, progress: fraction_or_bool.to_f.clamp(0, 1) }
+        else
+          raise ArgumentError, 'Expected nil, boolean, or a number'
+        end
+      end
+    end
+  end
+end

data/lib/pads/client.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require 'interop'
+
+require 'pads/client/pad'
+require 'pads/client/local_resolver'
+
+module Pads
+  # Low-level client for Pads servers
+  class Client
+    def initialize(reader = nil, writer = nil)
+      reader ||= LocalResolver.new.connect
+
+      @pads = {}
+      @rpc_client = Hx::Interop::RPC::Client.new(reader, writer || reader)
+      @rpc_client.on(//) do |message|
+        next unless (pad_id = message[:pad_id])
+
+        @pads[pad_id]&.events&.dispatch(
+          message[Hx::Interop::Headers::CLASS],
+          message[Hx::Interop::Headers::CONTENT_TYPE] ? message.decode : message.body
+        )
+      end
+    end
+
+    def create_pad(before: nil, after: nil)
+      raise 'You cannot specify before and after' if before && after
+
+      headers = {
+        before_pad_id: before && pad_id(before),
+        after_pad_id:  after && pad_id(after)
+      }.compact
+
+      pad_id        = call(:create_pad, headers)[:pad_id]
+      @pads[pad_id] = Pad.new(pad_id, self) { @pads.delete pad_id }
+    end
+
+    def swap_pads(pad_or_range_a, pad_or_range_b)
+      call :swap_pads, Hx::Interop::ContentType::JSON.encode(
+        range_a: pad_range(*Array(pad_or_range_a)),
+        range_b: pad_range(*Array(pad_or_range_b))
+      )
+    end
+
+    def wait
+      @rpc_client.wait
+    end
+
+    def call(*args, &block)
+      @rpc_client.call(*args, &block)
+    end
+
+    private
+
+    def pad_id(pad_or_id)
+      case pad_or_id
+      when String
+        pad_or_id
+      when Pad
+        @pads.key(pad_or_id) or
+          raise 'The given pad does not belong to this client'
+      else
+        raise ArgumentError, "Unexpected #{pad_or_id.inspect}"
+      end
+    end
+
+    def pad_range(first, last = first)
+      {
+        first_pad_id: pad_id(first),
+        last_pad_id:  pad_id(last)
+      }
+    end
+  end
+end

data/lib/pads/events/base.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Pads
+  module Events
+    class Base # rubocop:disable Lint/EmptyClass
+    end
+  end
+end

data/lib/pads/events/button_clicked.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'pads/events/base'
+
+module Pads
+  module Events
+    # Occurs when one of a pad's buttons are clicked.
+    class ButtonClicked < Base
+      # Zero-based index of the button that was clicked.
+      # @return Integer
+      attr_reader :index
+
+      # Label of the button that was clicked.
+      # @return String
+      attr_reader :label
+
+      def initialize(event_data)
+        @index = event_data.fetch('index')
+        @label = event_data.fetch('label')
+        super()
+      end
+    end
+  end
+end

data/lib/pads/events/dispatcher.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'pads/events/publisher'
+require 'pads/events/button_clicked'
+require 'pads/events/files_dropped'
+
+module Pads
+  module Events
+    # A central object for dispatch all events related to an event subject.
+    class Dispatcher
+      DEFAULT_PUBLISHERS = {
+        pad_clicked:    nil,
+        button_clicked: Events::ButtonClicked,
+        files_dropped:  Events::FilesDropped
+      }.freeze
+
+      attr_reader :publishers
+
+      def initialize(publishers = DEFAULT_PUBLISHERS)
+        @publishers = publishers.to_h do |event_name, event_class|
+          [event_name.to_s, Publisher.new(event_class)]
+        end.freeze
+      end
+
+      def on(event_name, &handler)
+        @publishers.fetch(event_name.to_s).subscribe(&handler)
+      end
+
+      def dispatch(event_name, payload = nil)
+        @publishers[event_name.to_s]&.publish payload
+      end
+    end
+  end
+end

data/lib/pads/events/files_dropped.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'pads/events/base'
+
+require 'pathname'
+require 'uri'
+
+module Pads
+  module Events
+    # Occurs when files are dropped on a pad.
+    class FilesDropped < Base
+      File = Struct.new(:path)
+
+      # @return Array<File>
+      attr_reader :files
+
+      def initialize(event_data)
+        @files = event_data.map do |file|
+          File.new Pathname URI.decode_www_form_component URI(file.fetch('url')).path
+        end
+        super()
+      end
+    end
+  end
+end

data/lib/pads/events/publisher.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'set'
+require 'pads/events/subscription'
+
+module Pads
+  module Events
+    # Manages event subscribers and distributes events to them.
+    class Publisher
+      def initialize(payload_class = nil)
+        @payload_class = payload_class
+        @handlers      = Set.new.compare_by_identity
+      end
+
+      def subscribe(&block)
+        Subscription.new(self, block).tap { |h| @handlers << h }
+      end
+
+      def unsubscribe_all
+        @handlers.clear
+        self
+      end
+
+      def publish(payload = nil)
+        payload = @payload_class.new(payload) if @payload_class && !payload.is_a?(@payload_class)
+        @handlers.each do |handler|
+          handler.__send__ :call, payload
+        end
+        payload
+      end
+
+      private
+
+      def unsubscribe(handler)
+        @handlers.delete handler
+      end
+    end
+  end
+end

data/lib/pads/events/subscription.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'set'
+
+module Pads
+  module Events
+    # Represents an event subscription, and can be used to unsubscribe.
+    class Subscription
+      def initialize(publisher, proc)
+        @publisher = publisher
+        @proc      = proc
+      end
+
+      def unsubscribe
+        @publisher.__send__ :unsubscribe, self
+        self
+      end
+
+      private
+
+      def call(*args, &block)
+        @proc.call(*args, &block)
+      end
+    end
+  end
+end

data/lib/pads/live_array.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require 'observer'
+
+module Pads
+  # An array that can be mapped to pads, and will update a pad group when it changes.
+  class LiveArray < Array
+    include Observable
+
+    OBSERVED_METHODS = Set.new(
+      %i[
+        []= << push append prepend pop shift unshift insert
+        delete delete_at delete_if keep_if fill clear replace
+      ] + instance_methods.grep(/!$/)
+    )
+
+    OBSERVED_METHODS.each do |method|
+      class_eval <<-RUBY, __FILE__, __LINE__ + 1
+        def #{method}(*)              # def push(*)
+          original = dup              #   original = dup
+          result   = super            #   result   = super
+          changed self != original    #   changed self != original
+          notify_observers            #   notify_observers
+          result                      #   result
+        end                           # end
+      RUBY
+    end
+  end
+end

data/lib/pads/mapper.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require 'pads/pad_group'
+require 'pads/live_array'
+
+module Pads
+  # A Mapper binds an ObservableArray to a PadGroup
+  class Mapper
+    def self.map(source, id: :object_id, &mapper)
+      if source.is_a? LiveArray
+        new(source, id: id, &mapper).target
+      else
+        PadGroup.new Array(source).map(&mapper)
+      end
+    end
+
+    # @return [PadGroup]
+    attr_reader :target
+
+    def initialize(source, id: :object_id, &mapper)
+      raise ArgumentError, 'Expected a LiveArray' unless source.is_a? LiveArray
+
+      @id     = id.to_proc
+      @mapper = mapper
+      @source = source
+      @target = PadGroup.new
+      @actual = []
+      source.add_observer self
+      update
+    end
+
+    def update
+      ids = @source.map(&@id)
+      @target.batch do
+        remove_old_members ids
+        sort_members ids
+        add_new_members ids
+      end
+    end
+
+    private
+
+    def remove_old_members(ids)
+      expected = Set.new(ids)
+      @actual.each.with_index.reverse_each do |id, index|
+        next if expected.include? id
+
+        @actual.delete_at index
+        @target.delete_at index
+      end
+    end
+
+    def sort_members(ids)
+      return unless @actual.length > 1
+
+      expected = (ids & @actual)
+
+      (0..(@actual.length - 2)).each do |i|
+        next if expected[i] == @actual[i]
+
+        j = @actual.index(expected[i])
+        @actual[j], @actual[i] = @actual.values_at(i, j)
+        @target.swap i, j
+      end
+    end
+
+    def add_new_members(ids)
+      skip = Set.new(@actual)
+      @source.each.with_index do |object, index|
+        id = ids[index]
+        next if skip.include? id
+
+        @actual.insert index, id
+        @target.insert index, @mapper.call(object)
+      end
+    end
+  end
+end