The current README was generated by rails plugin new, it needs to be replaced with something that:

• provides a brief introduction to the project, scope
• has an install and setup guide
• gives a brief overview of the provided components, we'll probably need more in-depth documentation later, perhaps a generated site like form builder's
• lists alternatives in the same/similar niche (eg. govuk_publishing_components)
• details the licence info
• links to the DfE's code of conduct
• provides guidance on development/contributing

For visibility, @peteryates, @tvararu and I had a discussion on the DfE Slack about the scope for this library.

The consensus (I think) is that this library lives along side other projects that enable developers to build applications using the GOV.UK Design System. For forms, there's govuk_design_system_formbuilder, which means that form elements are out of scope for this gem. We suspect that some GOV.UK Design System components like tables might be too complex to be built nicely using ViewComponent, and would benefit from a custom DSL.

This is a quick list of components and whether or not they're in scope. Feel free to edit & comment.

I've been trying to add govuk-components to another rails service and came across this issue while trying to deploy the app to production. Everything seems to work and run correctly in development. I'm not sure if perhaps its a config setting in the rails app that is making the server fail when it starts up.

DFE-Digital/get-help-with-tech#466 (comment)

@paulrobertlloyd has created a comprehensive list of differences between this library and the Nunjucks macros that are provided by the Design System.

Most of them fall into the categories of renaming arguments to match or adding slots to match the html: behaviour from Nunjucks. The most important ones will be included in version 2.0.0.

It's a bit unexpected that govuk_link_to doesn't take blocks. Ideally the method would behave identically to the underlying link_to.

Example:

<%= govuk_link_to('', some_path) do %>
  Change<span class="govuk-visually-hidden"> Account holder name</span>
<%- end %>

This isn't a show-stopper because this can still be expressed as:

<%= govuk_link_to('Change<span class="govuk-visually-hidden"> Account holder name</span>'.html_safe, some_path) %>

but that's a bit clunkier than it needs to be.

