publishing_platform_publishing_components 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fd01d35952a87cf92b3a809b7628e56626ece151e2d565e50a01b3f2b9f2e061
+  data.tar.gz: ba093a8a4bdaf481ee512f9591b1e8c5c1ac07e7c47b282d67d6e6040b6d4b65
+SHA512:
+  metadata.gz: 3d2483aaec570385b5ccb72fa91d69f6a823e4759f89bcca713ad1581611a7ddf7e2dda58ceb02f6443bfb25467039828530f78d25e84baf9fd5987768eb334c
+  data.tar.gz: 0eec104aef8ff7d932dbffc0b218707c8ba0c7032d9d89c62b4c025baea141693ed3a7886f813499717ffc4add6eaf82b5407e3da1d7be8369263767d3660a33

data/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Publishing Platform
+Copyright (c) 2017 Crown Copyright (Government Digital Service)
+
+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/README.md

@@ -0,0 +1,2 @@
+# Publishing Platform Publishing Components
+A gem to document and distribute frontend components for Publishing Platform applications

data/Rakefile

@@ -0,0 +1,41 @@
+require "bundler/setup"
+require "rubocop/rake_task"
+require "rspec/core/rake_task"
+APP_RAKEFILE = File.expand_path("spec/dummy/Rakefile", __dir__)
+
+load "rails/tasks/engine.rake"
+load "rails/tasks/statistics.rake"
+
+require "bundler/gem_tasks"
+
+RuboCop::RakeTask.new
+RSpec::Core::RakeTask.new
+
+namespace :assets do
+  desc "Test precompiling assets through dummy application"
+  task precompile: :environment do
+    Rake::Task["app:assets:precompile"].invoke
+  end
+
+  desc "Test cleaning assets through dummy application"
+  task clean: :environment do
+    Rake::Task["app:assets:clean"].invoke
+  end
+
+  desc "Test clobbering assets through dummy application"
+  task clobber: :environment do
+    Rake::Task["app:assets:clobber"].invoke
+  end
+end
+
+desc "Build the Sass files"
+task dartsass: :environment do
+  Rake::Task["app:dartsass:build"].invoke
+end
+
+desc "Linting for Ruby, JS and SASS"
+task lint: %i[rubocop environment] do
+  sh "yarn run lint"
+end
+
+task default: %i[dartsass lint spec]

data/app/assets/config/publishing_platform_publishing_components_manifest.js

@@ -0,0 +1,2 @@
+//= link_tree ../images
+//= link_tree ../builds

data/app/assets/stylesheets/publishing_platform_publishing_components/_all_components.scss

@@ -0,0 +1,3 @@
+@import "bootstrap";
+@import "components/attachment";
+@import "components/summary-list";

data/app/assets/stylesheets/publishing_platform_publishing_components/components/_attachment.scss

