custom_elements_manifest_parser 0.1.0

data/lib/custom_elements_manifest_parser/nodes/javascript_module.rb

@@ -0,0 +1,58 @@
+require_relative "../base_struct.rb"
+require_relative "../types.rb"
+
+module CustomElementsManifestParser
+  module Nodes
+    # Document a JS module
+    class JavaScriptModule < BaseStruct
+      # @!attribute kind
+      #    @return ["javascript-module"]
+      attribute :kind, Types.Value("javascript-module")
+
+      # @return ["javascript-module"]
+      def self.kind; "javascript-module"; end
+
+      # @!attribute path
+      #   @return [String] -
+      #     Path to the javascript file needed to be imported.
+      #     (not the path for example to a typescript file.)
+      attribute :path, Types::Strict::String
+
+      # @!attribute summary
+      #   @return [String, nil] - A markdown summary suitable for display in a listing.
+      attribute :summary, Types::Strict::String.optional.meta(required: false)
+
+      # @!attribute declarations
+      #    @return[nil, Array<
+      #      Nodes::ClassDeclaration,
+      #      Nodes::FunctionDeclaration,
+      #      Nodes::MixinDeclaration,
+      #      Nodes::VariableDeclaration>] -
+      #        The declarations of a module.
+      #        For documentation purposes, all declarations that are reachable from
+      #        exports should be described here. Ie, functions and objects that may be
+      #        properties of exported objects, or passed as arguments to functions.
+      attribute :declarations, Types::Strict::Array.optional.meta(required: false)
+
+      # @!attribute exports
+      #   @return [nil, Array<CustomElementExport, JavaScriptExport>] -
+      #     The exports of a module. This includes JavaScript exports and
+      #     custom element definitions.
+      attribute :exports, Types::Strict::Array.optional.meta(required: false)
+
+      # @!attribute deprecated
+      #    @return [String, nil, Boolean] -
+      #       Whether the module is deprecated.
+      #       If the value is a string, it's the reason for the deprecation.
+      attribute :deprecated, Types::Strict::String.optional | Types::Strict::Bool.optional.meta(required: false)
+
+      def visit(parser:)
+        hash = {}
+        hash[:declarations] = declarations.map { |declaration| parser.visit_node(declaration.merge(parent_module: self)) } unless declarations.nil?
+        hash[:exports] = exports.map { |export| parser.visit_node(export.merge(parent_module: self)) } unless exports.nil?
+
+        new(hash)
+      end
+    end
+  end
+end

data/lib/custom_elements_manifest_parser/nodes/manifest.rb

@@ -0,0 +1,36 @@
+require_relative "../base_struct.rb"
+require_relative "../types.rb"
+
+module CustomElementsManifestParser
+  module Nodes
+    # top level of a custom elements manifest. This technically isn't a "ParseableNode". its a top level "root" of a custom-elements.json.
+    class Manifest < BaseStruct
+      # @!attribute schemaVersion
+      #   @return [String] - Version of the schema.
+      attribute :schemaVersion, Types::Strict::String
+
+      # @!attribute modules
+      #   @return [Array<Nodes::JavaScriptModule>] - An array of the modules this package contains..
+      attribute :modules, Types::Strict::Array
+
+      # @!attribute readme
+      #   @return [String, nil] - The Markdown to use for the main readme of this package.
+      attribute :readme, Types::Strict::String.optional.meta(required: false)
+
+      # @!attribute deprecated
+      #   @return [String, Boolean, nil] - if nil or false, not deprecated. If true, deprecated. If string, why it's deprecated.
+      attribute :deprecated, Types::Bool.optional | Types::String.optional.meta(required: false)
+
+      def visit(parser:)
+        hash = {}
+
+        hash[:modules] = modules.map do |mod|
+          parser.visit_node(mod)
+        end
+
+        hash[:modules]
+        new(hash)
+      end
+    end
+  end
+end

data/lib/custom_elements_manifest_parser/nodes/mixin_declaration.rb

