has_helpers 5.0.2

data/app/api/has_helpers/rack_api.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require "rack"
+
+# Rack API
+# This is an abstract class providing wrappers and default functionality for an
+# API provided as a mountable Rack appliaction.
+# This API follows JSON API standards (http://jsonapi.org/format/).
+module HasHelpers
+  class RackAPI
+    INTERNAL_ERROR_MSG = "Server internal error"
+    NOT_ACCEPTABLE_MSG = "Not Acceptable"
+    UNAUTHORIZED_MSG = "Unauthorized"
+    DEFAULT_HEADERS = { "Content-Type" => "application/json" }.freeze
+
+    def self.call(env)
+      new(env).run
+    end
+
+    attr_accessor :request
+
+    def initialize(env)
+      self.request = Rack::Request.new(env)
+    end
+
+    def run
+      catch(:response) do
+        validate_request_format!
+        authorize_user!
+        handle_request
+      end.tap do |response|
+        # Log the API request.
+        ::Rails.logger.info do
+          [
+            "SearchAPI: ",
+            response.first,
+            *(
+              (400..599).cover?(response.first.to_i) && response[-1] # Logs the body containing an error message
+            )
+          ].join(" ")
+        end
+      end
+    rescue => e
+      ::Rails.logger.info { "\n\n#{ ["SearchAPI Error", "~" * 40, e.message, *e.backtrace].join("\n") }" }
+      api_response(
+        status: 500,
+        body: error_body(title: INTERNAL_ERROR_MSG)
+      )
+    end
+
+    private
+
+    def current_user
+      request.env["warden"].user
+    end
+
+    def params
+      request.params
+    end
+
+    # Throws :response (with a Rack-compatible response) if the request does not
+    # accept a supported format.
+    def validate_request_format!
+      accepted_formats = request.env["HTTP_ACCEPT"].split(",")
+
+      # Currently we only support JSON format or any (*/*).
+      unless accepted_formats.any? { |format| format =~ %r[\A(?:\*/\*|application/json)(?:\b|;|\z)] }
+        api_response!(status: 406, body: error_body(title: NOT_ACCEPTABLE_MSG))
+      end
+    end
+
+    # Throws :response (with a Rack-compatible response) if the user is not
+    # authorized to make the request.
+    def authorize_user!
+      # We allow Warden/Devise to authenticate the user. Any additional
+      # authorization should be made here.
+      api_response!(status: 401, body: error_body(title: UNAUTHORIZED_MSG)) unless current_user
+    end
+
+    # Returns a Rack-compliant API response.
+    def api_response(status:, headers: default_headers.dup, body: nil)
+      # must dup the default_headers because Rack wants to modify them (and cannot if they are frozen).
+      serialized_body = body.is_a?(::String) ? body : body.to_json
+      [
+        status,
+        headers,
+        Array(serialized_body)
+      ]
+    end
+
+    # Throws an API reponse. This is intended for error/bad request cases and
+    # will immediately stop processing the request.
+    #
+    #===  Examples
+    #   api_response!(status: 400, body: "Bad Request") if resource.nil?
+    #   # ...code which should only run if a resource is present.
+    def api_response!(*args, **options)
+      throw(:response, api_response(*args, **options))
+    end
+
+    def handle_request
+      raise ::NotImplementedError
+    end
+
+    def default_headers
+      # Qualify the constant with a dynamic lookup (self.class) so that this
+      # method works with subclasses which override the constant value.
+      self.class::DEFAULT_HEADERS
+    end
+
+    def error_body(attrs)
+      # See standard structure for error objects http://jsonapi.org/format/#errors
+      { errors: [attrs] }
+    end
+  end
+end