@@ -0,0 +1,117 @@
+@import 'functions';
+@import 'variables';
+@import 'mixins';
+
+$thumbnail-width: 99px;
+$thumbnail-height: 140px;
+$thumbnail-border-width: 5px;
+$thumbnail-background: $white;
+$thumbnail-border-colour: rgba(11, 12, 12, .1); /* stylelint-disable-line */
+$thumbnail-shadow-colour: rgba(11, 12, 12, .4); /* stylelint-disable-line */
+$thumbnail-shadow-width: 0 2px 2px;
+$thumbnail-icon-border-colour: $gray-500;
+
+.gem-c-attachment {
+  position: relative;
+
+  @include clearfix;
+}
+
+.gem-c-attachment__thumbnail {
+  position: relative;
+  width: auto;
+  padding: $thumbnail-border-width;
+  float: left;
+}
+
+.gem-c-attachment__thumbnail-image {
+  display: block;
+  width: auto; // for IE8
+  max-width: calc($thumbnail-width / 1.5);
+  height: calc($thumbnail-height / 1.5);
+  border: $thumbnail-border-colour; // for IE9 & IE10
+  outline: $thumbnail-border-width solid $thumbnail-border-colour;
+  background: $thumbnail-background;
+  box-shadow: $thumbnail-shadow-width $thumbnail-shadow-colour;
+  fill: $thumbnail-icon-border-colour;
+  stroke: $thumbnail-icon-border-colour;
+
+  @include media-breakpoint-up(sm) {
+    max-width: $thumbnail-width;
+    height: $thumbnail-height;
+  }
+}
+
+.gem-c-attachment__details {
+  padding-left: calc(($thumbnail-width + $thumbnail-border-width * 2 + 30px) / 1.5);
+
+  @include media-breakpoint-up(sm) {
+    padding-left: $thumbnail-width + $thumbnail-border-width * 2 + 25px;
+  }  
+
+  .gem-c-details {
+    margin-top: 15px;
+    word-break: break-word;
+    word-wrap: break-word;
+  }
+}
+
+.gem-c-attachment__title {
+  margin: 0 0 15px;
+  font-size: $h5-font-size;
+
+  @include media-breakpoint-up(sm) {
+    font-size: $h3-font-size;
+  }      
+}
+
+.gem-c-attachment__metadata {
+  margin: 0 0 15px;
+  color: $gray-600;
+  word-wrap:break-word;
+  overflow-wrap: break-word;
+
+  &:last-of-type {
+    margin-bottom: 0;
+  }
+}
+
+.publishing-platform-markdown,
+.gem-c-publishing-platform-markdown {
+  .gem-c-attachment__title {
+    margin: 0 0 15px;
+    font-size: $h5-font-size;
+
+    @include media-breakpoint-up(sm) {
+      font-size: $h3-font-size;
+    }    
+  }
+
+  .gem-c-attachment__metadata {
+    margin: 0 0 15px;
+  }
+}
+
+.gem-c-attachment__metadata--compact {
+  margin-bottom: 0;
+}
+
+.gem-c-attachment__abbr {
+  text-decoration: none !important;
+  cursor: help;
+}
+
+@media print {
+  .gem-c-attachment__details {
+    padding: 0;
+  }
+
+  .gem-c-attachment__metadata {
+    color: $black;
+  }
+
+  .gem-c-attachment__metadata,
+  .gem-c-attachment__metadata .govuk-link::after {
+    font-size: 12pt;
+  }
+}

data/app/assets/stylesheets/publishing_platform_publishing_components/components/_summary-list.scss

