openproject-primer_view_components 0.6.3

data/previews/pages/forms/01_introduction.md.erb

@@ -0,0 +1,44 @@
+---
+title: "Introduction"
+id: introduction
+---
+
+Primer contains a framework for declaratively building Rails forms. It was designed to meet the following goals:
+
+1. Be accessible by default.
+1. Integrate deeply with Ruby on Rails and its existing form capabilities.
+1. Follow web standards.
+1. Adhere to Primer's [form interface guidelines](/design/ui-patterns/forms).
+
+### Accessible by default
+
+Creating accessible forms can be challenging. Forms are a common source of accessibility issues, and can hinder someone from successfully completing and submitting a form. This can be true even for people who do not use assistive technologies.
+
+Primer forms are designed to be accessible by default - i.e. accessible without developer effort - borrowing from Rails' sane defaults philosophy.
+
+For example, Primer forms:
+
+1. Automatically associate labels, captions, and validation messages with their inputs.
+1. Use `<fieldset>`s where appropriate.
+1. Focus the first invalid input after submission.
+
+And more!
+
+### Integrates with Rails
+
+Primer forms augment Rails' battle-tested form capabilties, allowing developers to leverage their existing Rails knowledge. Primer forms delegate HTML generation to Rails, meaning inputs accept the same arguments as their vanilla Rails counterparts. For example, Primer's `#text_field` method accepts all the arguments Rails' `#text_field_tag` method accepts.
+
+Primer forms are emitted using the familiar `#render` method, and wrapped using `#primer_form_with`, analogous to Rails' `#form_with`.
+
+### Follows web standards
+
+Under the hood, Primer forms are just HTML with some JavaScript sprinkles. Nothing too fancy, meaning they should work pretty much everywhere.
+
+### What to read next
+
+1. Read the getting started guide.
+1. Take a look at the various form inputs.
+1. Explore form layout options.
+1. Compose forms together.
+1. Include custom validation messages.
+1. Submit boolean values immediately with toggle switch forms.

data/previews/pages/forms/02_getting_started.md.erb