data/app/api/has_helpers/search_api.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+# Handles incoming requests for searches. See docs/Search_API.md
+module HasHelpers
+  class SearchAPI < ::HasHelpers::RackAPI
+    OPTION_PARAM_KEYS = %w[with]
+    DEFAULT_QUERY_OPTIONS = { page: 1, per_page: 15 }.freeze
+    INVALID_QUERY_MSG = "Missing or invalid query"
+
+    class << self
+      attr_accessor :options_hook
+    end
+
+    def handle_request
+      validate_query!(raw_query)
+      resources.each { |r| validate_resource!(r) } # Validate each resource, if one fails it will throw an error.
+      api_response(
+        status: 200,
+        body: search # Run the search and return the result
+      )
+    end
+
+    def search
+      search_results = provider.search(
+        resource: resources,
+        query: raw_query,
+        options: query_options
+      )
+
+      # Show type when searching multiple resources OR any of the resources uses STI
+      show_type = resources.size > 1 || resource_klasses.any? { |k| k.descendants.any? }
+      search_presenter = ::HasHelpers::SearchPresenter.new(search_results[:results], show_type: show_type)
+      search_results.merge!(results: search_presenter.results(format_ungrouped: true))
+    end
+
+    private
+
+    def provider
+      if ::HasHelpers::Feature.active?(:sql_search)
+        ::HasHelpers::Query::Sql
+      else
+        ::HasHelpers::Query::Elasticsearch
+      end
+    end
+
+    def resources
+      @resources ||= begin
+                       # Split the given string value for resources, e.g. "Advisor,Client" => ["Advisor", "Client"]
+                       result = Array(params["resource"] && params["resource"].split(",")).map(&:strip)
+
+                       # If no resources are given then return _all_ Base-type resources, i.e. omitting
+                       # the resource param is the same as specifying ALL Base-type resources.
+                       result.empty? ? global_resources.map(&:name) : result
+                     end
+    end
+
+    def resource_klasses
+      @resource_klasses ||= resources.map { |klass_name| klass_name.constantize }.compact
+    end
+
+    def current_application
+      ::HasHelpers::Application.current_application(request)
+    end
+
+    def application_resources
+      current_application.resources
+    end
+
+    # Resources used when none is specified.
+    # This returns Base-type resources for which the current user has read permissions.
+    def global_resources
+      application_resources.
+        select { |r| r.resource_type == ::HasHelpers::ResourceType::BASE }.
+        select do |r|
+        !( # FIXME: This is Agencieshq-specific and should be injected •
+          current_user.respond_to?(:manager_only_access_class?) &&
+            current_user.manager_only_access_class?(r.klass)
+        )
+      end
+    end
+
+    # Any option param manipulation or default values belong here.
+    def base_query_options
+      self.class::DEFAULT_QUERY_OPTIONS.merge(
+        **params.slice(OPTION_PARAM_KEYS)
+      ).
+        tap do |options|
+        if params["with"]
+          options["with"] = params["with"].with_indifferent_access
+        else
+          options["with"] ||= {}
+        end
+
+        # If organization_id is given as a condition it should be sanitized.
+        # The only values allowed should be 0 (used to match non-org-specific
+        # records like source_carrier) or the current user's own org id.
+        if options["with"].has_key?("organization_id")
+          given_org_id = options["with"]["organization_id"].to_i
+          options["with"].delete("organization_id") unless given_org_id == 0 || given_org_id == current_user.organization_id
+        end
+
+        # If no org id is given then one should be added by default.
+        # 0 is always included for searches like "Scope" on the Advisor form,
+        # where we search across organization scoped resources and non organization
+        # scoped resources
+        unless options["with"]["organization_id"]
+          options["with"]["organization_id"] = current_user.organization_id
+        end
+
+        # FIXME: manager only access is Agencieshq-specific and should be injected •
+        # FIXME: manager only access for one type will prevent matches on another type, e.g. the presence of "user_ids_for_advisors" will exclude all contracts. •
+        resource_klasses.each do |klass|
+          if current_user.respond_to?(:manager_only_access_class?) && current_user.manager_only_access_class?(klass)
+            options["with"].merge!("user_ids_for_#{klass.table_name}".to_sym => [current_user.id]) if current_user.manager_only_access_class?(klass)
+          end
+        end
+      end.
+        with_indifferent_access # Sphinx is pretty picky about hash keys (symbols vs strings).
+    end
+
+    # Wrapper around the base_query_options. This invokes the options hook if it is set.
+    def query_options
+      if self.class.options_hook.respond_to?(:to_proc)
+        self.class.options_hook.call(
+          resources: resource_klasses,
+          query: raw_query,
+          options: base_query_options,
+          current_user: current_user,
+          provider: provider
+        )
+      else
+        base_query_options
+      end
+    end
+
+    #=== Examples
+    #   validate_resource!("Advisor")
+    #   validate_resource!("Contact")  # Matches HasContactInfo::Contact
+    def validate_resource!(resource)
+      unless valid_resource?(resource)
+        api_response!(
+          status: 422,
+          body: error_body(title: "Invalid Resource: '#{ resource }'")
+        )
+      end
+    end
+
+    def validate_query!(query)
+      if query.blank?
+        api_response!(
+          status: 422,
+          body: error_body(title: INVALID_QUERY_MSG)
+        )
+      end
+    end
+
+    #=== Examples
+    #   valid_resource?("Advisor")
+    def valid_resource?(resource)
+      application_resources.any? { |r| r.name == resource }
+    end
+
+    # Parses out the "with" options,
+    # e.g. "firm_id:23,product_type_id:12" => { "firm_id" => "23", "product_type_id" => "12" }
+    def parse_with_options(raw)
+      Hash[raw.scan(/([^:,]+):([^:,]+)/)] # Magic voodoo
+    end
+
+    def raw_query
+      params["query"]
+    end
+  end
+end