@@ -0,0 +1,169 @@
+@import 'functions';
+@import 'variables';
+@import 'mixins';
+
+.gem-c-summary-list {
+  margin-top: 1rem;
+
+  &:nth-of-type(1) {
+    margin-top: 0;
+  }
+}
+
+.gem-c-summary-list__group-title {
+  @include media-breakpoint-up(sm) {
+    display: inline-block;
+    margin-right: 15px;
+  }
+}
+
+.gem-c-summary-list__items {
+  clear: both;
+
+  @include media-breakpoint-up(sm) {
+    display: table;
+    width: 100%;
+    table-layout: fixed; // Required to allow us to wrap words that overflow.
+    border-collapse: collapse;
+  }
+
+  margin: 0; // Reset default user agent styles
+  margin-bottom: 30px;
+}  
+
+.gem-c-summary-list__row {
+  border-bottom: 1px solid $border-color;
+
+  @include media-breakpoint-down(sm){
+    margin-bottom: 15px;
+  }
+
+  @include media-breakpoint-up(sm){
+    display: table-row;
+  }
+}
+
+// Remove right padding from the last column in the row
+.gem-c-summary-list__row:not(.gem-c-summary-list__row--no-actions) > :last-child {
+  padding-right: 0;
+}
+
+.gem-c-summary-list__row--no-actions {
+  @include media-breakpoint-up(sm) {
+    &::after {
+      content: "";
+      display: table-cell;
+      width: 20%;
+    }
+  }
+}
+
+.gem-c-summary-list__key,
+.gem-c-summary-list__value,
+.gem-c-summary-list__actions {
+  margin: 0; // Reset default user agent styles
+
+  @include media-breakpoint-up(sm) {
+    display: table-cell;
+    padding-top: 10px;
+    padding-right: 20px;
+    padding-bottom: 10px;
+  }
+}
+
+.gem-c-summary-list__key,
+.gem-c-summary-list__value {
+  // Automatic wrapping for unbreakable text (e.g. URLs)
+  word-wrap: break-word; // Fallback for older browsers only
+  overflow-wrap: break-word;
+}
+
+.gem-c-summary-list__key {
+  margin-bottom: 5px;
+  font-weight: $font-weight-bold;
+
+  @include media-breakpoint-up(sm) {
+    width: 30%;
+  }
+}
+
+.gem-c-summary-list__value {
+  @include media-breakpoint-down(sm){
+    margin-bottom: 15px;
+  }  
+}
+
+.gem-c-summary-list__value > p {
+  margin-bottom: 10px;
+}
+
+.gem-c-summary-list__value > :last-child {
+  margin-bottom: 0;
+}
+
+.gem-c-summary-list__actions {
+  margin-bottom: 15px;
+
+  @include media-breakpoint-up(sm) {
+    width: 20%;
+    text-align: right;
+  }
+}
+
+.gem-c-summary-list__actions-list {
+  width: 100%;
+  margin: 0; // Reset default user agent styles
+  padding: 0; // Reset default user agent styles
+}
+
+.gem-c-summary-list__actions-list-item {
+  display: inline-block;
+}
+
+@include media-breakpoint-down(sm){
+  .gem-c-summary-list__actions-list-item {
+    margin-right: 10px;
+    padding-right: 10px;
+    border-right: 1px solid $border-color;
+  }
+  
+  .gem-c-summary-list__actions-list-item:last-child {
+    margin-right: 0;
+    padding-right: 0;
+    border: 0;
+  }
+}  
+
+@include media-breakpoint-up(sm){
+  .gem-c-summary-list__actions-list-item {
+    margin-left: 10px;
+    padding-left: 10px;
+  }
+
+  .gem-c-summary-list__actions-list-item:not(:first-child) {
+    border-left: 1px solid $border-color;
+  }
+
+  .gem-c-summary-list__actions-list-item:first-child {
+    margin-left: 0;
+    padding-left: 0;
+    border: 0;
+  }
+}
+
+.gem-c-summary-list__group-actions-list {
+  margin-bottom: 15px;
+
+  @include media-breakpoint-up(sm) {
+    float: right;
+    width: auto;
+  }
+}
+
+.gem-c-summary__block {  
+  margin-bottom: 20px;
+
+  @include media-breakpoint-up(sm) {
+    margin-bottom: 30px;
+  }    
+}

data/app/controllers/publishing_platform_publishing_components/application_controller.rb

@@ -0,0 +1,4 @@
+module PublishingPlatformPublishingComponents
+  class ApplicationController < ActionController::Base
+  end
+end

data/app/helpers/publishing_platform_publishing_components/application_helper.rb

@@ -0,0 +1,4 @@
+module PublishingPlatformPublishingComponents
+  module ApplicationHelper
+  end
+end

data/app/models/publishing_platform_publishing_components/component_doc.rb