@@ -0,0 +1,93 @@
+require_relative "../structs/function_like_struct.rb"
+require_relative "../structs/declarable_node_struct.rb"
+require_relative "../structs/custom_element_like_struct.rb"
+
+require_relative "../types.rb"
+require_relative "../base_struct.rb"
+
+module CustomElementsManifestParser
+  module Nodes
+    # A description of a class mixin.
+    #
+    # Mixins are functions which generate a new subclass of a given superclass.
+    # This interfaces describes the class and custom element features that
+    # are added by the mixin. As such, it extends the CustomElement interface and
+    # ClassLike interface.
+    #
+    # Since mixins are functions, it also extends the FunctionLike interface. This
+    # means a mixin is callable, and has parameters and a return type.
+    #
+    # The return type is often hard or impossible to accurately describe in type
+    # systems like TypeScript. It requires generics and an `extends` operator
+    # that TypeScript lacks. Therefore it's recommended that the return type is
+    # left empty. The most common form of a mixin function takes a single
+    # argument, so consumers of this interface should assume that the return type
+    # is the single argument subclassed by this declaration.
+    #
+    # A mixin should not have a superclass. If a mixins composes other mixins,
+    # they should be listed in the `mixins` field.
+    #
+    # See <https://justinfagnani.com/2015/12/21/real-mixins-with-javascript-classes/>
+    # for more information on the classmixin pattern in JavaScript.
+    #
+    # This JavaScript mixin declaration:
+    # ```javascript
+    # const MyMixin = (base) => class extends base {
+    #   foo() { ... }
+    # }
+    # ```
+    #
+    # Is described by this JSON:
+    # ```json
+    # {
+    #   "kind": "mixin",
+    #   "name": "MyMixin",
+    #   "parameters": [
+    #     {
+    #       "name": "base",
+    #     }
+    #   ],
+    #   "members": [
+    #     {
+    #       "kind": "method",
+    #       "name": "foo",
+    #     }
+    #   ]
+    # }
+    # ```
+    class MixinDeclaration < BaseStruct
+      # @!parse Structs::CustomElementLikeStruct
+      attributes_from Structs::CustomElementLikeStruct
+
+      # @!parse Structs::FunctionLikeStruct
+      Structs::FunctionLikeStruct.schema.each do |attr|
+        names = Structs::CustomElementLikeStruct.schema.keys.map { |obj| obj.name }
+
+        next if names.include?(attr.name)
+
+        attribute attr.name, attr.type
+      end
+
+      attributes_from Structs::DeclarableNodeStruct
+
+      # @!attribute kind
+      #    @return ["mixin"]
+      attribute :kind, Types.Value("mixin")
+
+      # @return ["mixin"]
+      def self.kind; 'mixin'; end
+
+      def visit(parser:)
+        hash = {}
+
+        hash = hash.merge(
+          # Structs::FunctionLikeStruct.build_hash(parser: parser, struct: self),
+          Structs::CustomElementLikeStruct.build_hash(parser: parser, struct: self),
+          Structs::DeclarableNodeStruct.build_hash(parser: parser, struct: self),
+        )
+
+        new(hash)
+      end
+    end
+  end
+end

data/lib/custom_elements_manifest_parser/nodes/variable_declaration.rb

@@ -0,0 +1,41 @@
+require_relative "../structs/declarable_node_struct.rb"
+require_relative "../structs/property_like_struct.rb"
+
+require_relative "../base_struct.rb"
+require_relative "../types.rb"
+
+module CustomElementsManifestParser
+  module Nodes
+    # Documents a variable
+    class VariableDeclaration < BaseStruct
+      # @!parse include Structs::DeclarableNodeStruct
+      attributes_from Structs::DeclarableNodeStruct
+
+      # @!parse include Structs::PropertyLikeStruct
+      attributes_from Structs::PropertyLikeStruct
+
+      # @return ["variable"]
+      def self.kind; "variable"; end
+
+      # @!attribute kind
+      #   @return ["variable"]
+      attribute :kind, Types.Value("variable")
+
+      # @!attribute source
+      #   @return [Nodes::SourceReference, nil]
+      attribute :source, Types::Nominal::Any.optional.meta(required: false)
+
+      def visit(parser:)
+        hash = {}
+        hash[:source] = parser.data_types[:source].new(source).visit(parser: parser) unless source.nil?
+
+        hash = hash.merge(
+          Structs::DeclarableNodeStruct.build_hash(parser: parser, struct: self),
+          Structs::PropertyLikeStruct.build_hash(parser: parser, struct: self),
+        )
+
+        new(hash)
+      end
+    end
+  end
+end