data/app/assets/stylesheets/has_helpers/base.scss

@@ -0,0 +1,5 @@
+@import "has_helpers/color_palette";
+
+@include colors;
+
+@import "has_helpers/components/dataset";

data/app/assets/stylesheets/has_helpers/color_palette.scss

@@ -0,0 +1,33 @@
+/* To override this create a stylesheet in the host application (or another engine) at a location which matches
+ * /has_helpers/color_palette (e.g. /app/assets/stylesheets/has_helpers/color_palette.scss). Import a palette or
+ * define custom palette options in that stylesheet.
+ */
+@import 'has_helpers/color_palettes/default';
+
+@mixin colors {
+  @if & {
+    &.color-none,
+    &.color-neutral    { color: $color-neutral; }
+    &.color-green      { color: $color-green; }
+    &.color-red        { color: $color-red; }
+    &.color-blue       { color: $color-blue; }
+    &.color-brown      { color: $color-brown; }
+    &.color-purple     { color: $color-purple; }
+    &.color-orange     { color: $color-orange; }
+    &.color-grey       { color: $color-grey; }
+    &.color-yellow     { color: $color-yellow; }
+    &.color-pink       { color: $color-pink; }
+  } @else {
+    .color-none,
+    .color-neutral    { color: $color-neutral; }
+    .color-green      { color: $color-green; }
+    .color-red        { color: $color-red; }
+    .color-blue       { color: $color-blue; }
+    .color-brown      { color: $color-brown; }
+    .color-purple     { color: $color-purple; }
+    .color-orange     { color: $color-orange; }
+    .color-grey       { color: $color-grey; }
+    .color-yellow     { color: $color-yellow; }
+    .color-pink       { color: $color-pink; }
+  }
+}

data/app/assets/stylesheets/has_helpers/color_palettes/default.scss

@@ -0,0 +1,11 @@
+$color-grey:      #a9aeb8;
+$color-dark-grey: #838B95;
+$color-green:     #88dbb2;
+$color-red:       #f28090;
+$color-blue:      #8fd6ff;
+$color-brown:     #d0c0b4;
+$color-purple:    #aa9eea;
+$color-orange:    #fbb57c;
+$color-neutral:   #a9a4ee;
+$color-yellow:    #F5C700;
+$color-pink:      #ea9ed0;

data/app/assets/stylesheets/has_helpers/components/dataset.scss

@@ -0,0 +1,43 @@
+.dataset {
+  .row {
+    margin: 0;                  // Cancel some Bootstrap setting
+    &:after { content: none; }  // Cancel some Bootstrap setting
+  }
+
+  .pre {
+    white-space: pre;
+  }
+
+  &.table {
+    // Cancel Bootstrap styles
+    width: auto;
+    max-width: none;
+    margin: 0;
+
+    display: table;
+
+    > .row {
+      display: table-row;
+
+      > .cell {
+        display: table-cell;
+        padding-top: 5px;
+        padding-bottom: 5px;
+        padding-left: 12px;
+        text-align: left;
+        word-break: break-word;  // Prevent long words, especially email addresses, from pushing the table wider than the container.
+
+        &:first-child {
+          text-align: center;
+          padding-left: 0;
+        }
+      }
+
+      &:first-child {
+        > .cell {
+          padding-top: 0;
+        }
+      }
+    }
+  }
+}

data/app/assets/stylesheets/has_helpers/mixins.scss