@@ -0,0 +1,90 @@
+module PublishingPlatformPublishingComponents
+  class ComponentDoc
+    attr_reader :id,
+                :name,
+                :description,
+                :body,
+                :component,
+                :accessibility_excluded_rules,
+                :source,
+                :embed
+
+    def initialize(component)
+      @component = component
+      @id = component[:id]
+      @name = component[:name]
+      @description = component[:description]
+      @body = component[:body]
+      @accessibility_excluded_rules = component[:accessibility_excluded_rules]
+      @source = component[:source]
+      @embed = component[:embed]
+    end
+
+    def accessibility_criteria
+      shared_accessibility_criteria = []
+
+      if component[:shared_accessibility_criteria].present?
+        component[:shared_accessibility_criteria].each do |criteria|
+          shared_accessibility_criteria << SharedAccessibilityCriteria.send(criteria) if SharedAccessibilityCriteria.respond_to? criteria
+        end
+      end
+
+      "#{component[:accessibility_criteria]}\n#{shared_accessibility_criteria.join("\n")}"
+    end
+
+    def example
+      examples.first
+    end
+
+    def other_examples
+      examples.slice(1..-1)
+    end
+
+    def display_html?
+      component[:display_html]
+    end
+
+    def display_preview?
+      component[:display_preview].nil? || component[:display_preview]
+    end
+
+    def html_body
+      markdown_to_html(body) if body.present?
+    end
+
+    def html_accessibility_criteria
+      markdown_to_html(accessibility_criteria) if accessibility_criteria.present?
+    end
+
+    def partial_path
+      if source == "gem"
+        "publishing_platform_publishing_components/components/#{id}"
+      else
+        "#{PublishingPlatformPublishingComponents::Config.component_directory_name}/#{id}"
+      end
+    end
+
+    def publishing_platform_frontend_components
+      component[:publishing_platform_frontend_components].to_a
+    end
+
+    def github_search_url
+      params = { q: "org:publishing-platform components/components/#{id}", type: "Code" }
+      "https://github.com/search?#{params.to_query}"
+    end
+
+    def examples
+      @examples ||= component[:examples].map do |id, example_data|
+        example_data ||= {}
+        example_data["embed"] ||= embed
+        ComponentExample.new(id.to_s, example_data)
+      end
+    end
+
+  private
+
+    def markdown_to_html(markdown)
+      Kramdown::Document.new(markdown).to_html
+    end
+  end
+end

data/app/models/publishing_platform_publishing_components/component_docs.rb

@@ -0,0 +1,57 @@
+module PublishingPlatformPublishingComponents
+  # @private
+  class ComponentDocs
+    def initialize(gem_components: false)
+      @documentation_directory = gem_components ? gem_documentation_directory : app_documentation_directory
+    end
+
+    def get(id)
+      component = fetch_component_doc(id)
+      build(component)
+    end
+
+    def all
+      fetch_component_docs.map { |component| build(component) }.sort_by(&:name)
+    end
+
+    def used_in_this_app
+      fetch_component_docs.map { |component| build(component) if component_in_use(component[:id]) }.compact.sort_by(&:name)
+    end
+
+  private
+
+    def build(component)
+      ComponentDoc.new(component)
+    end
+
+    def fetch_component_docs
+      doc_files = Rails.root.join(@documentation_directory, "*.yml")
+      Dir[doc_files].sort.map { |file| parse_documentation(file) }
+    end
+
+    def fetch_component_doc(id)
+      file = Rails.root.join(@documentation_directory, "#{id}.yml")
+      if !file.exist?
+        file = gem_documentation_directory.join("#{id}.yml")
+        parse_documentation(file).merge(source: "gem")
+      else
+        parse_documentation(file).merge(source: "application")
+      end
+    end
+
+    def parse_documentation(file)
+      # Psych 4's YAML.unsafe_load_file === Psych 3's YAML.load_file
+      # but until we drop support for Ruby 2.7 and Ruby 3.0, we need to support both major versions of Psych
+      yaml = YAML.respond_to?(:unsafe_load_file) ? YAML.unsafe_load_file(file) : YAML.load_file(file)
+      { id: File.basename(file, ".yml") }.merge(yaml).with_indifferent_access
+    end
+
+    def app_documentation_directory
+      Rails.root.join("app", "views", PublishingPlatformPublishingComponents::Config.component_directory_name, "docs")
+    end
+
+    def gem_documentation_directory
+      Pathname.new(PublishingPlatformPublishingComponents::Config.gem_directory).join("app", "views", "publishing_platform_publishing_components", "components", "docs")
+    end
+  end
+end

data/app/models/publishing_platform_publishing_components/component_example.rb