data/lib/custom_elements_manifest_parser/parser.rb

@@ -0,0 +1,111 @@
+require_relative "./base_struct.rb"
+require_relative "./types.rb"
+
+module CustomElementsManifestParser
+  Dir["#{__dir__}/**/*.rb"].each { |file| require_relative file if file != __FILE__ }
+
+  # Top level interface that users will interact with when reading custom elements JSON.
+  # @example
+  #   ::CustomElementsManifestParser::Parser.new(JSON.parse("custom-elements.json"))
+  #
+  class Parser
+    attr_accessor :visitable_nodes, :manifest, :data_types
+
+    # @param hash [Hash{String => any}]
+    def initialize(hash)
+      type_check = Types::Strict::Hash
+      type_check[hash]
+
+      @visitable_nodes = {}
+      @visitable_nodes[Nodes::JavaScriptModule.kind] = Nodes::JavaScriptModule
+      @visitable_nodes[Nodes::CustomElementField.kind] = Nodes::CustomElementField
+      @visitable_nodes[Nodes::JavaScriptExport.kind] = Nodes::JavaScriptExport
+      @visitable_nodes[Nodes::CustomElementExport.kind] = Nodes::CustomElementExport
+      @visitable_nodes[Nodes::ClassMethod.kind] = Nodes::ClassMethod
+
+      # Top level declarations
+      @visitable_nodes[Nodes::ClassDeclaration.kind] = Nodes::ClassDeclaration
+      @visitable_nodes[Nodes::FunctionDeclaration.kind] = Nodes::FunctionDeclaration
+      @visitable_nodes[Nodes::VariableDeclaration.kind] = Nodes::VariableDeclaration
+
+      ## This is equivalent to MixinDeclaration | CustomElementDeclaration | CustomElementMixinDeclaration;
+      @visitable_nodes[Nodes::MixinDeclaration.kind] = Nodes::MixinDeclaration
+
+      # data_types are different from @visitable_nodes. They serialize data, but do not represent a physical node in the Custom Elements JSON.
+      @data_types = {
+        attribute: DataTypes::Attribute,
+        css_part: DataTypes::CssPart,
+        css_custom_property: DataTypes::CssCustomProperty,
+        demo: DataTypes::Demo,
+        declaration: DataTypes::Reference,
+        event: DataTypes::Event,
+        function_return_type: DataTypes::FunctionReturnType,
+        mixin: DataTypes::Reference,
+        parameter: DataTypes::Parameter,
+        superclass: DataTypes::Reference,
+        source: DataTypes::SourceReference,
+        slot: DataTypes::Slot,
+        type: DataTypes::Type,
+        type_reference: DataTypes::TypeReference,
+        inheritedFrom: DataTypes::Reference,
+        resolve_initializer: DataTypes::ResolveInitializer,
+        reference: DataTypes::Reference
+      }
+
+      # @return [Nodes::Manifest]
+      @manifest = Nodes::Manifest.new(hash)
+    end
+
+    # Builds the fully parsed tree
+    # @return [Parser]
+    def parse
+      @manifest = manifest.visit(parser: self)
+      self
+    end
+
+    # def array_fields
+    #   [
+    #     "declarations",
+    #     "exports",
+    #     "members",
+    #     "mixins",
+    #     "attributes",
+    #     "events",
+    #     "slots",
+    #     "cssParts",
+    #     "cssProperties",
+    #     "demos",
+    #     "parameters",
+    #     "references",
+    #     "modules",
+    #   ]
+    # end
+
+    # Hash{String, symbol => unknown}
+    def visit_node(node)
+      kind = node["kind"] || node[:kind]
+      @visitable_nodes[kind].new(node).visit(parser: self)
+    end
+
+    def find_custom_elements(tag_names = [])
+      custom_elements = []
+
+      manifest.modules.flatten.each do |mod|
+        mod.declarations.flatten.each do |dec|
+          next if dec.attributes[:customElement] != true
+
+          if tag_names.empty?
+            custom_elements << dec
+            next
+          end
+
+          if tag_names.include?(dec.attributes[:tagName])
+            custom_elements << dec
+          end
+        end
+      end
+
+      custom_elements
+    end
+  end
+end

