bulma_x 0.2.0

data/README.md

@@ -0,0 +1,315 @@
+- [BulmaX](#bulmax)
+  - [Requirements](#requirements)
+  - [Installation](#installation)
+    - [Example of integration with Rails & Importmap](#rails-importmap)
+  - [Getting started](#getting-started)
+    - [Using BulmaX components](#using-bulmax)
+    - [Components may contains slots](#slots)
+    - [Create your own components](#custom-component)
+  - [Problems ?](#problems)
+  - [Contributing](#contributing)
+  - [Licence](#licence)
+  - [Authors](#authors)
+
+
+<a id="bulmax"></a>
+
+# BulmaX
+
+Generate Bulma CSS components using the power of Phlex.
+
+BulmaX is a Phlex component library that provides a set of components styled with Bulma CSS. It allows you to create responsive and modern web applications using the Bulma framework while leveraging the power of Phlex for building reusable components.
+
+<a id="requirements"></a>
+
+## Features
+
+BulmaX is based on [Phlex](https://github.com/yippee-fun/phlex) which is its only dependency. 
+
+BulmaX's ambition is to expose a DSL as simple as possible and the team will focus on keeping it that way.
+
+We decided to make BulmaX's components deferred by default which makes sure component's markup is rendered in a consistent order.
+
+## Non-features
+
+BulmaX aims only at generating HTML in regard to Bulma's components structure and classes but do not inject any css. All CSS handling is the developer's responsability.
+
+BulmaX is a ruby only framework. There is no Rails integration and it's going to stay that way. We plan to add another interfacing layer BulmaX-rails later.
+
+<a id="requirements"></a>
+
+## Requirements
+
+-   Ruby: 3.4+
+-   Phlex: 2.1+
+
+BulmaX is still in a early stage, feel free to open issues or contributing.
+
+
+<a id="installation"></a>
+
+## Installation
+
+BulmaX only generates the HTML structure of components, adding Bulma CSS to the project is at the developer's discretion.
+
+In your Gemfile:
+
+```rb
+git_source(:gitlab) { |repo| "https://gitlab.com/#{repo}.git" }
+
+gem 'bulma_x', gitlab: 'tftp/open/bulma_x'
+```
+
+Then run
+
+```sh
+bundle install
+```
+
+
+<a id="rails-importmap"></a>
+
+### Example of integration with Rails & Importmap
+
+Using importmap:
+
+```sh
+yarn add bulma
+./bin/importmap pin bulma
+```
+
+then in your application.scss
+
+```scss
+@use "bulma";
+```
+
+
+<a id="getting-started"></a>
+
+## Getting started
+
+
+<a id="using-bulmax"></a>
+
+### Using BulmaX components
+
+The complete list of components can be found below
+
+
+<details>
+<summary>List of components</summary>
+
+```
+  base_component.rb
+  base_input.rb
+  block.rb
+  box.rb
+  breadcrumbs.rb
+  button.rb
+  card.rb
+  checkbox.rb
+  columns.rb
+  component_dsl.rb
+  dropdown.rb
+  field.rb
+  figure.rb
+  file.rb
+  footer.rb
+  form.rb
+  grid.rb
+  help.rb
+  hero.rb
+  icon.rb
+  image.rb
+  input.rb
+  level.rb
+  link.rb
+  media.rb
+  message.rb
+  modal.rb
+  navbar.rb
+  notification.rb
+  pagination.rb
+  panel.rb
+  paragraph.rb
+  progress.rb
+  radio.rb
+  section.rb
+  select.rb
+  shared
+  slot.rb
+  subtitle.rb
+  table.rb
+  tabs.rb
+  tag.rb
+  textarea.rb
+  title.rb
+  version.rb
+  vertical_menu.rb
+```
+
+</details>
+
+An example of section could be as follows:
+
+```erb
+<%= render BulmaX::Section.new(background_color: 'black') do %>
+  <%= render BulmaX::Title.new(text_modifier: 'primary') do %>
+    Section title
+  <% end %>
+
+  <%= render BulmaX::Paragraph.new do %>
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+  <% end %>
+<% end %>
+```
+
+
+<a id="slots"></a>
+
+### Components may contains slots
+
+As Bulma is based on order of classes in the DOM, BulmaX knows where each content should go in advance, but not what they contain. For that, it defines `slot` that you can fill during the rendering of the component.
+
+For example, the `BulmaX::Card` component has a slot for the header and another for the footer. You can use them like this:
+
+```erb
+<%= render BulmaX::Card.new do |card| %>
+  <%= card.content(:header) do |header| %>
+    <%= header.content(:title) do %>
+      Card title
+    <% end %>
+  <% end %>
+
+  <%= card.content(:body) do %>
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+  <% end %>
+
+  <%= card.content(:footer) do |footer| %>
+    <%= footer.content(:item) do %>
+      <%= render BulmaX::Link.new(href: '#') do %>
+        Learn more
+      <% end %>
+    <% end %>
+  <% end %>
+<% end %>
+```
+
+As of today, the best way to know a component's slots is to look at the source code of the component.
+
+<a id="custom-component"></a>
+
+### Create your own components
+
+BulmaX allows you to create new components easily.
+
+Either you can inherits the behaviour of existing components or create your own from scratch.
+
+#### New component based on existing one
+
+```rb
+class TwoColumns < BulmaX::Columns
+  slot :left
+  slot :right
+
+  def view_template
+    super do
+      content(:column) do
+        slot(:left)
+      end if slot?(:left)
+
+      content(:column) do
+        slot(:right)
+      end if slot?(:right)
+    end
+  end
+end
+```
+
+To find a complete reference to BulmaX DSL, until there is a proper documentation you can check for the files in the [dsl](<https://gitlab.com/tftp/open/bulma_x/-/tree/master/lib/bulma_x/dsl>) folder.
+
+#### New component from scratch
+
+When no components fits your needs, you can create a new one from scratch.
+
+BulmaX has a basic component that is the root of all components named `BulmaX::BaseComponent`. It generates a simple div and provides the whole power of BulmaX DSL to it.
+
+```rb
+class SpecificComponent < BulmaX::BaseComponent
+  # => Define your slots
+  # slot :slot_name, classes: ['class1', 'class2'], attributes: { turbo: 'something' }
+  # slot :slot_sub_component, component: 'NameOfSubComponent'
+  # slot :slot_other_component, component: OtherComponentClass
+
+  # => Define your options
+  # option :option # allows anything
+  # option :option_enum, values: [:enum, :value], default: :value
+
+  # => Define your validators
+  # validate :option, -> { it.is_a?(String) }, message: 'Must be a string'
+
+  def prepare
+    # => Prefill your slots if needed
+    #
+    # content(:slot_name) { content }
+    # content(:slot_other_component) do |other_component|
+    #   other_component.content(:slot_name) { content }
+    # end
+  end
+
+  def view_template
+    super do
+      slot(:slot_name) if slot?(:slot_name)
+      slot(:slot_sub_component)
+      slot(:slot_other_component) if slot?(:slot_other_component)
+    end
+  end
+
+  def root_classes
+    super + [
+      @condition && 'custom-class' # => falsy values are removed from the classes
+    ]
+  end
+
+  def root_attributes
+    super.merge(
+      data: {
+        custom: 'value'
+      }
+    )
+  end
+end
+```
+
+
+<a id="problems"></a>
+
+## Problems ?
+
+**Do not directly email any committers with questions or problems**. A community is best served when discussions are held in public.
+
+If you have a problem, please open an issue on the [GitLab project](<https://gitlab.com/tftp/open/bulma_x/-/issues>).
+
+Please note that BulmaX is still in early stages, its documentation is not complete yet and bugs may be present.
+
+
+<a id="contributing"></a>
+
+## Contributing
+
+See the [contributing guidelines](<https://gitlab.com/tftp/open/bulma_x/-/blob/master/CONTRIBUTING.md>) for more information on how to contribute to BulmaX.
+
+
+<a id="licence"></a>
+
+## Licence
+
+See [LICENCE](<https://gitlab.com/tftp/open/bulma_x/-/blob/master/LICENSE>) for more information on the licence of BulmaX.
+
+
+<a id="authors"></a>
+
+## Authors
+
+BulmaX is maintained by [Team for the Planet](<https://team-planet.com/>) and contributors.

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/bulma_x/base_component.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require 'phlex'
+
+module BulmaX
+  class BaseComponent < Phlex::HTML
+    BOOLEAN = [true, false].freeze
+
+    COLORS = %w[primary secondary link info success warning danger text].freeze
+    COLOR_MODIFIER = %w[light dark soft bold on-scheme].freeze
+    COLOR_PALETTE = (0..100).step(5).to_a.map { Kernel.format('%<value>02d', value: _1) }.freeze
+
+    MODIFIERS_PALETTE = COLORS +
+                        COLORS
+                        .product(COLOR_MODIFIER).map { _1.join('-') } +
+                        COLORS
+                        .product(COLOR_PALETTE).map { _1.join('-') } +
+                        COLORS
+                        .product(COLOR_MODIFIER, COLOR_PALETTE)
+                        .map { _1.join('-') } +
+                        [nil] +
+                        COLORS + %w[light dark white black]
+
+    MODIFIERS_DECLINED = COLORS + COLORS.product(COLOR_MODIFIER).map { _1.join('-') } + [nil] + %w[light dark]
+    MODIFIERS = (COLORS + [nil])
+
+    BLANK_VALUES = [nil, false, '', [], {}].freeze
+
+    include ComponentDsl
+    include Shared::TextOptions
+    include Shared::SpacingOptions
+    include Shared::FlexOptions
+    include Shared::DataOptions
+    include Shared::GlobalOptions
+    include Shared::AriaOptions
+
+    spacing_options
+    data_options
+    aria_options
+    global_options
+    text_options
+    flex_options
+
+    root_slot # TODO: Root slot is an old concept that we'd like to remove soon
+
+    def initialize(**, &)
+      super(&)
+
+      build_from_options(**)
+      validate!(**)
+    end
+
+    def view_template(&) = render_root(&)
+
+    def render_root(&)
+      public_send(
+        root_tag,
+        **classes(root_classes),
+        **attributes(**root_attributes)
+      ) do
+        # NOTE: Returning nil in the block may return the generated HTML in some engines
+        # For instance in slim :
+        # = render BulmaX::Block.new do
+        #   = 'void' if false
+        # Will render a block which content is the HTML of the BulmaX::Block
+        # To avoid this, capturing ensure we always return the same thing
+        capture(&) if block_given?
+      end
+    end
+
+    def base_classes
+      [
+        respond_to?(:spacing_classes) && spacing_classes,
+        respond_to?(:text_classes) && text_classes,
+        respond_to?(:flex_classes) && flex_classes,
+        respond_to?(:global_classes) && global_classes
+      ].flatten
+    end
+
+    def base_attributes
+      %i[data_attributes aria_attributes global_attributes].each_with_object({}) do |method, acc|
+        acc.merge!(public_send(method)) if respond_to?(method)
+      end
+    end
+
+    # NOTE: classes will remove all pairs having a falsy value, including false bool. Use "false" string to keep it.
+    def classes(*args)
+      compact_args = compact_blank(args.flatten)
+
+      return {} if compact_args.empty?
+
+      { class: compact_args.join(' ') }
+    end
+
+    # NOTE: attributes will remove all pairs having a falsy value, including false bool. Use "false" string to keep it.
+    def attributes(**kwargs)
+      compact_blank(kwargs)
+    end
+
+    def css(str) = str.to_s.tr('_', '-')
+
+    def compact_blank(obj)
+      case obj
+      when Array
+        obj.reject { BLANK_VALUES.include?(it) }
+      when Hash
+        obj.reject { |_, v| BLANK_VALUES.include?(v) }
+      else
+        obj
+      end
+    end
+
+    if defined?(Rails) && Rails.env.development?
+      def before_template
+        comment { "<#{self.class.name}>".html_safe }
+        super
+      end
+
+      def after_template
+        super
+        comment { "</#{self.class.name}>".html_safe }
+      end
+    end
+  end
+end

data/lib/bulma_x/base_input.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module BulmaX
+  class BaseInput < BaseComponent
+    option :modifier, values: MODIFIERS, default: nil
+    option :size, values: %w[small normal medium large], default: 'normal'
+    option :disabled, values: BOOLEAN, default: false
+    option :readonly, values: BOOLEAN, default: false
+    option :static, values: BOOLEAN, default: false
+    option :html, default: {}
+    option :autofocus, values: BOOLEAN, default: false
+    option :required, values: BOOLEAN, default: false
+
+    root_slot tag: :input
+
+    def root_classes
+      super +
+        [
+          'input',
+          @modifier && "is-#{@modifier}",
+          "is-#{@size}",
+          @disabled && 'is-disabled',
+          @static && 'is-static'
+        ]
+    end
+
+    def root_attributes
+      super.merge(
+        disabled: @disabled,
+        readonly: @readonly || @static,
+        autofocus: @autofocus,
+        required: @required,
+        **@html
+      )
+    end
+  end
+end

data/lib/bulma_x/block.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module BulmaX
+  class Block < BaseComponent
+    root_slot classes: ['block']
+  end
+end

data/lib/bulma_x/box.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module BulmaX
+  class Box < BaseComponent
+    root_slot classes: %w[box]
+  end
+end

data/lib/bulma_x/breadcrumbs.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module BulmaX
+  class Breadcrumbs < BaseComponent
+    root_slot tag: :nav
+
+    option :alignment, values: %i[left centered right], default: :left
+
+    slot :breadcrumbs_ul, tag: :ul
+    slots :item, component: 'Item'
+
+    def view_template
+      super do
+        slot(:breadcrumbs_ul) do
+          slots(:item).each { render it }
+        end
+      end
+    end
+
+    def root_classes
+      super +
+        [
+          'breadcrumb',
+          "is-#{@alignment}"
+        ]
+    end
+
+    class Item < BaseComponent
+      option :current, values: BOOLEAN, default: false
+
+      def root_classes = super + [@current && 'is-active']
+      def root_tag = :li
+    end
+  end
+end

data/lib/bulma_x/button.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module BulmaX
+  class Button < BaseComponent
+    option :kind, values: MODIFIERS, default: :primary
+    option :rounded, values: BOOLEAN, default: false
+    option :type, values: %i[button submit reset], default: :button
+    option :size, values: [nil, :small, :medium, :large], default: nil
+    option :style, values: [nil, :outlined, :inverted, :rounded]
+    option :responsive, values: BOOLEAN, default: false
+    option :disabled, values: BOOLEAN, default: false
+    option :href
+    option :target
+    option :rel
+    option :static, values: BOOLEAN, default: false
+
+    def root_tag = @href ? :a : :button
+
+    def root_classes
+      super +
+        [
+          'button',
+          "is-#{@kind}",
+          @size && "is-#{@size}",
+          @style && "is-#{@style}",
+          @responsive && 'is-responsive',
+          @rounded && 'is-rounded',
+          @static && 'is-static'
+        ]
+    end
+
+    def root_attributes
+      super.merge(
+        href: @href,
+        type: @type,
+        disabled: @disabled,
+        target: @target,
+        rel: @rel
+      )
+    end
+  end
+end

data/lib/bulma_x/card.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module BulmaX
+  class Card < BulmaX::BaseComponent
+    root_slot classes: ['card']
+
+    slot :header, component: 'CardHead'
+    slot :content, component: 'CardContent'
+    slot :footer, component: 'CardFooter'
+
+    def view_template
+      super do
+        slot(:header) if slot?(:header)
+        slot(:content)
+        slot(:footer) if slot?(:footer)
+      end
+    end
+
+    class CardHead < BulmaX::BaseComponent
+      root_slot classes: ['card-header']
+
+      slot :figure, component: BulmaX::Figure
+      slot :image, classes: ['card-image']
+      slot :title, classes: ['card-header-title'], tag: :p
+
+      def view_template
+        super do
+          if slot?(:image)
+            slot(:figure, fullwidth: true, extra_classes: 'card-image', ratio: '16x9') do
+              slot(:image, fullwidth: true)
+            end
+          else
+            slot(:title)
+          end
+        end
+      end
+    end
+
+    class CardContent < BulmaX::BaseComponent
+      root_slot classes: ['card-content']
+    end
+
+    class CardFooter < BulmaX::BaseComponent
+      root_slot classes: ['card-footer']
+
+      slots :item, classes: ['card-footer-item'], tag: :div
+
+      def view_template
+        super do
+          slots(:item).each { render it }
+        end
+      end
+    end
+  end
+end

data/lib/bulma_x/checkbox.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module BulmaX
+  class Checkbox < BaseComponent
+    option :disabled, values: BOOLEAN, default: false
+    option :checked, values: BOOLEAN, default: false
+    option :name
+    option :value
+
+    root_slot tag: :label, classes: ['checkbox']
+
+    def view_template
+      super do
+        render Input.new(**input_attributes)
+
+        yield if block_given?
+      end
+    end
+
+    def root_attributes = super.merge(disabled: @disabled)
+    def input_attributes = { type: 'checkbox', disabled: @disabled, checked: @checked, name: @name, value: @value }
+  end
+end