(came up in DFE-Digital/get-help-with-tech#513)

Currently, content provided for the product_description slot gets added as follows:

<div class="govuk-header__logo">
    <a href="/" class="govuk-header__link govuk-header__link--homepage">
        <span class="govuk-header__logotype">
            <svg class="govuk-header__logotype-crown">…</svg>
            <span class="govuk-header__logotype-text">GOV.UK</span>
        </span>
    </a>
    <span class="govuk-header__product-name">Support for Apply</span>
    <strong class="govuk-tag ">Development</strong>
</div>

In practice, it should appear within govuk-header__link:

<div class="govuk-header__logo">
    <a href="/" class="govuk-header__link govuk-header__link--homepage">
        <span class="govuk-header__logotype">
            <svg class="govuk-header__logotype-crown">…</svg>
            <span class="govuk-header__logotype-text">GOV.UK</span>
        </span>
        <span class="govuk-header__product-name">Support for Apply</span>
        <strong class="govuk-tag ">Development</strong>
    </a>
</div>

By not having this content injected in the correct place in the markup, the product name (and any other content) is not linked, and the vertical alignment is also off:

Currently:

Intended:

There’s an undocumented class available to the header navigation which means the navigation list can be aligned to the bottom right on the non-mobile viewports.

Here’s the header without .govuk-header__navigation--end class added:

and with:

Given this option isn’t documented, or appears as an option in GDS’s Nunjucks templates, I’d be templated to enable authors to apply classes to the ul.govuk-header__navigation element, rather than make it a param.

Additionally, on apply we add the govuk-!-display-none-print class to prevent this navigation list from appearing when printed. This further supports the idea that maybe it should be possible to add classes to this element.

Tables might be too complicated to implement using components (#18) as they could potentially need two 'layers' of slots - one for rows and one within it for cells. More investigation is needed

• Is it possible to nest slots? Can we use this technique to build a table?
• Would a 'simple' table component work as an alternative, pass in a array of arrays or array of hashes (like CSV) and it builds a table itself? = govuk_table(@teachers)

Whether panels should contain body content or not is a separate question, but we use the panel component in a few places where we only show a title. Right now the panel component requires a value for body, meaning we need to set a nil value for body in these instances:

<%= govuk_panel(
  title: 'You’ve successfully signed the data sharing agreement',
  body: nil,
) %>

Ideally the body argument (and possibly even the title argument) would be optional.

Morning, I've just tried to use the GovukComponent::NotificationBanner and does not render. The component has the following implementation

  def render?
    headings.any?
  end

To add a heading one would use add_heading but the component is missing

wrap_slot :heading

where wrap_slot

  def self.wrap_slot(name)
    define_method(%(add_#{name})) do |*args, **kwargs, &block|
      self.slot(name, *args, **kwargs, &block)
    end
  end

Is there an alternative way to add headings to this component? Or can wrap_slot be added to the component?

Content areas are now deprecated in view components, and they need to be updated (and replaced with slots)

Only the CookieBanner component uses these currently, so only this component needs updating.

This will be a breaking change for users and should be versioned accordingly.

On the flip side, the current implementation is a breaking change for teams who have upgraded view-component to 2.30.0 and beyond and raise errors on active support deprecation warnings (my team at least) 😂

By adding govuk-!-display-none-print class. Particularly relevant for navigation components.

DEPRECATION WARNING: `with_slot` is deprecated and will be removed in ViewComponent v3.0.0.
Use the new slots API (https://viewcomponent.org/guide/slots.html) instead.

https://github.com/github/view_component/releases/tag/v2.31.0

See: https://design-system.service.gov.uk/components/breadcrumbs/#collapsing-breadcrumbs-on-mobile-devices

In the design system
Nunjucks implementation

The inset text component can only accept a value for text. This is fine for one line of text, but requires significant work arounds when multiple lines and other elements need to be shown within this component. For example, on Apply we have the following:

<div class="govuk-inset-text">
  <% if no_viable_references? %>
    <p class="govuk-body">You need 2 references before you can submit your application.</p>
    <%= govuk_button_link_to 'Add a referee', candidate_interface_references_start_path %>
  <% elsif one_viable_reference? %>
    <p class="govuk-body">You need 2 references before you can submit your application.</p>
    <%= govuk_button_link_to 'Add a second referee', candidate_interface_references_start_path %>
  <% else %>
    <p class="govuk-body">You can add more referees to increase the chances of getting 2 references quickly.</p>
    <p class="govuk-body">We’ll cancel any remaining requests when you’ve received 2 references.</p>
    <%= govuk_button_link_to 'Add another referee', candidate_interface_references_start_path, class: 'govuk-button--secondary' %>
  <% end %>
</div>

It’d be nice if the inset text component could accept either block content or use a slot.

This evening I installed this gem and noticed that as part of the installation it added slim-rails gem to my Gemfile.lock

I had a look at the components markup files and none of them use slim so shouldn't this line be a dev dependency rather than an actual dependency.

Background

We need components to have a consistent API otherwise it will make it difficult to implement without looking at documentation. It will also make it confusing to know which method to use for each component.

Eg.

• Backlink uses a named parameter called classes and allows you to pass in a string. It does use Rails built in link_to method . https://github.com/DFE-Digital/govuk-components/blob/master/app/components/govuk_component/back_link.rb#L7-L10
• warning component uses an array of of classes. https://github.com/DFE-Digital/govuk-components/blob/master/app/components/govuk_component/warning.html.erb#L1

Proposal

I feel that we should support a string of class names as default as most frameworks support this. In addition if its really necessary then we should also support an array of class names and let the component convert the array to a string. BTH, when I see classes as an array I automatically start wondering if theres a priority in which the classes need to be in or whether the order of it matters (which it shouldn't). This is another reason why I think string of class names is easer to use because these thoughts or concerns are not brought about because of it being an array, it is just a string after all when its rendered.

🤔 Should we have a helper method which accepts string/array of classes and converts it into a string of class names for components to reuse? This could be used in other components which don't currently support custom css class names.

Any other thoughts or suggestions from others on the subject?

Currently (as of #1) the two example components are separated by directory

app/components
├── panel
│   ├── panel_component.html.erb
│   └── panel_component.rb
└── start_now_button
    ├── start_now_button_component.html.erb
    └── start_now_button_component.rb

And invoked like this:

StartNowButton::StartNowButtonComponent.new(text: text, href: href)

This is ugly and repetitive. It would be nicer if they were namespaced under GOVUK and in a flatter structure:

GOVUK::StartNowButtonComponent.new(text: text, href: href)

Questions

• Do we need to name them all <thing>Component? Is the common suffix just adding noise?
• Are people ok with not separating components by directory? We'll probably have quite a few components and having them - the ruby files and templates - all in a single directory might get a bit unwieldy

The equivalent Nunjucks macro for this component allows for a greater deal of customisation, given that it accepts all the arguments for tag that are available to the tag component. It would be great if this component behaved in a similar way.

On Apply, we change the colour of the tag based on the environment (production, staging, QA, etc.). However, it’s not possible to achieve the same with the phase banner component as it currently stands in this gem.

https://github.com/DFE-Digital/govuk-components/blob/master/app/components/govuk_component/notification_banner.html.erb?rgh-link-date=2021-01-07T09%3A12%3A03Z#L13

%>.

In v2.0, the role param is now available. However, its value should default to alert if success is set to true.

From the GDS Nunjucks component docs for its role param:

Overrides the value of the role attribute for the notification banner. Defaults to region. If you set type to success, role defaults to alert.

The README says to install the gem, the developer needs to add it to their Gemfile using gem 'govuk-components'.

Yes, it is possible to install it from Github but if you using an ruby:2.6.x-alpine docker image git it is not installed by default so the build fails when it tries to install the gems.

Following on from #165, in v2.0.0 you can now do this:

<% summary_list.row(
  key: "Foo",
  value: foo,
  action: {
    visually_hidden_text: "the foobar",
    href: "#"
  }
) %>

However, sometimes you don’t want to show a change link if a given test doesn’t pass:

<% summary_list.row(
  key: "Foo",
  value: foo,
  action: foo.present? : {
    visually_hidden_text: "the foobar",
    href: "#"
  } : nil
) %>

However, using nil gives the following error: Could not find a template file or inline render method for GovukComponent::SummaryListComponent::Row.

That seems odd. Instead, I have to pass in {}, like so:

<% summary_list.row(
  key: "Foo",
  value: foo,
  action: foo.present? : {
    visually_hidden_text: "the foobar",
    href: "#"
  } : {}
) %>

There is no way of using this library to generate GOV.UK button style links.

Apply have a good implementation that can be used as a starting point. It might make more sense to add a button param to govuk_link_to that adds the govuk-button class.

https://dfe-digital.github.io/govuk-components/ doesn’t feature a preview or documentation for the recently added cookie banner component.

Currently, v2.0.0 outputs the following for a cookie banner heading:

<h2 class="govuk-cookie-banner__heading">Cookies on [name of service]</h2>

Weirdly, the design system uses govuk-cookie-banner__heading in combination with the govuk-heading-m class:

<h2 class="govuk-cookie-banner__heading govuk-heading-m">Cookies on [name of service]</h2>

The component should follow the same pattern.

I’m looking to use the new notification component, and show a success message after a user has successful completed a task. The design system, says this:

Since you’re using the notification banner to tell the user about the outcome of something they’ve just done, add role="alert" so focus shifts to the notification banner on page load.

However, as far as I can tell, this value is hard coded to region: https://github.com/DFE-Digital/govuk-components/blob/e963f4749572f6ae8668adcc64b3db24e6f92f50/app/components/govuk_component/notification_banner.html.erb#L1

Have I understood this correctly? Does this advice also not conflict somewhat with the disable_auto_focus option? (I’m not sure if role="alert" should always mean attracting focus on page load, but this seems reasonable).

Rather than have a separate product_description param, might it be possible to just provide product_name as either a string or via a slot or block?

product_description was only added to serve a narrow use case, chiefly that of allowing other content to be shown next to a product name such as a tag. product_description gives the impression this is something supported by the header design, which it is not.

The notification banner could include a variety of content. The API for this component should be as flexible as the design system's.

The following is not currently possible:

You are impersonating <a href="/">Paul Hayes</a> ([email protected])

[Stop impersonating]

Suggestion:

• Add an html param, to pass in and render any provided html

Like:

{{ govukNotificationBanner({
  html: html
}) }}

https://design-system.service.gov.uk/components/notification-banner/

This is affecting this PR: DFE-Digital/get-help-with-tech#1410

The new version of the Design System includes a cookie banner, we should implement it.

I was just going through the view component docs and came across this - which is pretty cool!

I wondered if we might want to add a section to our docs/readme to list the different teams using this gem?

I've noticed that when supplying custom classes to these helpers, the govuk-link class is no longer applied (i.e overwritten rather than merged).

Adding this issue so
a) I don't forget about it
b) Someone else can investigate/fix if they feel inclined to do so

It’s currently not possible to pass in anything into a navigation item other than a link. With the following params:

<% component.slot(:item, title: 'Navigation item') %>

the following HTML is returned:

<li class="govuk-header__navigation-item">
  <a class="govuk-header__link" href>Navigation item</a>
</li>

A link with an empty href is not the desired – or possibly expected – outcome. What’s needed is a means of providing text only content (which is unlinked without the presence of href). For example:

<% component.slot(:item, title: 'I like apples') %>

would generate the following markup:

<li class="govuk-header__navigation-item">
  I like apples
</li>

Additionally, it would be good if block content could be provided. For example:

<%= component.slot(:item) do %>
  I <em>really</em> like apples
<% end %>

the following markup would be generated:

<li class="govuk-header__navigation-item">
  I <em>really</em> like apples
</li>

For reference, the GDS Nunjucks macro provides the following options for navigation items:

Sidenote: The title value ought to be called text. This would not only align it with the GDS Nunjucks macros, but also other components in this gem (where a text param can be overwritten by block content).

Design system
Nunjucks implementation

The notification banner component was added to the design system after the scope of this gem was originally agreed. Is it a reasonable candidate for inclusion?

This is a valid invocation of link_to:

<%= link_to 'abc', param1: 'a', param2: 'b' %>

which generates:

<a href="/?param1=a&param2=b">abc</a>

However, calling

<%= govuk_link_to 'abc', param1: 'a', param2: 'b' %>

unexpectedly generates

<a href="/?class=govuk-link&param1=a&param2=b">abc</a>

instead of

<a class="govuk-class" href="/?param1=a&param2=b">abc</a>

(arose in DFE-Digital/get-help-with-tech#611)

All the BAT services deviate from the standard component in a few subtle ways:

• We don’t show the OGL/Crown copyright line
• We show a title for the meta section (the design system component only allows you to update meta.visuallyHiddenTitle which allows authors to update the hidden ‘Support links’ text)
• Moves the meta.html/meta.text block above the array of navigation meta.items.

Given these deviations from the component as currently configured in the design system, maybe this is beyond the scope of this gem?

Chatting to @peteryates on Slack, he said:

Perhaps the best route would be to add slots for the various bits and allow teams to inject their own content - the only reason I'm usually inclined to provide the functionality and have params passed in is that you end up with bits of arbitrary HTML in blocks that, when the footer component is updated in the future, need to be manually addressed in several places.

The GDS Nunjucks component takes an array of items for a row’s action links, something this gem currently doesn’t allow.

Now this is really pernickety, but… what’s called the ‘Start now button’ component in this gem, is commonly referred to as the ‘Start button’. See: https://design-system.service.gov.uk/components/button/#start-buttons (Also, the class is govuk-button--start).

Suppose it’s too late to rename this component… or at least until there’s a breaking change?

If you add items to the header, the following markup should be added after .govuk-header__link and prior to the nav element:

<button type="button" class="govuk-header__menu-button govuk-js-header-toggle" aria-controls="navigation" aria-label="Show or hide navigation menu">Menu</button>

This allows the navigation to be revealed in the mobile breakpoint.

Furthermore, as there’s no way to insert content within the header, this button markup can’t be added manually.

See: https://design-system.service.gov.uk/components/header/#header-with-service-name-and-navigation

@misaka has kindly pointed out that the attempt to make the library more DSL-like has created a clash of method names. ViewComponent defines an accessor that shares a name with the inner object.

I think the fix that will cause the least confusion could be to prefix the generated (wrapped) method with add_, so calling would look something like:

govuk_accordion(id: 'def234') do |accordion|
  accordion.add_section(title: 'Section 1') do
    tag.p(class: 'govuk-body') do
      "Lorem ipsum dolor sit amet, consectetur adipiscing elit."
    end
  end
end

This aligns with the param used in the Design system Nunjucks template.

Typically, the ‘Change’ link in a summary list is composed of 2 parts: the visible link (usually labelled ‘Change’), and a visually hidden part, which helps tell change links apart when a screen reader announces them.

Currently, the action param for a row in GovukComponent::SummaryList is pretty dumb; it’ll take anything. However, given this link pattern is so intrinsic to this component, it’d be much more helpful if this component enabled setting these values.

How about, in addition to taking any value as it does currently:

<%= component.slot(
    :row,
    key: 'Name',
    value: 'Aardvark',
    action: link_to('Change', '#aardvark')
) %>

you can supply an object with the following values instead:

<%= component.slot(
    :row,
    key: 'Name',
    value: 'Aardvark',
    action: {
        href: "#aardvark",             # Required
        text: "Change",                # Required, defaults to ‘Change’ if not provided 
        visually_hidden_text: "name",  # Required, but maybe defaults to lowercased `key` value? 
        classes: "",                   # Optional
        html_attributes: {},           # Optional
    }
) %>

Something like that.

Adding the class govuk-link--no-visited-state to links ensures the colour do not change to purple if the linked destination has been visited. This is useful in places like navigation, or other areas where recording the visited state is not useful.

In using govuk_link_to helper, I’ve noticed that this is typically the only class I need to add manually, which can be quite verbose:

<%= govuk_link_to('give feedback or report a problem', @feedback_link, class: 'govuk-link--no-visited-state') %>

Hading a new param for this class would make such links less verbose, and more clearly expose this option (for which I always forget the correct class name):

<%= govuk_link_to('give feedback or report a problem', @feedback_link, no_visited_state: true) %>

Feature request for v2. Just seen that the param for the details component has been renamed to summary_text, to match that of the GDS Design system nunjucks template, summaryText. This is perfect, but it has reminded me…

A number of params in the design system templates are sort of paired, and the details element is a good example. For this component, you can supply both the summary and disclosed text values with plain text strings:

{{ govukDetails({
  summaryText: "See some details",
  text: "Is this what you expected?"
}) }}

However, you can also provide HTML to both of these values:

{{ govukDetails({
  summaryHtml: "See some <strong>important<strong> details",
  html: "<p class="\govuk-body\">Getta load of <em>these</em> details!</p>"
}) }}

For all the places these param pairs exist in the Nunjucks templates, this gem should behave similarly, either excepting a string or a block. (Currently the details component accepts block content only for the disclosed text, but not the summary text).

When govuk_link_to is called with url_options hash (https://apidock.com/rails/ActionView/Helpers/UrlHelper/link_to) it appends class to url_options instead of html_options, resulting in link without govuk-link class and with href with appended ?class=govuk-link.

    <%= govuk_link_to "show", action: :show %>  #=> <a href="{correct_url}?class=govuk-link">

This can be avoided by adding button: false and parenthesising url_options:

    <%= govuk_link_to "show", { action: :show }, button: false %>  #=> <a class="govuk-link" href="{correct_url}">

Parenthesising alone does not fix the issue - url_options are then still treated as kwargs rather than part of *args (which I find a bit odd - this might depend on ruby version though)

Design system
Nunjucks implementation

The header component can take a product name - the regular weight text which can appear right after the GOV.UK logo. We use this variant on Apply. See: https://github.com/DFE-Digital/apply-for-teacher-training/blob/master/app/components/product_header_component.html.erb

(Additionally, we also include a tag after the product name. This option is not available in the design systems Nunjucks templates, but sure would be nice to have a means of injecting custom content into product name area should this be desired)

This is a central progress/tracking issue for components based on @tijmenb's list (#3)

Components

• Accordion (too complex, maybe out of scope) #45
• Back link #13
• Breadcrumbs #12
• Details #25
• Footer #35
• Header #17
• Inset text #9
• Panel 8ca5451
• Phase banner #8
• Start now button #1
• Summary list #48
• Table (too complex, maybe out of scope)
• Tabs (maybe too complex initially, probably relies on the enhanced content block functionality of View Component) #42
• Tag #4
• Warning text #28

Helpers

• #govuk_link_to #15
• #govuk_mail_to #36
• #govuk_button_to (thinking this should map to Rails' button_to but maybe there's also need for a link styled as a button #36
• #govuk_back_to_top_link #19
• Skip link #20

Other useful stuff

Perhaps this shouldn't be in here, but it's something that's probably useful to every project. Maybe it's better suited to the DfE Rails Boilerplate

• A GOV.UK date format that can be used by Rails' date helpers, eg object.submitted_on.to_formatted_s(:govuk), see example. A PR with this functionality has been submitted to the boilerplate