data/lib/custom_elements_manifest_parser/structs/class_like_struct.rb

@@ -0,0 +1,92 @@
+require_relative "../types.rb"
+require_relative "../base_struct.rb"
+
+module CustomElementsManifestParser
+  module Structs
+    # The common interface of classes and mixins.
+    class ClassLikeStruct < BaseStruct
+      # @!attribute name
+      #    @return [String] - Name of the class
+      attribute :name, Types::Strict::String
+
+      # @!attribute summary
+      #   @return [String, nil] - A markdown summary suitable for display in a listing.
+      attribute :summary, Types::Strict::String.optional.meta(required: false)
+
+      # @!attribute description
+      #   @return [String, nil] - A markdown description of the class.
+      attribute :description, Types::Strict::String.optional.meta(required: false)
+
+      # @!attribute superclass
+      #   @return [Reference, nil] -
+      #     The superclass of this class.
+      #
+      #     If this class is defined with mixin applications, the prototype chain
+      #     includes the mixin applications and the true superclass is computed
+      #     from them.
+      #
+      #     Any class mixins applied in the extends clause of this class.
+      attribute :superclass, Types::Nominal::Any.optional.meta(required: false)
+
+      # @param mixins [Array<Reference>, nil] -
+      #   If mixins are applied in the class definition, then the true superclass
+      #   of this class is the result of applying mixins in order to the superclass.
+      #
+      #   Mixins must be listed in order of their application to the superclass or
+      #   previous mixin application. This means that the innermost mixin is listed
+      #   first. This may read backwards from the common order in JavaScript, but
+      #   matches the order of language used to describe mixin application, like
+      #   "S with A, B".
+      #
+      #   @example
+      #
+      #   ```javascript
+      #   class T extends B(A(S)) {}
+      #   ```
+      #
+      #   is described by:
+      #   ```json
+      #   {
+      #     "kind": "class",
+      #     "superclass": {
+      #       "name": "S"
+      #     },
+      #     "mixins": [
+      #       {
+      #         "name": "A"
+      #       },
+      #       {
+      #         "name": "B"
+      #       },
+      #     ]
+      #   }
+      #   ```
+      #
+      attribute :mixins, Types::Strict::Array.optional.meta(required: false)
+
+      # @!attribute members
+      #   @return [Array<ClassField, ClassMethod>, nil]
+      attribute :members, Types::Strict::Array.optional.meta(required: false)
+
+      # @!attribute source
+      #   @return [SourceReference, nil]
+      attribute :source, Types::Nominal::Any.optional.meta(required: false)
+
+      # @!attribute deprecated
+      #   @return [nil, boolean, string]
+      #     Whether the class or mixin is deprecated.
+      #     If the value is a string, it's the reason for the deprecation.
+      attribute :deprecated, Types::Strict::Bool | Types::Strict::String.optional.meta(required: false)
+
+      def self.build_hash(parser:, struct:)
+        hash = {}
+        hash[:superclass] = struct.parser.data_types[:superclass].new(superclass).visit(parser: parser) unless struct.superclass.nil?
+        hash[:mixins] = struct.mixins.map { |mixin| parser.data_types[:mixin].new(mixin).visit(parser: parser) } unless struct.mixins.nil?
+        hash[:source] = struct.parser.data_types[:source].new(source).visit(parser: parser) unless struct.source.nil?
+
+        hash[:members] = struct.members.map { |member| parser.visit_node(member) } unless struct.members.nil?
+        hash
+      end
+    end
+  end
+end

data/lib/custom_elements_manifest_parser/structs/custom_element_like_struct.rb