@@ -0,0 +1,104 @@
+require "rouge"
+
+module PublishingPlatformPublishingComponents
+  class ComponentExample
+    attr_reader :id,
+                :data,
+                :context,
+                :description,
+                :block,
+                :embed
+
+    def initialize(id, example)
+      @id = id
+      @data = example["data"] || {}
+      @context = example["context"] || {}
+      @description = example["description"] || false
+      @block = @data.delete(:block) || false
+      @embed = example["embed"]
+    end
+
+    def name
+      id.humanize
+    end
+
+    def highlight_code(string_to_format = "")
+      formatter = Rouge::Formatters::HTML.new
+      lexer = Rouge::Lexers::ERB.new
+      formatter.format(lexer.lex(string_to_format)).html_safe
+    end
+
+    def pretty_data
+      json_key_regex = /"(\w*)":/ # matches quoted keys ending with a colon, i.e. "key":
+      output = JSON.pretty_generate(data).gsub('\\n', "\n    ").gsub(json_key_regex, '\1:')
+
+      quoted_string_regex = /"((?:[^"\\]|\\.)*)"/ # matches "some text" - ignores escaped quotes, i.e. \"
+      output.gsub(quoted_string_regex) do |group|
+        match = Regexp.last_match[1]
+        contains_html?(match) ? "sanitize(#{group})" : group
+      end
+    end
+
+    def contains_html?(input)
+      ActionController::Base.helpers.strip_tags(input) != input
+    end
+
+    def data?
+      data.any?
+    end
+
+    def html_safe_data
+      html_safe_strings(data.dup)
+    end
+
+    # Iterate through data object and recursively mark
+    # any found string as html_safe
+    #
+    # Safe HTML can be passed to components, simulate
+    # by marking any string that comes from YAML as safe
+    def html_safe_strings(obj)
+      case obj
+      when String
+        obj.html_safe
+      when Hash
+        obj.each do |key, value|
+          obj[key] = html_safe_strings(value)
+        end
+      when Array
+        obj.map! { |e| html_safe_strings(e) }
+      else
+        obj
+      end
+    end
+
+    def right_to_left?
+      context["right_to_left"].present?
+    end
+
+    def dark_background?
+      context["dark_background"].present?
+    end
+
+    def black_background?
+      !!context["black_background"]
+    end
+
+    def html_description
+      markdown_to_html(description) if description.present?
+    end
+
+    def has_block?
+      block.present?
+    end
+
+    def has_embed?
+      embed.present?
+    end
+
+  private
+
+    def markdown_to_html(markdown)
+      Kramdown::Document.new(markdown).to_html
+    end
+  end
+end

data/app/models/publishing_platform_publishing_components/shared_accessibility_criteria.rb

@@ -0,0 +1,37 @@
+module PublishingPlatformPublishingComponents
+  module SharedAccessibilityCriteria
+    def self.link
+      "
+  Links in the component must:
+
+  - accept focus
+  - be focusable with a keyboard
+  - be usable with a keyboard
+  - indicate when they have focus
+  - change in appearance when touched (in the touch-down state)
+  - change in appearance when hovered
+  - be usable with touch
+  - be usable with [voice commands](https://www.w3.org/WAI/perspectives/voice.html)
+  - have visible text
+  - have meaningful text
+        "
+    end
+
+    def self.button
+      "
+  Buttons in the component must:
+
+  - accept focus
+  - be focusable with a keyboard
+  - be usable with a keyboard
+  - indicate when they have focus
+  - change in appearance when touched (in the touch-down state)
+  - change in appearance when hovered
+  - be usable with touch
+  - be usable with [voice commands](https://www.w3.org/WAI/perspectives/voice.html)
+  - have visible text
+  - have meaningful text
+        "
+    end
+  end
+end

data/app/views/publishing_platform_publishing_components/component_doc/_component_output.html.erb

@@ -0,0 +1,15 @@
+<% component = capture do %>
+  <% if example.has_block? %>
+    <%= render component_doc.partial_path, example.html_safe_data do %>
+      <%= render inline: example.block %>
+    <% end %>
+  <% else %>
+    <%= render component_doc.partial_path, example.html_safe_data %>
+  <% end %>
+<% end %>
+
+<% if example.has_embed? %>
+  <%= render inline: example.embed, locals: { component: component } %>
+<% else %>
+  <%= component %>
+<% end %>