@@ -0,0 +1,149 @@
+/* Common mixins which are used throughout HQ applications and engines
+ * ===================================================================
+ */
+
+@mixin border-box {
+  @include vendor-prefix('box-sizing', 'border-box');
+}
+
+// Clearfix for clearing floats like a boss h5bp.com/q
+@mixin clearfix {
+  zoom: 1;
+  &:before, &:after {
+    display: table;
+    content: "";
+    zoom: 1;
+  }
+  &:after {
+    clear: both;
+  }
+}
+
+@mixin horizontal-list {
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+// Center-align a block level element
+@mixin center-block {
+  display: block;
+  margin-left: auto;
+  margin-right: auto;
+}
+
+// Border Radius
+@mixin border-radius($radius: 5px) {
+  @include vendor-prefix('border-radius', $radius);
+}
+
+// Drop shadows
+@mixin box-shadow($shadow...) {
+  @include vendor-prefix('box-shadow', $shadow);
+}
+
+// Transitions
+@mixin transition ($transition...) {
+  @include vendor-prefix('transition', $transition);
+}
+
+// CSS3 Content Columns
+@mixin content-columns($columnCount, $columnGap: 20px) {
+  @include vendor-prefix('column-count', $columnCount);
+  @include vendor-prefix('column-gap', $columnGap);
+}
+
+@mixin gradient {
+  background: -webkit-linear-gradient($color-item-gradient1, #f3f3f3);
+}
+
+@mixin vertical-gradient($startColor: #555555, $endColor: #333333) {
+  background-color: $endColor;
+  background-repeat: repeat-x;
+  background-image: -moz-linear-gradient(top, $startColor, $endColor);
+  // FF 3.6+
+  background-image: -ms-linear-gradient(top, $startColor, $endColor);
+  // IE10
+  background-image: -webkit-gradient(linear, left top, left bottom, color-stop(0%, $startColor), color-stop(100%, $endColor));
+  // Safari 4+, Chrome 2+
+  background-image: -webkit-linear-gradient(top, $startColor, $endColor);
+  // Safari 5.1+, Chrome 10+
+  background-image: -o-linear-gradient(top, $startColor, $endColor);
+  // Opera 11.10
+  background-image: linear-gradient(top, $startColor, $endColor);
+  // The standard
+  -ms-filter: progid:DXImageTransform.Microsoft.gradient(startColorstr='#{$startColor}', endColorstr='#{$endColor}', GradientType=0);
+  // IE9 and down
+}
+
+@mixin directional-gradient($startColor: #555555, $endColor: #333333, $deg: 45deg) {
+  background-color: $endColor;
+  background-repeat: repeat-x;
+  background-image: -moz-linear-gradient($deg, $startColor, $endColor);
+  // FF 3.6+
+  background-image: -ms-linear-gradient($deg, $startColor, $endColor);
+  // IE10
+  background-image: -webkit-linear-gradient($deg, $startColor, $endColor);
+  // Safari 5.1+, Chrome 10+
+  background-image: -o-linear-gradient($deg, $startColor, $endColor);
+  // Opera 11.10
+  background-image: linear-gradient($deg, $startColor, $endColor);
+  // The standard
+}
+
+@mixin vertical-three-colors-gradient($startColor: #00b3ee, $midColor: #7a43b6, $colorStop: 50%, $endColor: #c3325f) {
+  background-color: $endColor;
+  background-repeat: no-repeat;
+  background-image: -webkit-gradient(linear, 0 0, 0 100%, from($startColor), color-stop($colorStop, $midColor), to($endColor));
+  background-image: -webkit-linear-gradient($startColor, $midColor $colorStop, $endColor);
+  background-image: -moz-linear-gradient($startColor, $midColor $colorStop, $endColor);
+  background-image: -ms-linear-gradient($startColor, $midColor $colorStop, $endColor);
+  background-image: -o-linear-gradient($startColor, $midColor $colorStop, $endColor);
+  background-image: linear-gradient($startColor, $midColor $colorStop, $endColor);
+  filter: progid:DXImageTransform.Microsoft.gradient(startColorstr='#ff#{$startColor}', endColorstr='#ff#{$endColor}', GradientType=0);
+  // IE9 and down, gets no color-stop at all the proper fallback
+}
+
+// Opacity
+@mixin opacity($opacity: 100) {
+  @include vendor-prefix('opacity', $opacity / 100);
+  filter: alpha(opacity = $opacity)\9;
+}
+
+@mixin box-sizing($model) {
+  @include vendor-prefix('box-sizing', $model);
+}
+
+@mixin vendor-prefix($name, $value) {
+  @each $vendor in ('', '-webkit-', '-moz-', '-ms-', '-o-') {
+    #{$vendor}#{$name}: #{$value};
+  }
+}
+
+@mixin justified {
+  font-size: 0.1px;  // Collapse whitespace, must be greater than 0 to work in IE
+  text-align: justify;
+  white-space: normal;
+
+  > * {
+    display: inline-block;
+    font-size: 1.4rem;  // Reset font size
+  }
+
+  &:after {
+    content: "";
+    display: inline-block;
+    width: 100%;
+    height: 0;
+  }
+}
+
+@mixin wrapped-text {
+  -ms-word-break: break-all;
+  word-break: break-all;
+  word-break: break-word;  // Non standard for webkit
+
+  -webkit-hyphens: auto;
+  -moz-hyphens: auto;
+  hyphens: auto;
+}

data/app/commands/has_helpers/cards/available_cards_command.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module HasHelpers
+  module Cards
+    # Command object that returns the catalog of cards available for a given
+    # resource WITHOUT resolving any record data. Unlike CardDataCommand this is
+    # global (not scoped to a role): it does not apply role visibility/position
+    # overrides and does not build field entries.
+    #
+    # For each CardDefinition linked to the resource it returns the card-level
+    # metadata (name, description, identifier, layout, variant, position) plus
+    # the non-persisted presentation hints (icon_name, icon_color) which live in
+    # the DSL registry only.
+    #
+    # Usage:
+    #   cards = HasHelpers::Cards::AvailableCardsCommand.call(resource_id: resource)
+    #   cards.first # => { id:, name:, description:, identifier:, layout:, variant:,
+    #               #      position:, icon_name:, icon_color: }
+    class AvailableCardsCommand
+      def self.call(resource_id:)
+        new(resource_id: resource_id).call
+      end
+
+      def initialize(resource_id:)
+        @resource = find_resource(resource_id)
+      end
+
+      def call
+        card_definitions.map { |card_definition| serialize_card(card_definition) }
+      end
+
+      private
+
+      attr_reader :resource
+
+      def find_resource(resource_or_id)
+        return resource_or_id if resource_or_id.is_a?(::HasHelpers::Resource)
+
+        ::HasHelpers::Resource.find(resource_or_id)
+      end
+
+      # All persisted card definitions linked to this resource. Hover-only cards
+      # are not persisted, so they're naturally excluded.
+      def card_definitions
+        ::HasHelpers::Cards::CardDefinition.
+          joins(:card_definition_resources).
+          where(card_definition_resources: { resource_id: resource.id }).
+          ordered.
+          includes(:identifier, :layout_type, :variant).
+          distinct
+      end
+
+      def serialize_card(card_definition)
+        registry_meta = registry_card_for(card_definition)
+
+        {
+          id:          card_definition.id,
+          name:        card_definition.name,
+          description: card_definition.description,
+          identifier:  serialize_identifier(card_definition.identifier),
+          layout:      card_definition.layout_type.name.downcase.to_sym,
+          variant:     card_definition.variant&.name&.downcase&.to_sym,
+          position:    card_definition.position,
+          icon_name:   registry_meta && registry_meta[:icon_name],
+          icon_color:  registry_meta && registry_meta[:icon_color]
+        }
+      end
+
+      # Maps a persisted card definition back to its in-memory DSL registry entry
+      # so we can read the non-persisted icon_name / icon_color hints.
+      def registry_card_for(card_definition)
+        @registry_cards ||=
+          ::HasHelpers::Cards::Registry.cards.index_by { |c| normalize_identifier(c[:identifier]) }
+        @registry_cards[normalize_identifier(card_definition.identifier)]
+      end
+
+      def serialize_identifier(identifier_value)
+        return nil if identifier_value.nil?
+
+        if identifier_value.respond_to?(:id) && identifier_value.id
+          identifier_value.id
+        elsif identifier_value.respond_to?(:name) && identifier_value.name
+          identifier_value.name.to_s
+        else
+          identifier_value.to_s
+        end
+      end
+
+      def normalize_identifier(identifier_value)
+        if identifier_value.respond_to?(:name) && !identifier_value.is_a?(String)
+          identifier_value.name.to_s
+        else
+          identifier_value.to_s
+        end
+      end
+    end
+  end
+end