@@ -0,0 +1,125 @@
+---
+title: "Getting started"
+id: getting_started
+---
+
+A number of the concepts in Primer Forms are borrowed from the [view_component](https://viewcomponent.org) framework. For example, forms are defined inside Ruby classes and rendered using the `#render` method.
+
+Let's create a sign up form and render it on the page.
+
+## Example for the impatient
+
+<%= code :ruby do %>
+  class SignUpForm < ApplicationForm
+    form do |sign_up_form|
+      sign_up_form.group(layout: :horizontal) do |name_group|
+        name_group.text_field(
+          name: :first_name,
+          label: "First name",
+          required: true,
+          caption: "What your friends call you."
+        )
+
+        name_group.text_field(
+          name: :last_name,
+          label: "Last name",
+          required: true,
+          caption: "What the principal calls you."
+        )
+      end
+
+      sign_up_form.text_field(
+        name: :dietary_restrictions,
+        label: "Dietary restrictions",
+        caption: "Any allergies?"
+      )
+
+      if @show_notifications_checkbox
+        sign_up_form.check_box(
+          name: :email_notifications,
+          label: "Send me gobs of email!",
+          caption: "Check this if you enjoy getting spam."
+        )
+      end
+
+      sign_up_form.submit(label: "Submit")
+    end
+
+    def initialize(show_notifications_checkbox: true)
+      @show_notifications_checkbox = show_notifications_checkbox
+    end
+  end
+<% end %>
+
+## Directory structure
+
+Autoloading is automatically enabled for any sub-directory inside a Rails' app's app/ directory. Accordingly, we recommend placing all form classes inside app/forms/.
+
+The directory structure within app/forms/ is arbitrary, but we have seen success using the same directory structure as app/controllers/. For example:
+
+```
+app
+  ╵─ controllers
+     ╵─ settings
+        ╵─ email_notifications_controller.rb
+  ╵─ forms
+     ╵─ settings
+        ╵─ email_notifications
+           ╵─ config_form.rb
+```
+
+## `ApplicationForm`
+
+Our example class above inherits from `ApplicationForm`. This follows the Rails convention of a base class that houses application-specific logic common to all forms. It's similar in purpose to `ApplicationRecord` and `ApplicationController`.
+
+Ultimately, forms must inherit from `Primer::Forms::Base`, meaning `ApplicationForm` can be as simple as:
+
+<%= code :ruby do %>
+  class ApplicationForm < Primer::Forms::Base
+    # empty body, add common methods, includes, etc here
+  end
+<% end %>
+
+Place `ApplicationForm` in app/forms/application_form.rb
+
+## Anatomy of a form
+
+Forms are just Ruby classes that inherit from `Primer::Forms::Base`. Define a form's inputs using the `form` class method, which accepts a block. The block is called with an instance of `Primer::Forms::Dsl::FormObject`, which responds to the following form input methods:
+
+* [`text_field`](<%= page_path(:text_field_input) %>): Text input field.
+* [`text_area`](<%= page_path(:text_area_input) %>): Text area field (multi-line).
+* [`select_list`](<%= page_path(:select_list_input) %>): Drop-down select list.
+* [`check_box`](<%= page_path(:check_box_input) %>): Single check box.
+* [`check_box_group`](<%= page_path(:check_box_group_input) %>): Group of related check boxes.
+* [`radio_button_group`](<%= page_path(:radio_button_group_input) %>): Group of related radio buttons.
+* [`hidden`](<%= page_path(:miscellaneous_inputs) %>): Hidden input.
+* [`multi`](<%= page_path(:multi_input) %>): Multi input (multiple fields that look like a single field).
+* [`submit`](<%= page_path(:submit_button_input) %>): Submit button.
+* [`button`](<%= page_path(:form_button_input) %>): Regular, non-submit button.
+* [`separator`](<%= page_path(:miscellaneous_inputs) %>): Horizontal separator.
+* [`fields_for`](<%= page_path(:compound_forms) %>): Used for composing forms together.
+
+## Rendering
+
+Forms are rendered using the familiar Rails `#render` method:
+
+<%= code :erb do %>
+  <%%= primer_form_with(model: @user) do |f| %>
+    <%%= render SignUpForm.new(f, show_notifications_checkbox: false) %>
+  <%% end %>
+<% end %>
+
+## The `primer_form_with` helper
+
+You may have noticed the use of the `primer_form_with` helper above. This helper is analogous to Rails' `form_with` helper, but layers on some additional functionality. It automatically:
+
+1. configures the form to use Primer's form builder
+1. disables Rails' default error markup functionality, which breaks Primer styling
+1. forces labels to always identify their inputs via the `for` attribute
+1. enables the special handling of `system_arguments` that allows for utility arguments like `ml: 2` and friends
+
+It is recommended to always use `primer_form_with` instead of `form_with`.
+
+## The `primer_form_for` helper
+
+Before the introduction of `#form_with` in Rails 5.1, forms were created using the `#form_for` helper. Although `#form_for` has since been soft-deprecated, Primer includes the analogous `#primer_form_for` for completeness. Prefer `#primer_form_with` for new forms.

data/previews/pages/forms/03_caption_templates.md.erb

@@ -0,0 +1,30 @@
+---
+title: "Caption templates"
+id: caption_templates
+---
+
+All inputs support the `caption:` argument as a string, which renders explainer text underneath the input and validation message. Caption strings can be anything that responds to `#to_s`, meaning HTML-safe strings can be used in cases that need a little bit of markup:
+
+<%= code :ruby do %>
+  class ExampleForm < ApplicationForm
+    form do |example_form|
+      example_form.text_field(
+        name: :disco_name,
+        label: "Disco name",
+        caption: "Enter your <strong>grooviest</strong> name".html_safe
+      )
+    end
+  end
+<% end %>
+
+## Defining caption templates
+
+In cases where a lot of logic or markup is necessary, or where the caption text is awkward to express in Ruby code, forms may define caption content in separate template files. Caption templates are located in a directory named after the form. For example, if `ExampleForm` lives in app/forms/example\_form.rb, its caption templates should be created in the `app/forms/example_form/` directory.
+
+Caption template files must be named after the field they describe. For example, a caption template for the `disco_name` field above would live in app/forms/example\_form/disco\_name_caption.html.erb.
+
+In cases where the `caption:` argument _and_ a caption template are provided, the `caption:` argument takes precedence.
+
+## Example
+
+<%= embed Primer::FormsPreview, :caption_template_form %>

data/previews/pages/forms/04_after_content.md.erb

@@ -0,0 +1,39 @@
+---
+title: '"After" content'
+id: after_content
+---
+
+Primer forms is designed to be accessible by default. In service of this goal, the framework intentionally limits the types of inputs, layout styles, etc that may be used to build a form. For example, consider rendering a hidden component like a dialog or tooltip that appears when a form input is hovered or clicked. Normally these hidden elements can only be rendered _outside_ the form. The hidden elements don't "travel" with the form and can be easily forgotten.
+
+For such cases, Primer forms feature "after" content. Like [caption templates](<%= page_path(:caption_templates) %>), after content lives in a directory named after the form, specifically in a file called after\_content.html.erb. If present, after\_content.html.erb is rendered after the last form input.
+
+## Usage
+
+<%= code :ruby do %>
+  # app/forms/example_form.rb
+  class ExampleForm < ApplicationForm
+    form do |example_form|
+      example_form.text_field(
+        name: :name,
+        label: "Name",
+        id: "my-text-field"
+      )
+    end
+  end
+<% end %>
+
+<%= code :erb do %>
+  <%%# app/forms/example_form/after_content.html.erb %>
+  <%%= render(
+    Primer::Alpha::Tooltip.new(
+      for_id: "my-text-field",
+      type: :description,
+      text: "Some tooltip text",
+      direction: :ne
+    )
+  ) %>
+<% end %>
+
+## Example
+
+<%= embed Primer::FormsPreview, :after_content_form %>

data/previews/pages/forms/05_groups_layouts.md.erb

@@ -0,0 +1,22 @@
+---
+title: "Groups and layouts"
+label: "Groups and Layouts"
+id: groups_layouts
+---
+
+By default, forms are oriented vertically. In other words, inputs are rendered from top to bottom in the order they are defined. Rendering inputs this way is generally more accessible than rendering inputs side-by-side, and should be preferred for most use-cases.
+
+However in certain circumstances it may be appropriate to render groups of inputs horizontally, and Primer forms provides a grouping mechanism for doing so:
+
+<%= code :ruby do %>
+  class ExampleForm < ApplicationForm
+    form do |example_form|
+      example_form.group(layout: :horizontal) do |name_group|
+        name_group.text_field(name: :first_name, label: "First name")
+        name_group.text_field(name: :last_name, label: "Last name")
+      end
+    end
+  end
+<% end %>
+
+The `layout:` argument also accepts a `:vertical` option, which is the default.

data/previews/pages/forms/06_miscellaneous_inputs.md.erb

@@ -0,0 +1,43 @@
+---
+title: "Miscellaneous inputs"
+label: "Miscellaneous Inputs"
+id: miscellaneous_inputs
+---
+
+Aside from the set of component-based form inputs, Primer forms also features several additional inputs.
+
+## Hidden inputs
+
+Primer supports standard hidden HTML inputs, eg. `<input type="hidden">`, via the `#hidden` method.
+
+### Usage
+
+<%= code :ruby do %>
+  class ExampleForm < ApplicationForm
+    form do |example_form|
+      example_form.hidden(arguments)
+    end
+  end
+<% end %>
+
+`#hidden` is a thin wrapper around Rails' [`hidden_field` method](https://api.rubyonrails.org/classes/ActionView/Helpers/FormBuilder.html#method-i-hidden_field) and accepts the same arguments.
+
+## Separators
+
+Occasionally it can be appealing to visually distinguish parts of a form from each other. The `#separator` method adds a horizontal rule between inputs.
+
+### Usage
+
+<%= code :ruby do %>
+  class ExampleForm < ApplicationForm
+    form do |example_form|
+      example_form.separator
+    end
+  end
+<% end %>
+
+`#separator` does not accept any arguments.
+
+### Example
+
+<%= embed Primer::FormsPreview, :multi_text_field_form %>

data/previews/pages/forms/07_toggle_switch_forms.md.erb

@@ -0,0 +1,58 @@
+---
+title: "Toggle switch forms"
+label: "Toggle Switch Forms"
+id: toggle_switch_forms
+---
+
+The Primer toggle switch component is designed to immediately submit a true/false value to the server when toggled. The forms framework adds a label, caption, and validation message to the stock toggle switch in keeping with the other inputs in the framework. However, toggle switches cannot be added to forms directly. Instead, toggle switch forms are their own complete, standalone forms.
+
+Toggle switches make POST requests to the configured URL (the `src` argument).
+
+## Creating toggle switch forms
+
+Toggle switch forms can be defined in one of two ways: either by creating an instance of the `Primer::Forms::ToggleSwitchForm` class or by inheriting from it.
+
+### Instance
+
+<%= code :erb do %>
+  <%% render(Primer::Forms::ToggleSwitchForm.new(arguments)) %>
+<% end %>
+
+### Inheritance
+
+Define the form:
+
+<%= code :ruby do %>
+  # app/forms/my_toggle_form.rb
+  class MyToggleForm < Primer::Forms::ToggleSwitchForm
+    def initialize(**system_arguments)
+      super(arguments, **system_arguments)
+    end
+  end
+<% end %>
+
+Render the form:
+
+<%= code :erb do %>
+  <%%# app/views/some_controller/some_view.html.erb %>
+  <%% render(MyToggleForm.new) %>
+<% end %>
+
+## Arguments
+
+| Name | Type | Default | Description |
+| :- | :- | :- | :- |
+|`name`|String||The name of the input, used to associate the toggle switch with its label.|
+|`label`|String||Label text displayed adjacent to the input.|
+|`src`|String||The URL to submit toggle POST requests to.|
+|`csrf`|String||A CSRF token to submit along with the toggle value. If no value is provided, a CSRF token is automatically generated via Rails' [`form_authenticity_token` method](https://api.rubyonrails.org/v7.0/classes/ActionController/RequestForgeryProtection.html#method-i-form_authenticity_token)|
+|`hidden`|Boolean||When set to `true`, visually hides the form.|
+|`label_arguments`|Hash||Attributes that will be passed to Rails' `builder.label` method. These can be HTML attributes or any of the other label options Rails supports. They will appear as HTML attributes on the `<label>` tag.|
+
+## Error messages
+
+The server can indicate that an error occurred by responding with a non-2xx status code to toggle switch POST requests. In such a scenario, the response body will be used to populate the toggle switch form's validation message, and will cause a red warning icon to appear next to the switch.
+
+## Example
+
+<%= embed Primer::FormsPreview, :example_toggle_switch_form %>

data/previews/pages/forms/08_validations.md.erb

@@ -0,0 +1,28 @@
+---
+title: "Validations"
+id: validations
+---
+
+In Rails, forms usually have an associated model object. Models define validations which include validation messages that describe which validations failed and why. Primer forms automatically display validation messages when a model object is provided.
+
+## Custom validation messages
+
+All form inputs allow overriding the default validation message via the `:validation_message` argument:
+
+<%= code :ruby do %>
+  class ExampleForm < ApplicationForm
+    form do |example_form|
+      example_form.text_field(
+        name: :foo,
+        label: "Foo",
+        validation_message: "Custom validation message"
+      )
+    end
+  end
+<% end %>
+
+A custom validation message is also useful if no associated model object is available, i.e. for forms that are not tied to a database table.
+
+## Input focus
+
+Primer forms will automatically focus the first invalid input in accordance with accessibility best-practices. Inputs are considered invalid if the associated model's field is invalid _or_ if a custom validation message has been provided.

data/previews/pages/forms/09_compound_forms.md.erb

@@ -0,0 +1,97 @@
+---
+title: "Compound forms"
+label: "Compound Forms"
+id: compound_forms
+---
+
+In addition to rendering individual forms, Primer supports combining forms together.
+
+## Form lists
+
+Form lists are arrays of one or more forms. They can be rendered anywhere individual forms can be rendered. Consider this example where the user wants to render two individual forms:
+
+<%= code :erb do %>
+  <%%= primer_form_with(model: Foo.new) do |f| %>
+    <%%= render(FirstForm.new(f)) %>
+    <%%= render(SecondForm.new(f)) %>
+  <%% end %>
+<% end %>
+
+The example above can be re-written using `FormList`:
+
+<%= code :erb do %>
+  <%%= primer_form_with(model: Foo.new) do |f| %>
+    <%%= render(Primer::Forms::FormList.new(FirstForm.new(f), SecondForm.new(f))) %>
+  <%% end %>
+<% end %>
+
+Form lists can come in handy in cases where the framework expects a single form object, such as the nested form option for check boxes and radio buttons:
+
+<%= code :ruby do %>
+  class ExampleForm < ApplicationForm
+    form do |example_form|
+      example_form.check_box(name: :foo, label: "Foo") do |check_box|
+        check_box.nested_form do |builder|
+          Primer::Forms::FormList.new(
+            FirstForm.new(builder),
+            SecondForm.new(builder)
+          )
+        end
+      end
+    end
+  end
+<% end %>
+
+## Associated records
+
+In all the examples above, Primer assumes `FirstForm` and `SecondForm` define inputs that have corresponding fields in the provided model object (an instance of `Foo`). However it's common in Rails to accept nested attributes for an associated model object. For example, a `User` may have a `Profile`. Both are created on signup, so the form should accept both sets of attributes. Rails provides the `fields_for` helper for just this scenario:
+
+<%= code :erb do %>
+  <%%= form_with(model: User.new) do |f| %>
+    <%%= f.text_field :username %>
+    <%%= f.fields_for(:profile) do |f| %>
+      <%%= f.text_field :first_name %>
+      <%%= f.text_field :last_name %>
+    <%% end %>
+  <%% end %>
+<% end %>
+
+Primer forms also support a `#fields_for` method for accomplishing the same goal with form objects. The example above can be rewritten as follows:
+
+<%= code :ruby do %>
+  # app/forms/signup_form.rb
+  class SignupForm < ApplicationForm
+    form do |signup_form|
+      signup_form.text_field(name: :username, label: "Username")
+      signup_form.fields_for(:profile) do |builder|
+        ProfileForm.new(builder)
+      end
+    end
+  end
+<% end %>
+
+<%= code :ruby do %>
+  # app/forms/profile_form.rb
+  class ProfileForm < ApplicationForm
+    form do |profile_form|
+      profile_form.text_field(name: :first_name, label: "First name")
+      profile_form.text_field(name: :last_name, label: "Last name")
+    end
+  end
+<% end %>
+
+## Avoiding attribute nesting
+
+For situations where an association exists between two models, the approach described above works well. However sometimes all you want is to compose two forms together that aren't connected by an association. In such cases the fields will still include the name of the parent model when submitted to the server, eg. `user[profile][first_name]` instead of `profile[first_name]`. To render the form independent of the parent, pass `nested: false` to `fields_for`:
+
+<%= code :ruby do %>
+  # app/forms/signup_form.rb
+  class SignupForm < ApplicationForm
+    form do |signup_form|
+      signup_form.text_field(name: :username, label: "Username")
+      signup_form.fields_for(:profile, nested: false) do |builder|
+        ProfileForm.new(builder)
+      end
+    end
+  end
+<% end %>

data/previews/primer/alpha/action_bar_preview/inline.html.erb

@@ -0,0 +1,16 @@
+
+<%= render(Primer::BaseComponent.new(tag: :div, flex_items: :center, display: :flex)) do %>
+  <%= render(Primer::Beta::Heading.new(tag: :h1, font_size: 3, mr: 2)) { "Title" }%>
+  <%= render(Primer::Alpha::ActionBar.new) do |component| %>
+    <% component.with_item_icon_button(icon: :search, label: "Search") %>
+    <% component.with_item_icon_button(icon: :pencil, label: "Edit") %>
+    <% component.with_item_icon_button(icon: :archive, label: "Archive") %>
+    <% component.with_item_divider %>
+    <% component.with_item_icon_button(icon: :heart, label: "Heart") %>
+    <% component.with_item_icon_button(icon: :bookmark, label: "Bookmark") %>
+    <% component.with_item_icon_button(icon: :mention, label: "Mention") %>
+    <% component.with_item_divider %>
+    <% component.with_item_icon_button(icon: :paperclip, label: "Attach") %>
+  <% end %>
+  <%= render(Primer::Beta::Button.new(scheme: :primary, ml: 2)) { "New Issue"} %>
+<% end %>

data/previews/primer/alpha/action_bar_preview.rb

@@ -0,0 +1,77 @@
+# typed: true
+# frozen_string_literal: true
+
+# Setup Playground to use all available component props
+# Setup Features to use individual component props and combinations
+
+module Primer
+  module Alpha
+    # @label ActionBar
+    class ActionBarPreview < ViewComponent::Preview
+      # @label Default
+      # @snapshot
+      def default
+        render(Primer::Alpha::ActionBar.new) do |component|
+          component.with_item_icon_button(icon: :search, label: "Search")
+          component.with_item_icon_button(icon: :pencil, label: "Edit")
+          component.with_item_icon_button(icon: :archive, label: "Archive")
+          component.with_item_divider
+          component.with_item_icon_button(icon: :heart, label: "Heart")
+          component.with_item_icon_button(icon: :bookmark, label: "Bookmark")
+          component.with_item_icon_button(icon: :mention, label: "Mention")
+          component.with_item_divider
+          component.with_item_icon_button(icon: :paperclip, label: "Attach")
+        end
+      end
+
+      # @label Inline with other components
+      def inline; end
+
+      # @label Playground
+      # @param size [Symbol] select [[Small, small], [Medium, medium], [Large, large]]
+      # @param overflow_menu [Boolean]
+      def playground(size: :medium, overflow_menu: true)
+        render(Primer::Alpha::ActionBar.new(size: size, overflow_menu: overflow_menu)) do |component|
+          component.with_item_icon_button(icon: :search, label: "Search")
+          component.with_item_icon_button(icon: :pencil, label: "Edit")
+          component.with_item_icon_button(icon: :archive, label: "Archive")
+          component.with_item_divider
+          component.with_item_icon_button(icon: :heart, label: "Heart")
+          component.with_item_icon_button(icon: :bookmark, label: "Bookmark")
+          component.with_item_icon_button(icon: :mention, label: "Mention")
+          component.with_item_divider
+          component.with_item_icon_button(icon: :paperclip, label: "Attach")
+        end
+      end
+
+      # @!group sizes
+      def small
+        render(Primer::Alpha::ActionBar.new(size: :small)) do |component|
+          component.with_item_icon_button(icon: :search, label: "Search")
+          component.with_item_icon_button(icon: :pencil, label: "Edit")
+          component.with_item_icon_button(icon: :archive, label: "Archive")
+          component.with_item_divider
+        end
+      end
+
+      def medium
+        render(Primer::Alpha::ActionBar.new(size: :medium)) do |component|
+          component.with_item_icon_button(icon: :search, label: "Search")
+          component.with_item_icon_button(icon: :pencil, label: "Edit")
+          component.with_item_icon_button(icon: :archive, label: "Archive")
+          component.with_item_divider
+        end
+      end
+
+      def large
+        render(Primer::Alpha::ActionBar.new(size: :large)) do |component|
+          component.with_item_icon_button(icon: :search, label: "Search")
+          component.with_item_icon_button(icon: :pencil, label: "Edit")
+          component.with_item_icon_button(icon: :archive, label: "Archive")
+          component.with_item_divider
+        end
+      end
+      # @!endgroup
+    end
+  end
+end