@@ -0,0 +1,64 @@
+require_relative "./class_like_struct.rb"
+require_relative "../types.rb"
+
+module CustomElementsManifestParser
+  module Structs
+    # The additional fields that a custom element adds to classes and mixins.
+    class CustomElementLikeStruct < BaseStruct
+      # @!parse include Structs::ClassLikeStruct
+      attributes_from ClassLikeStruct
+
+      # @!attribute customElement
+      #   @return [True] - Distinguishes a regular JavaScript class from a custom element class
+      attribute :customElement, Types::Strict::True
+
+      # @!attribute tagName
+      #   @return [String, nil] -
+      #     An optional tag name that should be specified if this is a
+      #     self-registering element.
+      #
+      #     Self-registering elements must also include a CustomElementExport
+      #     in the module's exports.
+      attribute :tagName, Types::Strict::String.optional.meta(required: false)
+
+      # @!attribute attributes
+      #   @return [Array<Attribute>, nil] - The attributes that this element is known to understand.
+      attribute :attributes, Types::Strict::Array.optional.meta(required: false)
+
+      # @param demos [Array<Demo>, nil]
+      attribute :demos, Types::Strict::Array.optional.meta(required: false)
+
+      # @!attribute cssProperties
+      #    @return [Array<CssCustomProperty>, nil]
+      attribute :cssProperties, Types::Strict::Array.optional.meta(required: false)
+
+      # @!attribute cssParts
+      #    @return [Array<CssPart>, nil] - Array of CSS Parts
+      attribute :cssParts, Types::Strict::Array.optional.meta(required: false)
+
+      # @!attribute slots
+      #    @return [Array<Slot>, nil] - The shadow dom content slots that this element accepts.
+      attribute :slots, Types::Strict::Array.optional.meta(required: false)
+
+      # @!attribute events
+      #    @return [Array<Event>, nil] - The events that this element fires.
+      attribute :events, Types::Strict::Array.optional.meta(required: false)
+
+      def self.build_hash(parser:, struct:)
+        hash = {}
+
+        # This is a special case because DryStruct reserves the `attributes` namespace.
+        hash[:attributes] = struct.attributes[:attributes].map { |attr| parser.data_types[:attribute].new(attr).visit(parser: parser) } unless struct.attributes[:attributes].nil?
+
+        hash[:cssProperties] = struct.cssProperties.map { |css_custom_property| parser.data_types[:css_custom_property].new(css_custom_property).visit(parser: parser) } unless struct.cssProperties.nil?
+
+        hash[:cssParts] = struct.cssParts.map { |css_part| parser.data_types[:css_part].new(css_part).visit(parser: parser) } unless struct.cssParts.nil?
+        hash[:demos] = struct.demos.map { |demo| parser.data_types[:demo].new(demo).visit(parser: parser) } unless struct.demos.nil?
+        hash[:slots] = struct.slots.map { |slot| parser.data_types[:slot].new(slot).visit(parser: parser) } unless struct.slots.nil?
+        hash[:events] = struct.events.map { |event| parser.data_types[:event].new(event).visit(parser: parser) } unless struct.events.nil?
+
+        hash
+      end
+    end
+  end
+end

data/lib/custom_elements_manifest_parser/structs/declarable_node_struct.rb

@@ -0,0 +1,19 @@
+require_relative "../types.rb"
+require_relative "../base_struct.rb"
+
+# DeclarableNode is a Node that has a parent JavaScript module.
+module CustomElementsManifestParser
+  module Structs
+    class DeclarableNodeStruct < BaseStruct
+      # @!attribute parent_module
+      #   @return [JavaScriptModule, nil] -
+      #     A convenience helper so you don't need to manually traverse the manifest and always go top -> bottom.
+      #     By using this you can grab the "path" and "exports" of a custom element.
+      attribute :parent_module, Types::Nominal::Any.optional.meta(required: false)
+
+      def self.build_hash(parser:, struct:)
+        {}
+      end
+    end
+  end
+end

data/lib/custom_elements_manifest_parser/structs/function_like_struct.rb

