katalyst-govuk-formbuilder 1.30.1 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9117d661c2225e77188c2cd1b95df29bcdf27a0d507981bceca33477896f5a53
-  data.tar.gz: 42e6309f7ea989a7a52f159bc2ec78466de4354378c3c10d61aba02198699de6
+  metadata.gz: bfaf577c810adcbb0beccb5c19593d351212fa47ac656eab727fddac588dbaa2
+  data.tar.gz: 498dc851c834e026add583e93c411496007d4bfc3905957686b9a02b854fcb51
 SHA512:
-  metadata.gz: 26683a6307957c466fc712d11b6ec430424e64f5dcf24e1730a9b487c36e8ae5c2236a7c171c734c72bdb812cc40d6ac34562018b143f9b4e3c57776e16dfca4
-  data.tar.gz: 9c88e639a61aee9fa049d399296e59fcc9da810ed0f7f5d718c9dbe2751a68144b0a1848b404701e2ff212786451f25e852e61a42672dfb2f8ffbf132cca1a6f
+  metadata.gz: a0534e3ca97f200c06440c6c2d5e698f8f3912ad3b804fbaac7627d0f2c46eea005191033289b7be1358f98e87763d171202e8af6d986a03614e05abd9510a4b
+  data.tar.gz: db9d235514210ce9a33f31abc660642837a1de680c84e32a968ac118705495b8de8383ebad0a82832da0a3da646e227bcd03c6402021deda7ecc421ec4db40c4

data/README.md