@@ -0,0 +1,40 @@
+require_relative "../types.rb"
+require_relative "../base_struct.rb"
+
+module CustomElementsManifestParser
+  module Structs
+    # An interface for functions / methods.
+    class FunctionLikeStruct < BaseStruct
+      # @!attribute name
+      #    @return [String, nil] - Name of the function
+      attribute :name, Types::Strict::String.optional.meta(required: false)
+
+      # @!attribute summary
+      #   @return [String, nil] - A markdown summary suitable for display in a listing.
+      attribute :summary, Types::Strict::String.optional.meta(required: false)
+
+      # @!attribute description
+      #    @return [String, nil] - A markdown description.
+      attribute :description, Types::Strict::String.optional.meta(required: false)
+
+      # @!attribute deprecated
+      #   @return [Boolean, String, nil]
+      #     Whether the function is deprecated.
+      #     If the value is a string, it's the reason for the deprecation.
+      attribute :deprecated, Types::Strict::String.optional | Types::Strict::Bool.optional.meta(required: false)
+
+      # @param parameters [nil, Array<Parameter>]
+      attribute :parameters, Types::Strict::Array.optional | Types::Strict::Nil.optional.meta(required: false)
+
+      # @param return [nil, FunctionReturnType]
+      attribute :return, Types::Nominal::Any.optional.meta(required: false)
+
+      def self.build_hash(parser:, struct:)
+        hash = {}
+        hash[:parameters] = struct.parameters.map { |parameter| parser.data_types[:parameter].new(parameter).visit(parser: parser) } if struct.parameters
+        hash[:return] = parser.data_types[:function_return_type].new(struct.return).visit(parser: parser) if struct.return
+        hash
+      end
+    end
+  end
+end

data/lib/custom_elements_manifest_parser/structs/property_like_struct.rb

@@ -0,0 +1,47 @@
+require_relative "../types.rb"
+require_relative "../base_struct.rb"
+
+module CustomElementsManifestParser
+  module Structs
+    # The common interface of variables, class fields, and function
+    # parameters.
+    class PropertyLikeStruct < BaseStruct
+      # @!attribute name
+      #   @return [String] - Name of the property
+      attribute :name, Types::Strict::String
+
+      # @!attribute summary
+      #    @return [String, nil] - A markdown summary suitable for display in a listing.
+      attribute :summary, Types::Strict::String.optional.meta(required: false)
+
+      # @!attribute description
+      #   @return [String, nil] - A markdown description of the field.
+      attribute :description, Types::Strict::String.optional.meta(required: false)
+
+      # @!attribute type
+      #   @return [nil, Type] - The type serializer IE: "Object", "String", etc.
+      attribute :type, Types::Nominal::Any.optional.meta(required: false)
+
+      # @!attribute default
+      #    @return [String, nil] - Default value
+      attribute :default, Types::Strict::String.optional.meta(required: false)
+
+      # @!attribute deprecated
+      #   @return [nil, Boolean, String] -
+      #     Whether the property is deprecated.
+      #     If the value is a string, it's the reason for the deprecation.
+      attribute :deprecated, Types::Strict::Bool.optional | Types::Strict::String.optional.meta(required: false)
+
+      # @!attribute readonly
+      #   @return [nil, Boolean] - Whether the property is read-only.
+      attribute :readonly, Types::Strict::Bool.optional.meta(required: false)
+
+      def self.build_hash(parser:, struct:)
+        hash = {}
+        hash[:type] = parser.data_types[:type].new(struct.type).visit(parser: parser) if struct.type
+        hash
+      end
+    end
+  end
+end
+

data/lib/custom_elements_manifest_parser/types.rb

@@ -0,0 +1,13 @@
+require "dry-types"
+
+module CustomElementsManifestParser
+  # Dry types
+  module Types
+    include Dry.Types
+
+    # @return [Types::String.enum("private", "protected", "public"]
+    def self.privacy
+      Types::String.enum("private", "protected", "public")
+    end
+  end
+end

data/lib/custom_elements_manifest_parser/version.rb

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

data/lib/custom_elements_manifest_parser.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+#
+# Top level parser
+module CustomElementsManifestParser
+  Dir["#{__dir__}/custom_elements_manifest_parser/**/*.rb"].each { |file| require file }
+
+  # Shortuct for `CustomElementsManifestParser::Parser.new().parse()`
+  def self.parse(hash)
+    Parser.new(hash).parse
+  end
+end

data/sig/custom_elements_manifest_parser.rbs

@@ -0,0 +1,4 @@
+module CustomElementsManifestParser
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end