@@ -1,7 +1,9 @@
 # Katalyst::GOVUK::FormBuilder
 
 Repacking of [GOV.UK Frontend](https://frontend.design-system.service.gov.uk) and
-[GOV.UK form components](https://govuk-form-builder.netlify.app) for use in Katalyst projects.
+[GOV.UK form components](https://govuk-form-builder.netlify.app) for use in Katalyst projects,
+extended with ActiveStorage-backed attachment fields: previews, drag-and-drop, async direct
+uploads, and a complete no-JavaScript fallback.
 
 ## Installation
 
@@ -21,6 +23,14 @@ Or install it yourself as:
 
 ## Usage
 
+Use the GOV.UK form builder for your forms, most simply as the application default:
+
+```ruby
+class ApplicationController < ActionController::Base
+  default_form_builder GOVUKDesignSystemFormBuilder::FormBuilder
+end
+```
+
 Add the stylesheet to your default layout:
 
 ```erb
@@ -33,38 +43,154 @@ You can also add it to your SASS build:
 @use "katalyst/govuk/formbuilder";
 ```
 
-Some GOVUK components require javascript enhancements 
-(see [GOVUK docs](https://frontend.design-system.service.gov.uk/get-started/#5-get-the-javascript-working)).
+### JavaScript
+
+The attachment and file upload fields are Stimulus-powered. Load the gem's
+controllers into your Stimulus application:
+
+```js
+import { Application } from "@hotwired/stimulus";
+
+const application = Application.start();
+
+import GOVUK from "@katalyst/govuk-formbuilder";
+GOVUK.start(application);
+```
 
-You can use the provided helper to load the formbuilder esm from importmaps and enhance your form:
+If you want to keep GOVUK enhancements separate from your main app's Stimulus
+application, you can inject the bootstrap JS module into your body instead:
 
 ```erb
-<%= form_with ... %>
 <%= govuk_formbuilder_init %>
 ```
 
-You'll need to include the helper to make this method available, which you can add to your `ApplicationController`:
+You'll need to include the helper to make this method available, which you can add
+to your `ApplicationController`:
 
 ```ruby
 helper Katalyst::GOVUK::FormBuilder::Frontend
 ```
 
-## Extensions
+The snippet marks the page as JavaScript-capable and calls the module's `initAll()`,
+but will not survive a new page render (including Turbo navigation). Use this
+approach if you are only using GOVUK sparingly.
 
-We include some optional extensions for integrating with gems that we (Katalyst) commonly use.
+#### JavaScript dependencies
 
-These require additional steps to use.
+The formbuilder module imports `@hotwired/stimulus` and `@rails/activestorage`. With
+importmaps the gem pins itself and `@rails/activestorage` for you. It does not pin
+`@hotwired/stimulus` — your app provides that (`stimulus-rails` does this in a
+standard Rails app). If you use jsbundling or similar, you'll need both packages
+available at runtime; the wiring is the same `GOVUK.start(application)` shown above,
+from your own bundle.
 
-### File inputs
+## Attachment fields
 
-We've added image and document fields designed for use with Koi. These will not be suitable for
-every project. If you want to use these, you'll need to import and load their stimulus controllers:
+`govuk_image_field` and `govuk_document_field` render an upload field for
+`has_one_attached` / `has_many_attached` attributes. With JavaScript, files upload
+asynchronously as soon as they are chosen or dropped, each showing a preview figure
+with progress, retry on failure, and a remove control. Without JavaScript the same
+field is a plain file input plus a keep/remove select per attached file — no
+functionality is lost, only polish.
 
-```js
-import govuk from "@katalyst/govuk-formbuilder";
-application.load(govuk);
+```erb
+<%= f.govuk_image_field :avatar %>
+<%= f.govuk_document_field :cv %>
+<%= f.govuk_attachment_field :recording, accept: "audio/*" %>
 ```
 
+Both fields delegate to `govuk_attachment_field`; they differ only in the mime types
+they accept (`config.image_mime_types` / `config.document_mime_types`).
+
+- The attribute's value must be an `ActiveStorage::Attached`; anything else raises
+  `ArgumentError` at render. For plain multipart uploads without ActiveStorage, use
+  the upstream `govuk_file_field`.
+- `multiple` is inferred from the association (`has_many_attached` → multiple), and
+  an explicit `multiple:` argument is respected.
+- Attachments round-trip as blob signed ids: when validation fails, the re-rendered
+  form retains every attachment — stored, direct-uploaded, or pending multipart — so
+  a failed submit never loses an upload.
+- Removal is always offered. A required attachment should say so with a presence
+  validation; the form does not hide removal on its behalf.
+- Direct uploads post to `rails_direct_uploads_url` by default. Pass
+  `direct_upload_url:` to use a different endpoint, or `direct_upload: false` to
+  leave chosen files in the input and submit them as ordinary multipart.
+- Fields accept the standard GOV.UK options (`label:`, `hint:`, `caption:`,
+  `form_group:`, `before_input:`, `after_input:`) and a block for supplemental
+  content rendered inside the form group.
+
+Preview thumbnails are generated lazily through ActiveStorage's representation
+route. The transformation is configurable:
+
+```ruby
+GOVUKDesignSystemFormBuilder.config.attachment_preview_representation =
+  { resize_to_fill: [256, 256] } # the default
+```
+
+### Strings and internationalisation
+
+All user-facing strings resolve through Rails i18n under `katalyst.govuk.attachment.*`
+(`upload_succeeded`, `upload_failed`, `retry_button`, `file_removed`, `remove_button`,
+`remove_button_content`), alongside govuk-frontend's FileUpload strings. Each has a
+per-field text option (`upload_succeeded_text`, `upload_failed_text`,
+`retry_button_text`, `file_removed_text`, `remove_button_text`,
+`remove_button_content_text`, `choose_files_button_text`, `drop_instruction_text`,
+`no_file_chosen_text`, `multiple_files_chosen_text`, `entered_drop_zone_text`,
+`left_drop_zone_text`). Strings reach the JavaScript enhancement via the field's
+`data-i18n.*` attributes, with the locale taken from the closest `lang` attribute.
+
+## Upgrading from 1.x
+
+This major version replaces the image/document field implementations with the
+attachment field described above.
+
+- `govuk_image_field` / `govuk_document_field` now require an
+  `ActiveStorage::Attached` value and raise `ArgumentError` otherwise. The legacy
+  fields rendered a plain enhanced input for other values (e.g. form objects) — for
+  those, use `govuk_file_field`.
+- The `optional:` argument no longer does anything: removal is always offered, and
+  submitting the remove option detaches on save. A required attachment must be
+  guarded by a presence validation.
+- Dropped files are no longer filtered by mime type on the client. The `accept`
+  attribute remains a file-picker courtesy; your model's validations are the
+  authority on content.
+- `application.load(govuk)` no longer works — the default export is no longer the
+  controller definitions array, and Stimulus raises a `TypeError` at boot. Replace it
+  with `GOVUK.start(application)` (see JavaScript above), which registers the
+  controllers and keeps enhancement running across Turbo visits.
+- Remove any `turbo:render` / `turbo:frame-load` re-initialisation wiring —
+  enhancement now observes the DOM and owns re-enhancement; repeated calls are
+  harmless no-ops.
+- Text options on file fields are now honoured by the JavaScript. Previously they
+  rendered but were never read, so non-English sites got English announcements.
+- Brand (`GOVUKDesignSystemFormBuilder.brand`) now affects CSS classes only:
+  Stimulus identifiers, `data-controller`/`data-action` wiring, and events are
+  always `govuk-*`. The gem's compiled CSS remains govuk-prefixed — a non-default
+  brand presumes a consumer-supplied frontend build.
+
+As a transitional escape hatch, the legacy implementations remain available behind a
+flag:
+
+```ruby
+GOVUKDesignSystemFormBuilder.config.use_legacy_file_fields = true # default false
+```
+
+The flag flips `govuk_image_field` / `govuk_document_field` back to the legacy
+elements. It exists to stage a migration, not to stay on: the flag and the legacy
+code will be removed together in a subsequent release.
+
+## Extensions
+
+We include some optional extensions for integrating with gems that we (Katalyst)
+commonly use. These require additional steps to use.
+
+### Rich text area
+
+`govuk_rich_textarea` renders a Trix editor with GOV.UK form conventions. It
+requires ActionText to be set up in your application (`rails action_text:install`),
+including its JavaScript (`trix` and `@rails/actiontext`) in your bundle or
+importmap.
+
 ### Hotwire Combobox
 
 [Hotwire Combobox](https://hotwirecombobox.com) is a promising option for adding asynchronous multi-select inputs to

data/app/assets/builds/katalyst/govuk/formbuilder.css

@@ -995,6 +995,83 @@
   }
 }
 
+:where(.govuk-attachment) {
+  display: grid;
+  grid-template-areas: "preview caption actions";
+  grid-template-columns: auto 1fr auto;
+  margin: 0;
+  padding: 15px 15px;
+  grid-gap: 10px;
+  background-color: #f3f3f3;
+  border: 2px solid var(--govuk-border-colour, #cecece);
+}
+:where(.govuk-attachment) .preview {
+  grid-area: preview;
+  max-width: 4rem;
+  aspect-ratio: 1/1;
+  object-fit: cover;
+}
+:where(.govuk-attachment) .caption {
+  display: flex;
+  flex-direction: column;
+  grid-area: caption;
+  font-family: "Open Sans", sans-serif;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+@media print {
+  :where(.govuk-attachment) .caption {
+    font-family: sans-serif;
+  }
+}
+:where(.govuk-attachment) .caption {
+  font-weight: 400;
+  font-size: 1rem;
+  line-height: 1.25;
+}
+@media print {
+  :where(.govuk-attachment) .caption {
+    font-size: 14pt;
+    line-height: 1.25;
+  }
+}
+:where(.govuk-attachment) .filename {
+  font-weight: 700;
+}
+:where(.govuk-attachment) .size {
+  color: var(--govuk-secondary-text-colour, #484949);
+}
+:where(.govuk-attachment) .actions {
+  grid-area: actions;
+}
+:where(.govuk-attachment) .actions button {
+  display: none;
+}
+:where(.govuk-attachment)[data-state=upload-successful] .status {
+  color: var(--govuk-success-colour, #0f7a52);
+}
+:where(.govuk-attachment)[data-state=upload-failed] {
+  border-color: var(--govuk-error-colour, #ca3535);
+}
+:where(.govuk-attachment)[data-state=upload-failed] .status {
+  color: var(--govuk-error-colour, #ca3535);
+}
+
+.govuk-attachment {
+  margin-bottom: 10px;
+}
+
+.govuk-frontend-supported :where(.govuk-attachment) .actions select {
+  display: none;
+}
+.govuk-frontend-supported :where(.govuk-attachment) .actions button {
+  display: revert;
+}
+
+.govuk-file-upload-wrapper:has(input[type=file]:not([multiple])) .govuk-attachment:has(+ .govuk-attachment) {
+  display: none;
+}
+
 .govuk-error-message {
   font-family: "Open Sans", sans-serif;
   -webkit-font-smoothing: antialiased;